### Install Augur from Source Source: https://docs.nextstrain.org/projects/augur/en/stable/_sources/installation/installation.rst.txt Clones the repository and installs the package locally using pip. ```bash git clone https://github.com/nextstrain/augur.git cd augur python3 -m pip install . ``` -------------------------------- ### Verify Augur Installation Source: https://docs.nextstrain.org/projects/augur/en/stable/installation/installation.html Checks if the installation was successful by displaying the help menu. ```bash augur --help ``` -------------------------------- ### Install Augur via PyPI Source: https://docs.nextstrain.org/projects/augur/en/stable/_sources/installation/installation.rst.txt Installs the nextstrain-augur package using pip. Requires Python 3.10 or higher. ```bash python3 -m pip install nextstrain-augur ``` -------------------------------- ### Example Augur Configuration File Source: https://docs.nextstrain.org/projects/augur/en/stable/_sources/releases/migrating-v5-v6.rst.txt A sample configuration file demonstrating the structure of an Augur project. ```json { "title": "Phylodynamics of my Pathogen", "maintainers": [ {"name": "Jane Doe", "url": "www.janedoe.com"}, {"name": "Ravi Kupra", "url": "www.ravikupra.co.uk"} ], "build_url": "https://github.com/nextstrain/zika", "colorings": [ { "key": "age", "title": "Host age", "type": "continuous" }, { "key": "hospitalized", "type": "boolean" }, { "key": "country", "type": "categorical" }, { "key": "region", "type": "categorical" } ], "geo_resolutions": [ {"key":"country", "title": "Areas"}, "region" ], "panels": ["tree", "map"], "filters": ["country","region","symptom","age"], "display_defaults": { "color_by": "symptom", "geo_resolution": "region", "distance_measure": "div", "map_triplicate": "true" } } ``` -------------------------------- ### Build a tree with IQ-TREE Source: https://docs.nextstrain.org/projects/augur/en/stable/usage/cli/tree.html Example command format for building a phylogenetic tree using the IQ-TREE method. ```bash augur tree --method iqtree --alignment --substitution-model --output --tree-builder-args=”” ``` -------------------------------- ### augur version Source: https://docs.nextstrain.org/projects/augur/en/stable/usage/cli/version.html Prints the installed version of the augur CLI tool. ```APIDOC ## augur version ### Description Prints the version of augur currently installed. ### Usage `augur version [-h]` ``` -------------------------------- ### Filter by min length examples Source: https://docs.nextstrain.org/projects/augur/en/stable/api/developer/augur.filter.include_exclude_rules.html Examples showing how to filter metadata by minimum sequence length, including handling of missing strains and non-ATGC nucleotides. ```python >>> metadata = pd.DataFrame([{"region": "Africa", "date": "2020-01-01"}, {"region": "Europe", "date": "2020-01-02"}], index=["strain1", "strain2"]) >>> sequence_index = pd.DataFrame([{"strain": "strain1", "A": 7000, "C": 7000, "G": 7000, "T": 7000, "invalid_nucleotides": 0}, {"strain": "strain2", "A": 6500, "C": 6500, "G": 6500, "T": 6500, "invalid_nucleotides": 0}]).set_index("strain") >>> filter_by_min_length(metadata, sequence_index, min_length=27000) {'strain1'} ``` ```python >>> sequence_index = pd.DataFrame([{"strain": "strain3", "A": 7000, "C": 7000, "G": 7000, "T": 7000, "invalid_nucleotides": 0}, {"strain": "strain2", "A": 6500, "C": 6500, "G": 6500, "T": 6500, "invalid_nucleotides": 0}]).set_index("strain") >>> filter_by_min_length(metadata, sequence_index, min_length=27000) set() ``` ```python >>> sequence_index = pd.DataFrame([{"strain": "strain1", "A": 7000, "C": 7000, "G": 7000, "T": 7000, "N": 0, "invalid_nucleotides": 0}, {"strain": "strain2", "A": 6500, "C": 6500, "G": 6500, "T": 6500, "N": 2000, "invalid_nucleotides": 0}]).set_index("strain") >>> filter_by_min_length(metadata, sequence_index, min_length=27000) {'strain1'} ``` -------------------------------- ### Filter by min date examples Source: https://docs.nextstrain.org/projects/augur/en/stable/api/developer/augur.filter.include_exclude_rules.html Demonstrates filtering by minimum date and behavior when the date column is missing. ```python >>> from augur.dates import numeric_date >>> metadata = pd.DataFrame([{"region": "Africa", "date": "2020-01-01"}, {"region": "Europe", "date": "2020-01-02"}], index=["strain1", "strain2"]) >>> filter_by_min_date(metadata, date_column="date", min_date=numeric_date("2020-01-02")) {'strain2'} ``` ```python >>> sorted(filter_by_min_date(metadata, date_column="missing_column", min_date=numeric_date("2020-01-02"))) ['strain1', 'strain2'] ``` -------------------------------- ### Set Up Augur Development Environment Source: https://docs.nextstrain.org/projects/augur/en/stable/_sources/installation/installation.rst.txt Creates a Conda environment from a YAML file, activates it, and installs Augur in editable mode with development dependencies. ```bash NAME=augur conda env create -n "$NAME" -f dev_env.yml ``` ```bash conda activate "$NAME" ``` ```bash git clone https://github.com/nextstrain/augur.git cd augur python3 -m pip install -e .'[dev]' ``` -------------------------------- ### Install External Bioinformatics Dependencies Source: https://docs.nextstrain.org/projects/augur/en/stable/installation/installation.html Installs required external tools like mafft, iqtree, and others across different platforms. ```bash conda install -c conda-forge -c bioconda mafft raxml fasttree iqtree vcftools seqkit sqlite --yes ``` ```bash brew tap brewsci/bio brew install mafft iqtree raxml fasttree vcftools seqkit sqlite ``` ```bash sudo apt install mafft iqtree raxml fasttree vcftools seqkit sqlite3 ``` -------------------------------- ### Filter by max length examples Source: https://docs.nextstrain.org/projects/augur/en/stable/api/developer/augur.filter.include_exclude_rules.html Examples showing how to filter metadata by sequence length, including handling of non-ATGC nucleotides and amino acid sequences. ```python >>> metadata = pd.DataFrame([{"region": "Africa", "date": "2020-01-01"}, {"region": "Europe", "date": "2020-01-02"}], index=["strain1", "strain2"]) >>> sequence_index = pd.DataFrame([{"strain": "strain1", "A": 7000, "C": 7000, "G": 7000, "T": 7000, "invalid_nucleotides": 0}, {"strain": "strain2", "A": 6500, "C": 6500, "G": 6500, "T": 6500, "invalid_nucleotides": 0}]).set_index("strain") >>> filter_by_max_length(metadata, sequence_index, max_length=27000) {'strain2'} ``` ```python >>> sequence_index = pd.DataFrame([{"strain": "strain1", **{r: 10 for r in 'ACDEFGHIKLMNPQRSTVWY'}, "invalid_residues": 0}]).set_index("strain") >>> filter_by_max_length(metadata, sequence_index, max_length=300) {'strain1'} ``` -------------------------------- ### Example strain names file format Source: https://docs.nextstrain.org/projects/augur/en/stable/api/developer/augur.io.strains.html Demonstrates the expected format for strain name files, including support for full-line and inline comments. ```text # this is a comment at the top of the file strain1 # exclude strain1 because it isn't sequenced properly strain2 # this is an empty line that will be ignored. ``` -------------------------------- ### Sequence index file format Source: https://docs.nextstrain.org/projects/augur/en/stable/usage/cli/index.html Example of the tab-delimited output format produced by the augur index command. ```text strain length A C G T N other_IUPAC - ? invalid_nucleotides PAN/CDC_259359_V1_V3/2015 10771 2952 2379 3142 2298 0 0 0 0 0 COL/FLR_00024/2015 10659 2921 2344 3113 2281 0 0 0 0 0 PRVABC59 10675 2923 2351 3115 2286 0 0 0 0 0 COL/FLR_00008/2015 10659 2924 2344 3110 2281 0 0 0 0 0 ``` -------------------------------- ### Sequence index file format Source: https://docs.nextstrain.org/projects/augur/en/stable/_sources/usage/cli/index.rst.txt Example output showing the structure of the generated sequence index TSV file. ```text strain length A C G T N other_IUPAC - ? invalid_nucleotides PAN/CDC_259359_V1_V3/2015 10771 2952 2379 3142 2298 0 0 0 0 0 COL/FLR_00024/2015 10659 2921 2344 3113 2281 0 0 0 0 0 PRVABC59 10675 2923 2351 3115 2286 0 0 0 0 0 COL/FLR_00008/2015 10659 2924 2344 3110 2281 0 0 0 0 0 ``` -------------------------------- ### Example Metadata File Format Source: https://docs.nextstrain.org/projects/augur/en/stable/_sources/faq/metadata.rst.txt A sample structure for a tab- or comma-separated metadata file containing strain, accession, date, region, and host information. ```text strain accession date region host 1_0087_PF KX447509 2013-12-XX Oceania Human 1_0181_PF KX447512 2013-12-XX Oceania Bat 1_0199_PF KX447519 2013-11-XX Oceania Human BRA/2016 KY785433 2016-04-08 South America Cow BRA/2015 KY558989 2015-02-23 South America Bat ``` -------------------------------- ### Snakefile Rule for Augur Clades Source: https://docs.nextstrain.org/projects/augur/en/stable/_sources/faq/clades.md.txt A Snakemake rule example for running the augur clades command to annotate tree nodes. ```bash rule clades: input: tree = rules.refine.output.tree, aa_muts = rules.translate.output.aa_data, nuc_muts = rules.ancestral.output.nt_data, clades = "config/clades.tsv" output: clade_data = "results/clades.json" shell: """ augur clades --tree {input.tree} \ --mutations {input.nuc_muts} {input.aa_muts} \ --clades {input.clades} \ --output-node-data {output.clade_data} """ ``` -------------------------------- ### Sample distance command output Source: https://docs.nextstrain.org/projects/augur/en/stable/api/developer/augur.distance.html Example of the JSON output produced by the distance command, including parameters and node-specific distance data. ```json { "params": { "attributes": ["ep", "ne", "ne_star", "ep_pairwise"], "compare_to": ["root", "root", "ancestor", "pairwise"], "map_name": [ "wolf_epitope", "wolf_nonepitope", "wolf_nonepitope", "wolf_epitope" ], "latest_date": "2009-10-01" }, "nodes": { "A/Afghanistan/AF1171/2008": { "ep": 7, "ne": 6, "ne_star": 1, "ep_pairwise": { "A/Aichi/78/2007": 1, "A/Argentina/3509/2006": 2 } } } } ``` -------------------------------- ### Example Node Data JSON Output Source: https://docs.nextstrain.org/projects/augur/en/stable/_sources/usage/cli/ancestral.rst.txt Shows the structure of the node-data JSON file generated by the ancestral command, including mutation lists and sequences for specific nodes. ```json { "nodes": { "NODE_1": { "muts": [], "sequence": "TCCAAACAAAGT..." }, "NODE_2": { "muts": [ "A4461G", "A6591G", "A9184C", "A10385T", "T15098C" ], "sequence": "TCCAAACAAAGT..." } } } ``` -------------------------------- ### Install Augur via Conda Source: https://docs.nextstrain.org/projects/augur/en/stable/_sources/installation/installation.rst.txt Installs Augur and its dependencies using the conda-forge and bioconda channels. ```bash conda install -c conda-forge -c bioconda augur ``` -------------------------------- ### Access command help Source: https://docs.nextstrain.org/projects/augur/en/stable/usage/usage.html Display usage information and available options for a specific subcommand. ```bash augur tree --help ``` -------------------------------- ### augur tree usage help Source: https://docs.nextstrain.org/projects/augur/en/stable/usage/cli/tree.html Displays the command-line interface usage and available arguments for the augur tree command. ```bash usage: augur tree [-h] --alignment ALIGNMENT [--method {fasttree,raxml,iqtree}] [--output OUTPUT] [--substitution-model SUBSTITUTION_MODEL] [--nthreads NTHREADS] [--vcf-reference VCF_REFERENCE] [--exclude-sites EXCLUDE_SITES] [--tree-builder-args TREE_BUILDER_ARGS] [--override-default-args] ``` -------------------------------- ### Calculate indel distance Source: https://docs.nextstrain.org/projects/augur/en/stable/api/developer/augur.distance.html Example showing that a single indel is treated as one event. ```python >>> node_a_sequences = {"gene": "ACTG"} >>> node_b_sequences = {"gene": "A--G"} >>> distance_map = {"default": 1, "map": {}} >>> get_distance_between_nodes(node_a_sequences, node_b_sequences, distance_map) 1.0 ``` -------------------------------- ### Serialize objects to JSON Source: https://docs.nextstrain.org/projects/augur/en/stable/api/developer/augur.io.json.html Examples of serializing specific Python types to JSON strings. ```python >>> as_json(timedelta(days=42)) '"P42D"' ``` ```python >>> as_json(UUID(int=147952133113722764103424939352979237618)) '"6f4e8b5a-8500-4928-b7ae-dc098a256af2"' ``` -------------------------------- ### Compare configuration structure changes Source: https://docs.nextstrain.org/projects/augur/en/stable/_sources/releases/migrating-v5-v6.rst.txt Shows the structural differences between v5 and v6 configuration formats for metadata and display settings. ```json | "type": "discrete", | }, | | "key": "host" | { | | }, | "key": "country", | | "country": { | "type": "categorical" | | "type": "discrete" | }, | | }, | { | | "region": { | "key": "region", | | "type": "discrete" | "type": "categorical" | | }, | } | | "clade_membership":{ | ], | | "menuItem": "Clade", | | | "legendTitle": "Clade", | | | "type": "discrete", | | | "key": "clade_membership" | | | } | | | }, | | | "geo": [ | "geo_resolutions": [ | | "country", | "country", | | "region" | "region" | | ], | ], | | "maintainer": [ | "maintainers": [ | | "Hanna Kukk, Mohammad Fahir", | {"name": "Hanna Kukk", "url": "http://vamuzlab.org"}, | | "http://vamuzlab.org" | {"name": "Mohammad Fahir", "url": "http://mfahir.co.uk"} | | ], | ], | | "filters": [ | "filters": [ | | "country", "region" | "country", "region" | | ], | ], | | "defaults": { | "display_defaults": { | | "layout": "unrooted", | "layout": "unrooted", | | "colorBy": "age" | "color_by": "age" | | } | } | | } | } | +-----------------------------------------------+-----------------------------------------------------------------+ ``` -------------------------------- ### Run test builds Source: https://docs.nextstrain.org/projects/augur/en/stable/_sources/releases/v6.rst.txt Execute the test builds included in the repository to verify functionality and visualize results in Auspice. ```bash cd tests/builds bash runner.sh # creates output in ./auspice auspice view --datasetDir auspice ``` -------------------------------- ### Filter strains in TiterCollection Source: https://docs.nextstrain.org/projects/augur/en/stable/api/developer/augur.titer_model.html Examples of filtering titer measurements based on specific strain lists. ```python >>> measurements, strains, sources = TiterCollection.load_from_file("tests/data/titer_model/h3n2_titers_subset.tsv") >>> len(measurements) 248 ``` ```python >>> len(TiterCollection.filter_strains(measurements, ["A/Oslo/244/1997"])) 0 ``` ```python >>> len(TiterCollection.filter_strains(measurements, ["A/Oslo/244/1997", "A/Johannesburg/33/1994"])) 2 ``` ```python >>> len(TiterCollection.filter_strains(measurements, [])) 0 ``` -------------------------------- ### Command line usage for apply-record-annotations Source: https://docs.nextstrain.org/projects/augur/en/stable/usage/cli/curate/apply-record-annotations.html Displays the available arguments and options for the apply-record-annotations command. ```bash usage: augur curate apply-record-annotations [-h] [--metadata METADATA] [--id-column ID_COLUMN] [--metadata-delimiters METADATA_DELIMITERS [METADATA_DELIMITERS ...]] [--fasta FASTA] [--seq-id-column SEQ_ID_COLUMN] [--seq-field SEQ_FIELD] [--unmatched-reporting {error_first,error_all,warn,silent}] [--duplicate-reporting {error_first,error_all,warn,silent}] [--output-metadata OUTPUT_METADATA] [--output-fasta OUTPUT_FASTA] [--output-id-field OUTPUT_ID_FIELD] [--output-seq-field OUTPUT_SEQ_FIELD] --annotations TSV [--id-field ID_FIELD] ``` -------------------------------- ### Augur LBI Command Usage Source: https://docs.nextstrain.org/projects/augur/en/stable/usage/cli/lbi.html Displays the command-line interface syntax and required arguments for running the augur lbi tool. ```bash usage: augur lbi [-h] --tree TREE --branch-lengths BRANCH_LENGTHS --output OUTPUT --attribute-names ATTRIBUTE_NAMES [ATTRIBUTE_NAMES ...] --tau TAU [TAU ...] --window WINDOW [WINDOW ...] [--no-normalization] ``` -------------------------------- ### Convert metadata to dictionary Source: https://docs.nextstrain.org/projects/augur/en/stable/_sources/releases/changelog.md.txt Example of converting a pandas DataFrame metadata object back into a dictionary format. ```py metadata = read_metadata(args.metadata) metadata.insert(0, "strain", metadata.index.values) columns = metadata.columns metadata = metadata.to_dict(orient="index") ``` -------------------------------- ### Define sample configuration mapping Source: https://docs.nextstrain.org/projects/augur/en/stable/api/developer/augur.subsample.html Mapping of YAML configuration keys to augur filter options for intermediate filter calls. ```python FILTER_SAMPLE_CONFIG: Dict[str, str | Tuple[str, str | None] | None] = {'context_sample': None, 'drop_sample': None, 'exclude': '--exclude', 'exclude_all': ('--exclude-all', None), 'exclude_ambiguous_dates_by': '--exclude-ambiguous-dates-by', 'exclude_invalid': ('--exclude-invalid', None), 'exclude_where': '--exclude-where', 'group_by': '--group-by', 'group_by_weights': '--group-by-weights', 'include': '--include', 'include_where': '--include-where', 'max_date': '--max-date', 'max_length': '--max-length', 'max_sequences': '--subsample-max-sequences', 'min_date': '--min-date', 'min_length': '--min-length', 'non_nucleotide': ('--exclude-invalid', None), 'probabilistic_sampling': ('--probabilistic-sampling', '--no-probabilistic-sampling'), 'query': '--query', 'query_columns': '--query-columns', 'sequences_per_group': '--sequences-per-group'} ``` -------------------------------- ### JSONDecodeError context examples Source: https://docs.nextstrain.org/projects/augur/en/stable/api/developer/augur.io.json.html Demonstrates how JSONDecodeError provides contextual snippets when parsing invalid JSON input. ```python >>> load_json('{foo: "bar"}') Traceback (most recent call last): ... augur.io.json.JSONDecodeError: Expecting property name enclosed in double quotes: line 1 column 2 (char 1): '{▸▸▸f◂◂◂oo: "bar"}' >>> load_json('not json') Traceback (most recent call last): ... augur.io.json.JSONDecodeError: Expecting value: line 1 column 1 (char 0): 'not json' >>> load_json("[0, 1, 2, 3, 4, 5") Traceback (most recent call last): ... augur.io.json.JSONDecodeError: Expecting ',' delimiter: line 1 column 18 (char 17): unexpected end of document: '…, 3, 4, 5' >>> load_json("[\n") Traceback (most recent call last): ... augur.io.json.JSONDecodeError: Expecting value: line 2 column 1 (char 2): unexpected end of document: '[\n' >>> load_json("\n") Traceback (most recent call last): ... augur.io.json.JSONDecodeError: Expecting value: line 2 column 1 (char 1): unexpected end of document: '\n' >>> load_json('') Traceback (most recent call last): ... augur.io.json.JSONDecodeError: Expecting value: line 1 column 1 (char 0): (empty source document) ``` -------------------------------- ### View augur curate titlecase usage Source: https://docs.nextstrain.org/projects/augur/en/stable/usage/cli/curate/titlecase.html Displays the command-line interface help and available arguments for the titlecase command. ```bash usage: augur curate titlecase [-h] [--metadata METADATA] [--id-column ID_COLUMN] [--metadata-delimiters METADATA_DELIMITERS [METADATA_DELIMITERS ...]] [--fasta FASTA] [--seq-id-column SEQ_ID_COLUMN] [--seq-field SEQ_FIELD] [--unmatched-reporting {error_first,error_all,warn,silent}] [--duplicate-reporting {error_first,error_all,warn,silent}] [--output-metadata OUTPUT_METADATA] [--output-fasta OUTPUT_FASTA] [--output-id-field OUTPUT_ID_FIELD] [--output-seq-field OUTPUT_SEQ_FIELD] --titlecase-fields [TITLECASE_FIELDS ...] [--articles [ARTICLES ...]] [--abbreviations [ABBREVIATIONS ...]] [--failure-reporting {error_first,error_all,warn,silent}] ``` -------------------------------- ### Configure Geo Resolutions Source: https://docs.nextstrain.org/projects/augur/en/stable/_sources/releases/migrating-v5-v6.rst.txt Examples of defining geographical traits with optional custom titles in the configuration file. ```json "geo_resolutions: ["country", "region"]" ``` ```json "geo_resolutions": [{"key": "country", "title": "Areas"}, {"key": "region", "title": "Global"}] ``` ```json "geo_resolutions": [ {"key": "country", "title": "Areas"}, "region"] ``` -------------------------------- ### augur.version.run Source: https://docs.nextstrain.org/projects/augur/en/stable/api/developer/augur.version.html Executes the logic to print the current version of Augur. ```APIDOC ## augur.version.run(_args_) ### Description Executes the logic to print the current version of Augur based on the provided arguments. ### Parameters - **_args_** (object) - Required - The arguments passed to the version command. ``` -------------------------------- ### Convert dates to numerical format Source: https://docs.nextstrain.org/projects/augur/en/stable/api/developer/augur.dates.html Examples of converting various date string formats into numerical values. ```python >>> numeric_date("2020.42") 2020.42 >>> numeric_date("2020-06-04") 2020.42486... >>> import datetime, isodate >>> numeric_date("1W") == date_to_numeric(datetime.date.today() - isodate.parse_duration("P1W")) True ``` -------------------------------- ### Metadata Embedded in Fasta Header Source: https://docs.nextstrain.org/projects/augur/en/stable/_sources/faq/metadata.rst.txt An example of how metadata can be encoded directly within a Fasta sequence header. ```text >1_0087_PF | KX447509 | 2013-12-XX | oceania ACTCGCTGCATCG... ``` -------------------------------- ### View augur sequence-traits usage Source: https://docs.nextstrain.org/projects/augur/en/stable/usage/cli/sequence-traits.html Displays the command-line interface help and available arguments for the sequence-traits tool. ```bash usage: augur sequence-traits [-h] [--ancestral-sequences ANCESTRAL_SEQUENCES] [--translations TRANSLATIONS] [--vcf-reference VCF_REFERENCE] [--vcf-translate-reference VCF_TRANSLATE_REFERENCE] [--features FEATURES] [--count {traits,mutations}] [--label LABEL] [--output-node-data OUTPUT_NODE_DATA] ``` -------------------------------- ### augur write-file usage Source: https://docs.nextstrain.org/projects/augur/en/stable/usage/cli/write-file.html Displays the command-line syntax for the write-file utility. ```bash usage: augur write-file [-h] PATH ``` -------------------------------- ### Implement custom default method for JSONEncoder Source: https://docs.nextstrain.org/projects/augur/en/stable/api/developer/augur.io.json.html Example of overriding the default method to support arbitrary iterables during JSON serialization. ```python def default(self, o): try: iterable = iter(o) except TypeError: pass else: return list(iterable) # Let the base class default method raise the TypeError return super().default(o) ``` -------------------------------- ### augur.io.file.open_file(path_or_buffer, mode='r', **kwargs) Source: https://docs.nextstrain.org/projects/augur/en/stable/api/developer/augur.io.file.html Opens a file path or buffer and returns a file handle, with support for transparent compression. ```APIDOC ## augur.io.file.open_file(path_or_buffer, mode='r', **kwargs) ### Description Opens a given file path and returns the handle. Transparently handles compressed inputs and outputs. ### Parameters - **path_or_buffer** (str/IO) - Required - Name of the file to open or an existing IO buffer. - **mode** (str) - Optional - Mode to open file (read or write). Defaults to 'r'. ### Response - **handle** (IO) - File handle object. ``` -------------------------------- ### augur.util_support.warnings.configure_warnings() Source: https://docs.nextstrain.org/projects/augur/en/stable/api/developer/augur.util_support.warnings.html Configures the warning system for the Augur application. ```APIDOC ### Function: configure_warnings() **Description:** Configures the warning system for the Augur application. This should be called to initialize warning handling settings. ``` -------------------------------- ### Group strains for subsampling Source: https://docs.nextstrain.org/projects/augur/en/stable/api/developer/augur.filter.subsample.html Examples of grouping strains by metadata columns, including automatic date parsing and handling missing columns. ```python >>> strains = ["strain1", "strain2"] >>> metadata = pd.DataFrame([{"strain": "strain1", "date": "2020-01-01", "region": "Africa"}, {"strain": "strain2", "date": "2020-02-01", "region": "Europe"}]).set_index("strain") >>> group_by = ["region"] >>> group_by_strain = get_groups_for_subsampling(strains, metadata, group_by) >>> group_by_strain {'strain1': ('Africa',), 'strain2': ('Europe',)} ``` ```python >>> group_by = ["year", "month"] >>> group_by_strain = get_groups_for_subsampling(strains, metadata, group_by) >>> group_by_strain {'strain1': ('2020', '2020-01'), 'strain2': ('2020', '2020-02')} ``` ```python >>> group_by_strain = get_groups_for_subsampling(strains, metadata) >>> group_by_strain {'strain1': ('_dummy',), 'strain2': ('_dummy',)} ``` ```python >>> group_by = ["missing_column"] >>> get_groups_for_subsampling(strains, metadata, group_by) Traceback (most recent call last): ... augur.errors.AugurError: The specified group-by categories (['missing_column']) were not found. ``` -------------------------------- ### View augur clades command usage Source: https://docs.nextstrain.org/projects/augur/en/stable/usage/cli/clades.html Displays the command-line interface help and argument structure for the augur clades tool. ```bash usage: augur clades [-h] --tree TREE --mutations NODE_DATA_JSON [NODE_DATA_JSON ...] --clades TSV [--output-node-data NODE_DATA_JSON] [--membership-name MEMBERSHIP_NAME] [--label-name LABEL_NAME] [--validation-mode {error,warn,skip}] [--skip-validation] ``` -------------------------------- ### Initialize ColorParser Source: https://docs.nextstrain.org/projects/augur/en/stable/api/developer/augur.util_support.color_parser.html Constructor for the ColorParser class, accepting a mapping filename and an optional flag to use defaults. ```python class augur.util_support.color_parser.ColorParser(* , mapping_filename , use_defaults =True) ``` -------------------------------- ### Calculate distance between nodes Source: https://docs.nextstrain.org/projects/augur/en/stable/api/developer/augur.distance.html Examples demonstrating how to use get_distance_between_nodes with various distance map configurations, including precision and output type settings. ```python >>> node_a_sequences = {"gene": "ACTG"} >>> node_b_sequences = {"gene": "ACGG"} >>> distance_map = {"default": 0, "map": {}} >>> get_distance_between_nodes(node_a_sequences, node_b_sequences, distance_map) 0.0 >>> distance_map = {"default": 1, "map": {}} >>> get_distance_between_nodes(node_a_sequences, node_b_sequences, distance_map) 1.0 >>> distance_map = {"default": 0.0, "map": {"gene": {3: 1.0}}} >>> get_distance_between_nodes(node_a_sequences, node_b_sequences, distance_map) 0.0 >>> distance_map = {"default": 0.0, "map": {"gene": {2: 3.14159, 3: 1.0}}} >>> get_distance_between_nodes(node_a_sequences, node_b_sequences, distance_map) 3.14159 >>> distance_map = {"default": 0.0, "precision": 2, "map": {"gene": {2: 3.14159, 3: 1.0}}} >>> get_distance_between_nodes(node_a_sequences, node_b_sequences, distance_map) 3.14 >>> distance_map = {"default": 0.0, "output_type": "integer", "map": {"gene": {2: 3.14159, 3: 1.0}}} >>> get_distance_between_nodes(node_a_sequences, node_b_sequences, distance_map) 3 >>> distance_map = {"default": 0.0, "output_type": "int", "map": {"gene": {2: 3.14159, 3: 1.0}}} >>> get_distance_between_nodes(node_a_sequences, node_b_sequences, distance_map) 3 >>> distance_map = {"default": 0.0, "output_type": "unsupported", "map": {"gene": {2: 3.14159, 3: 1.0}}} >>> get_distance_between_nodes(node_a_sequences, node_b_sequences, distance_map) Traceback (most recent call last): ... ValueError: Unsupported output type of 'unsupported' provided in the distance map ``` -------------------------------- ### Augur Import Usage Source: https://docs.nextstrain.org/projects/augur/en/stable/usage/cli/import.html Displays the general usage and help information for the augur import command. ```bash usage: augur import [-h] Import analyses into augur pipeline from other systems ... ``` -------------------------------- ### Augur index command usage Source: https://docs.nextstrain.org/projects/augur/en/stable/usage/cli/index.html Displays the command-line interface syntax and available arguments for the augur index tool. ```bash usage: augur index [-h] --sequences SEQUENCES --output OUTPUT [--seq-type {nuc,aa}] [--verbose] ``` -------------------------------- ### Serialize objects to JSON using as_json Source: https://docs.nextstrain.org/projects/augur/en/stable/api/developer/augur.io.json.html Examples of converting date, datetime, and time objects to JSON strings using the custom JsonEncoder. ```python >>> as_json(date(year=2024, month=7, day=17)) '"2024-07-17"' ``` ```python >>> as_json(datetime(year=2024, month=7, day=17, hour=11, minute=38)) '"2024-07-17T11:38:00"' ``` ```python >>> as_json(time(hour=11, minute=38)) '"11:38:00"' ``` -------------------------------- ### Apply Titlecase to Strings Source: https://docs.nextstrain.org/projects/augur/en/stable/api/developer/augur.curate.titlecase.html Examples of transforming various location strings into title case using the titlecase function with specified articles and abbreviations. ```python >>> titlecase("the night OF THE LIVING DEAD", articles) 'The Night of the Living Dead' ``` ```python >>> titlecase("BRAINE-LE-COMTE, FRANCE", articles) 'Braine-le-Comte, France' ``` ```python >>> titlecase("auvergne-RHÔNE-alpes", articles) 'Auvergne-Rhône-Alpes' ``` ```python >>> titlecase("washington DC, usa", articles, abbreviations) 'Washington DC, USA' ``` -------------------------------- ### Augur Curate Format-Dates CLI Usage Source: https://docs.nextstrain.org/projects/augur/en/stable/usage/cli/curate/format-dates.html Displays the command-line interface options and arguments for the format-dates tool. ```bash usage: augur curate format-dates [-h] [--metadata METADATA] [--id-column ID_COLUMN] [--metadata-delimiters METADATA_DELIMITERS [METADATA_DELIMITERS ...]] [--fasta FASTA] [--seq-id-column SEQ_ID_COLUMN] [--seq-field SEQ_FIELD] [--unmatched-reporting {error_first,error_all,warn,silent}] [--duplicate-reporting {error_first,error_all,warn,silent}] [--output-metadata OUTPUT_METADATA] [--output-fasta OUTPUT_FASTA] [--output-id-field OUTPUT_ID_FIELD] [--output-seq-field OUTPUT_SEQ_FIELD] [--date-fields NAME [NAME ...]] [--expected-date-formats FORMAT [FORMAT ...]] [--failure-reporting {error_first,error_all,warn,silent}] [--no-mask-failure] ``` -------------------------------- ### Define an asymmetric distance map Source: https://docs.nextstrain.org/projects/augur/en/stable/api/developer/augur.distance.html Example of a distance map JSON structure assigning asymmetric weights to amino acid substitutions at a specific position. ```json { "default": 0.0, "map": { "HA1": { "112": [ { "from": "V", "to": "I", "weight": 1.192 }, { "from": "I", "to": "V", "weight": 0.002 } ] } } } ``` -------------------------------- ### Comparison of Export v1 and v2 Config Files Source: https://docs.nextstrain.org/projects/augur/en/stable/_sources/releases/migrating-v5-v6.rst.txt Side-by-side comparison showing the structural changes required when migrating from export v1 to export v2. ```json { "title": "Phylodynamics of Virus A", "color_options": { "gt": { "menuItem": "genotype", "legendTitle": "Genotype", "type": "discrete", "key": "genotype" }, "num_date": { "menuItem": "date", "legendTitle": "Sampling date", "type": "continuous", "key": "num_date" }, "age": { "menuItem": "Host age", "legendTitle": "Host Age (years)", "type": "continuous", "key": "age" }, "host": { "menuItem": "Animal", "legendTitle": "Animal", "type": "categorical", "key": "host" } ``` ```json { "title": "Phylodynamics of Virus A", "colorings": [ { "key": "age", "title": "Host age", "type": "continuous" }, { "key": "host", "title": "Animal", "type": "categorical" } ``` -------------------------------- ### Read metadata files using read_metadata Source: https://docs.nextstrain.org/projects/augur/en/stable/api/developer/augur.io.metadata.html Examples for loading metadata into pandas DataFrames, handling missing index columns, and processing files in chunks. ```python >>> read_metadata("tests/functional/filter/data/metadata.tsv").index.values[0] 'COL/FLR_00024/2015' ``` ```python >>> read_metadata("tests/functional/filter/data/metadata.tsv", id_columns=("Virus name",)) Traceback (most recent call last): ... Exception: None of the possible id columns ('Virus name') were found in the metadata's columns ('strain', 'virus', 'accession', 'date', 'region', 'country', 'division', 'city', 'db', 'segment', 'authors', 'url', 'title', 'journal', 'paper_url') ``` ```python >>> for chunk in read_metadata("tests/functional/filter/data/metadata.tsv", chunk_size=5): ... print(chunk.shape) ... (5, 14) (5, 14) (2, 14) ``` -------------------------------- ### Augur Subsample CLI Usage Source: https://docs.nextstrain.org/projects/augur/en/stable/usage/cli/subsample.html Displays the command-line interface help and available arguments for the augur subsample command. ```bash usage: augur subsample [-h] [--metadata FILE] [--sequences FILE] [--sequence-index FILE] [--metadata-chunk-size N] [--metadata-id-columns COLUMN [COLUMN ...]] [--metadata-delimiters CHARACTER [CHARACTER ...]] [--skip-checks] [--seq-type {nuc,aa}] --config FILE [--config-section KEY [KEY ...]] [--search-paths DIR [DIR ...]] [--nthreads N] [--seed N] [--output-metadata FILE] [--output-sequences FILE] [--output-log OUTPUT_LOG] ``` -------------------------------- ### Augur JSON Output Structure Source: https://docs.nextstrain.org/projects/augur/en/stable/_sources/usage/json_format.md.txt Example of the JSON format used for storing node annotations, including branch lengths, dates, and clock model parameters. ```json { "alignment": "results/aligned.fasta", "input_tree": "results/tree_raw.nwk", "clock": { "intercept": -2.2139560216719905, "rate": 0.0011001967850769103, "rtt_Tmrca": 2012.3272960820566 }, "nodes": { "1_0087_PF": { "branch_length": 0.0001694424712162532, "clock_length": 0.0001694424712162532, "date": "2013-12-31", "mutation_length": 0.00027877777449324505, "numdate": 2013.9993155382122, "raw_date": "2013-12-XX" }, "1_0181_PF": { "branch_length": 0.00009101896681161861, "clock_length": 0.00009101896681161861, "date": "2013-12-31", "mutation_length": 0.0001858351915513057, "numdate": 2013.9993155382122, "raw_date": "2013-12-XX" }, "NODE_0000030": { "branch_length": 0.0006468897126106284, "clock_length": 0.0006468897126106284, "date": "2016-06-06", "mutation_length": 0.0010229321826899364, "numdate": 2016.4318911009404 } } } ``` -------------------------------- ### augur read-file usage syntax Source: https://docs.nextstrain.org/projects/augur/en/stable/usage/cli/read-file.html Displays the command-line interface usage pattern for reading one or more file paths. ```bash usage: augur read-file [-h] PATH [PATH ...] ``` -------------------------------- ### Example Node Data JSON Output Source: https://docs.nextstrain.org/projects/augur/en/stable/_sources/usage/cli/translate.rst.txt This JSON structure represents the output of the translate command, showing annotations, node-specific amino acid mutations, and reference sequences. ```json { "annotations": { "GENE_1": { "end": 1685, "seqid": "reference.gb", "start": 108, "strand": "+", "type": "CDS" }, "GENE_2": { "end": 2705, "seqid": "reference.gb", "start": 1807, "strand": "+", "type": "CDS" }, }, "nodes": { "NODE_1": { "aa_muts": [] }, "NODE_2": { "aa_muts": [ "GENE_1": [ "S139N", "R213K", "R439G", "V440A", "D474N", "S479W", "S481T", "P485L", "R521K" ], "GENE_2": [ "P43S", "D46N", "C64R", "R98K", "D136G", "M175V" ] ] } }, "reference": { "GENE_1": "MATLLRSLAL...", "GENE_2": "MAEEQARHVK..." } } ``` -------------------------------- ### augur.tree.build_iqtree Source: https://docs.nextstrain.org/projects/augur/en/stable/api/developer/augur.tree.html Builds a phylogenetic tree using the IQ-TREE software. ```APIDOC ## augur.tree.build_iqtree(aln_file, out_file, substitution_model='GTR', clean_up=True, nthreads=1, tree_builder_args=None) ### Description Builds a tree using the IQ-Tree executable. ### Parameters - **aln_file** (str) - Required - File name of the input alignment. - **out_file** (str) - Required - File name to write the resulting tree to. - **substitution_model** (str) - Optional - Substitution model to use (default: 'GTR'). - **clean_up** (bool) - Optional - Whether to clean up temporary files (default: True). - **nthreads** (int) - Optional - Number of threads to use (default: 1). - **tree_builder_args** (str) - Optional - Additional arguments for the tree builder. ```