rnamotifs-mars couples RNAmotifs with eCLIP RBP-binding data to score how well a discovered motif set matches an RBP's binding — the MRM–RBP association score. It extends the RNAMaRs framework by running RNAmotifs motif discovery directly inside the scoring loop.
| Phase | Name | What it does |
|---|---|---|
| 1 | Multi-parameter sweep | Runs RNAmotifs across hw/ew combinations (paper notation n = 2·hw / e) to find enriched MRMs (multivalent RNA motifs; tetramer in code) under different clustering stringencies. |
| 2 | Signal Recovery Rate — SRR (SCORE1 in code) | eCLIP-downsampling robustness of the RBP's binding profile. |
| 3 | Cosine Similarity — CS (SCORE2 in code) | Cosine similarity between the motif-enrichment profile and the eCLIP binding profile. |
The Association Score (AS) = CS × SRR (SCORE2 × SCORE1 in code), aggregated into per-RBP heatmaps. The SRR weight is optional: pass --score-mode cs-only to score on the cosine similarity alone (AS = CS), or keep the default --score-mode full for AS = CS × SRR.
--mode discovery) — sweeps hw/ew per RBP (grid or Bayesian optimisation, --optim grid|bayes) and picks the parameters that best identify the true RBP, writing a crash-safe, resumable manifest.--mode application) — scores a new splicing dataset against a trained reference panel../rnamotifs-mars dummy.txt --mode discovery \
--cell-line HepG2 --mars-exons-dir data/mars_exons/HepG2 \
--eclip-dir data/eCLIP_processed/HepG2/hg19 \
--mars-dir data/mars_reference -n discovery_HepG2 -g hg19 \
-c 8 -b 1000 --p-empirical 0.01Intermediate results: results/MaRs_discovery/<cell>_<genome>/<rbp>/ with sweep/ (RNAmotifs runs) and scores/ (association scores + diagnostics/).
Score a new splicing dataset against the trained reference panel. The bundled reference (per-cell parameter tables, SRR references, and the panel-RBP eCLIP peaks) lives under data/reference/. Download it and unzip into your working directory:
./rnamotifs-mars my_events.txt \
--cell-line HepG2 -g hg19 \
--eclip-dir data/reference/eclip \
--mars-dir data/reference/HepG2 \
-n my_analysis -c 8--mode application is the default, so it can be omitted. --eclip-dir points at the parent eclip/ (auto-resolved to <eclip>/<cell>/<genome>/); --mars-dir points at the per-cell bundle (data/reference/HepG2 or data/reference/K562). For each panel RBP the tool reports SCORE1 (SRR), SCORE2 (CS), and AS = CS × SRR. See data/reference/README.md for the panel and the input-file format.
my_events.txt is a splicing-change file in RNAmotifs ;-format (see Input format). rnamotifs-mars does not call rMATS or convert its output itself — it only selects the event type with --event-type {SE,RI}. You build the input in two upstream steps.
1. Run rMATS on your knockdown-vs-control BAMs to get differential splicing (data/run_rmats_geo.sh is a reference wrapper). The parameters that matter:
| rMATS parameter | Meaning |
|---|---|
--b1 / --b2 | Comma-separated BAM lists: b1 = knockdown, b2 = control (ΔΨ = IncLevel1 − IncLevel2 = KD − Ctrl). |
--gtf | Annotation (e.g. GENCODE). Must match the genome you pass to rnamotifs-mars (-g). |
-t single|paired | Library layout. |
--readLength | Read length per mate; pair with --variable-read-length if trimmed reads vary. |
--novelSS | Include novel splice sites (optional). |
--nthread / --tstat | Threads for counting / statistics. |
The relevant output is SE.MATS.JC.txt (skipped exons; use RI.MATS.JC.txt for intron retention). rMATS reports per event: IncLevelDifference (ΔΨ) and FDR.
2. Convert rMATS → RNAmotifs input with the rnamotifs (cis) tool's --from-rmats, which applies the ΔΨ/FDR thresholds, samples controls, writes the dIRank labels, and saves a reusable rnamotifs_input.txt:
./rnamotifs SE.MATS.JC.txt --from-rmats \
--rmats-incl 0.1 --rmats-fdr 0.05 \
--name MYRBP --genome hg19 --cores 8
# → writes results/<name>/rnamotifs_input.txt (the ;-format file)| Conversion parameter | Default | Meaning |
|---|---|---|
--from-rmats | off | Treat input_file as an rMATS file (event chosen by --event-type). |
--rmats-incl | 0.1 | Min |IncLevelDifference| (ΔΨ) for a regulated exon → dIRank = ±1 (sign of ΔΨ). |
--rmats-fdr | 0.05 | Max FDR for regulated exons. |
--rmats-constit | 0.01 | Max |ΔΨ| for an exon to count as a constitutive control (dIRank = 0). |
--rmats-max-constit | 5000 | Cap on control exons (random sample if exceeded). |
Then feed the resulting rnamotifs_input.txt to rnamotifs-mars as my_events.txt. Set --event-type RI on both the conversion and the MaRs run for intron retention.
| Flag | Default | Meaning |
|---|---|---|
--mode | application | discovery (train params) or application (score new data). |
--cell-line | — | HepG2 or K562 (eCLIP panel). |
--event-type | SE | Splicing event type: SE (skipped exon) or RI (intron retention). Must match how the input was built from rMATS. |
--eclip-dir | — | Path to eCLIP peak files. |
--mars-dir | — | RNAmars data dir (Tables/, Rdata/). |
--mars-exons-dir | — | Per-RBP RNAmotifs input files (discovery). |
--param-grid-n | 10 30 50 70 | Clustering-window grid n (paper notation, n = 2·hw; each value even). Back-compat alias --param-grid-hw (= n/2) still accepted. |
--param-grid-e | 30 50 100 200 300 | Enrichment-window grid e (alias --param-grid-ew). |
--optim | grid | grid or bayes (Bayesian optimisation). |
--make-heatmaps | off | After discovery, run generate_heatmap.R for every trained RBP → the Figure-4A final heatmaps (AS heatmap + per-RBP RNA splicing maps), using the grid optima. Reuses existing sweeps (no re-search); writes …/<cell>_<genome>/heatmaps/<cell>_<RBP>_<enh|sil>.pdf. Resumable. |
--heatmap-top-mrms | 0 (all) | Crop the Phase-3 heatmaps to the top-N enriched MRMs (columns). 5 reproduces the Figure-4A top-5 crop. |
--heatmap-top-rbps | 0 (all) | Crop the Phase-3 heatmaps to the top-N RBPs (rows). |
--bo-n-init / --bo-n-iter | 8 / 30 | Bayesian-opt initial points / iterations. |
--bo-seed | 42 | Bayesian-opt random seed. |
--in-intron | 300 | One or more intron-extent values (grid-searchable). |
All shared RNAmotifs parameters (-b, --p-fisher, --p-empirical, --in-exon, -k, …) work as documented in Parameters. Discovery mode is resumable: re-running the same command skips completed RBPs/combinations via the discovery_manifest.json.
See the project README's RNAmotifs-MaRs section for the full end-to-end workflow.