cibrrig.utils.alf_utils
=======================

.. py:module:: cibrrig.utils.alf_utils

.. autoapi-nested-parse::

   alf_utils.py

   This module provides utilities for handling ALF (Alyx File) data.
   The primary usage is for concatenating data from multiple recordings within a session.

   May be useful to expand functionality in the future.



Attributes
----------

.. autoapisummary::

   cibrrig.utils.alf_utils._log
   cibrrig.utils.alf_utils.TEMPORAL_FEATURES


Classes
-------

.. autoapisummary::

   cibrrig.utils.alf_utils.Recording


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

.. py:data:: _log

.. py:data:: TEMPORAL_FEATURES
   :value: ['intervals', 'times', 'on_sec', 'off_sec', 'pk_time', 'inhale_peaks', 'exhale_troughs',...


.. py:class:: Recording(session_path)

   Represents a recording session and provides methods to load, concatenate, and process ALF objects and logs.

   .. attribute:: session_path

      Path to the session directory.

      :type: Path

   .. attribute:: raw_ephys_path

      Path to the raw electrophysiological data directory.

      :type: Path

   .. attribute:: alf_path

      Path to the ALF data directory.

      :type: Path

   .. attribute:: ni_fns

      List of NIDQ binary files in the raw ephys data directory.

      :type: list

   .. attribute:: n_recs

      Number of recordings found in the session.

      :type: int

   .. attribute:: breaks

      Array of break times between recordings.

      :type: np.ndarray

   .. attribute:: alf_objects

      List of all ALF objects in the session.

      :type: list


   .. py:attribute:: session_path


   .. py:attribute:: raw_ephys_path


   .. py:attribute:: alf_path


   .. py:attribute:: ni_fns


   .. py:attribute:: n_recs


   .. py:method:: get_breaks_times()

      Calculates the break times between recordings and stores them in the breaks attribute.

      This method reads the metadata from each NIDQ binary file to determine the duration of each recording
      and calculates the cumulative break times.



   .. py:method:: list_all_alf_objects()

      Lists all ALF objects present in the session and stores them in the alf_objects attribute.

      This method scans the ALF directory for all ALF objects and extracts their names.



   .. py:method:: concatenate_triggers(object_name)

      Concatenates data of a given object (e.g., breaths, laser...) from multiple recordings (i.e. triggers) into a single ALF object.

      :param object_name: Name of the ALF object to concatenate.
      :type object_name: str

      :returns: Concatenated ALF object.
      :rtype: dict



   .. py:method:: concatenate_log(save=True, overwrite=True)

      Concatenates log data from multiple recordings into a single DataFrame.

      :param save: If True, save the concatenated log to a file. Defaults to True.
      :type save: bool, optional
      :param overwrite: If True, overwrite existing log files. Defaults to True.
      :type overwrite: bool, optional

      :returns: Concatenated log DataFrame.
      :rtype: pd.DataFrame



   .. py:method:: improve_opto_log(log)

      Enhances the optogenetic stimulation log by adding calibrated amplitudes and end times.

      :param log: DataFrame containing the optogenetic stimulation log.
      :type log: pd.DataFrame

      :returns: Enhanced optogenetic stimulation log.
      :rtype: pd.DataFrame



   .. py:method:: concatenate_alf_objects(save=True, overwrite=True)

      Concatenates all ALF objects in the session.

      :param save: If True, save the concatenated ALF objects to files. Defaults to True.
      :type save: bool, optional
      :param overwrite: If True, overwrite existing ALF files. Defaults to True.
      :type overwrite: bool, optional

      :returns: None



   .. py:method:: concatenate_session(save=True, overwrite=True)

      Concatenates all ALF objects and logs in the session.

      :param save: If True, save the concatenated data to files. Defaults to True.
      :type save: bool, optional
      :param overwrite: If True, overwrite existing files. Defaults to True.
      :type overwrite: bool, optional

      :returns: None



   .. py:method:: load_spikes()