Package: isocirc
isoCirc: computational pipeline to identify high-confidence BSJs and full-length circRNA isoforms from isoCirc long-read dataWhat is isoCirc ?isoCirc is a long-read sequencing strategy coupled with an integrated
computational pipeline to characterize full-length circRNA isoforms
using rolling circle amplification (RCA) followed by long-read sequencing.Table of ContentsWhat is isoCirc?InstallationDependenciesInstall isoCirc withpipInstall isoCirc from sourceGetting startedInput and outputInput filesOutput files1.isocirc.out2.isocirc.bed3.isocirc_stats.outCircular long-read alignment of isoCirc readFAQContactChangelogInstallationDependenciesisoCirc is dependent on two open-source software packages:bedtools(>= v2.27.0)and minimap2minimap2(>= 2.11).
Please ensure that these packages are installed before running isoCirc.Install isoCirc withpipisoCircis written withpython, please usepipto installisoCirc:pip install isocirc            # first time installation
pip install isocirc --upgrade  # update to the latest versionInstall isoCirc from sourceAlternatively, you can installisoCircfrom source:git clone https://github.com/Xinglab/isoCirc.git
cd isoCirc/isoCirc_pipeline && pip install .Getting started with toy example intest_datacd isoCirc/test_data
isocirc -t 1 read_toy.fa chr16_toy.fa chr16_toy.gtf chr16_circRNA_toy.bed outputDetailed arguments:usage: isocirc [-h] [-v] [-t THREADS] [--bedtools BEDTOOLS]
               [--minimap2 MINIMAP2] [--short-read short.fa/fq] [--lordec LORDEC]
               [--kmer KMER] [--solid SOLID] [--trf TRF] [--match MATCH]
               [--mismatch MISMATCH] [--indel INDEL] [--match-frac MATCH_FRAC]
               [--indel-frac INDEL_FRAC] [--min-score MIN_SCORE]
               [--max-period MAX_PERIOD] [--min-len MIN_LEN]
               [--min-copy MIN_COPY] [--min-frac MIN_FRAC]
               [--high-max-ratio HIGH_MAX_RATIO]
               [--high-min-ratio HIGH_MIN_RATIO]
               [--high-iden-ratio HIGH_IDEN_RATIO]
               [--high-repeat-ratio HIGH_REPEAT_RATIO]
               [--low-repeat-ratio LOW_REPEAT_RATIO]
               [--cano-motif {GT/AG,all}] [--bsj-xid BSJ_XID]
               [--key-bsj-xid KEY_BSJ_XID] [--min-circ-dis MIN_CIRC_DIS]
               [--rescue-low] [--fsj-xid FSJ_XID] [--key-fsj-xid KEY_FSJ_XID]
               [--Alu ALU] [--flank-len FLANK_LEN] [--all-repeat ALL_REPEAT]
               long.fa/fq ref.fa anno.gtf circRNA.bed/gtf out_dir

isocirc: circular RNA profiling and analysis using long-read sequencing

positional arguments:
  long.fa/fq            Long-read sequencing data generated with isoCirc
  ref.fa                Reference genome sequence file
  anno.gtf              Gene annotation file in GTF format
  circRNA.bed/gtf       circRNA database annotation file in BED or GTF format
                        Use ',' to separate multiple circRNA annotation files
  out_dir               Output directory for final result and temporary files

optional arguments:
  -h, --help            Show this help message and exit
  -v, --version         Show program's version number and exit

General options:
  -t THREADS, --threads THREADS
                        Number of threads to use (default: 8)
  --bedtools BEDTOOLS   Path to bedtools (default: bedtools)
  --minimap2 MINIMAP2   Path to minimap2 (default: minimap2)

Hybrid error-correction with short-read data (LoRDEC):
  --short-read short.fa/fq
                        Short-read data for error correction 
                        Use ',' to connect multiple or paired-end short-read data
                        (default: )
  --lordec LORDEC       Path to lordec-correct (default: lordec-correct)
  --kmer KMER           k-mer size (default: 21)
  --solid SOLID         Solid k-mer abundance threshold (default: 3)

Consensus calling with Tandem Repeats Finder (TRF)):
  --trf TRF             Path to TRF program (default: trf409.legacylinux64)
  --match MATCH         Match score (default: 2)
  --mismatch MISMATCH   Mismatch penalty (default: 7)
  --indel INDEL         Indel penalty (default: 7)
  --match-frac MATCH_FRAC
                        Match probability (default: 80)
  --indel-frac INDEL_FRAC
                        Indel probability (default: 10)
  --min-score MIN_SCORE
                        Minimum alignment score to report (default: 100)
  --max-period MAX_PERIOD
                        Maximum period size to report (default: 2000)

