seismic filter

Note

filter was named mask in versions before v0.25.0. See the project CHANGELOG.md for the full rename list.

Purpose

seismic filter prepares IDmut output for downstream analysis. It decides which base changes (substitutions, deletions, insertions) count as mutations, masks positions unsuitable for your chemical probe (e.g. G and U for DMS), and drops reads that fail quality thresholds such as too few covered positions or too high a mutation rate. The result is a cleaned dataset ready for quantification and structure prediction.

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}/filter/{ref}/{reg}/.

filter-batch-{num}.brickle: One batch of filtered reads as a FilterBatchIO object. See Brickle: Compressed Python Objects.
filter-report.json: Summary of settings and results (reads/positions kept and dropped per filter). See Filter Report.

Quick example

Filter all IDmut output for sample-1 against ref-1 with DMS defaults:

seismic filter out/sample-1/idmut/ref-1

Options

Probe preset

--probe {DMS|SHAPE|ETC|none}: Sets base masking and collision defaults. DMS (default): masks G and T/U, uses --mut-collisions drop. ETC: masks A and C, uses --mut-collisions merge. SHAPE: keeps all bases, uses --mut-collisions merge. none: keeps all bases and sets --min-mut-gap 0 (so no collision handling is applied). Individual options override the preset.

Regions

Select a sub-range of each reference with --region-coords or --region-primers. See Define Regions.

Mutation definitions

--count-del/--no-del / --count-ins/--no-ins: Count deletions/insertions as mutations (on by default).
--no-mut XY: Ignore a specific mutation type (e.g. ag = A→G substitution).
--only-mut XY: Count only this type as a mutation (overrides all other mutation settings).

Mask out positions

--mask-a / --mask-c / --mask-g / --mask-u: Mask/keep positions by base identity. G and T/U masked for DMS by default; A and C for ETC; all kept otherwise.
--mask-polya N: Mask positions inside poly(A) runs of length ≥ N (default 5; 0 to disable).
--mask-pos REF POS / --mask-pos-file FILE: Mask specific positions or positions from a List of Positions file.

Filter reads

--min-ncov-read N: Minimum positions a read must cover (default 1).
--min-fcov-read F: Minimum fraction of the region a read must cover (default 0.0).
--min-finfo-read F: Minimum fraction of informative positions per read (default 0.95).
--max-fmut-read F: Maximum fraction of mutated positions per read (default 1.0; disabled).
--drop-discontig/--keep-discontig: Drop paired-end reads with non-contiguous mates (default: drop).
--min-mut-gap N: Minimum gap between two mutations in a read; pairs closer than N bases are handled by --mut-collisions. Probe-specific defaults: 4 for DMS, 2 for SHAPE/ETC, 0 for none.
--mut-collisions {auto|drop|merge}: How to handle reads that violate --min-mut-gap (default auto).

Filter positions

--min-ninfo-pos N: Minimum informative reads at a position to keep it (default 1000).
--max-fmut-pos F: Maximum fraction of mutated reads at a position (default 1.0; disabled).

Branches

--branch X: Create a new branch: output results in {out}/{sample}/filter_{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.

Common unexpected results

Too many reads filtered out: Check filter-report.json to see which criterion removed the most reads. Loosen --min-finfo-read, --min-mut-gap, or --max-fmut-read, or shorten the region so reads cover it fully. Excessive mutations may indicate low RNA quality, bad base calls, or misalignment.
Too many positions filtered out: Check filter-report.json. Loosen --min-ninfo-pos or --max-fmut-pos. Too few informative reads usually means low sequencing depth or too many reads were removed first.
Filter hangs or crashes early: Almost always out of memory. Reduce --num-cpus or rerun IDmut with a smaller --batch-size.