lunapi.results

Result and metadata utilities.

This module provides helper functions for:

• discovering Luna command domains/tables/variables

• reading command files

• converting raw return tuples into DataFrames

• subsetting/concatenating result collections

Functions

fetch_doms()	Return all top-level Luna command domains.
fetch_cmds(dom)	Return all Luna commands belonging to a domain.
fetch_params(cmd)	Return the accepted parameters for a Luna command.
fetch_tbls(cmd)	Return the output tables produced by a Luna command.
fetch_vars(cmd, tbl)	Return the output variables in a specific command/table.
fetch_desc_dom(dom)	Return a short description for a Luna command domain.
fetch_desc_cmd(cmd)	Return a short description for a Luna command.
fetch_desc_param(cmd, param)	Return a short description for a Luna command parameter.
fetch_desc_tbl(cmd, tbl)	Return a short description for a Luna command output table.
fetch_desc_var(cmd, tbl, var)	Return a short description for a variable in a Luna output table.
cmdfile(f)	Read and return the full text of a Luna command script file.
strata(ts)	List all (command, stratum) pairs present in a result collection.
table(ts, cmd[, strata])	Extract a single output table as a DataFrame from a raw result dict.
tables(ts)	Convert a raw backend result dict to a collection of DataFrames.
show(dfs)	Display a result collection in the notebook with bold headings.
subset(df[, ids, qry, vars])	Subset rows and/or columns of a Luna result DataFrame.
concat(dfs, tlab[, vars, add_index, ignore_index])	Concatenate matching tables from a dict of result sets.
version()	Return version information for both the Python package and the C++ backend.

Module Contents

lunapi.results.fetch_doms()

Return all top-level Luna command domains.

Returns:

Domain names (e.g. 'PSG', 'Spectral').

Return type:

list of str

lunapi.results.fetch_cmds(dom)

Return all Luna commands belonging to a domain.

Parameters:

dom (str) – Domain name as returned by fetch_doms().

Returns:

Command names within dom.

Return type:

list of str

lunapi.results.fetch_params(cmd)

Return the accepted parameters for a Luna command.

Parameters:

cmd (str) – Luna command name (e.g. 'PSD').

Returns:

Parameter names accepted by cmd.

Return type:

list of str

lunapi.results.fetch_tbls(cmd)

Return the output tables produced by a Luna command.

Parameters:

cmd (str) – Luna command name.

Returns:

Strata labels for the tables produced by cmd (e.g. ['BL', 'CH', 'CH_F']).

Return type:

list of str

lunapi.results.fetch_vars(cmd, tbl)

Return the output variables in a specific command/table.

Parameters:

• cmd (str) – Luna command name.

• tbl (str) – Strata label identifying the table within cmd.

Returns:

Variable names present in the specified output table.

Return type:

list of str

lunapi.results.fetch_desc_dom(dom)

Return a short description for a Luna command domain.

Parameters:

dom (str) – Domain name.

Returns:

Human-readable description of dom.

Return type:

str

lunapi.results.fetch_desc_cmd(cmd)

Return a short description for a Luna command.

Parameters:

cmd (str) – Luna command name.

Returns:

Human-readable description of cmd.

Return type:

str

lunapi.results.fetch_desc_param(cmd, param)

Return a short description for a Luna command parameter.

Parameters:

• cmd (str) – Luna command name.

• param (str) – Parameter name within cmd.

Returns:

Human-readable description of param.

Return type:

str

lunapi.results.fetch_desc_tbl(cmd, tbl)

Return a short description for a Luna command output table.

Parameters:

• cmd (str) – Luna command name.

• tbl (str) – Strata label identifying the table within cmd.

Returns:

Human-readable description of the table.

Return type:

str

lunapi.results.fetch_desc_var(cmd, tbl, var)

Return a short description for a variable in a Luna output table.

Parameters:

• cmd (str) – Luna command name.

• tbl (str) – Strata label identifying the table.

• var (str) – Variable name within the table.

Returns:

Human-readable description of var.

Return type:

str

lunapi.results.cmdfile(f)

Read and return the full text of a Luna command script file.

Preserves original line structure so that IF/FI blocks are parsed as separate Luna commands (some workflows rely on multiline control statements).

Parameters:

f (str or path-like) – Path to a .txt (or .luna) script file.

Returns:

Raw text content of the file.

Return type:

str

lunapi.results.strata(ts)

List all (command, stratum) pairs present in a result collection.

Parameters:

ts (dict) – Nested dict returned by tables(), mapping command names to stratum-keyed dicts of raw result tuples.

Returns:

List of (command, stratum) string pairs.

Return type:

list of tuple

lunapi.results.table(ts, cmd, strata='BL')

Extract a single output table as a DataFrame from a raw result dict.

Parameters:

• ts (dict) – Raw result dict as returned by the C++ backend (before conversion).

• cmd (str) – Luna command name.

• strata (str, optional) – Stratum label. Default 'BL'.

Returns:

Result table with properly named columns.

Return type:

pandas.DataFrame

lunapi.results.tables(ts)

Convert a raw backend result dict to a collection of DataFrames.

Parameters:

ts (dict) – Raw result dict returned by the C++ backend, mapping command names to stratum-keyed dicts of (column_names, data_matrix) tuples.

Returns:

Mapping of "COMMAND: STRATA" string keys to pandas.DataFrame values.

Return type:

dict

lunapi.results.show(dfs)

Display a result collection in the notebook with bold headings.

Parameters:

dfs (dict) – Mapping of label strings to pandas.DataFrame objects, as returned by tables().

Returns:

Output is rendered via IPython.display.

Return type:

None

lunapi.results.subset(df, ids=None, qry=None, vars=None)

Subset rows and/or columns of a Luna result DataFrame.

Parameters:

• df (pandas.DataFrame) – Result table to filter, typically containing an 'ID' column.

• ids (str or list of str, optional) – Keep only rows whose 'ID' value is in ids.

• qry (str, optional) – A pandas.DataFrame.query() expression for row filtering (e.g. 'F > 10 and F < 20').

• vars (str or list of str, optional) – Column names to retain. 'ID' is always kept as the first column.

Returns:

Filtered DataFrame.

Return type:

pandas.DataFrame

lunapi.results.concat(dfs, tlab, vars=None, add_index=None, ignore_index=True)

Concatenate matching tables from a dict of result sets.

Assumes dfs is a dict where each value is itself a result dict (as returned by tables()), and extracts the table labelled tlab from each, then concatenates them. Commonly used to stack results from multiple individuals or conditions that were processed separately.

Parameters:

• dfs (dict) – Outer dict mapping arbitrary keys (e.g. individual IDs) to inner result dicts ("CMD: STRATA" → DataFrame).

• tlab (str) – Result key ("CMD: STRATA") identifying which table to extract from each inner dict.

• vars (str or list of str, optional) – Columns to keep from each extracted table. If omitted, all columns are included.

• add_index (str, optional) – If provided, a column with this name is added to each table and populated with the corresponding outer key from dfs.

• ignore_index (bool, optional) – Passed directly to pandas.concat(). Default True.

Returns:

Concatenated table.

Return type:

pandas.DataFrame

lunapi.results.version()

Return version information for both the Python package and the C++ backend.

Returns:

{'lunapi': '<version>', 'luna': '<version>'}

Return type:

dict