🧬 DNBelab C Series HT scATAC 分析参数

🔬 主分析流程 (run) • 📊 参考数据库构建 (mkref) • 📋 多样本操作 (multi)

🔬 主分析流程 (run)

📊 用法

$ dnbc4tools atac run --help
Usage: dnbc4tools atac run [OPTIONS]

optional arguments:
  -h, --help            show this help message and exit

Input Files:
  Choose ONE input method: either --fastqs (directory) OR individual FASTQ files (-1 and -2).

  --fastqs <DIR>        Input directory containing paired-end FASTQ files. The pipeline automatically detects Read1/Read2 files. Example: ./fastq_dir
  -1, --fastq1 <FILE> [<FILE> ...]
                        Read1 FASTQ file(s) for the ATAC library (supports wildcards and comma-separated lists). Example: sample1_L01_R1.fastq.gz,sample1_L02_R1.fastq.gz
  -2, --fastq2 <FILE> [<FILE> ...]
                        Read2 FASTQ file(s) for the ATAC library (supports wildcards and comma-separated lists). Must match --fastq1 order. Example: sample1_L01_R2.fastq.gz,sample1_L02_R2.fastq.gz

Basic Settings:
  -n, --name <STR>      Unique identifier for the sample (e.g., sample1). Used for naming output files and reports.
  -g, --genomeDir <DIR>
                        Path to reference genome directory. Must contain the required index and annotation resources.
  -o, --outdir <DIR>    Output directory for results and reports [default: current directory]. Example: ./output
  -t, --threads <INT>   Number of CPU threads for parallel processing [default: 10].

Library Settings:
  Configure sequencing library settings and dark cycles.
  Auto-detection is recommended for dark cycles.
  Use --customize to specify sequence structure patterns when needed.

  --darkreaction <STR>  Dark cycle setting for ATAC library [default: auto]. Options: auto (automatic detection), R1R2 (both reads), R1 (Read1 only), R2 (Read2 only), unset (no dark cycles).
  --customize <STR>     Customize read structure for barcode/sequence extraction, format: <type>,<read>:<start>-<end> separated by ';'. Types: cb (cell barcode), R1 (sequence from Read1), R2 (sequence from Read2). Example:
                        "cb,R1:1-10;cb,R1:11-20;R1,R1:21-70;R2,R2:1-50".

Filtering Settings:
  --forcecells <INT>    Force pipeline to use exactly this number of cells, overriding detection (e.g., 5000).
  --frags_cutoff <INT>  Minimum number of unique fragments to retain a cell [default: 1000].
  --tss_cutoff <FLOAT>  Minimum TSS proportion threshold to retain a cell [default: 0] (e.g., 0.2).
  --jaccard_cutoff <FLOAT>
                        Jaccard similarity threshold for merging beads (e.g., 0.02).
  --merge_cutoff <INT>  Minimum number of fragments when merging beads [default: 1000].

Analysis Settings:
  --need_bam            Enable generation of BAM files containing aligned reads. Note: generating BAM files increases computational time and disk space usage.
  --sample_read_pairs <INT>
                        Subsample the specified number of read pairs from the input FASTQ files (e.g., 1000000).

📝 参数说明

🔴 必需参数

⚠️ 成功分析必须指定的基本参数

`-n, --name` (必需)

为本次分析提供一个唯一的样本名称。

功能: 该名称将用作所有输出文件和HTML报告的前缀。
显示: 在最终的网页报告中，此名称将作为样本ID显示。

默认值: 无

示例:

--name sample_001

`-g, --genomeDir` (必需)

指定参考基因组目录的路径。

要求: 目录必须包含由 mkref 命令生成的索引和注释资源。
内容: 包含基因组序列、TSS文件、比对索引等。

默认值: 无

示例:

--genomeDir /path/to/genome/database

🟢 输入文件参数

📁 选择一种输入方式：基于目录 OR 单独指定文件

`--fastqs` (方式1)

指定包含所有FASTQ文件的目录路径。