Filtering and mapping of consensus sequences (minimap2):
  --min-len MIN_LEN     Minimum consensus length to keep (default: 30)
  --min-copy MIN_COPY   Minimum copy number of consensus to keep 
                        (default: 2.0)
  --min-frac MIN_FRAC   Minimum fraction of original long read to keep
                        (default: 0.0)
  --high-max-ratio HIGH_MAX_RATIO
                        Maximum mappedLen / consLen ratio for high-quality
                        alignment (default: 1.1)
  --high-min-ratio HIGH_MIN_RATIO
                        Minimum mappedLen /consLen ratio for high-quality
                        alignment (default: 0.9)
  --high-iden-ratio HIGH_IDEN_RATIO
                        Minimum identicalBases/ consLen ratio for high-quality
                        alignment (default: 0.75)
  --high-repeat-ratio HIGH_REPEAT_RATIO
                        Maximum mappedLen / consLen ratio for high-quality
                        self-tandem consensus (default: 0.6)
  --low-repeat-ratio LOW_REPEAT_RATIO
                        Minimum mappedLen / consLen ratio for low-quality
                        self-tandem alignment (default: 1.9)

Identifying high-confidence BSJs and full-length circRNAs:
  --cano-motif {GT/AG,all}
                        Canonical back-splice motif (GT/AG or all three
                        motifs: GT/AG, GC/AG, AT/AC) (default: GT/AG)
  --bsj-xid BSJ_XID     Maximum allowed mis/ins/del for 20-bp exonic sequence
                        flanking BSJ (10-bp each side) (default: 1)
  --key-bsj-xid KEY_BSJ_XID
                        Maximum allowed mis/ins/del for 4-bp exonic sequence
                        flanking BSJ (2-bp each side) (default: 0)
  --min-circ-dis MIN_CIRC_DIS
                        Minimum distance between genomic coordinates of
                        two back-splice sites (default: 150)
  --rescue-low          Use high-mapping quality reads to rescue low-mapping
                        quality reads (default: False)
  --fsj-xid SJ_XID       Maximum allowed mis/ins/del for 20-bp exonic sequence
                        flanking FSJ (10-bp each side) (default: 1)
  --key-fsj-xid KEY_SJ_XID
                        Maximum allowed mis/ins/del for 4-bp exonic sequence
                        flanking FSJ (2-bp each side) (default: 0)

