# CIRI-toolkit
`CIRI-toolkit` is a high-performance circRNA detection and isoform reconstruction toolkit for large-scale transcriptome data. It provides CIRI3-compatible BSJ detection, read-level circRNA segment reconstruction, high-confidence isoform sequence output, and IGV-ready review tracks.
## Performance Benchmarking
Benchmark dataset: ~80 GB BAM file (~300 GB SAM).
| CIRI3 | BSJ detection | ~80 min |
| CIRI-toolkit | BSJ detection + isoform reconstruction | ~11.5 min |
## Prerequisites
- Rust >= 1.85.0 if building from source
- GCC >= 5
- `pigz` or `gzip`
- `samtools` in `PATH`, or set `SAMTOOLS=/path/to/samtools`
## Installation
Download a prebuilt binary from the [release page](https://bioinfo.ioz.ac.cn/git/zhangjy/CIRI-toolkit/releases), or build from source:
```bash
git clone https://bioinfo.ioz.ac.cn/git/zhangjy/CIRI-toolkit.git
cd CIRI-toolkit
cargo build --release
# Run the compiled binary
./target/release/ciri --help
```
## Quick Start
```bash
# Step 1. Align reads with BWA-MEM and write a BAM file.
# NOTE: BAM must **NOT** be coordinate-sorted.
bwa mem -t <threads> -T 19 <bwa_index> <R1.fastq.gz> <R2.fastq.gz> \
| samtools view -bS -@ <threads> -o <bam_file> -
# Step 2. Run CIRI-toolkit.
ciri \
-i <bam_file> \
-o <prefix> \
-r <reference_fasta> \
-a <annotation_gtf> \
-t <threads>
```
## Usage
```text
CIRI-toolkit: fast circRNA detection and isoform reconstruction
Usage: ciri [OPTIONS] --in <IN_SAM> --out <OUT_PREFIX> --ref <REF_FASTA>
Required arguments:
-i, --in <SAM/BAM> Input SAM/BAM file
-o, --out <PREFIX> Output prefix
-r, --ref <FASTA> Reference genome FASTA
Optional arguments:
-a, --anno <GTF> GTF annotation file
-m, --mapq <MIN_MAPQ> Minimum MAPQ for candidate BSJ reads (default: 10)
-s, --stringency <LEVEL> Stringency level [0/1/2] (default: 0)
--min-span <SIZE> Minimum circRNA span (default: 50)
--max-span <SIZE> Maximum circRNA span (default: 200000)
--linear-range-size-min <SIZE> Linear competitor search range size (default: 50000)
-t, --threads <THREADS> Number of worker threads (default: auto)
-M, --mem-per-thread <MEM> Maximum memory per thread (default: 512M; e.g., 2G)
Advanced arguments:
--circ <BED6> External BED6 circRNA catalog from `ciri-merge`
--1st-pass Output only `<prefix>.out` for first-pass BSJ detection
--2nd-pass Output only `<prefix>.segments` for second-pass segment detection
Debugging arguments:
--trace <READS> Comma-separated read IDs to trace in Scan1/Scan2
--debug Keep internal pipeline temporary files
--perf Write profiling report to `<prefix>.perf.log`
--continue Rebuild isoforms only from existing `<prefix>.out` + `<prefix>.segments`
-h, --help Print help
-v, --version Print version
```
**Note:** CIRI-toolkit keeps the CIRI3 BSJ detection, Scan2 rescue, and Summary stringency formulas, but its default command-line policy is tuned for downstream segment and isoform reconstruction. CIRI-toolkit defaults to `-s 0 --min-span 50`, while CIRI3 defaults to `-S 2 -Min 140`. To use the same filtering policy as CIRI3, run CIRI-toolkit with `-s 2 --min-span 140`.
## Outputs
The main output files are:
- `<prefix>.out`: CIRI3-compatible circRNA result table
- `<prefix>.bsj`: mate-level BSJ evidence display used for review/debugging
- `<prefix>.segments`: read-level BSJ/backward/outward segments
- `<prefix>.isoforms.gtf`: major isoform structure audit table for all reported circRNAs; attributes use `gene_id`, `transcript_id`, `type`, `evidence`, `weakness`, `score`, `bsj_reads`, `weight`, `exon_count`, and `isoform_len`
- `<prefix>.isoforms.fa`: high-confidence circRNA isoform sequences; FASTA IDs use `<circRNA_id>.iso1` and headers keep compact sequence/filter fields such as `type`, `evidence`, `len`, and `cirexon`
- `<prefix>.bedpe`: IGV-compatible BSJ anchor track
- `<prefix>.segments.bam` and `<prefix>.segments.bam.bai`: IGV-compatible segment alignments
- `<prefix>.log`: run log
### `.out` Format
`<prefix>.out` uses the CIRI3-compatible 13-column format:
```text
1. circRNA_ID
2. chr
3. circRNA_start
4. circRNA_end
5. #junction_reads
6. SM_MS_SMS
7. #non_junction_reads
8. junction_reads_ratio
9. circRNA_type
10. gene_id
11. strand
12. junction_reads_ID
13. Score
```
### Full-length isoform sequence assembly
`<prefix>.isoforms.fa` contains assembled circRNA isoform sequences, but
not every FASTA record has the same structural confidence. The FASTA header
includes `type` and `evidence` fields so users can choose a filtering strategy
that matches the tolerance of their downstream analysis.
Recommended filtering criteria:
- For the highest-confidence sequence set, use records with `type=mature` and
`evidence=phased_junction`; these isoforms are supported by phased read-chain
evidence across the selected junction path.
- For a balanced precision/recall set, include `type=estimate` records with
annotation-guided or unphased junction evidence, such as
`evidence=annotation_guided,unphased_junction`.
- Records containing `ambiguous_exon`, `low_coverage_exon`, or
`unconfident_long_exon` are retained to preserve recall, but should be treated
as lower-confidence candidates in sequence-sensitive downstream analyses.
## Multi-sample integration
For multi-sample integrated analysis, `ciri` provides a two-pass
workflow:
```bash
# Run the first pass: BSJ detection
ciri -i sample1.bam -o sample1_1st_pass -r ref.fa -a annotation.gtf -s 0 --1st-pass
ciri -i sample2.bam -o sample2_1st_pass -r ref.fa -a annotation.gtf -s 0 --1st-pass
# Merge detected BSJ sites
ciri-merge -i sample1_1st_pass.out sample2_1st_pass.out -o 1st_pass.bed
# Run the second pass: segment detection
ciri -i sample1.bam -o sample1_2nd_pass -r ref.fa -a annotation.gtf --circ 1st_pass.bed -s 0 --2nd-pass
ciri -i sample2.bam -o sample2_2nd_pass -r ref.fa -a annotation.gtf --circ 1st_pass.bed -s 0 --2nd-pass
# Prepare the sample list
printf "sample1\tsample1_2nd_pass\n" > sample_list.tsv
printf "sample2\tsample2_2nd_pass\n" >> sample_list.tsv
# Integrated assembly of circRNA isoforms
ciri-assemble -i sample_list.tsv -o merged -r ref.fa -a annotation.gtf
```
The final `merged.isoforms.fa` and `merged.isoforms.gtf` contain co-assembled isoform
structures and sequences. Isoform reconstruction and multi-sample assembly currently
run serially; this stage is fast on current validation datasets, and parallel
execution will be revisited when larger multi-sample datasets require it.
## Generate simulation datasets with `ciri-simulator`
CIRI-toolkit also includes `ciri-simulator`, which generates paired-end circRNA reads and structured truth tables from a reference genome and annotation.
```bash
ciri-simulator \
-r <reference_fasta> \
-a <source_gtf> \
-o <prefix> \
--circ-count 100 \
--circ-coverage 10 \
--linear-coverage 0.1 \
--exon-exclusive-rate 0.25 \
--seed 5
```
Simulator outputs:
- `<prefix>_1.fq.gz` and `<prefix>_2.fq.gz`: simulated paired-end reads
- `<prefix>.annotation.gtf`: masked linear annotation for de novo evaluation
- `<prefix>.isoforms.tsv`: isoform-level truth table
- `<prefix>.reads.tsv`: read-pair-level truth table
To generate a matched two-sample fixture with shared circRNA/isoform structures
and controlled major isoform switching, pass two output prefixes and set
`--switching-event`:
```bash
ciri-simulator \
-r <reference_fasta> \
-a <source_gtf> \
-o sample1 sample2 \
--circ-count 1000 \
--circ-coverage 100 \
--linear-coverage 10 \
--switching-event 200
```
The simulator writes the normal per-sample FASTQ/truth files for each prefix.
It also writes `<sample1>.usage.tsv` and `<sample2>.usage.tsv` with per-sample
isoform usage truth.