Ericaaixue/fyp-tcr-pmhc-pu-learning
GitHub: Ericaaixue/fyp-tcr-pmhc-pu-learning
该项目是一个基于 PU 学习的 TCR-pMHC 结合预测可靠负样本筛选与评估的可复现 Python 工作流。
Stars: 0 | Forks: 0
# 评估正样本-未标记学习与采样策略以构建 TCR-pMHC 结合预测中的可靠负样本
本代码库包含一个可复现的 Python 工作流，用于在 T 细胞受体与肽-MHC (TCR-pMHC) 结合预测中构建可靠负样本。该项目将假定的非交互式 TCR-pMHC 对视为未标记的候选负样本，而非已确认的非结合物，随后评估正样本-未标记 (PU) 学习方法和采样策略，以构建可靠的负样本数据集。
## 研究目标
经实验验证的非结合 TCR-pMHC 对数量有限。在实践中，假定的非交互对通常被用作负样本，尽管其中一些可能是未经测试的结合物。本项目旨在探讨基于 PU 学习的可靠负样本筛选与采样策略，是否能够为下游的 TCR-pMHC 结合预测构建更具信息量的负样本数据集。
## 项目摘要
该工作流使用：
- `51,183` 个经过筛选的阳性 TCR-pMHC 结合物。
- `3,342,225` 个假定的非交互对作为未标记候选负样本池。
- `44` 个基于序列衍生的 CDR3beta 和肽特征。
- 七种可靠负样本筛选方法：Spy、Rocchio、kNN、biased SVM、weighted logistic regression、uPU 和 nnPU。
- 一种随机基线和四种 PU 指导的采样策略。
- `29` 个负样本数据集，每个数据集恰好包含 `50,000` 个选定的负样本。
- 使用 Logistic Regression、Complement Naive Bayes 和 Random Forest 进行分层 5 折交叉下游验证。
主要发现是，top-k 可靠负样本采样通常能提供最高的分类器分离度，但可能会选择过于简单且分布较窄的负样本。肽平衡和 HLA-肽平衡采样通常会降低分类器得分，但能更好地保留生物学覆盖率。因此，评估可靠负样本的质量应同时考虑下游性能和分布的代表性。
## 仓库结构
```
fyp-tcr-pmhc-pu-learning/
|-- README.md
|-- environment.yml
|-- .gitignore
|
|-- data/
| `-- example_data/
| |-- positive_sample.csv
| |-- unlabeled_candidate_sample.csv
| |-- reliable_negative_sample.csv
| `-- README.md
|
|-- rn_screener/
| `-- core implementation package
|
|-- scripts/
| |-- 01_data_preprocessing.py
| |-- 02_feature_extraction.py
| |-- 03_rn_screening.py
| |-- 04_negative_sampling.py
| |-- 05_downstream_validation.py
| |-- 06_stage10_analysis.py
| |-- 07_plot_figures.py
| `-- legacy_helpers/
| `-- auxiliary plotting and continuation scripts from the project workflow
|
|-- tests/
| `-- smoke tests for core workflows
|
`-- results/
|-- figures/
| |-- data_distribution.png
| |-- stage10_loss_gap_boxplot.png
| `-- stage10_mcc_gap_heatmap.png
|
`-- tables/
|-- stage10_validation_loss.csv
|-- stage10_validation_mcc.csv
|-- stage10_test_mcc.csv
|-- stage10_loss_gap.csv
`-- stage10_mcc_gap.csv
```
## 示例数据
`data/example_data/` 下包含了小型的预览 CSV 文件，以便读者检查预期的输入格式。这些文件每个仅包含 20 行数据，不适用于最终分析。
由于文件大小的限制，完整的项目数据未包含在 GitHub 中。完整数据工作流需要：
```
data/positive_stats_output1/positive_cleaned_mouse_MHC_removed.csv
data/omics_neg_with_HLA_peptide.csv
rn_features/
rn_method_outputs_50k/
rn_sampling_strategies_50k_29/
staged_validation_outputs/
dataset_level_validation_outputs/
```
完整数据包：
```
https://drive.google.com/file/d/1Heify61gDa-YvUQNqAEI4KFRv8rh8Zkx/view?usp=drive_link
```
## 环境
创建 conda 环境：
```
conda env create -f environment.yml
conda activate bio319-rn-analysis
```
本项目使用 Python `3.8.10` 开发。
可选依赖说明：
- 仅在重新运行 uPU 和 nnPU 筛选器时需要 PyTorch。
- 包含 XGBoost 以供可选的重运行使用，但 XGBoost 的结果不作为最终主要分析的一部分。
## 主工作流脚本
`scripts/` 中的编号脚本代表了项目的主要工作流。
预览并验证示例数据：
```
python scripts\01_data_preprocessing.py
```
构建特征：
```
python scripts\02_feature_extraction.py `
--positive-input data\positive_stats_output1\positive_cleaned_mouse_MHC_removed.csv `
--unlabeled-input data\omics_neg_with_HLA_peptide.csv `
--output-dir rn_features
```
运行可靠负样本筛选：
```
python scripts\03_rn_screening.py `
--x-pos rn_features\X_pos.npy `
--x-unlabeled rn_features\X_unlabeled.npy `
--metadata rn_features\U_metadata.csv `
--method all `
--ratio 0.05 `
--output-dir rn_method_outputs_50k
```
构建 29 个负样本数据集：
```
python scripts\04_negative_sampling.py `
--rn-output-dir rn_method_outputs_50k `
--metadata rn_features\U_metadata.csv `
--output-dir rn_sampling_strategies_50k_29 `
--rn-count 50000
```
运行下游验证：
```
python scripts\05_downstream_validation.py `
--staged-run-dir staged_validation_outputs\full_stratified_stage10_20260507_233700 `
--negative-dir rn_sampling_strategies_50k_29 `
--classifiers logistic complement_nb random_forest `
--n-splits 5 `
--save-plots
```
生成 stage-10 分析表格和热图：
```
python scripts\06_stage10_analysis.py
```
生成论文风格的数据分布图：
```
python scripts\07_plot_figures.py
```
## 包含的结果
本次上传包含了部分轻量级的结果文件供查阅：
- `results/figures/data_distribution.png`
- `results/figures/stage10_loss_gap_boxplot.png`
- `results/figures/stage10_mcc_gap_heatmap.png`
- `results/tables/stage10_validation_loss.csv`
- `results/tables/stage10_validation_mcc.csv`
- `results/tables/stage10_test_mcc.csv`
- `results/tables/stage10_loss_gap.csv`
- `results/tables/stage10_mcc_gap.csv`
这些是具有代表性的面向论文的输出。完整的中间数据、完整的方法输出以及完整的验证输出目录均未包含在 GitHub 中。
## 测试
`tests/` 目录下包含了冒烟测试：
```
python -B tests\smoke_test_rn_screeners.py
python -B tests\smoke_test_rn_sampling.py
python -B tests\smoke_test_staged_validation.py
python -B tests\smoke_test_staged_continue.py
python -B tests\smoke_test_fixed_stage_dataset_validation.py
python -B tests\smoke_test_stage_history_summary.py
```
## 局限性
- 可靠负样本是根据未标记数据推断出来的，而非实验确认的非结合物。
- Top-k 采样可能会产生非常高的 MCC，但可能会导致简单负样本的代表性过高。
- 平衡采样能更好地保留肽或 HLA-肽的覆盖率，但可能会降低分类器的分离度。
- 大型原始和生成的数据文件必须单独下载。
## AI 使用声明
AI 工具被用于代码编写支持、调试、文档起草和工作流检查。最终的项目决策、解释以及论文内容均由学生本人审查和控制。
标签：Apex, PU学习, Python, TCR-pMHC, 凭据扫描, 无后门, 机器学习, 生物信息学, 负样本选择, 逆向工具