========================
Spline (hwx.common.math)
========================

A two element list of (x, y) values.

Spline has methods to convert to/from units, add/insert/delete rows, interpolate,
get the derivative and read/write CSV files.

The length of x should be the same as y and at least 4. Also, x should be
increasing i.e. x[i] < x[i+1].

----------
Properties
----------

  +----+----+
  | x_ | y_ |
  +----+----+

--------------
Public Methods
--------------

  +-------------------------------------------------------------------+
  | addInterpolated_ (self, row)                                      |
  +-------------------------------------------------------------------+
  | appendInterpolated_ (self)                                        |
  +-------------------------------------------------------------------+
  | copy_ (self, **kwds)                                              |
  +-------------------------------------------------------------------+
  | deleteRows_ (self, *deleteRows)                                   |
  +-------------------------------------------------------------------+
  | derivative_ (self, order=1, npts=None, type='akima', scaled=True) |
  +-------------------------------------------------------------------+
  | fromBaseUnits_ (self)                                             |
  +-------------------------------------------------------------------+
  | getFormattedStrings_ (self, format=5)                             |
  +-------------------------------------------------------------------+
  | getXFromY_ (self, y)                                              |
  +-------------------------------------------------------------------+
  | insertInterpolated_ (self, row)                                   |
  +-------------------------------------------------------------------+
  | interpolate_ (self, npts=None, type='akima', order=0, x=None)     |
  +-------------------------------------------------------------------+
  | isValid_ (self)                                                   |
  +-------------------------------------------------------------------+
  | prependInterpolated_ (self)                                       |
  +-------------------------------------------------------------------+
  | readCsv_ (self, fname, validationMethod=None)                     |
  +-------------------------------------------------------------------+
  | reflect_ (self)                                                   |
  +-------------------------------------------------------------------+
  | removeNegativeX_ (self)                                           |
  +-------------------------------------------------------------------+
  | scalex_ (self, factor)                                            |
  +-------------------------------------------------------------------+
  | scaley_ (self, factor)                                            |
  +-------------------------------------------------------------------+
  | setComponent_ (self, row, col, value)                             |
  +-------------------------------------------------------------------+
  | setValues_ (self, x, y=None)                                      |
  +-------------------------------------------------------------------+
  | shiftx_ (self, offset)                                            |
  +-------------------------------------------------------------------+
  | shifty_ (self, offset)                                            |
  +-------------------------------------------------------------------+
  | toBaseUnits_ (self)                                               |
  +-------------------------------------------------------------------+
  | writeCsv_ (self, fname=None)                                      |
  +-------------------------------------------------------------------+

----------------
Property Details
----------------

.. _x:
.. method:: x

The x values.

.. _y:
.. method:: y

The y values.

--------------
Method Details
--------------

.. _addInterpolated:
.. method:: addInterpolated(self, row)

Adds a linear interpolated value after the specified row.

:param row: The row where to add the value after.
:type row: int

:returns: A reference to the instance Spline object on which it was called.
:rtype: Spline


.. _appendInterpolated:
.. method:: appendInterpolated(self)

Appends a linear interpolated value.

:returns: A reference to the instance Spline object on which it was called.
:rtype: Spline


.. _copy:
.. method:: copy(self, **kwds)

Return a copy of self.

It is updated with kwds if specified to support derived classes.

.. _deleteRows:
.. method:: deleteRows(self, *deleteRows)

Removes the specified rows.

:returns: A reference to the instance Spline object on which it was called.
:rtype: Spline


.. _derivative:
.. method:: derivative(self, order=1, npts=None, type='akima', scaled=True)

Computes the derivative.

Scale the derivative so it is not too big but can still be viewed.

:param order: Order of the derivative.
:type order: int
:param npts: Number of points to interpolate.
:type npts: int
:param type: Type of Interpolation.
:type type: str
:param scaled: The factor to scale y values.
:type scaled: Union[bool, float]

:returns: A reference to the instance Spline object on which it was called.
:rtype: Spline


.. _fromBaseUnits:
.. method:: fromBaseUnits(self)

Makes the Spline values work like other Double values.


.. _getFormattedStrings:
.. method:: getFormattedStrings(self, format=5)

