1use 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
17pub const SCHEMA_VERSION: &str = "1.0.0";
19
20#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
28pub enum SupportLabel {
29 #[serde(rename = "NS")]
31 NoSupport,
32 #[serde(rename = "LS")]
34 Low,
35 #[serde(rename = "ELS")]
37 EqualToThreshold,
38}
39
40impl SupportLabel {
41 #[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#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
54#[serde(rename_all = "snake_case")]
55pub enum EntropyMethod {
56 Dima,
58 ChaoWangJost,
60 MillerMadow,
62 PlugIn,
64 NotEstimable,
66}
67
68impl EntropyMethod {
69 #[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#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
84#[serde(rename_all = "snake_case")]
85pub enum EntropyFallback {
86 SupportAtOrBelowThreshold,
88 TooFewPoints,
90 DegenerateRegression,
92 SingleObservation,
94}
95
96impl EntropyFallback {
97 #[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#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
111pub enum Motif {
112 Index,
114 Major,
116 Minor,
118 Unique,
120}
121
122impl Motif {
123 #[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 #[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#[derive(Clone, Debug, Default, PartialEq, Eq)]
151pub struct Metadata(pub Vec<FieldCounts>);
152
153#[derive(Clone, Debug, Default, PartialEq, Eq)]
155pub struct FieldCounts {
156 pub field: String,
158 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
184struct 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#[derive(Clone, Debug, PartialEq)]
225pub struct Variant {
226 pub sequence: String,
228 pub count: u64,
230 pub incidence: f64,
232 pub motif: Motif,
234 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#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
282pub struct PositionResult {
283 pub position: u64,
285 pub low_support: Option<SupportLabel>,
287 pub support: u64,
289 pub distinct_variants_count: u64,
291 pub entropy: Option<f64>,
293 pub observed_entropy: Option<f64>,
295 pub entropy_method: EntropyMethod,
297 pub entropy_fallback: Option<EntropyFallback>,
299 pub distinct_variants_incidence: Option<f64>,
301 pub total_variants_incidence: Option<f64>,
303 pub sample_coverage: Option<f64>,
305 pub below_min_coverage: Option<bool>,
307 pub diversity_motifs: Vec<Variant>,
309}
310
311#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
317pub struct Extremum {
318 pub position: u64,
320 pub entropy: f64,
322 pub tied_position_count: u64,
324}
325
326#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
328pub struct SupportLabelCounts {
329 #[serde(rename = "NS")]
331 pub no_support: u64,
332 #[serde(rename = "LS")]
334 pub low: u64,
335 #[serde(rename = "ELS")]
337 pub equal_to_threshold: u64,
338 pub eligible: u64,
340}
341
342#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
345pub struct AllPositionsSummary {
346 pub rule: String,
348 pub position_count: u64,
350 pub average_entropy: Option<f64>,
352 pub lowest_entropy: Option<Extremum>,
354 pub highest_entropy: Option<Extremum>,
356}
357
358#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
360pub struct CoverageSummary {
361 pub evaluated: u64,
363 pub min: Option<f64>,
365 pub mean: Option<f64>,
367 pub min_coverage: Option<f64>,
369 pub below_min_count: Option<u64>,
371}
372
373#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
379pub struct ToolInfo {
380 pub name: String,
382 pub version: String,
384}
385
386#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
388pub struct Parameters {
389 pub alphabet: Param<Alphabet>,
391 pub kmer_length: Param<u64>,
393 pub support_threshold: Param<u64>,
395 pub estimator: Param<Estimator>,
397 pub validation: Param<ValidationMode>,
399 pub min_coverage: Param<Option<f64>>,
401 pub query_name: Param<String>,
403 pub header_format: Param<Option<Vec<String>>>,
405 pub metadata_fields: Param<Option<Vec<String>>>,
407 pub header_fill: Param<String>,
409}
410
411#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
413#[serde(rename_all = "snake_case")]
414pub enum AlphabetMethod {
415 Detected,
417 User,
419}
420
421#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
423pub struct AlphabetInfo {
424 pub resolved: Alphabet,
426 pub method: AlphabetMethod,
428 pub records_examined: u64,
430 pub residues_examined: u64,
432 pub t_u_folded: u64,
434 pub contradiction: Option<String>,
436}
437
438#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
440#[serde(rename_all = "snake_case")]
441pub enum Compression {
442 None,
444 Gzip,
446 Bzip2,
448 Zstd,
450}
451
452#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
454pub struct Checksum {
455 #[serde(rename = "type")]
457 pub kind: String,
458 pub value: String,
460}
461
462#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
464pub struct InputInfo {
465 pub name: String,
467 pub size_bytes: u64,
469 pub checksum: Checksum,
471 pub compression: Compression,
473}
474
475#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
477#[serde(rename_all = "snake_case")]
478pub enum ByteClass {
479 Residue,
481 Gap,
483 Missing,
485 Ambiguity,
487 Stop,
489 Frameshift,
491 Whitespace,
493 Unknown,
495}
496
497impl ByteClass {
498 #[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#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
516pub struct CharacterCount {
517 #[serde(rename = "char")]
520 pub character: Option<String>,
521 pub byte: u8,
523 pub class: ByteClass,
525 pub count: u64,
527}
528
529#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
531pub struct WhitespaceCounts {
532 pub trailing: u64,
534 pub interior: u64,
536}
537
538#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
540pub struct CodePointCount {
541 pub code_point: String,
543 pub count: u64,
545}
546
547#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
549pub struct HeaderCleaning {
550 pub unicode_version: String,
552 pub trimmed: u64,
554 pub invisible_removed: Vec<CodePointCount>,
556 pub nfc_changed: u64,
558 pub fill_uses: u64,
561}
562
563#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
565pub struct ValidationInfo {
566 pub mode: ValidationMode,
568 pub records: u64,
570 pub lowercase_folded: u64,
572 pub whitespace: WhitespaceCounts,
574 pub characters: Vec<CharacterCount>,
576 pub unknown_total: u64,
578 pub header_utf8_replacements: u64,
580 pub header_cleaning: Option<HeaderCleaning>,
582}
583
584#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
586pub struct HeaderMismatch {
587 pub record: u64,
589 pub line: u64,
591 pub header: String,
593 pub expected: u64,
595 pub found: u64,
597}
598
599#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
601pub struct Mismatches {
602 pub count: u64,
604 pub first: Vec<HeaderMismatch>,
606}
607
608#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
610pub struct MetadataInfo {
611 pub fields: Vec<String>,
613 pub stratified: Vec<String>,
615 pub probe_records: u64,
617 pub mismatches: Mismatches,
619 pub fill_uses: u64,
622}
623
624#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
626pub struct Rarefaction {
627 pub grid: String,
631 pub size_rounding: String,
633 pub start_rounding: String,
635 pub sampling: String,
637 pub min_points: u64,
639}
640
641#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
643pub struct EntropyInfo {
644 pub estimator: Estimator,
646 pub log_base: u64,
648 pub rarefaction: Option<Rarefaction>,
650}
651
652#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
654pub struct Reference {
655 pub key: String,
657 pub citation: String,
659 pub doi: Option<String>,
661 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 #[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#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
691pub struct RunInfo {
692 pub tool: ToolInfo,
694 pub parameters: Parameters,
696 pub alphabet: AlphabetInfo,
698 pub alignment_length: u64,
700 pub input: InputInfo,
702 pub validation: ValidationInfo,
704 pub metadata: Option<MetadataInfo>,
706 pub entropy: EntropyInfo,
708 pub diagnostics: Vec<Diagnostic>,
710 pub references: Vec<Reference>,
712}
713
714#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
716pub struct Results {
717 pub schema_version: String,
719 pub query_name: String,
721 pub sequence_count: u64,
723 pub support_threshold: u64,
725 pub kmer_length: u64,
727 pub low_support_count: u64,
729 pub average_entropy: Option<f64>,
731 pub lowest_entropy: Option<Extremum>,
733 pub highest_entropy: Option<Extremum>,
735 pub position_count: u64,
737 pub eligible_position_count: u64,
739 pub support_label_counts: SupportLabelCounts,
741 pub all_positions_summary: AllPositionsSummary,
743 pub coverage_summary: CoverageSummary,
745 pub run: RunInfo,
747 pub results: Vec<PositionResult>,
749}
750
751#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
757#[serde(rename_all = "snake_case")]
758pub enum HcsEligibility {
759 AllPositions,
762 SupportGtThreshold,
764}
765
766#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
768pub struct HcsSource {
769 pub query_name: String,
771 pub kmer_length: u64,
773 pub support_threshold: u64,
775 pub sequence_count: u64,
777 pub input_checksum: Checksum,
779 pub tool_version: String,
781 pub results_schema_version: String,
783}
784
785#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
787pub struct HcsConfidence {
788 pub method: String,
790 pub level: f64,
792}
793
794#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
796pub struct HcsParameters {
797 pub threshold_percent: crate::config::Percent,
799 pub merge_rule: String,
802 pub eligibility: HcsEligibility,
804 pub confidence: HcsConfidence,
806}
807
808#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
810pub struct HcsMember {
811 pub position: u64,
813 pub kmer: String,
815 pub count: u64,
817 pub support: u64,
819 pub incidence: f64,
821 pub conservation_lower_bound_95: f64,
823}
824
825#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
827pub struct HcsRegion {
828 pub id: u64,
830 pub start_column: u64,
832 pub end_column: u64,
834 pub length: u64,
836 pub sequence: String,
838 pub min_incidence: f64,
840 pub min_support: u64,
842 pub conservation_lower_bound_95: f64,
844 pub low_support_positions: Vec<u64>,
846 pub flagged: bool,
848 pub split_from_previous: bool,
850 pub members: Vec<HcsMember>,
852}
853
854#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
856pub struct HcsResults {
857 pub schema_version: String,
859 pub tool: ToolInfo,
861 pub source: HcsSource,
863 pub parameters: HcsParameters,
865 pub region_count: u64,
867 pub flagged_region_count: u64,
869 pub regions: Vec<HcsRegion>,
871 pub diagnostics: Vec<Diagnostic>,
873 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 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}