lunapi.destrat

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

Provides 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

destrat

Read one or more Luna STOUT output databases.

Module Contents

class lunapi.destrat.destrat(pattern)

Read one or more Luna STOUT output databases.

Parameters:

pattern (str or list of str) – Glob pattern, single path, or list of paths/patterns pointing to Luna .db files.

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')

tables()

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

Returns:

Columns: CMD, FACTORS, N_VARS, VARIABLES

Return type:

pandas.DataFrame

vars(cmd=None)

List variables available in the database(s).

Parameters:

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

Returns:

Columns: CMD, VAR

Return type:

pandas.DataFrame

get(cmd, r=None, v=None, ids=None, c=None)

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

Parameters:

• cmd (str) – Command name. Leading + or # is accepted and stripped, so '+PSD', '#PSD', and 'PSD' are all equivalent.

• r (str, list, or dict, optional) –

  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).

• c (str, list, or dict, optional) – Column stratifiers — each level combination is pivoted into its own set of column(s) named VAR.FAC_LEVEL. Accepts the same forms as r.

• v (str or list of str, optional) – Variable name(s) to include. Space-separated string accepted. None returns all variables.

• ids (str or list of str, optional) – Individual IDs to include. Space-separated string accepted. None returns all individuals.

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.

Return type:

pandas.DataFrame

property files

List of resolved .db file paths.