# PhyloX

**Repository Path**: sculab/phylox

## Basic Information

- **Project Name**: PhyloX
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-01
- **Last Updated**: 2026-10-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PhyloX v2

**Nanopore 三代测序植物物种鉴定工具**（ITS + psbA-trnH），基于 **Rust 引擎**，
带 **Tauri 桌面 GUI** 与 **phyx 命令行**。

一条命令（或点击按钮）即可完成：目标基因分离 → 引物/polyA 修剪 →
**UNOISE3 去噪**（ONT 高错误率下免疫 consensus 放大错误）→ **本地 BLAST 定种**
（默认，离线）→ **多基因联合打分** → 输出 Top-5 物种的
**拉丁学名 / 中文名 / 属 / 科**。

> PhyloX v2 用 Rust 完全重写了引擎与界面（不再依赖 Python / conda / Streamlit），
> 并针对 **Oxford Nanopore 高错误率长读**重新设计了降噪核心（UNOISE3 + 属级
> 一致性剔离群），解决传统"聚类 + consensus"在 ONT 数据上放大测序错误的问题。

---

## 特性

- **纯 Rust 引擎**：分离 / 修剪 / UNOISE3 去噪 / BLAST 比对 / 物种投票 / 差异位点
  全部 Rust 实现，无 Python / conda 运行时
- **Tauri 桌面 GUI**：原生窗口、多选 FASTQ 批量鉴定、每样本补充照片、
  独立结果窗口（综合鉴定 + 每基因差异位点 + HTML 报告）
- **phyx CLI**：命令行批量鉴定，离线可用
- **ONT 感知降噪**：vsearch UNOISE3 输出 zOTU（观测真实序列，非 consensus），
  免疫 ONT 高错误率下 consensus 投票放大错误的问题
- **每基因单独鉴定**：ITS 与 psbA-trnH 分别给出 Top1 物种 + 与最佳参考的
  差异位点（位置/碱基/权重）
- **多基因联合**：双标记独立实验，种级一致得分最高
- **本地 BLAST 库**：离线定种，无网络依赖

## 快速开始

```bash
# 1. 构建 & 安装（生成 PhyloX.app 并安装到 /Applications）
cd rust && bash install_app.sh

# 2. 启动桌面 GUI
open -a PhyloX

# 3. 命令行鉴定（可选）
cd rust && cargo build --release -p phyx-cli
./target/release/phyx input.fastq --out ./results
```

### GUI 使用流程

1. **添加样本**：点"浏览 FASTQ…"可一次选择多个 FASTQ → 生成多个样本
2. **补充照片**（可选）：每个样本行有 📁 按钮，为该样本选择植物照片
3. **运行全部**：批量鉴定，实时日志可折叠查看
4. **查看结果**：每个样本运行完成后，点"查看结果"在独立窗口查看
   - 综合鉴定 Top-N（多基因联合打分）
   - 属级结论
   - **每基因单独鉴定** + 差异位点
   - 完整 HTML 报告（含图片辅助鉴定，照片识别完成后可见）

## 输出

每个样本一个结果目录 `~/phylox_results/<前缀>_pipeline/`：

| 文件 | 说明 |
|---|---|
| `01_separation/` | 基因分离统计与定向 reads |
| `02_trim/` | 修剪后 reads |
| `03_clustering/` | derep + UNOISE3 zOTU |
| `pipeline.json` | 结构化结果（含 gene_results 每基因鉴定） |
| `report.html` | 自包含 HTML 报告 |
| `sequences_<gene>.fasta` | 每基因代表序列 |

## 命令行

```bash
# 完整版（切引物 + polyA）
phyx barcode01.fastq --out ./results

# 简化版（仅 polyA/T）
phyx --np barcode01.fastq

# 指定输出目录（默认 ~/phylox_results/）
phyx input.fastq --out /path/to/out
```

## 生物学背景

植物 DNA 条形码鉴定利用标准短标记区分物种。本工具使用：

- **ITS**（核核糖体 DNA 内转录间隔区）：植物物种鉴定的主流标记，种间变异高，
  但存在种内多态与假基因
- **psbA-trnH**（叶绿体间隔区）：单拷贝叶绿体标记，与 ITS 互补，可用于
  双标记交叉验证与杂交检测

详见 [docs/BIOLOGY.md](docs/BIOLOGY.md)（生物学意义）与
[docs/TECHNICAL.md](docs/TECHNICAL.md)（算法技术细节）。

## 目录结构

```
rust/
  engine/    Rust 引擎（primers/separate/trim/cluster/blast/classify/...）
  cli/       phyx 命令行
  tauri-app/ Tauri 桌面 GUI
  install_app.sh   一键构建+安装到 /Applications
  bundle_resources.sh  捆绑数据库/工具/凭证
engine/      Python 遗留引擎（旧版，保留参考）
gui/         Python 遗留 Streamlit 界面（旧版，保留参考）
db/         本地 blast 库（不随仓库分发，按需自建）
```

## 测试

```bash
cd rust/engine && cargo test
```