DeRIP2 Command Line Interface
Basic usage
For aligned sequences in 'mintest.fa':
- Any column with >= 70% gap positions will not be corrected and a gap inserted in corrected sequence.
- Bases in column must be >= 80% C/T or G/A
- At least 50% bases in a column must be in RIP dinucleotide context (C/T as CpA / TpA) for correction.
- Default: Inherit all remaining uncorrected positions from the least RIP'd sequence.
- Mask all substrate and product motifs from corrected columns as ambiguous bases (i.e. CpA to TpA --> YpA)
Basic usage with masking
derip2 -i tests/data/mintest.fa \
--max-gaps 0.7 \
--max-snp-noise 0.2 \
--min-rip-like 0.5 \
--mask \
-d results \
--prefix derip_output
Output:
results/derip_output.fasta- Corrected sequenceresults/derip_output_alignment.fasta- Alignment with masked correctionsresults/derip_output_masked_alignment.fasta- Alignment with masked corrections
With vizualization
The --plot option will create a visualization of the alignment with RIP markup. The --plot-rip-type option can be used to specify the type of RIP events to be displayed in the alignment visualization product, substrate, or both. The --plot-format option selects the output file format: svg (default, scalable vector) or png (a fully rasterised, high-resolution image). For very wide alignments the SVG embeds its dense base grid as a raster that can blur at extreme zoom levels; choose png if you need a sharp image at any zoom.
derip2 -i tests/data/mintest.fa \
--max-gaps 0.7 \
--max-snp-noise 0.2 \
--min-rip-like 0.5 \
--plot \
--plot-rip-type both \
-d results \
--prefix derip_output
Output:
results/derip_output.fasta- Corrected sequenceresults/derip_output_masked_alignment.fasta- Alignment with masked correctionsresults/derip_output_visualization.svg- Visualization of the alignment with RIP markup
Using maximum GC content for filling
By default uncorrected positions in the output sequence are filled from the sequence with the lowest RIP count. If the --fill-max-gc option is set, remaining positions are filled from the sequence with the highest G/C content sequence instead.
derip2 -i tests/data/mintest.fa \
--max-gaps 0.7 \
--max-snp-noise 0.2 \
--min-rip-like 0.5 \
--fill-max-gc \
-d results \
--prefix derip_gc_filled
Alternatively, the --fill-index option can be used to force selection of alignment row to fill uncorrected positions from by row index number (indexed from 0). Note: This will override the --fill-max-gc option.
Correcting all deamination events
If the --reaminate option is set, all deamination events will be corrected, regardless of RIP context.
--plot-rip-type product is used to highlight the product of RIP events in the visualization.
Non-RIP deamination events are also highlighted.
derip2 -i tests/data/mintest.fa \
--max-gaps 0.7 \
--reaminate \
-d results \
--plot \
--plot-rip-type product \
--prefix derip_reaminated
Output:
results/derip_reaminated.fasta- Corrected sequence using highest GC content sequence for fillingresults/derip_reaminated_alignment.fasta- Alignment with corrected sequence appendedresults/derip_reaminated_vizualization.svg- Visualization of the alignment with RIP markup
Per-sequence HTML report
The --per-seq-report option writes an interactive, self-contained
prefix_per_sequence.html with one panel per input sequence: the alignment row
with its RIP sites highlighted, a fixed-height per-sequence strand-bias strip, a
per-sequence SBS-96 mutation spectrum measured against the reconstructed
ancestor, the flank-context spectra of RIP-like sites, and that sequence's
summary statistics. Step between sequences with the left/right arrow keys (or the
Prev/Next buttons).
The report's flank-context section tests whether a local sequence context
protects a substrate from RIP: it classifies every RIP-like dinucleotide by its
1 bp upstream and downstream flanks (16 channels) for surviving substrate
(CpA/TpG, anywhere) and realised product (TpA, in RIP columns) sites,
shown as a substrate/product × combined/forward/reverse grid with a
cosine/Cramér's V/χ² comparison table (and a pooled version on the overview
page). --per-seq-report also writes prefix_rip_context_spectra.tsv (tidy
counts) and prefix_rip_context_comparisons.tsv (comparison statistics).
For large alignments, --max-report-seqs N caps the report at the N
sequences with the strongest strand bias (largest |RSI|) and notes the
truncation.
By default every sequence's mutation spectrum is measured against the deRIP-corrected
consensus. Use --spectra-ref-index N to compare against an alignment row instead
(0-based; negative indices count from the end, so -1 is the last sequence). The
chosen reference then has an empty (self-comparison) spectrum, and the report prose
names it.
Gene annotation and RIP effect reporting
Supply a GFF3 gene model with --gff. Sequence ids in the GFF must match the
alignment record ids; coordinates are 1-based in each sequence's own ungapped
frame and are automatically adjusted for alignment gaps. Providing --gff:
- draws a stacked gene-annotation track below the
--plotfigure, - adds a gene-effect table (premature stops, non-synonymous changes, frameshifts, broken splice sites) and the deRIP-restored protein to each annotated sequence's panel in the per-sequence report, and
- always writes a
prefix_snp_effects.txtsummary.
derip2 -i tests/data/mintest.fa \
--gff tests/data/mintest.gff3 \
--per-seq-report \
--plot \
--genetic-code 1 \
-d results \
--prefix derip_output
Use --genetic-code to select an NCBI translation table other than the
standard code (table 1), and --annotation-colors FILE to override the
annotation-track colours with a two-column type<TAB>hex file.
Output:
results/derip_output_per_sequence.html- Interactive per-sequence reportresults/derip_output_rip_context_spectra.tsv- Flank-context site countsresults/derip_output_rip_context_comparisons.tsv- Substrate-vs-product testsresults/derip_output_snp_effects.txt- Per-sequence + restored-CDS effectsresults/derip_output_visualization.svg- Alignment figure with the track
Standard Options
--version Show the version and exit.
-i, --input TEXT Multiple sequence alignment. [required]
-g, --max-gaps FLOAT Maximum proportion of gapped positions in
column to be tolerated before forcing a gap
in final deRIP sequence. [default: 0.7]
-a, --reaminate Correct all deamination events independent
of RIP context.
--max-snp-noise FLOAT Maximum proportion of conflicting SNPs
permitted before excluding column from
RIP/deamination assessment. i.e. By default
a column with >= 0.5 'C/T' bases will have
'TpA' positions logged as RIP events.
[default: 0.5]
--min-rip-like FLOAT Minimum proportion of deamination events in
RIP context (5' CpA 3' --> 5' TpA 3')
required for column to deRIP'd in final
sequence. Note: If 'reaminate' option is set
all deamination events will be corrected.
[default: 0.1]
--fill-max-gc By default uncorrected positions in the
output sequence are filled from the sequence
with the lowest RIP count. If this option is
set remaining positions are filled from the
sequence with the highest G/C content.
--fill-index INTEGER Force selection of alignment row to fill
uncorrected positions from by row index
number (indexed from 0). Note: Will override
'--fill-max-gc' option.
--mask Mask corrected positions in alignment with
degenerate IUPAC codes.
--no-append If set, do not append deRIP'd sequence to
output alignment.
-d, --out-dir TEXT Directory for deRIP'd sequence files to be
written to.
-p, --prefix TEXT Prefix for output files. Output files will
be named prefix.fasta,
prefix_alignment.fasta, etc. [default:
deRIPseq]
--plot Create a visualization of the alignment with
RIP markup.
--plot-rip-type [both|product|substrate]
Specify the type of RIP events to be
displayed in the alignment visualization.
[default: both]
--plot-format [svg|png] File format for the --plot alignment
visualization. "svg" is scalable vector
output (the dense base grid of wide
alignments is embedded as a raster and can
blur at extreme zoom); "png" is a fully
rasterised, high-resolution image that stays
sharp at any zoom level. [default: svg]
--plot-strand-bias Create a diverging stacked-bar chart of per-
column RIP strand bias.
--strand-bias-scale [column|alignment|counts]
Bar height normalisation: each column to its
own depth, to the number of sequences (so
gappy columns are short), or raw counts.
[default: column]
--strand-bias-xaxis [none|logo|derip]
Draw a sequence logo or the deRIP'd
consensus along the zero line. [default:
none]
--strand-bias-columns [rip|substrate|all]
Which positions are lettered along the zero
line. [default: all]
--strand-bias-stack [signal|product|all]
Which bases each bar is made of. [default:
signal]
--rsi-ambiguous [split|exclude|weight|both]
How to attribute a TA dinucleotide that
could have arisen from RIP on either strand
when calculating RSI. [default: split]
--sort-by-rsi Sort the output alignment from most forward-
to most reverse-strand RIP.
--stats-out Write the per-sequence statistics table to
prefix_stats.tsv.
--html-report Write a self-contained HTML report to
prefix_report.html.
--per-seq-report Write an interactive per-sequence HTML
report to prefix_per_sequence.html (one
arrow-key-navigable panel per sequence).
--max-report-seqs INTEGER Cap the number of sequence panels in the
per-sequence report. When the alignment has
more sequences, the strongest strand-bias
sequences are kept. Unset renders every
sequence.
--spectra-ref-index INTEGER Alignment row index (0-based; negatives
allowed) of a sequence to use as the
reference for the per-sequence report
mutation spectra, instead of the deRIP-
corrected consensus. The chosen reference
has an empty (self-comparison) spectrum.
Unset compares against the deRIP consensus.
--gff TEXT GFF3 gene model. Sequence ids must match
alignment record ids. Enables a gene-
annotation track on --plot, gene-effect
panels in the per-sequence report, and a
prefix_snp_effects.txt summary.
--genetic-code INTEGER NCBI genetic code table for CDS translation
and effect prediction. [default: 1]
--annotation-colors TEXT Two-column (type<TAB>hex) file overriding
default annotation-track colours by feature
type.
--loglevel [DEBUG|INFO|WARNING|ERROR|CRITICAL]
Set logging level. [default: INFO]
--logfile TEXT Log file path.
-h, --help Show this message and exit.
Mutation spectra (derip2-spectra)
derip2-spectra builds trinucleotide-context SBS-96 and SBS-192 mutation spectra
from an alignment (or a CHG-aware downstream-triplet context, see below). See the
Mutation Spectra tutorial for a full
walkthrough; the essentials are below.
Baseline (no tree, no external tools)
Writes family.SBS96.txt, family.SBS192.txt (SigProfiler-compliant matrices),
the spectrum/strand-asymmetry/homoplasy plots, and family_events.tsv.
By default the baseline reconstructs the deRIP consensus internally and calls every sequence against it.
Downstream-triplet context (CHG methylation)
--context downstream classifies each substitution by the mutated base plus its
two downstream bases (motif ref-d1-d2) instead of the 5′/3′ flanks, exposing
methylation-driven C>T in the fungal CHG context. It produces a single
pyrimidine-folded, orientation-invariant 96-channel matrix — no SBS-192 or
strand-asymmetry — with distinct [REF>ALT]d1d2 labels and a JSON provenance
sidecar. --sbs 192/both are rejected in this mode. It composes with everything
else (--method phylo, --groups, --partition-by).
derip2-spectra -i family.fasta --context downstream -d results -p family
# writes family.SBSdownstream.txt, family.SBSdownstream.meta.json,
# family_SBSdownstream.png, family_events.tsv, family_homoplasy.{tsv,png}
Reusing a precomputed ancestral reference
If you have already run derip2 and appended the deRIP'd consensus to your
alignment, derip2-spectra will reuse it instead of recomputing. Any row whose
id matches --reference-tag (default deRIPseq) is used as the ancestral
reference and excluded from the counted sequences (a message is logged when
this happens):
# family_with_deRIPseq.fasta already contains a "deRIPseq" row
derip2-spectra -i family_with_deRIPseq.fasta -d results -p family
# Point at a differently-named reference row
derip2-spectra -i family.fasta --reference-tag MyAncestor -d results -p family
Alternatively, supply a separate hypothetical ancestor as a single-sequence
FASTA with --ancestor. It must be the same length as the alignment (this is
validated up front) and takes precedence over any in-alignment reference row:
Input must be unambiguous DNA. Alignments may only contain
A/C/G/T/-(upper or lower case; soft-masking is normalised). Degenerate IUPAC characters (N,R,Y, …) are rejected with an error naming the offending character and its location, rather than being silently treated as gaps.
Phylogenetic (IQ-TREE ancestral reconstruction)
Requires IQ-TREE (iqtree3/iqtree2/iqtree) on PATH.
# Infer the tree and reconstruct ancestors automatically
derip2-spectra -i family.fasta --method phylo -d results -p family
Supplying a precalculated phylogeny
Pass any Newick tree with --tree; IQ-TREE fixes that topology and recomputes the
model, branch lengths and ancestral states from the alignment.
iqtree3 -s family.fasta -m MFP -B 1000 -T AUTO --prefix family_tree
derip2-spectra -i family.fasta --method phylo --tree family_tree.treefile \
-d results -p family
Recommended: topology from a RIP-masked alignment
Infer the topology from a RIP-masked alignment (so convergent RIP does not distort it), then reconstruct ancestral states for the unmasked sequences on that same topology:
derip2 -i family.fasta --mask --no-append -d results -p family
iqtree3 -s results/family_masked_alignment.fasta -m MFP -B 1000 -T AUTO \
--prefix results/family_masked
derip2-spectra -i family.fasta --method phylo --tree results/family_masked.treefile \
-d results -p family_spectrum
Per-group spectra (species or user-defined sets)
Pass a two-column (name, group) file with --groups to report one spectrum per
group. Works for both methods and tolerates IQ-TREE name reformatting:
derip2-spectra -i family.fasta --groups groups.tsv -d results -p family
derip2-spectra -i family.fasta --method phylo --groups groups.tsv -d results -p family
derip2-spectra options
--version Show the version and exit.
-i, --input TEXT Multiple sequence alignment (FASTA,
optionally gzipped). [required]
-d, --out-dir TEXT Directory for spectrum output files.
-p, --prefix TEXT Prefix for output files. [default:
deRIPspectra]
--ancestor TEXT Optional FASTA of a hypothetical ancestor to
call against instead of the reconstructed
deRIP consensus. Must be the same length as
the alignment.
--reference-tag TEXT Exact sequence ID of a pre-computed
ancestral reference already present in the
input alignment (e.g. a deRIP consensus you
appended with derip2). When found (baseline
method), that row is used as the ancestor
and excluded from the counted sequences
instead of re-running deRIP. Overridden by
--ancestor. [default: deRIPseq]
--context [trinucleotide|downstream]
Sequence context to classify substitutions
by: the 5'/3' trinucleotide flanks
(SBS-96/192), or the mutated base plus its
two downstream bases (pyrimidine-folded
96-channel, CHG-aware). The downstream
context produces a single folded matrix, so
--sbs 192/both do not apply. [default:
trinucleotide]
--sbs [96|192|both] Which SBS matrices/plots to produce
(trinucleotide context only). [default:
both]
--partition-by [none|row|clade]
Split spectra into one pooled sample, one
per sequence (baseline) or one per root
clade (phylo). [default: none]
--groups TEXT Path to a two-column (name, group) file
mapping sequences to group labels (e.g.
species). Reports one spectrum per group;
works for both methods and tolerates IQ-TREE
name reformatting. Overrides --partition-by.
--percentage Plot spectra as a percentage of each sample
total.
--min-hits INTEGER Minimum independent hits for a site in the
homoplasy report. [default: 2]
--no-plots Write matrices and tables only; skip
figures.
--method [baseline|phylo] Spectrum method: tree-free single-reference
baseline, or phylogenetic branch-by-branch
calling via IQ-TREE ancestral
reconstruction. [default: baseline]
--tree TEXT Fixed Newick tree for the phylo path; IQ-
TREE reconstructs ancestral states on this
topology instead of inferring a new tree.
--iqtree-model TEXT Substitution model passed to IQ-TREE (-m)
for the phylo path. [default: MFP]
--threads TEXT IQ-TREE thread count (-T). AUTO benchmarks
the best value; pass an integer to skip the
benchmark (faster on small alignments).
[default: AUTO]
--rooting [midpoint|outgroup|none]
How to root the tree for the phylo path
(sets substitution direction). [default:
midpoint]
--outgroup TEXT Outgroup tip name(s) for --rooting outgroup;
comma-separate a clade.
--min-prob FLOAT Drop phylo events whose parent x child
ancestral posterior is below this threshold.
[default: 0.0]
--root-sensitivity Also report the fraction of edges whose
direction flips under midpoint rooting
(phylo path).
-g, --max-gaps FLOAT Maximum gap proportion in a column before it
is gapped in the consensus. [default: 0.7]
-a, --reaminate Correct all deamination events regardless of
RIP context when building the ancestor.
--max-snp-noise FLOAT Maximum proportion of conflicting SNPs
before a column is excluded from RIP
assessment. [default: 0.5]
--min-rip-like FLOAT Minimum proportion of RIP-context
deamination for a column to be corrected.
[default: 0.1]
--fill-max-gc Fill uncorrected positions from the highest-
GC sequence rather than the least-RIP'd one.
--fill-index INTEGER Force the fill row by index (overrides
--fill-max-gc).
--loglevel [DEBUG|INFO|WARNING|ERROR|CRITICAL]
Set logging level. [default: INFO]
--logfile TEXT Log file path.
-h, --help Show this message and exit.