GTFound

GTFound 是用于二等位基因型填补的单倍型模型。给定目标样本已观测的等位基因、同位点对齐的参考单倍型、基因组位置及 LD 矩阵，模型预测缺失位置为 REF（0）或 ALT（1）的概率。本仓库提供模型权重、推理代码，以及从 VCF 准备输入和导出 VCF 的命令行工具。

• 作者：Wang Qiyu
• 机构：哈尔滨工业大学（深圳）（HITSZ）
• 训练数据：千人基因组项目（1000 Genomes Project），GRCh38
• 输入单位：一个位置对应参考面板中的一个变异记录，不对应一个碱基
• 模型配置：12 层、12 个注意力头、隐藏维度 768；默认每窗 1024 个面板位点，重叠 128 个位点
• 许可：MIT

模型用于研究用途。仓库未附带参考面板、目标基因型或可直接用于临床解释的校准结果；使用者需要自行准备并核对数据。

目录结构

GTFound/
├── .gitattributes           # 权重文件规则
├── .gitignore               # 忽略生成文件
├── README.md                 # 模型介绍与使用入口
├── VCF_PIPELINE.md           # VCF 对齐、LD、窗口和输出细节
├── model.safetensors         # 模型权重
├── SHA256SUMS                # 权重校验值
├── config.json               # 模型结构配置
├── vocab.txt                 # 固定词表
├── pyproject.toml            # 安装配置及 gtfound 命令
├── requirements.txt          # Python 依赖
├── gtfound/
│   ├── __init__.py
│   ├── cli.py                # prepare-vcf / infer / export-vcf
│   ├── vcf_pipeline.py       # VCF、PLINK LD 与窗口处理
│   ├── inference.py          # 加载权重和推理接口
│   ├── modeling_gtfound.py   # 模型主体
│   ├── layers_gtfound.py     # 注意力和模型层
│   ├── heads_gtfound.py      # 输出头
│   └── vocab_gtfound.py      # 词表读取
├── LICENSE
├── THIRD_PARTY_NOTICES.md
└── third_party/
    └── ESM_LICENSE          # 第三方许可证

安装

要求 Python 3.10+、PyTorch 2.x。VCF 准备阶段还需单独安装 PLINK 1.9，并使 plink 位于 PATH；也可以在准备命令中用 --plink-bin 指定可执行文件。PLINK 不随仓库分发。

python -m pip install -U huggingface_hub
hf download unknow1024/GTFound --local-dir GTFound
cd GTFound
sha256sum -c SHA256SUMS
python -m pip install -e .
gtfound --help
plink --version

权重校验应显示 model.safetensors: OK。pip install -e . 让命令直接读取当前目录中的权重；若使用普通的 pip install .，运行 gtfound infer 时需用 --model-dir 指向下载后的模型目录。本模型使用原生 PyTorch 代码，不能直接用 Transformers 的 AutoModel.from_pretrained 加载。

VCF 输入要求

下面的完整流程一次处理一个目标样本的一条染色体。命令中的文件名、样本名 SAMPLE_001 和染色体名 chr1 都是示例，请替换为自己的数据；示例路径相对于当前 GTFound 目录。

文件	要求
目标 VCF	包含目标样本的二倍体 GT。已观测杂合位点须分相，例如 `0
参考 VCF	包含待填补的二等位面板位点，按位置排序；参与计算的样本应有完整的 0/1 二倍体 GT，杂合位点须分相。默认取 8 条近邻参考单倍型，至少需要 4 名合格参考样本。
两者共同	使用同一 GRCh38 坐标及一致的 CHROM/POS/REF/ALT。请先完成多等位拆分、indel 规范化、REF/ALT 核对、分相和质量控制。chr1 与 1 不视为相同名称。

目标样本若也存在于参考 VCF，工具会按样本名将它从参考选择和 LD 计算中排除。工具不会自动识别其他重复个体，也不会自动检查 VCF 的组装版本。面板外位点不能由本模型填补；本流程要求二倍体，未处理的单倍体 GT 不适用。

完整使用流程：VCF → VCF

1. 生成张量和 LD

gtfound prepare-vcf \
  --target-vcf target.phased.vcf.gz \
  --reference-vcf reference.phased.vcf.gz \
  --sample SAMPLE_001 \
  --chrom chr1 \
  --output-dir work_chr1

work_chr1 必须不存在或为空。程序为两条目标单倍型生成窗口，按已观测位点选择最近的参考单倍型，并用 PLINK 1.9 的 --r2 square gz yes-really 逐窗生成 LD。若 plink 不在 PATH，在命令末尾添加 --plink-bin 并提供 PLINK 可执行文件路径。默认窗口为 1024 个面板位点、重叠 128 个位点；这里的位点数不是碱基长度。

先检查 work_chr1/manifest.json，尤其是 site_count、unmatched_target_variants、skipped_* 和 windows_without_observed_sites。如需减少单个张量分片占用的内存，可在准备命令中加 --windows-per-shard 2。详细的位点筛选、PLINK 调用与窗口映射见 VCF 数据处理手册。

2. 对全部分片运行模型

mkdir -p work_chr1/predictions
for input in work_chr1/input_*.pt; do
  name=$(basename "$input")
  gtfound infer \
    --input "$input" \
    --output "work_chr1/predictions/${name/input_/pred_}" \
    --device cuda:0 \
    --batch-size 1
done

3. 导出填补后的 VCF

gtfound export-vcf \
  --prepared-dir work_chr1 \
  --predictions-dir work_chr1/predictions \
  --output-vcf SAMPLE_001.chr1.imputed.vcf.gz

输出文件不能已存在。程序保留目标原本已观测的 GT；对缺失等位基因，先平均重叠窗口的 ALT 概率，再按 0.5 判定 0/1。

输出是新的单样本、面板位点 VCF，FORMAT 只有 GT；它不会复制原目标 VCF 的其他 INFO/FORMAT、FILTER 或面板外变异。.vcf.gz 为 BGZF 压缩；如需索引，可运行 bcftools index -t SAMPLE_001.chr1.imputed.vcf.gz。每个样本、每条染色体分别使用自己的工作目录和输出文件。

已有张量时直接推理

已有自行对齐的输入张量时，可直接运行：

gtfound infer --input input.pt --output output.pt --device cuda:0 --batch-size 1

input.pt 是 torch.save 保存的字典，包含：

键	形状	内容
tokens	[N,L]	目标单倍型；0=REF，1=ALT，5=待填补的 [MASK]。
references	[N,R,L]	与目标逐位对齐的 0/1 参考单倍型。
positions	[N,L] 或 [L]	GRCh38 位置。
ld_bias	[N,L,L]	与相同位点顺序对应的浮点 LD 注意力偏置。

output.pt 包含 probabilities [N,L,2]、mask [N,L] 和 imputed_tokens [N,L]。Python 调用直接使用 from gtfound.inference import load_gtfound, predict。probabilities 的最后一维依次是 0、1 的条件 softmax 概率。

适用边界与许可

权重与代码按 MIT 许可证发布。第三方代码声明见 THIRD_PARTY_NOTICES.md。参考面板和目标 VCF 不在本仓库中，请遵守各自的数据使用条款。