cibrrig.preprocess.extract_physiology
=====================================

.. py:module:: cibrrig.preprocess.extract_physiology

.. autoapi-nested-parse::

   Command line script to extract and downsample physiological data from NIDAQ recording.
   The recorded auxiliary data (e.g. diaphragm and pleth) is sampled at 10K.
   While the high sampling rate is critical to acquire good EMG, it is excessive for both
   the integrated and the pleth.

   This script does the following:
   1) Downsamples the Flow/Pdiff  traces by 10x to be input into breathmetrics (BM does filtering and processing)
   2) Filters the EMG (300-5K)
   3) Integrates the EMG with a triangular window
   4) Downsamples the integrated EMG by 10x to match the pleth
   5) Extracts features from the integrated EMG.
   6) Extracts heart rate from EKG channel if recorded
   6) Saves to alf standardized files in the session path



Attributes
----------

.. autoapisummary::

   cibrrig.preprocess.extract_physiology._log
   cibrrig.preprocess.extract_physiology.BM_PATH
   cibrrig.preprocess.extract_physiology.BM_PATH


Functions
---------

.. autoapisummary::

   cibrrig.preprocess.extract_physiology._crop_traces
   cibrrig.preprocess.extract_physiology._get_trigger_from_SR
   cibrrig.preprocess.extract_physiology.label_sighs
   cibrrig.preprocess.extract_physiology.run_one
   cibrrig.preprocess.extract_physiology.run
   cibrrig.preprocess.extract_physiology.main


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

.. py:data:: _log

.. py:data:: BM_PATH
   :value: '/active/ramirez_j/ramirezlab/nbush/projects/cibrrig/cibrrig/preprocess'


.. py:data:: BM_PATH

.. py:function:: _crop_traces(t, x)

   Utility to crop both the time trace and an arbitrary vector to the same length (shortest length).
   Useful to prevent off-by-one errors.

   :param t: Time stamps for each element in x.
   :type t: np.ndarray
   :param x: Signal vector.
   :type x: np.ndarray

   :returns:

             A tuple containing:
                 - np.ndarray: Cropped timestamp array.
                 - np.ndarray: Cropped Signal vector.
   :rtype: tuple


.. py:function:: _get_trigger_from_SR(SR)

   Get the trigger number from the filename

   :param SR: Spikeglx reader object
   :type SR: spikeglx.Reader

   :returns: Trigger label extracted from the filename (e.g., 't0', 't1', etc.)
   :rtype: str


.. py:function:: label_sighs(dia_df)

   Categorize breaths as sighs or eupnea based on the diaphragm data.

   :param dia_df: DataFrame containing diaphragm data with columns 'on_sec' and 'auc'.
   :type dia_df: pd.DataFrame

   :returns: DataFrame with additional columns 'breath_type', 'is_sigh', and 'is_eupnea'.
   :rtype: pd.DataFrame


.. py:function:: run_one(SR, wiring, v_in, inhale_pos, save_path)

   Process physiological data from a single recording.
   Passes data to functions in the physiology module to process and save the data.

   :param SR: SpikeGLX reader object for the recording.
   :type SR: spikeglx.Reader
   :param wiring: Wiring configuration.
   :type wiring: dict
   :param v_in: Voltage input.
   :type v_in: float
   :param inhale_pos: Inhale position.
   :type inhale_pos: int
   :param save_path: Path to save the processed data.
   :type save_path: Path

   :returns: None


.. py:function:: run(session_path, v_in=9, inhale_pos=False, save_path=None, debug=False)

   Run the physiology extraction process on a session.

   :param session_path: Path to the session data.
   :type session_path: Path
   :param v_in: Voltage supply for the flowmeter sensor. Defaults to 9.
   :type v_in: float, optional
   :param inhale_pos: Set true if inhale was acquired as a positive signal. Defaults to False.
   :type inhale_pos: bool, optional
   :param save_path: Path to save data to. If None, save to parent directory of binary file. Defaults to None.
   :type save_path: Path, optional
   :param debug: If True, enable debug loggin. Defaults to False.
   :type debug: bool, optional


.. py:function:: main(session_path, v_in, inhale_pos, save_path, debug)

   Main entry point for the physiology extraction script.

   :param session_path: Path to the session data.
   :type session_path: str
   :param v_in: Voltage supply for the flowmeter sensor. Defaults to 9.
   :type v_in: float, optional
   :param inhale_pos: Set true if inhale was acquired as a positive signal. Defaults to False.
   :type inhale_pos: bool, optional
   :param save_path: Path to save data to. If None, save to parent directory of binary file. Defaults to None.
   :type save_path: str, optional
   :param debug: If True, enable debug mode.
   :type debug: bool