genoABO Workflow: Loading to Output¶

This document describes how genotype data moves through genoABO from file load to written results. For CLI flags and the Python API see usage.md; for inference rules see methods.md; for marker coordinates see markers.md; for limitations see assumptions.md.

Research use only. genoABO is not a clinical blood-transfusion typing tool.

Overview¶

genoABO reads four ABO tag SNPs (rs8176719, rs8176746, rs8176747, rs505922) from a cohort genotype file, detects the genome build, normalizes alleles to biological marker states, infers haplotypes and diplotypes, and writes per-sample ABO calls with QC metrics. Indexed VCF/BCF fetches those sites by region. Unindexed VCF is scanned into an in-memory cache. PGEN and BGEN parse full variant-metadata indexes, then read genotypes only for the matched markers.

The package is organized into four modules plus YAML registries:

flowchart TB
    Input[Genotype file]
    Readers[readers/]
    Core[core/]
    Methods[methods/]
    CLI[cli/]
    Data[data/*.yaml]
    OutABO["PREFIX.abo.tsv"]
    OutQC["PREFIX.qc.tsv"]
    OutSum["PREFIX.summary.txt"]
    OutRep["PREFIX.report.html"]

    Input --> Readers
    Readers --> Core
    Core --> Data
    Core --> Methods
    Methods --> CLI
    CLI --> OutABO
    CLI --> OutQC
    CLI --> OutSum
    CLI --> OutRep

Entry points¶

Both paths run the same pipeline via ABOCaller. See Usage for the full CLI and Python API.

# Full inference + output
genoabo cohort.pgen --out abo

# Marker inspection only (stops after step 7; no .abo.tsv)
genoabo cohort.pgen --inspect

from genoabo import ABOCaller

caller = ABOCaller(method="auto", build="auto", genotype_mode="auto", phase="auto")
result = caller.call("cohort.pgen")

for call in result.calls:
    print(call.sample.iid, call.abo_group, call.abo_genotype)

Pipeline stages¶

The orchestrator is ABOCaller._run() in methods/methods_caller.py. Stages run in this order:

Per-sample sub-flow¶

For each sample, marker data passes through normalization before method-specific inference:

flowchart LR
    GT[GenotypeCall per marker]
    Geno[interpret_genotype]
    Norm[normalize_marker]
    Hap[infer_haplotype]
    Method[method.call_sample]
    Call[ABOCall]

    GT --> Geno --> Norm --> Hap --> Method --> Call

Layers are strictly separated: readers know file formats but not ABO biology; normalization knows biological states but not inference rules; methods know decision tables but not VCF/PGEN syntax.

Genotype and phase modes¶

CLI flags map to CallerConfig and affect step 9:

In auto genotype mode, GP is used when available, else DS, else hardcall GT. GP and DS replace leftover phased GT so the requested mode wins.

Missing genotypes and dosage/GP below threshold become MISSING_MARKER with confidence=none on methods that require that marker. Conflicting A/B SNPs under three-marker become CONFLICT with confidence=low. The geno_mode column stores the requested mode (auto stays auto).

Marker identification (probe and fetch)¶

When locating variants in input files, genoABO tries keys in priority order (first hit wins):

1. rsID — e.g. rs8176719
2. contig + position — all equivalent contig names for the build:
3. numeric: 9:133257521
4. chr-prefixed: chr9:133257521
5. RefSeq NC: NC_000009.12:133257521 (GRCh38 chr9)
6. contig + position + alleles — chr:pos:nea:ea for each representation in markers.yaml, both orientations (e.g. 9:133257521:G:GC and 9:133257521:GC:G)

Contig aliases are defined per build in assemblies.yaml (contigs section). Input files are indexed under every alias derived from their CHROM field, so a VCF using NC_000009.12 matches the same marker as one using 9 or chr9.

For indexed VCF/BCF, region queries are attempted for each contig alias. Allele-aware keys disambiguate when they match. A position-only key (chr:pos) keeps the first indexed variant at that site, so rsID or allele keys are preferred when several records share a position.

Output files¶

Default CLI invocation:

genoabo cohort.pgen --out abo

writes four files (if -o is omitted, the prefix is the input path with its last suffix stripped):

--report PATH.html overrides the HTML path. Column descriptions in the report come from data/report.yaml (same schema as .abo.tsv).

genoabo cohort.pgen --out abo
genoabo cohort.pgen --out abo --report custom_report.html

Python:

from genoabo import ABOCaller
from genoabo.visualize import write_report

result = ABOCaller().call("cohort.pgen")
write_report(result, "abo.report.html")
# result.stats.n_input_samples, result.stats.n_group_A, ...
# result.config, result.input_path, result.phase_resolved

See also Examples for runnable demos across formats.

PREFIX.abo.tsv columns¶

Example header row:

FID IID ABO_group   ABO_genotype    ABO_allele1 ABO_allele2 haplotype1  haplotype2  method  geno_mode   phase_mode  build   confidence  qc_status   qc_reason   possible_diplotypes ukb_haplotype   isbt_alleles

PREFIX.qc.tsv¶

Key-value metrics including n_samples, genome_build, input_format, method, per-marker call rates, group counts (n_A, n_B, …), and percentages.

PREFIX.summary.txt¶

Plain-text cohort summary with ABO group counts and marker availability — suitable for logs.

PREFIX.report.html¶

Self-contained HTML run report: ABO pie and run settings at the top, then results (sample-flow and ABO charts), output column dictionary, input settings, selected-method rules, citations, and limitations. Always written; --report only changes the path.

YAML registries¶

All coordinates and biological mappings live in src/genoabo/data/, loaded at runtime via importlib.resources:

Error handling and early exit¶

When build detection conflicts (e.g. mixed GRCh37/GRCh38 signal), set --build hg19, --build hg38, or --build chm13 explicitly.

Related documentation¶

• methods.md — formal decision tables per inference method
• markers.md — coordinate provenance, biological states, and 1000 Genomes LD r²
• assumptions.md — rare-allele limits and unresolved edge cases
• Home — installation and quick start