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 .
Command-line reference
This page is generated from the definitions dima itself parses, so it always matches dima --help for this version. Run dima <command> --help for the same text in a terminal; -h shows one-line summaries.
| Exit status | Meaning |
|---|---|
0 | Success (also when a reader of standard output, such as head, stops early) |
1 | Internal error (a bug; please report it) |
2 | Usage error (invalid options) |
3 | Input/output or system error (missing file, no permission, disk full, a thread the system refused) |
4 | Invalid input data (not an aligned FASTA, unequal lengths, invalid characters in strict mode) |
130, 143, 129 | Interrupted by SIGINT (Ctrl-C), SIGTERM or SIGHUP; unfinished outputs are removed, never left partial |
DiMA quantifies the diversity of viral protein or nucleotide alignments: for every k-mer position it counts the distinct k-mers, estimates their Shannon entropy with a correction for sample size, classifies variants into Index, Major, Minor and Unique motifs, and reports their incidence, optionally stratified by FASTA header metadata. Conserved stretches (historically conserved sequences) are reported separately.
References: Tharanga et al. 2025, doi:10.1093/bib/bbae607
dima [OPTIONS] [COMMAND]Options
Section titled “Options”--licenses
Section titled “--licenses”Print the licences of DiMA and its components, and exit
Global options
Section titled “Global options”--color <WHEN>
Section titled “--color <WHEN>”Controls when to use color
- Values:
auto,always,never - Default:
auto
-q, --quiet (repeatable)
Section titled “-q, --quiet (repeatable)”Print errors only (no warnings, no summary line).
-v, --verbose (repeatable)
Section titled “-v, --verbose (repeatable)”Print progress milestones and a performance report (-v); debugging details (-vv). DIMA_LOG accepts a tracing filter such as ‘dima_core=debug’.
dima analyze
Section titled “dima analyze”Analyse an alignment
dima analyze [OPTIONS]-i, --input <FASTA>
Section titled “-i, --input <FASTA>”Aligned FASTA file (plain, .gz, .bz2 or .zst; ’-’ or omitted = standard input)
-a, --alphabet <ALPHABET>
Section titled “-a, --alphabet <ALPHABET>”Sequence alphabet. ‘auto’ detects it from the first records with Easel’s rules (as in HMMER), which make no false calls and otherwise ask for this option. T and U are folded to the alphabet’s letter; lower case is folded to upper case. Symbols: gaps - . _, missing ~ ?, stops * $ ^, frameshift #, and ambiguity codes (protein X B J Z; nucleotide R Y K M S W B D H V N X I) exclude the k-mers that contain them; protein U (selenocysteine) and O (pyrrolysine) are residues.
References: Eddy 2011, doi:10.1371/journal.pcbi.1002195; Cornish-Bowden 1985, doi:10.1093/nar/13.9.3021; Los Alamos HIV Sequence Database 2009, https://www.hiv.lanl.gov/content/sequence/HelpDocs/IUPAC.html; Los Alamos HIV Sequence Database 2024, https://www.hiv.lanl.gov/content/sequence/GENE_CUTTER/cutter-help.html; Böck et al. 1991, doi:10.1111/j.1365-2958.1991.tb00722.x; Srinivasan et al. 2002, doi:10.1126/science.1069588
- Values:
auto,protein,dna,rna - Default:
auto
--validation <MODE>
Section titled “--validation <MODE>”How characters outside the alphabet are handled. ‘strict’ stops at the first one with its record, line and column; ‘permissive’ excludes the k-mers that contain them and reports one aggregated warning; ‘report’ is permissive and also prints the table of every character found. Structural problems (no FASTA, unequal lengths, NUL bytes) always stop the run. Default: strict.
- Values:
strict,permissive,report
Method
Section titled “Method”-k, --kmer-length <K>
Section titled “-k, --kmer-length <K>”Length k of the overlapping windows (k-mers). Default: 9 for proteins (the length of peptides presented by HLA class I molecules) and 27 for DNA/RNA (the codons of a 9-mer). Any value from 1 to the alignment length is accepted.
References: Tharanga et al. 2025, doi:10.1093/bib/bbae607; Falk et al. 1991, doi:10.1038/351290a0; Rammensee 1993, doi:10.1146/annurev.immunol.11.1.213
-s, --support-threshold <T>
Section titled “-s, --support-threshold <T>”Support threshold T. A position’s support is the number of sequences with a valid k-mer there. Positions with support above T are eligible: they enter the summary statistics, and the ‘dima’ estimator corrects their entropy for sample size. Positions with support 0 (NS), below T (LS) or equal to T (ELS) are labelled and excluded from the summaries; with ‘dima’ LS and ELS keep their observed entropy. NS has no entropy (null, NA), where the paper assigns a pseudo-entropy of 0: a value that was not observed is missing, not zero. Default: 100, as in the paper.
References: Tharanga et al. 2025, Methods, doi:10.1093/bib/bbae607; Rubin 1976, doi:10.1093/biomet/63.3.581; Silverman et al. 2020, doi:10.1016/j.csbj.2020.09.014
--estimator <ESTIMATOR>
Section titled “--estimator <ESTIMATOR>”Entropy estimator. ‘dima’ is the paper’s correction: entropies of subsamples of R% of the sequences (R is every multiple of 5 from 50 to 95 that is at least 100*T/N, plus 100%) are regressed on 1/n and the intercept is the estimate; positions with support up to T keep the observed entropy. It is the intercept expected over the paper’s random with-replacement subsampling, computed exactly, so results are reproducible bit for bit; it is the limit of averaging many random subsets, as in the original method. ‘chao-wang-jost’ (the least biased estimator in its authors’ comparison) and ‘miller-madow’ (which adds (D - 1)/(2N ln 2)) apply to every position with at least 2 sequences; ‘raw’ is the observed (plug-in) entropy everywhere. Default: dima.
References: Tharanga et al. 2025, Fig. 2, doi:10.1093/bib/bbae607; Shannon 1948, doi:10.1002/j.1538-7305.1948.tb01338.x; Rao 1945; Blackwell 1947, doi:10.1214/aoms/1177730497; Khan et al. 2017, doi:10.1186/s12920-017-0301-2; Chao et al. 2013, doi:10.1111/2041-210X.12108; Miller 1955; Paninski 2003, doi:10.1162/089976603321780272
- Values:
dima,chao-wang-jost,miller-madow,raw
--min-coverage <X>
Section titled “--min-coverage <X>”Flag positions whose estimated sample coverage (the probability that one more sequence carries an already-seen k-mer) is below this value, between 0 and 1. Coverage is always reported; this only adds the flag and a warning.
References: Chao & Jost 2012, Eq. 4a, doi:10.1890/11-1952.1
Metadata
Section titled “Metadata”--query-name <NAME>
Section titled “--query-name <NAME>”Name of the analysed protein or gene. Default: the input file name without its FASTA and compression extensions; ‘Unknown Protein/DNA/RNA’ for standard input.
--header-format <FIELDS>
Section titled “--header-format <FIELDS>”Names of the ’|‘-separated fields of the FASTA headers, e.g. ‘Accession|Host|Country|Year’. Variants are then counted per value of each field. Values are cleaned (invisible characters removed, white space trimmed, Unicode NFC) and empty values get the fill value.
References: Tharanga et al. 2025, doi:10.1093/bib/bbae607; UAX #15, https://www.unicode.org/reports/tr15/tr15-57.html; Phillips 2021, https://www.w3.org/TR/2021/NOTE-charmod-norm-20210811/
--metadata-fields <FIELDS>
Section titled “--metadata-fields <FIELDS>”The header fields to stratify variants by (default: all fields of —header-format), e.g. ‘Host|Year’. Identifier-like fields (such as accessions) multiply the size of the results; DiMA warns about them.
--header-fillna <VALUE>
Section titled “--header-fillna <VALUE>”Value used for empty header fields and for headers whose field count differs from —header-format (permissive mode). Default: Unknown.
Output
Section titled “Output”-o, --output <PATH>
Section titled “-o, --output <PATH>”Write the results here (’-’ = standard output). The format follows -O or the file extension: .json, .jsonl/.ndjson or .tsv/.tab, optionally followed by .gz or .zst for compression. Without -o or —tsv-dir (with ‘dima analyze’, also —hcs-output), JSON goes to standard output. Files are replaced atomically.
-O, --output-format <FORMAT>
Section titled “-O, --output-format <FORMAT>”Format of -o: ‘json’ (complete results with provenance), ‘jsonl’ (one position per line) or ‘tsv’ (one table; choose it with —table). Must agree with the file extension.
- Values:
json,jsonl,tsv
--table <TABLE>
Section titled “--table <TABLE>”The table written by -O tsv: positions, variants, metadata or hcs. Tables are tidy (one row per observation), tab-separated with RFC 4180 quoting, and use NA for undefined values.
References: Wickham 2014, doi:10.18637/jss.v059.i10; Broman & Woo 2018, doi:10.1080/00031305.2017.1375989; RFC 4180, doi:10.17487/RFC4180
- Values:
positions,variants,metadata,hcs
--tsv-dir <DIR>
Section titled “--tsv-dir <DIR>”Write all four tables to this directory (created if needed) as <name>.positions.tsv, <name>.variants.tsv, <name>.metadata.tsv and <name>.hcs.tsv.
--pretty
Section titled “--pretty”Indent JSON output (it is compact by default, and indented when written to a terminal).
--run-report <PATH>
Section titled “--run-report <PATH>”Also write a run report here (JSON): version and build target, the command (file names only), status, start and end time (UTC), threads and where their number came from, platform, time per phase, CPU time, peak memory, and the size and SHA-256 of the input and every output. It is separate from the results, which stay identical from run to run, and holds no host or user names and no paths.
References: Taschuk & Wilson 2017, Rule 10, doi:10.1371/journal.pcbi.1005412; Khan et al. 2019, doi:10.1093/gigascience/giz095; Leo et al. 2024, doi:10.1371/journal.pone.0309210
Conserved sequences
Section titled “Conserved sequences”--hcs-output <PATH>
Section titled “--hcs-output <PATH>”Also write the historically conserved sequences here (.json or .tsv, optionally .gz or .zst). Consecutive positions whose most common (Index) k-mer reaches —hcs-min-incidence are joined when the k-mers overlap or abut; regions that include positions with support at most T are flagged, and each region reports the exact 95% Clopper-Pearson lower bound of its conservation.
References: Tharanga et al. 2025, doi:10.1093/bib/bbae607; Abd Raman et al. 2020, doi:10.7717/peerj.7954; Hu et al. 2013, doi:10.1371/journal.pone.0059994; Clopper & Pearson 1934, doi:10.1093/biomet/26.4.404
--hcs-min-incidence <PERCENT>
Section titled “--hcs-min-incidence <PERCENT>”Minimum Index incidence (%) of the positions that form conserved sequences, above 50 and at most 100 (above 50% the Index k-mer is unique). Compared exactly. Default: 100, the paper’s (every sequence with a valid k-mer has the Index).
References: Tharanga et al. 2025, Methods, doi:10.1093/bib/bbae607
--hcs-eligible-only
Section titled “--hcs-eligible-only”Build conserved sequences from positions with support above T only; positions with support at most T end a region instead of being flagged.
References: Hu et al. 2013, doi:10.1371/journal.pone.0059994; Castresana 2000, doi:10.1093/oxfordjournals.molbev.a026334
-t, --threads <N>
Section titled “-t, --threads <N>”Worker threads. Default: RAYON_NUM_THREADS if set, otherwise the CPUs this process may use, limited to the CPUs granted by Slurm, PBS, SGE or LSF when running under one. Results do not depend on the number of threads.
--progress <WHEN>
Section titled “--progress <WHEN>”How progress is shown on standard error. ‘auto’: on a terminal that can redraw a line, one line updated in place; elsewhere nothing, or plain lines with -v. ‘plain’: appended lines, one per phase and the progress at most every 10 seconds (at each 10%) and at least once a minute; recommended with screen readers, which read every update of a redrawn line, and for log files. ‘off’: nothing. -q always hides progress. Also DIMA_PROGRESS (for example DIMA_PROGRESS=plain in a shell profile).
- Values:
auto,plain,off - Default:
auto - Environment:
DIMA_PROGRESS
Global options (--color, -q, -v) apply to every subcommand; see dima.
dima view
Section titled “dima view”Convert results (JSON) to JSON, JSONL or TSV
dima view [OPTIONS] --input <RESULTS>Options
Section titled “Options”-i, --input <RESULTS>
Section titled “-i, --input <RESULTS>”Results written by `dima analyze` (JSON, optionally .gz or .zst; ’-’ = standard input)
-o, --output <PATH>
Section titled “-o, --output <PATH>”Write the results here (’-’ = standard output). The format follows -O or the file extension: .json, .jsonl/.ndjson or .tsv/.tab, optionally followed by .gz or .zst for compression. Without -o or —tsv-dir (with ‘dima analyze’, also —hcs-output), JSON goes to standard output. Files are replaced atomically.
-O, --output-format <FORMAT>
Section titled “-O, --output-format <FORMAT>”Format of -o: ‘json’ (complete results with provenance), ‘jsonl’ (one position per line) or ‘tsv’ (one table; choose it with —table). Must agree with the file extension.
- Values:
json,jsonl,tsv
--table <TABLE>
Section titled “--table <TABLE>”The table written by -O tsv: positions, variants, metadata or hcs. Tables are tidy (one row per observation), tab-separated with RFC 4180 quoting, and use NA for undefined values.
References: Wickham 2014, doi:10.18637/jss.v059.i10; Broman & Woo 2018, doi:10.1080/00031305.2017.1375989; RFC 4180, doi:10.17487/RFC4180
- Values:
positions,variants,metadata,hcs
--tsv-dir <DIR>
Section titled “--tsv-dir <DIR>”Write all four tables to this directory (created if needed) as <name>.positions.tsv, <name>.variants.tsv, <name>.metadata.tsv and <name>.hcs.tsv.
--pretty
Section titled “--pretty”Indent JSON output (it is compact by default, and indented when written to a terminal).
Global options (--color, -q, -v) apply to every subcommand; see dima.
dima hcs
Section titled “dima hcs”Compute historically conserved sequences from results
dima hcs [OPTIONS] --input <RESULTS>Options
Section titled “Options”-i, --input <RESULTS>
Section titled “-i, --input <RESULTS>”Results written by `dima analyze` (JSON, optionally .gz or .zst; ’-’ = standard input)
--hcs-min-incidence <PERCENT>
Section titled “--hcs-min-incidence <PERCENT>”Minimum Index incidence (%) of the positions that form conserved sequences, above 50 and at most 100 (above 50% the Index k-mer is unique). Compared exactly. Default: 100, the paper’s (every sequence with a valid k-mer has the Index).
References: Tharanga et al. 2025, Methods, doi:10.1093/bib/bbae607
--hcs-eligible-only
Section titled “--hcs-eligible-only”Build conserved sequences from positions with support above T only; positions with support at most T end a region instead of being flagged.
References: Hu et al. 2013, doi:10.1371/journal.pone.0059994; Castresana 2000, doi:10.1093/oxfordjournals.molbev.a026334
-o, --output <PATH>
Section titled “-o, --output <PATH>”Write the regions here (’-’ = standard output, the default)
-O, --output-format <FORMAT>
Section titled “-O, --output-format <FORMAT>”Format (default: from the extension, else JSON)
- Values:
json,tsv
--pretty
Section titled “--pretty”Indent JSON output
Global options (--color, -q, -v) apply to every subcommand; see dima.
dima cite
Section titled “dima cite”Print how to cite DiMA (and, with —from, the references of a run)
dima cite [OPTIONS]Options
Section titled “Options”--format <FORMAT>
Section titled “--format <FORMAT>”Output format
- Values:
text,bibtex,ris,cff - Default:
text
--from <FILE>
Section titled “--from <FILE>”Results of a run, and/or the conserved sequences computed from it (repeat the option): print a methods text and the references of the methods used
Global options (--color, -q, -v) apply to every subcommand; see dima.
dima completions
Section titled “dima completions”Print a shell completion script
dima completions [OPTIONS] <SHELL>Options
Section titled “Options”<SHELL>
Section titled “<SHELL>”The shell
- Values:
bash,elvish,fish,powershell,zsh
Global options (--color, -q, -v) apply to every subcommand; see dima.