Returns the values suitable for display in the gui fields or table cells.

:param format: The format of the values as strings.
:type format: Union[int, str]

:returns: The x, y values.
:rtype: list[list[float], list[float]]


.. _getXFromY:
.. method:: getXFromY(self, y)

Returns a computed x value from the specified y value.

This uses linear interpolation since we can not assume the y values are
monotonically increasing.

:param y: The y value.
:type y: float

:returns: The x value.
:rtype: float


.. _insertInterpolated:
.. method:: insertInterpolated(self, row)

Adds a linear interpolated value before the specified row.

:param row: The row where to add the value before.
:type row: int

:returns: A reference to the instance Spline object on which it was called.
:rtype: Spline


.. _interpolate:
.. method:: interpolate(self, npts=None, type='akima', order=0, x=None)

Recalculates x and y by interpolation.

This is used to get equally spaced values of x, kind can be "akima" or any
scipy.interpolate.inter1d.

If x is specified, returns the computed y value.

:param npts: Number of samples to generate, if x is None.
:type npts: int
:param type: The type of interpolation.
          Possible choices are "akima", "linear", "cubic", "zero", "natural".
          If none of these is given then "splev" is used.
:type type: str
:param order: The order of interpolation.
:type order: int
:param x: The x value used to return the interpolated y.
:type x: float

:returns: A reference to the instance Spline object on which it was called.
:rtype: Spline


.. _isValid:
.. method:: isValid(self)

Determines if self can be interpolated and if the derivative can be computed.

:returns: True if it is valid, False otherwise.
:rtype: bool


.. _prependInterpolated:
.. method:: prependInterpolated(self)

Adds a linear interpolated value in the beginning.

:returns: A reference to the instance Spline object on which it was called.
:rtype: Spline


.. _readCsv:
.. method:: readCsv(self, fname, validationMethod=None)

Reads a csv file to populate the x/y values.

:param fname: The path to the csv file.
:type fname: str
:param validationMethod: A function used to validate the csv reading.
:type validationMethod: func

:returns: A reference to the instance Spline object on which it was called.
:rtype: Spline


.. _reflect:
.. method:: reflect(self)

Reflects the data across X and Y.

.. _removeNegativeX:
.. method:: removeNegativeX(self)

Removes x, y pairs with negative x values.

.. _scalex:
.. method:: scalex(self, factor)

Mulitplies the x values by a scale factor.

:param factor: The factor to multiply the values with.
:type factor: float

:returns: A reference to the instance Spline object on which it was called.
:rtype: Spline


.. _scaley:
.. method:: scaley(self, factor)

Mulitplies the y values by a scale factor.

:param factor: The factor to multiply the values with.
:type factor: float

:returns: A reference to the instance Spline object on which it was called.
:rtype: Spline


.. _setComponent:
.. method:: setComponent(self, row, col, value)

Sets a single value.

:param row: The row value to set.
:type row: int
:param col: The column value to set.
:type col: int
:param value: The value to set.
:type value: float

:raises: :exc:`SplineValueError` -- If value is not numeric.

:returns: A reference to the instance Spline object on which it was called.
:rtype: Spline


.. _setValues:
.. method:: setValues(self, x, y=None)

Sets the list of x and y values.

:param x: The list of x values.
:type x: list
:param y: The list of y values.
:type y: list

:returns: A reference to the instance Spline object on which it was called.
:rtype: Spline


.. _shiftx:
.. method:: shiftx(self, offset)

Shifts the x values by an offset.

:param offset: The offset to shift the values with.
:type offset: float

:returns: A reference to the instance Spline object on which it was called.
:rtype: Spline


.. _shifty:
.. method:: shifty(self, offset)

Shifts the y values by an offset.

:param offset: The offset to shift the values with.
:type offset: float

:returns: A reference to the instance Spline object on which it was called.
:rtype: Spline


.. _toBaseUnits:
.. method:: toBaseUnits(self)

Makes the Spline values work like other Double values.


.. _writeCsv:
.. method:: writeCsv(self, fname=None)

Writes x/y values to a csv file.

:param fname: The path to the csv file.
:type fname: str