seismic filterscan

Purpose

seismic filterscan searches a full-length RNA for domains: regions that appear to fold independently, revealed by positions whose mutations are correlated with each other (correlated pairs). It slides overlapping tiles along the RNA, runs the filter step on each tile, finds pairs of positions that mutate together more often than expected by chance, and groups those pairs into domains. It then runs the filter step once more on each detected domain, so that the domains are ready to be clustered. Use it when you want an unbiased, data-driven way to discover structural domains along a long RNA without defining regions by hand. Follow it with seismic clusterscan to cluster the domains it detects.

Inputs

IDmut output directory or report file: One or more IDmut output directories or idmut-report.json files. See Specify Input Files for ways to select multiple inputs at once.

Outputs

All outputs go into {out}/{sample}/filterscan/{ref}/{reg}/.

filterscan-report.json: Summary of settings and results, including the coordinates of every detected domain. See Filterscan Report.
pairs.csv: The correlated pairs of positions found in the RNA.
domains.csv: The coordinates (5’ and 3’ ends) of the detected domains.
pairs_and_domains.html: An interactive plot of the correlated pairs and the domains built from them.
confusion-matrix.csv: The per-pair counts and statistics used to decide which pairs are correlated.

The filter step is also run on each detected domain, producing the same output as seismic filter for every domain.

Quick example

Scan a full-length RNA for domains:

seismic filterscan out/sample-1/idmut/long-rna

Options

Tiling

--tile-length N (-L): Length of each tile in nucleotides (default 0 = 2× the median read length).
--tile-min-overlap F (-O): Minimum fractional overlap between adjacent tiles (default 0.5).
--erase-tiles/--keep-tiles: Delete the intermediate filter files from the tiling step (default: erase).

Correlated-pair detection

--pair-fdr F: False discovery rate for calling a pair of positions correlated (default 0.05).
--endpoint-window N: Aggregate pair-endpoint counts over this many adjacent positions when testing whether a position is a hub of correlated pairs (default 2). Larger values help when a helix does not always start or end at exactly the same position.
--pair-distance-percentile F: Drop a correlated pair if its nearest surviving neighbor is farther than this percentile of all nearest-neighbor distances (default 95.0). Isolated pairs are treated as noise.
--min-nearby-pairs N: Minimum number of other surviving pairs that must lie within the distance threshold for a pair to be kept (default 2). Values above 1 filter out small coincidental clusters of noise pairs.

Domain length filters

--min-pairs N: Keep only domains with at least this many correlated pairs (default 2).
--min-cluster-length N: Keep only domains with at least this many positions (default 20).
--max-cluster-length N: Keep only domains with no more than this many positions (default 1200).

Gap handling

--gap-mode {omit|insert|expand}: What to do with the gaps between domains (default omit): omit leaves the gaps out, insert turns each gap into its own domain, and expand grows the neighboring domains to fill the gaps.

Filter options

All seismic filter options are accepted and applied to each tile and domain.

Branches

--branch X (-b): Create a new branch: output results in {out}/{sample}/filterscan_{branch}. See Branches.

Performance

--num-cpus N — multiprocessing; see Parallelize Tasks. --force — overwrite existing outputs.

The auto-generated Command Line Reference lists every option with its current default.