日本語版 README はこちら

DAJIN2 is a genotyping tool for genome-edited samples, utilizing nanopore target sequencing.

DAJIN2 takes its name from the Japanese phrase 一網打尽 (Ichimou DAJIN, or Yīwǎng Dǎjìn in Chinese),
which means “to capture everything in a single sweep.”
This reflects the tool’s design philosophy: to comprehensively detect both intended and unintended genome editing outcomes in one go.

🌟 Features

• Comprehensive Mutation Detection
  DAJIN2 can detect a wide range of genome editing events in nanopore-targeted regions, from point mutations to structural variants.
  It is particularly effective at identifying unexpected mutations and complex mutations, such as insertions within deleted regions.

• Highly Sensitive Allele Classification
  Supports classification of mosaic alleles, capable of detecting minor alleles present at approximately 1%.

• Intuitive Visualization
  Genome editing results are visualized in an intuitive manner, enabling rapid and easy identification of mutations.

• Multi-Sample Support
  Batch processing of multiple samples is supported, allowing efficient execution of large-scale experiments and comparative studies.

• Simple Installation and Operation
  Requires no specialized computing environment and runs smoothly on a standard laptop.
  Easily installable via Bioconda or PyPI, and usable via the command line.

🛠 Installation

System Requirements

Hardware

• Runs on a standard laptop
• Recommended memory: 8 GB or more

Note

DAJIN2 is the successor to DAJIN, which required a GPU for efficient computation due to its use of deep learning.
In contrast, DAJIN2 does not use deep learning and does not require a GPU.
Therefore, it runs smoothly on typical laptops.

Software

• Python 3.9-3.12
• Unix-based environment (Linux, macOS, WSL2, etc.)

Important

For Windows Users
DAJIN2 is designed to run in a Linux environment.
If you are using Windows, please use WSL2 (Windows Subsystem for Linux 2).

From Bioconda (Recommended)

# Setting up Bioconda
conda config --add channels defaults
conda config --add channels bioconda
conda config --add channels conda-forge
conda config --set channel_priority flexible

# Install DAJIN2
conda create -n env-dajin2 python=3.12 DAJIN2 -y
conda activate env-dajin2

From PyPI

pip install DAJIN2

Important

DAJIN2 is actively being developed and improved.
Please make sure you are using the latest version to take advantage of the newest features.

🔍 To check your current version:

DAJIN2 --version

➡️ Check the latest version:
https://github.com/akikuno/DAJIN2/releases

🔄 To update to the latest version:

conda update DAJIN2 -y

or

pip install -U DAJIN2

Caution

If you encounter any issues during the installation, please refer to the Troubleshooting Guide

💻 Usage

Required Files

FASTQ/FASTA/BAM Files for Sample and Control

In DAJIN2, a control that has not undergone genome editing is necessary to detect genome-editing-specific mutations. Specify a directory containing the FASTQ/FASTA (both gzip compressed and uncompressed) or BAM files of the genome editing sample and control.

Basecalling with Guppy

After basecalling with Guppy, the following file structure will be output:

fastq_pass
├── barcode01
│   ├── fastq_runid_b347657c88dced2d15bf90ee6a1112a3ae91c1af_0_0.fastq.gz
│   ├── fastq_runid_b347657c88dced2d15bf90ee6a1112a3ae91c1af_10_0.fastq.gz
│   └── fastq_runid_b347657c88dced2d15bf90ee6a1112a3ae91c1af_11_0.fastq.gz
└── barcode02
    ├── fastq_runid_b347657c88dced2d15bf90ee6a1112a3ae91c1af_0_0.fastq.gz
    ├── fastq_runid_b347657c88dced2d15bf90ee6a1112a3ae91c1af_10_0.fastq.gz
    └── fastq_runid_b347657c88dced2d15bf90ee6a1112a3ae91c1af_11_0.fastq.gz

Assuming barcode01 is the control and barcode02 is the sample, the respective directories are specified as follows:

• Control: fastq_pass/barcode01
• Sample: fastq_pass/barcode02

Basecalling with Dorado

For basecalling with Dorado (dorado demux), the following file structure will be output:

dorado_demultiplex
├── EXP-PBC096_barcode01.bam
└── EXP-PBC096_barcode02.bam

Important

Store each BAM file in a separate directory. The directory names can be set arbitrarily.

dorado_demultiplex
├── barcode01
│   └── EXP-PBC096_barcode01.bam
└── barcode02
    └── EXP-PBC096_barcode02.bam

Similarly, store the FASTA files outputted after sequence error correction with dorado correct in separate directories.

dorado_correct
├── barcode01
│   └── EXP-PBC096_barcode01.fasta
└── barcode02
    └── EXP-PBC096_barcode02.fasta

Assuming barcode01 is the control and barcode02 is the sample, the respective directories are specified as follows:

• Control: dorado_demultiplex/barcode01 / dorado_correct/barcode01
• Sample: dorado_demultiplex/barcode02 / dorado_correct/barcode02

FASTA File Including Anticipated Allele Sequences

The FASTA file should contain descriptions of the alleles anticipated as a result of genome editing.

Important

A header name >control and its sequence are necessary.

If there are anticipated alleles (e.g., knock-ins or knock-outs), include their sequences in the FASTA file too. These anticipated alleles can be named arbitrarily.

Below is an example of a FASTA file:

>control
ACGTACGTACGTACGT
>knock-in
ACGTACGTCCCCACGTACGT
>knock-out
ACGTACGT

Here, >control represents the sequence of the control allele, while >knock-in and >knock-out represent the sequences of the anticipated knock-in and knock-out alleles, respectively.

Important

Ensure that both ends of the FASTA sequence match those of the amplicon sequence. If the FASTA sequence is longer or shorter than the amplicon, the difference may be recognized as an indel.

Single Sample Analysis

DAJIN2 allows for the analysis of single samples (one sample vs one control).

DAJIN2 <-s|--sample> <-c|--control> <-a|--allele> <-n|--name> \
  [-g|--genome] [-b|--bed] [-t|--threads] [--no-filter] [-h|--help] [-v|--version]

Options:
-s, --sample            Specify the path to the directory containing sample FASTQ/FASTA/BAM files.
-c, --control           Specify the path to the directory containing control FASTQ/FASTA/BAM files.
-a, --allele            Specify the path to the FASTA file.
-n, --name (Optional)   Set the output directory name. Default: 'Results'.
-g, --genome (Optional) Specify the reference UCSC genome ID (e.g., hg38, mm39). Default: '' (empty string).
-b, --bed (Optional)    Specify the path to BED6 file containing genomic coordinates. Default: '' (empty string).
-t, --threads (Optional) Set the number of threads. Default: 1.
--no-filter (Optional)  Disable minor allele filtering (keep alleles <0.5%). Default: False.
-h, --help              Display this help message and exit.
-v, --version           Display the version number and exit.

Using BED Files for Genomic Coordinates

If the reference genome is not from UCSC, you can specify a BED file using the -b/--bed option.

When using the -b/--bed option with a BED file, please ensure:

1. Use BED6 format (6 columns required):

   chr1    1000000    1001000    248956422    0    +
   

   Column descriptions:

   • Column 1: Chromosome name (e.g., chr1, chr2)
   • Column 2: Start position (0-based, inclusive)
   • Column 3: End position (0-based, exclusive)
   • Column 4: Feature name (use chromosome size for proper IGV visualization)
   • Column 5: Score (typically 0)
   • Column 6: Strand (+ or -, must match FASTA allele orientation)

2. Match strand orientation: The strand field (column 6: + or -) in your BED file must match the strand orientation of your FASTA allele sequences.

   • If your FASTA allele sequence is on the forward strand (5' to 3'), use + in the BED file
   • If your FASTA allele sequence is on the reverse strand (3' to 5'), use - in the BED file

