🏠 Home • 中文

🔬 Main Analysis Pipeline (run)

$ dnbc4tools vdj run -h
usage: dnbc4tools vdj 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) (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) (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.
  -r, --ref <REF>         Reference database: 'human'/'mouse' (case-insensitive) or path to a custom reference directory containing reference.json. Examples: human | mouse | ./custom_vdj_ref
  -c, --chain <STR>     VDJ receptor type: 'IG' (B-cell receptors) or 'TR' (T-cell receptors).
  -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: all available cores] (e.g., 16).
  -s, --beadstrans <FILE>
                        RNA analysis singlecell.csv file for filtering cells and merging beads information. When not provided, all cells will be kept by default (equivalent to --keep_all_cells).

Library Settings:
  Auto-detection is recommended for dark cycles. Available modes include "R1" and "unset".
  For multiple files, ensure consistent settings across all inputs.
  customize: Specify sequence structure patterns for parsing.

  --darkreaction <STR>  Dark cycle setting for VDJ library [default: auto]. Use 'R1' if dark cycles occur in Read1; otherwise leave as 'auto' or 'unset'.
  --customize <STR>     Sequence structure patterns, format: <type>,<read>:<start>-<end> separated by ';'. Types include: cb (cell barcode), umi (UMI) R1/R2 (sequence). Example:
                        "cb,R1:1-10;cb,R1:11-20;umi,R1:21-30;R1,R1:31-120;R2,R2:1-150"
  --enrichment_primers <FILE>
                        Custom inner enrichment primers file (one primer sequence per line). Required when using a custom reference database.

Analysis Settings:
  --keep_all_cells      Keep all cells in analysis without RNA data filtering. If --beadstrans is not provided, this behavior is enabled by default.
  --r2_only             Only use R2 reads for VDJ assembly. Manual setting required because Read1 assembly requirements cannot be auto-detected.
  --sample_read_pairs <INT>
                        Subsample the specified number of read pairs from the input FASTQ files (e.g., 1000000).

-n, --name (Required)

Provide a unique name for this analysis run.

• Function: This name will be used as a prefix for all output files and the HTML report.
• Display: In the final web report, this name will be shown as the Sample ID.

Default: None

Example:

--name sample_VDJ_001

-r, --ref (Required)

Specify the reference database to be used for VDJ analysis.

• Function: Specifies the reference database for VDJ analysis.
• Built-in Support: The software comes with reference databases for human (human) and mouse (mouse).
• Custom Support: A path to a custom reference directory containing a reference.json file can be provided.

Default: None

Examples:

# Use the built-in human reference database
--ref human

# Use a custom reference database
--ref ./custom_vdj_ref

-c, --chain (Required)

Specify the type of immune receptor to be analyzed.

• Core Function: Specifies the immune receptor type for analysis, directly impacting the identification and recombination analysis of V(D)J gene segments.
• TR: T-cell Receptor, for T-cell studies.
• IG: Immunoglobulin, for B-cell studies.

Default: None

Examples:

# Analyze T-cell receptors
--chain TR

# Analyze B-cell receptors
--chain IG

--fastqs (Method 1)

Specify the path to the directory containing all FASTQ files.

• Function: The pipeline will automatically detect paired files (R1/R2) within this directory.
• Note: This is a convenience option and cannot be used simultaneously with --fastq1 / --fastq2.

Default: None

Example:

--fastqs ./VDJ_fastq_dir

-1, --fastq1 (Method 2A)

Specify one or more Read1 FASTQ files for the VDJ library individually.

• Support: You can use wildcards (*) to match files or a comma-separated list for multiple files.
• Requirement: Must be used in pairs with the --fastq2 parameter, and the file order must match exactly.

Default: None

Example:

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

-2, --fastq2 (Method 2B)

Specify one or more Read2 FASTQ files for the VDJ library individually.

• Support: You can use wildcards (*) to match files or a comma-separated list for multiple files.
• Requirement: Must be used in pairs with the --fastq1 parameter, and the file order must match exactly.

Default: None

Example:

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

-o, --outdir (Optional)

Specify the output directory for all analysis results and reports.

• Function: All analysis results will be saved in this directory, and the pipeline will automatically create a structured subdirectory named after the sample.

