Skip to main content

dima_core/
model.rs

1//! Typed analysis results and their JSON representation (`schemas/results.schema.json`).
2//!
3//! Key names follow DiMA (Tharanga et al. 2025) so existing knowledge of the tool carries over;
4//! enumerations serialise to DiMA's strings. Quantities that are undefined are `null`, never a
5//! sentinel: entropy at positions without support, ratios with a zero denominator, extrema of an
6//! empty set. The output is deterministic: no timestamps, no absolute paths, a fixed key order.
7
8use std::fmt;
9
10use serde::de::{self, MapAccess, Visitor};
11use serde::ser::SerializeMap;
12use serde::{Deserialize, Deserializer, Serialize, Serializer};
13
14use crate::config::{Alphabet, Estimator, Param, ValidationMode};
15use crate::diagnostics::Diagnostic;
16
17/// Version of the results and HCS JSON schemas (SemVer: a reader accepts the same major).
18pub const SCHEMA_VERSION: &str = "1.0.0";
19
20// ---------------------------------------------------------------------------------------------
21// Per-position vocabulary
22// ---------------------------------------------------------------------------------------------
23
24/// Low-support class of a position with support *N* and threshold *T* (Tharanga et al. 2025):
25/// no support (N = 0), low support (0 < N < T), equal to the threshold (N = T). Positions with
26/// N > T are *eligible* and carry no label.
27#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
28pub enum SupportLabel {
29    /// No support: no sequence has a valid k-mer here.
30    #[serde(rename = "NS")]
31    NoSupport,
32    /// Low support: fewer sequences than the threshold.
33    #[serde(rename = "LS")]
34    Low,
35    /// Equal to the threshold.
36    #[serde(rename = "ELS")]
37    EqualToThreshold,
38}
39
40impl SupportLabel {
41    /// The paper's abbreviation.
42    #[must_use]
43    pub const fn as_str(self) -> &'static str {
44        match self {
45            Self::NoSupport => "NS",
46            Self::Low => "LS",
47            Self::EqualToThreshold => "ELS",
48        }
49    }
50}
51
52/// The method that produced a position's `entropy`.
53#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
54#[serde(rename_all = "snake_case")]
55pub enum EntropyMethod {
56    /// The paper's rarefaction-regression correction (exact expectation).
57    Dima,
58    /// Chao et al. (2013).
59    ChaoWangJost,
60    /// Miller–Madow.
61    MillerMadow,
62    /// Plug-in (observed) entropy.
63    PlugIn,
64    /// No support: entropy is undefined.
65    NotEstimable,
66}
67
68impl EntropyMethod {
69    /// Serialised name.
70    #[must_use]
71    pub const fn as_str(self) -> &'static str {
72        match self {
73            Self::Dima => "dima",
74            Self::ChaoWangJost => "chao_wang_jost",
75            Self::MillerMadow => "miller_madow",
76            Self::PlugIn => "plug_in",
77            Self::NotEstimable => "not_estimable",
78        }
79    }
80}
81
82/// Why the requested estimator fell back to the plug-in entropy.
83#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
84#[serde(rename_all = "snake_case")]
85pub enum EntropyFallback {
86    /// `dima`: support N ≤ T, so the paper reports the observed entropy.
87    SupportAtOrBelowThreshold,
88    /// `dima`: fewer than five rarefaction points (DiMA v5.0.9's minimum).
89    TooFewPoints,
90    /// `dima`: all subsample sizes are equal, so no regression line exists.
91    DegenerateRegression,
92    /// Miller–Madow / Chao–Wang–Jost: a single observation (N = 1), entropy 0.
93    SingleObservation,
94}
95
96impl EntropyFallback {
97    /// Serialised name.
98    #[must_use]
99    pub const fn as_str(self) -> &'static str {
100        match self {
101            Self::SupportAtOrBelowThreshold => "support_at_or_below_threshold",
102            Self::TooFewPoints => "too_few_points",
103            Self::DegenerateRegression => "degenerate_regression",
104            Self::SingleObservation => "single_observation",
105        }
106    }
107}
108
109/// Diversity motif of a k-mer variant (Hu et al. 2013; Tharanga et al. 2025).
110#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
111pub enum Motif {
112    /// The most common variant (count > 1; ties are all Index).
113    Index,
114    /// The most common of the remaining non-unique variants (ties are all Major).
115    Major,
116    /// Any other variant seen more than once.
117    Minor,
118    /// A variant seen exactly once.
119    Unique,
120}
121
122impl Motif {
123    /// Short form used by DiMA: `I`, `Ma`, `Mi`, `U`.
124    #[must_use]
125    pub const fn short(self) -> &'static str {
126        match self {
127            Self::Index => "I",
128            Self::Major => "Ma",
129            Self::Minor => "Mi",
130            Self::Unique => "U",
131        }
132    }
133
134    /// Long form: `Index`, `Major`, `Minor`, `Unique`.
135    #[must_use]
136    pub const fn long(self) -> &'static str {
137        match self {
138            Self::Index => "Index",
139            Self::Major => "Major",
140            Self::Minor => "Minor",
141            Self::Unique => "Unique",
142        }
143    }
144}
145
146/// Counts of each value of each stratified header field among the sequences carrying a
147/// variant, in `--header-format` order with values sorted by their UTF-8 bytes.
148///
149/// Serialised as an object of objects: `{"Host": {"Camel": 3, "Human": 2}}`.
150#[derive(Clone, Debug, Default, PartialEq, Eq)]
151pub struct Metadata(pub Vec<FieldCounts>);
152
153/// Value counts of one header field.
154#[derive(Clone, Debug, Default, PartialEq, Eq)]
155pub struct FieldCounts {
156    /// Field name.
157    pub field: String,
158    /// `(value, count)` pairs.
159    pub values: Vec<(String, u64)>,
160}
161
162struct Pairs<'a>(&'a [(String, u64)]);
163
164impl Serialize for Pairs<'_> {
165    fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
166        let mut m = s.serialize_map(Some(self.0.len()))?;
167        for (k, v) in self.0 {
168            m.serialize_entry(k, v)?;
169        }
170        m.end()
171    }
172}
173
174impl Serialize for Metadata {
175    fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
176        let mut m = s.serialize_map(Some(self.0.len()))?;
177        for f in &self.0 {
178            m.serialize_entry(&f.field, &Pairs(&f.values))?;
179        }
180        m.end()
181    }
182}
183
184/// Deserialises a JSON object into ordered pairs, preserving document order.
185struct OrderedMap<V>(Vec<(String, V)>);
186
187impl<'de, V: Deserialize<'de>> Deserialize<'de> for OrderedMap<V> {
188    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
189        struct V2<V>(std::marker::PhantomData<V>);
190        impl<'de, V: Deserialize<'de>> Visitor<'de> for V2<V> {
191            type Value = OrderedMap<V>;
192            fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
193                f.write_str("an object")
194            }
195            fn visit_map<A: MapAccess<'de>>(self, mut a: A) -> Result<Self::Value, A::Error> {
196                let mut v = Vec::with_capacity(a.size_hint().unwrap_or(0));
197                while let Some(entry) = a.next_entry::<String, V>()? {
198                    v.push(entry);
199                }
200                Ok(OrderedMap(v))
201            }
202        }
203        d.deserialize_map(V2(std::marker::PhantomData))
204    }
205}
206
207impl<'de> Deserialize<'de> for Metadata {
208    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
209        let fields = OrderedMap::<OrderedMap<u64>>::deserialize(d)?;
210        Ok(Self(
211            fields
212                .0
213                .into_iter()
214                .map(|(field, values)| FieldCounts {
215                    field,
216                    values: values.0,
217                })
218                .collect(),
219        ))
220    }
221}
222
223/// One distinct k-mer at a position.
224#[derive(Clone, Debug, PartialEq)]
225pub struct Variant {
226    /// The k-mer, upper case, in the resolved alphabet.
227    pub sequence: String,
228    /// Number of sequences carrying it.
229    pub count: u64,
230    /// `count / support × 100`.
231    pub incidence: f64,
232    /// Diversity motif.
233    pub motif: Motif,
234    /// Header-field value counts; `null` when no header format was given.
235    pub metadata: Option<Metadata>,
236}
237
238impl Serialize for Variant {
239    fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
240        let mut m = s.serialize_map(Some(6))?;
241        m.serialize_entry("sequence", &self.sequence)?;
242        m.serialize_entry("count", &self.count)?;
243        m.serialize_entry("incidence", &self.incidence)?;
244        m.serialize_entry("motif_short", self.motif.short())?;
245        m.serialize_entry("motif_long", &self.motif)?;
246        m.serialize_entry("metadata", &self.metadata)?;
247        m.end()
248    }
249}
250
251impl<'de> Deserialize<'de> for Variant {
252    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
253        #[derive(Deserialize)]
254        struct Raw {
255            sequence: String,
256            count: u64,
257            incidence: f64,
258            motif_short: String,
259            motif_long: Motif,
260            metadata: Option<Metadata>,
261        }
262        let r = Raw::deserialize(d)?;
263        if r.motif_short != r.motif_long.short() {
264            return Err(de::Error::custom(format!(
265                "motif_short {:?} does not match motif_long {:?}",
266                r.motif_short,
267                r.motif_long.long()
268            )));
269        }
270        Ok(Self {
271            sequence: r.sequence,
272            count: r.count,
273            incidence: r.incidence,
274            motif: r.motif_long,
275            metadata: r.metadata,
276        })
277    }
278}
279
280/// Results for one k-mer position.
281#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
282pub struct PositionResult {
283    /// 1-based alignment column of the k-mer's first residue.
284    pub position: u64,
285    /// Low-support class; `null` for eligible positions (support > T).
286    pub low_support: Option<SupportLabel>,
287    /// Number of sequences with a valid k-mer here (*N*).
288    pub support: u64,
289    /// Number of distinct non-Index variants (DiMA's definition).
290    pub distinct_variants_count: u64,
291    /// Entropy in bits from `entropy_method`; `null` without support.
292    pub entropy: Option<f64>,
293    /// Observed (plug-in) entropy in bits; `null` without support.
294    pub observed_entropy: Option<f64>,
295    /// Method that produced `entropy`.
296    pub entropy_method: EntropyMethod,
297    /// Why the requested estimator was not used, if it was not.
298    pub entropy_fallback: Option<EntropyFallback>,
299    /// Non-Index variant types per 100 non-Index sequences; `null` when there are none.
300    pub distinct_variants_incidence: Option<f64>,
301    /// Non-Index sequences per 100 supporting sequences; `null` without support.
302    pub total_variants_incidence: Option<f64>,
303    /// Estimated sample coverage (Chao & Jost 2012); `null` when support < 2.
304    pub sample_coverage: Option<f64>,
305    /// Whether coverage is below `--min-coverage`; `null` when not requested or not estimable.
306    pub below_min_coverage: Option<bool>,
307    /// Variants ordered by count (descending), then sequence.
308    pub diversity_motifs: Vec<Variant>,
309}
310
311// ---------------------------------------------------------------------------------------------
312// Summaries
313// ---------------------------------------------------------------------------------------------
314
315/// An entropy extremum: the first (lowest) position attaining it and how many positions do.
316#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
317pub struct Extremum {
318    /// 1-based position of the first position with this value.
319    pub position: u64,
320    /// The value, in bits.
321    pub entropy: f64,
322    /// Number of positions with exactly this value (≥ 1).
323    pub tied_position_count: u64,
324}
325
326/// Number of positions in each support class.
327#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
328pub struct SupportLabelCounts {
329    /// N = 0.
330    #[serde(rename = "NS")]
331    pub no_support: u64,
332    /// 0 < N < T.
333    #[serde(rename = "LS")]
334    pub low: u64,
335    /// N = T.
336    #[serde(rename = "ELS")]
337    pub equal_to_threshold: u64,
338    /// N > T.
339    pub eligible: u64,
340}
341
342/// The summary over all positions with DiMA v5.0.9's rule (positions without support count as
343/// 0 bits; low-support positions contribute their observed entropy).
344#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
345pub struct AllPositionsSummary {
346    /// The averaging rule, in words.
347    pub rule: String,
348    /// Number of positions averaged.
349    pub position_count: u64,
350    /// Mean entropy; `null` when there are no positions.
351    pub average_entropy: Option<f64>,
352    /// Lowest entropy (first position, tie count).
353    pub lowest_entropy: Option<Extremum>,
354    /// Highest entropy (first position, tie count).
355    pub highest_entropy: Option<Extremum>,
356}
357
358/// Sample-coverage summary (Chao & Jost 2012).
359#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
360pub struct CoverageSummary {
361    /// Positions with support ≥ 2, where coverage is defined.
362    pub evaluated: u64,
363    /// Lowest coverage.
364    pub min: Option<f64>,
365    /// Mean coverage.
366    pub mean: Option<f64>,
367    /// The `--min-coverage` threshold, if given.
368    pub min_coverage: Option<f64>,
369    /// Positions below the threshold, if one was given.
370    pub below_min_count: Option<u64>,
371}
372
373// ---------------------------------------------------------------------------------------------
374// Provenance
375// ---------------------------------------------------------------------------------------------
376
377/// Name and version of the producing tool.
378#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
379pub struct ToolInfo {
380    /// `dima`.
381    pub name: String,
382    /// SemVer version.
383    pub version: String,
384}
385
386/// Every parameter with its value and origin.
387#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
388pub struct Parameters {
389    /// Sequence alphabet.
390    pub alphabet: Param<Alphabet>,
391    /// k-mer length.
392    pub kmer_length: Param<u64>,
393    /// Support threshold *T*.
394    pub support_threshold: Param<u64>,
395    /// Entropy estimator.
396    pub estimator: Param<Estimator>,
397    /// Validation mode.
398    pub validation: Param<ValidationMode>,
399    /// Minimum sample coverage, if any.
400    pub min_coverage: Param<Option<f64>>,
401    /// Query (protein or gene) name.
402    pub query_name: Param<String>,
403    /// Header field names, if any.
404    pub header_format: Param<Option<Vec<String>>>,
405    /// Stratified header fields, if any.
406    pub metadata_fields: Param<Option<Vec<String>>>,
407    /// Fill value for empty or mismatched header fields.
408    pub header_fill: Param<String>,
409}
410
411/// How the alphabet was determined.
412#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
413#[serde(rename_all = "snake_case")]
414pub enum AlphabetMethod {
415    /// Detected from the data (Easel's rules; Eddy 2011).
416    Detected,
417    /// Given by the user.
418    User,
419}
420
421/// Alphabet provenance.
422#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
423pub struct AlphabetInfo {
424    /// The alphabet used.
425    pub resolved: Alphabet,
426    /// How it was chosen.
427    pub method: AlphabetMethod,
428    /// Records examined by the detector.
429    pub records_examined: u64,
430    /// Residue letters examined by the detector.
431    pub residues_examined: u64,
432    /// T (in RNA) or U (in DNA) letters folded to the alphabet's spelling.
433    pub t_u_folded: u64,
434    /// Why the data contradict an explicit alphabet, if they do.
435    pub contradiction: Option<String>,
436}
437
438/// Compression of the input.
439#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
440#[serde(rename_all = "snake_case")]
441pub enum Compression {
442    /// Plain text.
443    None,
444    /// gzip or BGZF.
445    Gzip,
446    /// bzip2.
447    Bzip2,
448    /// Zstandard.
449    Zstd,
450}
451
452/// A content checksum.
453#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
454pub struct Checksum {
455    /// Algorithm (`sha-256`).
456    #[serde(rename = "type")]
457    pub kind: String,
458    /// Lower-case hexadecimal digest.
459    pub value: String,
460}
461
462/// Identity of the analysed input (D47): name, size and checksum of the bytes as stored.
463#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
464pub struct InputInfo {
465    /// File name without directories, or `-` for standard input.
466    pub name: String,
467    /// Size of the stored (possibly compressed) bytes.
468    pub size_bytes: u64,
469    /// Checksum of the stored bytes.
470    pub checksum: Checksum,
471    /// Compression detected from the content.
472    pub compression: Compression,
473}
474
475/// Class of a sequence byte (see the documentation's symbol tables).
476#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
477#[serde(rename_all = "snake_case")]
478pub enum ByteClass {
479    /// A residue of the alphabet.
480    Residue,
481    /// Alignment gap (`-`, `.`, `_`).
482    Gap,
483    /// Missing data (`~`, `?`).
484    Missing,
485    /// Ambiguity code (IUPAC).
486    Ambiguity,
487    /// Stop codon (`*`, `$`, `^`).
488    Stop,
489    /// Frameshift (`#`).
490    Frameshift,
491    /// Whitespace inside a sequence line (ignored).
492    Whitespace,
493    /// Not valid for the alphabet.
494    Unknown,
495}
496
497impl ByteClass {
498    /// Serialised name.
499    #[must_use]
500    pub const fn as_str(self) -> &'static str {
501        match self {
502            Self::Residue => "residue",
503            Self::Gap => "gap",
504            Self::Missing => "missing",
505            Self::Ambiguity => "ambiguity",
506            Self::Stop => "stop",
507            Self::Frameshift => "frameshift",
508            Self::Whitespace => "whitespace",
509            Self::Unknown => "unknown",
510        }
511    }
512}
513
514/// Occurrences of one byte value in sequence lines.
515#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
516pub struct CharacterCount {
517    /// The character, when the byte is a visible ASCII character (`!` to `~`); `None` for the
518    /// space, control bytes and bytes above 127.
519    #[serde(rename = "char")]
520    pub character: Option<String>,
521    /// The byte value.
522    pub byte: u8,
523    /// Its class under the resolved alphabet (before case folding).
524    pub class: ByteClass,
525    /// Occurrences.
526    pub count: u64,
527}
528
529/// Whitespace found inside sequence lines.
530#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
531pub struct WhitespaceCounts {
532    /// Lines with trailing whitespace.
533    pub trailing: u64,
534    /// Lines with whitespace between residues.
535    pub interior: u64,
536}
537
538/// Code points removed from header values, by code point.
539#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
540pub struct CodePointCount {
541    /// `U+XXXX`.
542    pub code_point: String,
543    /// Occurrences.
544    pub count: u64,
545}
546
547/// Header-value cleaning statistics (D59).
548#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
549pub struct HeaderCleaning {
550    /// Unicode version of the character data used.
551    pub unicode_version: String,
552    /// Values with leading or trailing white space removed.
553    pub trimmed: u64,
554    /// Invisible (format and control) code points removed.
555    pub invisible_removed: Vec<CodePointCount>,
556    /// Values changed by NFC normalisation.
557    pub nfc_changed: u64,
558    /// Stratified values replaced by the fill value: empty values, and every stratified field of
559    /// a header with the wrong number of fields (the same count as `run.metadata.fill_uses`).
560    pub fill_uses: u64,
561}
562
563/// Input validation statistics.
564#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
565pub struct ValidationInfo {
566    /// Validation mode.
567    pub mode: ValidationMode,
568    /// Records read.
569    pub records: u64,
570    /// Lower-case residue letters folded to upper case.
571    pub lowercase_folded: u64,
572    /// Whitespace inside sequence lines.
573    pub whitespace: WhitespaceCounts,
574    /// Every byte value seen in sequence lines, by byte.
575    pub characters: Vec<CharacterCount>,
576    /// Occurrences of characters of class `unknown`.
577    pub unknown_total: u64,
578    /// Header bytes replaced because they were not valid UTF-8.
579    pub header_utf8_replacements: u64,
580    /// Header-value cleaning; `null` when headers were not parsed.
581    pub header_cleaning: Option<HeaderCleaning>,
582}
583
584/// A header whose field count differs from the header format.
585#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
586pub struct HeaderMismatch {
587    /// 1-based record number.
588    pub record: u64,
589    /// 1-based line number.
590    pub line: u64,
591    /// The header line (without `>`).
592    pub header: String,
593    /// Expected number of fields.
594    pub expected: u64,
595    /// Fields found.
596    pub found: u64,
597}
598
599/// Header mismatches: the total and the first ones in full.
600#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
601pub struct Mismatches {
602    /// Total mismatched headers.
603    pub count: u64,
604    /// The first mismatches (at most 20).
605    pub first: Vec<HeaderMismatch>,
606}
607
608/// Header-metadata provenance (present when a header format was given).
609#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
610pub struct MetadataInfo {
611    /// Header field names.
612    pub fields: Vec<String>,
613    /// Fields variants are stratified by.
614    pub stratified: Vec<String>,
615    /// Records examined for the field statistics behind the metadata diagnostics.
616    pub probe_records: u64,
617    /// Mismatched headers.
618    pub mismatches: Mismatches,
619    /// Stratified values replaced by the fill value: empty values, and every stratified field of
620    /// a header with the wrong number of fields.
621    pub fill_uses: u64,
622}
623
624/// Settings of the paper's rarefaction-regression correction as implemented (D51, D55).
625#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
626pub struct Rarefaction {
627    /// Subsample grid: `paper_fig2`, the grid of the paper's Fig. 2 with the step and start
628    /// rounding of DiMA v5.0.9 (R % from max(50, ⌈100·T/N⌉ rounded up to a multiple of 5) to 95
629    /// in steps of 5, plus 100%).
630    pub grid: String,
631    /// Subsample size: `ceil` (⌈R·N/100⌉).
632    pub size_rounding: String,
633    /// Grid start rounding: `ceil_to_5`.
634    pub start_rounding: String,
635    /// `expected_with_replacement`: the exact expectation of with-replacement resampling.
636    pub sampling: String,
637    /// Minimum number of points for the regression (5).
638    pub min_points: u64,
639}
640
641/// Entropy settings.
642#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
643pub struct EntropyInfo {
644    /// Estimator requested.
645    pub estimator: Estimator,
646    /// Logarithm base (2: bits).
647    pub log_base: u64,
648    /// Rarefaction settings (estimator `dima` only).
649    pub rarefaction: Option<Rarefaction>,
650}
651
652/// A reference cited by the methods used in the run.
653#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
654pub struct Reference {
655    /// Citation key.
656    pub key: String,
657    /// Full reference text.
658    pub citation: String,
659    /// DOI, if any.
660    pub doi: Option<String>,
661    /// URL, for references without a DOI.
662    pub url: Option<String>,
663}
664
665impl From<&crate::citations::Citation> for Reference {
666    fn from(c: &crate::citations::Citation) -> Self {
667        Self {
668            key: c.key.to_owned(),
669            citation: c.text(),
670            doi: c.doi.map(str::to_owned),
671            url: c.url.map(str::to_owned),
672        }
673    }
674}
675
676impl Reference {
677    /// The reference for a citation key.
678    ///
679    /// # Panics
680    /// If the key is unknown (keys used by the library are checked by tests).
681    #[must_use]
682    pub fn of(key: &str) -> Self {
683        crate::citations::by_key(key)
684            .unwrap_or_else(|| panic!("unknown citation key {key:?}"))
685            .into()
686    }
687}
688
689/// Provenance of a run.
690#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
691pub struct RunInfo {
692    /// Producing tool.
693    pub tool: ToolInfo,
694    /// Parameters.
695    pub parameters: Parameters,
696    /// Alphabet determination.
697    pub alphabet: AlphabetInfo,
698    /// Alignment length (columns).
699    pub alignment_length: u64,
700    /// Input identity.
701    pub input: InputInfo,
702    /// Input validation.
703    pub validation: ValidationInfo,
704    /// Header metadata; `null` without a header format.
705    pub metadata: Option<MetadataInfo>,
706    /// Entropy settings.
707    pub entropy: EntropyInfo,
708    /// Conditions worth knowing about.
709    pub diagnostics: Vec<Diagnostic>,
710    /// The publication, this software and the references of the methods used.
711    pub references: Vec<Reference>,
712}
713
714/// The complete results of an analysis.
715#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
716pub struct Results {
717    /// Schema version ([`SCHEMA_VERSION`]).
718    pub schema_version: String,
719    /// Query (protein or gene) name.
720    pub query_name: String,
721    /// Number of sequences.
722    pub sequence_count: u64,
723    /// Support threshold *T*.
724    pub support_threshold: u64,
725    /// k-mer length.
726    pub kmer_length: u64,
727    /// Positions with support ≤ T (NS + LS + ELS), as in DiMA.
728    pub low_support_count: u64,
729    /// Mean entropy over eligible positions (support > T); `null` when there are none.
730    pub average_entropy: Option<f64>,
731    /// Lowest entropy over eligible positions.
732    pub lowest_entropy: Option<Extremum>,
733    /// Highest entropy over eligible positions.
734    pub highest_entropy: Option<Extremum>,
735    /// Number of k-mer positions (alignment length − k + 1).
736    pub position_count: u64,
737    /// Positions with support > T.
738    pub eligible_position_count: u64,
739    /// Positions per support class.
740    pub support_label_counts: SupportLabelCounts,
741    /// Summary over all positions with DiMA v5.0.9's rule.
742    pub all_positions_summary: AllPositionsSummary,
743    /// Sample-coverage summary.
744    pub coverage_summary: CoverageSummary,
745    /// Provenance.
746    pub run: RunInfo,
747    /// Per-position results, in position order.
748    pub results: Vec<PositionResult>,
749}
750
751// ---------------------------------------------------------------------------------------------
752// Historically conserved sequences
753// ---------------------------------------------------------------------------------------------
754
755/// Which positions may contribute to conserved regions.
756#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
757#[serde(rename_all = "snake_case")]
758pub enum HcsEligibility {
759    /// Any position whose Index variant meets the threshold (the paper's rule; low-support
760    /// positions are flagged).
761    AllPositions,
762    /// Only positions with support above the threshold; NS, LS and ELS positions break regions.
763    SupportGtThreshold,
764}
765
766/// The results an HCS computation was derived from.
767#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
768pub struct HcsSource {
769    /// Query name.
770    pub query_name: String,
771    /// k-mer length.
772    pub kmer_length: u64,
773    /// Support threshold *T*.
774    pub support_threshold: u64,
775    /// Number of sequences.
776    pub sequence_count: u64,
777    /// Checksum of the analysed input.
778    pub input_checksum: Checksum,
779    /// Version of the tool that produced the results.
780    pub tool_version: String,
781    /// Schema version of the results.
782    pub results_schema_version: String,
783}
784
785/// Confidence-bound settings.
786#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
787pub struct HcsConfidence {
788    /// `clopper_pearson` (exact, two-sided).
789    pub method: String,
790    /// Confidence level (0.95).
791    pub level: f64,
792}
793
794/// Parameters of an HCS computation.
795#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
796pub struct HcsParameters {
797    /// Minimum Index incidence, per cent, in (50, 100].
798    pub threshold_percent: crate::config::Percent,
799    /// `overlap_or_adjacent`: consecutive qualifying k-mers join when they overlap or abut and
800    /// agree on the overlap.
801    pub merge_rule: String,
802    /// Which positions may contribute.
803    pub eligibility: HcsEligibility,
804    /// Confidence bound on conservation.
805    pub confidence: HcsConfidence,
806}
807
808/// A position contributing to a conserved region.
809#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
810pub struct HcsMember {
811    /// 1-based position.
812    pub position: u64,
813    /// The Index k-mer.
814    pub kmer: String,
815    /// Sequences carrying it.
816    pub count: u64,
817    /// Support of the position.
818    pub support: u64,
819    /// Index incidence, per cent.
820    pub incidence: f64,
821    /// Exact 95% Clopper–Pearson lower bound of the Index proportion (0–1).
822    pub conservation_lower_bound_95: f64,
823}
824
825/// One historically conserved sequence.
826#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
827pub struct HcsRegion {
828    /// 1-based region number.
829    pub id: u64,
830    /// First alignment column.
831    pub start_column: u64,
832    /// Last alignment column.
833    pub end_column: u64,
834    /// Columns spanned.
835    pub length: u64,
836    /// The conserved sequence.
837    pub sequence: String,
838    /// Lowest Index incidence among members, per cent.
839    pub min_incidence: f64,
840    /// Lowest support among members.
841    pub min_support: u64,
842    /// Lowest Clopper–Pearson lower bound among members (0–1).
843    pub conservation_lower_bound_95: f64,
844    /// Positions from the first to the last member with support ≤ T (members or not).
845    pub low_support_positions: Vec<u64>,
846    /// `true` when `low_support_positions` is not empty.
847    pub flagged: bool,
848    /// `true` when the previous region ended because its overlap disagreed with this one.
849    pub split_from_previous: bool,
850    /// Contributing positions.
851    pub members: Vec<HcsMember>,
852}
853
854/// Historically conserved sequences of a results file.
855#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
856pub struct HcsResults {
857    /// Schema version ([`SCHEMA_VERSION`]).
858    pub schema_version: String,
859    /// The tool that computed the regions.
860    pub tool: ToolInfo,
861    /// The results they were computed from.
862    pub source: HcsSource,
863    /// Parameters.
864    pub parameters: HcsParameters,
865    /// Number of regions.
866    pub region_count: u64,
867    /// Regions with low-support positions.
868    pub flagged_region_count: u64,
869    /// Regions in column order.
870    pub regions: Vec<HcsRegion>,
871    /// Conditions worth knowing about.
872    pub diagnostics: Vec<Diagnostic>,
873    /// References of the method.
874    pub references: Vec<Reference>,
875}
876
877#[cfg(test)]
878mod tests {
879    use super::*;
880
881    fn variant(seq: &str, count: u64, motif: Motif, metadata: Option<Metadata>) -> Variant {
882        Variant {
883            sequence: seq.into(),
884            count,
885            incidence: 50.0,
886            motif,
887            metadata,
888        }
889    }
890
891    #[test]
892    fn variant_json_shape_and_round_trip() {
893        let md = Metadata(vec![
894            FieldCounts {
895                field: "Year".into(),
896                values: vec![("2015".into(), 2), ("2012".into(), 1)],
897            },
898            FieldCounts {
899                field: "Host".into(),
900                values: vec![("Human".into(), 3)],
901            },
902        ]);
903        let v = variant("SVKSACIEV", 3, Motif::Index, Some(md));
904        let json = serde_json::to_string(&v).unwrap();
905        assert_eq!(
906            json,
907            r#"{"sequence":"SVKSACIEV","count":3,"incidence":50.0,"motif_short":"I","motif_long":"Index","metadata":{"Year":{"2015":2,"2012":1},"Host":{"Human":3}}}"#
908        );
909        let back: Variant = serde_json::from_str(&json).unwrap();
910        assert_eq!(back, v, "document order is preserved");
911        let bad = json.replace(r#""motif_short":"I""#, r#""motif_short":"U""#);
912        assert!(serde_json::from_str::<Variant>(&bad).is_err());
913        let plain = variant("A", 1, Motif::Unique, None);
914        assert!(
915            serde_json::to_string(&plain)
916                .unwrap()
917                .ends_with(r#""motif_short":"U","motif_long":"Unique","metadata":null}"#)
918        );
919    }
920
921    #[test]
922    fn enum_spellings() {
923        let s = |v: &dyn erased::Ser| v.json();
924        assert_eq!(s(&SupportLabel::NoSupport), r#""NS""#);
925        assert_eq!(s(&SupportLabel::Low), r#""LS""#);
926        assert_eq!(s(&SupportLabel::EqualToThreshold), r#""ELS""#);
927        assert_eq!(s(&EntropyMethod::NotEstimable), r#""not_estimable""#);
928        assert_eq!(s(&EntropyMethod::PlugIn), r#""plug_in""#);
929        assert_eq!(
930            s(&EntropyFallback::SupportAtOrBelowThreshold),
931            r#""support_at_or_below_threshold""#
932        );
933        assert_eq!(s(&Compression::Zstd), r#""zstd""#);
934        assert_eq!(s(&ByteClass::Frameshift), r#""frameshift""#);
935        assert_eq!(s(&AlphabetMethod::Detected), r#""detected""#);
936        for m in [
937            EntropyMethod::Dima,
938            EntropyMethod::ChaoWangJost,
939            EntropyMethod::MillerMadow,
940            EntropyMethod::PlugIn,
941            EntropyMethod::NotEstimable,
942        ] {
943            assert_eq!(s(&m), format!("\"{}\"", m.as_str()));
944        }
945        for f in [
946            EntropyFallback::SupportAtOrBelowThreshold,
947            EntropyFallback::TooFewPoints,
948            EntropyFallback::DegenerateRegression,
949            EntropyFallback::SingleObservation,
950        ] {
951            assert_eq!(s(&f), format!("\"{}\"", f.as_str()));
952        }
953        let counts = SupportLabelCounts {
954            no_support: 1,
955            low: 2,
956            equal_to_threshold: 3,
957            eligible: 4,
958        };
959        assert_eq!(
960            serde_json::to_string(&counts).unwrap(),
961            r#"{"NS":1,"LS":2,"ELS":3,"eligible":4}"#
962        );
963    }
964
965    /// Minimal object-safe serialisation helper for the table-driven test above.
966    mod erased {
967        pub trait Ser {
968            fn json(&self) -> String;
969        }
970        impl<T: serde::Serialize> Ser for T {
971            fn json(&self) -> String {
972                serde_json::to_string(self).unwrap()
973            }
974        }
975    }
976}