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 .
Analyse an alignment
This guide covers the decisions of a typical analysis. Every option is listed in the command-line reference.
Prepare the input
Section titled “Prepare the input”DiMA analyses an existing multiple sequence alignment in FASTA format: every sequence must have the same number of columns. Align your sequences first (for example with MAFFT or Clustal Omega (Katoh & Standley 2013; Sievers et al. 2011)), and keep them protein or nucleotide, not mixed.
The file can be wrapped or not, upper or lower case, with Unix or Windows line endings, plain or compressed with gzip, bzip2 or Zstandard — DiMA recognises compression by content, so the file name does not matter. It can also come from a pipe:
dima analyze -i spike.fasta.zst -o spike.jsonzcat spike.fasta.gz | dima analyze -o spike.json # standard inputdima analyze -i <(seqkit grep -n -r -p 'Homo sapiens' all.fasta) -o human.jsonseqkit (Shen et al. 2016) is used here only as an example of a tool that writes FASTA to a pipe.
Run it
Section titled “Run it”dima analyze -i spike.fasta -o spike.jsonWithout -o (and without --tsv-dir or --hcs-output), the results go to standard output as
JSON. DiMA prints warnings and a one-line summary on standard error; add -v for progress
milestones and a performance report, or -q for errors only.
Choose the k-mer length
Section titled “Choose the k-mer length”-k sets the window length. The default depends on the alphabet: 9 for proteins, the length
of the peptides presented by HLA class I molecules (Falk et al. 1991; Rammensee 1993; Tharanga et al. 2025),
and 27 for nucleotides (the codons of a 9-mer). Any value from 1 to the alignment length is
accepted:
dima analyze -i spike.fasta -k 15 -o spike.k15.jsonLonger k-mers capture longer stretches but are more often invalidated by a gap or an ambiguity
code, which lowers the support. The value used, and whether it was the default, is recorded in
run.parameters.kmer_length.
Choose the support threshold
Section titled “Choose the support threshold”-s/--support-threshold sets entropy_fallback records) and they enter the summary statistics. The default, 100, is
the paper’s value, which it describes as “arbitrarily defined” (Tharanga et al. 2025):
dima analyze -i spike.fasta -s 50 -o spike.T50.jsonThere is no universally right value. A lower threshold_exceeds_sequence_count). Whatever you choose, report it: it is recorded in the
results and printed by dima cite --from. See
the support threshold.
Set the alphabet if needed
Section titled “Set the alphabet if needed”By default DiMA detects protein, DNA or RNA from the residues of the first records, with the rules of HMMER’s Easel library (Eddy 2011). When they do not decide — very short sequences, or both T and U present — DiMA stops and asks:
dima analyze -i short_peptides.fasta -a protein -o peptides.json-a accepts auto, protein, dna and rna. If you set it and the data look different,
DiMA warns (alphabet_contradiction) but uses your choice.
Choose the entropy estimator
Section titled “Choose the entropy estimator”The default, --estimator dima, is the paper’s correction, computed exactly. Three alternatives
are available for comparison or sensitivity analyses:
dima analyze -i spike.fasta --estimator chao-wang-jost -o spike.cwj.json| Estimator | When to use it |
|---|---|
dima (default) | Results comparable with the paper and earlier DiMA analyses |
chao-wang-jost | Lowest bias among the estimators in its authors’ comparison (Chao et al. 2013); also corrects positions with support ≤ |
miller-madow | The classical first-order correction (Miller 1955) |
raw | The observed entropy, uncorrected |
Every position also reports its observed entropy and its sample coverage, whatever the estimator. See Entropy and its correction.
Read the results
Section titled “Read the results”The summary keys at the top of the JSON answer the paper’s questions directly:
jq '{query_name, sequence_count, position_count, eligible_position_count, average_entropy, lowest_entropy, highest_entropy, support_label_counts}' spike.jsonEach entry of results describes one position: its support and label, entropies, incidences,
coverage and the list of variants with their motifs. For example, the five most diverse
eligible positions:
jq -c '[.results[] | select(.low_support == null)] | sort_by(-.entropy) | .[:5][] | {position, support, entropy}' spike.jsonThe same data as tables, ready for R or pandas, come from --tsv-dir:
dima analyze -i spike.fasta -o spike.json --tsv-dir tablesSee Choose and read outputs and the JSON reference.
DiMA uses all the CPUs it may use (on a batch scheduler, the CPUs of your allocation); -t N
sets the number. The results never depend on it. See
Run on clusters and in pipelines and Analyse large alignments.
References
Section titled “References”- Chao A, Wang YT, Jost L. Entropy and the species accumulation curve: a novel entropy estimator via discovery rates of new species. Methods in Ecology and Evolution. 2013;4(11):1091-1100. doi:10.1111/2041-210X.12108 ↩︎
- Eddy SR. Accelerated Profile HMM Searches. PLoS Computational Biology. 2011;7(10):e1002195. doi:10.1371/journal.pcbi.1002195 ↩︎
- Falk K, Rötzschke O, Stevanović S, Jung G, Rammensee HG. Allele-specific motifs revealed by sequencing of self-peptides eluted from MHC molecules. Nature. 1991;351(6324):290-296. doi:10.1038/351290a0 ↩︎
- Katoh K, Standley DM. MAFFT Multiple Sequence Alignment Software Version 7: Improvements in Performance and Usability. Molecular Biology and Evolution. 2013;30(4):772-780. doi:10.1093/molbev/mst010 ↩︎
- Miller GA. Note on the bias of information estimates. In: Information Theory in Psychology: Problems and Methods (Quastler H, ed.), Free Press, Glencoe, IL. 1955. p. 95-100. ↩︎
- Rammensee H. Peptides Naturally Presented by MHC Class I Molecules. Annual Review of Immunology. 1993;11(1):213-244. doi:10.1146/annurev.immunol.11.1.213 ↩︎
- Shen W, Le S, Li Y, Hu F. SeqKit: A Cross-Platform and Ultrafast Toolkit for FASTA/Q File Manipulation. PLOS ONE. 2016;11(10):e0163962. doi:10.1371/journal.pone.0163962 ↩︎
- Sievers F, Wilm A, Dineen D, Gibson TJ, Karplus K, Li W, Lopez R, McWilliam H, Remmert M, Söding J, Thompson JD, Higgins DG. Fast, scalable generation of high-quality protein multiple sequence alignments using Clustal Omega. Molecular Systems Biology. 2011;7(1):MSB201175. doi:10.1038/msb.2011.75 ↩︎
- 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