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 .
Frequently asked questions
Each answer is short and links to the page that explains it in full. Error messages and warnings are explained in Troubleshooting, and the terms used in the results in the Glossary.
Before you start
Section titled “Before you start”Is this the DiMA of the paper?
Section titled “Is this the DiMA of the paper?”Yes. dima implements the method of the DiMA paper (Tharanga et al. 2025) and reproduces its published
results (Comparison with the paper). It replaces dima-cli 5.x,
which stays installable from PyPI but is no longer developed, and the web server.
I used dima-cli 5.x. What changed?
Section titled “I used dima-cli 5.x. What changed?”The analysis is now a subcommand: dima analyze -i alignment.fasta. Several options were renamed,
and short options now have the meanings common to command-line tools: -t sets the number of
threads, -q and -v how much is printed, and -k the k-mer length (see
the command line). The default support threshold is now the paper’s 100
(5.x used 30). Some results differ by design; each difference is listed with its reason in
Differences from DiMA v5.0.9.
Does my data leave my computer?
Section titled “Does my data leave my computer?”No. The command-line tool and the desktop app read and write local files only and make no network connections. The desktop app opens a web page, in your browser, only when you click a link.
Is DiMA only for viruses?
Section titled “Is DiMA only for viruses?”DiMA was designed and validated on viral alignments. The computation works on any protein or nucleotide alignment, but its defaults were chosen for viral data: k = 9 for proteins is the length of the peptides presented by HLA class I molecules (Falk et al. 1991; Rammensee 1993; Tharanga et al. 2025) (27 for nucleotides), and the paper set the support threshold of 100 arbitrarily (Tharanga et al. 2025). Check them before using DiMA on other organisms (Choose the k-mer length, Choose the support threshold).
What input does DiMA need?
Section titled “What input does DiMA need?”A multiple sequence alignment in FASTA format, protein or nucleotide, plain or compressed (gzip,
bzip2 or Zstandard; decompress an xz file first, or recompress it with Zstandard). DiMA does not
align sequences itself. Convert other alignment formats
first, for example Stockholm with Easel’s esl-reformat afa alignment.sto > alignment.fasta or
with Biopython’s AlignIO.convert (Cock et al. 2009). See Reading alignments.
How many sequences do I need?
Section titled “How many sequences do I need?”A position needs more sequences with a valid k-mer than the support threshold (-s, default 100)
for the paper’s corrected entropy and to enter the summary statistics. With smaller alignments,
lower -s and report the value you used, or choose --estimator chao-wang-jost, which corrects
every position with at least two sequences (Chao et al. 2013). See
Choose the support threshold and
Alternative estimators.
Which version of this documentation should I read?
Section titled “Which version of this documentation should I read?”The one that matches dima --version; choose it in the version menu at the top of the page.
latest describes the development version (the master branch) and may include changes that are not released yet. In
released builds, the documentation link printed by dima --help and shown in the desktop app
leads to the documentation of that version; builds from source link latest.
Using DiMA
Section titled “Using DiMA”How do I get the entropy per host, country or year?
Section titled “How do I get the entropy per host, country or year?”Split the alignment by that header field, for example with seqkit grep (Shen et al. 2016), and analyse
each part. --metadata-fields does something else: it counts each variant’s sequences per value
of a header field (Stratify by header metadata). Before comparing the parts,
see the next question.
Can I compare diversity between proteins or datasets?
Section titled “Can I compare diversity between proteins or datasets?”Yes, that is what DiMA is for (Tharanga et al. 2025), but only between runs with the same k, alphabet and
support threshold, and between positions of similar support: the scale of entropy depends on the
window length and the alphabet, and entropy estimates grow with the number of sequences
(Miller 1955; Chao et al. 2013), a dependence the paper’s correction reduces but does not remove. Report
the support and the sample coverage of both analyses, and check that the conclusion holds with
--estimator chao-wang-jost. See Entropy and its correction.
How do I plot entropy along the alignment?
Section titled “How do I plot entropy along the alignment?”In the desktop app, export the entropy chart as PNG or SVG. From the command line, plot entropy
against position from the positions table; positions without support have no entropy (NA)
and should stay gaps, not zeros. See
Plot entropy along the alignment.
Can I run DiMA from Python or R?
Section titled “Can I run DiMA from Python or R?”Yes, as a command, then read its tables or JSON (Read the tables in R and Python). In Python:
import subprocesssubprocess.run(["dima", "analyze", "-i", "spike.fasta", "--tsv-dir", "tables"], check=True)In R:
stopifnot(system2("dima", c("analyze", "-i", "spike.fasta", "--tsv-dir", "tables")) == 0)There is no Python or R package. Rust programs can use the dima_core library, the one both the
command-line tool and the desktop app are built on.
Results and versions
Section titled “Results and versions”Why do my results differ from the paper or from dima-cli 5.x?
Section titled “Why do my results differ from the paper or from dima-cli 5.x?”Comparison with the paper reproduces the paper’s results, and Differences from DiMA v5.0.9 lists every deliberate difference from 5.x with its reason. For example, the default support threshold is 100, as in the paper, where 5.x used 30.
Will updating DiMA change my results?
Section titled “Will updating DiMA change my results?”Only where the changelog says so under “Methodology”. Each version gives byte-identical results for the same input and options on every platform and with any number of threads, and every result file records the version that produced it (Comparing versions).
How exact are the numbers?
Section titled “How exact are the numbers?”Exact to far more digits than any analysis needs, but not to the last digit. Like any
floating-point program, DiMA rounds. Its values are accurate to about 14 significant digits on
alignments of thousands of sequences, and to at least 10 at 17.5 million sequences per
position (the opt-in Chao–Wang–Jost estimator to about 15 digits at any size). The error is
at least
How long will an analysis take, and how much memory does it need?
Section titled “How long will an analysis take, and how much memory does it need?”The benchmark report linked from Benchmarks gives measured times and
memory for the paper’s datasets and larger alignments; memory grows with the diversity of the alignment, not with the number of
sequences (Large alignments). With -v, DiMA prints the time of
each phase and the peak memory at the end of a run.
Can I use DiMA on a cluster, or in Snakemake or Nextflow?
Section titled “Can I use DiMA on a cluster, or in Snakemake or Nextflow?”Yes: Run on clusters and in pipelines covers batch schedulers, thread counts, exit codes and workflow managers. A Bioconda recipe will be submitted (Install DiMA); there is no Galaxy tool yet.
Where can I get help or report a bug?
Section titled “Where can I get help or report a bug?”Ask questions in GitHub Discussions and
report bugs in GitHub Issues; search
both first, as your question may already have an answer. The bug form asks for the version, the
command and, if you can share it, the run report (--run-report), which records how the run went
without user or host names.
How do I cite DiMA?
Section titled “How do I cite DiMA?”Cite the paper and the version you used: dima cite prints both, and
dima cite --from results.json prints a methods paragraph and every reference of that run. See
Citing DiMA.
What licence does DiMA have?
Section titled “What licence does DiMA have?”The MIT licence. dima --licenses prints the licences of DiMA and of the components built into
it.
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 ↩︎ 1 2
- Cock PJA, Antao T, Chang JT, Chapman BA, Cox CJ, Dalke A, Friedberg I, Hamelryck T, Kauff F, Wilczynski B, de Hoon MJL. Biopython: freely available Python tools for computational molecular biology and bioinformatics. Bioinformatics. 2009;25(11):1422-1423. doi:10.1093/bioinformatics/btp163 ↩︎
- 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 ↩︎
- 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 ↩︎
- 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 4