功能: 流程会自动检测目录中的Read1和Read2配对文件。
注意: 这是一个便捷选项，不能与 --fastq1 / --fastq2 同时使用。

默认值: 无

示例:

--fastqs ./fastq_directory

`-1, --fastq1` (方式2A)

单独指定一个或多个Read1 FASTQ文件。

支持: 可以使用通配符 (*) 匹配文件，使用逗号分隔来指定多个文件。
要求: 必须与 --fastq2 参数配对使用，且文件顺序必须完全匹配。

默认值: 无

示例:

--fastq1 sample1_L01_R1.fastq.gz,sample1_L02_R1.fastq.gz

`-2, --fastq2` (方式2B)

单独指定一个或多个Read2 FASTQ文件。

支持: 可以使用通配符 (*) 匹配文件，使用逗号分隔来指定多个文件。
要求: 必须与 --fastq1 参数配对使用，且文件顺序必须完全匹配。

默认值: 无

示例:

--fastq2 sample1_L01_R2.fastq.gz,sample1_L02_R2.fastq.gz

⚠️ 输入方式选择：

🔸 方式1： 使用--fastqs指定包含配对FASTQ文件的目录

🔸 方式2： 使用-1, --fastq1和-2, --fastq2分别指定R1和R2文件

⚠️ 重要提示： 参数下所有文件必须来自同一文库，测序模式和暗反应设置保持一致，不同文库的数据不能合并分析。

🟢 基本设置参数

`-o, --outdir` (可选)

指定所有分析结果和报告的输出目录。

功能: 所有分析结果将保存在此目录中，流程会自动创建以样本名命名的结构化子目录。

默认值: ./ (当前目录)

示例:

--outdir ./output_results

`-t, --threads` (可选)

设置分析过程中可使用的CPU线程数。

功能: 增加线程数可显著提高分析速度。
建议: 根据可用的CPU核心数进行调整，以获得最佳性能。

默认值: 10

示例:

--threads 16

🟢 文库设置参数

`--darkreaction` (可选)

配置ATAC文库的暗循环（dark cycle）设置，以确保细胞条形码的精确识别。

功能: 指导软件正确解析因测序化学（如MGI平台）产生的暗反应周期。
智能检测: 默认情况下，软件会自动检测数据特征以选择合适的模式。强烈推荐初次分析时使用。

详细配置选项

选项	说明	适用场景
`auto`	(默认) 自动检测暗循环配置，并根据文库类型应用最优设置。	适用于所有标准 ATAC 测序数据。
`R1R2`	Read1 与 Read2 两端均包含暗循环碱基。	适用于双端暗循环的测序设计。
`R1`	仅 Read1 端包含暗循环碱基。	适用于单端暗循环（Read1 方向）的测序设计。
`R2`	仅 Read2 端包含暗循环碱基。	适用于单端暗循环（Read2 方向）的测序设计。
`unset`	文库不含暗循环碱基，不进行暗循环校正。	适用于非 MGI 平台或无暗循环设计的测序设计。

示例:

# 场景1: 首次分析，使用自动检测
dnbc4tools atac run --name sample1 --fastqs ./fq --genomeDir ./ref

# 场景2: 已知文库仅在R1端有暗循环且自动分析无法识别或者识别错误
dnbc4tools atac run --name sample2 --fastqs ./fq --genomeDir ./ref --darkreaction R1

⚠️ 重要提示：不正确的设置可能导致细胞条形码识别失败或序列信息丢失。仅在了解文库结构或自动检测失败时手动指定。

`--customize` (高级)

为非标准文库精确定义条形码（barcode）和有效序列（read）的提取结构。

功能: 当 --darkreaction 的预设模式不适用时，此参数提供终极控制。它会覆盖任何 --darkreaction 设置。
语法: "<type>,<read>:<start>-<end>;..."，多个段用分号(;)分隔，坐标为1-based。

参数类型详解

类型	说明	示例
`cb`	细胞条形码 (Cell Barcode)	`cb,R1:1-10`
`R1`	Read1 中的有效DNA序列	`R1,R1:21-70`
`R2`	Read2 中的有效DNA序列	`R2,R2:1-50`

