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 .
Diversity motifs and summaries
Entropy condenses a position into one number. Diversity motifs keep the structure: which variant dominates, which variants follow, and how much of the population carries something other than the dominant variant. The motif classes were introduced by Hu et al. for HIV-1 (Hu et al. 2013) and applied by Abd Raman et al. to influenza A (H5N1) (Abd Raman et al. 2020), as the paper recounts; DiMA reports them as the paper defines them (Tharanga et al. 2025).
Motif classes
Section titled “Motif classes”At a position with variant counts
| Motif | Short | Rule |
|---|---|---|
| Index | I | the highest count, if it is above 1 |
| Unique | U | count 1 |
| Major | Ma | the highest count among the remaining variants (count above 1) |
| Minor | Mi | every other variant (count above 1) |
Ties are kept, as the paper states that “a position may exhibit more than one index or major variant”: every variant tied at the highest count is Index, and every variant tied at the next-highest count is Major. A position where every variant occurs once has no Index (all are Unique). Examples, by count:
| Counts | Motifs |
|---|---|
| 129, 14, 9, 6, 4, 4, 1, 1, 1, 1 | I, Ma, Mi, Mi, Mi, Mi, U, U, U, U |
| 3, 3, 2, 2, 1 | I, I, Ma, Ma, U |
| 7, 4, 3, 3 | I, Ma, Mi, Mi |
| 5 | I |
| 1, 1, 1 | U, U, U |
Variants are listed by count, highest first; variants with equal counts are ordered by their sequence (byte order), so the order is the same in every run.
Incidences
Section titled “Incidences”All incidences are percentages of the position’s support
The total variants incidence (2) is the share of sequences that carry a
variant other than the Index; the distinct variants incidence (3) measures
how many different variants those sequences carry, relative to how many sequences there are. The
number of non-Index variants is reported as distinct_variants_count.
At MERS-CoV spike position 25 (support 170; the Index SVKSACIEV occurs 129 times):
41 sequences carry a non-Index variant, so the total variants incidence is
The paper’s text gives this denominator — the total variants count — and so does its Fig. 1C. Its schematic Fig. 1A divides by the support instead (“Distinct variants (6/20)”); DiMA follows the text and Fig. 1C (Tharanga et al. 2025).
Undefined ratios
Section titled “Undefined ratios”A ratio whose denominator is 0 is undefined, and DiMA reports it as null (JSON) or NA
(tables) instead of inventing a value:
- a position without support has no variants (
diversity_motifsis empty) and both incidences arenull; - a fully conserved position (every sequence carries the Index) has a total variants
incidence of 0 and an undefined distinct variants incidence (
).
DiMA v5.0.9 reported both cases as 0, which made a conserved position indistinguishable from a position with no data.
Metadata per variant
Section titled “Metadata per variant”With --header-format, each variant also carries the number of its sequences per value of every
stratified header field — for example how many of the 14 SFKSACIEV sequences at position 25
came from each host. Fields appear in header-format order and values in byte order. See
Stratify by header metadata.
Run summaries
Section titled “Run summaries”Every result file starts with run-level summaries.
Eligible summary (top-level keys). The mean, lowest and highest entropy over the eligible
positions (support above tied_position_count), so ties are visible instead of being resolved silently. All three are
null when no position is eligible.
All-positions summary (all_positions_summary). The same statistics with DiMA v5.0.9’s
averaging rule — every position, NS positions counted as 0 bits and LS/ELS positions with their
reported entropy (the observed entropy with the dima and raw estimators) — so that results can
be compared with earlier analyses. The rule key records
the rule. It is not the paper’s summary; see
why NS positions have no entropy.
Support classes. position_count, eligible_position_count, the counts per label
(support_label_counts: NS, LS, ELS, eligible) and low_support_count (NS + LS + ELS).
Coverage summary (coverage_summary). How many positions have a sample coverage (support of
at least 2), its minimum and mean, and with --min-coverage the threshold and the number of
positions below it.
For the MERS-CoV spike protein with the defaults: 1,345 positions, all eligible; mean entropy 0.1261 bits; lowest 0 bits (first at position 7, 455 positions tied); highest 1.5878 bits at position 26.
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 ↩︎
- 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 ↩︎ 1 2 3