goat_cli/
cli.rs

1//! The command line interface, defined with clap's derive API.
2//!
3//! Each subcommand's arguments are a typed struct, so the code using them is
4//! checked at compile time.
5//!
6//! Help text is given with explicit `help = ...` attributes rather than doc
7//! comments, because clap derive turns doc comments on these types into
8//! (long) help, which would change the `--help` output.
9
10use std::path::PathBuf;
11
12use clap::{Args, CommandFactory, Parser, Subcommand};
13
14use crate::output::Format;
15use crate::report::report::ReportOptions;
16use crate::utils::url::FieldBuilder;
17use crate::utils::utils::pretty_print_usize;
18use crate::{IndexType, UPPER_CLI_FILE_LIMIT, UPPER_CLI_SIZE_LIMIT};
19
20const ABOUT: &str = "Genomes on a Tree. Query metadata across the tree of life.\n\nFor a tutorial on usage, visit: https://github.com/genomehubs/goat-cli/wiki\nVisit the GoaT website here: https://goat.genomehubs.org/";
21const SEARCH_TAXON_HELP: &str = "The taxon to search. An NCBI taxon ID, or the name of a taxon at any rank.\nMay be omitted if an expression (-e) is given, to search across all taxa.";
22const LOOKUP_TAXON_HELP: &str =
23    "The taxon to search. An NCBI taxon ID, or the name of a taxon at any rank.";
24const EXPRESSION_HELP: &str = "Use an expression to filter results server-side, e.g.\n  'genome_size > 1e9 AND assembly_level = chromosome,complete genome'\nClauses are <variable> <operator> <value>, joined by AND / OR (OR binds loosest).\nSee --print-expression for variables, and EXPRESSIONS.md for the full syntax.";
25const EXCLUDE_HELP: &str = "Exclude all missing and ancestral values, so that a returned table may contain only direct measures (excluding missing/ancestral). If multiple variables are requested, a row is only returned if all the variables have a direct value. Will only take effect if one or more variables are specified.";
26const LINEAGE_HELP: &str = "Displays lineage information. I.e. from this node in the tree go back and give all the nodes to the root. Conflicts with descendents.";
27const PRINT_EXPRESSION_HELP: &str = "Print all variables in GoaT currently, with their associated variants.\nUseful for construction of expressions.";
28const PROGRESS_BAR_HELP: &str = "Add a progress bar to large queries, to estimate time left.";
29const NO_DESCENDENTS_HELP: &str =
30    "Do not return values for descendents (i.e. a tax_name() call).";
31const NEWICK_NO_DESCENDENTS_HELP: &str =
32    "Use only the given taxa as tips, rather than all their descendents at --rank. The taxa must be at --rank.";
33const TAX_DEPTH_HELP: &str = "With -d, only return taxa exactly <depth> levels below each taxon (1: its children). Taxa above species only have estimated values, so add -i for those.";
34const SORT_BY_HELP: &str = "Sort the results by a field (e.g. genome_size), or by scientific_name, taxon_id, taxon_rank or (assembly) assembly_id. With several taxa, each taxon's results are sorted separately.";
35const SEARCH_FORMAT_HELP: &str =
36    "Output format: tsv, csv, or json (search: GoaT's full JSON response; count: the rows as objects).";
37const TABLE_FORMAT_HELP: &str = "Output format: tsv, csv, or json (the rows as objects).";
38const REPORT_FORMAT_HELP: &str =
39    "Output format: a tsv or csv table, or json (GoaT's full report response).";
40const OPTS_HELP: &str = "Options for the x-axis. Comma-separated: min,max,tickCount,scale,axisTitle.\nScales: linear, sqrt, log10, log2, log, proportion, ordinal.";
41
42/// Ranks for `-R/--ranks` in search and count.
43const RANKS: [&str; 10] = [
44    "none",
45    "subspecies",
46    "species",
47    "genus",
48    "family",
49    "order",
50    "class",
51    "phylum",
52    "kingdom",
53    "superkingdom",
54];
55/// Ranks for `-r/--rank` in most reports.
56const REPORT_RANKS: [&str; 4] = ["species", "genus", "family", "order"];
57/// Ranks for `-r/--rank` in the arc report.
58const ARC_RANKS: [&str; 7] = [
59    "species", "genus", "family", "order", "phylum", "class", "kingdom",
60];
61
62fn file_help() -> String {
63    format!("A file of NCBI taxonomy ID's (tips) and/or binomial names.\nEach line should contain a single entry.\nFile size is limited to {} entries.", pretty_print_usize(*UPPER_CLI_FILE_LIMIT))
64}
65
66fn size_help() -> String {
67    format!(
68        "The number of results to return. Max {} currently.",
69        pretty_print_usize(*UPPER_CLI_SIZE_LIMIT)
70    )
71}
72
73/// The `clap::Command` for the CLI, e.g. for generating completions or
74/// checking its definition in tests.
75pub fn build_cli() -> clap::Command {
76    Cli::command()
77}
78
79// `goat-cli`
80#[derive(Parser, Debug)]
81#[command(
82    name = "goat-cli",
83    bin_name = "goat-cli",
84    version,
85    propagate_version = true,
86    arg_required_else_help = true,
87    author = "Max Brown, Richard Challis, Sujai Kumar, Cibele Sotero-Caio <goat@genomehubs.org>",
88    about = ABOUT
89)]
90pub struct Cli {
91    #[command(subcommand)]
92    pub index: Index,
93}
94
95// The index to query.
96#[derive(Subcommand, Debug)]
97pub enum Index {
98    #[command(arg_required_else_help = true, about = "Query by taxon index.")]
99    Taxon {
100        #[command(subcommand)]
101        command: TaxonCommand,
102    },
103    #[command(arg_required_else_help = true, about = "Query by assembly index.")]
104    Assembly {
105        #[command(subcommand)]
106        command: AssemblyCommand,
107    },
108    #[command(about = "Print a shell completion script (see the README to install it).")]
109    Completions {
110        #[arg(value_enum, value_name = "shell", help = "The shell to generate completions for.")]
111        shell: clap_complete::Shell,
112    },
113}
114
115/// Write the completion script for `shell` to `out`.
116pub fn write_completions(shell: clap_complete::Shell, out: &mut impl std::io::Write) -> std::io::Result<()> {
117    // clap_complete panics on a write error (e.g. a closed pipe), so generate
118    // into memory and write that.
119    let mut script = Vec::new();
120    clap_complete::generate(shell, &mut Cli::command(), "goat-cli", &mut script);
121    out.write_all(&script)
122}
123
124// `goat-cli taxon <command>`
125#[derive(Subcommand, Debug)]
126pub enum TaxonCommand {
127    #[command(about = "Query metadata for any taxon across the tree of life by taxon index.")]
128    Search(TaxonSearchCommandArgs),
129    #[command(
130        about = "Return the count of results for any taxon across the tree of life by taxon index."
131    )]
132    Count(TaxonSearchArgs),
133    #[command(about = "Return information relating to a taxon name, e.g. synonyms, authorities.")]
134    Lookup(LookupArgs),
135    #[command(
136        about = "Show the full record for taxa: every field with its value and sources, or their names or lineage."
137    )]
138    Record(RecordArgs),
139    #[command(about = "Get the sources of data for all taxa input.")]
140    Sources(SourcesArgs),
141    #[command(about = "Generate a newick tree from input taxa.")]
142    Newick(NewickArgs),
143    #[command(about = "Generate a histogram report from input taxa.")]
144    Hist(HistArgs),
145    #[command(about = "Generate a scatter (bivariate) report.")]
146    Scatter(ScatterArgs),
147    #[command(
148        about = "Generate an arc report (proportion of taxa meeting a condition).\nOmit --taxon for a global query across all taxa."
149    )]
150    Arc(ArcArgs),
151}
152
153// `goat-cli assembly <command>`
154#[derive(Subcommand, Debug)]
155pub enum AssemblyCommand {
156    #[command(about = "Query metadata for any taxon across the tree of life by assembly index.")]
157    Search(AssemblySearchCommandArgs),
158    #[command(
159        about = "Return the count of results for any taxon across the tree of life by assembly index."
160    )]
161    Count(AssemblySearchArgs),
162    #[command(about = "Return information relating to a taxon name, e.g. synonyms, authorities.")]
163    Lookup(LookupArgs),
164    #[command(
165        about = "Show the full record for assemblies: every field with its value and source, or their identifiers or lineage."
166    )]
167    Record(RecordArgs),
168}
169
170// ── search and count ─────────────────────────────────────────────────────────
171
172// Arguments shared by `search` and `count` in both indexes.
173#[derive(Args, Debug, Clone, Default)]
174pub struct QueryArgs {
175    #[arg(
176        short = 't',
177        long,
178        value_name = "taxon",
179        required_unless_present_any = ["file", "print_expression", "expression"],
180        help = SEARCH_TAXON_HELP
181    )]
182    pub taxon: Option<String>,
183    #[arg(
184        short = 'f',
185        long,
186        value_name = "file",
187        required_unless_present_any = ["taxon", "print_expression", "expression"],
188        help = file_help()
189    )]
190    pub file: Option<PathBuf>,
191    #[arg(
192        short = 'v',
193        long,
194        value_name = "variables",
195        help = "Variable parser. Input a comma separated string of variables."
196    )]
197    pub variables: Option<String>,
198    #[arg(long, value_name = "size", default_value_t = 50, help = size_help())]
199    pub size: u64,
200    #[arg(
201        short = 'R',
202        long,
203        value_name = "ranks",
204        default_value = "none",
205        value_parser = RANKS,
206        help = "Choose a rank to display with the results. All ranks up to the given rank are displayed."
207    )]
208    pub ranks: String,
209    #[arg(short = 'e', long, value_name = "expression", help = EXPRESSION_HELP)]
210    pub expression: Option<String>,
211    #[arg(
212        long,
213        value_name = "tax-rank",
214        help = "The taxonomic rank to return the results at."
215    )]
216    pub tax_rank: Option<String>,
217    #[arg(short = 'x', long, help = EXCLUDE_HELP)]
218    pub exclude: bool,
219    #[arg(
220        short = 'd',
221        long,
222        help = "Get information for all descendents of a common ancestor."
223    )]
224    pub descendents: bool,
225    #[arg(short = 'l', long, conflicts_with = "descendents", help = LINEAGE_HELP)]
226    pub lineage: bool,
227    #[arg(long, value_name = "depth", requires = "descendents", help = TAX_DEPTH_HELP)]
228    pub tax_depth: Option<u32>,
229}
230
231// The sort order for `--sort-order`.
232#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, clap::ValueEnum)]
233pub enum SortOrder {
234    #[default]
235    Asc,
236    Desc,
237}
238
239impl std::fmt::Display for SortOrder {
240    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
241        f.write_str(match self {
242            SortOrder::Asc => "asc",
243            SortOrder::Desc => "desc",
244        })
245    }
246}
247
248// Sorting, for `search` only (it doesn't change a count).
249#[derive(Args, Debug, Clone, Default)]
250pub struct SortArgs {
251    #[arg(long, value_name = "field", help = SORT_BY_HELP)]
252    pub sort_by: Option<String>,
253    #[arg(
254        long,
255        value_enum,
256        value_name = "order",
257        requires = "sort_by",
258        help = "Sort ascending (the default) or descending. Needs --sort-by."
259    )]
260    pub sort_order: Option<SortOrder>,
261}
262
263// Output options shared by `search` and `count` in both indexes.
264#[derive(Args, Debug, Clone, Default)]
265pub struct OutputArgs {
266    #[arg(long, help = PRINT_EXPRESSION_HELP)]
267    pub print_expression: bool,
268    #[arg(long, help = PROGRESS_BAR_HELP)]
269    pub progress_bar: bool,
270    #[arg(
271        short = 'u',
272        long,
273        help = "Print the underlying GoaT API URL(s). Useful for debugging."
274    )]
275    pub url: bool,
276    #[arg(
277        short = 'U',
278        long,
279        help = "Print the underlying GoaT UI URL(s). View on the browser!"
280    )]
281    pub goat_ui_url: bool,
282    #[arg(
283        short = 'F',
284        long,
285        value_enum,
286        value_name = "format",
287        default_value = "tsv",
288        help = SEARCH_FORMAT_HELP
289    )]
290    pub format: Format,
291}
292
293// Field flags for `taxon search` and `taxon count`.
294#[derive(Args, Debug, Clone, Default)]
295pub struct TaxonFieldArgs {
296    #[arg(short = 'a', long, help = "Print assembly data (assembly span, assembly level).")]
297    pub assembly: bool,
298    #[arg(short = 'b', long, help = "Print BUSCO estimates.")]
299    pub busco: bool,
300    #[arg(short = 'g', long, help = "Print GC%.")]
301    pub gc_percent: bool,
302    #[arg(
303        short = 'k',
304        long,
305        help = "Print karyotype data (chromosome number & haploid number)."
306    )]
307    pub karyotype: bool,
308    #[arg(short = 'G', long, help = "Print genome size data.")]
309    pub genome_size: bool,
310    #[arg(
311        short = 'B',
312        long,
313        help = "Print the bioproject and biosample ID of records."
314    )]
315    pub bioproject: bool,
316    #[arg(short = 'N', long, help = "Print the contig & scaffold n50 of assemblies.")]
317    pub n50: bool,
318    #[arg(short = 'D', long, help = "Print EBP & assembly dates.")]
319    pub date: bool,
320    #[arg(long, help = "Print gene count data.")]
321    pub gene_count: bool,
322    #[arg(
323        short = 'm',
324        long,
325        help = "Print mitochondrial genome assembly size & GC%."
326    )]
327    pub mitochondria: bool,
328    #[arg(short = 'p', long, help = "Print plastid genome assembly size & GC%.")]
329    pub plastid: bool,
330    #[arg(short = 'S', long, help = "Print sex determination data.")]
331    pub sex_determination: bool,
332    #[arg(short = 'P', long, help = "Print ploidy estimates.")]
333    pub ploidy: bool,
334    #[arg(short = 'c', long, help = "Print c-value data.")]
335    pub c_values: bool,
336    #[arg(long, help = "Print legislation data.")]
337    pub legislation: bool,
338    #[arg(long, help = "Print target list data associated with each taxon.")]
339    pub target_lists: bool,
340    #[arg(short = 'C', long, help = "Print list of countries where taxon is found.")]
341    pub country_list: bool,
342    #[arg(
343        long,
344        help = "Print all data associated with how far this taxon has progressed with genomic sequencing.\nThis includes sample collection, acquisition, progress in sequencing, and whether submitted to INSDC."
345    )]
346    pub status: bool,
347    #[arg(
348        short = 'n',
349        long,
350        help = "Print all associated name data (synonyms, Tree of Life ID, and common names)."
351    )]
352    pub names: bool,
353    #[arg(short = 'r', long, help = "Print raw values (i.e. no aggregation/summary).")]
354    pub raw: bool,
355    #[arg(short = 'T', long, help = "Print data in tidy format.")]
356    pub tidy: bool,
357    #[arg(
358        short = 'i',
359        long,
360        conflicts_with = "raw",
361        help = "Include ancestral estimates. Omitting this flag includes only direct estimates from a taxon. Cannot be used with --raw."
362    )]
363    pub include_estimates: bool,
364    #[arg(
365        long,
366        help = "For each variable specified, return additional columns for direct measures, ancestral inferred, and descendent inferred."
367    )]
368    pub toggle_direct: bool,
369}
370
371// Field flags for `assembly search` and `assembly count`.
372#[derive(Args, Debug, Clone, Default)]
373pub struct AssemblyFieldArgs {
374    #[arg(short = 'a', long, help = "Print assembly data (span & level)")]
375    pub assembly: bool,
376    #[arg(short = 'k', long, help = "Print karyotype data (chromosome number only).")]
377    pub karyotype: bool,
378    #[arg(short = 'c', long, help = "Print contig data (count, l50, n50).")]
379    pub contig: bool,
380    #[arg(short = 's', long, help = "Print scaffold data (count, l50, n50).")]
381    pub scaffold: bool,
382    #[arg(
383        short = 'g',
384        long,
385        help = "Print gene count data (gene count, non-coding gene count)."
386    )]
387    pub gene_count: bool,
388    #[arg(long, help = "Print GC percent data.")]
389    pub gc_percent: bool,
390    #[arg(
391        short = 'b',
392        long,
393        help = "Print BUSCO data (BUSCO completeness, lineage, and string)."
394    )]
395    pub busco: bool,
396    #[arg(long, help = "Print BlobToolKit data (no-hit, target).")]
397    pub btk: bool,
398    #[arg(
399        short = 'i',
400        long,
401        help = "Include ancestral estimates. Omitting this flag includes only direct estimates from a taxon."
402    )]
403    pub include_estimates: bool,
404}
405
406// `goat-cli taxon search` and `goat-cli taxon count`.
407#[derive(Args, Debug, Clone, Default)]
408pub struct TaxonSearchArgs {
409    #[command(flatten)]
410    pub query: QueryArgs,
411    #[command(flatten)]
412    pub fields: TaxonFieldArgs,
413    #[command(flatten)]
414    pub output: OutputArgs,
415}
416
417// `goat-cli assembly search` and `goat-cli assembly count`.
418#[derive(Args, Debug, Clone, Default)]
419pub struct AssemblySearchArgs {
420    #[command(flatten)]
421    pub query: QueryArgs,
422    #[command(flatten)]
423    pub fields: AssemblyFieldArgs,
424    #[command(flatten)]
425    pub output: OutputArgs,
426}
427
428// `goat-cli taxon search`: the `count` arguments, plus sorting.
429#[derive(Args, Debug, Clone, Default)]
430pub struct TaxonSearchCommandArgs {
431    #[command(flatten)]
432    pub search: TaxonSearchArgs,
433    #[command(flatten)]
434    pub sort: SortArgs,
435}
436
437// `goat-cli assembly search`: the `count` arguments, plus sorting.
438#[derive(Args, Debug, Clone, Default)]
439pub struct AssemblySearchCommandArgs {
440    #[command(flatten)]
441    pub search: AssemblySearchArgs,
442    #[command(flatten)]
443    pub sort: SortArgs,
444}
445
446impl From<&TaxonSearchCommandArgs> for SearchRequest {
447    fn from(args: &TaxonSearchCommandArgs) -> Self {
448        Self {
449            sort: args.sort.clone(),
450            ..Self::from(&args.search)
451        }
452    }
453}
454
455impl From<&AssemblySearchCommandArgs> for SearchRequest {
456    fn from(args: &AssemblySearchCommandArgs) -> Self {
457        Self {
458            sort: args.sort.clone(),
459            ..Self::from(&args.search)
460        }
461    }
462}
463
464/// Everything `search` and `count` need, from either index's arguments.
465#[derive(Debug, Clone)]
466pub struct SearchRequest {
467    /// The index to search.
468    pub index_type: IndexType,
469    /// The taxa and filters.
470    pub query: QueryArgs,
471    /// What to print.
472    pub output: OutputArgs,
473    /// Include ancestral estimates.
474    pub include_estimates: bool,
475    /// Include raw values (taxon index only).
476    pub include_raw_values: bool,
477    /// The fields selected by flags.
478    pub fields: FieldBuilder,
479    /// How to sort the results (`search` only).
480    pub sort: SortArgs,
481}
482
483impl From<&TaxonSearchArgs> for SearchRequest {
484    fn from(args: &TaxonSearchArgs) -> Self {
485        let f = &args.fields;
486        let fields = FieldBuilder {
487            taxon_assembly: f.assembly,
488            taxon_bioproject: f.bioproject,
489            taxon_busco: f.busco,
490            taxon_country_list: f.country_list,
491            taxon_cvalues: f.c_values,
492            taxon_date: f.date,
493            taxon_gc_percent: f.gc_percent,
494            taxon_gene_count: f.gene_count,
495            taxon_gs: f.genome_size,
496            taxon_karyotype: f.karyotype,
497            taxon_legislation: f.legislation,
498            taxon_mitochondrion: f.mitochondria,
499            taxon_names: f.names,
500            taxon_n50: f.n50,
501            taxon_plastid: f.plastid,
502            taxon_ploidy: f.ploidy,
503            taxon_sex_determination: f.sex_determination,
504            taxon_status: f.status,
505            taxon_target_lists: f.target_lists,
506            // raw values are always returned in tidy format
507            taxon_tidy: f.tidy || f.raw,
508            taxon_toggle_direct: f.toggle_direct,
509            ..Default::default()
510        };
511        Self {
512            index_type: IndexType::Taxon,
513            query: args.query.clone(),
514            output: args.output.clone(),
515            include_estimates: f.include_estimates,
516            include_raw_values: f.raw,
517            fields,
518            sort: SortArgs::default(),
519        }
520    }
521}
522
523impl From<&AssemblySearchArgs> for SearchRequest {
524    fn from(args: &AssemblySearchArgs) -> Self {
525        let f = &args.fields;
526        let fields = FieldBuilder {
527            assembly_assembly: f.assembly,
528            assembly_karyotype: f.karyotype,
529            assembly_contig: f.contig,
530            assembly_scaffold: f.scaffold,
531            assembly_gc: f.gc_percent,
532            assembly_gene: f.gene_count,
533            assembly_busco: f.busco,
534            assembly_btk: f.btk,
535            ..Default::default()
536        };
537        Self {
538            index_type: IndexType::Assembly,
539            query: args.query.clone(),
540            output: args.output.clone(),
541            include_estimates: f.include_estimates,
542            include_raw_values: false,
543            fields,
544            sort: SortArgs::default(),
545        }
546    }
547}
548
549// ── lookup ───────────────────────────────────────────────────────────────────
550
551// `goat-cli taxon lookup` and `goat-cli assembly lookup`.
552#[derive(Args, Debug, Clone, Default)]
553pub struct LookupArgs {
554    #[arg(
555        short = 't',
556        long,
557        value_name = "taxon",
558        required_unless_present = "file",
559        help = LOOKUP_TAXON_HELP
560    )]
561    pub taxon: Option<String>,
562    #[arg(
563        short = 'f',
564        long,
565        value_name = "file",
566        required_unless_present_any = ["taxon"],
567        help = file_help()
568    )]
569    pub file: Option<PathBuf>,
570    #[arg(short = 'u', long, help = "Print lookup URL.")]
571    pub url: bool,
572    #[arg(
573        short = 's',
574        long,
575        value_name = "size",
576        default_value_t = 10,
577        help = "The number of results to return."
578    )]
579    pub size: u64,
580    #[arg(
581        short = 'F',
582        long,
583        value_enum,
584        value_name = "format",
585        default_value = "tsv",
586        help = TABLE_FORMAT_HELP
587    )]
588    pub format: Format,
589}
590
591// ── record ───────────────────────────────────────────────────────────────────
592
593// `goat-cli taxon record` and `goat-cli assembly record`
594#[derive(Args, Debug, Clone, Default)]
595pub struct RecordArgs {
596    #[arg(
597        short = 't',
598        long,
599        value_name = "taxon",
600        required_unless_present = "file",
601        help = "The records to show, comma separated: NCBI taxon IDs or names (taxon record), or assembly accessions (assembly record)."
602    )]
603    pub taxon: Option<String>,
604    #[arg(
605        short = 'f',
606        long,
607        value_name = "file",
608        required_unless_present = "taxon",
609        help = file_help()
610    )]
611    pub file: Option<PathBuf>,
612    #[arg(
613        short = 'n',
614        long,
615        conflicts_with = "lineage",
616        help = "Show names (taxon record) or identifiers (assembly record) instead of fields."
617    )]
618    pub names: bool,
619    #[arg(short = 'l', long, help = "Show the lineage instead of fields.")]
620    pub lineage: bool,
621    #[arg(short = 'u', long, help = "Print the record URL(s).")]
622    pub url: bool,
623    #[arg(
624        short = 'F',
625        long,
626        value_enum,
627        value_name = "format",
628        default_value = "tsv",
629        help = "Output format: a tsv or csv table, or json (the full records)."
630    )]
631    pub format: Format,
632}
633
634// ── reports ──────────────────────────────────────────────────────────────────
635
636// `goat-cli taxon sources`
637#[derive(Args, Debug, Clone)]
638pub struct SourcesArgs {
639    #[arg(
640        short = 't',
641        long,
642        value_name = "taxon",
643        help = "The taxon to return sources for. Multiple taxa will return the sources for all."
644    )]
645    pub taxon: String,
646    #[arg(
647        short = 'r',
648        long,
649        value_name = "rank",
650        default_value = "species",
651        value_parser = REPORT_RANKS,
652        help = "The rank of the results to return."
653    )]
654    pub rank: String,
655    #[arg(short = 'n', long, help = NO_DESCENDENTS_HELP)]
656    pub no_descendents: bool,
657    #[arg(short = 'u', long, help = "Print report URL.")]
658    pub url: bool,
659    #[arg(
660        short = 'F',
661        long,
662        value_enum,
663        value_name = "format",
664        default_value = "tsv",
665        help = REPORT_FORMAT_HELP
666    )]
667    pub format: Format,
668}
669
670// `goat-cli taxon newick`
671#[derive(Args, Debug, Clone)]
672pub struct NewickArgs {
673    #[arg(
674        short = 't',
675        long,
676        value_name = "taxon",
677        required_unless_present = "file",
678        help = "The taxon to return a newick of. Multiple taxa will return the joint tree."
679    )]
680    pub taxon: Option<String>,
681    #[arg(
682        short = 'f',
683        long,
684        value_name = "file",
685        required_unless_present = "taxon",
686        help = file_help()
687    )]
688    pub file: Option<PathBuf>,
689    #[arg(
690        long,
691        value_name = "threshold",
692        default_value_t = 2000,
693        value_parser = clap::value_parser!(i32).range(-1..),
694        allow_negative_numbers = true,
695        help = "Threshold for returned number of nodes. -1 disables the parameter."
696    )]
697    pub threshold: i32,
698    #[arg(
699        short = 'r',
700        long,
701        value_name = "rank",
702        default_value = "species",
703        value_parser = REPORT_RANKS,
704        help = "The rank of the results to return."
705    )]
706    pub rank: String,
707    #[arg(short = 'n', long, help = NEWICK_NO_DESCENDENTS_HELP)]
708    pub no_descendents: bool,
709    #[arg(short = 'u', long, help = "Print report URL.")]
710    pub url: bool,
711    #[arg(long, help = PROGRESS_BAR_HELP)]
712    pub progress_bar: bool,
713}
714
715// `goat-cli taxon hist`
716#[derive(Args, Debug, Clone)]
717pub struct HistArgs {
718    #[arg(
719        short = 't',
720        long,
721        value_name = "taxon",
722        required_unless_present = "file",
723        help = "The taxon to return a histogram of. Multiple taxa will return the joint histogram."
724    )]
725    pub taxon: Option<String>,
726    #[arg(
727        short = 'f',
728        long,
729        value_name = "file",
730        required_unless_present = "taxon",
731        help = file_help()
732    )]
733    pub file: Option<PathBuf>,
734    #[arg(
735        short = 'x',
736        long,
737        value_name = "x-variable",
738        help = "The variable to bin on the x-axis."
739    )]
740    pub x_variable: String,
741    #[arg(
742        short = 'r',
743        long,
744        value_name = "rank",
745        default_value = "species",
746        value_parser = REPORT_RANKS,
747        help = "The taxonomic rank to aggregate results at."
748    )]
749    pub rank: String,
750    #[arg(
751        short = 'c',
752        long,
753        value_name = "category",
754        help = "A variable or rank to use as a colour category (e.g. 'sex', 'genus')."
755    )]
756    pub category: Option<String>,
757    #[arg(
758        short = 's',
759        long,
760        value_name = "size",
761        help = "The number of category levels to show."
762    )]
763    pub size: Option<usize>,
764    #[arg(short = 'n', long, help = NO_DESCENDENTS_HELP)]
765    pub no_descendents: bool,
766    #[arg(
767        short = 'o',
768        long,
769        value_name = "x-opts",
770        help = format!("{}\nE.g. ',,20' = 20 bins; '1,10,5' = range 1–10 with 5 bins.", OPTS_HELP)
771    )]
772    pub x_opts: Option<String>,
773    #[arg(short = 'u', long, help = "Print report URL.")]
774    pub url: bool,
775    #[arg(
776        short = 'F',
777        long,
778        value_enum,
779        value_name = "format",
780        default_value = "tsv",
781        help = REPORT_FORMAT_HELP
782    )]
783    pub format: Format,
784}
785
786// `goat-cli taxon scatter`
787#[derive(Args, Debug, Clone)]
788pub struct ScatterArgs {
789    #[arg(
790        short = 't',
791        long,
792        value_name = "taxon",
793        required_unless_present = "file",
794        help = "The taxon to return a scatter of. Multiple taxa will return the joint scatter."
795    )]
796    pub taxon: Option<String>,
797    #[arg(
798        short = 'f',
799        long,
800        value_name = "file",
801        required_unless_present = "taxon",
802        help = file_help()
803    )]
804    pub file: Option<PathBuf>,
805    #[arg(
806        short = 'x',
807        long,
808        value_name = "x-variable",
809        help = "The variable on the x-axis."
810    )]
811    pub x_variable: String,
812    #[arg(
813        short = 'y',
814        long,
815        value_name = "y-variable",
816        help = "The variable on the y-axis."
817    )]
818    pub y_variable: String,
819    #[arg(
820        short = 'r',
821        long,
822        value_name = "rank",
823        default_value = "species",
824        value_parser = REPORT_RANKS,
825        help = "The taxonomic rank to aggregate results at."
826    )]
827    pub rank: String,
828    #[arg(
829        short = 'c',
830        long,
831        value_name = "category",
832        help = "A variable or rank to use as a colour category."
833    )]
834    pub category: Option<String>,
835    #[arg(short = 'n', long, help = NO_DESCENDENTS_HELP)]
836    pub no_descendents: bool,
837    #[arg(long, value_name = "x-opts", help = OPTS_HELP)]
838    pub x_opts: Option<String>,
839    #[arg(
840        long,
841        value_name = "y-opts",
842        help = "Options for the y-axis. Same format as --x-opts."
843    )]
844    pub y_opts: Option<String>,
845    #[arg(short = 'u', long, help = "Print report URL.")]
846    pub url: bool,
847    #[arg(
848        short = 'F',
849        long,
850        value_enum,
851        value_name = "format",
852        default_value = "tsv",
853        help = REPORT_FORMAT_HELP
854    )]
855    pub format: Format,
856}
857
858// `goat-cli taxon arc`
859#[derive(Args, Debug, Clone)]
860pub struct ArcArgs {
861    #[arg(
862        short = 't',
863        long,
864        value_name = "taxon",
865        help = "The taxon to scope the arc report to. Omit for a global query."
866    )]
867    pub taxon: Option<String>,
868    #[arg(
869        short = 'x',
870        long,
871        value_name = "x-filter",
872        help = "Filter expression for the numerator.\nE.g. 'assembly_level >= scaffold', 'assembly_span', 'genome_size > 1e9'."
873    )]
874    pub x_filter: String,
875    #[arg(
876        short = 'y',
877        long,
878        value_name = "y-filter",
879        help = "Filter expression for the denominator (reference population).\nDefaults to all taxa at the given rank."
880    )]
881    pub y_filter: Option<String>,
882    #[arg(
883        short = 'r',
884        long,
885        value_name = "rank",
886        default_value = "species",
887        value_parser = ARC_RANKS,
888        help = "The taxonomic rank to aggregate results at."
889    )]
890    pub rank: String,
891    #[arg(
892        long,
893        value_name = "exclude-missing",
894        help = "Comma-separated fields to exclude if missing (e.g. 'assembly_span').\nReduces denominator to only taxa with a direct value for this field."
895    )]
896    pub exclude_missing: Option<String>,
897    #[arg(
898        long,
899        value_name = "exclude-ancestral",
900        help = "Comma-separated fields to exclude if ancestrally inferred (e.g. 'assembly_span')."
901    )]
902    pub exclude_ancestral: Option<String>,
903    #[arg(
904        short = 'n',
905        long,
906        help = "Do not include descendents (i.e. a tax_name() call)."
907    )]
908    pub no_descendents: bool,
909    #[arg(short = 'u', long, help = "Print report URL.")]
910    pub url: bool,
911    #[arg(
912        short = 'F',
913        long,
914        value_enum,
915        value_name = "format",
916        default_value = "tsv",
917        help = REPORT_FORMAT_HELP
918    )]
919    pub format: Format,
920}
921
922impl From<&SourcesArgs> for ReportOptions {
923    fn from(args: &SourcesArgs) -> Self {
924        Self {
925            taxon: Some(args.taxon.clone()),
926            rank: args.rank.clone(),
927            no_descendents: args.no_descendents,
928            url: args.url,
929            format: args.format,
930            ..Default::default()
931        }
932    }
933}
934
935impl From<&NewickArgs> for ReportOptions {
936    fn from(args: &NewickArgs) -> Self {
937        Self {
938            taxon: args.taxon.clone(),
939            file: args.file.clone(),
940            rank: args.rank.clone(),
941            threshold: args.threshold,
942            no_descendents: args.no_descendents,
943            url: args.url,
944            ..Default::default()
945        }
946    }
947}
948
949impl From<&HistArgs> for ReportOptions {
950    fn from(args: &HistArgs) -> Self {
951        Self {
952            taxon: args.taxon.clone(),
953            file: args.file.clone(),
954            rank: args.rank.clone(),
955            x_variable: Some(args.x_variable.clone()),
956            category: args.category.clone(),
957            size: args.size,
958            no_descendents: args.no_descendents,
959            x_opts: args.x_opts.clone(),
960            url: args.url,
961            format: args.format,
962            ..Default::default()
963        }
964    }
965}
966
967impl From<&ScatterArgs> for ReportOptions {
968    fn from(args: &ScatterArgs) -> Self {
969        Self {
970            taxon: args.taxon.clone(),
971            file: args.file.clone(),
972            rank: args.rank.clone(),
973            x_variable: Some(args.x_variable.clone()),
974            y_variable: Some(args.y_variable.clone()),
975            category: args.category.clone(),
976            no_descendents: args.no_descendents,
977            x_opts: args.x_opts.clone(),
978            y_opts: args.y_opts.clone(),
979            url: args.url,
980            format: args.format,
981            ..Default::default()
982        }
983    }
984}
985
986impl From<&ArcArgs> for ReportOptions {
987    fn from(args: &ArcArgs) -> Self {
988        Self {
989            taxon: args.taxon.clone(),
990            rank: args.rank.clone(),
991            x_filter: Some(args.x_filter.clone()),
992            y_filter: args.y_filter.clone(),
993            exclude_missing: args.exclude_missing.clone(),
994            exclude_ancestral: args.exclude_ancestral.clone(),
995            no_descendents: args.no_descendents,
996            url: args.url,
997            format: args.format,
998            ..Default::default()
999        }
1000    }
1001}