示例:

# 示例1：假设其R1结构为：Barcode 1 (10bp) -> Barcode 2 (10bp) -> 插入序列 (50bp)。R2结构为：插入序列 (50bp)。
--customize "cb,R1:1-10;cb,R1:11-20;R1,R1:21-70;R2,R2:1-50"

# 示例2：假设其R1结构为：固定序列(6bp) -> Barcode 1 (10bp) -> 固定序列(6bp) -> Barcode 2 (10bp) -> 固定序列(33bp) -> 插入序列 (50bp)。R2结构为：固定序列(19bp) -> 插入序列(50bp)。
--customize "cb,R1:7-16;cb,R1:23-32;R1,R1:66-115;R2,R2:20-69"

⚠️ 注意事项：

必须使用引号：由于包含特殊字符，整个字符串必须用双引号包裹。
坐标精确：坐标范围不能超过FASTQ文件中的实际读长，否则会导致解析失败。

🟢 过滤设置参数

`--forcecells` (可选)

强制流程使用确切的细胞数量，此参数会覆盖软件的自动细胞检测结果。

功能: 当您希望分析一个预先知道数量的细胞群体时使用。
优先级: 这是最高优先级的过滤参数。

默认值: 无

示例:

# 强制输出5000个细胞进行分析
dnbc4tools atac run --name sample1 --fastqs ./fq --genomeDir ./ref --forcecells 5000

`--frags_cutoff` (可选)

设定用于保留细胞的最低唯一fragments数量。

功能: 这是核心的细胞质量控制参数。低于此阈值的细胞被认为数据质量不佳，将从后续分析中排除。
建议: 初次分析可使用默认值，然后根据网页报告中“TSS Targeting”部分的“Fragments计数分布图”来确定更合适的阈值。

默认值: 1000

示例:

# 将细胞过滤的fragments阈值降低到500
dnbc4tools atac run --name sample1 --fastqs ./fq --genomeDir ./ref --frags_cutoff 500

`--tss_cutoff` (可选)

设定用于保留细胞的最低TSS区域片段比例。

功能: TSS富集是ATAC-seq数据质量的关键指标。设置此阈值可有效排除细胞破损或核溶解等技术问题导致的低质量细胞。

默认值: 0 (不过滤)

示例:

# 过滤掉TSS区域片段比例低于0.1的细胞
dnbc4tools atac run --name sample1 --fastqs ./fq --genomeDir ./ref --tss_cutoff 0.1

`--jaccard_cutoff` (可选)

用于合并潜在属于同一个细胞的多个条形码（beads）的Jaccard相似度阈值。

功能: 基于染色质可及性模式的相似度来修正因上样或扩增偏好产生的“重复”细胞条形码。
模式: 支持手动设置阈值，或使用 auto 让软件基于OTSU算法自动确定最佳阈值。

默认值: auto

示例:

# 手动设置Jaccard相似度阈值为0.02
dnbc4tools atac run --name sample1 --fastqs ./fq --genomeDir ./ref --jaccard_cutoff 0.02

`--merge_cutoff` (可选)

设定参与Jaccard合并的磁珠（beads）所需的最低fragments数量。

功能: 只有fragments数量高于此阈值的磁珠才会被纳入Jaccard相似性计算和合并流程。合并后的有效细胞片段将用于后续的peak calling。
作用: 在合并前过滤掉低质量的磁珠，提高合并的准确性和效率。
建议: 对于fragments总量偏低的样本，可适当降低该值以纳入更多磁珠进行合并，从而获取更多有效片段用于后续分析。

默认值: 500

示例:

# 对于低fragment样本，将阈值降至200以纳入更多磁珠进行合并
dnbc4tools atac run --name sample1 --fastqs ./fq --genomeDir ./ref --merge_cutoff 200

🚩 分析设置参数

`--need_bam` (标志)

启用BAM格式文件的生成。

