:py:mod:`pyloggrid.Libs.datasci`
================================

.. py:module:: pyloggrid.Libs.datasci

.. autoapi-nested-parse::

   Libraries for data science



Module Contents
---------------


Functions
~~~~~~~~~

.. autoapisummary::

   pyloggrid.Libs.datasci.filter_range
   pyloggrid.Libs.datasci.mean
   pyloggrid.Libs.datasci.clamp_zero
   pyloggrid.Libs.datasci.fit
   pyloggrid.Libs.datasci.powerlaw_fit
   pyloggrid.Libs.datasci.randcomplex_like
   pyloggrid.Libs.datasci.randcomplex
   pyloggrid.Libs.datasci.rand_seeded_by_array
   pyloggrid.Libs.datasci.randcomplex_seeded_by_array
   pyloggrid.Libs.datasci.ragged_array_to_array
   pyloggrid.Libs.datasci.logmean



.. py:function:: filter_range(data: numpy.ndarray, start: float = 0, end: float = 1) -> numpy.ndarray

   Trims a 1D array from its first and last portions.

   This is a shortcut to ``data[int(size * start) : int(size * end)]``

   :param data: the data to filter
   :param start: where to start in the values (ex: 0.2 -> we ommit the 20% first values)
   :param end: where to end in the values (ex: 0.8 -> we ommit the 20% last values)

   :returns: the new array *(if filtered, the shape is altered)*


.. py:function:: mean(data: numpy.ndarray, ts: Optional[numpy.ndarray] = None, log: bool = False, start: float = 0, end: float = 1) -> tuple[numpy.ndarray, numpy.ndarray | None]

   Mean of ``data``. If ``ts`` is provided, the mean is weighted by the time intervals. If ``log``, the log mean is returned.

   :param data: data to average
   :param ts: times associated with the data. Must be increasing.
   :param log: if True, only the mean avg is returned ``exp(mean(log(abs(data_weighted)))``, and the variance returns ``None``
   :param start: where to start in the values (ex: 0.2 -> we ommit the 20% first values)
   :param end: where to end in the values (ex: 0.2 -> we ommit the 20% last values)

   :returns: the mean and std value


.. py:function:: clamp_zero(data: numpy.ndarray, fill: Any = None) -> numpy.ndarray

   Replace all zero values with ``fill`` (defaults to ``min(data)/10``)

   :param data: array to clamp
   :param fill: if specified, all zero values are filled with this

   :returns: The clamped array


.. py:function:: fit(f: Callable, x: numpy.ndarray, y: numpy.ndarray, mask: numpy.ndarray | tuple[float, float] = None) -> tuple[float, Ellipsis]

   Fit ``(x,y)`` by the function ``f`` with an optional mask

   :param f: fit function
   :param x:
   :param y:
   :param mask: an array mask, or a tuple (start, end)


.. py:function:: powerlaw_fit(x: numpy.ndarray, y: numpy.ndarray, mask: numpy.ndarray | float = None, a: float = None) -> tuple[float, float]

   Power law fit ``Y = b * X ^ a``

   :param x: X array
   :param y: Y array
   :param mask: mask to specify the relevant values of X, Y to use (same as :func:`fit`)
   :param a: optional fixed value for ``a``. If specified, only ``b`` is fitted

   :returns: the fit parameters ``b, a``


.. py:function:: randcomplex_like(data: numpy.ndarray) -> numpy.ndarray

   Random array of complex numbers, see :func:`randcomplex`

   :param data: array to copy the shape from

   :returns: random array


.. py:function:: randcomplex(shape: Iterable) -> numpy.ndarray

   Random array of complex numbers, normally distributed in modulus and uniformly in angle

   :param shape: return array shape

   :returns: random array


.. py:function:: rand_seeded_by_array(source: numpy.ndarray, seed: int) -> numpy.ndarray

   Returns a pseudorandom array of same shape as ``source`` where items with the same ``source`` will have the same value for a given seed.

   This is useful when creating pseudorandom arrays based on ``kx,ky,kz``, of different sizes, e.g. when changing the grid size but keeping the same pseudorandom forcing

   .. warning:: This is not optimised for speed, and should probably not be called every step


.. py:function:: randcomplex_seeded_by_array(source: numpy.ndarray, seed: int) -> numpy.ndarray

   Like :func:`rand_seeded_by_array`, but returns a complex array (uniform in a square)


.. py:function:: ragged_array_to_array(data: numpy.ndarray | list, fill=np.nan) -> numpy.ndarray

   Transform an 1D array of 1D array of different sizes into an array of array of same sizes, i.e a classic 2D array.

   Smaller arrays are padded with ``fill``.

   If a classic 2D array is given, it does nothing.

   :param data: array of array of different sizes
   :param fill: fill value

   :returns: padded 2D-array


.. py:function:: logmean(data: numpy.ndarray, axis=None) -> numpy.ndarray

   Logarithmic mean along an axis, ignoring zero and nan values.