Version Compatibility

Reference examples tested with: HOMER 4.11+, MEME Suite 5.5+ (STREME, MEME-ChIP, FIMO), bedtools 2.31+, kpLogo 1.1+, mCross v1+, PEKA v1+, RBPamp 0.9+, ggseqlogo 0.1+, biopython 1.83+.

Before using code patterns, verify installed versions match. If versions differ:

• CLI: <tool> --version then <tool> --help to confirm flags
• Python: pip show <package> then help(module.function) to check signatures

If code throws unexpected errors, introspect the installed tool and adapt the example to match the actual API rather than retrying.

CLIP-seq Motif Analysis

"Find enriched RNA motifs at my RBP binding sites" -> Discover the in vivo sequence preference of an RNA-binding protein from CLIP-seq peaks or single-nucleotide crosslink sites. The fundamental confound is the uracil bias of UV254 crosslinking: U is the most-crosslinked base, so naive motif logos centered on CL positions are U-enriched even for non-U-binding RBPs. Modern tools (mCross, PEKA) register motifs relative to the CL position and correct for this bias; legacy tools (HOMER, MEME) need careful background selection.

• CLI (de novo, peak-based, HOMER RNA mode): findMotifs.pl peaks.fa fasta motif_out -rna -len 5,6,7,8 -p 4
• CLI (de novo, peak-based, MEME-ChIP / STREME): streme --rna --oc streme_out -p peaks.fa -n background.fa --minw 5 --maxw 10
• CLI (positional, single-nt CL-registered, mCross): mCross -i crosslinks.bed -g genome.fa -k 7 -o mcross_out (jointly models motif + CL position)
• CLI (positional k-mer, no input control needed, PEKA): peka --peakfilename peaks.bed --crosslinksfilename crosslinks.bed --genomefilename genome.fa --regionsfilename regions.bed --kmerlength 5 --percentile 30 --outpath pekaout (the short flags -i/-x/-g/-r/-k/-p shown in earlier docs are not all stable; use the long forms or check peka --help)
• CLI (affinity-weighted, RBPamp): rbpamp run -i peaks.fa -k 7 -o rbpamp_out (joint affinity + motif model)
• CLI (positional logo, kpLogo): kpLogo crosslinkswithkmerscores.txt -o kplogoout (position-specific significance)

ENCODE eCLIP motif convention: extract sequences from peaks (CLIPper + SMInput stringent), use shuffled or expression-matched background, run HOMER -rna -len 5,6,7,8. The Yeo lab eCLIP papers typically report the top 1-3 HOMER hits per RBP and validate with mCross for CL-registered position. For ASB and variant-effect work, mCross is mandatory.

Algorithmic Taxonomy

Methodology evolves; verify motif comparison databases (CISBP-RNA, ATtRACT, oRNAment, mCrossBase, RBPDB) for known motif validation. RBNS in vitro Kd values (Lambert 2014; Dominguez 2018 for 78 RBPs) are the most reliable orthogonal reference for in vivo CLIP motifs.

Critical Choice: Peak-Based vs Crosslink-Site-Based Motif Discovery

Peak-based (HOMER, MEME/STREME, RBPamp): Extract sequences from peak BED, find enriched k-mers / PWMs. Produces classical motif logos. Fast and intuitive. Captures broad binding zones.

Crosslink-site-based (mCross, PEKA, kpLogo): Use single-nucleotide CL positions; analyze sequence in a window around each CL position. Produces motif logos REGISTERED to the CL site. Required for understanding the structural relationship between motif and crosslink.

The fundamental difference: peak-based logos show "what sequence is enriched near binding"; CL-registered logos show "what sequence the RBP contacts at the crosslink position." For most RBPs they agree on the core motif but diverge on flanking context.

Uracil Crosslinking Bias

UV254 crosslinking is U-biased: single-nt CL events are strongly enriched at U residues (Konig 2010; Sugimoto 2012). Consequence: motif logos centered on raw CL positions are U-enriched at the center even for non-U-binding RBPs (e.g., PUM2 binds UGUANAUA but peak-center is shifted; HNRNPK binds C-rich tracts but centers can show spurious U).

Mitigations:

• Use peak boundaries, not single-nt CL, for HOMER/MEME (peak-level averaging dilutes the U bias).
• Use mCross or PEKA, which explicitly model the CL position offset from the motif center.
• Shuffle background should preserve mononucleotide composition (HOMER default does; MEME with --markov-order 1 does).
• For PAR-CLIP, the bias is at U residues but T->C marks the EXACT CL position; mCross / PEKA register more cleanly than for iCLIP/eCLIP.

For naive HOMER/MEME output, examine the central column of the PWM: if it is U-skewed, suspect CL bias rather than true U preference. Cross-check against published RBNS Kd if available.

Per-Tool Failure Modes

HOMER -- Background mismatch inflates GC-biased motifs

