Skip to content

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 statusMeaning
0Success (also when a reader of standard output, such as head, stops early)
1Internal error (a bug; please report it)
2Usage error (invalid options)
3Input/output or system error (missing file, no permission, disk full, a thread the system refused)
4Invalid input data (not an aligned FASTA, unequal lengths, invalid characters in strict mode)
130, 143, 129Interrupted 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]

Print the licences of DiMA and its components, and exit

Controls when to use color

  • Values: auto, always, never
  • Default: auto

Print errors only (no warnings, no summary line).

Print progress milestones and a performance report (-v); debugging details (-vv). DIMA_LOG accepts a tracing filter such as ‘dima_core=debug’.

Analyse an alignment

dima analyze [OPTIONS]

Aligned FASTA file (plain, .gz, .bz2 or .zst; ’-’ or omitted = standard input)

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

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

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

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

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

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

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.

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/

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.

Value used for empty header fields and for headers whose field count differs from —header-format (permissive mode). Default: Unknown.

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.

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

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

Write all four tables to this directory (created if needed) as <name>.positions.tsv, <name>.variants.tsv, <name>.metadata.tsv and <name>.hcs.tsv.

Indent JSON output (it is compact by default, and indented when written to a terminal).

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

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

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

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

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.

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.

Convert results (JSON) to JSON, JSONL or TSV

dima view [OPTIONS] --input <RESULTS>

Results written by `dima analyze` (JSON, optionally .gz or .zst; ’-’ = standard input)

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.

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

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

Write all four tables to this directory (created if needed) as <name>.positions.tsv, <name>.variants.tsv, <name>.metadata.tsv and <name>.hcs.tsv.

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.

Compute historically conserved sequences from results

dima hcs [OPTIONS] --input <RESULTS>

Results written by `dima analyze` (JSON, optionally .gz or .zst; ’-’ = standard input)

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

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

Write the regions here (’-’ = standard output, the default)

Format (default: from the extension, else JSON)

  • Values: json, tsv

Indent JSON output

Global options (--color, -q, -v) apply to every subcommand; see dima.

Print how to cite DiMA (and, with —from, the references of a run)

dima cite [OPTIONS]

Output format

  • Values: text, bibtex, ris, cff
  • Default: text

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.

Print a shell completion script

dima completions [OPTIONS] <SHELL>

The shell

  • Values: bash, elvish, fish, powershell, zsh

Global options (--color, -q, -v) apply to every subcommand; see dima.