FAQs

This page collects answers to common questions that come up while installing, running, and interpreting SEISMIC-RNA.

Installation and external tools

Why does seismic fold fail with a DATAPATH error?

The RNAstructure backend needs the DATAPATH environment variable to point at its data_tables/ directory (parameter files, free-energy tables, etc.). SEISMIC-RNA can usually guess the correct value of DATAPATH, without need for setting DATAPATH manually, if RNAstructure was installed using Conda or Mamba or was downloaded from the RNAstructure website. Run seismic datapath to see what SEISMIC-RNA guesses. If it does not guess DATAPATH correctly, then set it manually before running seismic fold or seismic wf --fold:

export DATAPATH=/whatever/your/path/is/to/RNAstructure/data_tables

Add the line to your shell rc file (~/.bashrc, ~/.zshrc) to make it persistent. See Install for the full RNAstructure setup, and seismic fold for backend selection.

Why does seismic draw print “Skip draw if RNARTISTCORE is not installed”?

seismic draw shells out to RNArtistCore to render structures as SVG. If the RNARTISTCORE environment variable does not point to a working install, the draw step is skipped with a warning rather than failing the whole pipeline. Install RNArtistCore and set:

export RNARTISTCORE=/path/to/rnartistcore

See Install and seismic draw.

Which optional dependencies do I actually need?

  • Bowtie 2 and samtools — required for seismic align.

  • samtools — required for seismic idmut.

  • RNAstructure (with DATAPATH) — required for the default --fold-backend rnastructure and for --pseudoknots (ShapeKnots).

  • ViennaRNA — required for --fold-backend viennarna.

  • RNArtistCore (with RNARTISTCORE) — required for seismic draw.

If a backend / tool is not installed, the corresponding step fails with a clear message — earlier steps still work.

Renamed commands and options (v0.25.0)

In v0.25.0 several commands and options were renamed for clarity. A summary is in CHANGELOG.md; seismic migrate migrates older output directories automatically.

Commands

Old name

New name

seismic relate

seismic idmut

seismic mask

seismic filter
Options

Old option

New option

--fold-table

--fold-table-region

--fold-full

--fold-full-region

--quantile

--fold-quantile (fold) + --graph-quantile (graph)

--mismatch-tolerence

--mismatch-tolerance

--index-tolerence

--index-tolerance

--mask-* (reads)

--drop-*

--mask-gu

--mask-a/c/g/u (per-base)

--pooled (seismic pool)

positional pool-name argument

--joined (seismic join)

positional region-name argument

Run seismic migrate out -o out_new to migrate older output directory trees to the v0.25.0 layout. See seismic migrate.

Probes and probe-specific defaults

What does --probe do?

--probe {DMS|SHAPE|ETC|none} declares which chemical probe was used, and switches on probe-appropriate defaults across the pipeline:

  • Filter masks the bases that are unreactive to that probe by default (DMS: G + U; ETC: A + C; SHAPE / none: no mask).

  • Filter picks --mut-collisions (drop for DMS; merge for SHAPE/ETC).

  • Fold picks --fold-backend (RNAstructure for DMS, ViennaRNA for SHAPE/ETC/none) and --fold-energy-method (cordero for DMS, eddy for SHAPE/ETC/none).

  • Sim turns on --min-mut-gap-weights for DMS and --injected-mut-probs for SHAPE/ETC by default.

Override any of these explicitly to use a non-default combination.

When should I set --probe none?

For untreated control samples — that is, sequencing reads from RNA that was not exposed to a chemical probe. This disables base-specific masking and selects the appropriate folding defaults.

Performance and parallelism

How do I make seismic wf run faster?

  • Parallelize. Use --num-cpus N (where N is the number of CPUs to use). See Parallelize Tasks.

  • Tune ``–batch-size``. Smaller batches use less memory per worker but produce more files. See seismic idmut.

  • Disable indel ambiguity. If your data has few indels, pass --no-ambindel to skip the ambiguous-indel enumeration. See seismic idmut.

How do I limit memory usage?

Reduce --batch-size and/or --num-cpus. Monitor memory with top (Linux/macOS) or Activity Monitor (macOS) during a run; if memory pressure is high, halve --batch-size and try again.

Output and interpretation

Where do my output files go?

Under --out-dir (default ./out), organized as {out}/{sample}/{step}/{ref}/.... Each step also writes a JSON report file (e.g. idmut-report.json, filter-report.json) that records the settings used and summarizes the results. See Report Formats.

Why is my output empty / why were all my reads filtered out?

The Filter step drops reads that fail any of its criteria. Open the filter report (filter-report.json) to see how many reads each criterion dropped. Common causes:

  • --min-fcov-read set too high (drops reads that do not cover the full region).

  • --probe set incorrectly (wrong default base masking).

  • --mut-collisions drop dropping reads with closely-spaced mutations.

  • The IDmut step itself produced empty batches because the alignment maps had too few reads (see seismic idmut).

I ran seismic wf but got no structures / no clustered output / no JSON.

The Fold, Cluster, Draw, and Export steps are off by default in seismic wf. Turn them on explicitly:

  • Cluster: -k N (or --max-clusters N)

  • Fold: --fold

  • Draw: --draw

  • Export: --export

See seismic wf.

How do I re-run only one step?

Run the step’s command directly on the upstream outputs, e.g.

seismic filter out/sampleA/idmut/refX/idmut-report.json --probe DMS

seismic wf will also skip any step whose outputs already exist; pass --force to overwrite.

Troubleshooting and support

How do I see what SEISMIC-RNA is actually doing?

Use -v / -vv / -vvv / -vvvv to increase log verbosity, and -q / -qq / -qqq / -qqqq to decrease it. All messages are also written to a log file regardless of verbosity. See Log Messages.

I found a bug. Where do I report it?

See Bugs and Requests.

I have a question that’s not answered here.

Open a GitHub issue (see Bugs and Requests) or check the Tutorials for worked examples.