Skip to main content

dima_core/output/
tsv.rs

1//! Tidy tab-separated tables (D22, D50): one observation per row, one variable per column
2//! (Wickham 2014; Broman & Woo 2018), a header row, RFC 4180 minimal quoting with a tab
3//! delimiter, `NA` for undefined values, and floating-point numbers in their shortest
4//! round-trip form.
5
6use std::io::{self, Write};
7
8use crate::model::{HcsResults, Results};
9
10/// The tables DiMA writes.
11#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
12pub enum Table {
13    /// One row per position.
14    Positions,
15    /// One row per (position, variant).
16    Variants,
17    /// One row per (position, variant, field, value).
18    Metadata,
19    /// One row per conserved region.
20    Hcs,
21}
22
23impl Table {
24    /// Every table, in file order.
25    pub const ALL: [Self; 4] = [Self::Positions, Self::Variants, Self::Metadata, Self::Hcs];
26
27    /// Name used in file names (`<base>.<name>.tsv`) and on the command line.
28    #[must_use]
29    pub const fn name(self) -> &'static str {
30        match self {
31            Self::Positions => "positions",
32            Self::Variants => "variants",
33            Self::Metadata => "metadata",
34            Self::Hcs => "hcs",
35        }
36    }
37
38    /// Column names.
39    #[must_use]
40    pub const fn columns(self) -> &'static [&'static str] {
41        match self {
42            Self::Positions => &[
43                "position",
44                "low_support",
45                "support",
46                "distinct_variants_count",
47                "entropy",
48                "observed_entropy",
49                "entropy_method",
50                "entropy_fallback",
51                "distinct_variants_incidence",
52                "total_variants_incidence",
53                "sample_coverage",
54                "below_min_coverage",
55            ],
56            Self::Variants => &[
57                "position",
58                "sequence",
59                "count",
60                "incidence",
61                "motif_short",
62                "motif_long",
63            ],
64            Self::Metadata => &["position", "sequence", "field", "value", "count"],
65            Self::Hcs => &[
66                "region_id",
67                "start_column",
68                "end_column",
69                "length",
70                "min_incidence",
71                "min_support",
72                "conservation_lower_bound_95",
73                "flagged",
74                "low_support_position_count",
75                "sequence",
76            ],
77        }
78    }
79}
80
81/// Missing-value marker.
82pub const NA: &str = "NA";
83
84struct Row<'a> {
85    w: csv::Writer<&'a mut dyn Write>,
86    float: ryu::Buffer,
87    int: String,
88}
89
90impl Row<'_> {
91    fn str(&mut self, s: &str) -> io::Result<()> {
92        self.w.write_field(s).map_err(csv_error)
93    }
94
95    fn int(&mut self, v: u64) -> io::Result<()> {
96        use std::fmt::Write as _;
97        self.int.clear();
98        let _ = write!(self.int, "{v}");
99        self.w.write_field(self.int.as_bytes()).map_err(csv_error)
100    }
101
102    fn float(&mut self, v: Option<f64>) -> io::Result<()> {
103        match v {
104            Some(x) if x.is_finite() => {
105                let s = self.float.format_finite(x);
106                self.w.write_field(s).map_err(csv_error)
107            }
108            _ => self.str(NA),
109        }
110    }
111
112    fn opt_str(&mut self, v: Option<&str>) -> io::Result<()> {
113        self.str(v.unwrap_or(NA))
114    }
115
116    fn opt_bool(&mut self, v: Option<bool>) -> io::Result<()> {
117        self.str(match v {
118            Some(true) => "true",
119            Some(false) => "false",
120            None => NA,
121        })
122    }
123
124    fn end(&mut self) -> io::Result<()> {
125        self.w.write_record(None::<&[u8]>).map_err(csv_error)
126    }
127}
128
129fn csv_error(e: csv::Error) -> io::Error {
130    match e.into_kind() {
131        csv::ErrorKind::Io(e) => e,
132        other => io::Error::other(format!("{other:?}")),
133    }
134}
135
136/// Writes `table` of `results` (and `hcs` for the HCS table) to `out`.
137///
138/// # Errors
139/// I/O errors of `out`; [`io::ErrorKind::InvalidInput`] when the HCS table is requested
140/// without HCS results.
141pub fn write_table(
142    results: &Results,
143    hcs: Option<&HcsResults>,
144    table: Table,
145    out: &mut dyn Write,
146) -> io::Result<()> {
147    write_any(Some(results), hcs, table, out)
148}
149
150/// Writes the HCS table from conserved regions alone.
151///
152/// # Errors
153/// I/O errors of `out`.
154pub fn write_table_hcs(hcs: &HcsResults, out: &mut dyn Write) -> io::Result<()> {
155    write_any(None, Some(hcs), Table::Hcs, out)
156}
157
158fn write_any(
159    results: Option<&Results>,
160    hcs: Option<&HcsResults>,
161    table: Table,
162    out: &mut dyn Write,
163) -> io::Result<()> {
164    let positions: &[crate::model::PositionResult] = results.map_or(&[], |r| &r.results);
165    let w = csv::WriterBuilder::new()
166        .delimiter(b'\t')
167        .quote_style(csv::QuoteStyle::Necessary)
168        .terminator(csv::Terminator::Any(b'\n'))
169        .has_headers(false)
170        .flexible(true)
171        .from_writer(out);
172    let mut row = Row {
173        w,
174        float: ryu::Buffer::new(),
175        int: String::new(),
176    };
177    for c in table.columns() {
178        row.str(c)?;
179    }
180    row.end()?;
181    match table {
182        Table::Positions => {
183            for p in positions {
184                row.int(p.position)?;
185                row.opt_str(p.low_support.map(|l| l.as_str()))?;
186                row.int(p.support)?;
187                row.int(p.distinct_variants_count)?;
188                row.float(p.entropy)?;
189                row.float(p.observed_entropy)?;
190                row.str(p.entropy_method.as_str())?;
191                row.opt_str(p.entropy_fallback.map(|f| f.as_str()))?;
192                row.float(p.distinct_variants_incidence)?;
193                row.float(p.total_variants_incidence)?;
194                row.float(p.sample_coverage)?;
195                row.opt_bool(p.below_min_coverage)?;
196                row.end()?;
197            }
198        }
199        Table::Variants => {
200            for p in positions {
201                for v in &p.diversity_motifs {
202                    row.int(p.position)?;
203                    row.str(&v.sequence)?;
204                    row.int(v.count)?;
205                    row.float(Some(v.incidence))?;
206                    row.str(v.motif.short())?;
207                    row.str(v.motif.long())?;
208                    row.end()?;
209                }
210            }
211        }
212        Table::Metadata => {
213            for p in positions {
214                for v in &p.diversity_motifs {
215                    for f in v.metadata.iter().flat_map(|m| &m.0) {
216                        for (value, n) in &f.values {
217                            row.int(p.position)?;
218                            row.str(&v.sequence)?;
219                            row.str(&f.field)?;
220                            row.str(value)?;
221                            row.int(*n)?;
222                            row.end()?;
223                        }
224                    }
225                }
226            }
227        }
228        Table::Hcs => {
229            let hcs = hcs.ok_or_else(|| {
230                io::Error::new(
231                    io::ErrorKind::InvalidInput,
232                    "the HCS table needs HCS results",
233                )
234            })?;
235            for g in &hcs.regions {
236                row.int(g.id)?;
237                row.int(g.start_column)?;
238                row.int(g.end_column)?;
239                row.int(g.length)?;
240                row.float(Some(g.min_incidence))?;
241                row.int(g.min_support)?;
242                row.float(Some(g.conservation_lower_bound_95))?;
243                row.opt_bool(Some(g.flagged))?;
244                row.int(g.low_support_positions.len() as u64)?;
245                row.str(&g.sequence)?;
246                row.end()?;
247            }
248        }
249    }
250    row.w.flush()
251}