Other options:
  --Alu ALU             Alu repetitive element annotation in BED format
                        (default: )
  --flank-len FLANK_LEN
                        Length of upstream and downstream flanking sequence to
                        search for Alu (default: 500)
  --all-repeat ALL_REPEAT
                        All repetitive element annotation in BED format
                        (default: )Input and outputInput filesisoCirc takes a long read containing multiple copies of a circRNA sequence as inputIt also requires a reference genome sequence and gene annotation to be provided.Output filesisoCirc outputs three result files in a user-specified directory:No.File nameExplanation1isocirc.outdetailed information of each circRNA isoform with a high-confidence BSJ, in tabular format2isocirc.bedbed12 format file ofisocirc.out3isocirc_stats.outbasic summary stats numbers forisocirc.out1. isocirc.outisocirc.outis a 35-column tabular file, each line represents one unique circRNA isoform that has a high-confidence BSJ:No.Column nameExplanation1isoformIDassigned isoform ID2chromchromosome ID3startCoor0basedstart coordinate of circRNA, 0-based4endCoorend coordinate of circRNA5geneStrandgene strand (+/-)6geneIDgene ID7geneNamegene name8blockCountnumber of block9blockSizesize of each block, separated by,10blockStartsrelative start coordinates of each block, separated by,. refer tobed12format for further details11refMapLentotal length of circRNA12blockTypecategory of each block. E: exon, I: intron, N: intergenic13blockAnnodetailed annotation for each block, in format: "TransID:E1(100)+I(50)+E2(30)", where TransID is ID of corresponding transcript; E1 and E2 are 1st and 2nd exon of transcript; multiple blocks are separated by,; and multiple transcripts of one block are separated by;14isKnownSSTrueif SS is catalogued in gene annotation,Falseif not, separated by,15isKnownFSJTrueif FSJ is catalogued in gene annotation,Falseif not, separated by,16canoFSJMotifstrandness and canonical motifs of FSJs, e.g.,-GT/AG,NAif FSJ is not canonical, separated by,17isHighFSJTrueif alignment around FSJ is high-quality,Falseif not, separated by,18isKnownExonTrueif block is a catalogued exon in gene annotation,Falseif not, separated by ‘,’19isKnownBSJTrueif BSJ exists in circRNA annotation,Falseif not; multiple circRNA annotations are separated by,20isCanoBSJTrueif BSJ has canonical motif (GT/AG),Falseif not21canoBSJMotifstrandness and canonical motif of BSJ, e.g.,-GT/AG,NAif BSJ is not canonical22isFullLengthTrueif isoform is considered asfull-length isoform,Falseif not23BSJCatecategory of BSJs:FSM/NIC/NNC, see explanation below.24FSJCatecategory of FSJs:FSM/NIC/NNC25CDSnumber of bases that are mapped to CDS region26UTRnumber of bases that are mapped to UTR region27lincRNAnumber of bases that are mapped to lincRNA region28antisensenumber of bases that are mapped to antisense region29rRNAnumber of bases that are mapped to rRNA region30Alunumber of bases that are mapped to Alu element;NAif Alu annotation is not provided31allRepeatnumber of bases that are mapped to all repeat elements;NAif repeat annotation is not provided32upFlankAluflanking Alu element in upstream;NAif none or Alu annotation is not provided33downFlankAluflanking Alu element in downstream;NAif none or Alu annotation is not provided34readCountnumber of reads that come from this circRNA isoform35readIDsID of reads that come from this circRNA isoform, separated by,2. isocirc.bedisocirc.bedis a bed12 format file, each line represents one unique circRNA isoform fromisocirc.out:No.Column nameExplanation1chromchromosome ID2startCoor0basedstart coordinate of circRNA, 0-based3endCoorend coordinate of circRNA4isoformNamename of the circRNA isoform5scoreindicates how dark the peak will be displayed in the browser (0-1000), set as 0 byisoCirc6strand+/- to denote strand7thickStartthe starting position at which the feature is drawn thickly, set as 0 byisoCirc8thickEndthe ending position at which the feature is drawn thickly, set as 0 byisoCirc9itemRgban RGB value of the form R,G,B (e.g. 255,0,0), set as 0 byisoCirc10blockCountnumber of block11blockSizesize of each block, separated by,12blockStartsrelative start coordinates of each block, separated by,. refer tobed12format for further details3. isocirc_stats.outisocirc_stats.outcontains 27 basic stats numbers forisocirc.out:No.NameExplanation1Total readsNumber of raw reads in sample2Total reads with consNumber of reads with consensus sequence called3Total mappable reads with consNumber of reads with consensus sequence called, mappable to genome4Total reads with candidate BSJNumber of reads with consensus sequence called, mappable to genome, and with BSJs ("candidate BSJs")5Total candidate BSJsNumber of candidate BSJs (circRNA species)6Total known candidate BSJsNumber of candidate BSJs reported in existing circRNA BSJ database (circBase / MiOncoCirc)7Total reads with high BSJsNumber of reads with consensus sequence called, mappable to genome, and with high-confidence BSJs (based on additional inspection of alignment around BSJs)8Total high BSJsNumber of high-confidence BSJs9Total known high BSJsNumber of high-confidence BSJs that are known10Total isoforms with high BSJsNumber of circRNA isoforms with high-confidence BSJs11Total isoforms with high BSJs high FSJsNumber of circRNA isoforms with high-confidence BSJs, and all FSJs are high-confidence (canonical, high-quality alignment around internal splice sites)12Total isoforms with high BSJ known SSsNumber of circRNA isoforms with high-confidence BSJs, and all SS are known (based on existing transcript GTF annotations for splice sites in linear RNA)13Total isoforms with high BSJs high FSJs known SSsNumber of circRNA isoforms with high-confidence BSJs, all FSJs are high-confidence, and all SS are known14Total full-length isoformsNumber of circRNA isoforms with high-confidence BSJs, and FSJs are high-confidence or all SS are known15Total reads for full-length isoformsNumber of reads for circRNA isoforms with high-confidence BSJs, and all FSJs arehigh-confidence or all SS are known16Total full-length isoforms with FSM BSJNumber of full-length circRNA isoforms with FSM BSJs17Total reads for full-length isoforms with FSM BSJNumber of reads for full-length circRNA isoforms with FSM BSJs18Total full-length isoforms with NIC BSJNumber of full-length circRNA isoforms with NIC BSJs19Total reads for full-length isoforms with NIC BSJNumber of reads for full-length circRNA isoforms with NIC BSJs20Total full-length isoforms with NNC BSJNumber of full-length circRNA isoforms with NNC BSJs21Total reads for full-length isoforms with NNC BSJNumber of reads for full-length circRNA isoforms with NNC BSJs22Total full-length isoforms with FSM FSJNumber of full-length circRNA isoforms with FSM FSJs23Total reads for full-length isoforms with FSM FSJNumber of reads for full-length circRNA isoforms with FSM FSJs24Total full-length isoforms with NIC FSJNumber of full-length circRNA isoforms with NIC internal FSJs25Total reads for full-length isoforms with NIC FSJNumber of reads for full-length circRNA isoforms with NIC FSJs26Total full-length isoforms with NNC FSJNumber of full-length circRNA isoforms with NNC FSJs27Total reads for full-length isoforms with NNC FSJNumber of reads for full-length circRNA isoforms with NNC FSJsBSJ:  Back-Splice JunctionFSJ:  Forward-Splice JunctionFSS:  Forward-Splice SiteSS:   Splice Sitecons: consensus sequencecano: canonicalhigh: high-confidence (canonical and high-quality alignment around FSJ/BSJ)FSM: Full Splice MatchNIC: Novel In CatalogNNC: Novel Not in CatalogCircular alignment of isoCirc long readWith the result file generated byisocirc, we can visulize the circular alignment of full-length isoCirc reads. Let's use the toy example in thetest_dataagain:isocircPlot ./read_toy.fa ./chr16_toy.fa ./chr16_toy.gtf ./output/isocirc.bed ./isocircPlot_toy.list SJ ./outputA.pngfile will be generated in theoutputfolder indicating how the isoCirc long read is aligned to the reference genome multiple times.FAQContactYan Gaogaoy286@mail.sysu.edu.cnYi Xingyi.xing@pennmedicine.upenn.edugithub issues