Metadata-Version: 2.4
Name: eukbin
Version: 0.1.0
Summary: BUSCO-guided binning tool for eukaryotic metagenomes
Home-page: https://github.com/yourusername/eukbin
Author: EukBin Contributors
Author-email: your.email@example.com
License: MIT
Project-URL: Bug Reports, https://github.com/yourusername/eukbin/issues
Project-URL: Source, https://github.com/yourusername/eukbin
Project-URL: Documentation, https://github.com/yourusername/eukbin/blob/main/README.md
Keywords: metagenomics,binning,eukaryotes,BUSCO,deep-learning,VAE,bioinformatics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: torch>=2.0.0
Requires-Dist: biopython>=1.79
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Requires-Dist: pre-commit>=2.20.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=4.5.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# EukBin

**真核微生物宏基因组分箱工具**

EukBin 是一款专为真核微生物（原生生物、真菌、藻类等）设计的宏基因组分箱工具，通过结合 BUSCO 标记基因约束和深度学习技术，实现高质量的基因组重建。

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://img.shields.io/badge/tests-96%20passed-brightgreen.svg)](tests/)

---

## 🌟 核心特性

### 1. **Repeat-Masked TNF（四核苷酸频率）**
- 仅在非重复区域计算组成特征，避免转座子等重复序列干扰
- 使用 DUST 算法识别低复杂度序列
- 136 个 canonical 4-mers + CLR 标准化

### 2. **BUSCO-Guided Constraints（标记基因约束）**
- **Cannot-link 约束**：Duplicated BUSCO 的 contigs 不能聚在同一个 bin
- **Must-link 约束**：相同 BUSCO 的 fragments 应聚在一起
- **Anchor 初始化**：用含多个 Complete BUSCO 的 contig 初始化聚类中心
- **自动推断物种数**：通过 BUSCO 冲突图的图着色算法估计基因组数量

### 3. **Constrained β-VAE（约束变分自编码器）**
- 深度表征学习，捕获非线性特征关联
- β-VAE 平衡重构精度和表征解耦
- 对比损失（Contrastive Loss）：
  - Cannot-link: hinge margin loss
  - Must-link: 欧氏距离惩罚
- KL warmup 防止后验坍塌

### 4. **Ploidy-Aware Refinement（倍性感知精修）**
- **Over-split 合并**：合并覆盖度高度相关、TNF 相似的 bins
- **Contamination 分裂**：分离含多个基因组的污染 bins
- **Haplotig 检测**：识别单倍型 contigs（coverage ~0.5×, TNF 高相似）
- **BUSCO 质量评估**：完整度 (Completeness) 和污染度 (Contamination)

### 5. **Multi-Tool Benchmark（多工具对比）**
- 支持 MetaBAT2, MaxBin2, CONCOCT, VAMB 等主流工具
- MIMAG 质量分级（HQ/MQ/LQ）
- 生成比较报告（ASCII 表格 + TSV）

---

## 📋 目录

