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 .
Your first analysis
This tutorial analyses the alignment behind Fig. 1C of the DiMA paper (Tharanga et al. 2025): 191
MERS-CoV spike protein sequences. It takes a few minutes and shows every kind of result DiMA
produces. You need dima (Install DiMA) and, for a few steps,
jq.
1. Get the alignment
Section titled “1. Get the alignment”curl -fLO https://raw.githubusercontent.com/ShanWeera/dima-perf/master/samples/mers_spike_aa.fastagrep -c '>' mers_spike_aa.fasta # 191 sequenceshead -c 200 mers_spike_aa.fasta>YP_009047204.1 |Homo sapiens||2012MIHSVFLLMFLLTPTESYVDVGPDSVKSACIEVDIQQTFFDKTWPRPIDVSKADGIIYPQGRTYSNITITYQGLFPYQGDHGDMYVYSAGHATGTTPQKLFVANYSQDVKQFANGFVVRIIt is an ordinary FASTA alignment, wrapped at 60 characters, with Windows (CRLF) line endings —
DiMA reads it like any other layout. The headers carry the accession, the host, the country and
the year, separated by |.
2. Run the analysis
Section titled “2. Run the analysis”dima analyze -i mers_spike_aa.fasta -o mers.jsonDiMA detects that the sequences are proteins, uses 9-mers and the paper’s support threshold of
100, and writes the results to mers.json. On the terminal it prints a one-line summary of the
run (and warnings, if there were any).
3. Read the summary
Section titled “3. Read the summary”jq '{sequence_count, position_count, eligible_position_count, average_entropy, lowest_entropy, highest_entropy}' mers.json{ "sequence_count": 191, "position_count": 1345, "eligible_position_count": 1345, "average_entropy": 0.12613379461699337, "lowest_entropy": { "position": 7, "entropy": 0.0, "tied_position_count": 455 }, "highest_entropy": { "position": 26, "entropy": 1.5878251756456703, "tied_position_count": 1 }}The alignment has 1,353 columns, so there are
4. Look at one position
Section titled “4. Look at one position”Position 25 is the one shown in the paper’s Fig. 1C:
jq '.results[24] | {position, support, entropy, observed_entropy, total_variants_incidence, distinct_variants_incidence, sample_coverage}' mers.jsonjq -r '.results[24].diversity_motifs[] | [.sequence, .count, .motif_long] | @tsv' mers.jsonSVKSACIEV 129 IndexSFKSACIEV 14 MajorSVKPACIEV 9 MinorSAKSACIEV 6 MinorSLKSACIEV 4 MinorSVKSACIAV 4 MinorSAKSVCIEV 1 UniqueSIKSACIEV 1 UniqueSVKSACIKV 1 UniqueSVKSVCIEV 1 Unique- 170 of the 191 sequences have a complete 9-mer at columns 25–33 (the others have a gap or an ambiguous residue there): the support is 170.
- The most common variant, the Index, is carried by 129 sequences (75.88%); the second most common is the Major; variants seen more than once are Minor; variants seen once are Unique.
- 41 sequences (24.12%) carry a non-Index variant (
total_variants_incidence); they carry 9 distinct variants, 21.95% of 41 (distinct_variants_incidence; 22.0% in the paper). - The observed entropy is 1.4224 bits; corrected for sample size it is 1.4617 bits (
entropy). The paper shows 1.38 bits for this position, from one run of its random correction with a threshold of 30; the explanation shows why both agree. - The sample coverage, 0.98, estimates that one more sequence would almost certainly carry a variant already seen.
5. Write tables
Section titled “5. Write tables”For R, Python or a spreadsheet, write the same results as four tidy tables:
dima analyze -i mers_spike_aa.fasta -o mers.json --tsv-dir tablesls tablesmers_spike_aa.hcs.tsv mers_spike_aa.metadata.tsv mers_spike_aa.positions.tsv mers_spike_aa.variants.tsvpositions has one row per position, variants one row per variant, hcs one row per conserved
region; metadata stays empty until you describe the headers (step 7). See
Choose and read outputs for R and pandas recipes.
6. Find conserved sequences
Section titled “6. Find conserved sequences”dima hcs -i mers.json -O tsv | cut -f 1-4,10 | head -4region_id start_column end_column length sequence1 7 22 16 LLMFLLTPTESYVDVG2 35 83 49 IQQTFFDKTWPRPIDVSKADGIIYPQGRTYSNITITYQGLFPYQGDHGD3 107 125 19 QDVKQFANGFVVRIGAAANAt the default threshold of 100%, DiMA finds 44 historically conserved sequences: stretches
where every supporting sequence carries the same residues. Try --hcs-min-incidence 95 to allow
rare variants. See Find conserved sequences.
7. Count variants per host
Section titled “7. Count variants per host”dima analyze -i mers_spike_aa.fasta -o mers.meta.json \ --header-format 'Accession|Host|Geolocation|Year' --metadata-fields 'Host|Geolocation|Year'jq '.results[24].diversity_motifs[1].metadata.Host' mers.meta.json{ "Camelus": 2, "Camelus dromedarius": 9, "Homo sapiens": 3 }The Major variant at position 25 was found in camels and in humans. DiMA also warns that two
records have the year nan — a value that usually means “missing” — so that you can decide what
it means. See Stratify by header metadata.
8. Cite the analysis
Section titled “8. Cite the analysis”dima cite --from mers.jsonprints a methods paragraph describing this run and the references of the methods it used, including the DiMA paper and the exact version of the software. See Citing DiMA.
Next steps
Section titled “Next steps”- Analyse an alignment: choose k, the support threshold, the alphabet and the estimator for your data.
- How DiMA measures diversity: what every number means.
- Use the desktop app to explore the same results interactively.
- Frequently asked questions and the Glossary of the terms in the results.
References
Section titled “References”- 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 ↩︎