vitabel.utils.helpers
=====================

.. py:module:: vitabel.utils.helpers

.. autoapi-nested-parse::

   Collection of various auxiliary and helper functions.

   ..
       !! processed by numpydoc !!


Classes
-------

.. autoapisummary::

   vitabel.utils.helpers.NumpyEncoder


Functions
---------

.. autoapisummary::

   vitabel.utils.helpers.deriv
   vitabel.utils.helpers.integrate
   vitabel.utils.helpers.construct_snippets
   vitabel.utils.helpers.av_mean
   vitabel.utils.helpers.predict_circulation
   vitabel.utils.helpers.area_under_threshold
   vitabel.utils.helpers.rename_channels
   vitabel.utils.helpers.determine_gaps_in_recording
   vitabel.utils.helpers.linear_interpolate_gaps_in_recording
   vitabel.utils.helpers.resample_to_common_index
   vitabel.utils.helpers.convert_two_alternating_list
   vitabel.utils.helpers.find_ROSC_2
   vitabel.utils.helpers.CCF_minute
   vitabel.utils.helpers.gaussian_kernel_regression_point


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

.. py:class:: NumpyEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

   Bases: :py:obj:`json.JSONEncoder`


   
   Special json encoder for numpy types
















   ..
       !! processed by numpydoc !!

   .. py:method:: default(obj)

      
      Implement this method in a subclass such that it returns
      a serializable object for ``o``, or calls the base implementation
      (to raise a ``TypeError``).

      For example, to support arbitrary iterators, you could
      implement default like this::

          def default(self, o):
              try:
                  iterable = iter(o)
              except TypeError:
                  pass
              else:
                  return list(iterable)
              # Let the base class default method raise the TypeError
              return super().default(o)















      ..
          !! processed by numpydoc !!


.. py:function:: deriv(time, data)

   
   Calculates the central point first derivative of x=time,y=data,
   and take forward/backward step derivative at the boundaries


   :Parameters:

       **time** : np.array()
           equidistantly spaced x values.

       **data** : np.array()
           corresponding y values.



   :Returns:

       **ddat** : np.array()
           array with the derivative values.











   ..
       !! processed by numpydoc !!

.. py:function:: integrate(time, data)

   
   Integrates data after time with trapezoidal rule


   :Parameters:

       **time** : pd.Series
           Timestamps in seconds.

       **data** : pd.Series
           Datapoints.



   :Returns:

       **vel** : pd.Series
           Integrated data. vel[0]=0











   ..
       !! processed by numpydoc !!

.. py:function:: construct_snippets(acctime, acc, ecgtime, ecg, CC_starts, CC_stops)

.. py:function:: av_mean(k: int, data: numpy.typing.ArrayLike) -> numpy.typing.NDArray

   
   Calculate a centered average mean of data over k elements.

   The data is zero-padded at the boundaries.















   ..
       !! processed by numpydoc !!

.. py:function:: predict_circulation(erg)

.. py:function:: area_under_threshold(timeseries: pandas.Series, start_time: vitabel.typing.Timestamp | vitabel.typing.Timedelta | None = None, stop_time: vitabel.typing.Timestamp | vitabel.typing.Timedelta | None = None, threshold: int = 0, time_unit: vitabel.typing.TimeUnitChoices = 'minutes') -> vitabel.typing.ThresholdMetrics

   
   Calculates the area and duration where the signal falls
   below a threshold.

   This function operates on a given timeseries, subtracts a threshold,
   detects zero-crossings (sign changes), interpolates crossing points,
   and integrates the area under the threshold using the trapezoidal rule.

   :Parameters:

       **timeseries**
           A :class:`pandas.Series` holding numerical data indexed by a timeseries.

       **start_time**
           Start time for truncating the timeseries (passed to meth:`.Vitals.truncate`).

       **stop_time**
           End time for truncating the timeseries (passed to meth:`.Vitals.truncate`).

       **threshold**
           The threshold of the signal under which the area is calcuated.

       **time_unit**
           The time unit according to which the result is scaled. Defaults to ``"minutes"``,
           accepts the same arguments as ``pandas.to_timedelta``.



   :Returns:

       :class:`.ThresholdMetrics`
           ..











   ..
       !! processed by numpydoc !!

.. py:function:: rename_channels(dats, new_name_dict)

.. py:function:: determine_gaps_in_recording(time: numpy.typing.ArrayLike, data: numpy.typing.ArrayLike) -> (numpy.typing.NDArray, numpy.typing.NDArray)

.. py:function:: linear_interpolate_gaps_in_recording(time: numpy.typing.ArrayLike, data: numpy.typing.ArrayLike) -> (numpy.typing.NDArray, numpy.typing.NDArray)

.. py:function:: resample_to_common_index(*channels: vitabel.timeseries.Channel) -> tuple[vitabel.typing.DataSlice, Ellipsis]

   
   Aligns two or more Channel objects by their time indices, ensuring
   all are sampled at the same time points, including zero-crossings.
   Data are interpolated to a common time base within their overlapping range.


   :Parameters:

       **\*channels**
           Two or more :class:`.Channel` objects to be aligned and interpolated.



   :Returns:

       tuple[DataSlice, ...]
           A tuple of :class:`.DataSlice` objects representing the aligned
           channels.




   :Raises:

       ValueError
           If there is no overlapping time range between the two channels.




   .. rubric:: Notes

   Zero-crossings are inserted to improve alignment, especially for
   strongly oscillating signals.



   ..
       !! processed by numpydoc !!

.. py:function:: convert_two_alternating_list(df)

.. py:function:: find_ROSC_2(rosctime, roscdata, CC_starts, CC_stops)

.. py:function:: CCF_minute(t_start, t_stop, CC_starts, CC_stops)

.. py:function:: gaussian_kernel_regression_point(x0, x, y, sigma=1, max_width_factor=2)