Skip to content

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.

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.

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.

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.

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

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.

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.

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.

Yes, as a command, then read its tables or JSON (Read the tables in R and Python). In Python:

import subprocess
subprocess.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.

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.

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

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 10 10 times smaller than the sampling error of the estimate. Numerical accuracy has the measurements.

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.

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.

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.

The MIT licence. dima --licenses prints the licences of DiMA and of the components built into it.

  • 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