lunapi.results ============== .. py:module:: lunapi.results .. autoapi-nested-parse:: 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 --------- .. autoapisummary:: lunapi.results.fetch_doms lunapi.results.fetch_cmds lunapi.results.fetch_params lunapi.results.fetch_tbls lunapi.results.fetch_vars lunapi.results.fetch_desc_dom lunapi.results.fetch_desc_cmd lunapi.results.fetch_desc_param lunapi.results.fetch_desc_tbl lunapi.results.fetch_desc_var lunapi.results.cmdfile lunapi.results.strata lunapi.results.table lunapi.results.tables lunapi.results.show lunapi.results.subset lunapi.results.concat lunapi.results.version Module Contents --------------- .. py:function:: fetch_doms() Return all top-level Luna command domains. :returns: Domain names (e.g. ``'PSG'``, ``'Spectral'``). :rtype: list of str .. py:function:: fetch_cmds(dom) Return all Luna commands belonging to a domain. :param dom: Domain name as returned by :func:`fetch_doms`. :type dom: str :returns: Command names within *dom*. :rtype: list of str .. py:function:: fetch_params(cmd) Return the accepted parameters for a Luna command. :param cmd: Luna command name (e.g. ``'PSD'``). :type cmd: str :returns: Parameter names accepted by *cmd*. :rtype: list of str .. py:function:: fetch_tbls(cmd) Return the output tables produced by a Luna command. :param cmd: Luna command name. :type cmd: str :returns: Strata labels for the tables produced by *cmd* (e.g. ``['BL', 'CH', 'CH_F']``). :rtype: list of str .. py:function:: fetch_vars(cmd, tbl) Return the output variables in a specific command/table. :param cmd: Luna command name. :type cmd: str :param tbl: Strata label identifying the table within *cmd*. :type tbl: str :returns: Variable names present in the specified output table. :rtype: list of str .. py:function:: fetch_desc_dom(dom) Return a short description for a Luna command domain. :param dom: Domain name. :type dom: str :returns: Human-readable description of *dom*. :rtype: str .. py:function:: fetch_desc_cmd(cmd) Return a short description for a Luna command. :param cmd: Luna command name. :type cmd: str :returns: Human-readable description of *cmd*. :rtype: str .. py:function:: fetch_desc_param(cmd, param) Return a short description for a Luna command parameter. :param cmd: Luna command name. :type cmd: str :param param: Parameter name within *cmd*. :type param: str :returns: Human-readable description of *param*. :rtype: str .. py:function:: fetch_desc_tbl(cmd, tbl) Return a short description for a Luna command output table. :param cmd: Luna command name. :type cmd: str :param tbl: Strata label identifying the table within *cmd*. :type tbl: str :returns: Human-readable description of the table. :rtype: str .. py:function:: fetch_desc_var(cmd, tbl, var) Return a short description for a variable in a Luna output table. :param cmd: Luna command name. :type cmd: str :param tbl: Strata label identifying the table. :type tbl: str :param var: Variable name within the table. :type var: str :returns: Human-readable description of *var*. :rtype: str .. py:function:: 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). :param f: Path to a ``.txt`` (or ``.luna``) script file. :type f: str or path-like :returns: Raw text content of the file. :rtype: str .. py:function:: strata(ts) List all (command, stratum) pairs present in a result collection. :param ts: Nested dict returned by :func:`tables`, mapping command names to stratum-keyed dicts of raw result tuples. :type ts: dict :returns: List of ``(command, stratum)`` string pairs. :rtype: list of tuple .. py:function:: table(ts, cmd, strata='BL') Extract a single output table as a DataFrame from a raw result dict. :param ts: Raw result dict as returned by the C++ backend (before conversion). :type ts: dict :param cmd: Luna command name. :type cmd: str :param strata: Stratum label. Default ``'BL'``. :type strata: str, optional :returns: Result table with properly named columns. :rtype: pandas.DataFrame .. py:function:: tables(ts) Convert a raw backend result dict to a collection of DataFrames. :param ts: Raw result dict returned by the C++ backend, mapping command names to stratum-keyed dicts of ``(column_names, data_matrix)`` tuples. :type ts: dict :returns: Mapping of ``"COMMAND: STRATA"`` string keys to ``pandas.DataFrame`` values. :rtype: dict .. py:function:: show(dfs) Display a result collection in the notebook with bold headings. :param dfs: Mapping of label strings to ``pandas.DataFrame`` objects, as returned by :func:`tables`. :type dfs: dict :returns: Output is rendered via ``IPython.display``. :rtype: None .. py:function:: subset(df, ids=None, qry=None, vars=None) Subset rows and/or columns of a Luna result DataFrame. :param df: Result table to filter, typically containing an ``'ID'`` column. :type df: pandas.DataFrame :param ids: Keep only rows whose ``'ID'`` value is in *ids*. :type ids: str or list of str, optional :param qry: A :meth:`pandas.DataFrame.query` expression for row filtering (e.g. ``'F > 10 and F < 20'``). :type qry: str, optional :param vars: Column names to retain. ``'ID'`` is always kept as the first column. :type vars: str or list of str, optional :returns: Filtered DataFrame. :rtype: pandas.DataFrame .. py:function:: 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 :func:`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. :param dfs: Outer dict mapping arbitrary keys (e.g. individual IDs) to inner result dicts (``"CMD: STRATA"`` → ``DataFrame``). :type dfs: dict :param tlab: Result key (``"CMD: STRATA"``) identifying which table to extract from each inner dict. :type tlab: str :param vars: Columns to keep from each extracted table. If omitted, all columns are included. :type vars: str or list of str, optional :param add_index: If provided, a column with this name is added to each table and populated with the corresponding outer key from *dfs*. :type add_index: str, optional :param ignore_index: Passed directly to :func:`pandas.concat`. Default ``True``. :type ignore_index: bool, optional :returns: Concatenated table. :rtype: pandas.DataFrame .. py:function:: version() Return version information for both the Python package and the C++ backend. :returns: ``{'lunapi': '', 'luna': ''}`` :rtype: dict