Trigger: HOMER auto-generates a shuffled background that preserves only nucleotide frequency, not GC distribution per region; CLIP peaks come disproportionately from 3' UTRs which are AU-rich.

Mechanism: AU-rich foreground vs GC-shuffled background produces "AU-rich motif" as the top hit for any 3' UTR-binding RBP, regardless of biology.

Symptom: Top HOMER motif looks like the 3' UTR mean composition (AU-rich, no clear specificity); known motif scan (-known) finds the RBP's canonical motif at lower rank than the spurious "AU" motif.

Fix: Provide a GC-matched background: extract sequences from random 3' UTR regions of expressed transcripts matched by length distribution. Use -bg matchedbg.fa flag. Or use STREME with -n matchedbg.fa.

MEME -- Slow on large peak sets

Trigger: MEME run on > 1000 peak sequences.

Mechanism: MEME is O(N^2) in sequence count; classical OOPS/ZOOPS/ANR models do not scale.

Symptom: Runtime > 12h; out-of-memory on large machines.

Fix: Use STREME (MEME Suite >= 5.0); it is the modern fast successor (sub-quadratic). Or restrict to top-1000 peaks by score.

mCross -- Requires single-nt CL sites

Trigger: mCross run on a peak BED instead of crosslink BED.

Mechanism: mCross's model is motifPWM x CLpositionoffsetPMF. Without single-nt CL positions there is no offset axis; the model degenerates.

Symptom: mCross output looks identical to a peak-centered logo; the diagnostic CL-offset histogram is flat.

Fix: Provide CL sites from PureCLIP, CTK CITS, or PARalyzer. The Yeo lab and Zhang lab use the convention of PureCLIP CL sites as mCross input.

PEKA -- Background from same dataset

Trigger: Concerned that PEKA's "low-count crosslinks within same dataset" background is biased.

Mechanism: PEKA does NOT need external input. It uses low-count crosslinks (below a quantile threshold) as the background and high-count crosslinks (above) as the foreground. This is by design (Kuret 2022) and cross-validated against mCross.

Symptom: False positive concern; user wants to verify.

Fix: Run BOTH PEKA and mCross; cross-validate. The PEKA paper reports high concordance with mCross for ENCODE RBPs; treat them as orthogonal confirmation.

RBPamp -- Slow convergence

Trigger: Large peak set (> 5000); RBPamp jointly optimizes affinity + motif iteratively.

Mechanism: Joint optimization is slow; some RBPs have multimodal binding (multiple motifs) that confuse single-PWM RBPamp.

Symptom: Runtime > 24h; output PWM disagrees with HOMER top motif.

Fix: Down-sample to top-2000 peaks; or run HOMER for initial PWM and use it as RBPamp seed.

RBNS comparison -- in vitro vs in vivo divergence

Trigger: Comparing CLIP-derived motif to RBNS Kd-ranked motif (Dominguez 2018) and finding divergence (e.g., CLIP top motif rank 3 in RBNS; RBNS top motif weakly enriched in CLIP).

Mechanism: In vivo binding is shaped by structure accessibility (RNA secondary structure), cooperativity, and competing factors. RBNS measures intrinsic affinity in vitro. They diverge for:

• Structurally regulated RBPs (PUM2, RBFOX2 favor accessible loops)
• Cooperative binders (FUS, TDP-43, SR proteins)
• Co-factor-dependent (SRSF1 paralogs)

Symptom: CLIP motif logo plausible but rank-3 in RBNS; or RBNS top motif missing from CLIP peaks.

Fix: Accept the divergence as informative. Cite both. Use SHAPE-eCLIP or icSHAPE-MaP to test structural-accessibility hypothesis. For variant-effect studies, prefer RBNS-derived PWM (RBPamp Kd) over CLIP motif for absolute affinity prediction.

Known motif scan -- FIMO threshold too lenient

Trigger: Used FIMO with default -thresh 1e-4 and got matches everywhere.

Mechanism: Default threshold is too lenient for in vivo binding; CLIP background sequences contain many low-affinity matches.

Symptom: FIMO match rate > 50% of peaks AND > 20% of random background; no enrichment signal.

Fix: Use -thresh 1e-5 or -thresh 1e-6; or use CentriMo for local enrichment around peak center (testing positional enrichment, not threshold).

Decision Tree by Scenario

Reconciliation: When Motif Tools Disagree

Operational rule for high-confidence motif reporting: Report (a) HOMER top de novo motif with GC-matched background, (b) mCross PWM with CL-position offset histogram, (c) PEKA k-mer enrichment for orthogonal confirmation, (d) FIMO scan against published RBP PWM (CISBP-RNA / ATtRACT) for known-motif validation, (e) RBNS Kd ranking from Dominguez 2018 if available. Three independent methods agreeing on the core motif is the bar.

Workflow: De Novo + Known + CL-Registered

