genoabo 0.1.0__tar.gz

genoabo-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.egg
+
+# Local / IDE
+.venv/
+venv/
+.env
+.idea/
+.vscode/
+.DS_Store
+
+# pytest temp dirs
+pytest-cache-files-*/
+
+# Local derivation downloads (UCSC chain, CHM13 dbSNP VCF)
+/data/
+
+# Example run outputs
+examples/out/
+
+# Zensical site build
+site/

genoabo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yunye He
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

genoabo-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.5
+Name: genoabo
+Version: 0.1.0
+Summary: Genetically determined ABO blood group inference from genotype datasets
+Project-URL: Homepage, https://github.com/cloufield/genoABO
+Project-URL: Repository, https://github.com/cloufield/genoABO
+Author: Yunye He
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ABO,GWAS,biobank,bioinformatics,blood-group,genotype
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.11
+Requires-Dist: bgen-reader>=4.0
+Requires-Dist: cyvcf2>=0.30
+Requires-Dist: numpy>=1.24
+Requires-Dist: pgenlib>=0.94
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.9
+Provides-Extra: bgenix
+Requires-Dist: bgenix>=1.1; extra == 'bgenix'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.5; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: zensical; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# genoABO
+
+**genoABO** infers genetically determined ABO blood group from VCF, BGEN, PGEN, and PLINK genotype datasets.
+
+```bash
+pip install genoabo
+genoabo biobank.pgen --out bloodgroup
+```
+
+> **Research use only.** genoABO is intended for population-genetics, epidemiology, GWAS, PheWAS, and biobank research. Genotype-inferred ABO groups do not capture all rare, weak, cis-AB, structural, or otherwise atypical ABO alleles and **must not** be used for transfusion or clinical decision-making.
+
+## Quick start
+
+```bash
+genoabo cohort.pgen --out abo
+# writes: abo.abo.tsv, abo.qc.tsv, abo.summary.txt, abo.report.html
+```
+
+See [docs/workflow.md](docs/workflow.md) for the full load-to-output pipeline.
+
+See [examples/](examples/) for VCF (unphased and phased), PGEN, and PLINK1 demos across builds and marker notations, a 1000 Genomes EAS four-marker example (phased `--phase auto`, or forced unphased), and a multi-ancestry `--assume-bo` check against phased 1KG AFR/AMR/EAS/EUR.
+
+Inspect markers without calling:
+
+```bash
+genoabo cohort.pgen --inspect
+```
+
+## Supported formats
+
+| Format | Extensions | Notes |
+|--------|------------|-------|
+| VCF/BCF | `.vcf`, `.vcf.gz`, `.bcf` | GT, phased GT, DS, GP |
+| PLINK2 | `.pgen` + `.pvar` + `.psam` | Auto-locates companion files |
+| PLINK1 | `.bed` + `.bim` + `.fam` | `--format plink1` |
+| BGEN | `.bgen` + `.sample` | Dosage/probability support |
+
+## Methods
+
+```bash
+genoabo --methods
+genoabo --method-info three-marker
+genoabo data.pgen --method auto        # default
+genoabo data.pgen --method common
+genoabo data.pgen --method three-marker
+genoabo data.pgen --method ukb
+genoabo data.pgen --method extended
+```
+
+| Method | Markers | Use case |
+|--------|---------|----------|
+| `common` | rs8176719, rs8176746 | Standard 2-marker inference |
+| `three-marker` | + rs8176747 | East Asian / extra B check |
+| `ukb` | rs8176719, rs8176746, rs505922 | UK Biobank Field 23165 style |
+| `extended` | ISBT YAML (v0.1: A.01, B.01, O.01) | Experimental allele matching |
+
+## Options
+
+```text
+--format auto|vcf|bcf|bgen|pgen|plink1
+--build auto|hg19|hg38|chm13
+--geno-mode auto|hardcall|dosage|probability
+--phase auto|phased|unphased
+--assume-bo / --no-assume-bo
+--min-genotype-prob 0.90
+--dosage-hardcall-threshold 0.1
+--strict-method
+--inspect
+--report PATH.html
+```
+
+## Python API
+
+```python
+from genoabo import ABOCaller
+
+caller = ABOCaller(method="auto", build="auto")
+result = caller.call("ukb.pgen")
+for call in result.calls:
+    print(call.sample.iid, call.abo_group, call.abo_genotype)
+```
+
+## Genome builds
+
+GRCh37/hg19, GRCh38/hg38, and T2T-CHM13v2 are supported. Build auto-detection uses marker coordinates, VCF header metadata, and chromosome lengths. Conflicting evidence returns an error requiring explicit `--build`.
+
+## Citations
+
+Full records are printed by `genoabo --method-info NAME` and in the Citations section of each HTML run report.
+
+- **software** — Yunye He. genoABO: genetically determined ABO blood group inference from genotype datasets. Version 0.1.0. 2026. [https://github.com/cloufield/genoABO](https://github.com/cloufield/genoABO).
+- **common** — Melzer D, Perry JRB, Hernandez D, Corsi AM, Stevens K, Rafferty I, et al. A genome-wide association study identifies protein quantitative trait loci (pQTLs). *PLoS Genet*. 2008;4:e1000072. [DOI: 10.1371/journal.pgen.1000072](https://doi.org/10.1371/journal.pgen.1000072). PMID: [18464913](https://pubmed.ncbi.nlm.nih.gov/18464913/).
+- **three-marker** — Fry AE, Griffiths MJ, Auburn S, Diakite M, Forton JT, Green A, et al. Common variation in the ABO glycosyltransferase is associated with susceptibility to severe *Plasmodium falciparum* malaria. *Hum Mol Genet*. 2008;17:567–576. [DOI: 10.1093/hmg/ddm331](https://doi.org/10.1093/hmg/ddm331). PMID: [18003641](https://pubmed.ncbi.nlm.nih.gov/18003641/).
+- **ukb** — UK Biobank. Data-Field 23165: Blood-type haplotype. [https://biobank.ndph.ox.ac.uk/showcase/field.cgi?id=23165](https://biobank.ndph.ox.ac.uk/showcase/field.cgi?id=23165).
+- **extended** — Daniels GL, Fletcher A, Garratty G, Henry S, Jørgensen J, Judd WJ, et al. Blood group terminology 2004: from the International Society of Blood Transfusion committee on terminology for red cell surface antigens. *Vox Sang*. 2004;87:304–316. [DOI: 10.1111/j.1423-0410.2004.00564.x](https://doi.org/10.1111/j.1423-0410.2004.00564.x). PMID: [15585029](https://pubmed.ncbi.nlm.nih.gov/15585029/).
+
+See [Inference methods](docs/methods.md) for used-in and molecular-basis notes.
+
+## Documentation
+
+Preview the docs site locally:
+
+```bash
+pip install -e ".[docs]"
+./serve.sh           # http://127.0.0.1:8000
+zensical build       # writes ./site/
+```
+
+- [Inference methods](docs/methods.md)
+- [Marker coordinates](docs/markers.md)
+- [Assumptions and limitations](docs/assumptions.md)
+- [Examples](examples/)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

genoabo-0.1.0/README.md

@@ -0,0 +1,116 @@
+# genoABO
+
+**genoABO** infers genetically determined ABO blood group from VCF, BGEN, PGEN, and PLINK genotype datasets.
+
+```bash
+pip install genoabo
+genoabo biobank.pgen --out bloodgroup
+```
+
+> **Research use only.** genoABO is intended for population-genetics, epidemiology, GWAS, PheWAS, and biobank research. Genotype-inferred ABO groups do not capture all rare, weak, cis-AB, structural, or otherwise atypical ABO alleles and **must not** be used for transfusion or clinical decision-making.
+
+## Quick start
+
+```bash
+genoabo cohort.pgen --out abo
+# writes: abo.abo.tsv, abo.qc.tsv, abo.summary.txt, abo.report.html
+```
+
+See [docs/workflow.md](docs/workflow.md) for the full load-to-output pipeline.
+
+See [examples/](examples/) for VCF (unphased and phased), PGEN, and PLINK1 demos across builds and marker notations, a 1000 Genomes EAS four-marker example (phased `--phase auto`, or forced unphased), and a multi-ancestry `--assume-bo` check against phased 1KG AFR/AMR/EAS/EUR.
+
+Inspect markers without calling:
+
+```bash
+genoabo cohort.pgen --inspect
+```
+
+## Supported formats
+
+| Format | Extensions | Notes |
+|--------|------------|-------|
+| VCF/BCF | `.vcf`, `.vcf.gz`, `.bcf` | GT, phased GT, DS, GP |
+| PLINK2 | `.pgen` + `.pvar` + `.psam` | Auto-locates companion files |
+| PLINK1 | `.bed` + `.bim` + `.fam` | `--format plink1` |
+| BGEN | `.bgen` + `.sample` | Dosage/probability support |
+
+## Methods
+
+```bash
+genoabo --methods
+genoabo --method-info three-marker
+genoabo data.pgen --method auto        # default
+genoabo data.pgen --method common
+genoabo data.pgen --method three-marker
+genoabo data.pgen --method ukb
+genoabo data.pgen --method extended
+```
+
+| Method | Markers | Use case |
+|--------|---------|----------|
+| `common` | rs8176719, rs8176746 | Standard 2-marker inference |
+| `three-marker` | + rs8176747 | East Asian / extra B check |
+| `ukb` | rs8176719, rs8176746, rs505922 | UK Biobank Field 23165 style |
+| `extended` | ISBT YAML (v0.1: A.01, B.01, O.01) | Experimental allele matching |
+
+## Options
+
+```text
+--format auto|vcf|bcf|bgen|pgen|plink1
+--build auto|hg19|hg38|chm13
+--geno-mode auto|hardcall|dosage|probability
+--phase auto|phased|unphased
+--assume-bo / --no-assume-bo
+--min-genotype-prob 0.90
+--dosage-hardcall-threshold 0.1
+--strict-method
+--inspect
+--report PATH.html
+```
+
+## Python API
+
+```python
+from genoabo import ABOCaller
+
+caller = ABOCaller(method="auto", build="auto")
+result = caller.call("ukb.pgen")
+for call in result.calls:
+    print(call.sample.iid, call.abo_group, call.abo_genotype)
+```
+
+## Genome builds
+
+GRCh37/hg19, GRCh38/hg38, and T2T-CHM13v2 are supported. Build auto-detection uses marker coordinates, VCF header metadata, and chromosome lengths. Conflicting evidence returns an error requiring explicit `--build`.
+
+## Citations
+
+Full records are printed by `genoabo --method-info NAME` and in the Citations section of each HTML run report.
+
+- **software** — Yunye He. genoABO: genetically determined ABO blood group inference from genotype datasets. Version 0.1.0. 2026. [https://github.com/cloufield/genoABO](https://github.com/cloufield/genoABO).
+- **common** — Melzer D, Perry JRB, Hernandez D, Corsi AM, Stevens K, Rafferty I, et al. A genome-wide association study identifies protein quantitative trait loci (pQTLs). *PLoS Genet*. 2008;4:e1000072. [DOI: 10.1371/journal.pgen.1000072](https://doi.org/10.1371/journal.pgen.1000072). PMID: [18464913](https://pubmed.ncbi.nlm.nih.gov/18464913/).
+- **three-marker** — Fry AE, Griffiths MJ, Auburn S, Diakite M, Forton JT, Green A, et al. Common variation in the ABO glycosyltransferase is associated with susceptibility to severe *Plasmodium falciparum* malaria. *Hum Mol Genet*. 2008;17:567–576. [DOI: 10.1093/hmg/ddm331](https://doi.org/10.1093/hmg/ddm331). PMID: [18003641](https://pubmed.ncbi.nlm.nih.gov/18003641/).
+- **ukb** — UK Biobank. Data-Field 23165: Blood-type haplotype. [https://biobank.ndph.ox.ac.uk/showcase/field.cgi?id=23165](https://biobank.ndph.ox.ac.uk/showcase/field.cgi?id=23165).
+- **extended** — Daniels GL, Fletcher A, Garratty G, Henry S, Jørgensen J, Judd WJ, et al. Blood group terminology 2004: from the International Society of Blood Transfusion committee on terminology for red cell surface antigens. *Vox Sang*. 2004;87:304–316. [DOI: 10.1111/j.1423-0410.2004.00564.x](https://doi.org/10.1111/j.1423-0410.2004.00564.x). PMID: [15585029](https://pubmed.ncbi.nlm.nih.gov/15585029/).
+
+See [Inference methods](docs/methods.md) for used-in and molecular-basis notes.
+
+## Documentation
+
+Preview the docs site locally:
+
+```bash
+pip install -e ".[docs]"
+./serve.sh           # http://127.0.0.1:8000
+zensical build       # writes ./site/
+```
+
+- [Inference methods](docs/methods.md)
+- [Marker coordinates](docs/markers.md)
+- [Assumptions and limitations](docs/assumptions.md)
+- [Examples](examples/)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

genoabo-0.1.0/genoabo/data/alleles.yaml

@@ -0,0 +1,33 @@
+# Extended method allele definitions — v0.1 minimal set only.
+# ISBT nomenclature; not clinical blood typing.
+
+isbt_database:
+  name: "ISBT Blood Group Database / BGMUT"
+  url: "https://www.isbtweb.org/blood-group-terminology/"
+  version_note: "Record version at release; nomenclature evolves"
+
+alleles:
+  ABO*O.01:
+    phenotype: O
+    description: "Common O allele (261delG)"
+    variants:
+      rs8176719: O_DEL
+    haplotype_state: O
+
+  ABO*B.01:
+    phenotype: B
+    description: "Common B allele"
+    variants:
+      rs8176719: NON_O
+      rs8176746: B_ALLELE
+      rs8176747: B_ALLELE
+    haplotype_state: B
+
+  ABO*A.01:
+    phenotype: A
+    description: "Common A allele"
+    variants:
+      rs8176719: NON_O
+      rs8176746: A_ALLELE
+      rs8176747: A_ALLELE
+    haplotype_state: A

genoabo-0.1.0/genoabo/data/assemblies.yaml

@@ -0,0 +1,78 @@
+# Assembly registry — all coordinates must cite a source.
+# CHM13v2 packaged positions are UCSC hg38-chm13v2.over.chain.gz liftOver from GRCh38.
+# scripts/derive_chm13_markers.py is an optional alternative (dbSNP VCF scan).
+
+GRCh37:
+  aliases: [hg19, GRCh37.p13]
+  chr9_length: 141213431
+  chr9_source: "NCBI NC_000009.11"
+  contigs:
+    "9":
+      aliases: [chr9, NC_000009.11]
+  markers:
+    rs8176719:
+      chrom: "9"
+      pos: 136132908
+      source: "dbSNP rs8176719 NC_000009.11"
+    rs8176746:
+      chrom: "9"
+      pos: 136131322
+      source: "dbSNP rs8176746 NC_000009.11"
+    rs8176747:
+      chrom: "9"
+      pos: 136131315
+      source: "dbSNP rs8176747 NC_000009.11"
+    rs505922:
+      chrom: "9"
+      pos: 136149229
+      source: "dbSNP rs505922 NC_000009.11"
+
+GRCh38:
+  aliases: [hg38, GRCh38.p14]
+  chr9_length: 138394717
+  chr9_source: "NCBI NC_000009.12"
+  contigs:
+    "9":
+      aliases: [chr9, NC_000009.12]
+  markers:
+    rs8176719:
+      chrom: "9"
+      pos: 133257521
+      source: "dbSNP rs8176719 NC_000009.12"
+    rs8176746:
+      chrom: "9"
+      pos: 133255935
+      source: "dbSNP rs8176746 NC_000009.12"
+    rs8176747:
+      chrom: "9"
+      pos: 133255928
+      source: "dbSNP rs8176747 NC_000009.12"
+    rs505922:
+      chrom: "9"
+      pos: 133273813
+      source: "dbSNP rs505922 NC_000009.12"
+
+CHM13v2:
+  aliases: [chm13, T2T-CHM13v2, hs1]
+  chr9_length: 150617247
+  chr9_source: "T2T-CHM13v2.0 NC_060925.1"
+  contigs:
+    "9":
+      aliases: [chr9, NC_060925.1]
+  markers:
+    rs8176719:
+      chrom: "9"
+      pos: 145471385
+      source: "UCSC hg38-chm13v2.over.chain.gz liftOver from GRCh38:133257521"
+    rs8176746:
+      chrom: "9"
+      pos: 145469798
+      source: "UCSC hg38-chm13v2.over.chain.gz liftOver from GRCh38:133255935"
+    rs8176747:
+      chrom: "9"
+      pos: 145469791
+      source: "UCSC hg38-chm13v2.over.chain.gz liftOver from GRCh38:133255928"
+    rs505922:
+      chrom: "9"
+      pos: 145487688
+      source: "UCSC hg38-chm13v2.over.chain.gz liftOver from GRCh38:133273813"

genoabo-0.1.0/genoabo/data/citations.yaml

@@ -0,0 +1,136 @@
+software:
+  title: "genoABO: genetically determined ABO blood group inference from genotype datasets"
+  authors: "Yunye He"
+  year: 2026
+  version: "0.1.0"
+  url: "https://github.com/cloufield/genoABO"
+  license: MIT
+
+# role: primary = first description of this typing scheme (or operational spec)
+#       used_in = later application that used the same markers
+#       molecular = molecular allele definitions, not a SNP typing paper
+methods:
+  common:
+    description: "Common 2-marker inference using rs8176719 and rs8176746"
+    references:
+      - role: primary
+        doi: "10.1371/journal.pgen.1000072"
+        pmid: "18464913"
+        title: "A genome-wide association study identifies protein quantitative trait loci (pQTLs)"
+        authors: "Melzer D, Perry JRB, Hernandez D, Corsi AM, Stevens K, Rafferty I, et al."
+        journal: "PLoS Genet"
+        year: 2008
+        volume: "4"
+        pages: "e1000072"
+        note: "Recoded ABO from a two-SNP haplotype of rs8176746 and rs8176719"
+      - role: used_in
+        doi: "10.1161/ATVBAHA.119.313658"
+        pmid: "31969017"
+        title: "Genetically Determined ABO Blood Group and its Associations With Health and Disease"
+        authors: "Groot HE, Villegas Sierra LE, Said MA, Lipsic E, Karper JC, van der Harst P"
+        journal: "Arterioscler Thromb Vasc Biol"
+        year: 2020
+        volume: "40"
+        pages: "830-838"
+        note: "UK Biobank (n=406,755); inferred ABO from rs8176719 and rs8176746"
+
+  three-marker:
+    description: "3-marker inference using rs8176719, rs8176746, and rs8176747"
+    references:
+      - role: primary
+        doi: "10.1093/hmg/ddm331"
+        pmid: "18003641"
+        title: "Common variation in the ABO glycosyltransferase is associated with susceptibility to severe Plasmodium falciparum malaria"
+        authors: "Fry AE, Griffiths MJ, Auburn S, Diakite M, Forton JT, Green A, et al."
+        journal: "Hum Mol Genet"
+        year: 2008
+        volume: "17"
+        pages: "567-576"
+        note: "Designed large-scale assays for rs8176719, rs8176746, and rs8176747 (plus rs8176743)"
+      - role: used_in
+        doi: "10.1111/j.1349-7006.2011.01907.x"
+        pmid: "21306478"
+        title: "ABO blood group alleles and the risk of pancreatic cancer in a Japanese population"
+        authors: "Nakao M, Matsuo K, Hosono S, Ogata S, Ito H, Watanabe M, et al."
+        journal: "Cancer Sci"
+        year: 2011
+        volume: "102"
+        pages: "1076-1080"
+      - role: used_in
+        doi: "10.1038/s41588-021-00931-x"
+        pmid: "34594039"
+        title: "A cross-population atlas of genetic associations for 220 human phenotypes"
+        authors: "Sakaue S, Kanai M, Tanigawa Y, et al."
+        journal: "Nat Genet"
+        year: 2021
+        volume: "53"
+        pages: "1415-1424"
+        note: "BBJ, UKB, and FinnGen (ntotal ≈ 628,000); estimated ABO from rs8176747, rs8176746, and rs8176719 (preprint 2020)"
+      - role: used_in
+        doi: "10.1002/ajh.26307"
+        pmid: "34329492"
+        title: "Characterization of the human ABO genotypes and their association to common inflammatory and cardiovascular diseases in the UK Biobank"
+        authors: "Höglund J, Karlsson T, Johansson T, Ek WE, Johansson Å"
+        journal: "Am J Hematol"
+        year: 2021
+        volume: "96"
+        pages: "1350-1362"
+        note: "UK Biobank; inferred ABO genotypes from rs8176719, rs8176746, and rs8176747"
+
+  ukb:
+    description: "UK Biobank Field 23165 blood-type haplotype inference"
+    references:
+      - role: primary
+        url: "https://biobank.ndph.ox.ac.uk/showcase/field.cgi?id=23165"
+        title: "UK Biobank Data-Field 23165: Blood-type haplotype"
+        authors: "UK Biobank"
+        year: 2020
+        note: "Operational specification: rs8176719 deletion = O; rs505922 T as O proxy when rs8176719 is missing; rs8176746 T = B"
+      - role: used_in
+        doi: "10.1371/journal.pgen.1000072"
+        pmid: "18464913"
+        title: "A genome-wide association study identifies protein quantitative trait loci (pQTLs)"
+        authors: "Melzer D, Perry JRB, Hernandez D, Corsi AM, Stevens K, Rafferty I, et al."
+        journal: "PLoS Genet"
+        year: 2008
+        volume: "4"
+        pages: "e1000072"
+        note: "Cited by Field 23165; two-SNP ABO recoding and rs505922"
+      - role: used_in
+        doi: "10.1371/journal.pgen.1000118"
+        pmid: "18604267"
+        title: "Novel association of ABO histo-blood group antigen with soluble ICAM-1: results of a genome-wide association study of 6,578 women"
+        authors: "Paré G, Chasman DI, Kellogg M, Zee RYL, Rifai N, Badola S, Miletich JP, Ridker PM"
+        journal: "PLoS Genet"
+        year: 2008
+        volume: "4"
+        pages: "e1000118"
+        note: "Cited by Field 23165"
+
+  extended:
+    description: "ISBT allele nomenclature reference (v0.1 limited subset)"
+    references:
+      - role: primary
+        doi: "10.1111/j.1423-0410.2004.00564.x"
+        pmid: "15585029"
+        title: "Blood group terminology 2004: from the International Society of Blood Transfusion committee on terminology for red cell surface antigens"
+        authors: "Daniels GL, Fletcher A, Garratty G, Henry S, Jørgensen J, Judd WJ, et al."
+        journal: "Vox Sang"
+        year: 2004
+        volume: "87"
+        pages: "304-316"
+      - role: primary
+        url: "https://blooddatabase.isbtweb.org/"
+        title: "ISBT Blood Group Database"
+        authors: "International Society of Blood Transfusion Working Party on Red Cell Immunogenetics and Blood Group Terminology"
+        note: "Authoritative allele tables; nomenclature evolves. Accessed 2026-09"
+      - role: molecular
+        doi: "10.1038/345229a0"
+        pmid: "2333095"
+        title: "Molecular genetic basis of the histo-blood group ABO system"
+        authors: "Yamamoto F, Clausen H, White T, Marken J, Hakomori S"
+        journal: "Nature"
+        year: 1990
+        volume: "345"
+        pages: "229-233"
+        note: "Molecular definitions underlying ABO*A.01, ABO*B.01, and ABO*O.01"

genoabo-0.1.0/genoabo/data/markers.yaml

@@ -0,0 +1,105 @@
+# Biological marker definitions — independent of VCF REF/ALT orientation.
+# See docs/markers.md for coordinate provenance.
+
+rs8176719:
+  role: O_defining
+  transcript: "NM_020469.4:c.261delG"
+  description: "Major common O-defining loss-of-function (261delG)"
+  states:
+    O_DEL:
+      description: "261G deleted — functional O allele (ABO*O.01 background)"
+      copies: 0
+    NON_O:
+      description: "261G present — A or B functional background"
+      copies: 1
+  # Common VCF representations on GRCh37/38 (O = reference, A/B = insC)
+  representations:
+    - note: "GRCh38 O reference — insertion alt"
+      ref: "G"
+      alt: ["GC"]
+      state: NON_O
+    - note: "GRCh38 O reference — no alt (homozygous O)"
+      ref: "G"
+      alt: []
+      state: O_DEL
+    - note: "Legacy deletion notation"
+      ref: "G"
+      alt: ["G-"]
+      state: O_DEL
+    - note: "Insertion on O-ref representing NON_O"
+      ref: "G"
+      alt: ["GinsC"]
+      state: NON_O
+    - note: "Left-aligned 1KG / normalized VCF (T:TC instead of G:GC)"
+      ref: "T"
+      alt: ["TC"]
+      state: NON_O
+    - note: "Left-aligned O reference (T, no alt)"
+      ref: "T"
+      alt: []
+      state: O_DEL
+
+rs8176746:
+  role: AB_differentiating
+  transcript: "NM_020469.4:c.796C>A"
+  description: "Major A/B differentiating variant (796C>A, Leu266Met on B)"
+  states:
+    A_ALLELE:
+      description: "796C — A-associated"
+    B_ALLELE:
+      description: "796A — B-associated (VCF may show T on forward strand)"
+  representations:
+    - note: "Forward strand G ref, A alt"
+      ref: "G"
+      alt: ["A"]
+      state: B_ALLELE
+    - note: "Homozygous A background"
+      ref: "G"
+      alt: []
+      state: A_ALLELE
+    - note: "Alternate T notation (UKB field 23165)"
+      ref: "G"
+      alt: ["T"]
+      state: B_ALLELE
+
+rs8176747:
+  role: AB_differentiating
+  transcript: "NM_020469.4:c.803G>C"
+  description: "Additional A/B differentiating variant (803G>C)"
+  states:
+    A_ALLELE:
+      description: "803G — A-associated"
+    B_ALLELE:
+      description: "803C — B-associated"
+  representations:
+    - note: "Forward strand G ref, C alt"
+      ref: "G"
+      alt: ["C"]
+      state: B_ALLELE
+    - note: "Homozygous A background"
+      ref: "G"
+      alt: []
+      state: A_ALLELE
+    - note: "GRCh38 / 1KG C ref, G alt"
+      ref: "C"
+      alt: ["G"]
+      state: B_ALLELE
+
+rs505922:
+  role: O_proxy
+  transcript: null
+  description: "Proxy marker for O-related haplotype inference (LD with ABO O)"
+  states:
+    O_PROXY:
+      description: "T allele — proxy indicator for O haplotype (UKB fallback)"
+    NON_O_PROXY:
+      description: "C allele — not O proxy indicator"
+  representations:
+    - note: "Standard dbSNP"
+      ref: "C"
+      alt: ["T"]
+      state: O_PROXY
+    - note: "Homozygous non-O proxy"
+      ref: "C"
+      alt: []
+      state: NON_O_PROXY

genoabo-0.1.0/genoabo/data/methods.yaml

@@ -0,0 +1,74 @@
+methods:
+  common:
+    name: common
+    description: "Common 2-marker inference (rs8176719 + rs8176746)"
+    markers: [rs8176719, rs8176746]
+    outputs: [ABO_group, ABO_genotype]
+    min_markers: [rs8176719, rs8176746]
+    report:
+      logic:
+        - "Markers: rs8176719 (O deletion) and rs8176746 (A/B differentiator)."
+        - "If rs8176719 is O_DEL on a haplotype, that haplotype is O."
+        - "Otherwise rs8176746 B_ALLELE yields B and A_ALLELE yields A."
+        - "Infers the six common diplotypes A/A, A/O, B/B, B/O, A/B, and O/O when uniquely determined."
+        - "When both markers are heterozygous and unphased, --assume-bo (default) assigns B/O; --no-assume-bo leaves the call ambiguous (A/O or B/O)."
+      limitations:
+        - "Rare ABO alleles can violate the two-marker assumptions and may be misclassified."
+        - "The default --assume-bo rule (O deletion on an A background → B/O) is a common-allele assumption. Phased 1000 Genomes 30x hg38: AMR/EAS/EUR double-hets were all B/O; AFR 8/113 were A/O. Pass --no-assume-bo to leave those samples ambiguous."
+
+  three-marker:
+    name: three-marker
+    description: "3-marker inference (+ rs8176747); useful for East Asian datasets"
+    markers: [rs8176719, rs8176746, rs8176747]
+    outputs: [ABO_group, ABO_genotype]
+    min_markers: [rs8176719, rs8176746, rs8176747]
+    report:
+      logic:
+        - "Markers: rs8176719, rs8176746, and rs8176747 (additional A/B check)."
+        - "Haplotype rules match the common method, with rs8176747 confirming B vs A."
+        - "If rs8176746 and rs8176747 disagree on B vs A, a QC warning is raised and confidence is low."
+      limitations:
+        - "Marker disagreement between rs8176746 and rs8176747 is flagged, not resolved into a forced phenotype."
+
+  ukb:
+    name: ukb
+    description: "UK Biobank Field 23165 style (rs8176719, rs8176746, rs505922 proxy)"
+    markers: [rs8176719, rs8176746, rs505922]
+    outputs: [ABO_group, ABO_genotype, ukb_haplotype]
+    min_markers: [rs8176746]
+    proxy_markers: [rs505922]
+    report:
+      logic:
+        - "Implements UK Biobank Data-Field 23165 haplotype logic."
+        - "rs8176719 O_DEL indicates an O haplotype on that chromosome."
+        - "If rs8176719 is missing, rs505922 O_PROXY (T) is used as an O proxy and confidence is capped at low."
+        - "rs8176746 B_ALLELE indicates a B haplotype; otherwise a non-O haplotype is treated as A."
+        - "Output includes UKB-style haplotype codes: AA, AO, BO, BB, AB, OO."
+      limitations:
+        - "Proxy inference with rs505922 is not equivalent to typing the functional O deletion."
+
+  extended:
+    name: extended
+    description: "Curated ISBT allele definitions (v0.1: A.01, B.01, O.01 only)"
+    markers: [rs8176719, rs8176746, rs8176747]
+    outputs: [ABO_group, ABO_genotype, ISBT_alleles]
+    min_markers: [rs8176719]
+    report:
+      logic:
+        - "Match phased or resolved haplotypes against ISBT allele patterns in alleles.yaml."
+        - "v0.1 recognises ABO*A.01, ABO*B.01, and ABO*O.01 only."
+        - "If no pattern matches, ABO_group is unknown; classification is not forced."
+      limitations:
+        - "Not an ISBT-comprehensive typing method; unmatched alleles remain unknown."
+
+auto_selection:
+  - method: three-marker
+    requires: [rs8176719, rs8176746, rs8176747]
+    reason: "rs8176719, rs8176746 and rs8176747 available"
+  - method: common
+    requires: [rs8176719, rs8176746]
+    reason: "rs8176719 and rs8176746 available"
+  - method: ukb
+    requires: [rs8176746, rs505922]
+    reason: "rs8176746 and rs505922 available (proxy mode)"
+    confidence_cap: low

genoabo-0.1.0/genoabo/data/report.yaml

@@ -0,0 +1,151 @@
+disclaimer: >-
+  Research use only. Genotype-inferred ABO groups do not capture all rare, weak,
+  cis-AB, structural, or otherwise atypical ABO alleles and must not be used for
+  transfusion or clinical decision-making.
+
+pipeline:
+  - >-
+    genoABO fetches only ABO tag SNPs (rs8176719, rs8176746, rs8176747, rs505922)
+    from the input file. Variants are matched by rsID, contig and position (including
+    chr-prefixed and RefSeq contig aliases), then by allele-aware keys.
+  - >-
+    Genome build is resolved from marker coordinates, file-header metadata, and
+    contig lengths, or taken from an explicit --build setting. Conflicting evidence
+    is an error; the build is never guessed silently.
+  - >-
+    Per-sample genotypes are interpreted from hardcalls (GT), dosage (DS), or
+    genotype probabilities (GP) according to the selected genotype mode. REF/ALT
+    alleles are then mapped to biological marker states. Inference rules never
+    operate on raw VCF alleles.
+  - >-
+    The selected method applies haplotype and diplotype rules and emits ABO_group,
+    ABO_genotype, confidence, and QC fields.
+
+diplotype_phenotype:
+  - {diplotype: "A/A", phenotype: "A"}
+  - {diplotype: "A/O", phenotype: "A"}
+  - {diplotype: "B/B", phenotype: "B"}
+  - {diplotype: "B/O", phenotype: "B"}
+  - {diplotype: "A/B", phenotype: "AB"}
+  - {diplotype: "O/O", phenotype: "O"}
+
+confidence:
+  - level: high
+    criteria: Direct functional markers; consistent genotypes; phase sufficient
+  - level: medium
+    criteria: Unphased but uniquely inferable
+  - level: low
+    criteria: Proxy marker, uncertain dosage, or unusual marker combinations
+  - level: none
+    criteria: Insufficient or conflicting evidence
+
+confidence_note: Confidence is not a calibrated probability.
+
+genotype_modes:
+  - mode: hardcall
+    behavior: Discrete GT (0/0, 0/1, 1/1, or phased)
+  - mode: dosage
+    behavior: Threshold ALT dosage into 0/1/2 copies; otherwise uncertain
+  - mode: probability
+    behavior: Argmax GP if max(P) meets the minimum probability threshold; otherwise uncertain
+  - mode: auto
+    behavior: GP, then DS, then hardcall GT, in that order of precedence
+
+abo_group_meaning: >-
+  ABO_group is the inferred phenotype (A, B, AB, or O). unknown means the method
+  could not assign a group. ABO_genotype is the diplotype (for example A/O);
+  ambiguous means more than one diplotype was compatible with the unphased genotypes.
+  Population A/B/AB/O percentages are informational only; samples are never rejected
+  for frequency deviation.
+
+abo_columns:
+  - {name: FID, description: "Family or cohort identifier from the input file"}
+  - {name: IID, description: "Individual sample identifier"}
+  - {name: ABO_group, description: "Inferred phenotype: A, B, AB, O, or unknown"}
+  - {name: ABO_genotype, description: "Diplotype label (for example A/O), or ambiguous"}
+  - {name: ABO_allele1, description: "First haplotype allele after alphabetical sort (A < B < O)"}
+  - {name: ABO_allele2, description: "Second haplotype allele after alphabetical sort"}
+  - {name: haplotype1, description: "Haplotype call on chromosome copy 1"}
+  - {name: haplotype2, description: "Haplotype call on chromosome copy 2"}
+  - {name: method, description: "Inference method used for this sample"}
+  - {name: geno_mode, description: "Genotype interpretation mode (hardcall, dosage, probability, auto)"}
+  - {name: phase_mode, description: "Whether haplotypes used phase (phased) or enumeration (unphased)"}
+  - {name: build, description: "Genome assembly used for marker coordinates"}
+  - {name: confidence, description: "high, medium, low, or none (not a calibrated probability)"}
+  - {name: qc_status, description: "PASS, AMBIGUOUS, MISSING_MARKER, CONFLICT, or LOW_CONFIDENCE"}
+  - {name: qc_reason, description: "Free-text explanation of QC status"}
+  - {name: possible_diplotypes, description: "Compatible diplotypes when ABO_genotype is ambiguous"}
+  - {name: ukb_haplotype, description: "UK Biobank Field 23165 haplotype code (ukb method only)"}
+  - {name: isbt_alleles, description: "Matched ISBT allele IDs (extended method only)"}
+
+limitations:
+  - >-
+    Common A/B/O/AB inference uses four SNP markers and six common diplotypes under
+    standard assumptions. Rare, weak, cis-AB, null, hybrid, and structural ABO alleles
+    may be misclassified.
+  - >-
+    Non-deletional O alleles are not modelled. The extended method is limited to
+    ABO*A.01, ABO*B.01, and ABO*O.01; it is not ISBT-comprehensive.
+  - >-
+    rs505922 is an LD proxy for the O haplotype, not a functional variant. When it is
+    used (UKB fallback), confidence is capped at low.
+  - >-
+    On GRCh37/GRCh38 the reference allele at rs8176719 is the O-associated sequence.
+    VCF files often encode an insertion for A/B rather than a deletion for O;
+    normalization is required and representation varies by pipeline.
+  - >-
+    The default --assume-bo rule (O deletion on an A background, resolving
+    unphased double heterozygotes to B/O rather than A/O) is a common-allele
+    assumption. On 1000 Genomes 30x hg38 (phased GT, not serology), AMR/EAS/EUR
+    double-hets were all B/O; AFR 8/113 were A/O. Pass --no-assume-bo to mark
+    those samples ambiguous.
+  - >-
+    Low imputation INFO, missing genotypes, and uncertain dosages propagate to
+    low-confidence or unknown calls.
+  - >-
+    genoABO has not been validated against serological typing across ancestries.
+    Outputs are intended for population-genetics, epidemiology, GWAS, PheWAS, and
+    biobank research.
+
+determination:
+  intro: >-
+    ABO phenotype is inferred from biological marker states after REF/ALT
+    normalization, not from raw VCF alleles. The selected method of this run
+    is named below; unused markers are shown for reference.
+  marker_roles:
+    caption: Tag SNPs used for ABO inference and their biological states.
+    columns: [Marker, HGVS, States, Role]
+    rows:
+      - [rs8176719, "c.261delG", "O_DEL / NON_O", "O vs A/B background"]
+      - [rs8176746, "c.796C>A", "A_ALLELE / B_ALLELE", "A vs B"]
+      - [rs8176747, "c.803G>C", "A_ALLELE / B_ALLELE", "A vs B confirmation (three-marker)"]
+      - [rs505922, "—", "O_PROXY / NON_O_PROXY", "LD proxy for O (ukb only; not functional)"]
+  haplotype:
+    caption: Haplotype call on each chromosome copy.
+    columns: [Condition, Haplotype]
+    rows:
+      - ["rs8176719 = O_DEL", O]
+      - ["else rs8176746 = B_ALLELE (and rs8176747 = B_ALLELE when three-marker)", B]
+      - ["else rs8176746 = A_ALLELE", A]
+      - ["else", unknown]
+    note: >-
+      If rs8176746 and rs8176747 disagree on B vs A, a QC warning is raised and
+      confidence is low.
+  diplotype_from_markers:
+    caption: >-
+      Unphased diploid combinations of rs8176719 and rs8176746 (common and
+      three-marker). States are biological, not REF/ALT.
+    columns: [rs8176719, rs8176746, Diplotype, Phenotype]
+    rows:
+      - ["O_DEL / O_DEL", any, O/O, O]
+      - ["NON_O / NON_O", "A / A", A/A, A]
+      - ["O_DEL / NON_O", "A / A", A/O, A]
+      - ["NON_O / NON_O", "B / B", B/B, B]
+      - ["O_DEL / NON_O", "A / B", B/O, "B (--assume-bo default)"]
+      - ["NON_O / NON_O", "A / B", A/B, AB]
+    notes:
+      - "three-marker also requires rs8176747 to agree with rs8176746."
+      - "ukb may substitute rs505922 as an O proxy; confidence is then capped at low."
+      - "Inference rules never operate on raw VCF REF/ALT."
+      - "--no-assume-bo leaves O_DEL/NON_O × A/B ambiguous (A/O or B/O)."
+

genoabo-0.1.0/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "genoabo"
+version = "0.1.0"
+description = "Genetically determined ABO blood group inference from genotype datasets"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "Yunye He" }]
+keywords = ["ABO", "blood-group", "genotype", "GWAS", "biobank", "bioinformatics"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+    "cyvcf2>=0.30",
+    "Pgenlib>=0.94",
+    "bgen-reader>=4.0",
+    "numpy>=1.24",
+    "pyyaml>=6.0",
+    "typer>=0.9",
+    "rich>=13.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4",
+    "pytest-cov>=4.1",
+    "ruff>=0.1",
+    "mypy>=1.5",
+    "types-PyYAML>=6.0",
+]
+bgenix = ["bgenix>=1.1"]
+docs = ["zensical"]
+
+[project.scripts]
+genoabo = "genoabo.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/cloufield/genoABO"
+Repository = "https://github.com/cloufield/genoABO"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/genoabo"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/genoabo/data/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+ignore_missing_imports = true
+
+[tool.hatch.build]
+sources = ["src"]