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 .
Glossary
Each term is defined briefly here and in full on the page it links to. Names in code are the
fields of the JSON and TSV outputs or the options of the
command line.
Alignment and k-mers
Section titled “Alignment and k-mers”Alignment column
Section titled “Alignment column”One column of the multiple sequence alignment: the residue, or gap, that each sequence has at that place. Columns are numbered from 1. See the input.
Position
Section titled “Position”The window of k columns that starts at a given column; a position is numbered by its first column, so an alignment of L columns has L − k + 1 positions. See k-mer positions.
k-mer and k
Section titled “k-mer and k”A k-mer is the k characters of one sequence inside a position’s window. k is set with -k
(default 9 for proteins and 27 for nucleotides). See
choose the k-mer length.
Valid k-mer
Section titled “Valid k-mer”A k-mer whose characters are all residues. A gap, missing-data symbol, ambiguity code, stop or frameshift symbol anywhere in the window makes it invalid, and that sequence then does not count at that position. See valid k-mers and support.
Variant
Section titled “Variant”A distinct valid k-mer at a position, with the number of sequences that carry it.
Support
Section titled “Support”Support
Section titled “Support”The number of sequences with a valid k-mer at a position (N, support).
Support threshold
Section titled “Support threshold”The value T that each position’s support is compared with (-s, default 100, the paper’s value).
See the support threshold.
Eligible position
Section titled “Eligible position”A position with support above the support threshold. Only eligible positions receive the paper’s corrected entropy and enter the summary statistics.
NS, LS and ELS
Section titled “NS, LS and ELS”The labels (low_support) of positions that are not eligible: NS, no support (N = 0); LS, low
support (N below T); ELS, support equal to the threshold (N = T).
Entropy
Section titled “Entropy”Observed entropy
Section titled “Observed entropy”The Shannon entropy, in bits, of a position’s variant counts as observed (observed_entropy). It
underestimates the entropy of the population, more so with fewer sequences. See
observed entropy.
Corrected entropy
Section titled “Corrected entropy”The entropy reported as entropy: by default the paper’s sample-size correction at eligible
positions, and the observed entropy at the other positions with support. See
the paper’s correction.
Estimator
Section titled “Estimator”The method behind the reported entropy (--estimator): dima (the paper’s correction, the
default), chao-wang-jost, miller-madow or raw. Each position records the method used
(entropy_method). See alternative estimators.
Entropy fallback
Section titled “Entropy fallback”Why a position’s entropy was computed with another method than the one requested
(entropy_fallback), for example because its support is at or below the support threshold.
Sample coverage
Section titled “Sample coverage”The estimated probability that one more sequence would carry a k-mer already seen at that position
(sample_coverage). Low coverage means that much of the diversity there has probably not been
sampled. See sample coverage.
Diversity motifs
Section titled “Diversity motifs”Index, Major, Minor and Unique
Section titled “Index, Major, Minor and Unique”The motif of each variant of a position: Index, the most common variant (count above 1); Major, the next most common; Minor, the other variants seen more than once; Unique, the variants seen once. See motif classes.
Incidence
Section titled “Incidence”A variant’s count as a percentage of the position’s support.
Total variants incidence
Section titled “Total variants incidence”The percentage of a position’s support carried by variants other than the Index.
Distinct variants incidence
Section titled “Distinct variants incidence”The number of distinct non-Index variants as a percentage of the sequences that carry them. See incidences.
Conserved sequences
Section titled “Conserved sequences”Historically conserved sequence (HCS)
Section titled “Historically conserved sequence (HCS)”A region of consecutive positions whose Index variant reaches the threshold incidence
(--hcs-min-incidence, default 100%). See
historically conserved sequences.
Flagged region
Section titled “Flagged region”A conserved region that includes positions with support at or below the support threshold, so that its conservation rests on few sequences. See flagging.
Conservation lower bound
Section titled “Conservation lower bound”The exact 95% Clopper–Pearson lower bound of the Index proportion of a position or region
(conservation_lower_bound_95): how conserved it is at least, given the number of sequences. See
a lower bound on conservation.
Header format
Section titled “Header format”The names of the |-separated fields of the FASTA headers (--header-format). See
describe the headers.
Metadata fields
Section titled “Metadata fields”The header fields per whose values each variant’s sequences are counted (--metadata-fields).
See stratify by header metadata.
Fill value
Section titled “Fill value”The value that replaces an empty header field (--header-fillna, default Unknown).
Validation mode
Section titled “Validation mode”What happens to characters outside the alphabet (--validation): strict stops the run,
permissive excludes the k-mers that contain them, and report also lists every character
found. See validate input characters.
Query name
Section titled “Query name”The name of the analysed protein or gene in the results (query_name): --query-name, or the
input file name without its extensions. See the query name.
Results
Section titled “Results”Diagnostic
Section titled “Diagnostic”A condition that did not stop the analysis but that you should know about, reported once with a code, a count, examples and a hint. See Diagnostics.
Provenance
Section titled “Provenance”The run object of the results: the version, every parameter and where it came from, the input’s
checksum, what reading found, the diagnostics and the references, with nothing that varies between
runs. See run.
Run report
Section titled “Run report”An optional, separate JSON file (--run-report) that records how a run went: times, threads,
memory, platform and exit status, without user or host names. See
keep a run report.
Schema version
Section titled “Schema version”The version of a JSON output’s format (schema_version). Its major number changes when the
meaning of existing fields changes. See JSON outputs.