Goal: Produce a publication-grade motif report combining peak-based de novo discovery, CL-position-registered motif (mCross), and known-motif validation.

Approach: Extract sequences with strand preservation, build a GC-matched 3' UTR background, run HOMER + STREME for de novo, mCross for CL-registered, FIMO scan against CISBP-RNA, and report all three views with information-content QC.

# Step 1: Extract peak sequences (use stringent peak set: log2 FC >= 3, -log10 p >= 3)
bedtools getfasta -fi genome.fa -bed peaks.stringent.bed -s -fo peaks.fa

# Step 2: GC-matched background (random regions from expressed transcripts)
# expressed.bed = transcripts with TPM >= 1 in the same cell type
shuffleBed -i peaks.stringent.bed -g chrom.sizes -incl expressed.bed -seed 42 > shuffled.bed
bedtools getfasta -fi genome.fa -bed shuffled.bed -s -fo background.fa

# Step 3: HOMER de novo + known
findMotifs.pl peaks.fa fasta homer_out \
    -rna -len 5,6,7,8 -p 8 \
    -fasta background.fa

# Step 4: STREME for cross-validation
streme --rna --oc streme_out -p peaks.fa -n background.fa --minw 5 --maxw 10

# Step 5: mCross requires single-nt CL sites (PureCLIP output)
# crosslinks.bed = PureCLIP -o sites.bed (single-nt CL positions, see clip-seq/crosslink-site-detection)
mCross \
    -i crosslinks.bed -g genome.fa -k 7 -n 5 -o mcross_out

# Step 6: PEKA orthogonal positional k-mer
peka --peak_file_name peaks.stringent.bed --crosslinks_file_name crosslinks.bed --genome_file_name genome.fa --regions_file_name regions.bed --kmer_length 5 --percentile 30 --outpath peka_out

# Step 7: Compare to RBNS in vitro Kd (Dominguez 2018 supplementary)
# Manual cross-reference to RBNS Kd-ranked top-5 motifs for the target RBP

Quality Checks

import numpy as np
import pandas as pd
from Bio import motifs

def parse_homer_motif(motif_file):
    '''Parse HOMER motif PWM and return information content'''
    pwm = []
    with open(motif_file) as f:
        for line in f:
            if line.startswith('>'):
                continue
            pwm.append([float(x) for x in line.strip().split()])
    pwm = np.array(pwm)
    # Information content per position (bits)
    epsilon = 1e-10
    ic = np.sum(pwm * np.log2(pwm / 0.25 + epsilon), axis=1)
    return {
        'length': pwm.shape[0],
        'mean_IC_per_position': np.mean(ic),
        'max_IC': np.max(ic),
        'min_IC': np.min(ic),
        'is_low_complexity': np.mean(ic) < 0.5
    }

# A high-quality CLIP motif has mean IC per position > 1.0 bit
# Mean IC < 0.5 suggests no real motif - check for background mismatch

Common Errors

References

• Heinz S et al 2010 Mol Cell 38:576 (HOMER motif discovery)
• Bailey TL et al 2015 Nucleic Acids Res 43:W39 (MEME Suite)
• Bailey TL 2021 Bioinformatics 37:2834 (STREME, MEME's fast successor)
• Wu X & Bartel DP 2017 Nucleic Acids Res 45:W534 (kpLogo positional logo)
• Feng H et al 2019 Mol Cell 74:1189 (mCross, jointly modeling motif + CL position)
• Kuret K, Amalietti AG, Jones DM, Capitanchik C, Ule J 2022 Genome Biol 23:191 (PEKA, positional k-mer no input)
• Jens M et al 2022 bioRxiv 2022.11.08.515616 (RBPamp, affinity-weighted motif; preprint)
• Lambert N et al 2014 Mol Cell 54:887 (RNA Bind-n-Seq)
• Dominguez D et al 2018 Mol Cell 70:854 (78-RBP RBNS atlas)
• Sugimoto Y et al 2012 Genome Biol 13:R67 (CLIP/iCLIP analysis; uridine crosslink preference)
• Van Nostrand EL et al 2020 Nature 583:711 (ENCODE 150 RBP eCLIP + motifs)
• Konig J et al 2010 Nat Struct Mol Biol 17:909 (iCLIP, U bias origin)

Related Skills

• clip-seq/clip-peak-calling - Upstream peak calls feed motif discovery
• clip-seq/crosslink-site-detection - Single-nt CL sites required for mCross / PEKA
• clip-seq/binding-site-annotation - Region-level context for motifs
• clip-seq/clip-deep-learning - Sequence-to-binding deep models (RBPNet, DeepRiPe)
• clip-seq/ago-clip-mirna-targets - miRNA seed motifs from CLEAR-CLIP chimeras
• chip-seq/motif-analysis - DNA-protein motif analogue
• pathway-analysis/go-enrichment - Functional context of motif-bearing genes