CLI Reference

The CLI has four subcommands:

• enrich: one query set against many target sets;
• matrix: many query sets against many target sets;
• run: YAML-configured enrich or matrix.
• compare: threshold-crossing diff between two result tables.

enrich

genesets-rs enrich \
  --annotations gene_terms.tsv \
  --terms terms.tsv \
  --closure closure.tsv \
  --sample sample.txt \
  --background background.txt \
  --output results.tsv

Use --target-sets instead of --annotations for flat libraries:

genesets-rs enrich \
  --target-sets library.gmt \
  --target-format gmt \
  --sample sample.txt

Useful options:

• --sample-format: auto, list, pairwise, gene-term, gmt, gmx, gmx-desc;
• --sample-set: select one set from a multi-set sample file;
• --min-overlap: suppress rows below an overlap count;
• --max-p-value: suppress rows above a raw p-value cutoff;
• --max-p-adjust: suppress rows above an adjusted p-value cutoff;
• --correction: bonferroni or none;
• --output-format: tsv, parquet, or null; parquet requires --output, and null is useful for compute-only profiling;
• --overlap-genes: include overlapping gene IDs and names;
• --threads: set Rayon worker count.

matrix

genesets-rs matrix \
  --annotations gene_terms.tsv \
  --terms terms.tsv \
  --closure closure.tsv \
  --queries queries.gmx \
  --query-format gmx \
  --background background.txt

Use targets as queries for term-vs-term runs:

genesets-rs matrix \
  --annotations gene_terms.tsv \
  --closure closure.tsv \
  --queries-from-targets

run

mode: enrich
ontology:
  terms: terms.tsv
  closure: closure.tsv
  annotations: gene_terms.tsv
input:
  sample: sample.txt
  sample_format: list
  sample_name: sample
background:
  file: background.txt
overlap_genes: true
max_p_adjust: 0.05
output_format: tsv

Run it:

genesets-rs run examples/enrich.yaml

Relative paths in YAML are resolved from the config file’s directory. Relative paths passed directly as CLI arguments are resolved from the current working directory.

For mass evals, write Parquet and inspect it with DuckDB:

genesets-rs matrix ... --output-format parquet --output results.parquet
duckdb -c "SELECT * FROM 'results.parquet' WHERE p_adjust_bonferroni <= 0.05"

mgsa

Bayesian model-based gene set analysis. It takes the same target and sample options as enrich. Every set in a multi-set sample file is analyzed independently unless --sample-set picks one.

genesets-rs mgsa \
  --annotations gene_terms.tsv \
  --terms terms.tsv \
  --closure closure.tsv \
  --sample study_genes.txt \
  --background population_genes.txt \
  --min-posterior 0.5 \
  --summary-output mgsa-summary.yaml

Output columns: query_id, query_name, target_id, target_name, posterior, overlap, query_size, target_size, background_size, p_value (term-for-term, for comparison), equivalent_ids, and with --overlap-genes, overlap_genes and overlap_gene_names. Rows are sorted by posterior, highest first.

Only TSV (or null) output is supported. See Statistics for the model.

gsea

Preranked gene set enrichment analysis. It takes the same target options as enrich, but a scored gene list instead of a sample set and background: the ranking is the universe, so every ranked gene counts whether or not it is annotated, and target sets are restricted to ranked genes.

genesets-rs gsea \
  --annotations gene_terms.tsv \
  --terms terms.tsv \
  --closure closure.tsv \
  --ranks contrast.rnk \
  --max-p-adjust 0.05 \
  --leading-edge-genes

--ranks accepts two columns (gene, score), as in a GSEA .rnk file, or three (ranking_id, gene, score) to run several rankings at once; each is analyzed and adjusted independently. A first row with a non-numeric score is treated as a header. Duplicate genes and non-finite scores are errors. Like every table input, it may be gzip-compressed (detected from the file’s contents, not its extension), as the curated curation/rankings/*.rnk.gz are.

--statistic ks (the default) is the GSEA running sum; --statistic wilcoxon is a Wilcoxon rank-sum (Mann-Whitney U) test of members against non-members. --algorithm elim and --algorithm weight01 use the ontology graph to keep redundant ancestors from riding on a child’s signal; both need --closure.

Output columns: query_id (the ranking), query_name, target_id, target_name, es, nes, p_value, p_adjust, set_size (members scored), eliminated (ranked members removed by elim or weight01), target_size, ranked_size, leading_edge_size, peak_rank, and with --leading-edge-genes, leading_edge_genes and leading_edge_gene_names.

Both es columns run from -1 to 1 and are positive toward high scores. peak_rank is the 1-based rank of the leading edge’s boundary gene: its last gene for positive scores, its first for negative ones. Rows are sorted by p-value, then by |NES|. The p_adjust column means compare can diff two GSEA runs directly.

Only TSV (or null) output is supported. See Statistics for the method.

compare

Compare two enrichment result tables by (query_id, target_id) and classify adjusted p-value threshold crossings:

genesets-rs compare \
  --left go-2021.parquet \
  --right go-2026.parquet \
  --p-adjust-cutoff 0.05 \
  --output-format parquet \
  --output go-2021-vs-2026.diff.parquet \
  --metadata-output go-2021-vs-2026.diff.yaml

Input formats are inferred from .tsv, .txt, .parquet, or .pq, or can be set explicitly with --left-format and --right-format. TSV output goes to stdout by default. Parquet output requires --output.

The default output includes:

• lost_significant: significant on the left, not significant on the right;
• gained_significant: not significant on the left, significant on the right;
• shared_significant: significant on both sides.

Use --crossings-only to emit only gained/lost rows.

Workflow CLI

The separate genesets-workflows command is the convenience layer for configured source prep and reports. It calls the Rust CLI for batch compute and then writes Parquet plus metadata:

uv run --project python/genesets-workflows genesets-workflows doctor
genesets-workflows go-impact evals/go_impact_5y_expression500.yaml
genesets-workflows reactome-flat

go-impact YAML can apply query_sets.include_regex and query_sets.exclude_regex before selecting query sets from a cached snapshot. The regexes match query id, name, description, source class, stratum, and search query metadata. For example, exclude GO-derived MSigDB query sets from a GO target analysis:

query_sets:
  source_dir: expression_like/generated/msigdb_diverse_5k
  limit: 4313
  exclude_regex:
    - "^(GOBP|GOCC|GOMF)_"

For interactive review of an existing report bundle, use the optional web explorer dependencies:

uv run --project python/genesets-workflows --extra explorer \
  genesets-workflows explore notebooks/generated/go_iba_impact_expression5000_diverse

Use genesets-rs for normalized single jobs. Use genesets-workflows when the task needs downloads, evidence filters, release metadata, multiple Rust runs, DuckDB summaries, notebook/report artifacts, or browser-based result triage.