Command-line interface

Command-line interface#

smftools#

Command-line interface for smftools.

.. program:: smftools .. rubric:: Usage

.. code-block:: shell

smftools [OPTIONS] COMMAND [ARGS]...

.. rubric:: Options

.. option:: --version

Show the version and exit.

.. option:: --log-file <log_file>

Optional file path to write smftools logs.

.. option:: --log-level <log_level>

Logging level for smftools output.

:default: ``'INFO'``
:options: CRITICAL | ERROR | WARNING | INFO | DEBUG

experiment#

Run pipeline stages for a single experiment (one config path in).

.. program:: smftools experiment .. rubric:: Usage

.. code-block:: shell

smftools experiment [OPTIONS] COMMAND [ARGS]...

batch#

Run a TASK (raw, load, preprocess, spatial, variant, hmm) on multiple CONFIG_PATHs listed in a CSV/TSV or plain TXT file.

Plain text format: one config path per line, no header.

.. program:: smftools experiment batch .. rubric:: Usage

.. code-block:: shell

smftools experiment batch [OPTIONS] {raw|load|preprocess|spatial|variant|hmm}
                          CONFIG_TABLE

.. rubric:: Options

.. option:: -c, --column

Column name containing config paths (ignored for plain TXT).

:default: ``'config_path'``

.. option:: --sep

Field separator: default auto-detect (.tsv -> '\t', .csv -> ',', others treated as TXT).

.. rubric:: Arguments

.. option:: TASK

Required argument

.. option:: CONFIG_TABLE

Required argument

chimeric#

Finding putative PCR chimeras

.. program:: smftools experiment chimeric .. rubric:: Usage

.. code-block:: shell

smftools experiment chimeric [OPTIONS] CONFIG_PATH

.. rubric:: Arguments

.. option:: CONFIG_PATH

Required argument

concatenate#

Concatenate multiple .h5ad files into a single output file.

Reads concatenation parameters from an experiment config CSV. Input source (directory or CSV of paths) is configured via concatenate_input_dir / concatenate_csv_path in the config, or overridden with --input-dir / --csv-path.

Output path is auto-detected from the pipeline stage of the input filenames (e.g. *_variant.h5ad → variant output directory). Use --output-path to override.

Example:

smftools experiment concatenate experiment_config.csv

smftools experiment concatenate experiment_config.csv --recompute-pp-vars

smftools experiment concatenate experiment_config.csv --input-dir ./variant_h5ads/

.. program:: smftools experiment concatenate .. rubric:: Usage

.. code-block:: shell

smftools experiment concatenate [OPTIONS] CONFIG_PATH

.. rubric:: Options

.. option:: --recompute-pp-vars

Recompute calculate_coverage and append_base_context after concatenation.

.. option:: -d, --input-dir <input_dir>

Override concatenate_input_dir from config.

.. option:: -c, --csv-path <csv_path>

Override concatenate_csv_path from config.

.. option:: -o, --output-path <output_path>

Explicit output path (overrides stage auto-detection).

.. rubric:: Arguments

.. option:: CONFIG_PATH

Required argument

export-fastq#

Write one FASTQ per barcode of QC-passed reads, for one experiment.

Reads sequence/quality directly from the raw ragged store; the QC-passed read set is resolved from the most complete preprocessing artifact available.

Example:

smftools experiment export-fastq experiment_config.csv --outdir ./fastqs

.. program:: smftools experiment export-fastq .. rubric:: Usage

.. code-block:: shell

smftools experiment export-fastq [OPTIONS] CONFIG_PATH

.. rubric:: Options

.. option:: -o, --outdir

**Required** Output directory for FASTQ files + manifest CSV.

.. option:: --group-by <group_by>

obs column to group reads by (default: Sample/Barcode).

.. option:: --allow-unfiltered

Write all reads when no QC-passed read set is available, instead of raising/skipping.

.. option:: --no-gzip

Write plain .fastq instead of .fastq.gz.

.. rubric:: Arguments

.. option:: CONFIG_PATH

Required argument

full#

Workflow: raw preprocess spatial hmm.

.. program:: smftools experiment full .. rubric:: Usage

.. code-block:: shell

smftools experiment full [OPTIONS] CONFIG_PATH

.. rubric:: Arguments

.. option:: CONFIG_PATH

