Class to build query, curation, and output configurations for metahq retrieve. Exists to support modularity and reduce redundnacy in the retrieval commands.

get_filters(filters)

Parses and checks requested filters.

Parameters:
  • filters (str) –

    A comma-delimited string of supported MetaHQ filters.
Returns:
  • dict[str, str] –

    A dictionary of filter key, values.

Examples:

>>> from metahq_cli.retrieval_builder import Builder
>>> builder = Builder()
>>> filters = 'species=human,ecode=expert,tech=rnaseq'
>>> builder.get_filters()
{'species': 'human', 'ecode': 'expert', 'tech': 'rnaseq'}

parse_onto_terms(terms, reference)

Collects passed query terms and checks if they are appropriate.

Attributes:
  • terms (list[str]) –

    A list of ontology term IDs. Can be ontology IDs for tissues or diseases. (e.g., ['UBERON:0000948', 'UBERON:0000955']).

  • reference (str) –

    An indication of what kind of terms these are (e.g., 'UBERON' or 'MONDO').
Returns:
  • list[str] –

    Any terms that are supported within MetaHQ.
Raises:

query_config(db, attribute, level, filters, license='any')

Construct a query configuration.

Query parameters are checked in the metahq_core.query module.

Parameters:
  • db (str) –

    The name of a supported database within MetaHQ.

  • attribute (str) –

    A supported attribute within MetaHQ.

  • level (str) –

    A level of annotations (e.g., 'sample' or 'series').

  • filters (dict[str, str]) –

    Filters parsed by Builder.get_filters.

  • license (str, default: 'any' ) –

    License filter category. One of 'permissive', 'nc', or 'any' (default).
Returns:
  • QueryConfig –

    A populated QueryConfig.

curation_config(terms, mode, ontology)

Construct a curation configuration.

Attributes:
  • terms (str) –

    A list of terms to curate annotations for.

  • mode (str) –

    A supported curation mode (e.g., 'annotate', 'label').

  • ontology (str) –

    An ontology to use for propagating annotations and assigning labels.
Returns:
  • CurationConfig –

    A populated CurationConfig.

output_config(outdir, fmt, metadata, level, attribute)

Construct an output configuration.

Attributes:
  • outdir (Path) –

    Resolved output directory (created by resolve_outdir).

  • fmt (Literal[json, parquet, csv, tsv]) –

    Format of the output file.

  • metadata (str) –

    Comma-delimited string indicating which metadata fields to include.

  • level (str) –

    Annotation level to check if any of the requested metadata fields are available for the requested level.
Returns:
  • OutputConfig –

    A populated OutputConfig.

citation_config(version, terms, attribute, level, filters, mode, license, date, outdir)

Construct a citation configuration.

Attributes:
  • version (str) –

    Version of the MetaHQ databse.

  • attribute (str) –

    A supported attribute within MetaHQ.

  • level (str) –

    A level of annotations (e.g., 'sample' or 'series').

  • filters (dict[str, str]) –

    Filters parsed by Builder.get_filters.

  • mode (Literal[direct, annotate, label]) –

    Retrieve direct, propagated annotations, or labels.

  • license (str) –

    License filter applied to the query.

  • date (str) –

    Date and time of the query.

  • outdir (Path) –

    Path to the output directory for the citation file.
Returns:

make_age_curation(terms, mode)

Makes an age-specific CurationConfig.

make_sex_curation(terms, mode)

Sex-specific curation.

report_bad_filters(filters)

Check filters and return improper filter parameters.