3. Why strand matters:

   • DAJIN2 automatically applies reverse complement processing for minus strand regions
   • Strand information is preserved in BAM files for proper IGV genome browser visualization
   • Incorrect strand information can lead to misaligned sequences and inaccurate mutation detection

For detailed BED file usage, see BED_COORDINATE_USAGE.md.

Rare Mutation Detection with --no-filter

By default, DAJIN2 filters out alleles with read counts below 0.5% (5 reads out of 100,000 downsampled reads) to reduce noise and improve accuracy. However, when analyzing rare mutations or somatic mosaicism where minor alleles may be present at very low frequencies, you can use the --no-filter option to disable this filtering.

When to use --no-filter:

• Detecting rare somatic mutations (< 0.5% frequency)
• Analyzing samples with suspected low-level mosaicism
• Research requiring detection of all possible alleles regardless of frequency

Usage:

DAJIN2 \
    --control example_single/control \
    --sample example_single/sample \
    --allele example_single/stx2_deletion.fa \
    --name stx2_deletion \
    --genome mm39 \
    --threads 4 \
    --no-filter

Caution

Using --no-filter may increase noise and false positives in the results. It is recommended to validate rare alleles through additional experimental methods.

Example

# Download example dataset
curl -LJO https://github.com/akikuno/DAJIN2/raw/main/examples/example_single.tar.gz
tar -xf example_single.tar.gz

# Run DAJIN2
DAJIN2 \
    --control example_single/control \
    --sample example_single/sample \
    --allele example_single/stx2_deletion.fa \
    --name stx2_deletion \
    --genome mm39 \
    --threads 4

Batch Processing

By using the batch subcommand, you can process multiple samples simultaneously.
For this purpose, a CSV or Excel file consolidating the sample information is required.

Note

For guidance on how to compile sample information, please refer to this document.

Required columns: sample, control, allele, name
Optional columns: genome, bed (or genome_coordinate), and any custom columns

Example CSV with BED files:

sample,control,allele,name,bed
/path/to/sample1,/path/to/control1,/path/to/allele1.fa,experiment1,/path/to/coords1.bed
/path/to/sample2,/path/to/control2,/path/to/allele2.fa,experiment2,/path/to/coords2.bed

Tip

It is recommended to use the same value in the name column for samples that belong to the same experiment.
Using identical names enables parallel processing, thereby improving efficiency.
Here's an example 👉 batch.csv

DAJIN2 batch <-f|--file> [-t|--threads] [--no-filter] [-h]

options:
  -f, --file                Specify the path to the CSV or Excel file.
  -t, --threads (Optional)  Set the number of threads. Default: 1.
  --no-filter (Optional)    Disable minor allele filtering (keep alleles <0.5%). Default: False.
  -h, --help                Display this help message and exit.

Example

# Donwload the example dataset
curl -LJO https://github.com/akikuno/DAJIN2/raw/main/examples/example_batch.tar.gz
tar -xf example_batch.tar.gz

# Run DAJIN2
DAJIN2 batch --file example_batch/batch.csv --threads 4

GUI (Graphical User Interface) Mode

DAJIN2 provides a web interface that can be launched with a single command:

DAJIN2 gui

When executed, your default web browser will open and display the following GUI at http://localhost:{PORT}/.

Note

If the browser does not launch automatically, please open your browser manually and navigate to http://localhost:{PORT}/.

Single Sample Analysis via GUI

1. Launch GUI
   Run DAJIN2 gui to open the web interface.

2. Project Setup

   • Project Name: Enter any analysis name
   • Directory Upload: Select directories containing sample or control FASTQ/FASTA/BAM files
   • Allele FASTA: Upload FASTA file containing expected allele sequences
   • BED File (optional): Upload BED6 format file to specify genomic coordinates

3. Parameter Configuration

   • Reference Genome (optional): Specify UCSC genome ID (e.g., hg38, mm39)
   • Threads: Set the number of CPU threads to use
   • No Filter: Enable to detect rare mutations below 0.5% frequency

