togovar_search_variant
Find human genomic variants by gene, disease, chromosome, or frequency, with population allele frequencies, clinical significance, and pathogenicity predictions.
Instructions
Search TogoVar for human genome variants with population frequencies.
TogoVar integrates allele frequencies from gnomAD, ToMMo (Japanese), NCBN, GEM-J, JGA, and BioBank Japan, plus ClinVar + MGeND clinical significance and SIFT/PolyPhen/AlphaMissense predictions — data with no SPARQL counterpart elsewhere in TogoMCP.
All filters are optional and combined with AND. Supply zero filters to browse; but scope tightly — the database holds ~1 billion variants.
COUNTS: total is the size of the whole REST backend (1,097,708,150) and is
constant across queries; filtered is the count matching your filters. Note
the REST backend is LARGER than TogoMCP's togovar SPARQL graph (~2.8x: the
SPARQL side is the annotated subset, 390,725,782), so REST counts will not
match SPARQL COUNT(*) — they measure different sets.
PAGING CAP: the API allows offset + limit <= 10,000 and returns HTTP 400
beyond it, so a result set larger than 10,000 cannot be fully paged. Narrow the
filters until filtered <= 10,000 to enumerate one exhaustively.
STATISTICS SCOPE (stat=True): all facets are scoped to the filtered set, but
they count at different granularities. type counts per variant (sums to
filtered); dataset per variant-cohort; consequence per
variant-TRANSCRIPT (VEP fan-out, so its sum is filtered x transcripts per
variant — ~5-6 for a typical gene, 400+ in transcript-dense loci like
BRCA1); significance per variant-condition record. So consequence/
significance sums exceed filtered and must NOT be summed against it (they
are not per-variant counts). See statistics_caveats for the per-facet rule.
ROUND-TRIP TO SPARQL: gate on tgv_id. It is NULL for variants that exist in
the REST backend but NOT in the (smaller) SPARQL subset — including some
ClinVar-Pathogenic ones. variant_iri is emitted ONLY when tgv_id is
non-null, so a non-null variant_iri is safe to query in the togovar SPARQL
graph; a row with tgv_id: null has no SPARQL record at all, and REST is the
only source for it.
TWO-STEP WORKFLOW for gene/disease filters:
1. search_gene("ALDH2") -> hgnc_id -> pass as gene_hgnc_id.
2. search_disease("breast cancer") -> mondo_id -> pass as disease_id.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| stat | No | If True, also return match counts (`total`, `filtered`) and the aggregate breakdown (counts by dataset, type, consequence, significance). REQUIRED to get a count — e.g. "how many variants match". Left False by default because computing the aggregation is the slow part of the query; use stat=False when you only need rows. See STATISTICS SCOPE above — every facet is scoped to the filtered set, but they count at different granularities, so only `type` sums to `filtered`. | |
| stop | No | ||
| limit | No | Max variant rows to return, in [0, 1000]. Default 100. | |
| start | No | ||
| offset | No | Rows to skip (pagination). Default 0. | |
| tgv_id | No | TogoVar variant ID(s), e.g. "tgv16331". | |
| dataset | No | Frequency panel for a frequency filter, e.g. "gnomad_genomes", "gnomad_exomes", "tommo", "ncbn", "gem_j_wga", "jga_wgs", "jga_wes", "jga_snp", "bbj_riken". Sub-populations allowed (e.g. "gnomad_genomes.eas", "ncbn.jpn"). | |
| position | No | Single 1-based site (mutually exclusive with start/stop). | |
| chromosome | No | "1"-"22", "X", "Y", "MT". Required for a positional filter. | |
| disease_id | No | MONDO ID(s) (e.g. "MONDO_0007254") or MedGen CUI(s) from `search_disease`. | |
| consequence | No | SO consequence term or label, e.g. "missense_variant", "stop_gained", "frameshift_variant". | |
| gene_hgnc_id | No | HGNC ID (integer) from `search_gene` (NOT a symbol). | |
| variant_type | No | "snv", "ins", "del", "indel", "sub". | |
| max_frequency | No | ||
| min_frequency | No | ||
| disease_source | No | Restrict disease link source(s): "clinvar", "mgend". | |
| include_transcripts | No | If True, add a `transcripts` list to each row with the per-transcript VEP annotation the REST backend already carries: transcript/gene IDs, SO consequence(+labels), HGVS c/p/g, and per-transcript SIFT/PolyPhen/AlphaMissense. Default False — a variant in a transcript-dense locus (e.g. BRCA1) can carry 400+ transcript annotations, which would dominate the response. Note this means HGVS and per-transcript predictions do NOT require a SPARQL round-trip. | |
| significance_source | No | Restrict significance source(s): "clinvar", "mgend". | |
| include_full_alleles | No | If True, return full REF/ALT sequences even for large structural variants. Default False summarizes alleles over ~50 bp as "<head>…(<n> bp)" to keep the response inline-readable; `ref_length`/`alt_length` always give the true lengths. | |
| clinical_significance | No | e.g. "pathogenic", "likely_pathogenic", "benign", "uncertain_significance", "risk_factor". |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |