Skip to content

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.

Terminal window
curl -fLO https://raw.githubusercontent.com/ShanWeera/dima-perf/master/samples/mers_spike_aa.fasta
grep -c '>' mers_spike_aa.fasta # 191 sequences
head -c 200 mers_spike_aa.fasta
>YP_009047204.1 |Homo sapiens||2012
MIHSVFLLMFLLTPTESYVDVGPDSVKSACIEVDIQQTFFDKTWPRPIDVSKADGIIYPQ
GRTYSNITITYQGLFPYQGDHGDMYVYSAGHATGTTPQKLFVANYSQDVKQFANGFVVRI

It 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 |.

Terminal window
dima analyze -i mers_spike_aa.fasta -o mers.json

DiMA 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).

Terminal window
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 1,353 − 9 + 1 = 1,345 positions of 9-mers. Every position is supported by more than 100 sequences, so all are eligible: their entropy is corrected for sample size and they count in the summary. The spike protein is mostly conserved — mean entropy 0.13 bits, 455 positions with a single variant — with the highest diversity at position 26.

Position 25 is the one shown in the paper’s Fig. 1C:

Terminal window
jq '.results[24] | {position, support, entropy, observed_entropy, total_variants_incidence,
distinct_variants_incidence, sample_coverage}' mers.json
jq -r '.results[24].diversity_motifs[] | [.sequence, .count, .motif_long] | @tsv' mers.json
SVKSACIEV 129 Index
SFKSACIEV 14 Major
SVKPACIEV 9 Minor
SAKSACIEV 6 Minor
SLKSACIEV 4 Minor
SVKSACIAV 4 Minor
SAKSVCIEV 1 Unique
SIKSACIEV 1 Unique
SVKSACIKV 1 Unique
SVKSVCIEV 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.

For R, Python or a spreadsheet, write the same results as four tidy tables:

Terminal window
dima analyze -i mers_spike_aa.fasta -o mers.json --tsv-dir tables
ls tables
mers_spike_aa.hcs.tsv mers_spike_aa.metadata.tsv mers_spike_aa.positions.tsv mers_spike_aa.variants.tsv

positions 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.

Terminal window
dima hcs -i mers.json -O tsv | cut -f 1-4,10 | head -4
region_id start_column end_column length sequence
1 7 22 16 LLMFLLTPTESYVDVG
2 35 83 49 IQQTFFDKTWPRPIDVSKADGIIYPQGRTYSNITITYQGLFPYQGDHGD
3 107 125 19 QDVKQFANGFVVRIGAAAN

At 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.

Terminal window
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.

Terminal window
dima cite --from mers.json

prints 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.

  • 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 ↩︎