功能: 生成包含所有具有有效条形码且已比对的读段的BAM文件，可用于IGV等可视化工具或进行其他自定义分析。
注意: 启用此选项会显著增加计算时间和磁盘空间占用，预计运行时间会增加30-50%。此外，由于比对软件chromap在生成BAM文件和直接输出BED文件时存在差异，最终结果可能略有不同。

默认值: 不设置此参数则不生成BAM文件

`--sample_read_pairs` (可选)

从输入的FASTQ文件中提取指定数量的读段对进行分析。

功能: 用于在完整分析前对大数据集进行快速测试，或在资源有限时进行降采样分析。

默认值: 无 (使用全部数据)

示例:

--sample_read_pairs 100000000

💡 分析建议

首次分析时建议使用默认参数，获得结果报告后再根据需要调整参数。

📊 参考数据库构建 (mkref)

📊 用法

$ dnbc4tools atac mkref --help
Usage: dnbc4tools atac mkref [OPTIONS]
optional arguments:
  -h, --help           show this help message and exit

Input files:
  Input genome FASTA and gene annotation GTF files. For mixed species analysis, use comma to separate multiple files.

  --fasta <FILE>       Path to reference genome FASTA file. Multiple files separated by comma
  --ingtf <FILE>       Path to gene annotation GTF file. Multiple files separated by comma

Basic settings:
  --genomeDir <DIR>    Output directory for reference files [default: current directory]
  --species <STR>      Species identifier. For mixed species analysis, use comma separated [default: undefined]

Advanced settings:
  --tag <TYPE>         Select type to generate BED file [default: transcript]
  --chrM <STR>         Mitochondrial chromosome identifier in reference genome [default: auto]
  --chloroplast <STR>  Chloroplast chromosome name, particularly recommended for plants, e.g. "Pt"
  --prefix <STR>       Filter chromosomes by prefix or full name. Not supported for mixed species
  --kmer <INT>         k-mer length, this determines the size of the substrings being extracted [default: 17]
  --window <INT>       Window size, this defines the number of consecutive k-mers within a window [default: 7]
  --noindex            Only generate ref.json without building genome index

📝 参数说明

🔴 必需参数

`--fasta` (必需)

提供参考基因组序列文件。

要求: 标准FASTA格式，建议使用primary组装版本。
双物种: 支持提供两个以逗号分隔的FASTA文件用于混合物种分析。

默认值: 无

示例:

--fasta Homo_sapiens.GRCh38.dna.primary_assembly.fa

`--ingtf` (必需)

提供基因结构注释文件。

要求: 标准GTF格式，必须包含 gene 和 transcript 类型的注释条目。
功能: 用于定义TSS（转录起始位点）和启动子区域。

默认值: 无

示例:

--ingtf Homo_sapiens.GRCh38.108.gtf

🟢 输出设置参数

`--genomeDir` (可选)

指定生成的参考数据库的输出目录。

功能: 所有生成的参考文件（索引、注释等）都将存储在此目录中。

输出目录结构示例

<genomeDir/species>/
  ├── fasta/
  │   ├── genome.fa
  │   └── genome.index
  ├── genes/
  │   └── genes.gtf
  ├── regions/
  │   ├── chrom.sizes
  │   ├── promoter.bed
  │   └── tss.bed
  └── ref.json

默认值: ./ (当前目录)

示例:

dnbc4tools atac mkref --fasta genome.fa --ingtf genes.gtf --genomeDir /database/scATAC/GRCh38

`--species` (可选)

为参考数据库指定一个物种名称。

功能: 该名称会记录在配置文件中，便于后续识别。
建议: 使用标准的学名格式，如 Homo_sapiens。

默认值: undefined

示例:

dnbc4tools atac mkref --fasta genome.fa --ingtf genes.gtf --species Homo_sapiens

🟢 基因组设置参数

`--tag` (可选)

选择生成TSS（转录起始位点）文件的信息来源。

选项: gene (使用基因起始位点) 或 transcript (使用转录本起始位点)。
建议: 使用 transcript 模式可以获得更精确的TSS富集分析结果。

