Skip to content

Variants

Variants are the unit of clinical interpretation. In iFlow, they come in three flavours:

  1. Global variant — a canonical record keyed by chromosome, position, reference allele, and alternate allele. Lives in the variant catalogue.
  2. Sample variant — a snapshot of a global variant as it appeared in a specific sample's VCF, with the fields from the VCF (genotype, VAF, depth, annotations) frozen at ingestion time.
  3. Report variant association — a global variant added to a specific report, carrying per-report overrides (pathogenicity, ACMG criteria) and curator notes.

This three-tier structure means that a variant's clinical classification on a signed report is preserved even if the global catalogue is later updated.

Global variant

Minimal fields:

  • Chromosome, position, reference allele, alternate allele (the canonical key).
  • HGVS notation at DNA, RNA, and protein levels.
  • Gene symbol(s).
  • Consequence type.
  • Reference to the transcript that anchors the HGVS.

Sample variant

One row per (sample, variant). Stores the VCF-time fields:

  • Genotype and zygosity.
  • Read depth and variant allele frequency.
  • Pass / filter flags.
  • Annotation fields emitted by the pipeline, including:
    • ISEQ_REPORT_AMP_CLASSIFICATION — the AMP / ASCO / CAP tier.
    • ISEQ_REPORT_GENE_SYMBOL — the report-facing gene symbol.
    • Population frequencies (gnomAD, 1000 Genomes, etc.).

Sample variants are frozen at ingestion; they are not mutated by curator action.

Report variant association

When a curator adds a variant to a report (or the auto-populate does it on their behalf), a ReportVariantAssociation record is created with:

  • pathogenicity_override — the classification used on this report.
  • acmg_criteria_override — the ACMG criteria applied (for germline).
  • variant_snapshot — a JSON snapshot of the variant as it looked when added. This is what the signed PDF will show.
  • notes — curator notes for this variant on this report.
  • added_by, added_at, modified_by, modified_at — audit fields.

The composite primary key is (report_id, variant_id) — each variant appears on a report at most once.

AMP / ASCO / CAP tiering

Somatic cases use the four-tier system defined by AMP / ASCO / CAP. The internal enum values are:

  • Tier_IA, Tier_IB, Tier_IC, Tier_ID — Tier I with evidence sublevels.
  • Tier_II — potential clinical significance.
  • Tier_III — unknown clinical significance.
  • Tier_IV — benign or likely benign.

iFlow detects the tier from the VCF ISEQ_REPORT_AMP_CLASSIFICATION INFO field. Free-text annotations (for example "level a", "tier ii") are normalised to the enum values above.

Variant classifications are human decisions

iFlow does not compute ACMG or AMP classifications — it records what the curator enters. The platform captures, stores, and renders these classifications; it does not generate them.

Auto-population rules

On the first load of the report page for an order:

  • Variants with Tier IA, IB, II, III are auto-populated in priority order (Tier IA → IB → II → III).
  • Tier IV is excluded by default; curators may add Tier IV manually.
  • Auto-population is idempotent: it runs once per report (report.properties["variants_auto_populated"] = true) and will not re-add a variant that a curator has since removed.

Tier IV excluded by default

Benign / likely benign variants are not auto-populated. A curator can add them manually when clinically relevant.

The constants driving this behaviour live in flow_core.clinical so they stay consistent across services:

  • TIER_PRIORITY — ordered mapping of tier name to sort priority.
  • REPORTABLE_TIERS — the set of tiers eligible for auto-population (everything with priority below 5, i.e. Tier I–III).
  • AMP_CLASSIFICATION_FIELD — the VCF INFO field consulted.

ACMG (germline)

Hereditary cases use the ACMG / AMP standards. Curators record the ACMG criteria that apply on each variant's ReportVariantAssociation. iFlow does not compute an ACMG classification — the criteria and the final category (Pathogenic / Likely Pathogenic / VUS / Likely Benign / Benign) are human decisions captured on the record.

Variant detail page

See Variant Detail for the detail page's layout and the fields surfaced there.

API

Global variants and sample variants are exposed read-only through Miner's API. Report associations are mutated via the Report service.

  • GET /api/v1/variants — catalogue listing, usually with chromosome and region filters.
  • GET /api/v1/variants/{variant_id} — variant detail including HGVS, consequence, and transcript.
  • GET /api/v1/samples/{sample_id}/variants — sample variants.