Skip to main content

Module output

Module output 

Source
Expand description

Writing and reading results (D10, D22, D28, D31, D50, D61; findings E2, E11, F4, P4).

  • JSON (canonical, complete): compact by default or indented with pretty; always ends with a newline. Every number is finite (checked before writing: JSON has no NaN).
  • JSONL: one position per line (Nextclade’s NDJSON convention); the provenance and summaries live only in the JSON.
  • TSV: the tidy tables of tsv::Table.
  • .gz and .zst outputs are compressed; the format comes from the extension (compound and case-insensitive: x.JSONL.ZST) unless given explicitly.
  • read_results reads plain, gzip or Zstandard results JSON (detected by content) and rejects other schema major versions with a clear message. Errors reading the file are I/O errors (exit 3); corrupt or truncated compressed data is invalid input (exit 4).

Re-exports§

pub use tsv::NA;
pub use tsv::Table;
pub use tsv::write_table;

Modules§

tsv
Tidy tab-separated tables (D22, D50): one observation per row, one variable per column (Wickham 2014; Broman & Woo 2018), a header row, RFC 4180 minimal quoting with a tab delimiter, NA for undefined values, and floating-point numbers in their shortest round-trip form.

Structs§

Sink
An output being written; see the module documentation.
Written
What a committed sink wrote.

Enums§

Document
A DiMA JSON document of either kind.
OutputCompression
Stream compression of an output.
OutputFormat
Serialisation format of an output.
Target
Where output goes.

Functions§

check_finite
Checks that every floating-point value of the results is finite.
check_finite_hcs
Rejects non-finite numbers in conserved-sequence results.
destination_of
The file an output to path is written to: symbolic links followed one at a time, dangling ones included (the link’s target is created), and descriptor aliases such as /dev/stdout kept as given. Two outputs with the same destination would replace each other.
detect
Format and compression implied by a file name’s extensions (case-insensitive): an optional .gz/.zst after .json, .jsonl/.ndjson or .tsv/.tab. None when the name has no recognised format extension.
file_stem
A file-name-safe version of a query name, for output file names (--tsv-dir, the desktop app’s exports): characters other than letters, digits, ., - and _ become _; leading and trailing dots and underscores are removed (no hidden files); dima if nothing is left.
read_document
Reads a results or conserved-sequences JSON file, whichever it is (told apart by the keys DiMA writes first).
read_hcs
Reads a conserved-sequences JSON file (written by dima hcs or --hcs-output).
read_results
Reads a results JSON file (plain, gzip or Zstandard, detected by content); - reads standard input.
read_results_cancellable
read_results that stops with DimaError::Cancelled soon after cancel is set (a front end no longer wants the file, which can be gigabytes).
remove_temporaries
Removes the temporary files of every sink still being written. For front ends that must exit immediately (a second interrupt) and cannot unwind: the destinations are left as they were.
write_hcs_json
Writes HCS results as JSON, followed by a newline.
write_json
Writes the results as JSON (compact or indented), followed by a newline.
write_jsonl
Writes one JSON object per position, one per line.
write_tsv
Writes a TSV table.