4. Run Analysis
   Click "Start Analysis" and the progress will be displayed in real-time.

5. View Results
   After completion, the output folder path will be displayed for accessing result files.

Batch Processing via GUI

1. Prepare Batch File
   Create a CSV or Excel file with columns: sample, control, allele, name.

2. Upload Batch File
   Use the "Batch Processing" tab to upload your configuration file.

3. Configure Global Settings
   Set threads and filtering options for all samples at once.

4. Monitor Progress
   The analysis status for each sample is displayed with detailed log output.

5. View Results
   Results are saved in the DAJIN_Results/ folder with subdirectories for each sample.

📈 Reports

Upon completion of DAJIN2 processing, a directory named DAJIN_Results/{NAME} is generated.
Inside the DAJIN_Results/{NAME} directory, the following files can be found:

DAJIN_Results/tyr-substitution
├── BAM
│   ├── tyr_c230gt_01
│   ├── tyr_c230gt_10
│   ├── tyr_c230gt_50
│   └── tyr_control
├── FASTA
│   ├── tyr_c230gt_01
│   ├── tyr_c230gt_10
│   └── tyr_c230gt_50
├── HTML
│   ├── tyr_c230gt_01
│   ├── tyr_c230gt_10
│   └── tyr_c230gt_50
├── MUTATION_INFO
│   ├── tyr_c230gt_01.csv
│   ├── tyr_c230gt_10.csv
│   └── tyr_c230gt_50.csv
├── read_plot.html
├── read_plot.pdf
└── read_summary.xlsx

1. BAM

The BAM directory contains the BAM files of reads classified by allele.

Note

Specifying a reference genome using the genome option will align the reads to that genome.
Without genome options, the reads will align to the control allele within the input FASTA file.

2. FASTA and HTML

The FASTA directory stores the FASTA files of each allele.
The HTML directory contains HTML files for each allele, where mutation sites are color-highlighted.
For example, Tyr point mutation is highlighted in green.

Furthermore, DAJIN2 extracts representative SV alleles (Insertion, Deletion, Inversion) included in the sample and highlights SV regions with colored underlines.
The following is an example where a deletion (light blue) and an insertion (red) are observed at both ends of an inversion (purple underline):

3. MUTATION_INFO

The MUTATION_INFO directory saves tables depicting mutation sites for each allele.
An example of a Tyr point mutation is described by its position on the chromosome and the type of mutation.

4. read_summary.xlsx, read_plot.html and read_plot.pdf

read_summary.xlsx summarizes the number and proportion of reads per allele.
Both read_plot.html and read_plot.pdf illustrate the proportions of each allele.
The chart's Allele type indicates the type of allele, and Percent of reads shows the proportion of reads for each allele.

The Allele type includes:

• Intact: Alleles that perfectly match the input FASTA allele.
• Indels: Substitutions, deletions, insertions, or inversions within 50 bases.
• SV: Substitutions, deletions, insertions, or inversions beyond 50 bases.

Warning

In PCR amplicon sequencing, the % of reads might not match the actual allele proportions due to amplification bias.
Especially when large deletions are present, the deletion alleles might be significantly amplified, potentially not reflecting the actual allele proportions.

📣 Feedback and Support

We welcome your questions, bug reports, and feedback.
Please use the following Google Form to submit your report:
👉 Google Form

If you have a GitHub account, you can also submit reports via
👉 GitHub Issues

Please refer to CONTRIBUTING for how to contribute and how to verify your contributions.

Note

For frequently asked questions, please refer to this page.

🤝 Code of Conduct

Please note that this project is released with a Contributor Code of Conduct.
By participating in this project you agree to abide by its terms.

📄 References

For more information, please refer to the following publication:

Kuno A, et al. (2022) DAJIN enables multiplex genotyping to simultaneously validate intended and unintended target genome editing outcomes. PLoS Biology 20(1): e3001507.