goat_cli/record/
mod.rs

1//!
2//! Invoked by calling:
3//! `goat-cli taxon record <args>` or `goat-cli assembly record <args>`
4//!
5//! Fetches whole records from the GoaT `record` endpoint: every field with
6//! its value and sources, and the names and lineage.
7
8use futures::StreamExt;
9use serde_json::{json, Value};
10
11use crate::cli::RecordArgs;
12use crate::client::{concurrency, GoatClient};
13use crate::error::{Error, ErrorKind, Result};
14use crate::output::{Format, Table};
15use crate::utils::url::percent_encode_query_value;
16use crate::utils::utils::taxa_from_input;
17use crate::{IndexType, GOAT_URL, TAXONOMY};
18
19/// Which part of a record to show.
20#[derive(Clone, Copy, Debug, PartialEq, Eq)]
21pub enum RecordView {
22    /// One row per field (the default).
23    Fields,
24    /// Names (taxon) or identifiers (assembly).
25    Names,
26    /// The lineage, from the record up to the root.
27    Lineage,
28}
29
30impl RecordView {
31    /// The view chosen by `args` (clap ensures `--names` and `--lineage`
32    /// aren't both given).
33    pub fn from_args(args: &RecordArgs) -> Self {
34        if args.names {
35            RecordView::Names
36        } else if args.lineage {
37            RecordView::Lineage
38        } else {
39            RecordView::Fields
40        }
41    }
42}
43
44/// Main entry point for `goat-cli <index> record`.
45pub async fn record(args: &RecordArgs, index_type: IndexType) -> Result<()> {
46    let inputs = taxa_from_input(args.taxon.as_deref(), args.file.as_deref(), false)?;
47    let client = GoatClient::new();
48
49    let resolved = futures::stream::iter(inputs.iter().map(|input| {
50        let client = client.clone();
51        async move { resolve_id(&client, input, index_type).await }
52    }))
53    .buffered(concurrency(inputs.len()))
54    .collect::<Vec<_>>()
55    .await
56    .into_iter()
57    .collect::<Result<Vec<_>>>()?;
58
59    // names that match no taxon, or several, are reported and skipped
60    let mut found = Vec::new();
61    let mut problems = Vec::new();
62    for (input, resolution) in inputs.iter().zip(resolved) {
63        match resolution {
64            Resolved::Id(id) => found.push((input, id)),
65            Resolved::Problem(message) => problems.push(message),
66        }
67    }
68    if found.is_empty() && !problems.is_empty() {
69        let message = if problems.len() == 1 {
70            problems.remove(0)
71        } else {
72            format!("none of the names could be resolved:\n\t{}", problems.join("\n\t"))
73        };
74        return Err(Error::new(ErrorKind::GenericCli(message)));
75    }
76    for problem in &problems {
77        eprintln!("Skipping: {}", problem);
78    }
79    let (inputs, ids): (Vec<_>, Vec<_>) = found.into_iter().unzip();
80
81    let urls = ids.iter().map(|id| record_url(id, index_type)).collect::<Vec<_>>();
82    if args.url {
83        for (index, url) in urls.iter().enumerate() {
84            crate::outln!("{}.\tGoaT record API URL: {}", index, url)?;
85        }
86        return Ok(());
87    }
88
89    let responses = futures::stream::iter(urls.iter().map(|url| {
90        let client = client.clone();
91        async move { client.get_json(url).await }
92    }))
93    .buffered(concurrency(urls.len()))
94    .collect::<Vec<_>>()
95    .await;
96
97    let mut records = Vec::new();
98    for (input, response) in inputs.iter().zip(responses) {
99        match found_record(response?) {
100            Some(record) => records.push(record),
101            None => eprintln!("No record found for \"{}\".", input),
102        }
103    }
104
105    match args.format {
106        Format::Json => {
107            crate::outln!("{}", Value::Array(records))?;
108            Ok(())
109        }
110        format => record_table(&records, RecordView::from_args(args), index_type)?.print(format),
111    }
112}
113
114/// The `record` URL for an ID.
115pub fn record_url(id: &str, index_type: IndexType) -> String {
116    format!(
117        "{}record?recordId={}&result={}&taxonomy={}",
118        *GOAT_URL,
119        percent_encode_query_value(id),
120        index_type,
121        *TAXONOMY
122    )
123}
124
125/// What a name resolved to.
126#[derive(Debug, PartialEq, Eq)]
127enum Resolved {
128    /// The record ID.
129    Id(String),
130    /// Why it couldn't be resolved (no match, or several).
131    Problem(String),
132}
133
134/// The record ID for what the user typed. Assembly records are looked up by
135/// accession as given; taxon names are resolved to an NCBI taxon ID, and
136/// must match exactly one taxon. Errors are for failed requests only.
137async fn resolve_id(client: &GoatClient, input: &str, index_type: IndexType) -> Result<Resolved> {
138    if index_type == IndexType::Assembly || input.chars().all(|c| c.is_ascii_digit()) {
139        return Ok(Resolved::Id(input.to_string()));
140    }
141    let url = format!(
142        "{}search?query={}&result=taxon&taxonomy={}&includeEstimates=true&size=10",
143        *GOAT_URL,
144        percent_encode_query_value(&format!("tax_name({})", input)),
145        *TAXONOMY
146    );
147    let response = client.get_json(&url).await?;
148    resolve_from_search(input, &response)
149}
150
151/// Resolve `input` from the `/search` response for `tax_name(input)`.
152fn resolve_from_search(input: &str, response: &Value) -> Result<Resolved> {
153    let matches = response["results"]
154        .as_array()
155        .map(|results| results.iter().map(|r| &r["result"]).collect::<Vec<_>>())
156        .unwrap_or_default();
157    match matches.as_slice() {
158        [only] => only["taxon_id"]
159            .as_str()
160            .map(|id| Resolved::Id(id.to_string()))
161            .ok_or_else(|| Error::new(ErrorKind::Api(format!("no taxon_id for \"{}\"", input)))),
162        [] => Ok(Resolved::Problem(format!(
163            "no taxon found named \"{}\". Try `goat-cli taxon lookup -t \"{}\"`.",
164            input, input
165        ))),
166        several => Ok(Resolved::Problem(format!(
167            "\"{}\" matches several taxa; use a taxon ID instead: {}.",
168            input,
169            several
170                .iter()
171                .map(|r| format!(
172                    "{} ({} {})",
173                    r["taxon_id"].as_str().unwrap_or("?"),
174                    r["taxon_rank"].as_str().unwrap_or("?"),
175                    r["scientific_name"].as_str().unwrap_or("?")
176                ))
177                .collect::<Vec<_>>()
178                .join(", ")
179        ))),
180    }
181}
182
183/// The record in a `/record` response, if one was found.
184fn found_record(mut response: Value) -> Option<Value> {
185    let record = response["records"].get_mut(0)?;
186    if record["found"] != Value::Bool(true) {
187        return None;
188    }
189    Some(record["record"].take())
190}
191
192/// The table of `records` for `view`.
193pub fn record_table(records: &[Value], view: RecordView, index_type: IndexType) -> Result<Table> {
194    let id_column = match index_type {
195        IndexType::Taxon => "taxon_id",
196        IndexType::Assembly => "assembly_id",
197    };
198    let mut table = match (view, index_type) {
199        (RecordView::Fields, _) => Table::new(&[
200            id_column,
201            "scientific_name",
202            "field",
203            "value",
204            "count",
205            "aggregation_source",
206            "aggregation_method",
207            "sources",
208        ]),
209        (RecordView::Names, IndexType::Taxon) => {
210            Table::new(&[id_column, "scientific_name", "name", "class", "source"])
211        }
212        (RecordView::Names, IndexType::Assembly) => {
213            Table::new(&[id_column, "scientific_name", "identifier", "class"])
214        }
215        (RecordView::Lineage, _) => Table::new(&[
216            id_column,
217            "scientific_name",
218            "node_depth",
219            "lineage_taxon_id",
220            "lineage_scientific_name",
221            "lineage_rank",
222        ]),
223    };
224
225    for record in records {
226        let id = record[id_column].clone();
227        let name = record["scientific_name"].clone();
228        match (view, index_type) {
229            (RecordView::Fields, _) => {
230                for (field, attribute) in record["attributes"].as_object().into_iter().flatten() {
231                    table.push(vec![
232                        id.clone(),
233                        name.clone(),
234                        json!(field),
235                        attribute["value"].clone(),
236                        attribute["count"].clone(),
237                        attribute["aggregation_source"].clone(),
238                        attribute["aggregation_method"].clone(),
239                        json!(sources(attribute)),
240                    ]);
241                }
242            }
243            (RecordView::Names, IndexType::Taxon) => {
244                for entry in record["taxon_names"].as_array().into_iter().flatten() {
245                    table.push(vec![
246                        id.clone(),
247                        name.clone(),
248                        entry["name"].clone(),
249                        entry["class"].clone(),
250                        entry["source"].clone(),
251                    ]);
252                }
253            }
254            (RecordView::Names, IndexType::Assembly) => {
255                for entry in record["identifiers"].as_array().into_iter().flatten() {
256                    table.push(vec![
257                        id.clone(),
258                        name.clone(),
259                        entry["identifier"].clone(),
260                        entry["class"].clone(),
261                    ]);
262                }
263            }
264            (RecordView::Lineage, _) => {
265                for node in record["lineage"].as_array().into_iter().flatten() {
266                    table.push(vec![
267                        id.clone(),
268                        name.clone(),
269                        node["node_depth"].clone(),
270                        node["taxon_id"].clone(),
271                        node["scientific_name"].clone(),
272                        node["taxon_rank"].clone(),
273                    ]);
274                }
275            }
276        }
277    }
278    Ok(table)
279}
280
281/// The distinct sources of a field's values: taxon fields list their raw
282/// values, each with a source; assembly fields have a single source.
283fn sources(attribute: &Value) -> Vec<String> {
284    let mut sources: Vec<String> = Vec::new();
285    match attribute["values"].as_array() {
286        Some(values) => {
287            for source in values.iter().filter_map(|v| v["source"].as_str()) {
288                if !sources.iter().any(|s| s == source) {
289                    sources.push(source.to_string());
290                }
291            }
292        }
293        None => sources.extend(attribute["source"].as_str().map(String::from)),
294    }
295    sources
296}
297
298#[cfg(test)]
299mod tests {
300    use super::*;
301
302    fn taxon_record() -> Value {
303        json!({
304            "taxon_id": "9606",
305            "scientific_name": "Homo sapiens",
306            "attributes": {
307                "genome_size": {
308                    "value": 3423000000_u64, "count": 2, "aggregation_source": "direct", "aggregation_method": "primary",
309                    "values": [{"source": "AGSD"}, {"source": "AGSD"}, {"source": "Other"}]
310                },
311                "assembly_level": {"value": "complete genome", "count": 1, "aggregation_source": "direct", "aggregation_method": "enum", "values": []}
312            },
313            "taxon_names": [{"name": "human", "class": "genbank common name", "source": "NCBI Taxonomy"}],
314            "lineage": [{"node_depth": 1, "taxon_id": "9605", "scientific_name": "Homo", "taxon_rank": "genus"}]
315        })
316    }
317
318    #[test]
319    fn test_fields_table_sorted_with_distinct_sources() {
320        let table = record_table(&[taxon_record()], RecordView::Fields, IndexType::Taxon).unwrap();
321        assert_eq!(table.header[0], "taxon_id");
322        // fields are in alphabetical order
323        assert_eq!(table.rows[0][2], json!("assembly_level"));
324        assert_eq!(table.rows[1], vec![
325            json!("9606"), json!("Homo sapiens"), json!("genome_size"), json!(3423000000_u64),
326            json!(2), json!("direct"), json!("primary"), json!(["AGSD", "Other"]),
327        ]);
328    }
329
330    #[test]
331    fn test_names_and_lineage_tables() {
332        let names = record_table(&[taxon_record()], RecordView::Names, IndexType::Taxon).unwrap();
333        assert_eq!(names.rows, vec![vec![json!("9606"), json!("Homo sapiens"), json!("human"), json!("genbank common name"), json!("NCBI Taxonomy")]]);
334        let lineage = record_table(&[taxon_record()], RecordView::Lineage, IndexType::Taxon).unwrap();
335        assert_eq!(lineage.rows, vec![vec![json!("9606"), json!("Homo sapiens"), json!(1), json!("9605"), json!("Homo"), json!("genus")]]);
336    }
337
338    #[test]
339    fn test_assembly_fields_use_single_source() {
340        let record = json!({
341            "assembly_id": "GCA_000001405.29", "scientific_name": "Homo sapiens",
342            "attributes": {"assembly_span": {"value": 3099734149_u64, "count": 1, "source": "INSDC"}},
343            "identifiers": [{"identifier": "GCF_000001405.40", "class": "refseq_accession"}]
344        });
345        let fields = record_table(&[record.clone()], RecordView::Fields, IndexType::Assembly).unwrap();
346        assert_eq!(fields.header[0], "assembly_id");
347        assert_eq!(fields.rows[0][7], json!(["INSDC"]));
348        let names = record_table(&[record], RecordView::Names, IndexType::Assembly).unwrap();
349        assert_eq!(names.rows[0][2], json!("GCF_000001405.40"));
350    }
351
352    #[test]
353    fn test_resolve_from_search() {
354        let one = json!({"results": [{"result": {"taxon_id": "9606"}}]});
355        assert_eq!(resolve_from_search("Homo sapiens", &one).unwrap(), Resolved::Id("9606".into()));
356
357        let none = json!({"results": []});
358        assert!(matches!(resolve_from_search("Homo sapien", &none).unwrap(), Resolved::Problem(m) if m.contains("no taxon found")));
359
360        let several = json!({"results": [
361            {"result": {"taxon_id": "3497", "taxon_rank": "genus", "scientific_name": "Morus"}},
362            {"result": {"taxon_id": "37577", "taxon_rank": "genus", "scientific_name": "Morus"}}
363        ]});
364        assert!(matches!(resolve_from_search("Morus", &several).unwrap(), Resolved::Problem(m) if m.contains("3497 (genus Morus), 37577")));
365    }
366
367    #[test]
368    fn test_found_record() {
369        assert_eq!(found_record(json!({"records": [{"found": true, "record": {"taxon_id": "1"}}]})), Some(json!({"taxon_id": "1"})));
370        assert_eq!(found_record(json!({"records": [{"found": false}]})), None);
371        assert_eq!(found_record(json!({"records": []})), None);
372    }
373
374    #[test]
375    fn test_record_url() {
376        assert_eq!(
377            record_url("GCA_000001405.29", IndexType::Assembly),
378            format!("{}record?recordId=GCA_000001405.29&result=assembly&taxonomy=ncbi", *GOAT_URL)
379        );
380    }
381}