Function Plugins
================

What Function Plugins Do
------------------------

Function plugins transform one selected table column into another table column.
In the main window, the user selects:

- an input column,
- an output column,
- a function from the Functions dropdown,
- an optional multiplier and offset.

PhysPlot reads the input column as a one-dimensional numeric array, calls the
plugin's ``transform(values)`` function, then writes the returned values into
the output column.

Layman Example
--------------

If column 1 contains time and column 2 contains voltage, a function plugin can
create a new column containing ``voltage squared`` or ``baseline removed
voltage``. The plugin only needs to know how to transform one list of numbers.

Required File Location
----------------------

Put new function files in:

.. code-block:: text

   functions/

Use a clear filename, for example:

.. code-block:: text

   functions/15_normalize.py

Required Structure
------------------

Every function plugin should define:

``DISPLAY_NAME``
   Text shown in the PhysPlot Functions dropdown.

``DEFAULT_LABEL``
   Default label used by the app when a label is needed.

``transform(values)``
   Function that receives a one-dimensional numeric sequence and returns a
   sequence of the same length.

Minimal Template
----------------

.. code-block:: python

   """Normalize transform for PhysPlot."""

   import numpy as np

   DISPLAY_NAME = "Normalize"
   DEFAULT_LABEL = "Normalized"


   def transform(values):
       """transform(values) -> numpy.ndarray

       Normalize the selected table column between 0 and 1.

       Parameters:
           values (Sequence[float]): One-dimensional selected table column.

       Returns:
           numpy.ndarray: Normalized values with the same length as input.
       """
       values = np.asarray(values, dtype=float)
       minimum = np.nanmin(values)
       maximum = np.nanmax(values)
       if maximum == minimum:
           return np.zeros_like(values)
       return (values - minimum) / (maximum - minimum)

Practical Rules
---------------

- Return the same number of values that you received.
- Use ``numpy.asarray(values, dtype=float)`` if you need NumPy operations.
- Avoid changing files, opening windows, or modifying the table directly.
- Handle edge cases such as blank columns, zeros, or repeated values.

Existing Examples
-----------------

See:

- ``functions/01_identity.py``
- ``functions/05_log10.py``
- ``functions/14_xrd_baseline_remove.py``