# 数据 I/O 规范

本文档描述公司项目的数据目录结构与查找方法。agent 在处理数据分析任务时应参考这些规范来定位输入数据。

## 一、项目目录结构

所有流水线项目遵循统一目录结构，每个项目目录下必须包含：
- `info/` — 项目信息
- `Filter/` — 过滤数据
- `Analysis/` — 分析结果

使用 `annoeva stat` 命令可查看项目状态和目录结构（dirstat）。

## 二、商业项目标准分析目录

对于下单的商业项目，分析根目录按产品类型固定存放。以下是主要产品类型的分析路径对照表：

| 产品名称 | 分析根目录 |
|---------|-----------|
| 10XGenomics | `/annogene/data2/bioinfo/SCV/PROJECT/Commercial/scRNA/10xRNA` |
| 10XATAC | `/annogene/data2/bioinfo/SCV/PROJECT/Commercial/scEPI/10xATAC` |
| scRNA (Smart-seq) | `/annogene/data2/bioinfo/SCV/PROJECT/Commercial/scRNA/smartseq` |
| 10XGenomics_VDJ | `/annogene/data2/bioinfo/SCV/PROJECT/Commercial/scEPI/10xVDJ` |
| STO | `/annogene/data2/bioinfo/SCV/PROJECT/Commercial/scSpace/STO` |
| 10xHD | `/annogene/data2/bioinfo/SCV/PROJECT/Commercial/scSpace/10xSpace` |
| C4 | `/annogene/data2/bioinfo/SCV/PROJECT/Commercial/scRNA/C4` |
| RNA_VDJ | `/annogene/data2/bioinfo/SCV/PROJECT/Commercial/scEPI/VDJ_RNA` |
| M20 | `/annogene/data2/bioinfo/SCV/PROJECT/Commercial/scRNA/M20` |
| ATAC_GEX | `/annogene/data2/bioinfo/SCV/PROJECT/Commercial/scEPI/ATAC_GEX` |
| GEM_X_RNA | `/annogene/data2/bioinfo/SCV/PROJECT/Commercial/scRNA/GEM_X/` |

在对应根目录下，按 `合同号/项目分期号/分析员姓名/Analysis` 的层级查找具体分析结果。

## 三、云端分析目录

已迁移到云端的标准分析项目，根目录位于 `oss://sci-scv/standard/Commercial/`。

使用 ossutil 查看：
```bash
/annoroad/data1/software/bin/ossutil64 --config-file=<配置文件> ls oss://sci-scv/standard/Commercial/<产品子目录>/<合同号>/<项目分期号>/<分析员>/Analysis-<编号>/Analysis/
```

## 四、个性化项目目录

个性化分析包目录位于：
`/annogene/data2/bioinfo/SCV/PROJECT/Customized_project/Personalized_packages/`
按产品类型和项目组织。

## 五、过滤数据（Filter）目录查找

### 方法一：快捷命令查找（推荐）

```bash
/annogene/data1/bioinfo/Seq/software/miniforge/yuhancui/miniforge/envs/python3/bin/python \
  /annogene/data1/bioinfo/Seq/RD/Public/Stable/Public/query_path/query_path.py \
  <项目分期号>
```

输出示例：
```
>>>>>>>>>>lims数据路径
1    FILTER_FINISHED    /annogene/data1/bioinfo/Seq//Commercial/filter/NGS/<合同号>/Project_<项目分期号>//Analysis_1_<批次号>
2    FILTER_FINISHED    /annogene/data1/bioinfo/Seq//Commercial/filter/NGS/<合同号>/Project_<项目分期号>//Analysis_2_<批次号>
3    FILTER_FINISHED    /annogene/data1/bioinfo/Seq//Commercial/filter/NGS/<合同号>/Project_<项目分期号>//Analysis_3_<批次号>
```

**注意**：如果有多个过滤目录（Analysis_1, Analysis_2, ...），一般以编号最大的为准。配置时应提醒用户确认。

### 方法二：云端存储路径

原始过滤数据存储在 OSS 固定路径：
`oss://annoroad-cloud-product/user/project/<合同号>/<项目分期号>/`

### 云端数据回迁目录结构

当数据需从云端回迁本地分析时，应整理为以下结构：
```
Filter/<项目分期号>/
└── Analysis
    └── <样本名>
        └── filter
            └── clean (或 raw)
                ├── <样本名>_R1.fastq.gz
                └── <样本名>_R2.fastq.gz
```

## 六、10X 单细胞 CellRanger 数据

对于 10X 单细胞（包含 GEM-X）项目，过滤流程会自动运行 CellRanger 分析。获取 CellRanger matrix 等信息的路径：

```
<过滤目录>/cellranger_qc
```

示例：
```
/annogene/data1/bioinfo/Seq//Commercial/filter/NGS/XS01KF2026010320/Project_PM-XS01KF2026010320-01//Analysis_3_22LKKFLT4/cellranger_qc
```

## 七、常用路径模式总结

- **分析目录**: `<分析根目录>/<合同号>/<项目分期号>/<分析员>/Analysis`
- **过滤目录**: `/annogene/data1/bioinfo/Seq//Commercial/filter/NGS/<合同号>/Project_<项目分期号>//Analysis_<编号>_<批次号>`
- **云端原始数据**: `oss://annoroad-cloud-product/user/project/<合同号>/<项目分期号>/`
- **云端分析数据**: `oss://sci-scv/standard/Commercial/<产品子目录>/<合同号>/<项目分期号>/`
- **CellRanger QC**: `<过滤目录>/cellranger_qc`
