This is the documentation of DiMA . The newest release is .
This documentation of the development version includes changes that are not released yet. The newest release is .
Find conserved sequences
Historically conserved sequences (HCS) are stretches of the alignment whose most common k-mer is carried by (almost) every sequence; see Historically conserved sequences for the method.
During an analysis
Section titled “During an analysis”dima analyze -i spike.fasta -o spike.json --hcs-output spike.hcs.jsonThe regions are also written as <name>.hcs.tsv by --tsv-dir, and as a single table by
-o FILE.tsv --table hcs. --hcs-output takes .json or .tsv, optionally followed by .gz
or .zst.
The default threshold is the paper’s, 100%: positions where every sequence with a valid k-mer
carries the Index (Tharanga et al. 2025). Set another with
--hcs-min-incidence, a value above 50 and at most 100 (decimals allowed, compared exactly):
dima analyze -i hiv.fasta -o hiv.json --hcs-output hiv.hcs.tsv --hcs-min-incidence 70From existing results
Section titled “From existing results”Regions are computed from the results, so you can explore thresholds without reanalysing the alignment:
dima hcs -i spike.json # 100%, JSON on standard outputdima hcs -i spike.json --hcs-min-incidence 95 -o spike.hcs95.tsvdima hcs -i spike.json.zst --hcs-min-incidence 90 --hcs-eligible-only -O tsvdima hcs prints how many regions it found on standard error.
Read the regions
Section titled “Read the regions”dima hcs -i mers.json -O tsv | head -3region_id start_column end_column length min_incidence min_support conservation_lower_bound_95 flagged low_support_position_count sequence1 7 22 16 100.0 170 0.9785344450190554 false 0 LLMFLLTPTESYVDVG2 35 83 49 100.0 171 0.9786586254334971 false 0 IQQTFFDKTWPRPIDVSKADGIIYPQGRTYSNITITYQGLFPYQGDHGDFor each region: the alignment columns it covers and its sequence; the lowest Index incidence and
the lowest support among its member positions; the lowest exact 95% Clopper–Pearson lower bound
of their conservation (Clopper & Pearson 1934); and whether it is flagged because positions in its span
have support at or below
Flagged regions
Section titled “Flagged regions”A region is flagged when it spans positions supported by hcs_low_support_regions). Look at
min_support and conservation_lower_bound_95: a k-mer carried by all of 3 sequences has a
lower bound of 29.2%, by all of 100 sequences 96.4%.
To build regions from well-supported positions only, add --hcs-eligible-only: positions with
support ≤
Choose a threshold
Section titled “Choose a threshold”- 100% (default) asks for complete conservation, the paper’s definition.
- Lower thresholds tolerate rare variants; above 50% the most common k-mer is still unique at every member position, which is why lower values are refused.
- Report the threshold and whether eligible-only was used; both are recorded in the output
(
parameters).
Examples on the paper’s datasets are in Historically conserved sequences.
References
Section titled “References”- Abd Raman HS, Tan S, August JT, Khan AM. Dynamics of Influenza A (H5N1) virus protein sequence diversity. PeerJ. 2020;7:e7954. doi:10.7717/peerj.7954 ↩︎
- Clopper CJ, Pearson ES. The use of confidence or fiducial limits illustrated in the case of the binomial. Biometrika. 1934;26(4):404-413. doi:10.1093/biomet/26.4.404 ↩︎
- Hu Y, Tan PT, Tan TW, August JT, Khan AM. Dissecting the Dynamics of HIV-1 Protein Sequence Diversity. PLoS ONE. 2013;8(4):e59994. doi:10.1371/journal.pone.0059994 ↩︎
- Tharanga S, Ünlü ES, Hu Y, Sjaugi MF, Çelik MA, Hekimoğlu H, Miotto O, Öncel MM, Khan AM. DiMA: sequence diversity dynamics analyser for viruses. Briefings in Bioinformatics. 2025;26(1):bbae607. doi:10.1093/bib/bbae607 ↩︎