VarSage is a bioinformatics decision-support platform for interpretation of germline sequence variants. It is intended for exome or genome VCF/table outputs that have already passed through an upstream alignment, variant calling, and primary quality-control workflow. VarSage does not call variants from reads; it integrates existing variant calls with phenotype, inheritance, population, transcript, clinical-assertion, and computational evidence to produce a prioritization report.
The application is organized around three analytical contexts: Rare Disease - Singleton, carrier screening analysis, and Rare Disease - Trio. Across all contexts, VarSage treats the variant as a structured allele defined by chromosome, reference allele, alternate allele, selected sample genotype, and annotation fields. This deterministic coordinate model is deliberately kept separate from AI-generated summaries.
Clinical boundary: VarSage provides research and expert-review support. It does not establish a molecular diagnosis, does not issue a clinical laboratory classification, and does not replace orthogonal confirmation, segregation analysis, phase assessment, or disease-specific ACMG/AMP review.
Rare Disease - Singleton
Single-proband analysis that ranks candidate alleles by phenotype fit, molecular consequence, rarity, inheritance compatibility, quality, and provisional evidence.
Carrier Screening
Independent partner review followed by same-gene comparison for recessive reproductive-risk signals and scope-specific carrier findings.
Rare Disease - Trio
Proband-first prioritization followed by parental allele-state comparison for possible de novo, inherited, and compound-heterozygous models.
VarSage follows a layered interpretation architecture. First, submitted phenotypes and variants are normalized into controlled representations. Next, transcript and coordinate annotations are attached while preserving original source fields. The resulting candidate set is filtered for assay scope, quality, benign assertions, and population frequency. Finally, retained variants are ranked using phenotype similarity, inheritance compatibility, molecular consequence, rarity, clinical assertions, computational predictors, and provisional ACMG/AMP-oriented evidence.
The final report is not just a score table. It is an audit trail: which sample was analyzed, which file type was detected, which variants were removed, which databases matched, which HPO terms were used, which inheritance model was plausible, and which evidence remains incomplete. This is essential in clinical bioinformatics because the same numeric rank can arise from very different biological and evidentiary situations.
Rare Disease - Singleton
Use when an affected proband has WES/WGS variants and the primary question is phenotypic plausibility of candidate alleles.
Carrier screening
Use when two partners are assessed for heterozygous variants in the same recessive disease gene or in configured carrier scopes.
Rare Disease - Trio
Use when maternal and/or paternal variant files can inform de novo, inherited, or biallelic hypotheses in the proband.
The Rare Disease - Singleton workflow is a single-proband prioritization pipeline for suspected Mendelian disease. Its purpose is to reduce a large variant set to a biologically interpretable shortlist while preserving the evidentiary chain behind each retained candidate. The workflow explicitly distinguishes review priority from pathogenicity classification and separates variant-level evidence from case-level causality.
Case intake. VarSage records patient metadata, selected genome build, sample identifier, sex, age, expected inheritance, family history, consanguinity, present HPO terms, explicitly absent HPO terms, clinical narrative, optional BED scope, and per-case AI permissions.
Phenotype preparation. Manual HPO identifiers are used as high-confidence anchors. Free text is mapped to HPO by deterministic term and synonym matching, and optionally by AI extraction constrained to valid HPO terms supported by the submitted description.
Variant parsing and normalization. VCF, VCF.gz, TSV, CSV, and delimited text are converted into a common allele model. Chromosome labels, 1-based positions, reference and alternate alleles, genotype, zygosity, depth, genotype quality, gene, transcript, consequence, and source annotations are standardized.
Transcript and coordinate annotation. Existing VEP CSQ, ANN, INFO, FORMAT, and table annotations are preserved. Jannovar can add transcript consequences. Local databases are merged by exact allele identity to attach frequency, clinical assertion, rsID, predictor, splice, or laboratory-specific evidence fields.
Pre-ranking filtration. The candidate set is reduced using benign/likely benign assertions, population-frequency thresholds, depth, genotype quality, VCF FILTER status, and BED interval overlap. Rescue logic keeps selected rare high-impact or clinically asserted variants visible for expert review.
Phenotype-gene similarity. Candidate genes are compared with HPO-derived gene and disease profiles. Ontology ancestry is used to recognize specific-to-broad phenotype relationships while avoiding unsupported inference of co-symptoms.
Inheritance assessment. VarSage evaluates compatibility between genotype state, sex, expected inheritance, family history, known gene inheritance modes, and disease models such as autosomal dominant, autosomal recessive, X-linked, homozygous recessive, and possible compound heterozygosity.
Evidence scoring and ranking. Integrated ranking combines phenotype match, inheritance support, molecular severity, rarity, call quality, clinical assertions, predictors, and provisional ACMG/AMP evidence. The rank orders review priority, not diagnostic certainty.
Interpretation support. Reports include provisional evidence, candidate rationale, literature context where available, secondary-finding and important-heterozygous sections, missing evidence statements, and optional AI-assisted review.
Export and audit. Results are written as browser views and downloadable reports so each prioritization decision can be inspected, reproduced, and discussed in a multidisciplinary review setting.
Case decision spectrum
After ranking and optional synthesis, VarSage adds a cautious case-level decision spectrum. This summarizes whether the retained candidate set contains no positive candidate, an inconclusive candidate, a positive candidate requiring confirmation, or an externally confirmed cause. The decision is derived from structured evidence and report-review signals; it is not a molecular diagnosis.
The same evidence spectrum used in Rare Disease - Singleton result and report views. Green is the cautious no-positive-candidate end; red is reserved for expert and laboratory confirmation.
No positive candidate identified
Assigned when no retained candidate is available, or when the retained candidates do not contain pathogenic/likely-pathogenic or primary report-review evidence. This is not a statement that a genetic diagnosis is excluded.
Inconclusive candidate finding
Assigned when candidates remain important for review, but the current evidence is not strong enough for a cautious positive decision. The result should remain inconclusive or candidate-only until the uncertainty is resolved.
Positive candidate finding
Assigned when a prioritized candidate has a pathogenic/likely-pathogenic provisional classification, a matching ClinVar-like assertion, or a primary report-review signal. Expert review, orthogonal confirmation, and relevant segregation or phase checks are still required.
Confirmed cause
This is a reporting endpoint for human interpretation, not an automatic VarSage decision. The tool never assigns it; it requires qualified expert review and laboratory confirmation where appropriate.
How the decision is taken: VarSage starts from the ranked candidate set. When case synthesis supplies reportable or decision-making candidate IDs, the decision check is narrowed to those candidates; otherwise, all ranked candidates are considered. It then checks pathogenic/likely-pathogenic evidence and primary report-review hints before checking whether a high-priority uncertain candidate still needs review. If none apply, it returns the cautious no-positive-candidate state. Candidate IDs supporting the decision are preserved for audit.
Ranked candidates
The main table orders variants by a composite score that combines phenotype fit, inheritance support, consequence, rarity, and quality.
Evidence details
Each row can expand to show annotation, filtering, phenotype overlap, literature links, and provisional ACMG evidence.
Report outputs
The workflow exports HTML, TSV, and Microsoft word results so the shortlist can be reviewed and shared outside the app.
The carrier-screening workflow is built for reproductive-risk review in a couple. It analyzes each partner independently, applies carrier-scope filtering, and then performs a gene-level comparison between retained heterozygous findings. This design prevents partner-specific evidence from being conflated while still making shared-gene signals immediately visible.
Couple intake. VarSage records partner identifiers, sample IDs, genome build, relationship and ancestry notes, reproductive concern notes, carrier panel settings, optional secondary-finding scope, and optional BED interval restriction.
Independent partner parsing. Each partner file is normalized separately. Genotype, zygosity, depth, quality, gene, consequence, clinical assertion, and predictor evidence remain attached to the correct individual.
Carrier-scope matching. Retained variants are assigned to explanatory scopes: configured carrier-panel genes, phenotype-concern genes derived from HPO mapping of notes, ACMG secondary-finding genes when enabled, and X-chromosome review where relevant.
Heterozygous carrier filter. The core carrier model focuses on heterozygous variants. Common, low-quality, benign, or out-of-scope variants are removed before couple-level comparison.
Partner summaries. Each partner receives an auditable retained-variant list with gene, variant, category, zygosity, allele frequency, evidence score, and rationale.
Same-gene comparison. The final couple step flags genes where both partners carry retained heterozygous variants. This is a review alert for recessive disease risk, not an automated fetal-risk prediction.
Risk wording and review notes. The report separates evidence from interpretation and leaves disease mechanism, phase, classification, residual risk, ancestry context, and counseling decisions to the qualified reviewer.
Outputs. VarSage produces partner-specific tables, same-gene warning tables, downloadable TSV files, HTML reports, and Word reports.
Partner summaries
Each partner gets its own retained-variant summary, including panel genes, secondary findings, and X-chromosome review where relevant.
Same-gene warnings
The couple-level table highlights genes where both partners still have retained heterozygous variants after filtering.
Exports
The workflow writes downloadable TSV, HTML, and Word outputs with separate findings for each partner and the couple summary.
The Rare Disease - Trio workflow extends proband prioritization with parental allele-state evidence. It is designed for family-aware interpretation: the proband is ranked first, and parental calls are then used to evaluate inheritance hypotheses. Missing parent files, low-quality parental calls, or absent coverage are treated as missing evidence rather than definitive evidence of absence.
Family intake. VarSage records the proband case details, phenotype information, genome build, sample IDs, expected inheritance, and the mother and father variant files when provided.
Proband-first prioritization. The proband undergoes the Rare Disease - Singleton workflow first, including phenotype matching, annotation, filtration, ranking, recessive-pair detection, provisional ACMG evidence, and optional AI review.
Parent file normalization. Mother and father files are parsed with the same coordinate and annotation logic, so parental calls can be compared against proband candidates using chromosome, position, reference, alternate, and gene context.
Inheritance-state comparison. For each important proband candidate, VarSage records whether the same allele is observed in mother, father, both parents, neither parent, or cannot be assessed because parental evidence is unavailable or inadequate.
Possible de novo review. Variants seen in the proband but not confidently seen in either parent are flagged as possible de novo findings. Parentage, locus coverage, genotype quality, sample identity, mosaicism, and orthogonal confirmation remain explicit review requirements.
Compound-heterozygous review. For recessive genes, VarSage looks for pairs of proband variants in the same gene that may have different parental origins. These pairs are summarized so the reviewer can inspect phase, partner-allele classification, genotype quality, and gene-disease fit.
Causative shortlist. The pipeline combines proband ranking and parent-aware evidence to identify the most compelling candidates for follow-up. A variant can carry more than one review label, such as causative and possible de novo, without being printed repeatedly.
Parent review tables. Each parent receives one concise retained-variant table. Category labels explain whether a variant is trio-relevant, phenotype-related, part of the carrier panel, a secondary finding, or part of female X-chromosome review.
Outputs. VarSage writes concise HTML and Word Rare Disease - Trio reports with key proband findings, compound-het pair summaries, parent review tables, warnings, methodology, and limits.
Proband shortlist
The proband still gets a full Rare Disease - Singleton ranking table with phenotype, inheritance, and evidence context.
Parent-aware findings
The trio summary separates possible de novo, compound-heterozygous, and causative candidate views from the parental comparisons.
Family reports
Mother and father each receive their own structured summary, and the final exports include the trio-specific interpretation sections.
Single Variant Analysis looks up one small variant at a time without uploading a VCF or variant table. The user types a genomic locus, chooses the reference genome, and VarSage returns transcript consequences, coordinate-level evidence from the super database, protein 3D structure and 2D domain context, and cross-species conservation for that exact allele. It is intended for quick look-ups, for checking a variant reported elsewhere, and for reviewing a single candidate in more depth.
Interpretation boundary: Single Variant Analysis is descriptive context only. There is no phenotype, so the variant is not ranked, and VarSage does not apply its own ACMG/AMP scoring. Any InterVar criteria shown come directly from the super database record for the allele.
Entering a variant
Open the Single Variant Analysis tab on the analysis page (sign-in required). Enter the variant as VCF-style genomic coordinates (1-based position, reference allele, alternate allele) and select hg38 / GRCh38 (default) or hg19 / GRCh37. The reference allele must match the selected build.
Accepted form
Example
chromosome:position REF>ALT
chr17:7675088 C>T
Dash-separated
17-7675088-C-T
Colon-separated
17:7675088:C:T
Space-separated
17 7675088 C T
Indel with anchor base
chr7:117559590 ATCT>A
The chr prefix is optional. Chromosomes 1-22, X, Y and MT (or M) are accepted.
Commas in the position are allowed, for example 7,675,088.
REF and ALT must be DNA bases (A, C, G, T, N), up to 1000 bases each, and must differ. Insertions and deletions must include the shared anchor base, as in a VCF.
Only one alternate allele can be submitted at a time. HGVS notation (c. or p.) and rsIDs are not accepted as input.
The Examples links (TP53 R175H and CFTR F508del, both hg38) fill in the form so you can try the feature.
What happens after submission
Validation. The input is parsed and normalized. Malformed loci, unsupported chromosomes, invalid alleles, or an unknown genome build return a clear error message without running any analysis.
Transcript annotation. A one-line VCF is written to a temporary folder and annotated with Jannovar against the transcript database for the selected build. Every transcript consequence for the submitted alternate allele is returned.
Default transcript selection. VarSage picks a default transcript: highest impact first (HIGH, MODERATE, LOW, MODIFIER), then transcripts with a protein change, then NM_/ENST accessions, then the lowest accession number, which is usually the canonical transcript.
Super database lookup. The exact allele (chromosome, position, REF and ALT) is queried in the configured super database for that build. Matching fields are returned, including population frequency, ClinVar, REVEL, InterVar and dbSNP identifiers when present.
Protein mapping. The gene is mapped to its UniProt accession through HGNC. The residue position and amino acids are taken from the selected transcript's HGVS p. change.
Cleanup. Temporary files are deleted as soon as the response is returned. The submitted variant is not saved as a case.
Reading the results
Variant summary
Gene, variant type (SNV, MNV, insertion, deletion or deletion-insertion), consequence and impact, transcript and exon/intron number, cDNA change, protein change, and dbSNP ID. Any warnings, such as an unavailable annotation resource, are listed here.
Transcript annotation
One row per transcript with effect, impact, exon/intron, HGVS c. and p., CDS and amino-acid position/length, and biotype. The default row is highlighted. Choosing another row in the Use column updates the summary and protein views for that transcript.
Super database evidence
Max population allele frequency, ClinVar significance, REVEL, the automated InterVar classification, dbSNP ID, and the InterVar ACMG/AMP criteria met for this allele (pathogenic codes in red, benign codes in green). All super database fields expands the full record.
Protein context
For a protein-coding change, the AlphaFold 3D structure with the residue projected on it and the 2D InterPro domain map are shown, using the same viewers described in Protein 3D Structure. Intronic, UTR, splice-region and intergenic variants have no residue to show.
Conservation
A UCSC view of the region around the variant with phyloP and phastCons (100-vertebrate) tracks and a species-by-species alignment. The flanking window can be set to ±25, ±100, ±250 or ±500 bp.
Limits and troubleshooting
"Not found in the super database" does not mean the variant is rare or benign. Check that REF/ALT and the genome build are correct, and that indels are written with the anchor base.
No transcript consequence usually means the variant is intergenic, or transcript annotation is not installed on the server for that build. The warning list explains which.
Residue numbering follows the selected transcript. It matches the UniProt canonical protein only when that transcript encodes the canonical isoform, so check the transcript before interpreting structure or domain positions.
Busy server: at most two single-variant analyses run at the same time. If the server is busy, retry after a moment. Annotation of one variant usually finishes in seconds and stops after three minutes.
Single Variant Analysis does not consider phenotype, genotype, zygosity, call quality or inheritance. For full prioritization, use Rare Disease - Singleton or Rare Disease - Trio with a variant file.
Every gene-bearing result view in the web application uses the same on-demand GTEx panel. Rare Disease - Singleton ranked candidates, Carrier screening same-gene warnings and partner tables, and Rare Disease - Trio proband, inheritance-finding, compound-heterozygous, causative, parent-review, and literature-context tables all expose the same Expression control.
Opening the control retrieves the gene's GTEx Portal profile and shows median TPM by tissue, tissue ranking, expression breadth, tissue specificity, a distribution summary, phenotype-linked tissue context when a broad local mapping is available, a locally saved reviewer note, and a link to the GTEx gene page. Expression data are presented as biological plausibility context rather than as variant-classification evidence.
Data source
VarSage uses GTEx Portal API v2, with gtex_v8 and GENCODE v26 as the defaults. Expression is loaded only when a signed-in user opens a gene panel, and unavailable remote data does not interrupt the analysis.
Privacy boundary
The authenticated VarSage endpoint receives the selected gene and phenotype labels. VarSage sends the gene lookup to GTEx and performs phenotype-to-tissue matching locally; patient files, patient IDs, and clinical narrative are not sent to GTEx by this feature.
Interpretation boundary
Expression is biological context, not an ACMG/AMP criterion and not a pathogenicity measure. It does not change filtering, ranking, classification, or reportability. Low bulk-tissue expression does not exclude a gene because cell type, developmental stage, transcript, and disease state matter.
Why it is shown separately: GTEx expression can support a reviewer’s biological plausibility assessment, but it cannot substitute for gene-disease validity, transcript relevance, mechanism, functional evidence, segregation, phase, or laboratory confirmation.
VarSage uses the Human Phenotype Ontology (HPO) as the controlled vocabulary for clinical features. HPO terms are used for Rare Disease - Singleton ranking, phenotype-concern scope in carrier screening, Rare Disease - Trio proband interpretation, and gene-disease plausibility review. The system preserves the difference between observed findings, explicitly absent findings, and inferred ontology matching context.
How HPO terms are collected
The matcher recognizes HPO IDs, canonical names, synonyms, selected clinically equivalent aliases, punctuation-normalized terms, and common plural forms. HPO hierarchy is used when mapping phenotypes to genes: for example, Migraine (HP:0002076) is a child of Headache (HP:0002315), so a gene annotated with Headache can remain in scope for a patient with migraine. The extractor may add direct, clinically useful parent terms such as Headache to the editable suggestion list; users can remove any suggestion before submitting the case. Co-symptoms such as photophobia, nausea, visual impairment, or aura are not inferred unless the source text states them or the user confirms them. AI suggestions still require a valid ontology ID and supporting text, and explicit negation takes precedence.
Manual entry
Type HPO terms directly into the Known HPO Terms field. The autocomplete searches by term name and synonym. Add terms one at a time; they appear as removable chips below the input.
AI extraction
Use Extract HPO terms with AI below each pipeline's clinical description. The model suggests present and explicitly absent terms, including strongly supported ontology parents, while deterministic validation requires valid identifiers and evidence from the submitted text. Suggestions appear in removable chips and remain editable before the analysis starts.
Absent (excluded) symptoms
Terms entered in the Absent HPO Terms field are recorded as excluded findings. They help refine the phenotype profile but do not contribute positively to the ranking score.
Text matching
The deterministic matcher normalizes text, handles common plurals (seizures matches Seizure), and searches HPO term names and synonyms. It prioritizes more specific (longer) terms when the 25-term cap is reached. Gene-scope matching additionally recognizes a patient term's HPO ancestors, but it never treats unrelated associated symptoms as observed findings.
Gene-phenotype associations
VarSage loads a gene-phenotype mapping file configured through GENE_PHENOTYPES_FILE. HGNC aliases and HPOA disease annotations can enrich this layer by connecting previous gene symbols, OMIM/ORPHA disease identifiers, disease-level phenotypes, and known inheritance terms. Phenotype overlap is therefore a structured plausibility measure, not a proof of causality.
For selected rare-disease candidates, VarSage can show predicted 3D protein structure context beside the structured variant evidence. This view helps reviewers localize an annotated amino-acid position on the AlphaFold reference model and consider whether the residue sits in a visible domain, interface, helix, sheet, or exposed region.
Interpretation boundary: The variant-context panel is a residue projection on the reference structure, not a validated remodeled mutant protein. It supports visual review only and does not create ACMG evidence by itself.
Example protein structure context: the left panel shows the healthy/reference AlphaFold prediction and the right panel projects the annotated variant residue on the reference structure.
When it appears
The structure panel is shown when the candidate has enough gene, protein, and residue information to connect the variant to a UniProt/AlphaFold reference model. If the mapping is incomplete, the report simply omits the panel.
What it provides
The panel shows the reference model, a variant-context residue projection, confidence information when available, and links to external protein resources for deeper manual review.
How to use it
Reviewers can use the image to discuss structural plausibility, domain location, and residue context alongside phenotype fit, inheritance, population rarity, clinical assertions, and functional evidence.
What it does not do
It does not prove pathogenicity, simulate a validated altered fold, replace molecular modeling, or change the variant rank without supporting evidence from the rest of the analysis.
Standard Variant Call Format. VarSage reads genotype, depth, genotype quality, filter status, INFO annotations, FORMAT fields, and transcript annotations. Multi-sample VCFs are supported when the analyzed sample ID is selected.
TSV / CSV
Tabular files with separate coordinate columns or a single parseable variant column. Common aliases for chromosome, position, reference allele, alternate allele, gene, consequence, and frequency are recognized.
TXT
Plain text files are treated as delimited tables when a consistent separator is present. They are most appropriate for small, already-curated variant lists.
Auto-detection
VarSage can infer the parser from filename and content. For non-standard exports, optional AI schema detection can identify columns, after which coordinate parsing remains deterministic.
BED region filtering
BED files define genomic intervals of interest, usually assay targets or capture regions. When a BED target set is selected, variants outside those intervals are removed before Jannovar annotation and external database merging. This improves runtime and keeps the report aligned with the technical scope of the assay.
BED coordinates use the standard 0-based half-open convention, while VCF and most variant tables use 1-based variant positions. VarSage handles the comparison internally, but the BED file must correspond to the same genome build as the uploaded variants.
Note: BED filtering is build-aware. A BED file configured for hg38 is only offered when the run uses hg38. The same catalog is shared across rare-disease, carrier-screening, and trio workflows.
The VarSage SuperDB layer is a local, build-specific coordinate annotation resource. It is intended to provide high-value fields needed for rapid interpretation: population rarity, clinical assertion context, prediction scores, splice scores, and stable variant identifiers. Large SuperDB files can be BGZIP-compressed and Tabix-indexed so only positions present in the current analysis are queried.
What super databases provide
maxFreq
maxFreq summarizes population rarity by retaining the maximum observed allele frequency across configured population resources for the same allele. It provides a conservative rarity screen, but disease prevalence, penetrance, ancestry, and inheritance mode still determine the appropriate clinical threshold.
Prediction scores
REVEL, CADD, SpliceAI, InterVar-like fields, ClinVar-like assertions, and custom laboratory columns can be attached when present in local annotation tables. These fields support review but do not replace primary evidence assessment.
VarSage offers optional AI-assisted features, but the platform remains functional without any model call. AI can help translate clinical text into reviewable HPO candidates, identify unusual table schemas, summarize evidence for top-ranked variants, and draft cautious report narrative from structured data. It is not the authority for coordinate extraction, allele identity, ACMG evidence, or clinical classification.
What AI can do
Phenotype extraction
AI reads the free-text clinical description and suggests present or explicitly absent HPO terms. Suggestions must resolve to valid ontology identifiers and should be interpreted as phenotype curation assistance.
Evidence review
When enabled for a case, AI reviews a bounded top-ranked candidate set plus selected rescue candidates and provides a narrative summary of phenotype fit, inheritance support, evidence quality, and missing confirmation steps.
ACMG/AMP refinement
For AI-reviewed candidates, the model may suggest ACMG/AMP criteria that appear compatible with the supplied structured evidence. Deterministic validation checks the code, strength, and prerequisites before accepting any provisional refinement. Expert verification remains mandatory.
Schema detection
For unusual TSV/CSV headers, AI can identify which columns appear to encode chromosome, position, reference, alternate, gene, consequence, quality, and annotation fields. VarSage then parses coordinates deterministically.
Case conclusion
When enabled, AI drafts a case-level synthesis from structured candidate data. The synthesis separates review priority, provisional classification, case-level causality, reportability, and missing evidence.
Important: AI output is decision support. A model cannot establish pathogenicity, create ACMG evidence by assertion, override deterministic allele matching, or make a variant reportable without explicit supporting evidence and expert review.
VarSage provides conservative ACMG/AMP-oriented evidence summaries for germline Mendelian sequence variants. These summaries are provisional decision-support aids, not clinical laboratory classifications. Evidence is deliberately labeled by state so reviewers can distinguish explicit auditable data from hypotheses and contextual information.
Evidence categories
Phenotype evidence
Derived from HPO overlap between the patient profile and gene-disease associations. High overlap supports phenotype-gene plausibility, but it is not sufficient by itself for variant pathogenicity.
Inheritance evidence
Based on zygosity, sex, expected inheritance mode, known gene inheritance, and family clues. Trio and phase evidence remain provisional until sample identity, parentage, callability, and segregation are reviewed.
Population evidence
Derived from maxFreq and other frequency fields. Rarity supports review, but maximum credible allele frequency depends on prevalence, penetrance, inheritance mode, and disease-specific guidance.
Prediction evidence
REVEL, CADD, SpliceAI, and similar predictors support computational-impact review only when their thresholds and applicability are appropriate. Correlated predictors should not be counted independently.
Quality evidence
Depth, genotype quality, and filter status are used to reduce technical noise. Quality metrics support confidence in a call, not pathogenicity.
Evidence states
State
Meaning
Example
Applied
The prerequisite fact is explicitly present in the source data and can be audited.
A supplied validated functional assay strength, or de novo evidence with parentage confirmation.
Candidate
The data suggest a criterion, but disease-specific or laboratory prerequisites are incomplete.
Rarity compatible with PM2_Supporting, or possible compound heterozygosity without confirmed trans phase.
Informational
The field is useful context but is not counted as ACMG/AMP evidence.
ClinVar label, GTEx expression, LitVar context, or AI narrative without primary supporting evidence.
How to interpret ACMG evidence
PVS1 is not assigned from consequence alone; loss-of-function disease mechanism, transcript relevance, NMD expectation, exon rescue, and the ClinGen PVS1 decision tree require review. PM2 is treated conservatively at Supporting strength. PP3 and BP4 require calibrated predictors. PP5 and BP6 are not generated from ClinVar labels. De novo, trans-phase, co-segregation, and functional evidence require the corresponding laboratory and disease-specific prerequisites.
The pharmacogenomics section annotates patient variants against build-specific PGx databases. When a variant matches a PGx entry, its drug, gene, phenotype category, predicted effect, evidence level, clinical score, and relevant genotype-response text are attached to the result. PGx findings are kept strictly separate from Rare Disease - Singleton ranking and ACMG/AMP classification because genotype-based drug-response guidance describes pharmacological context, not Mendelian disease causality.
Clinical boundary: PGx entries describe population-level genotype-phenotype associations for drug response. They do not establish a rare-disease diagnosis. Medication relevance, current prescribing guidance, and genotype interpretation must be confirmed by a qualified pharmacist or clinical pharmacologist before clinical use.
PGx network diagram
Results that include PGx annotations display a hub-and-spoke network diagram that groups findings by pharmacogenomic category. Each hub node (large sphere) represents one category such as Toxicity, Efficacy, or Metabolism/PK. Satellite nodes around each hub show the genes, drugs or regimens, and variant identifiers belonging to that category. Hub size reflects the number of matched variants; color encodes category type. The diagram appears in the live results view, in saved HTML reports, and - as a compact pivot table - in Word report exports.
Example PGx network view: large hubs summarize drug-response categories while surrounding nodes keep genes, medications, and variant identifiers visible for review.
Actionable
A PGx guideline recommends a prescribing action based on the detected genotype. Confirmatory testing and prescriber review are required before acting on any automated finding.
Preemptive
The genotype is relevant to medications the patient may receive in the future. No current prescribing change is implied, but the finding should be available in the patient record.
Potentially actionable
Evidence supports a possible prescribing consideration but does not yet reach guideline-level recommendation. Expert clinical pharmacology review is indicated.
Association only
The variant is associated with drug response in the literature but lacks prescribing-level guidance at this time. Treat as background context, not a clinical trigger.
Evidence and scoring
Each PGx finding carries an evidence level, a clinical score derived from guideline strength and clinical relevance, a medication relevance indicator based on patient history where available, and source annotation links. The PGx priority score combines guideline actionability strength, medication relevance, genotype-phenotype match quality, evidence strength, clinical consequence relevance, and evidence consistency. This score orders the PGx summary table but does not represent a standard pharmacogenomic classification.
The GWAS section attaches population-level trait associations from the GWAS Catalog to patient variants. GWAS context highlights the strongest phenotype signals overlapping the patient variant set and is placed after all diagnostic review sections because GWAS associations describe susceptibility at the population level, not Mendelian disease causality for this individual patient.
Clinical boundary: GWAS associations do not establish a rare-disease diagnosis, an ACMG pathogenicity classification, or a case-level conclusion. They provide epidemiological plausibility context for the reviewer and must not be interpreted as causal without orthogonal functional, segregation, and clinical evidence.
GWAS network diagram
When GWAS context is available, a hub-and-spoke network diagram groups loci by confidence tier. Each hub represents one tier (Tier 1 - High confidence through Tier 5 - Low confidence, plus Excluded). Satellite nodes show the prioritized effector genes, matched patient phenotypes or GWAS traits, and genomic loci belonging to that tier. Hub size reflects the number of loci in the group; color encodes tier level from high-confidence red through low-confidence slate. The diagram appears in the live results view, saved HTML reports, and as a pivot table in Word exports.
Example GWAS network view: tier hubs group loci by patient relevance, while surrounding nodes show effector genes, matched traits, and genomic positions.
Tier 1 - High confidence
Patient-relevant trait, genome-wide significant p-value (≤ 5×10⁻⁸), and strong variant-level evidence including fine-mapping or functional support. Highest patient-locus score.
Tier 2 - Patient-relevant
Patient-relevant trait with suggestive significance (p ≤ 1×10⁻⁵) or moderate variant evidence. Warrants review in the context of the diagnostic question.
Tier 3 - Related phenotype
Association with a phenotype related to but not identical to the entered patient features. Provides secondary plausibility context.
Tier 4 - Context / pleiotropic
Broad trait association with limited phenotype overlap. May indicate shared genetic architecture with the patient's condition but should be interpreted cautiously.
Locus scoring
Each GWAS locus receives two scores. The patient-locus relevance score (0-100) combines phenotype relevance (40%), matched-trait GWAS evidence strength (25%), replication across studies (20%), and ancestry-study compatibility (15%). The variant evidence score (0-100) captures fine-mapping causal probability, functional annotation, QTL shared-variant support, patient effect-allele dosage, and gene-tissue plausibility. Both scores are shown in the GWAS summary table and referenced in the network hub size.
QTL support
Where available, eQTL and sQTL records are attached to GWAS loci. These indicate that the variant or a correlated variant modulates expression or splicing of a nearby gene in a relevant tissue. QTL support is biological plausibility context; it does not substitute for direct functional evidence of pathogenicity.
VarSage can estimate a patient's genetic ancestry from a VCF file by comparing observed genotypes against a compact reference panel of ancestry-informative SNPs (AIMs). The output is a set of population-affinity proportions: each value reflects how well a reference population's allele-frequency pattern statistically explains the patient's observed genotype set. This approach follows the constrained genotype-likelihood mixture framework established in the population-genetics literature[1,2,11] and used by tools such as STRUCTURE[1] and ADMIXTURE,[2] adapted here for individual-level inference against a pre-computed reference panel.
Important - what ancestry results mean and do not mean: Genetic ancestry proportions reflect inherited allele-frequency patterns, not ethnicity, nationality, religion, culture, or self-identified identity.[9,16] They depend entirely on which populations are represented in the installed reference database. The result must never be used to assign ethnicity or to make autonomous clinical decisions.
VarSage ancestry analysis follows a six-step workflow: build a reference AIM panel, extract patient genotypes, harmonize alleles, apply QC, verify PCA placement, and infer reference-population affinity.
Why Genetic Ancestry Matters in a Genomics Workflow
Ancestry estimation has become a standard step in clinical and research genomics pipelines.[3,16] It supports population-stratified variant filtering (allele frequencies are population-specific), flags potential reference-panel mismatches, and provides provenance context for pharmacogenomic and disease-risk interpretation. Understanding the statistical method behind the result is essential for interpreting confidence levels and for recognizing when the estimate is reliable versus when it should be treated with caution.
How the Six-Step Pipeline Works
Reference SNP panel construction. Before any patient analysis, a maintainer builds a compact panel from a reference cohort (for example, the 1000 Genomes Project[5] or the TOPMed Program[17]). The builder retains autosomal biallelic SNPs that pass quality-control filters:[7] pooled minor allele frequency ≥ 5%, per-site call rate ≥ 90%, distance-based LD pruning (50 kb default spacing),[13] and exclusion of strand-ambiguous A/T and C/G SNPs whose orientation cannot be reliably determined across datasets.[12] For each retained SNP and each reference population, the ALT allele frequency is recorded. A principal component analysis (PCA)[3,4] is also computed to define reference population centroids in PC space.
Genotype extraction from the patient VCF. VarSage scans the patient VCF and reads the dosage - the number of ALT allele copies - at each position in the reference panel: 0 for homozygous REF (0/0), 1 for heterozygous (0/1), and 2 for homozygous ALT (1/1). Sites below the configured minimum read depth or genotype quality score are treated as missing and excluded from analysis.
Allele harmonization. The patient VCF and the reference panel may have been built from different pipelines or sequenced on complementary strands at some positions.[12] VarSage reconciles each SNP: a direct match uses the dosage as-is; a reversed match (REF and ALT swapped) flips the dosage (2 - dosage) to correct strand orientation; incompatible sites are discarded. Only successfully harmonized SNPs proceed to inference.
Quality gate. If the number of usable SNPs falls below the configured minimum (default: 1,000), ancestry estimation stops and the result is marked INSUFFICIENT_MARKERS. This commonly occurs with whole-exome sequencing (WES) or gene panels because most AIMs lie in non-coding regions.[7] WGS data typically provides 10,000 or more markers, supporting high-confidence estimates.
PCA-based reference-space verification. The usable SNPs are projected into the same PCA space as the reference panel.[3,4,18] PCA decomposes population allele-frequency variation into orthogonal axes that capture the dominant axes of genetic differentiation.[10,14] The patient's PC coordinates are compared against the reference population centroids. If the patient lies further from every centroid than the configured distance threshold, the result is flagged as REFERENCE_MISMATCH.[9,10] This flag means the installed database may not represent the patient's background - it is not a sequencing quality failure. Installing a more diverse reference panel is the remedy.
Diploid genotype-likelihood mixture inference. This is the core statistical step. VarSage searches for a mixture vector q = [q1, q2, …, qk] - one non-negative weight per reference population, summing to 1 - that maximises the total log-likelihood of the patient's observed genotypes.[1,2,11] For a given mixture, the expected ALT allele frequency at each SNP is the weighted average of per-population frequencies. Under Hardy-Weinberg equilibrium,[6] the diploid genotype probabilities follow P(dosage = 0) = (1-p)², P(dosage = 1) = 2p(1-p), and P(dosage = 2) = p². The optimizer uses exponentiated gradient ascent,[15] a multiplicative update rule that keeps all weights non-negative and summing to 1 at every step without external transformations. It runs for up to 1,500 iterations with a step size that decays as 0.04 / √iteration; convergence is declared when both the weight change and the log-likelihood change fall below 1 × 10⁻⁸. After inference, components below the configured reporting threshold (default: 2%) are aggregated into an Other / unresolved bucket and the remaining components are renormalized to 100%.
Confidence Tiers
A confidence label is assigned to every result based on the number of usable SNPs,[7] whether the optimizer converged, and the PCA distance to the nearest reference centroid.[9,10]
Usable SNPs
Confidence tier
Interpretation guidance
< 1,000
Estimation aborted - INSUFFICIENT_MARKERS
Too few markers to produce a reliable estimate. Common with WES or gene panels.[7]
1,000 – 4,999
LOW
Broad population assignment may be possible; fine-grained estimates are unreliable.[8,9]
5,000 – 9,999
MEDIUM
Suitable for superpopulation-level components.[5,8] Interpret with caution for closely related groups.
≥ 10,000
HIGH
Robust estimate for the populations represented in the installed reference database.[2,3]
Quality Metrics Shown in the Result
Reference SNPs
Total SNPs in the installed reference panel for this genome build. A larger panel improves resolution, especially for closely related populations.[8,9]
Observed SNPs
Panel positions found in the patient VCF with a genotype call at or above quality thresholds. Low values suggest sparse coverage, low-depth sequencing, or a gene-panel assay.[7]
Harmonized SNPs (Informative SNPs)
Observed SNPs that were successfully reconciled between the patient VCF and the reference panel - including strand-flipped sites.[12] This is the count used for inference and confidence assignment.
Direct / Reversed matches
Direct matches required no allele reorientation; reversed matches had their dosage flipped to correct strand orientation.[12] A high fraction of reversed matches is not a problem - it simply reflects opposite-strand representation in the two datasets.
Reference Mismatch Warning
A REFERENCE_MISMATCH flag appears when the patient's PCA projection[3,4] lies beyond a configured distance threshold from all reference population centroids.[9,10] This most commonly occurs when the patient has ancestry from a region underrepresented in the installed database - for example, a patient with Middle Eastern ancestry analyzed against a database built solely from the five 1000 Genomes[5] superpopulations. In this case, the mixture proportions will be spread across the nearest available components and may not accurately reflect the patient's true ancestral background.[9] The appropriate resolution is to install a database that includes the relevant reference population, not to treat the result as a sequencing quality indicator.
How to Interpret an Ancestry Result
A result such as EUR 68% · SAS 24% · Other 8% means that the combination of 68% European-like and 24% South Asian-like reference allele frequencies provides the statistically best explanation for the genotypes in this VCF, given the installed reference panel.[1,2] It does not mean the patient identifies with these groups, was born in these regions, or has a specific genealogical history.[9,16] The percentages are population-affinity measures derived from allele-frequency patterns at thousands of SNPs simultaneously.
For clinical reporting: Ancestry results from VarSage should be described as genetic reference-population affinity, not as ethnicity.[9,16] Reports should state which reference database was used, the confidence tier, the number of informative markers, and any warnings (INSUFFICIENT_MARKERS or REFERENCE_MISMATCH) that were raised. They must not be reported as genealogical, ethnic, or cultural conclusions.
Installing a Reference Database
The ancestry feature requires a locally installed reference database. VarSage does not bundle reference data or connect to external ancestry services - the database is built by a maintainer from a legally obtained reference cohort (such as the 1000 Genomes Project[5] or the NHLBI TOPMed Program[17]) using the supplied build_ancestry_database.py script. After building, the compact panel is installed at the path configured in ANCESTRY_DATABASE_HG38 or ANCESTRY_DATABASE_HG19 and enabled with ANCESTRY_ENABLED=true. WES or gene-panel data typically yields fewer than 5,000 usable markers;[7] for reliable superpopulation-level estimates, a WGS VCF against a panel of 20,000 or more AIMs is strongly recommended.
Limitations
Panel-limited resolution. The installed database defines which populations can be distinguished.[9,10] Populations not represented in the reference cannot be detected or reported.
Closely related populations. Fine-grained labels (e.g. distinguishing Northern European from Southern European) require large, diverse reference panels and high marker counts.[8,9] Broad superpopulation labels are more robust for most databases.
WES / gene panel data. Most AIMs lie in non-coding regions. WES data typically yields 1,000 – 5,000 usable markers,[7] which is borderline for broad-component estimates and insufficient for fine-scale ones.
Hardy-Weinberg assumption. The genotype probability model assumes HWE within each reference population.[6] Departures from HWE - due to recent admixture, inbreeding, or sequencing artefacts - can reduce estimate accuracy.
Ancestry is not a diagnosis. Genetic ancestry proportions are statistical summaries of allele-frequency similarity.[9,16] They must never replace clinical, genealogical, or self-reported identity information in a clinical context.
Scientific References
#
Citation (Vancouver style)
1
Pritchard JK, Stephens M, Donnelly P. Inference of population structure using multilocus genotype data. Genetics. 2000;155(2):945-59.
2
Alexander DH, Novembre J, Lange K. Fast model-based estimation of ancestry in unrelated individuals. Genome Res. 2009;19(9):1655-64.
3
Price AL, Patterson NJ, Plenge RM, Weinblatt ME, Shadick NA, Reich D. Principal components analysis corrects for stratification in genome-wide association studies. Nat Genet. 2006;38(8):904-9.
4
Patterson N, Price AL, Reich D. Population structure and eigenanalysis. PLoS Genet. 2006;2(12):e190.
5
1000 Genomes Project Consortium, Auton A, Brooks LD, Durbin RM, Gargiulo EP, Kang HM, et al. A global reference for human genetic variation. Nature. 2015;526(7571):68-74.
6
Hardy GH. Mendelian proportions in a mixed population. Science. 1908;28(706):49-50.
7
Anderson CA, Pettersson FH, Clarke GM, Cardon LR, Morris AP, Zondervan KT. Data quality control in genetic case-control association studies. Nat Protoc. 2010;5(9):1564-73.
8
Rosenberg NA, Pritchard JK, Weber JL, Cann HM, Kidd KK, Zhivotovsky LA, et al. Genetic structure of human populations. Science. 2002;298(5602):2381-5.
9
Lawson DJ, van Dorp L, Falush D. A tutorial on how not to over-interpret STRUCTURE and ADMIXTURE bar charts. Nat Commun. 2018;9(1):3258.
10
McVean G. A genealogical interpretation of principal components analysis. PLoS Genet. 2009;5(10):e1000686.
11
Tang H, Peng J, Wang P, Risch NJ. Estimation of individual admixture: analytical and study design considerations. Genet Epidemiol. 2005;28(4):289-301.
12
Marchini J, Howie B. Genotype imputation for genome-wide association studies. Nat Rev Genet. 2010;11(7):499-511.
13
Purcell S, Neale B, Todd-Brown K, Thomas L, Ferreira MA, Bender D, et al. PLINK: a tool set for whole-genome association and population-based linkage analyses. Am J Hum Genet. 2007;81(3):559-75.
14
Hellenthal G, Busby GB, Band G, Wilson JF, Capelli C, Falush D, et al. A genetic atlas of human admixture history. Science. 2014;343(6172):747-51.
15
Kivinen J, Warmuth MK. Exponentiated gradient versus gradient descent for linear predictors. Inf Comput. 1997;132(1):1-63.
16
Martin AR, Kanai M, Kamatani Y, Okada Y, Neale BM, Daly MJ. Clinical use of current polygenic risk scores may exacerbate health disparities. Nat Genet. 2019;51(4):584-91.
17
Taliun D, Harris DN, Kessler MD, Carlson J, Szpiech ZA, Torres R, et al. Sequencing of 53,831 diverse genomes from the NHLBI TOPMed Program. Nature. 2021;590(7845):290-9.
18
Privé F, Luu K, Blum MGB, McGrath JJ, Vilhjálmsson BJ. Efficient toolkit implementing best practices for principal component analysis of population genetic data. Bioinformatics. 2020;36(16):4449-57.