goat_cli/report/
table.rs

1//! Turn GoaT report responses (JSON) into tables, for `--format tsv|csv`.
2//!
3//! Each function takes the whole `/report` response.
4
5use serde_json::{json, Value};
6
7use crate::error::{Error, ErrorKind, Result};
8use crate::output::{epoch_millis_to_date, Table};
9use crate::report::report::ReportType;
10
11fn unexpected(what: &str) -> Error {
12    Error::new(ErrorKind::Report(format!(
13        "unexpected report response: {what} missing (please report if you get this error!)"
14    )))
15}
16
17/// The report body, e.g. `response.report.report.histogram`.
18fn body<'a>(response: &'a Value, name: &str) -> Result<&'a Value> {
19    let body = &response["report"]["report"][name];
20    if body.is_null() {
21        return Err(unexpected(name));
22    }
23    Ok(body)
24}
25
26fn array<'a>(value: &'a Value, what: &str) -> Result<&'a Vec<Value>> {
27    value.as_array().ok_or_else(|| unexpected(what))
28}
29
30/// Show a bucket edge: dates come as milliseconds since the epoch.
31fn edge(value: &Value, value_type: &str) -> Value {
32    match (value_type, value.as_i64()) {
33        ("date", Some(millis)) => json!(epoch_millis_to_date(millis)),
34        _ => value.clone(),
35    }
36}
37
38/// One axis of a histogram or scatter.
39///
40/// Numeric and date axes have bucket edges, so bin `i` is
41/// `[buckets[i], buckets[i + 1])` and the last count (past the last edge)
42/// has no bin. Keyword axes have one bucket per value, so bin `i` is just
43/// `buckets[i]`, with a trailing `null` bucket.
44struct Axis<'a> {
45    field: &'a str,
46    value_type: &'a str,
47    buckets: &'a [Value],
48    keyword: bool,
49}
50
51impl<'a> Axis<'a> {
52    fn new(field: &'a str, value_type: &'a str, buckets: &'a [Value]) -> Self {
53        let keyword = value_type == "keyword" || buckets.iter().any(Value::is_string);
54        Self {
55            field,
56            value_type,
57            buckets,
58            keyword,
59        }
60    }
61
62    /// The column names: `<field>` for keywords, else `<field>_from` and
63    /// `<field>_to`.
64    fn columns(&self) -> Vec<String> {
65        if self.keyword {
66            vec![self.field.to_string()]
67        } else {
68            vec![format!("{}_from", self.field), format!("{}_to", self.field)]
69        }
70    }
71
72    /// Whether count `i` falls in a real bin (not the open-ended last
73    /// count of a numeric axis, or the `null` bucket of a keyword axis).
74    fn has_bin(&self, i: usize) -> bool {
75        if self.keyword {
76            self.buckets.get(i).map_or(false, |b| !b.is_null())
77        } else {
78            i + 1 < self.buckets.len()
79        }
80    }
81
82    /// The cells for count `i`; open-ended bins have a null edge.
83    fn cells(&self, i: usize) -> Vec<Value> {
84        let edge_at = |j: usize| self.buckets.get(j).map_or(Value::Null, |b| edge(b, self.value_type));
85        if self.keyword {
86            vec![self.buckets.get(i).cloned().unwrap_or(Value::Null)]
87        } else {
88            vec![edge_at(i), edge_at(i + 1)]
89        }
90    }
91
92    /// Error if there are more counts than buckets, which GoaT doesn't send.
93    fn check(&self, counts: usize, what: &str) -> Result<()> {
94        if counts > self.buckets.len() {
95            return Err(unexpected(&format!("{what} (more counts than buckets)")));
96        }
97        Ok(())
98    }
99}
100
101/// Counts outside every bin are always zero; skip them, but keep any that
102/// aren't so no values are lost.
103fn skip(count: &Value, in_bins: bool) -> bool {
104    !in_bins && count.as_u64() == Some(0)
105}
106
107/// The table for a report, other than a newick tree.
108pub fn report_table(report_type: ReportType, response: &Value) -> Result<Table> {
109    match report_type {
110        ReportType::Histogram => histogram_table(response),
111        ReportType::Scatterplot => scatter_table(response),
112        ReportType::Arc => arc_table(response),
113        ReportType::Sources => sources_table(response),
114        ReportType::Newick | ReportType::None => Err(Error::new(ErrorKind::Report(
115            "this report has no table format".to_string(),
116        ))),
117    }
118}
119
120/// One row per bin, with the count, then a count per category (`-c`).
121///
122/// Numeric and date bins are `[<field>_from, <field>_to)`; keyword
123/// histograms have one row per value.
124pub fn histogram_table(response: &Value) -> Result<Table> {
125    let histogram = body(response, "histogram")?;
126    let field = histogram["field"].as_str().unwrap_or("value");
127    let bins = &histogram["histograms"];
128    let buckets = array(&bins["buckets"], "histograms.buckets")?;
129    let counts = array(&bins["allValues"], "histograms.allValues")?;
130    let axis = Axis::new(field, bins["valueType"].as_str().unwrap_or(""), buckets);
131    axis.check(counts.len(), "histograms.allValues")?;
132    let categories = histogram["cats"]
133        .as_array()
134        .map(|cats| cats.iter().filter_map(|c| c["key"].as_str()).collect::<Vec<_>>())
135        .unwrap_or_default();
136
137    let mut header = axis.columns();
138    header.push("count".to_string());
139    header.extend(categories.iter().map(|c| c.to_string()));
140    let mut table = Table::new(&header.iter().map(String::as_str).collect::<Vec<_>>());
141
142    for (i, count) in counts.iter().enumerate() {
143        if skip(count, axis.has_bin(i)) {
144            continue;
145        }
146        let mut row = axis.cells(i);
147        row.push(count.clone());
148        for category in &categories {
149            row.push(bins["byCat"][category].get(i).cloned().unwrap_or(json!(0)));
150        }
151        table.push(row);
152    }
153    Ok(table)
154}
155
156/// One row per cell of the x/y grid: the x bin, the y bin and the count.
157/// Each axis is a value (keyword) or a `_from`/`_to` range, as in
158/// [`histogram_table`].
159pub fn scatter_table(response: &Value) -> Result<Table> {
160    let scatter = body(response, "scatter")?;
161    let bins = &scatter["histograms"];
162    let x = Axis::new(
163        bins["xLabel"].as_str().unwrap_or("x"),
164        bins["valueType"].as_str().unwrap_or(""),
165        array(&bins["buckets"], "histograms.buckets")?,
166    );
167    let y = Axis::new(
168        bins["yLabel"].as_str().unwrap_or("y"),
169        bins["yValueType"].as_str().unwrap_or(""),
170        array(&bins["yBuckets"], "histograms.yBuckets")?,
171    );
172    let grid = array(&bins["allYValues"], "histograms.allYValues")?;
173    x.check(grid.len(), "histograms.allYValues")?;
174
175    let mut header = x.columns();
176    header.extend(y.columns());
177    header.push("count".to_string());
178    let mut table = Table::new(&header.iter().map(String::as_str).collect::<Vec<_>>());
179    for (i, column) in grid.iter().enumerate() {
180        let column = array(column, "histograms.allYValues[]")?;
181        y.check(column.len(), "histograms.allYValues[]")?;
182        for (j, count) in column.iter().enumerate() {
183            if skip(count, x.has_bin(i) && y.has_bin(j)) {
184                continue;
185            }
186            let mut row = x.cells(i);
187            row.extend(y.cells(j));
188            row.push(count.clone());
189            table.push(row);
190        }
191    }
192    Ok(table)
193}
194
195/// A single row: the two queries, their counts and the proportion.
196pub fn arc_table(response: &Value) -> Result<Table> {
197    let arc = body(response, "arc")?;
198    let mut table = Table::new(&["x_query", "y_query", "rank", "x", "y", "proportion"]);
199    table.push(vec![
200        arc["xQuery"]["query"].clone(),
201        arc["yQuery"]["query"].clone(),
202        arc["rank"].clone(),
203        arc["x"].clone(),
204        arc["y"].clone(),
205        arc["arc"].clone(),
206    ]);
207    Ok(table)
208}
209
210/// One row per data source: how many values it provides, for which fields.
211pub fn sources_table(response: &Value) -> Result<Table> {
212    let sources = body(response, "sources")?
213        .as_object()
214        .ok_or_else(|| unexpected("sources"))?;
215    let mut table = Table::new(&["source", "count", "date", "url", "attributes"]);
216    for (name, source) in sources {
217        table.push(vec![
218            json!(name),
219            source["count"].clone(),
220            source["date"].clone(),
221            source["url"].clone(),
222            source["attributes"].clone(),
223        ]);
224    }
225    Ok(table)
226}
227
228#[cfg(test)]
229mod tests {
230    use super::*;
231
232    fn wrap(name: &str, body: Value) -> Value {
233        json!({"status": {"success": true}, "report": {"report": {name: body}}})
234    }
235
236    #[test]
237    fn test_numeric_histogram_with_categories() {
238        let response = wrap("histogram", json!({
239            "field": "genome_size",
240            "cats": [{"key": "scaffold"}, {"key": "chromosome"}],
241            "histograms": {
242                "buckets": [1, 10, 100],
243                "allValues": [5, 2, 0],
244                "valueType": "integer",
245                "byCat": {"scaffold": [4, 1, 0], "chromosome": [1, 1, 0]}
246            }
247        }));
248        let table = histogram_table(&response).unwrap();
249        assert_eq!(table.header, ["genome_size_from", "genome_size_to", "count", "scaffold", "chromosome"]);
250        assert_eq!(table.rows, vec![
251            vec![json!(1), json!(10), json!(5), json!(4), json!(1)],
252            vec![json!(10), json!(100), json!(2), json!(1), json!(1)],
253        ]);
254    }
255
256    #[test]
257    fn test_keyword_histogram() {
258        let response = wrap("histogram", json!({
259            "field": "assembly_level",
260            "histograms": {"buckets": ["scaffold", "chromosome", null], "allValues": [199, 40], "valueType": "keyword"}
261        }));
262        let table = histogram_table(&response).unwrap();
263        assert_eq!(table.header, ["assembly_level", "count"]);
264        assert_eq!(table.rows, vec![vec![json!("scaffold"), json!(199)], vec![json!("chromosome"), json!(40)]]);
265    }
266
267    #[test]
268    fn test_date_histogram_edges_are_dates() {
269        let response = wrap("histogram", json!({
270            "field": "assembly_date",
271            "histograms": {"buckets": [1_293_840_000_000_i64, 1_325_376_000_000_i64], "allValues": [7, 0], "valueType": "date"}
272        }));
273        let table = histogram_table(&response).unwrap();
274        assert_eq!(table.rows, vec![vec![json!("2011-01-01"), json!("2012-01-01"), json!(7)]]);
275    }
276
277    #[test]
278    fn test_scatter_grid() {
279        let response = wrap("scatter", json!({
280            "histograms": {
281                "xLabel": "genome_size", "yLabel": "c_value",
282                "valueType": "integer", "yValueType": "float",
283                "buckets": [1, 2, 3], "yBuckets": [0.5, 1.5],
284                "allYValues": [[4, 0], [6, 0], [0, 0]]
285            }
286        }));
287        let table = scatter_table(&response).unwrap();
288        assert_eq!(table.header, ["genome_size_from", "genome_size_to", "c_value_from", "c_value_to", "count"]);
289        assert_eq!(table.rows, vec![
290            vec![json!(1), json!(2), json!(0.5), json!(1.5), json!(4)],
291            vec![json!(2), json!(3), json!(0.5), json!(1.5), json!(6)],
292        ]);
293    }
294
295    #[test]
296    fn test_scatter_keyword_axis_is_one_column() {
297        // as GoaT sends it: keyword buckets end with null
298        let response = wrap("scatter", json!({
299            "histograms": {
300                "xLabel": "assembly_level", "yLabel": "assembly_span",
301                "valueType": "keyword", "yValueType": "integer",
302                "buckets": ["scaffold", "chromosome", null], "yBuckets": [10, 20, 30],
303                "allYValues": [[1, 2, 0], [0, 3, 0]]
304            }
305        }));
306        let table = scatter_table(&response).unwrap();
307        assert_eq!(table.header, ["assembly_level", "assembly_span_from", "assembly_span_to", "count"]);
308        assert_eq!(table.rows, vec![
309            vec![json!("scaffold"), json!(10), json!(20), json!(1)],
310            vec![json!("scaffold"), json!(20), json!(30), json!(2)],
311            vec![json!("chromosome"), json!(10), json!(20), json!(0)],
312            vec![json!("chromosome"), json!(20), json!(30), json!(3)],
313        ]);
314    }
315
316    #[test]
317    fn test_open_ended_bins_kept_if_not_zero() {
318        let response = wrap("scatter", json!({
319            "histograms": {
320                "xLabel": "x", "yLabel": "y", "valueType": "integer", "yValueType": "integer",
321                "buckets": [1, 2], "yBuckets": [5, 6],
322                "allYValues": [[1, 0], [0, 7]]
323            }
324        }));
325        let rows = scatter_table(&response).unwrap().rows;
326        assert_eq!(rows, vec![
327            vec![json!(1), json!(2), json!(5), json!(6), json!(1)],
328            vec![json!(2), Value::Null, json!(6), Value::Null, json!(7)],
329        ]);
330
331        let response = wrap("histogram", json!({
332            "field": "f", "histograms": {"buckets": [1, 10], "allValues": [5, 2], "valueType": "integer"}
333        }));
334        assert_eq!(histogram_table(&response).unwrap().rows, vec![
335            vec![json!(1), json!(10), json!(5)],
336            vec![json!(10), Value::Null, json!(2)],
337        ]);
338    }
339
340    #[test]
341    fn test_more_counts_than_buckets_is_an_error() {
342        let response = wrap("histogram", json!({
343            "field": "f", "histograms": {"buckets": [1], "allValues": [5, 2, 1], "valueType": "integer"}
344        }));
345        let err = histogram_table(&response).unwrap_err();
346        assert!(err.to_string().contains("more counts than buckets"), "{}", err);
347
348        let response = wrap("scatter", json!({
349            "histograms": {"buckets": [1, 2], "yBuckets": [1], "allYValues": [[1, 2]]}
350        }));
351        assert!(scatter_table(&response).is_err());
352    }
353
354    #[test]
355    fn test_arc_and_sources() {
356        let arc = wrap("arc", json!({
357            "arc": 0.25, "x": 1, "y": 4, "rank": "species",
358            "xQuery": {"query": "tax_tree(Primates) AND assembly_span"}, "yQuery": {"query": "tax_rank(species)"}
359        }));
360        assert_eq!(arc_table(&arc).unwrap().rows, vec![vec![
361            json!("tax_tree(Primates) AND assembly_span"), json!("tax_rank(species)"), json!("species"), json!(1), json!(4), json!(0.25),
362        ]]);
363
364        let sources = wrap("sources", json!({
365            "INSDC": {"count": 7, "date": "2026-10-02", "url": "https://x", "attributes": ["assembly_span"]},
366            "CNGB": {"count": 2, "attributes": ["assembly_level"]}
367        }));
368        let table = sources_table(&sources).unwrap();
369        assert_eq!(table.rows.len(), 2);
370        assert_eq!(table.rows[0][0], json!("CNGB"));
371        assert_eq!(table.rows[0][2], Value::Null);
372    }
373
374    #[test]
375    fn test_unexpected_shape_is_an_error() {
376        let err = histogram_table(&json!({"report": {}})).unwrap_err();
377        assert!(err.to_string().contains("histogram missing"), "{}", err);
378    }
379}