lunapi.destrat
==============

.. py:module:: lunapi.destrat

.. autoapi-nested-parse::

   Direct reader for Luna STOUT output databases (.db files).

   Provides :class:`destrat`, a pure-Python / SQLite reader that replicates
   the functionality of the ``destrat`` command-line tool without subprocess
   overhead.  One or more ``.db`` files (glob patterns accepted) are opened
   read-only, and data can be extracted as tidy pandas DataFrames.

   Example usage::

       import lunapi as lp

       db = lp.destrat('out/run-*.db')
       db.tables()                                   # summary of available data
       df = db.get('+PSD', r=['B', 'CH'])            # all PSD vars, all levels
       df = db.get('+PSD', r='B/ALPHA,SIGMA CH', v=['PSD'])  # destrat-style
       df = db.get('+PSD', r={'B': ['ALPHA','SIGMA'], 'CH': None}, v=['PSD'])
       df = db.get('STATS')                          # baseline (no row factors)



Classes
-------

.. autoapisummary::

   lunapi.destrat.destrat


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

.. py:class:: destrat(pattern)

   Read one or more Luna STOUT output databases.

   :param pattern: Glob pattern, single path, or list of paths/patterns pointing to
                   Luna ``.db`` files.
   :type pattern: str or list of str

   .. rubric:: Examples

   >>> db = lp.destrat('out/run-*.db')
   >>> db.tables()
   >>> db.get('+PSD', r=['B', 'CH'], v=['PSD'])
   >>> db.get('+PSD', r='B/ALPHA,SIGMA CH', v=['PSD'])
   >>> db.get('+PSD', r={'B': ['ALPHA','SIGMA'], 'CH': None})
   >>> db.get('STATS')


   .. py:method:: tables()

      Summary of all command/strata/variable combinations across all databases.

      :returns: Columns: ``CMD``, ``FACTORS``, ``N_VARS``, ``VARIABLES``
      :rtype: pandas.DataFrame



   .. py:method:: vars(cmd=None)

      List variables available in the database(s).

      :param cmd: Filter to a single command (e.g. ``'PSD'``).  Leading ``+``/``#``
                  is stripped automatically.
      :type cmd: str, optional

      :returns: Columns: ``CMD``, ``VAR``
      :rtype: pandas.DataFrame



   .. py:method:: get(cmd, r=None, v=None, ids=None, c=None)

      Extract data from the database(s) and return a tidy DataFrame.

      :param cmd: Command name.  Leading ``+`` or ``#`` is accepted and stripped,
                  so ``'+PSD'``, ``'#PSD'``, and ``'PSD'`` are all equivalent.
      :type cmd: str
      :param r: Row stratifiers — each unique combination becomes a separate row.
                Accepted forms (all equivalent):

                - space-separated string: ``'B CH'`` or ``'B/ALPHA,SIGMA CH'``
                - list: ``['B', 'CH']``
                - dict: ``{'B': ['ALPHA','SIGMA'], 'CH': None}``

                A ``/``-suffix restricts to specific levels: ``'B/ALPHA,SIGMA'``.
                Use ``'E'`` to include epoch numbers (joined from timepoints table).
      :type r: str, list, or dict, optional
      :param c: Column stratifiers — each level combination is pivoted into its
                own set of column(s) named ``VAR.FAC_LEVEL``.  Accepts the same
                forms as *r*.
      :type c: str, list, or dict, optional
      :param v: Variable name(s) to include.  Space-separated string accepted.
                ``None`` returns all variables.
      :type v: str or list of str, optional
      :param ids: Individual IDs to include.  Space-separated string accepted.
                  ``None`` returns all individuals.
      :type ids: str or list of str, optional

      :returns: Without *c*: columns are ``ID``, row-factor columns, variable
                columns.  With *c*: variable columns are named ``VAR.FAC_LVL``
                for each col-strata level.  Missing combinations yield ``NaN``.
      :rtype: pandas.DataFrame



   .. py:property:: files

      List of resolved .db file paths.