# arc_tools

**Repository Path**: dingxiuheng/arc_tools

## Basic Information

- **Project Name**: arc_tools
- **Description**: test pipe for atac + rna
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-12
- **Last Updated**: 2026-07-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CeleScope RNA+ATAC 联合分析说明

本仓库用于在现有 CeleScope RNA 和 ATAC 单组学流程之上，组织单细胞 RNA+ATAC multiome 联合分析。核心思路不是重写 RNA/ATAC 流程，而是用统一 mapfile 生成 RNA、ATAC 原生 mapfile 和运行脚本，再对成对样本执行 joint calling、ARC-like 矩阵生成和 multiome 下游分析。

## 目录

- [项目结构](#项目结构)
- [整体流程](#整体流程)
- [环境与安装](#环境与安装)
- [统一 mapfile](#统一-mapfile)
- [批量生成分析脚本](#批量生成分析脚本)
- [单样本联合分析](#单样本联合分析)
- [输入与输出](#输入与输出)
- [常用参数](#常用参数)
- [开发与测试](#开发与测试)
- [注意事项](#注意事项)

## 项目结构

```text
arc_multi_omics/
├── celescope_multiome/            # 唯一 Python 安装包，setup.py 从仓库根目录打包 celescope/
├── celescope/                     # 统一源码包：RNA、ATAC、multiome 入口均在这里
├── celescope_rna/                 # RNA 历史源码目录，仅作为普通文件夹保留
└── celescope_atac/                # ATAC 历史源码目录，仅作为普通文件夹保留
```

当前只需要安装 `celescope_multiome` 一个包。安装后会提供 `celescope`、`multi_rna`、`multi_atac`、`multi_multiome` 命令；`celescope_rna/` 和 `celescope_atac/` 不再需要单独 `pip install -e`。

## 整体流程

```text
统一四列表 multiome.mapfile
    -> 校验并按 sample_name 分组
    -> 生成 RNA 原生 mapfile
    -> 生成 ATAC 原生 mapfile
    -> 生成 run_rna.sh / run_atac.sh / run_multiome.sh / run_all.sh
    -> 执行 RNA 流程
    -> 执行 ATAC 流程
    -> 对 RNA+ATAC 成对样本执行 joint calling
    -> 生成 ARC-like matrix
    -> 执行 multiome analysis
```

单模态样本也会进入规划文件：RNA-only 或 ATAC-only 样本可以运行对应单组学流程，但会在 multiome 状态里标记为跳过联合分析。

## 环境与安装

推荐在同一环境中安装运行所需依赖，并只安装 `celescope_multiome`。`celescope_multiome/requirements.txt`
已经整合 RNA、ATAC 和 multiome 的 Python 依赖；`celescope_multiome/conda_pkgs.txt`
整合 STAR、chromap、bedtools、macs2、samtools 等外部命令行工具。

```bash
conda create -n celescope_multiome -c conda-forge -c bioconda --file celescope_multiome/conda_pkgs.txt
conda activate celescope_multiome

cd /path/to/arc_multi_omics
pip install -e celescope_multiome
```

若已存在可用环境，也可以只在该环境中补装外部工具后执行 `pip install -e celescope_multiome`。
ATAC 可视化相关 R 脚本还会用到 R 包 `Seurat`、`Signac`、`argparse`、`Gmisc` 和 `ggplot2`。

RNA 和 ATAC 参考基因组仍使用各自原生流程构建：

```bash
celescope rna mkref \
    --genome_name hg38 \
    --fasta /path/to/genome.fa \
    --gtf /path/to/genes.gtf

celescope atac mkref \
    --fasta /path/to/genome.fa \
    --gtf /path/to/genes.gtf \
    --thread 8
```

## 统一 mapfile

multiome 顶层 mapfile 使用四列，列之间必须用 Tab 分隔：

```text
library_id    data_path    sample_name    file_type
```

字段含义：

| 字段 | 说明 |
|------|------|
| `library_id` | FASTQ 前缀或测序文库 ID |
| `data_path` | FASTQ 所在目录 |
| `sample_name` | 生物学样本名，也是 RNA/ATAC 配对键 |
| `file_type` | 数据类型，支持 `rna` 或 `atac`，大小写不敏感 |

示例：

```text
RNA001    /data/run1/sampleA_rna    sampleA    rna
RNA002    /data/run2/sampleA_rna    sampleA    rna
ATAC001   /data/run1/sampleA_atac   sampleA    atac
ATAC002   /data/run2/sampleA_atac   sampleA    atac
RNA003    /data/run1/sampleB_rna    sampleB    rna
ATAC003   /data/run1/sampleB_atac   sampleB    atac
```

规则：

- 同一 `sample_name` 下的多行 `rna` 会合并为一个 RNA 样本运行，用于支持补测。
- 同一 `sample_name` 下的多行 `atac` 会合并为一个 ATAC 样本运行。
- 同时存在 RNA 和 ATAC 的样本才会生成 multiome 联合分析命令。
- 顶层第四列是 `file_type`；生成 ATAC 原生 mapfile 时第四列会转换为 ATAC 需要的 `match_dir`，默认值为 `None`。不要直接把顶层 mapfile 传给 `multi_atac`。

FASTQ 命名需能被原生流程识别。RNA 通常匹配 `*_1.fq.gz` / `*_2.fq.gz` 或 `*R1*.fastq.gz` / `*R2*.fastq.gz`；ATAC 通常匹配三文件模式 `*_1.fq.gz` / `*_2.fq.gz` / `*_3.fq.gz` 或对应 R1/R2/R3 fastq。

## 批量生成分析脚本

推荐使用 `multi_multiome` 从统一 mapfile 生成计划文件、原生 mapfile 和运行脚本：

```bash
multi_multiome \
    --mapfile multiome.mapfile \
    --outdir result \
    --rna_genomeDir /path/to/rna_ref \
    --atac_reference /path/to/atac_ref \
    --atac_genomesize 2.7e9 \
    --thread 8 \
    --n_jobs 8 \
    --mod shell
```

若 FASTQ 路径暂不存在，可在规划阶段增加：

```bash
--skip_path_check
```

生成内容：

```text
result/
├── pipeline_plan.json
├── pipeline_plan.tsv
├── generated_mapfiles/
│   ├── rna.mapfile
│   └── atac.mapfile
├── scripts/
│   ├── run_rna.sh
│   ├── run_atac.sh
│   ├── run_multiome.sh
│   └── run_all.sh
└── status/
    ├── sample_status.tsv
    └── sample_status.json
```

推荐直接运行：

```bash
bash result/scripts/run_all.sh
```

`run_all.sh` 会执行完整流程：

1. `run_rna.sh` 在 `result/work/rna` 中调用 `multi_rna --mod shell` 生成 RNA 原生脚本，并执行生成的每个样本脚本。
2. `run_atac.sh` 在 `result/work/atac` 中调用 `multi_atac --mod shell` 生成 ATAC 原生脚本，并执行生成的每个样本脚本。
3. 当 RNA 和 ATAC 都存在时，`run_all.sh` 会同步并行启动 `run_rna.sh` 和 `run_atac.sh`。
4. 只有 RNA 和 ATAC 都成功结束后，才会执行 `run_multiome.sh`，进入 joint calling、ARC-like matrix 和 multiome analysis。
5. 如果 RNA 或 ATAC 任一流程失败，`run_all.sh` 会跳过 joint calling 并以非零状态退出。

也可以按阶段手动运行：

```bash
bash result/scripts/run_rna.sh
bash result/scripts/run_atac.sh
bash result/scripts/run_multiome.sh
```

生成的 `run_multiome.sh` 默认假设 RNA 输出位于 `result/rna/<sample>`，ATAC 输出位于 `result/atac/<sample>`。

## 单样本联合分析

当 RNA 和 ATAC 已经分别完成后，可以直接运行单样本 multiome 后处理：

```bash
python -m celescope.multiome.run_joint_calling \
    --sample sampleA \
    --rna_sample_dir result/rna/sampleA \
    --atac_sample_dir result/atac/sampleA \
    --outdir result/multiome/sampleA \
    --n_jobs 8
```

也可以用输出根目录：

```bash
python -m celescope.multiome.run_joint_calling \
    --sample sampleA \
    --rna_base result/rna \
    --atac_base result/atac \
    --outdir result/multiome/sampleA
```

如果自动查找不到文件，可以手动指定关键输入：

```bash
python -m celescope.multiome.run_joint_calling \
    --sample sampleA \
    --rna_raw_matrix result/rna/sampleA/raw_feature_bc_matrix \
    --rna_filtered_matrix result/rna/sampleA/filtered_feature_bc_matrix \
    --rna_count_detail result/rna/sampleA/sampleA_counts_detail.txt \
    --atac_cell_qc result/atac/sampleA/cell_qc_metrics.tsv \
    --atac_fragments result/atac/sampleA/fragments.tsv.gz \
    --atac_peaks result/atac/sampleA/peak/sampleA_final_peaks.bed \
    --outdir result/multiome/sampleA
```

根目录 `celescope multiome sample` 包装入口也支持同类参数，适合已经安装根 `celescope` 包的环境。

## 输入与输出

RNA 样本目录至少需要能解析到：

```text
raw_feature_bc_matrix/ 或 outs/raw/
filtered_feature_bc_matrix/ 或 outs/filtered/
可选 counts_detail.txt / counts.tsv
```

矩阵目录必须包含：

```text
barcodes.tsv(.gz)
features.tsv(.gz)
matrix.mtx(.gz)
```

ATAC 样本目录至少需要能解析到：

```text
cell_qc_metrics.tsv
fragments.tsv.gz / fragments.tsv / fragments_corrected_*.tsv(.gz)
*_final_peaks.bed / peaks.bed
```

单样本 multiome 输出：

```text
result/multiome/sampleA/
├── joint_calling/
│   ├── joint_calling_cells_optimized.csv
│   ├── all_barcodes_with_calls_optimized.csv
│   └── calling_summary_optimized.txt
├── arc_matrix/
│   ├── raw_feature_bc_matrix/
│   ├── filtered_feature_bc_matrix/
│   ├── raw_feature_bc_matrix.h5
│   ├── filtered_feature_bc_matrix.h5
│   └── gex_molecule_info.h5
└── multiome_analysis/
    ├── metrics.json
    ├── summary_report.txt
    ├── plots/
    ├── filtered_gex.h5ad      # 使用 --save_h5ad 时生成
    └── filtered_atac.h5ad     # 使用 --save_h5ad 时生成
```

`arc_matrix_gen.py` 当前生成的是 ARC-like 矩阵，不应宣传为完全等同 Cell Ranger ARC 的 raw matrix。

## 常用参数

`multiome_pipeline.py` 常用参数：

| 参数 | 说明 |
|------|------|
| `--mapfile` | 顶层四列表 multiome mapfile |
| `--outdir` | 项目输出目录 |
| `--rna_genomeDir` | 传给 `multi_rna` 的 RNA 参考目录 |
| `--atac_reference` | 传给 `multi_atac` 的 ATAC 参考目录 |
| `--atac_genomesize` | 传给 `multi_atac` 的基因组大小 |
| `--thread` | RNA/ATAC 原生流程线程数；当 RNA 和 ATAC 并行运行时，该值会分别传给两个原生流程 |
| `--n_jobs` | multiome 后处理并行数 |
| `--skip_path_check` | 规划时不检查 `data_path` 是否存在 |
| `--rna_extra_args` | 追加给 `multi_rna` 的原始参数字符串 |
| `--atac_extra_args` | 追加给 `multi_atac` 的原始参数字符串 |

`run_joint_calling.py` 常用参数：

| 参数 | 说明 |
|------|------|
| `--sample` | 样本名 |
| `--rna_base` / `--atac_base` | RNA/ATAC 输出根目录 |
| `--rna_sample_dir` / `--atac_sample_dir` | RNA/ATAC 样本输出目录 |
| `--rna_raw_matrix` / `--rna_filtered_matrix` | 手动指定 RNA 矩阵 |
| `--atac_cell_qc` / `--atac_fragments` / `--atac_peaks` | 手动指定 ATAC 输入 |
| `--min_umi` / `--min_fragments` / `--min_genes` / `--cell_prob` | 转发给 joint calling 的阈值 |
| `--deep_analysis` | 执行更深度的下游分析 |
| `--save_h5ad` | 保存 H5AD 输出 |

注意：当 RNA 和 ATAC 并行运行时，`--thread` 会分别传给两个原生流程。例如 `--thread 8` 可能同时占用约 8 个 RNA 线程和 8 个 ATAC 线程；在资源受限机器上请降低该值，或后续扩展为 RNA/ATAC 分别设置线程数。

## 开发与测试

开发安装：

```bash
pip install -e celescope_multiome
```

运行 multiome 相关测试：

```bash
pytest celescope_multiome/tests/test_multiome_pipeline.py -v
pytest celescope_multiome/tests/test_multi_arc.py -v
pytest celescope_multiome/tests/test_multi_arc_integration.py -v
```

运行历史 RNA 目录中的单元测试（可选，不需要安装 `celescope_rna` 包）：

```bash
pytest celescope_rna/tests/test_function.py
```

代码检查：

```bash
ruff check celescope/
ruff format celescope/
```

## 注意事项

- `celescope/multiome/multi_arc.py` 是早期框架类，部分方法仍是占位逻辑；实际批量规划优先使用 `multi_multiome` / `celescope.multiome.multiome_pipeline`。
- `multi_atac` 原生 mapfile 第四列是 `match_dir`，而顶层 multiome mapfile 第四列是 `file_type`，两者不能混用。
- RNA-only 或 ATAC-only 样本会生成单模态流程状态，但不会执行 joint calling、ARC-like matrix 和 multiome analysis。
- 若 RNA/ATAC 输出目录命名不标准，优先使用 `run_joint_calling.py` 的手动路径参数。
- 旧版 `--rna_dir` / `--atac_dir` legacy 模式仍保留，但推荐使用 `--rna_sample_dir` / `--atac_sample_dir` 或 `--rna_base` / `--atac_base`。