Augur

https://docs.nextstrain.org/projects/augur/en/stable/
Admin
Augur is a bioinformatics toolkit for phylogenetic analysis that tracks the evolution of pathogen...
Tokens:89,251
Snippets:1,080
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### 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 <alignment> --substitution-model <model> --output <tree> --tree-builder-args=”<extra arguments>”
```

--------------------------------

### 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.
```
Tokens:
Raw