genoSecretor Workflow: Loading to Output¶

This document describes how genotype data moves through genoSecretor 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. genoSecretor is not a clinical typing tool.

Overview¶

genoSecretor reads three FUT2 tag SNPs (rs601338, rs1047781, rs602662) from a cohort genotype file, detects the genome build, normalizes alleles to biological marker states, infers haplotypes and diplotypes, and writes per-sample secretor calls with QC metrics. Only the requested markers are fetched — full variant sets are never loaded.

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

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

Module	Role
`readers/`	Format detection and indexed marker fetch (VCF, BGEN, PGEN, PLINK1)
`core/`	Types, YAML registry, build detection, genotype interpretation, normalization, haplotype logic
`methods/`	Inference methods and `SecretorCaller` orchestration
`cli/`	Command-line interface, output writers, citations
`data/`	YAML single source of truth for coordinates, states, methods

Entry points¶

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

genosecretor cohort.pgen --out secretor
genosecretor cohort.pgen --inspect

from genosecretor import SecretorCaller

caller = SecretorCaller(method="auto", ancestry="auto")
result = caller.call("cohort.pgen")
for call in result.calls:
    print(call.sample.iid, call.secretor_status, call.fut2_genotype)

Pipeline stages¶

Step	What happens
1. Format detection	Auto-detect VCF/BCF, PGEN, PLINK1, or BGEN
2. Sample list	FID/IID from the input
3. Marker probe	Fetch FUT2 tags using each assembly's coordinates
4. Build detection	Coordinates + header + optional chr19 length; conflicts error
5. Marker fetch	Re-fetch on the resolved build
6. Method selection	`auto` uses ancestry: two-marker when both SNPs exist; `--ancestry eas` (or EAS-like AF) refuses `common` without rs1047781
7. Inspect	Call rates, derived AF, ancestry; `--inspect` stops here (exit 1 if auto would refuse)
8. Genotype interpretation	hardcall / dosage / probability (`auto`: GP → DS → GT)
9. Normalization	REF/ALT → FUNCTIONAL / LOF / WEAK / SE_PROXY
10. Inference	Haplotype/diplotype rules; `secretor_status` follows `--phenotype-coding`
11. Outputs	`.secretor.tsv`, `.qc.tsv`, `.summary.txt`, `.report.html`

Outputs¶

.secretor.tsv columns: FID, IID, secretor_status, fut2_genotype, fut2_allele1/2, haplotype1/2, method, geno_mode, phase_mode, build, confidence, qc_status, qc_reason, possible_diplotypes. Missing secretor_status is written as NA.