just_dna_enricher.cli.pass_commands¶
just_dna_enricher.cli.pass_commands ¶
The enrichment passes: enrich, frequencies, gene-metrics, dosage, gene-validity, gwas,
assertions, literature, pgx and ld-pairs (RM260 split this out of the former single-file cli.py).
enrich_ ¶
enrich_(
spec_dir: Path = typer.Argument(
...,
exists=True,
file_okay=False,
help="Module spec directory",
),
strict: bool = typer.Option(
False,
"--strict/--best-effort",
help="Fail unless every variant resolves.",
),
offline: bool = typer.Option(
False,
"--offline",
help="Cache-only: never touch the network.",
),
ensembl_cache: Path | None = typer.Option(
None,
"--ensembl-cache",
help="Explicit Ensembl cache dir/.duckdb.",
),
clinvar_cache: Path | None = typer.Option(
None,
"--clinvar-cache",
help="Explicit ClinVar snapshot dir.",
),
clinvar_gkm_cache: Path | None = typer.Option(
None,
"--clinvar-gkm-cache",
help="Built ClinVar-GKM snapshot dir — a second witness for where each placed rsID sits (RM267). Omit it and $JUST_DNA_CLINVAR_GKM_CACHE is read; never downloaded by this command.",
),
pubmind_cache: Path | None = typer.Option(
None,
"--pubmind-cache",
help="Built PubMind snapshot dir (from `pubmind build`) — the second authority in the clinical-significance concordance check. Omit it and $JUST_DNA_PUBMIND_CACHE is read; with neither, PubMind's leg reads unchecked rather than agreement.",
),
use_clinvar: bool = typer.Option(
True,
"--clinvar/--no-clinvar",
help="Use the ClinVar link (after the Ensembl cache).",
),
use_gnomad: bool = typer.Option(
True,
"--gnomad/--no-gnomad",
help="Use the gnomAD link (last, after live Ensembl).",
),
mint_vrs: bool = typer.Option(
True,
"--vrs/--no-vrs",
help="Mint GA4GH VRS allele ids onto resolved rows.",
),
verify_ref: bool = typer.Option(
True,
"--verify-ref/--no-verify-ref",
help="Check each authored ref against the reference sequence and report disagreements.",
),
verify_clinsig: bool = typer.Option(
True,
"--verify-clinsig/--no-verify-clinsig",
help="Check each authored clin_sig against the ClinVar snapshot's own (warns, never fails).",
),
verify_rsids: bool = typer.Option(
True,
"--verify-rsids/--no-verify-rsids",
help="Check each authored rsID against dbSNP for merges/withdrawals (online only).",
),
verify_datasets: bool = typer.Option(
True,
"--verify-datasets/--no-verify-datasets",
help="Check each release recorded in sources.csv against the one that source publishes now, and report the gap. One request per source, and the cheap question to put before --rederive: it tells you whether re-asking every subject is worth the run.",
),
keep_par_twin: bool = typer.Option(
False,
"--keep-par-twin",
help="Record both contigs of a pseudoautosomal locus. Default keeps only the X spelling, which is the one every annotation source uses and the only one a hard-masked GRCh38 analysis set can match.",
),
rederive: bool = typer.Option(
False,
"--rederive",
help="Re-ask every source about every subject, including the ones already recorded, and report which of them changed value. An ordinary run gap-fills and never re-asks, so a source that quietly revised an answer moves nothing you could notice.",
),
keep_staging: bool = typer.Option(
False,
"--keep-staging",
help="Leave the staged answers beside resolution.csv after a successful run. They are removed by default; a killed run leaves them either way, and the next run resumes from them.",
),
) -> None
Resolve a spec's variants into resolution.csv beside the spec. Exit 1 in strict mode if unresolved.
Source code in enricher/src/just_dna_enricher/cli/pass_commands.py
31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 | |
frequencies_ ¶
frequencies_(
spec_dir: Path = typer.Argument(
...,
exists=True,
file_okay=False,
help="Module spec directory",
),
strict: bool = typer.Option(
False,
"--strict/--best-effort",
help="Fail unless every resolved allele has a frequency.",
),
offline: bool = typer.Option(
False,
"--offline",
help="No-op with a warning: gnomAD frequency has no offline snapshot.",
),
populations: str | None = typer.Option(
None,
"--populations",
help="Comma-separated ancestry groups to keep (e.g. 'global' for one row per allele). Default: all.",
),
dataset: str | None = typer.Option(
None,
"--dataset",
help="Override the dataset label recorded on each row.",
),
) -> None
Fill frequencies.csv from the coordinates already in resolution.csv (pass 2, online only).
Source code in enricher/src/just_dna_enricher/cli/pass_commands.py
gene_metrics_ ¶
gene_metrics_(
spec_dir: Path = typer.Argument(
...,
exists=True,
file_okay=False,
help="Module spec directory",
),
strict: bool = typer.Option(
False,
"--strict/--best-effort",
help="Fail unless every gene has constraint metrics.",
),
offline: bool = typer.Option(
False,
"--offline",
help="Snapshot only: never touch the network.",
),
constraint_cache: Path | None = typer.Option(
None,
"--constraint-cache",
help="Explicit gnomAD constraint snapshot dir.",
),
) -> None
Fill gene_metrics.csv for the genes variants.csv mentions (pass 3, snapshot then live API).
With no local snapshot the published one (gnomAD 4.1.2) is downloaded from HuggingFace first, exactly
as enrich provisions the Ensembl and ClinVar snapshots — --offline is what turns that off, and then
the pass is snapshot-only. Reaching the live API instead means numbers that name no release, labelled
gnomad_api_constraint; provisioning is what keeps a plain install on a named release.
Source code in enricher/src/just_dna_enricher/cli/pass_commands.py
dosage_ ¶
dosage_(
spec_dir: Path = typer.Argument(
...,
exists=True,
file_okay=False,
help="Module spec directory",
),
strict: bool = typer.Option(
False,
"--strict/--best-effort",
help="Fail unless every gene is ClinGen-curated.",
),
offline: bool = typer.Option(
False,
"--offline",
help="No-op with a warning: ClinGen's curation list is a live download with no snapshot.",
),
url: str = typer.Option(
DEFAULT_CLINGEN_URL,
"--url",
help="ClinGen gene-curation list URL.",
),
use: str = typer.Option(
"unstated",
"--use",
help="Declared use: unstated | non-commercial | commercial. ClinGen is CC0, so no declaration is refused here — it is recorded into sources.csv beside the rows it justifies.",
),
) -> None
Add ClinGen dosage-sensitivity rows to gene_metrics.csv (haploinsufficiency/triplosensitivity).
Source code in enricher/src/just_dna_enricher/cli/pass_commands.py
gene_validity_ ¶
gene_validity_(
spec_dir: Path = typer.Argument(
...,
exists=True,
file_okay=False,
help="Module spec directory",
),
source: str = typer.Option(
CLINGEN_VALIDITY_SOURCE,
"--source",
help="Which submitter to read: clingen (expert panels) or gencc (an aggregate of nineteen).",
),
strict: bool = typer.Option(
False,
"--strict/--best-effort",
help="Fail unless every gene carries a curated assertion.",
),
offline: bool = typer.Option(
False,
"--offline",
help="No-op with a warning: neither ClinGen nor GenCC publishes an offline snapshot.",
),
url: str | None = typer.Option(
None,
"--url",
help="Override the submitter's export URL.",
),
) -> None
Fill gene_validity.csv with curated gene-disease assertions for the genes variants.csv names.
One row per (gene, disease, mode of inheritance, submitter) — the source's own grain. Mode of
inheritance is in the key because 59 ClinGen (gene, disease) pairs carry two curations that differ
only there, and submitter is in it because GenCC publishes the disagreement between submitters,
which is the thing it exists to publish.
Source code in enricher/src/just_dna_enricher/cli/pass_commands.py
gwas_ ¶
gwas_(
spec_dir: Path = typer.Argument(
...,
exists=True,
file_okay=False,
help="Module spec directory",
),
strict: bool = typer.Option(
False,
"--strict/--best-effort",
help="Severity ladder for findings; see the pass docstring.",
),
offline: bool = typer.Option(
False,
"--offline",
help="No-op with a warning: this pass reads the REST API, not a snapshot.",
),
use: str = typer.Option(
"unstated",
"--use",
help="Declared use recorded on the licence row: unstated|non-commercial|commercial.",
),
study_facts: bool = typer.Option(
True,
"--study-facts/--no-study-facts",
help="Fetch each distinct study's ancestry, the one fact the Catalog's v2 API keeps behind a request: 1 request per study, measured at 190 requests in all for one real module. pmid, study accession and trait come with the association and are filled either way. Off drops ancestry PERMANENTLY for the rows it writes: the merge is keyed on association_id, so a later run with study facts on skips those rows rather than back-filling. Delete gwas_effects.csv to re-derive it.",
),
) -> None
Fill gwas_effects.csv with the GWAS Catalog's published effect sizes for this module's rsIDs.
One row per published association, not per variant — a well-studied variant carries dozens across
different traits and papers. It does NOT fill weight: an authored weight is the author's model
of the finding, and no tool writes one. The two sit side by side and a consumer picks.
Reads effect_unit verbatim, including the Catalog's uninformative "unit", because a beta whose
scale is unknown must not look like one whose scale is shared. An association the Catalog
published without establishing which allele carries the effect keeps a null effect_allele and is
counted in the manifest, never dropped.
Source code in enricher/src/just_dna_enricher/cli/pass_commands.py
assertions_ ¶
assertions_(
spec_dir: Path = typer.Argument(
...,
exists=True,
file_okay=False,
help="Module spec directory",
),
strict: bool = typer.Option(
False,
"--strict/--best-effort",
help="Fail unless every resolved allele has a ClinVar record.",
),
offline: bool = typer.Option(
False,
"--offline",
help="Snapshot only: never touch the network.",
),
clinvar_cache: Path | None = typer.Option(
None,
"--clinvar-cache",
help="Explicit ClinVar snapshot directory.",
),
) -> None
Fill clinical_assertions.csv from the coordinates already in resolution.csv.
Records what ClinVar says about each allele and how much review sits behind it — the star rating a compiled module previously discarded, so a one-star single submission and a practice guideline stopped being the same claim. Offline-capable: with a snapshot provisioned this pass never touches the network, and with none reachable it is a no-op rather than a failure.
It records; it does not adjudicate. Whether the module's own clin_sig agrees with ClinVar's is the
enrich cross-check's question, and that one warns in both modes on purpose.
Source code in enricher/src/just_dna_enricher/cli/pass_commands.py
literature_ ¶
literature_(
spec_dir: Path = typer.Argument(
...,
exists=True,
file_okay=False,
help="Module spec directory",
),
strict: bool = typer.Option(
False,
"--strict/--best-effort",
help="Fail if a cited PMID does not resolve.",
),
offline: bool = typer.Option(
False,
"--offline",
help="No-op with a warning: there is no offline PubMed snapshot.",
),
check_fulltext: bool = typer.Option(
True,
"--fulltext/--no-fulltext",
help="Also match provenance quotes against fulltext, falling back to the abstract.",
),
check_doi: bool = typer.Option(
True,
"--doi/--no-doi",
help="Also confirm the authored DOI resolves in Crossref (covers preprints/books).",
),
) -> None
Fill literature.csv from a module's citations (pass 4, online only).
studies.csv is one citation site of several: a pmid on a binning row grounds the threshold it
sits on, and one on a pharm_variants.csv row grounds that row's own drug and genotype claim. The
pass reads every site, so a module citing only from those tables is enriched rather than refused.
Source code in enricher/src/just_dna_enricher/cli/pass_commands.py
540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 | |
pgx_ ¶
pgx_(
spec_dir: Path = typer.Argument(
...,
exists=True,
file_okay=False,
help="Module spec directory",
),
strict: bool = typer.Option(
False,
"--strict/--best-effort",
help="Fail on an allele-function discrepancy.",
),
offline: bool = typer.Option(
False,
"--offline",
help="Snapshots only: never reach PharmVar or CPIC live.",
),
use: str = typer.Option(
"unstated",
"--use",
help="Declared use: unstated | non-commercial | commercial. Sources that forbid sale are SKIPPED when unstated and REFUSED when commercial.",
),
use_pharmvar: bool = typer.Option(
True,
"--pharmvar/--no-pharmvar",
help="Consult PharmVar (needs PHARMVAR_API_KEY).",
),
use_cpic: bool = typer.Option(
True,
"--cpic/--no-cpic",
help="Consult CPIC (open, no key).",
),
cpic_cache: Path | None = typer.Option(
None,
"--cpic-cache",
help="Explicit CPIC snapshot dir.",
),
pharmvar_cache: Path | None = typer.Option(
None,
"--pharmvar-cache",
help="Explicit PharmVar snapshot dir.",
),
) -> None
Cross-check star-allele tables against PharmVar/CPIC and record terms into sources.csv.
Snapshot first, live second (RM38). A built snapshot serves the check without egress and without
spending a shared per-IP budget; --offline says snapshot-only, and a leg with neither is skipped
with a reason rather than silently passing.
Source code in enricher/src/just_dna_enricher/cli/pass_commands.py
ld_pairs_ ¶
ld_pairs_(
spec_dir: Path = typer.Argument(
...,
exists=True,
file_okay=False,
help="Module spec directory",
),
offline: bool = typer.Option(
False,
"--offline",
help="Ask nothing and write nothing: there is no LD snapshot (online only).",
),
) -> None
Fill ld_pairs.csv: r² between each study's proxy_rsid and its lead, in the study's own ancestry.
Asks Ensembl REST's pairwise LD in the 1000 Genomes phase 3 superpopulation the study names. A study naming several superpopulations, or none, gets its row with r² withheld and the reason; an empty answer is withheld too (below the reference's floor, or not in LD), never written as r² = 0.