Required argument

hmm#

HMM feature annotations and plotting

.. program:: smftools experiment hmm .. rubric:: Usage

.. code-block:: shell

smftools experiment hmm [OPTIONS] CONFIG_PATH

.. rubric:: Arguments

.. option:: CONFIG_PATH

Required argument

latent#

Latent representations of signal

.. program:: smftools experiment latent .. rubric:: Usage

.. code-block:: shell

smftools experiment latent [OPTIONS] CONFIG_PATH

.. rubric:: Arguments

.. option:: CONFIG_PATH

Required argument

load#

Optionally pre-build the dense zarr cache from raw artifacts.

.. program:: smftools experiment load .. rubric:: Usage

.. code-block:: shell

smftools experiment load [OPTIONS] CONFIG_PATH

.. rubric:: Arguments

.. option:: CONFIG_PATH

Required argument

plot-current#

Plot nanopore current traces for specified reads.

.. program:: smftools experiment plot-current .. rubric:: Usage

.. code-block:: shell

smftools experiment plot-current [OPTIONS] CONFIG_PATH

.. rubric:: Arguments

.. option:: CONFIG_PATH

Required argument

preprocess#

Preprocessing.

.. program:: smftools experiment preprocess .. rubric:: Usage

.. code-block:: shell

smftools experiment preprocess [OPTIONS] CONFIG_PATH

.. rubric:: Arguments

.. option:: CONFIG_PATH

Required argument

raw#

Prepare BAM artifacts and write the ragged raw store.

.. program:: smftools experiment raw .. rubric:: Usage

.. code-block:: shell

smftools experiment raw [OPTIONS] CONFIG_PATH

.. rubric:: Arguments

.. option:: CONFIG_PATH

Required argument

spatial#

Spatial signal analysis

.. program:: smftools experiment spatial .. rubric:: Usage

.. code-block:: shell

smftools experiment spatial [OPTIONS] CONFIG_PATH

.. rubric:: Arguments

.. option:: CONFIG_PATH

Required argument

variant#

Sequence variation analyses

.. program:: smftools experiment variant .. rubric:: Usage

.. code-block:: shell

smftools experiment variant [OPTIONS] CONFIG_PATH

.. rubric:: Arguments

.. option:: CONFIG_PATH

Required argument

project#

Register experiments into a project and query/analyze across them.

.. program:: smftools project .. rubric:: Usage

.. code-block:: shell

smftools project [OPTIONS] COMMAND [ARGS]...

add#

Register EXPERIMENT_DIR into PROJECT_DIR (by pointer; append-only).

EXPERIMENT_DIR may be a run directory (auto-discovers every pipeline stage found under it) or a single legacy monolithic .h5ad/.h5ad.gz file from before the partitioned-store pipeline (use --stage to name which stage it represents; the source file is only ever read, never modified).

.. program:: smftools project add .. rubric:: Usage

.. code-block:: shell

smftools project add [OPTIONS] PROJECT_DIR EXPERIMENT_DIR

.. rubric:: Options

.. option:: --id <experiment_id>

Explicit experiment id.

.. option:: --name

Friendly experiment name.

.. option:: --stage

Pipeline stage this registration represents (raw, preprocess, spatial, hmm, latent, variant, chimeric). Only meaningful when EXPERIMENT_DIR is a legacy monolithic .h5ad/.h5ad.gz file; otherwise every stage is auto-discovered and this is ignored. Omit to infer from the legacy file's name.

.. rubric:: Arguments

.. option:: PROJECT_DIR

Required argument

.. option:: EXPERIMENT_DIR

Required argument

export-fastq#

Write one FASTQ per barcode of QC-passed reads, across every registered experiment.

Example:

smftools project export-fastq ./my_project --outdir ./fastqs

.. program:: smftools project export-fastq .. rubric:: Usage

.. code-block:: shell

smftools project export-fastq [OPTIONS] PROJECT_DIR

.. rubric:: Options

.. option:: -o, --outdir

**Required** Output directory for FASTQ files + manifest CSV.

.. option:: --experiments

Comma-separated experiment ids to include (default: all active).

.. option:: --allow-unfiltered

Write all reads when no QC-passed read set is available, instead of raising/skipping.

.. option:: --no-gzip

Write plain .fastq instead of .fastq.gz.