Default: ./ (current directory)

Example:

--outdir ./VDJ_analysis_output

-t, --threads (Optional)

Set the number of CPU threads to be used during the analysis.

• Function: Increasing the number of threads can significantly speed up the analysis.
• Recommendation: Adjust based on the number of available CPU cores for optimal performance.

Default: Use all available CPU cores

Example:

--threads 16

-s, --beadstrans (Optional)

Provide the singlecell.csv file from a scRNA analysis for cell filtering and information integration.

• Function: By integrating results from a 5' scRNA analysis, this enables bead merging and cell filtering, thereby establishing a precise correspondence between the single-cell RNA expression profile and the VDJ recombination sequence.
• Requirement: Using this feature requires providing the singlecell.csv output file from a 5' scRNA analysis of the same sample.
• Note: If this parameter is not specified, the bead merging step will be skipped, and all detected cells will be retained by default (equivalent to enabling --keep_all_cells).

Default: None

Example:

--beadstrans ./RNA_analysis_output/outs/singlecell.csv

--darkreaction (Optional)

Configure the dark cycle settings for the VDJ library.

• Function: Guides the software to correctly parse dark reaction cycles generated by the sequencing chemistry.
• Smart Detection (auto): Default setting. The software automatically identifies the structure by analyzing the sequence. Highly recommended for initial analysis.
• Manual Settings: Options are R1 (dark cycle in Read1) or unset (no dark cycle).

Default: auto

Example:

# Dark cycle present in Read1
--darkreaction R1

⚠️ Important Note: Incorrect settings may lead to cell barcode identification failure. Specify manually only if you know the library structure or if auto-detection fails.

--customize (Advanced)

Precisely define the extraction structure for barcodes, UMIs, and effective sequences (reads) for non-standard libraries. This is an advanced feature that overrides --darkreaction settings.

• Syntax: "<type>,<read>:<start>-<end>", with multiple segments separated by semicolons (;).
  • Parameter Types (type): cb (cell barcode), umi (UMI), R1/R2 (effective sequence).
• Notes:
  • The entire parameter string must be enclosed in quotes.
  • Coordinates are 1-based and cannot exceed the read length.

Example:

# Example of a standard VDJ library configuration
--customize "cb,R1:1-10;cb,R1:11-20;umi,R1:21-30;R1,R1:31-120;R2,R2:1-150"

⚠️ Risk Warning: Incorrect custom configurations can lead to data loss or analysis failure. Use only when standard configurations do not meet your needs.

--enrichment_primers (Optional)

Specify a file containing internal enrichment primers for VDJ region-specific amplification.

• Application: For VDJ libraries designed for non-human/mouse species or using custom primers.
• Format: A plain text file with one primer sequence per line.
• Requirement: This parameter is required when using a custom reference database.

Default: None

Example file content:

GTCCTCGGTGGCCTCCACGTG
AGCACCTGGGGCCTCGGCCAC
CCTGGACTCCTGGGCCCCAG

--keep_all_cells (Flag)

Enable this parameter to retain all detected cells without filtering based on RNA data.

• Function: This behavior is automatically enabled when the --beadstrans parameter is not provided. It is suitable for standalone VDJ analysis or when maximizing cell recovery is desired.

Default: Not set (but enabled by default if --beadstrans is absent)

--r2_only (Flag)

Enable this parameter to use only Read2 sequences for VDJ assembly.

• Function: Suitable for library designs where Read1 contains only barcode and UMI information.
• Note: The software cannot auto-detect this situation; it must be specified manually based on the library design.

Default: Not set

--sample_read_pairs (Optional)

Extract a specified number of read pairs from the input FASTQ files for analysis.

• Function: Used for quick testing of large datasets before a full analysis, or for down-sampling analysis when resources are limited.
• Note: Subsampling may affect the detection of low-frequency clonotypes. It is recommended to use the full dataset for formal analysis.

Default: None (uses all data)

Example:

--sample_read_pairs 10000000

💡 Tip

This document is continuously updated. If you find any errors or have information to add, your feedback is welcome.

📝 Document Version: 3.0 beta | Last Updated: 2025

---

🧬 DNBelab C Series HT scVDJ Analysis Software
High-performance single-cell immune repertoire data analysis pipeline