GPTomics Version Compatibility
Reference examples tested with: PureCLIP 1.3.1+, CTK 1.1.4+, PARalyzer 1.5+, wavClusteR 2.34+, pyCRAC 1.5+, samtools 1.19+, bedtools 2.31+, pysam 0.22+, R 4.3+.
Before using code patterns, verify installed versions match. If versions differ:
- CLI:
<tool> --versionthen<tool> --helpto confirm flags - Python:
pip show <package>thenhelp(module.function)to check signatures - R:
packageVersion('<pkg>')then?function_nameto verify parameters
If code throws unexpected errors, introspect the installed tool and adapt the example to match the actual CLI rather than retrying.
CLIP-seq Crosslink-Site Detection
"Detect single-nucleotide crosslink sites in my CLIP data" -> Identify the exact base where the protein-RNA UV adduct caused the reverse transcriptase to stop (truncation, in iCLIP/eCLIP), to read through with a mutation (deletion in HITS-CLIP, T->C in PAR-CLIP), or to leave a multi-base signature (PARalyzer kernel density for PAR-CLIP). Single-nucleotide resolution is the foundation of motif registration (mCross), allele-specific binding (BEAPR/ASPRIN), variant-effect prediction, and the most rigorous comparisons across CLIP variants. The detection chemistry differs by CLIP type: iCLIP/eCLIP read 5' end is one nucleotide downstream of the crosslink (CITS); PAR-CLIP reads contain T->C transitions at the crosslink (CIMS substitution); HITS-CLIP reads contain deletions at the crosslink (CIMS deletion).
- CLI (HMM, all CLIP variants):
pureclip -i dedup.bam -bai dedup.bam.bai -g genome.fa -ibam sminput.bam -ibai sminput.bam.bai -o crosslinks.bed -or regions.bed -nt 8 -dm 8 - CLI (CTK CITS truncations, iCLIP/eCLIP):
parseAlignment.pl --map-qual 1 --min-len 18 --mutation-file mut.txt dedup.bam dedup.bedthentag2cluster.pl ... -cs5 5 -m 1for truncation-cluster - CLI (CTK CIMS deletions, HITS-CLIP):
getMutationType.pl dedup.bed mut.txt -type delthenCIMS.pl dedup.bed mut.txt -big -c -p 0.01 cims.bed - CLI (CTK CIMS T->C, PAR-CLIP):
getMutationType.pl dedup.bed mut.txt -type sub -nuc t -mut cthenCIMS.pl dedup.bed t2c.mut -p 0.001 t2c_cims.bed - CLI (PAR-CLIP kernel density):
PARalyzer params.ini(parameters file defines read length, min reads per cluster, mutation rate threshold) - CLI (PAR-CLIP wavClusteR R):
wavClusteR::filterClusters(cl, snps=NULL, filterFC=FALSE)after wavelet clustering
Single-nt CL sites are the input to mCross motif registration (see clip-seq/clip-motif-analysis), to BEAPR/ASPRIN allele-specific binding analyses, and to RBPNet/DeepRiPe deep-learning models (see clip-seq/clip-deep-learning). They are NOT a replacement for broad peak calls; the two outputs are complementary. A common downstream error is passing a CLIPper peak BED to mCross instead of a PureCLIP single-nt BED - mCross requires the single-nt resolution to register motif position relative to the crosslink offset.
Crosslink Chemistry by CLIP Variant
The detection method must match the underlying chemistry of how the reverse transcriptase encountered the protein-RNA adduct:
| CLIP variant | RT behavior at CL | Detection signature | Sensitivity (CL captured per read) | Sequence bias |
|---|---|---|---|---|
| iCLIP / iCLIP2 / iCLIP3 / eCLIP / irCLIP / FLASH | Truncates at adduct | 5' end of cDNA = CL site - 1 | ~80% of reads truncate; the minority read through | Strong U bias at CL sites |
| HITS-CLIP | Reads through with deletion (~8-20% of tags) | Single-base deletion in read | ~8-20% of tags contain a deletion at the CL site | U bias plus sequence-specific deletion rate |
| PAR-CLIP (4SU) | Reads through with T->C (20-50% of T positions in crosslinked reads) | T->C transition (or G->A on reverse strand) | Per-T rate 20-50%; per-read 1-5 conversions | Restricted to T positions; depends on 4SU incorporation rate |
| PAR-CLIP (6SG) | Reads through with G->A | G->A transition | Lower rate than 4SU T->C | Restricted to G positions |
| miCLIP / miCLIP2 (m6A) | Primarily truncation at the m6A site (RT stops at antibody-trapped m6A); secondary C->T transition observed in a subset of reads at m6A | 5' end (CL -1); C->T rate is a feature used by m6Aboost ML in addition to truncation, not a stand-alone primary signal | Mixed; m6Aboost ML integrates truncation + sequence context to score | DRACH motif context required |
| STAMP | C->T editing on target (not crosslink) | C->T editing in mRNA reads | NA (editing-based; not crosslink-based) | N/A |
| TRIBE | A->I editing on target | A->G in cDNA (I read as G) | NA | Adjacent to ADAR consensus |
Algorithmic Taxonomy
| Tool | CLIP variant | Detection signal | Statistical model | Output resolution | Strength | Fails when |
|---|---|---|---|---|---|---|
| PureCLIP (Krakau 2017) | iCLIP/eCLIP/PAR-CLIP | Truncation + enrichment + CL motif | Non-homogeneous HMM | Single-nucleotide | The most comprehensive HMM model | Lowest F1 among callers benchmarked in Boyle 2023 on broad-binding RBPs (highly focal) |
| CTK CITS (Shah 2017) | iCLIP/eCLIP | Truncation only | Empirical FDR vs background | Single-nucleotide | Simple, well-validated for iCLIP | Less granular than PureCLIP; no HMM smoothing |
| CTK CIMS deletion (Shah 2017) | HITS-CLIP | Single-base deletions | Empirical FDR | Single-nucleotide | Standard for HITS-CLIP | Requires deletion-tolerant aligner (BWA -e) |
| CTK CIMS T->C (Shah 2017) | PAR-CLIP | T->C substitutions | Empirical FDR | Single-nucleotide | Alternative to PARalyzer | Less popular than PARalyzer |
| PARalyzer (Corcoran 2011) | PAR-CLIP | T->C transitions, kernel density | Kernel density estimation | Cluster (10-50 nt) | Field standard for PAR-CLIP | Cluster-level, not single-nt; needs careful parameter tuning |
| wavClusteR (Comoglio 2015) | PAR-CLIP | T->C with wavelet smoothing | Wavelet transform + clustering | Cluster | Robust to sequencing depth variability | Less single-nt; legacy R package |
| pyCRAC / kPLogo | CRAC (yeast) | Read truncation + deletion | Empirical | Single-nucleotide | Original CLIP analytics tool | Yeast-focused; perl/python legacy |
| Piranha bins | Any | Coverage in bins | ZTNB | Bin-level (50-200 nt) | Not crosslink-specific | Bin width too coarse for single-nt |
| HOMER tag2pos | Any | 5' end position | None | Read-end positions only | Quick truncation site dump | No statistical filtering |
| omniCLIP | Any | Coverage + variant pattern | Dirichlet-multinomial HMM | Region | Not focal | Too broad for single-nt |
| iCount (paths) | iCLIP | Crosslink site cluster | Empirical | Cluster | Used in nf-core/clipseq | Less single-nt than PureCLIP |
Methodology evolves; PureCLIP 2.0 and CTK 1.2 have minor flag changes; PARalyzer parameters need careful tuning per-RBP. Cross-validate single-nt sites with at least two tools when high-confidence reporting is required.
Critical Choice: Truncation vs Mutation vs HMM
Three orthogonal approaches:
Truncation-based (CITS, PureCLIP) -- Find positions enriched in cDNA 5' ends. The RT enzyme stops at the adduct; the 5' end of the read maps to CL site - 1. Used for iCLIP/eCLIP. Pro: high yield (~80% of reads truncate). Con: U bias of crosslinking inflates U positions.
Mutation-based (CIMS for deletions/substitutions; PARalyzer for T->C) -- Find positions with crosslink-induced mutations. RT reads through the adduct with high mutation rate at the CL position. Used for HITS-CLIP (deletions, ~8-20%) and PAR-CLIP (T->C, 20-50%). Pro: less U bias; PAR-CLIP signal is restricted to T positions. Con: lower yield (only mutated reads count).
HMM-based (PureCLIP, omniCLIP) -- Joint model of enrichment + CL signature + sequence context. State the most-likely posterior probability of CL state per nucleotide. Used across CLIP variants. Pro: integrates multiple signals; explicit input normalization. Con: F1 ~0.2 on bulk RBPs (very focal); single-nt resolution at the cost of breadth.
| Goal | Method | Tool |
|---|---|---|
| Single-nt CL map for motif registration (mCross) | HMM | PureCLIP |
| Truncation-based ENCODE-compatible iCLIP | Truncation | CTK CITS |
| PAR-CLIP T->C signal | Mutation | PARalyzer (cluster) or CTK CIMS sub T->C (single-nt) |
| HITS-CLIP deletion signal | Mutation | CTK CIMS deletion |
| Cross-CLIP-variant comparable single-nt | HMM | PureCLIP (all variants) |
| Allele-specific CLIP (BEAPR) | Truncation + ASB | PureCLIP CL sites + WASP-filtered BAM |
| Variant effect (computational from CL) | HMM | PureCLIP + downstream DeepRiPe (see clip-deep-learning) |
| Yeast / CRAC | Truncation + deletion | pyCRAC |
Per-Tool Failure Modes
PureCLIP -- HMM convergence on sparse coverage
Trigger: RBP with low IP enrichment; SMInput depth uneven; PureCLIP run on full genome without -iv interval.
Mechanism: PureCLIP HMM convergence is sensitive to coverage depth. On regions with < 5 reads/100 bp the HMM defaults to background state; if half the genome is sparse, the state distributions become bimodal and the entire run takes > 24 h or runs out of memory.
Symptom: PureCLIP "Convergence not reached" warning; or output has 0 CL sites; or runtime > 24 h on standard server.
Fix: Restrict analysis to expressed transcripts: -iv expressed_tx.bed. Or filter the BAM to high-coverage regions first. Test on chr22 first to verify parameters before genome-wide run.
PureCLIP -- Misses broad binding zones
Trigger: RBP with broad binding (PUM2 3' UTRs, SR proteins exonic enhancers); using PureCLIP exclusively.
Mechanism: PureCLIP HMM emits the CL state at very high stringency. The Boyle 2023 Skipper benchmark reports PureCLIP as the most focal caller with low recall on broad-binding RBPs.
Symptom: PureCLIP CL site count is 100x lower than CLIPper / Skipper peak count.
Fix: Use PureCLIP for single-nt CL maps AND CLIPper/Skipper for broad-zone peak calls. They are complementary, not substitutes. PureCLIP -or regions output is broader than -o sites but still focal.
CITS truncation -- Misapplied to PAR-CLIP
Trigger: CTK CITS run on PAR-CLIP data.
Mechanism: PAR-CLIP RT reads through the adduct (T->C mutation), not truncates. The 5' end of PAR-CLIP reads is at the fragment 5' end, not the CL site.
Symptom: CITS returns few sites; the sites that ARE returned do not align with the T->C mutation positions.
Fix: For PAR-CLIP use PARalyzer or CTK CIMS substitution mode (-type sub -nuc t -mut c). CITS is iCLIP/eCLIP only.
CIMS deletion -- Misapplied to iCLIP
Trigger: CTK CIMS run with -type del on iCLIP data.
Mechanism: iCLIP RT truncates, doesn't delete. The deletion rate is < 1% in iCLIP (background level), so CIMS finds nothing significant.
Symptom: CIMS output BED has < 100 sites genome-wide.
Fix: Use CTK CITS for iCLIP (truncation-based) or PureCLIP. CIMS deletion is HITS-CLIP / older PAR-CLIP only.
PARalyzer -- Parameter sensitivity
Trigger: PARalyzer default parameters on a new RBP; cluster count unexpected.
Mechanism: PARalyzer's kernel-density approach has 5+ parameters: minimum read depth, minimum mutation read count, mutation rate threshold, bandwidth, kernel type. Different combinations produce 5-100x different cluster counts.
Symptom: PARalyzer cluster count 5-100x off from literature reports for the same RBP.
Fix: Use the PARalyzer default parameters (Corcoran 2011), tuned for that RBP class. Validate on a known-binding region with a reference dataset before publication.
Aligner deletion-tolerance for HITS-CLIP
Trigger: HITS-CLIP aligned with STAR or bowtie2 in standard mode; CIMS finds few deletion sites.
Mechanism: Standard STAR/bowtie2 are aggressive about handling deletions; CIMS expects the deletions to be visible as CIGAR D operations in BAM. STAR/bowtie2 may soft-clip or fail to align deletion-bearing reads.
Symptom: Few CIGAR D operations in BAM (samtools view dedup.bam | awk '$6 ~ /D/' | wc -l); CIMS deletion site count low.
Fix: Re-align HITS-CLIP with BWA-aln (Zhang lab / CTK convention) or STAR --scoreDelOpen -1 --scoreDelBase -1 --scoreInsOpen -1 --scoreInsBase -1 to permit deletions. Or use Novoalign which is more deletion-tolerant.
PAR-CLIP T->C mismatch ceiling
Trigger: PAR-CLIP aligned with STAR --outFilterMismatchNoverReadLmax 0.04; T->C reads discarded.
Mechanism: PAR-CLIP per-T conversion rate 20-50% means a 30 nt read with 8 Ts may have 4 T->C events = 13% mismatch rate, exceeding the 4% ceiling.
Symptom: 40-70% read loss at alignment for PAR-CLIP; downstream T->C site detection finds nothing.
Fix: Raise to 0.07 for PAR-CLIP only (see clip-seq/clip-alignment).
Strand mis-assignment for truncation site
Trigger: Single-end CLIP; using read 5' end as CL site without strand consideration.
Mechanism: For plus-strand RNA, the cDNA 5' end is downstream of the CL position. For minus-strand RNA, it is upstream. Without strand-aware coordinate conversion, half of CL sites are mis-positioned by ~1 nt.
Symptom: mCross / motif analysis shows the motif positioned 1 nt off from expected.
Fix: Verify the BED output handles strand correctly. CTK CITS, PureCLIP, and most modern tools do this automatically; custom scripts must add if strand == '-': cl_position = read_end_5p + 1.
Decision Tree by Use Case
| Scenario | Tool | Parameters |
|---|---|---|
| Single-nt CL map for mCross motif registration | PureCLIP | -i dedup.bam -ibam sminput.bam -dm 8 |
| iCLIP/eCLIP CITS truncation sites | CTK CITS | tag2cluster.pl -cs5 5 -m 1 |
| HITS-CLIP deletion CIMS | CTK CIMS | CIMS.pl -big -c -p 0.01 |
| PAR-CLIP T->C clusters | PARalyzer | Per-RBP params tuned from Corcoran 2011 defaults |
| PAR-CLIP T->C single-nt | CTK CIMS substitution | CIMS.pl -type sub -nuc t -mut c -p 0.001 |
| Yeast CRAC | pyCRAC | pyCRAC.py with HTP-tagged protein |
| Variant effect at CL sites | PureCLIP + DeepRiPe | See clip-seq/clip-deep-learning |
| Allele-specific binding | WASP-filtered BAM + PureCLIP | See clip-seq/clip-alignment for WASP |
| Cross-CLIP comparison | PureCLIP (consistent across variants) | Same parameters |
| m6A miCLIP2 sites | miCLIP2-specific (m6Aboost) | See clip-seq/m6a-clip |
| STAMP edit sites | Not crosslink-based | See clip-seq/stamp-antibody-free |
Reconciliation: When Detection Methods Disagree
| Pattern | Likely cause | Action |
|---|---|---|
| PureCLIP << CTK CITS site count | PureCLIP HMM very focal; CITS empirical broader | Both correct; report which threshold |
| PARalyzer clusters << CIMS T->C sites for PAR-CLIP | PARalyzer is cluster-level; CIMS is single-nt | Aggregate CIMS to clusters for comparison |
| PureCLIP CL sites at unexpected positions | Strand mis-assignment OR aligner soft-clip | Check BED strand column; verify --alignEndsType EndToEnd |
| HITS-CLIP CIMS empty | Aligner not deletion-tolerant | Re-align with BWA-aln or STAR with adjusted scoring |
| PAR-CLIP CIMS << expected | Reads lost at mismatch ceiling | Raise STAR --outFilterMismatchNoverReadLmax to 0.07 |
| eCLIP CITS positions shifted by 1 nt | Strand handling off-by-one | Verify R2 5' end position handling |
| Multiple CITS sites within 5 nt | RT stops near each other; same CL event | Cluster within 10 nt window post-detection |
| Motif registers 5 nt off in mCross | CL positions wrong by RT-stop offset | Confirm tool reports "CL - 1" position consistently |
Operational rule: For motif registration and ASB, run PureCLIP with SMInput. For ENCODE-comparable truncation-based output, also run CTK CITS. Cross-validate by checking that mCross motif PWM is the same when fed PureCLIP sites vs CTK CITS sites. If they diverge by > 2 nt in motif position, suspect strand or off-by-one issue.
Workflow: PureCLIP -> mCross -> ASB
# Step 1: PureCLIP single-nt sites
pureclip \
-i sample.dedup.bam -bai sample.dedup.bam.bai \
-g genome.fa \
-ibam sminput.dedup.bam -ibai sminput.dedup.bam.bai \
-o sample.crosslinks.bed \
-or sample.regions.bed \
-nt 8 -dm 8 -iv expressed_tx.bed
# Step 2: mCross motif registration
mCross -i sample.crosslinks.bed -g genome.fa -k 7 -n 5 -o mcross_out
# Step 3: Intersect with heterozygous SNPs for allele-specific binding
bedtools intersect -wa -wb -s -a sample.crosslinks.bed -b het_snps.vcf > cl_at_hets.bed
# Step 4: Test allele bias with BEAPR or ASPRIN
# (see allele-specific CLIP literature; not in this skill)
Common Errors
| Error / symptom | Cause | Solution |
|---|---|---|
| PureCLIP "Convergence not reached" | HMM didn't converge on sparse coverage | Restrict to expressed transcripts with -iv expressed.bed |
| PureCLIP > 24h runtime | Full genome on large library | Test on chr22 first; add -iv filter |
| CTK CIMS empty for HITS-CLIP | Aligner not deletion-tolerant | Re-align with BWA-aln |
| CITS truncation sites not single-nt | CIGAR S operations from soft-clip | Verify --alignEndsType EndToEnd upstream |
| PAR-CLIP CIMS empty | Reads lost at mismatch ceiling | Raise STAR mismatch tolerance |
| Off-by-one motif position | Strand handling differs | Verify tool documents whether output is CL or CL-1 |
| Single-nt motif lost in HOMER on PureCLIP sites | Site BED too narrow; need flanking | Extend bedtools slop -b 15 before motif analysis |
| mCross "no crosslinks found" | Passed peak BED instead of CL BED | Use single-nt site output |
| PureCLIP output looks like uniform distribution | R2 5' end trimmed in preprocessing | Re-preprocess; -g and --trim_front2 banned for CLIP |
| Strand-specific motif inverted | BED column 6 wrong | Verify strand encoding; PureCLIP preserves correctly |
References
- Konig J et al 2010 Nat Struct Mol Biol 17:909 (iCLIP truncation principle)
- Hafner M et al 2010 Cell 141:129 (PAR-CLIP T->C signature)
- Granneman S et al 2009 PNAS 106:9613 (CRAC, single-nt CL detection)
- Corcoran DL et al 2011 Genome Biol 12:R79 (PARalyzer)
- Comoglio F et al 2015 BMC Bioinformatics 16:32 (wavClusteR)
- Shah A et al 2017 Bioinformatics 33:566 (CTK / CIMS / CITS)
- Krakau S et al 2017 Genome Biol 18:240 (PureCLIP HMM)
- Boyle EA et al 2023 Cell Genomics 3:100317 (Skipper; PureCLIP focality/F1 benchmark)
- Sugimoto Y et al 2012 Genome Biol 13:R67 (CLIP/iCLIP analysis; uridine crosslink preference)
- Feng H et al 2019 Mol Cell 74:1189 (mCross requires CL sites)
- Yang EW et al 2019 Nat Commun 10:1338 (BEAPR allele-specific protein-RNA binding)
- Van Nostrand EL et al 2020 Nature 583:711 (ENCODE eCLIP single-nt analyses)
Related Skills
- clip-seq/clip-preprocessing - 5' base preservation critical for truncation detection
- clip-seq/clip-alignment - End-to-end alignment for crosslink-preserving BAM
- clip-seq/clip-peak-calling - Peak vs CL site is a complementary distinction
- clip-seq/clip-motif-analysis - mCross consumes CL sites
- clip-seq/clip-deep-learning - RBPNet trained on CL count distributions
- clip-seq/m6a-clip - miCLIP2 has its own CL detection
- clip-seq/stamp-antibody-free - STAMP uses C->U editing, not crosslink
- alignment-files/sam-bam-basics - CIGAR string semantics for D operations