This repository is a monorepo for gene set enrichment, eval exploration, and curated gene set interpretation.
genesets-rs: a fast Rust CLI and library for ontology-aware and flat gene set enrichment.genesets-workflows: a Python workflow package for source preparation, configured evals, reports, curation helpers, and local browser tools.- Web explorer: a local, not-yet-deployed UI for browsing generated eval report bundles.
curation/: a LinkML-validated corpus of curated GO interpretations for non-GO gene sets.- Metabolite enrichment:
genesets-workflows prepare-chem2goturns GO-plus chemical axioms, Rhea and (optionally) enzyme annotations into chemical-to-GO tables the Rust engine runs unchanged; seedocs/src/metabolite-enrichment.md.
The Rust engine remains ontology-neutral. GO is represented as ordinary term IDs, a human-readable term-name table, a precomputed child-to-ancestor closure table, and gene-to-term annotations. If no closure is supplied, the target library is treated as flat.
cargo build --releaseFor day-to-day use on one machine, install the CLI from this checkout:
cargo install --path /path/to/genesets-rs --forceCargo installs the binary as ~/.cargo/bin/genesets-rs. Once that directory is
on your PATH, the command works from any directory:
genesets-rs --help
genesets-rs run /path/to/genesets-rs/examples/enrich.yamlAfter changing the Rust code, rerun the same cargo install --path ... --force
command to refresh the installed binary.
The repository includes an mdBook site for GitHub Pages-style documentation:
cargo install mdbook
mdbook serveThe book source lives in docs/src. It is organized around the project
surfaces: compute engine, reports/evals, local web explorer, curated
interpretation corpus, and reference material.
The Rust CLI is the fast enrichment kernel. Repeatable source prep and reports
live in a Python package under python/genesets-workflows.
Run the workflow CLI from this checkout:
uv run --project python/genesets-workflows genesets-workflows doctorOr install it editable:
python3 -m pip install -e python/genesets-workflows
genesets-workflows doctorThe package currently exposes:
genesets-workflows go-impact evals/go_impact_5y_expression500.yaml
genesets-workflows reactome-flat
genesets-workflows prepare-reactome-flat --out-dir evals/reactome_flat/generated/current
genesets-workflows fetch-mygeneset --query 'GSE*' --source-filter msigdb --limit 500 --out-dir evals/expression_like/generated/msigdb_gse_500
genesets-workflows explore notebooks/generated/go_iba_impact_expression5000_diverse
genesets-workflows curate --helpThe older script commands for these workflows remain as compatibility wrappers around the package; older eval helpers will be migrated incrementally.
The intended boundary is:
Python workflow prep -> normalized tables/YAML plan -> Rust batch command
-> Parquet outputs -> DuckDB/report summaries
The local explorer browses existing workflow report bundles. It does not run
enrichment itself; it reads summary.yaml, query metadata, query genes, and
Parquet result/diff files.
Open the default local bundles:
just browserOpen one bundle explicitly:
uv run --project python/genesets-workflows --extra explorer \
genesets-workflows explore notebooks/generated/go_iba_impact_expression5000_diverse --openThe curated gene set browser should be built as a separate static/generated
view over curation/genesets/*.yaml, not as part of the Rust compute engine.
All simple tables may be TSV or CSV. Comment lines beginning with # are ignored.
- Terms:
term_curie,name - Closure:
child_term_curie,ancestor_term_curie; reflexive rows are expected but the loader also adds self-annotation defensively - Ontology annotations:
gene_curie,term_curie - Gene names:
gene_curie,symbol - Background: one
gene_curieper row
Gene set inputs can be:
list: one gene per row, used as a single setpairwise:set_id,gene_curiegene-term:gene_curie,set_idgmt:set_id,description,gene...gmx: simple GMX, first row set IDs and remaining rows genesgmx-desc: standard GMX with a description row after the set IDs
Single sample against ontology targets:
genesets-rs enrich \
--annotations examples/gene_terms.tsv \
--terms examples/terms.tsv \
--closure examples/closure.tsv \
--sample examples/sample.txt \
--background examples/background.txt \
--overlap-genesAll ontology terms against themselves:
genesets-rs matrix \
--annotations examples/gene_terms.tsv \
--terms examples/terms.tsv \
--closure examples/closure.tsv \
--queries-from-targets \
--background examples/background.txtFlat library enrichment, such as MSigDB-style GMT:
genesets-rs matrix \
--target-sets path/to/library.gmt \
--target-format gmt \
--queries path/to/samples.gmx \
--query-format gmx \
--background path/to/background.txt \
--output enrichments.tsvBayesian model-based gene set analysis (MGSA), which explains the query with a few jointly active terms instead of testing each term on its own:
genesets-rs mgsa \
--annotations examples/gene_terms.tsv \
--terms examples/terms.tsv \
--closure examples/closure.tsv \
--sample examples/sample.txt \
--background examples/background.txtThe same MGSA sampler is available in Python as genesets.mgsa(...) from
python/genesets-py (PyO3 bindings; see its README for install).
Preranked gene set enrichment analysis (GSEA) over a scored gene list instead of a thresholded set. Every measured gene keeps its score (fold change, signed -log10 p-value, t-statistic), and each term gets an enrichment score for sitting at the top or bottom of the ranking:
genesets-rs gsea \
--annotations examples/gene_terms.tsv \
--terms examples/terms.tsv \
--closure examples/closure.tsv \
--ranks examples/ranks.rnk \
--min-size 1 \
--leading-edge-genes--ranks is a two-column gene, score table (a GSEA .rnk file) or a
three-column ranking_id, gene, score table for many contrasts in one run;
like every table input, it may be gzip-compressed.
--statistic wilcoxon swaps the GSEA running sum for a Wilcoxon rank-sum test,
and --algorithm elim or weight01 uses the ontology graph so that ancestors
do not ride on a child's signal (see docs/src/statistics.md).
YAML configuration:
genesets-rs run examples/enrich.yamlRelative paths inside YAML configs are resolved from the config file's directory. Relative paths passed directly on the command line are resolved from the current working directory.
Output is TSV with:
query_id, query_name, target_id, target_name, overlap, query_size, target_size, background_size, p_value, and adjusted p-value.
With --overlap-genes, the CLI also emits overlap_genes and overlap_gene_names.
mgsa output replaces the adjusted p-value with posterior (the probability
that the term is active), keeps the term-for-term p_value for comparison, and
adds equivalent_ids for terms with identical genes in the background.
gsea output has es, nes, p_value, and p_adjust (GSEA FDR q-value for
KS, Benjamini-Hochberg for Wilcoxon), plus set_size (members scored),
eliminated (members removed by elim or weight01), target_size, ranked_size,
leading_edge_size, and peak_rank; --leading-edge-genes adds the
leading-edge gene ids and names.
- Terms and query sets are represented as dense
Vec<u64>bitsets over a shared gene universe. - Ontology closure is applied during indexing: a gene annotated to a child term is set on every ancestor term.
- Default background is the union of target genes. A supplied background file overrides that and can include genes not annotated to any target.
- Matrix mode parallelizes over queries with Rayon. Output volume can dominate runtime for dense N x N jobs.
- Serialized reusable indexes for repeated GO version comparisons.
- Ontologizer-style parent-child, elim, and weight approaches (model-set MGSA is available as
genesets-rs mgsa). - Convenience wrappers for species/build metadata without baking those concerns into the core model.
- Test-data adapters around mygeneset.info and other public gene set sources.
The preferred real-data smoke panel is evals/expression20, a manifest of 20
human expression-derived MyGeneset.info/MSigDB signatures. Fetch a local GMT
snapshot with:
python3 scripts/fetch_mygeneset_eval.py \
--manifest evals/expression20/sets.tsv \
--out-dir evals/expression20/generatedGenerated eval files are intentionally separate from cargo test so ordinary CI stays deterministic.
Run the local overlap smoke:
genesets-rs run evals/expression20/config.yamlRun the 5-year GO impact report over 500 expression-derived signatures:
genesets-workflows go-impact evals/go_impact_5y_expression500.yamlThat report config runs the core matrix and compare commands, writes
Parquet outputs plus YAML/JSON metadata, and leaves notebook code to inspect
the generated artifacts rather than rebuild the workflow.
Run the same 500 expression-derived signatures against official Reactome pathways as a flat GMT target library:
genesets-workflows reactome-flatThe GO eval runner writes significance-focused TSVs by default:
python3 scripts/run_disease20_go_eval.py \
--manifest evals/expression20/sets.tsv \
--out-dir evals/expression20_vs_go/generated \
--eval-name expression20_vs_go \
--max-p-adjust 0.05Companion YAML metadata records the cutoff, source file digests, prep settings, row counts, and run timing.
curation/ holds expert GO-term interpretations of non-GO gene sets, validated
with LinkML term/reference validators and used as a precision/recall gold
standard. Each file records biological context, curated GO associations,
category, confidence, specificity, recovery status, enrichment stats, and
optional literature evidence.
See curation/README.md and the mdBook curation section.
curation/ holds expert GO-term interpretations of non-GO gene sets (MSigDB
single-cell, pathway, hallmark, and phenotype sets, plus literature
disease-activity and GWAS/CRISPR genetics sets), validated with LinkML
term/reference validators and an OAK obsolescence gate, and used as a
precision/recall gold standard for the enrichment tool. See curation/README.md
and evals/iba_vs_benchmark/README.md.
just curate-validate
just curate-report
Continuing this work: start from AGENTS.md, then the two runbook skills
in .claude/skills/ — curate-geneset (adding/reviewing an interpretation) and
evaluate-enrichment (scoring a method/evidence variant against the gold).