skultrafast.utils
=================

.. py:module:: skultrafast.utils

.. autoapi-nested-parse::

   Module with various utility functions. Was called dv in older Versions.



Classes
-------

.. autoapisummary::

   skultrafast.utils.LinRegResult


Functions
---------

.. autoapisummary::

   skultrafast.utils.weighted_binning
   skultrafast.utils.simulate_binning
   skultrafast.utils.sigma_clip
   skultrafast.utils.gauss_step
   skultrafast.utils.pfid_r4
   skultrafast.utils.pfid_r6
   skultrafast.utils.pfid
   skultrafast.utils.linreg_std_errors
   skultrafast.utils.ExpDecay
   skultrafast.utils.TwoExpDecay
   skultrafast.utils.ThreeExpDecay
   skultrafast.utils.poly_bg_correction
   skultrafast.utils.inbetween


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

.. py:function:: weighted_binning(x, arr, bins, weights=None)

   Bins a 1D array to given bins using weights.


.. py:function:: simulate_binning(wrapped=None, *, fac=5)

   Simulates


.. py:function:: sigma_clip(data, sigma: float = 3, max_iter: int = 5, axis: int = -1, use_mad: bool = False, mean_func=np.ma.mean, full_return=False) -> numpy.ma.MaskedArray | tuple[numpy.ma.MaskedArray, numpy.ndarray, numpy.ndarray]

   Masks outliers by iteratively removing points outside given
   standard deviations.

   :param data: The data array.
   :type data: np.ndarray
   :param sigma: All data outside +/- sigma*std will be masked in each iteration.
   :type sigma: float
   :param max_iter: How many iterations are done. If a new iteration does not mask new
                    values, the function will break the loop.
   :type max_iter: int
   :param mean_func: Function to calculate the mean. Default is np.ma.mean, which is
                     masked array aware.
   :type mean_func: callable

   :returns: Array with outliers being masked.
   :rtype: np.ma.MaskedArray


.. py:function:: gauss_step(x, amp: float, center: float, sigma: float)

   Returns the stepfunction (erf-style) for given arguments.

   :param x: Independent variable
   :type x: array
   :param amp: Amplitude of the step
   :type amp: float
   :param center: Position of the step
   :type center: float
   :param sigma: Width of the step
   :type sigma: float

   :returns: The step functions
   :rtype: array


.. py:function:: pfid_r4(T, om, om_10, T_2)

   Calculates the PFID contribution for pure bleaching.

   See the PFID tutorial for a longer explanation. The function does
   broadcasting, hence it is possible to calculate the PFID contributions of
   serveral bands at once. For that, om_10 and T_2 must have the same shape.

   :param T: Delays between pump and probe. The formula assume a postive
             delays.
   :type T: 1D-ndarry
   :param om: Array of frequencies given in wavenumbers (cm-1).
   :type om: 1D-ndarray
   :param om_10: Frequencies of the ground-state absorbtions
   :type om_10: 1D-ndarray or float
   :param T_2: Decoherence time of the bands.
   :type T_2: 1D_ndarray or float

   :rtype: ndarry


.. py:function:: pfid_r6(T, om, om_10, om_21, T_2)

   Calculates the PFID contribution for the shifted frequecy.

   See the PFID tutorial for a longer explanation. The function does
   broadcasting, hence it is possible to calculate the PFID contributions of
   serveral bands at once. For that, om_10, om_21 and T_2 must have the same
   shape.

   :param T: Delays between pump and probe. The formula assume a postive
             delays.
   :type T: 1D-ndarry
   :param om: Array of frequencies given in wavenumbers (cm-1).
   :type om: 1D-ndarray
   :param om_10: Frequencies of the ground-state absorbtions
   :type om_10: 1D-ndarray or float
   :param om_21: Frequencies of the shifted frequency
   :type om_21: 1D-ndarray or float
   :param T_2: Decoherence time of the bands.
   :type T_2: 1D_ndarray or float

   :rtype: ndarry


.. py:function:: pfid(T, om, om_10, fac, om_21, T_2)

.. py:class:: LinRegResult

   Linear regression result.


   .. py:attribute:: data
      :type:  numpy.ndarray


   .. py:attribute:: weights
      :type:  Optional[numpy.ndarray]


   .. py:attribute:: fit
      :type:  numpy.ndarray


   .. py:attribute:: residuals
      :type:  numpy.ndarray


   .. py:attribute:: sol
      :type:  numpy.ndarray


   .. py:attribute:: r2
      :type:  numpy.ndarray


   .. py:attribute:: var
      :type:  numpy.ndarray


   .. py:attribute:: stderr
      :type:  numpy.ndarray


   .. py:attribute:: rel_err
      :type:  numpy.ndarray


   .. py:method:: fit_data(A, y, weights: Optional[numpy.ndarray] = None)
      :classmethod:


      Fit data to a linear model.

      :param A: The design matrix.
      :type A: array_like
      :param y: The data to fit.
      :type y: array_like

      :rtype: LinRegResult



.. py:function:: linreg_std_errors(A, y)

   Calculates the solution and error terms in a linear regression.

   :param A: Basis matrix
   :type A: ndarray
   :param y: Data
   :type y: ndarray

   :returns: Tuple of three arrays: standard error, variance matrix, r2
   :rtype: (ndarray, ndarray, ndarray,)


.. py:function:: ExpDecay(x, A1, tau1, c)

.. py:function:: TwoExpDecay(x, A1, tau1, A2, tau2, c)

.. py:function:: ThreeExpDecay(x, A1, tau1, A2, tau2, A3, tau3, c)

.. py:function:: poly_bg_correction(wavelengths, data, left=30, right=30, deg=1)

   Fit and subtract baseline from given data

   :param wavelengths: Shared x-values
   :type wavelengths: np.ndarry
   :param data: Dataarray
   :type data: np.ndarray
   :param left: left points to use, by default 30
   :type left: int, optional
   :param right: right points to use, by default 30
   :type right: int, optional
   :param deg: Degree of the polynomial fit, by default 1 (linear)
   :type deg: int, optional

   :returns: [description]
   :rtype: [type]


.. py:function:: inbetween(a: numpy.ndarray, lower: float, upper: float)

   Returns index-array where a is between upper and lower