Metadata-Version: 2.5
Name: genosecretor
Version: 0.3.0
Summary: Genetically determined FUT2 secretor status inference from genotype datasets
Project-URL: Homepage, https://github.com/cloufield/genoSecretor
Project-URL: Repository, https://github.com/cloufield/genoSecretor
Project-URL: Documentation, https://cloufield.github.io/genoSecretor/
Project-URL: Issues, https://github.com/cloufield/genoSecretor/issues
Author: Yunye He
License-Expression: MIT
License-File: LICENSE
Keywords: FUT2,GWAS,biobank,bioinformatics,genotype,secretor
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: 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

# genoSecretor

**genoSecretor** infers genetically determined FUT2 secretor status from VCF, BGEN, PGEN, and PLINK genotype datasets.

```bash
pip install genosecretor
genosecretor biobank.pgen --out secretor
```

> **Research use only.** genoSecretor is intended for population-genetics, epidemiology, GWAS, PheWAS, and biobank research. Genotype-inferred secretor status does not capture all rare or atypical FUT2 alleles and **must not** be used for clinical decision-making.

## Quick start

```bash
genosecretor cohort.pgen --out secretor
# writes: secretor.secretor.tsv, secretor.qc.tsv, secretor.summary.txt, secretor.report.html
```

See [docs/usage.md](docs/usage.md) for the full CLI and Python API.

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 (`./examples/run_synthetic.sh`), plus 1000 Genomes FUT2 slices and an `--assume-trans` vs phase check.

Inspect markers without calling:

```bash
genosecretor cohort.pgen --inspect
```

## Supported formats

| Format | Extensions | Notes |
|--------|------------|-------|
| VCF/BCF | `.vcf`, `.vcf.gz`, `.bcf` | GT, phased GT, DS, GP. BCF is reported as `BCF`. |
| PLINK2 | `.pgen` + `.pvar` + `.psam` | Auto-locates companion files |
| PLINK1 | `.bed` + `.bim` + `.fam` | Auto-detected from `.bed`; `--format plink1` also works |
| BGEN | `.bgen` (+ optional `.sample`) | Dosage/probability support. Reader implemented; no bundled BGEN fixture yet. |

## Methods

```bash
genosecretor --methods
genosecretor --method-info two-marker
genosecretor data.pgen --method auto        # default
genosecretor data.pgen --ancestry eas      # require rs1047781; refuse `common` without it
genosecretor data.pgen --method two-marker
genosecretor data.pgen --method common
genosecretor data.pgen --method eas
genosecretor data.pgen --method proxy
```

| Method | Markers | Use case |
|--------|---------|----------|
| `two-marker` | rs601338, rs1047781 | Ancestry-aware se428 + se385 |
| `common` | rs601338 | European/African complete null (W143X) |
| `eas` | rs1047781 | East Asian weak allele (I129F) |
| `proxy` | rs602662 (± rs601338) | GWAS-chip LD proxy for se428 |

Phenotypes: **secretor**, **weak-secretor** (`Se^w/Se^w` or `Se^w/se`), **non-secretor** (`se/se`). `--phenotype-coding gwas` recodes weak-secretor as non-secretor.

## Options

```text
--format auto|vcf|bcf|bgen|pgen|plink1
--build auto|hg19|hg38|chm13   # also GRCh37, GRCh38, CHM13v2, hs1
--method auto|two-marker|common|eas|proxy
--ancestry auto|eas|eur|afr|amr|unknown
--geno-mode auto|hardcall|dosage|probability
--phase auto|phased|unphased
--assume-trans / --no-assume-trans
--phenotype-coding biochemical|gwas
--min-genotype-prob 0.90
--dosage-hardcall-threshold 0.1
--strict-method
--inspect
--methods
--method-info NAME
--version
--report PATH.html
```

Full option list: [docs/usage.md](docs/usage.md).

## Python API

```python
from genosecretor import SecretorCaller

caller = SecretorCaller(method="auto", ancestry="auto", build="auto")
result = caller.call("ukb.pgen")
for call in result.calls:
    print(call.sample.iid, call.secretor_status, call.fut2_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 `genosecretor --method-info NAME` and in the Citations section of each HTML run report.

- **software** — Yunye He. genoSecretor: genetically determined FUT2 secretor status inference from genotype datasets. Version 0.3.0. 2026. [https://github.com/cloufield/genoSecretor](https://github.com/cloufield/genoSecretor).
- **common** — Kelly RJ, Rouquier S, Giorgi D, Lennon GG, Lowe JB. Sequence and expression of a candidate for the human Secretor blood group alpha(1,2)fucosyltransferase gene (FUT2). *J Biol Chem*. 1995;270:4640–4649. [DOI: 10.1074/jbc.270.9.4640](https://doi.org/10.1074/jbc.270.9.4640). PMID: [7876234](https://pubmed.ncbi.nlm.nih.gov/7876234/).
- **two-marker** — Smyth DJ, Cooper JD, Howson JMM, et al. FUT2 nonsecretor status links type 1 diabetes susceptibility and resistance to infection. *Diabetes*. 2011;60:3081–3084. [DOI: 10.2337/db11-0138](https://doi.org/10.2337/db11-0138). PMID: [22042020](https://pubmed.ncbi.nlm.nih.gov/22042020/).
- **eas** — Koda Y, Soejima M, Liu Y, Kimura H. Molecular basis for secretor type α(1,2)-fucosyltransferase gene deficiency in a Japanese population. *J Biol Chem*. 1996;271:7410–7415. [DOI: 10.1074/jbc.271.13.7410](https://doi.org/10.1074/jbc.271.13.7410). PMID: [8631766](https://pubmed.ncbi.nlm.nih.gov/8631766/).
- **proxy** — Barrett JC, Hansoul S, Nicolae DL, et al. Genome-wide association defines more than 30 distinct susceptibility loci for Crohn's disease. *Nat Genet*. 2008;40:955–962. [DOI: 10.1038/ng.215](https://doi.org/10.1038/ng.215). PMID: [18587394](https://pubmed.ncbi.nlm.nih.gov/18587394/).

See [Inference methods](docs/methods.md) for used-in and molecular-basis notes.

## Documentation

[https://cloufield.github.io/genoSecretor/](https://cloufield.github.io/genoSecretor/)

Preview the docs site locally:

```bash
pip install -e ".[docs]"
./serve.sh           # http://127.0.0.1:8000
zensical build       # writes ./site/
```

- [Usage](docs/usage.md)
- [Inference methods](docs/methods.md)
- [Marker coordinates](docs/markers.md) (includes 1000 Genomes LD r²)
- [Assumptions and limitations](docs/assumptions.md)
- [Examples](examples/)
- [Update Log](docs/updatelog.md)

## License

MIT — see [LICENSE](LICENSE).