- [安装](#-安装)
- [快速开始](#-快速开始)
- [输入文件](#-输入文件)
- [使用指南](#-使用指南)
  - [完整分箱流程](#1-完整分箱流程)
  - [评估已有结果](#2-评估已有分箱结果)
  - [多工具对比](#3-多工具对比报告)
- [输出文件](#-输出文件)
- [参数详解](#-参数详解)
- [工作流程示例](#-工作流程示例)
- [常见问题](#-常见问题)
- [性能建议](#-性能建议)
- [引用](#-引用)

---

## 🔧 安装

### 环境要求

- Python ≥ 3.8
- 推荐使用 conda/mamba 管理环境

### 方法 1：从源码安装（推荐）

```bash
# 克隆仓库
git clone https://github.com/yourusername/eukbin.git
cd eukbin

# 创建 conda 环境
conda create -n eukbin python=3.10
conda activate eukbin

# 安装依赖
pip install -r requirements.txt

# 安装 EukBin
pip install -e .
```

### 方法 2：使用 pip（开发中）

```bash
pip install eukbin
```

### 验证安装

```bash
python -m eukbin --help
python -m pytest tests/  # 运行测试（可选）
```

---

## 🚀 快速开始

### 最小示例（无 BUSCO）

```bash
python -m eukbin run \
  --fasta assembly.fa \
  --depth depth.tsv \
  --output eukbin_out \
  --n-bins 5 \
  --epochs 100
```

### 完整示例（推荐，含 BUSCO）

```bash
python -m eukbin run \
  --fasta assembly.fa \
  --depth depth.tsv \
  --busco full_table.tsv \
  --output eukbin_out \
  --epochs 300 \
  --threads 16
```

**输出**：
- `eukbin_out/bin_assignments.tsv` - 分箱结果
- `eukbin_out/bins/*.fa` - 各 bin 的序列文件
- `eukbin_out/pipeline_stats.json` - 统计信息

---

## 📁 输入文件

### 1. **组装序列（必需）** `--fasta`

标准 FASTA 格式的宏基因组组装结果。

```fasta
>contig_1
ATCGATCGATCG...
>contig_2
GCTAGCTAGCTA...
```

**推荐组装器**：
- **metaSPAdes**（推荐）
- MEGAHIT
- metaFlye

### 2. **覆盖度文件（必需）** `--depth`

JGI 格式（MetaBAT2 标准），由 `jgi_summarize_bam_contig_depths` 生成。

```bash
# 生成覆盖度文件
jgi_summarize_bam_contig_depths --outputDepth depth.tsv *.bam
```

**文件格式**：
```
contigName    contigLen    totalAvgDepth    sample1.bam    sample1.bam-var    sample2.bam    ...
contig_1      12543        45.2             50.1           5.2                40.3           ...
contig_2      8921         23.8             25.0           3.1                22.6           ...
```

### 3. **BUSCO 结果（强烈推荐）** `--busco`

BUSCO v5 的 `full_table.tsv` 文件。

```bash
# 运行 BUSCO
busco -i assembly.fa \
      -o busco_out \
      -l eukaryota_odb10 \
      -m genome \
      -c 16

# 使用输出文件
--busco busco_out/run_eukaryota_odb10/full_table.tsv
```

**为什么需要 BUSCO？**
- ✅ 自动推断物种数量（无需手动指定 `--n-bins`）
- ✅ 提供生物学约束，提高分箱准确性
- ✅ 评估 bin 完整度和污染度
- ✅ 引导 VAE 训练，避免局部最优

### 4. **可选输入**

#### Tiara 分类 `--tiara`
用于过滤线粒体/叶绿体 contigs。

```bash
tiara -i assembly.fa -o tiara_out.txt --tf all
--tiara tiara_out.txt
```

#### 基因预测 GFF `--gff`
提供基因密度特征。

```bash
prodigal -i assembly.fa -o genes.gff -f gff
--gff genes.gff
```

#### 外部工具结果 `--benchmark`
用于对比评估。

```bash
--benchmark MetaBAT2:metabat_bins/ \
            VAMB:vamb_clusters.tsv
```

---

## 📖 使用指南

### 1. 完整分箱流程

#### 基础用法

```bash
python -m eukbin run \
  --fasta contigs.fa \
  --depth depth.tsv \
  --busco full_table.tsv \
  --output eukbin_out
```

#### 高级用法

```bash
python -m eukbin run \
  --fasta contigs.fa \
  --depth depth.tsv \
  --busco full_table.tsv \
  --tiara tiara_out.txt \
  --gff genes.gff \
  --output eukbin_out \
  \
  --min-contig-len 2000 \
  --n-bins 10 \
  --epochs 500 \
  --latent-dim 64 \
  --lambda-cl 3.0 \
  \
  --no-haplotig \
  --save-embeddings \
  --threads 32 \
  --device cuda
```

### 2. 评估已有分箱结果

```bash
# 评估 MetaBAT2 结果（FASTA bins 目录）
python -m eukbin evaluate \
  --bins metabat_bins/ \
  --busco full_table.tsv \
  --fasta contigs.fa \
  --tool-name MetaBAT2

# 评估 VAMB 结果（TSV 格式）
python -m eukbin evaluate \
  --bins vamb_clusters.tsv \
  --busco full_table.tsv \
  --fasta contigs.fa
```

**输出示例**：
```
────────────────────────────────────────────────────────────
工具：MetaBAT2
Bins 总数：12
  HQ (≥90% comp, ≤5% cont):  5
  MQ (≥50% comp, ≤10% cont): 4
  LQ:                         3
  NoBUSCO:                    0
平均完整度：78.3%
平均污染度：8.2%
总分箱量：  145.6 Mb
────────────────────────────────────────────────────────────
```

### 3. 多工具对比报告

```bash
python -m eukbin report \
  --tools EukBin:eukbin_out/bin_assignments.tsv \
          MetaBAT2:metabat_bins/ \
          MaxBin2:maxbin_bins/ \
          VAMB:vamb_clusters.tsv \
  --busco full_table.tsv \
  --fasta contigs.fa \
  --output comparison_report/ \
  --sample-name "Sample_A"
```

**生成报告**：
- `comparison_report/report.txt` - 人类可读的完整报告
- `comparison_report/summary.tsv` - 工具总览表格
- `comparison_report/per_bin/*.tsv` - 各工具的 per-bin 详情

---

## 📤 输出文件

### 主要输出

```
eukbin_out/
├── bin_assignments.tsv          # 最终分箱结果（推荐用于下游分析）
├── bins/                         # 各 bin 的 FASTA 文件
│   ├── bin.0.fa
│   ├── bin.1.fa
│   └── ...
├── pipeline_stats.json          # 流程统计信息
├── embeddings.npz               # VAE 潜变量（--save-embeddings）
└── benchmark_report/            # 对比报告（--benchmark）
    ├── report.txt
    ├── summary.tsv
    └── per_bin/
        ├── EukBin.tsv
        └── MetaBAT2.tsv
```

### 分箱结果格式

#### `bin_assignments.tsv`

```tsv
contig_id       bin_id  length  mean_coverage
contig_1        0       15234   45.2
contig_2        0       8921    42.8
contig_3        1       12450   23.5
contig_4        2       9876    67.3
```

#### `pipeline_stats.json`

```json
{
  "input": {
    "n_contigs": 1523,
    "total_bp": 45678901,
    "n_samples": 3
  },
  "busco": {
    "n_complete": 234,
    "n_duplicated": 45,
    "estimated_genomes": 5
  },
  "binning": {
    "n_bins": 5,
    "n_hq_bins": 3,
    "n_mq_bins": 2,
    "binned_fraction": 0.87
  },
  "runtime": {
    "total_seconds": 542.3,
    "steps": {
      "1_features": 23.1,
      "2_busco": 5.2,
      "3_vae": 480.5,
      "4_refine": 28.3,
      "5_benchmark": 3.8,
      "6_export": 1.4
    }
  }
}
```

---

## ⚙️ 参数详解

### 必需参数

| 参数 | 说明 | 示例 |
|------|------|------|
| `--fasta` | 组装 FASTA 文件 | `assembly.fa` |
| `--depth` | JGI 格式覆盖度文件 | `depth.tsv` |
| `--output` | 输出目录 | `eukbin_out` |

### 可选输入

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--busco` | BUSCO full_table.tsv | 无（强烈推荐） |
| `--tiara` | Tiara 分类结果 | 无 |
| `--gff` | 基因预测 GFF3 | 无 |
| `--benchmark` | 外部工具结果（可多个） | 无 |

### 特征提取参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--min-contig-len` | 最小 contig 长度 (bp) | 1000 |
| `--depth-format` | 覆盖度格式 (jgi/simple) | jgi |
| `--total-busco-genes` | BUSCO 数据集总基因数 | 255 (eukaryota_odb10) |

### VAE 训练参数

| 参数 | 说明 | 默认值 | 建议范围 |
|------|------|--------|----------|
| `--n-bins` | 目标 bin 数 | 自动推断 | 2-20 |
| `--latent-dim` | 潜变量维度 | 32 | 16-128 |
| `--epochs` | 训练轮数 | 300 | 100-1000 |
| `--batch-size` | 批大小 | 256 | 128-512 |
| `--lr` | 学习率 | 1e-3 | 1e-4 ~ 1e-2 |
| `--beta` | KL 损失权重 | 1.0 | 0.5-2.0 |
| `--lambda-cl` | Cannot-link 权重 | 2.0 | 1.0-5.0 |
| `--cl-margin` | Cannot-link 间距 | 4.0 | 2.0-8.0 |

### 精修参数

| 参数 | 说明 |
|------|------|
| `--no-merge` | 禁用 bin 合并 |
| `--no-split` | 禁用 bin 分裂 |
| `--no-haplotig` | 禁用 haplotig 检测 |

### 输出控制

| 参数 | 说明 |
|------|------|
| `--no-fasta-bins` | 不生成 FASTA bin 文件 |
| `--save-embeddings` | 保存 VAE 潜变量 (.npz) |

### 系统参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--threads` | 线程数 | 8 |
| `--seed` | 随机种子 | 42 |
| `--device` | 计算设备 (auto/cpu/cuda/mps) | auto |

---

## 🔬 工作流程示例

### 完整的真核宏基因组分箱流程

```bash
#!/bin/bash

# 1. 质控和去宿主
fastp -i R1.fq.gz -I R2.fq.gz -o clean_R1.fq.gz -O clean_R2.fq.gz
bbmap.sh in=clean_R1.fq.gz in2=clean_R2.fq.gz ref=host_genome.fa outu=unmap_R1.fq.gz outu2=unmap_R2.fq.gz

# 2. 组装
metaspades.py -1 unmap_R1.fq.gz -2 unmap_R2.fq.gz -o spades_out -t 32
seqkit seq -m 1000 spades_out/scaffolds.fasta > assembly.fa

# 3. 计算覆盖度
bwa index assembly.fa
bwa mem -t 32 assembly.fa unmap_R1.fq.gz unmap_R2.fq.gz | samtools sort -@ 8 -o mapped.bam
samtools index mapped.bam
jgi_summarize_bam_contig_depths --outputDepth depth.tsv mapped.bam

# 4. BUSCO 分析
busco -i assembly.fa -o busco_out -l eukaryota_odb10 -m genome -c 32

# 5. Tiara 分类（可选）
tiara -i assembly.fa -o tiara_out.txt -t 32 --tf all

# 6. 基因预测（可选）
prodigal -i assembly.fa -o genes.gff -f gff

# 7. EukBin 分箱
python -m eukbin run \
  --fasta assembly.fa \
  --depth depth.tsv \
  --busco busco_out/run_eukaryota_odb10/full_table.tsv \
  --tiara tiara_out.txt \
  --gff genes.gff \
  --output eukbin_out \
  --epochs 500 \
  --threads 32 \
  --device cuda

# 8. 质量检查
checkm2 predict --input eukbin_out/bins --output-directory checkm2_out -x fa
```

### 与其他工具对比

```bash
#!/bin/bash

# 运行多个分箱工具
metabat2 -i assembly.fa -a depth.tsv -o metabat_bins/bin -t 32
run_MaxBin.pl -contig assembly.fa -abund depth.tsv -out maxbin_bins/bin -thread 32
vamb --fasta assembly.fa --jgi depth.tsv --outdir vamb_out -o C

# 生成对比报告
python -m eukbin report \
  --tools EukBin:eukbin_out/bin_assignments.tsv \
          MetaBAT2:metabat_bins/ \
          MaxBin2:maxbin_bins/ \
          VAMB:vamb_out/vamb_clusters.tsv \
  --busco busco_out/run_eukaryota_odb10/full_table.tsv \
  --fasta assembly.fa \
  --output comparison_report/
```

---

## ❓ 常见问题

### Q1: 需要多少覆盖度样本？

**A**:
- **最少**：1 个样本（但不推荐）
- **推荐**：≥3 个样本，提供更多覆盖度差异信息
- **最佳**：5-10 个相关样本（如时间序列、空间梯度）

### Q2: 没有 BUSCO 结果可以运行吗？

**A**: 可以，但需要手动指定 `--n-bins`。BUSCO 提供的约束能显著提高分箱质量，强烈推荐使用。

```bash
# 无 BUSCO（必须指定 n-bins）
python -m eukbin run --fasta assembly.fa --depth depth.tsv --n-bins 8 --output out
```

### Q3: 如何选择 `--n-bins` 参数？

**A**:
1. **有 BUSCO**：不指定，自动通过图着色算法推断
2. **无 BUSCO**：
   - 根据样本类型估计（如土壤样本可能 10-50 种真核生物）
   - 先用 `--n-bins 10` 试运行，根据结果调整
   - 宁多勿少（精修会自动合并 over-split bins）

### Q4: 训练很慢怎么办？

**A**:
- 使用 GPU：`--device cuda`
- 减少 epochs：`--epochs 100`（快速测试）
- 增大批大小：`--batch-size 512`
- 减少线程竞争：`--threads 8`（避免过高）

### Q5: 如何解释输出的质量指标？

**A**: 基于 MIMAG 标准（Minimum Information about a Metagenome-Assembled Genome）：

| 质量级别 | 完整度 | 污染度 | 说明 |
|----------|--------|--------|------|
| **HQ** (High-Quality) | ≥90% | ≤5% | 可直接用于基因组注释 |
| **MQ** (Medium-Quality) | ≥50% | ≤10% | 可用于系统发育分析 |
| **LQ** (Low-Quality) | <50% 或 >10% | - | 需进一步精修 |

### Q6: Haplotig 检测是什么？

**A**: 单倍型 contigs（来自二倍体/多倍体的不同单倍型）会被组装成独立序列，但实际来自同一基因组。Haplotig 检测通过以下特征识别：
- 覆盖度约为主要 contigs 的 0.5× (异型合子) 或 0.33× (同型三倍体)
- TNF 极高相似度（cosine > 0.92）
- 无 BUSCO cannot-link 冲突

### Q7: 内存/显存不足怎么办？

**A**:
```bash
# 减少批大小
--batch-size 128

# 使用 CPU（虽然慢，但内存充足）
--device cpu

# 过滤短 contigs
--min-contig-len 2000

# 减少潜变量维度
--latent-dim 16
```

### Q8: 如何处理病毒/质粒序列？

**A**: EukBin 专注于真核微生物，建议：
1. 用 VirSorter2/DeepVirFinder 预先去除病毒序列
2. 用 PlasFlow 过滤质粒序列
3. 使用 `--tiara` 过滤细菌/古菌 contigs

---

## 🚀 性能建议

### 硬件配置

| 数据规模 | CPU | 内存 | GPU | 训练时间 |
|----------|-----|------|-----|----------|
| 小型 (<500 Mb) | 8 核 | 16 GB | 可选 | 10-30 分钟 |
| 中型 (0.5-2 Gb) | 16 核 | 32 GB | 推荐 | 30-90 分钟 |
| 大型 (>2 Gb) | 32 核 | 64 GB | 必需 | 2-6 小时 |

### GPU 加速

```bash
# 自动选择（优先 GPU）
--device auto

# 强制使用 CUDA GPU
--device cuda

# Apple Silicon GPU（M1/M2/M3）
--device mps
```

**GPU 加速效果**：
- NVIDIA RTX 3090: 约 10-15× 加速
- Apple M2 Max: 约 3-5× 加速

### 参数调优

#### 快速测试（牺牲精度）
```bash
--epochs 50 --batch-size 512 --latent-dim 16
```

#### 标准配置（推荐）
```bash
--epochs 300 --batch-size 256 --latent-dim 32
```

#### 高精度配置（发表级别）
```bash
--epochs 1000 --batch-size 128 --latent-dim 64 --lambda-cl 3.0
```

---

## 📊 算法流程

```mermaid
graph TD
    A[组装 FASTA] --> B[M1: 特征提取]
    C[覆盖度 depth.tsv] --> B
    D[BUSCO full_table.tsv] --> E[M2: 约束生成]

    B --> F[M3: VAE 训练]
    E --> F

    F --> G[M3: K-Means 聚类]
    E --> G

    G --> H[M4: 精修]
    E --> H

    H --> I[M5: 质量评估]
    D --> I

    I --> J[M6: 结果导出]

    B -.-> |TNF + Coverage + GC| F
    E -.-> |Cannot-link<br>Must-link<br>Anchors| F
    E -.-> |BUSCO 锚点| G
    H -.-> |Merge<br>Split<br>Haplotig| I
```

---

## 🧪 测试

运行完整测试套件：

```bash
cd eukbin
python -m pytest tests/ -v

# 预期输出
# ======================== 96 passed in 6.06s ========================
```

测试覆盖：
- ✅ 特征提取：16 tests
- ✅ BUSCO 种子：15 tests
- ✅ VAE 模型：18 tests
- ✅ 精修算法：16 tests
- ✅ Benchmark：20 tests
- ✅ Pipeline：11 tests

---

## 📚 引用

如果您在研究中使用了 EukBin，请引用：

```bibtex
@software{eukbin2024,
  author = {Your Name},
  title = {EukBin: A BUSCO-guided binning tool for eukaryotic metagenomes},
  year = {2024},
  url = {https://github.com/yourusername/eukbin}
}
```

### 相关工具引用

- **BUSCO**: Manni et al. (2021) BUSCO Update: Novel and Streamlined Workflows. *Molecular Biology and Evolution* 38(10):4647-4654
- **MetaBAT2**: Kang et al. (2019) MetaBAT 2: an adaptive binning algorithm. *PeerJ* 7:e7359
- **VAMB**: Nissen et al. (2021) Improved metagenome binning and assembly. *Nature Biotechnology* 39:59-65

---

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

### 开发环境设置

```bash
git clone https://github.com/yourusername/eukbin.git
cd eukbin
conda create -n eukbin-dev python=3.10
conda activate eukbin-dev
pip install -e ".[dev]"
pre-commit install
```

### 代码风格

- 遵循 PEP 8
- 使用 Black 格式化
- 添加类型注解
- 编写 docstrings

---

## 📝 更新日志

### v0.1.0 (2024-02-11)
- ✨ 初始版本发布
- ✅ 完整的 M1-M6 流程实现
- ✅ 96 个单元测试全部通过
- 📚 完整文档

---

## 📧 联系方式

- **Issues**: [GitHub Issues](https://github.com/yourusername/eukbin/issues)
- **Email**: your.email@example.com
- **Discussion**: [GitHub Discussions](https://github.com/yourusername/eukbin/discussions)

---

## 📜 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

---

## 🙏 致谢

感谢以下开源项目：
- PyTorch
- scikit-learn
- NumPy/Pandas
- BUSCO
- MetaBAT2

特别感谢真核宏基因组学社区的宝贵反馈！

---

<p align="center">
  Made with ❤️ for eukaryotic metagenomics
</p>
