Skip to content

Analyse an alignment

This guide covers the decisions of a typical analysis. Every option is listed in the command-line reference.

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:

Terminal window
dima analyze -i spike.fasta.zst -o spike.json
zcat spike.fasta.gz | dima analyze -o spike.json # standard input
dima analyze -i <(seqkit grep -n -r -p 'Homo sapiens' all.fasta) -o human.json

seqkit (Shen et al. 2016) is used here only as an example of a tool that writes FASTA to a pipe.

Terminal window
dima analyze -i spike.fasta -o spike.json

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

-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:

Terminal window
dima analyze -i spike.fasta -k 15 -o spike.k15.json

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

-s/--support-threshold sets T . Positions with support above T are eligible: their entropy is corrected for sample size (unless the correction cannot be applied there, which 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):

Terminal window
dima analyze -i spike.fasta -s 50 -o spike.T50.json

There is no universally right value. A lower T admits positions with fewer sequences, whose corrected entropy rests on less data; a higher T leaves more positions labelled LS. If T is not below the number of sequences, no position can be eligible and DiMA warns (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.

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:

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

The default, --estimator dima, is the paper’s correction, computed exactly. Three alternatives are available for comparison or sensitivity analyses:

Terminal window
dima analyze -i spike.fasta --estimator chao-wang-jost -o spike.cwj.json
EstimatorWhen to use it
dima (default)Results comparable with the paper and earlier DiMA analyses
chao-wang-jostLowest bias among the estimators in its authors’ comparison (Chao et al. 2013); also corrects positions with support ≤ T
miller-madowThe classical first-order correction (Miller 1955)
rawThe observed entropy, uncorrected

Every position also reports its observed entropy and its sample coverage, whatever the estimator. See Entropy and its correction.

The summary keys at the top of the JSON answer the paper’s questions directly:

Terminal window
jq '{query_name, sequence_count, position_count, eligible_position_count,
average_entropy, lowest_entropy, highest_entropy, support_label_counts}' spike.json

Each 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:

Terminal window
jq -c '[.results[] | select(.low_support == null)]
| sort_by(-.entropy) | .[:5][] | {position, support, entropy}' spike.json

The same data as tables, ready for R or pandas, come from --tsv-dir:

Terminal window
dima analyze -i spike.fasta -o spike.json --tsv-dir tables

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

  • 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