lunapi.lwf
==========

.. py:module:: lunapi.lwf

.. autoapi-nested-parse::

   Reader for Luna's .lwf (Luna Waveform) binary format.

   Public functions
   ----------------
   lwf_summary(paths, *, recur=False) -> pd.DataFrame
       Scan one or more .lwf files and return a per-file summary without loading
       any signal data.

   read_lwf(paths, *, recur=False) -> LWFResult
       Load one or more .lwf files into a single result object containing a numpy
       array of signal data, a per-event metadata DataFrame, and a per-channel
       metadata DataFrame.



Classes
-------

.. autoapisummary::

   lunapi.lwf.LWFResult


Functions
---------

.. autoapisummary::

   lunapi.lwf.lwf_summary
   lunapi.lwf.read_lwf


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

.. py:class:: LWFResult

   Bases: :py:obj:`NamedTuple`


   Return value of :func:`read_lwf`.

   .. attribute:: data

      Signal data decoded to physical units (µV etc.).  When the file was
      written with ``annot-ch-match=T``, ``n_channels`` is 1 and the
      detecting channel for each event is in ``meta['annot_ch']``.

      :type: np.ndarray, shape (n_waves, n_channels, n_samples)

   .. attribute:: meta

      Per-event metadata columns: ``id``, ``tag``, ``file``, ``annot``,
      ``instance``, ``annot_ch``, ``meta``, ``anchor_sec``,
      ``annot_start_sec``, ``annot_stop_sec``, ``wave_start_sec``,
      ``wave_stop_sec``.

      :type: pd.DataFrame, shape (n_waves, ...)

   .. attribute:: channels

      Per-channel metadata: ``label``, ``unit``, ``sr``, ``phys_min``,
      ``phys_max``.  In annot-ch-match mode this has a single placeholder
      row; consult ``meta['annot_ch']`` for the actual channel per event.

      :type: pd.DataFrame, shape (n_channels, ...)

   .. attribute:: attrs

      File-level attributes: ``sfreq``, ``align``, ``source_files``,
      ``annot_ch_match``.

      :type: dict


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


   .. py:attribute:: meta
      :type:  pandas.DataFrame


   .. py:attribute:: channels
      :type:  pandas.DataFrame


   .. py:attribute:: attrs
      :type:  dict


.. py:function:: lwf_summary(paths: Union[str, pathlib.Path, Iterable], *, recur: bool = False) -> pandas.DataFrame

   Summarise one or more .lwf files without loading signal data.

   :param paths: A .lwf file, a directory, or a list of either.
   :param recur: Recurse into subdirectories when *paths* is a directory.

   :returns: * *pd.DataFrame with one row per file and columns*
             * ``file``, ``id``, ``tag``, ``startdate``, ``starttime``, ``align``,
             * ``annots``, ``n_waves``, ``n_channels``, ``channels``, ``srs``,
             * ``n_features``.


.. py:function:: read_lwf(paths: Union[str, pathlib.Path, Iterable], *, recur: bool = False) -> LWFResult

   Load one or more .lwf files into an :class:`LWFResult`.

   All files must share the same channel labels and sample rates.
   All waveform events must have the same number of samples.

   :param paths: A .lwf file, a directory, or a list of either.
   :param recur: Recurse into subdirectories when *paths* is a directory.

   :returns: Named tuple with fields ``data``, ``meta``, ``channels``, ``attrs``.
             ``data`` has shape ``(n_waves, n_channels, n_samples)`` with values
             in physical units.  When written with ``annot-ch-match=T``,
             ``n_channels`` is 1 and each event's channel is in
             ``meta['annot_ch']``.
   :rtype: LWFResult