默认值: transcript

示例:

# 基于转录本起始位点生成TSS文件
dnbc4tools atac mkref --fasta genome.fa --ingtf genes.gtf --tag transcript

`--chrM` (可选)

指定线粒体染色体的名称。

功能: 用于细胞质量控制。线粒体片段过多通常指示细胞质量不佳。将线粒体片段纳入分析会影响TSS/peak区域片段的统计准确性。
自动检测: 默认会从常见名称（如 chrM, MT）中自动识别。

默认值: auto

示例:

# 如果线粒体染色体名称为"mitochondrion"
dnbc4tools atac mkref --fasta genome.fa --ingtf genes.gtf --chrM mitochondrion

`--chloroplast` (植物专用)

指定叶绿体染色体的名称，推荐植物样本使用。

功能: 用于植物样本的特定质量控制。将叶绿体片段纳入分析会影响TSS/peak区域片段的统计准确性。

默认值: 无

示例:

# 为拟南芥基因组指定叶绿体染色体名称
dnbc4tools atac mkref --fasta TAIR10.fa --ingtf Athaliana.gtf --chloroplast Pt

`--kmer` (可选)

设置Chromap索引构建时使用的k-mer长度。

功能: 影响比对的精确度、速度和内存使用。
建议: 对于标准分析，默认值通常是最佳选择。如果遇到内存不足的错误，可以尝试降低此值。

默认值: 17

示例:

# 降低k-mer长度以减少内存使用
dnbc4tools atac mkref --fasta genome.fa --ingtf genes.gtf --kmer 15

`--window` (可选)

设置Chromap索引构建时使用的窗口大小。

功能: 定义一个窗口内的连续k-mer数量，影响比对的灵敏度和特异性。
建议: 通常与 --kmer 参数协同调整以达到最佳效果。

默认值: 7

示例:

# 调整窗口大小
dnbc4tools atac mkref --fasta genome.fa --ingtf genes.gtf --window 5

`--noindex` (标志)

如果设置此参数，将只生成配置文件而不构建基因组索引。

功能: 当索引文件已存在时，使用此参数可以跳过耗时的索引构建步骤。

默认值: 不设置

示例:

# 仅生成配置文件，不构建索引
dnbc4tools atac mkref --fasta genome.fa --ingtf genes.gtf --noindex

Tip

📋 数据库构建说明：

使用Chromap构建的数据库目前无法处理极大的基因组，某些物种可能无法使用此软件进行scATAC分析，或者调整kmer和window参数来适配基因组索引构建。
数据库构建完成后，将在数据库目录中生成ref.json文件，记录关键信息

📋 ref.json文件示例：

{
    "species": "Homo_sapiens",
    "input_fasta_files": [
        "genome.fa"
    ],
    "input_gtf_files": [
        "genes.gtf"
    ],
    "genome": "/database/scATAC/Homo_sapiens/fasta/genome.fa",
    "index": "/database/scATAC/Homo_sapiens/fasta/genome.index",
    "gtf": "/database/scATAC/Homo_sapiens/genes/genes.gtf",
    "chrmt": "chrM",
    "chloroplast": "None",
    "chromeSize": "/database/scATAC/Homo_sapiens/regions/chrom.sizes",
    "tss": "/database/scATAC/Homo_sapiens/regions/tss.bed",
    "promoter": "/database/scATAC/Homo_sapiens/regions/promoter.bed",
    "version": "3.0beta",
    "blacklist": "None",
    "genomesize": "hs"
}

📋 重要说明：

chromeSize文件中列出的染色体名称将包含在fragments.tsv.gz文件中进行分析，未列出的染色体将被排除
自2.1.2版本起，blacklist参数已被移除，不再需要blacklist文件。如需要，可手动添加
黑名单区域的片段数量将记录在metadata文件output/singlecell.csv的blacklist_region_fragments列中
genomesize值用于MACS2 peak calling分析，MACS2对某些物种有特殊标识符，如人类为"hs"