.. rubric:: Arguments

.. option:: PROJECT_DIR

Required argument

init#

Initialize a project directory + registry, plus starter docs/dirs.

Creates registry.json, sets/, project_scripts/, project_outputs/, and starter README.md/AGENTS.md/CLAUDE.md/PLAN.md/project.yaml files. Safe to re-run -- only ever fills in what's missing, never overwrites existing files.

.. program:: smftools project init .. rubric:: Usage

.. code-block:: shell

smftools project init [OPTIONS] PROJECT_DIR

.. rubric:: Options

.. option:: --name

Project name used in scaffolded docs (default: directory name).

.. rubric:: Arguments

.. option:: PROJECT_DIR

Required argument

list#

List registered experiments and harmonized references.

.. program:: smftools project list .. rubric:: Usage

.. code-block:: shell

smftools project list [OPTIONS] PROJECT_DIR

.. rubric:: Arguments

.. option:: PROJECT_DIR

Required argument

materialize#

Pool CANONICAL_REFERENCE across matching experiments into one AnnData.

Prefer --layers and/or --start/--end: pooling all layers at full locus across many experiments builds very large objects. Refused over ~8 GiB unless --allow-large.

.. program:: smftools project materialize .. rubric:: Usage

.. code-block:: shell

smftools project materialize [OPTIONS] PROJECT_DIR CANONICAL_REFERENCE

.. rubric:: Options

.. option:: -o, --output

**Required** Output .h5ad(.gz).

.. option:: --set <set_name>

Restrict to a named experiment set.

.. option:: --modality

Restrict to a modality.

.. option:: --stage

Pipeline stage to materialize per experiment (raw/preprocess/spatial/hmm/latent/variant/chimeric). Default: most-derived stage available per experiment, since a later stage already carries forward earlier stages' data.

.. option:: --start

Genomic window start (with --end).

.. option:: --end

Genomic window end (with --start).

.. option:: --layers

Comma-separated layer subset to pool (e.g. 'C_site_binary'). Strongly recommended for cross-experiment pools -- the default pools every layer at full locus, which builds enormous objects. Use '' for X only (no layers).

.. option:: --read-metrics

Also attach spatial-stage per-read outputs (autocorrelation, Lomb-Scargle) when available.

.. option:: --allow-large

Bypass the ~8 GiB pooled-object size guardrail. Without it, a pool that would exceed the limit is refused with guidance to narrow it (--layers/--start/--end).

.. rubric:: Arguments

.. option:: PROJECT_DIR

Required argument

.. option:: CANONICAL_REFERENCE

Required argument

remove#

Mark an experiment inactive in the project.

.. program:: smftools project remove .. rubric:: Usage

.. code-block:: shell

smftools project remove [OPTIONS] PROJECT_DIR EXPERIMENT_ID

.. rubric:: Arguments

.. option:: PROJECT_DIR

Required argument

.. option:: EXPERIMENT_ID

Required argument

sample-store-list#

List per-sample-store partitions (Reference_strand x sample) cataloged by project add.

.. program:: smftools project sample-store-list .. rubric:: Usage

.. code-block:: shell

smftools project sample-store-list [OPTIONS] PROJECT_DIR

.. rubric:: Options

.. option:: --experiment-id <experiment_id>

Restrict to one experiment.

.. rubric:: Arguments

.. option:: PROJECT_DIR

Required argument

subsample-pod5#

Subsample POD5 file(s) by read ID list or random sampling.

.. program:: smftools subsample-pod5 .. rubric:: Usage

.. code-block:: shell

smftools subsample-pod5 [OPTIONS] POD5_PATH

.. rubric:: Options

.. option:: -r, --read-names <read_names>

Text file with one read_id per line.

.. option:: -n, --n-reads <n_reads>

Randomly subsample N reads.

.. option:: -o, --outdir

**Required** Output directory for subsampled POD5.

.. rubric:: Arguments

.. option:: POD5_PATH

Required argument

Command-line interface

Contents

Command-line interface#

smftools#

experiment#

batch#

chimeric#

concatenate#

export-fastq#

full#

hmm#

latent#

load#

plot-current#

preprocess#

raw#

spatial#

variant#

project#

add#

export-fastq#

init#

list#

materialize#

remove#

sample-store-list#

subsample-pod5#