📋 多样本操作 (multi)

📊 用法

$ dnbc4tools atac multi 
Usage: dnbc4tools atac multi [OPTIONS]
optional arguments:
  -h, --help         show this help message and exit
  --list <STR>       Path to the sample list file. Each line should contain sample name and FASTQ paths.
  --outdir <DIR>     Output directory. [default: current directory].
  --threads <INT>    Number of threads used for analysis.
  --genomeDir <DIR>  Path to the directory where genome files are stored.

📝 参数说明

🔴 必需参数

`--list` (必需)

指定包含多个样本信息的列表文件路径。

文件格式: 使用制表符(\t)分隔的文本文件，建议UTF-8编码。
列结构: 第一列为样本名称，第二列为该样本对应的FASTQ数据路径。

路径格式规则

多个fastq文件：使用逗号(,)分隔
R1和R2文件：使用分号(;)分隔
路径类型：支持绝对路径和相对路径

文件内容示例

# 场景1: 样本A，具有一对R1/R2文件
SampleA /path/to/SampleA_R1.fastq.gz;/path/to/SampleA_R2.fastq.gz

# 场景2: 样本B，具有两对R1/R2文件 (同一Read的文件用逗号分隔)
SampleB /path/to/B_L01_R1.fq.gz,/path/to/B_L02_R1.fq.gz;/path/to/B_L01_R2.fq.gz,/path/to/B_L02_R2.fq.gz

默认值: 无

📝 参数继承说明
对于其他分析参数设置，请参考dnbc4tools atac run命令的相应参数。

💡 提示

本文档持续更新中，如发现内容错误或需要补充的信息，欢迎反馈。

📝 文档版本： 3.0 beta | 最后更新： 2025年

🔬 DNBelab C Series HT scATAC Analysis Software
高性能单细胞ATAC测序数据分析流程

🧬 DNBelab C Series HT scATAC 分析参数

🔬 主分析流程 (run)

📊 用法

📝 参数说明

🔴 必需参数

-n, --name (必需)

-g, --genomeDir (必需)

🟢 输入文件参数

--fastqs (方式1)

-1, --fastq1 (方式2A)

-2, --fastq2 (方式2B)

🟢 基本设置参数

-o, --outdir (可选)

-t, --threads (可选)

🟢 文库设置参数

--darkreaction (可选)

--customize (高级)

🟢 过滤设置参数

--forcecells (可选)

--frags_cutoff (可选)

--tss_cutoff (可选)

--jaccard_cutoff (可选)

--merge_cutoff (可选)

🚩 分析设置参数

--need_bam (标志)

--sample_read_pairs (可选)

📊 参考数据库构建 (mkref)

📊 用法

📝 参数说明

🔴 必需参数

--fasta (必需)

--ingtf (必需)

🟢 输出设置参数

--genomeDir (可选)

--species (可选)

🟢 基因组设置参数

--tag (可选)

--chrM (可选)

--chloroplast (植物专用)

--kmer (可选)

--window (可选)

--noindex (标志)

📋 多样本操作 (multi)

📊 用法

📝 参数说明

🔴 必需参数

--list (必需)

`-n, --name` (必需)

`-g, --genomeDir` (必需)

`--fastqs` (方式1)

`-1, --fastq1` (方式2A)

`-2, --fastq2` (方式2B)

`-o, --outdir` (可选)

`-t, --threads` (可选)

`--darkreaction` (可选)

`--customize` (高级)

`--forcecells` (可选)

`--frags_cutoff` (可选)

`--tss_cutoff` (可选)

`--jaccard_cutoff` (可选)

`--merge_cutoff` (可选)

`--need_bam` (标志)

`--sample_read_pairs` (可选)

`--fasta` (必需)

`--ingtf` (必需)

`--genomeDir` (可选)

`--species` (可选)

`--tag` (可选)

`--chrM` (可选)

`--chloroplast` (植物专用)

`--kmer` (可选)

`--window` (可选)

`--noindex` (标志)

`--list` (必需)