augur export

Note

The behavior of augur export has changed in v6. Please see here for more details.

Export JSON files suitable for visualization with auspice.

usage: augur export [-h]
                    Augur export now needs you to define the JSON version you
                    want, e.g. `augur export v2`. ...

JSON SCHEMA

Augur export now needs you to define the JSON version you want, e.g. `augur export v2`.

Possible choices: v2, v1

Sub-commands

v2

Export version 2 JSON schema for visualization with Auspice

augur export v2 [-h] --tree newick --output JSON
                [--auspice-config JSON [JSON ...]] [--title title]
                [--maintainers name [name ...]] [--build-url url]
                [--description description.md] [--warning text or file]
                [--geo-resolutions trait [trait ...]]
                [--color-by-metadata trait [trait ...]]
                [--metadata-columns METADATA_COLUMNS [METADATA_COLUMNS ...]]
                [--panels panels [panels ...]] [--node-data JSON [JSON ...]]
                [--metadata FILE]
                [--metadata-delimiters METADATA_DELIMITERS [METADATA_DELIMITERS ...]]
                [--metadata-id-columns METADATA_ID_COLUMNS [METADATA_ID_COLUMNS ...]]
                [--colors FILE] [--lat-longs TSV]
                [--minify-json | --no-minify-json]
                [[--include-root-sequence | --include-root-sequence-inline]]
                [--validation-mode {error,warn,skip}] [--skip-validation]
                [--output-auspice-config JSON]

REQUIRED

--tree, -t

Phylogenetic tree, usually output from augur refine

--output

Output file (typically for visualisation in auspice)

DISPLAY CONFIGURATION

These control the display settings for auspice. Config JSON(s) allow customisation of all available options whereas individual command line arguments are more limited but great to get started. Supplying both is fine too, command line args will overrule what is set in the config file. Multiple JSONs will be merged together, and lists present in multiple configs will be merged by extending the original list.

--auspice-config

Auspice configuration file(s)

Default: []

--title

Title to be displayed by auspice

--maintainers

Analysis maintained by, in format ‘Name <URL>’ ‘Name2 <URL>’, …

--build-url

Build URL/repository to be displayed by Auspice

--description

Markdown file with description of build and/or acknowledgements to be displayed by Auspice

--warning

Text or file in Markdown format to be displayed as a warning banner by Auspice

--geo-resolutions

Geographic traits to be displayed on map

--color-by-metadata

Metadata columns to include as coloring options. Ignores columns named ‘none’, so please rename them if you would like to include them as colorings.

--metadata-columns

Metadata columns to export in addition to columns provided by –color-by-metadata or colorings in the Auspice configuration file. These columns will not be used as coloring options in Auspice but will be visible in the tree. Ignores columns named ‘none’, so please rename them if you would like to include them as metadata fields.

--panels

Possible choices: tree, map, entropy, frequencies, measurements

Restrict panel display in auspice. Options are [‘tree’, ‘map’, ‘entropy’, ‘frequencies’, ‘measurements’]. Ignore this option to display all available panels.

OPTIONAL INPUT FILES

--node-data

JSON files containing metadata for nodes in the tree

--metadata

Additional metadata for strains in the tree

--metadata-delimiters

delimiters to accept when reading a metadata file. Only one delimiter will be inferred.

Default: (',', '\t')

--metadata-id-columns

names of possible metadata columns containing identifier information, ordered by priority. Only one ID column will be inferred.

Default: ('strain', 'name')

--colors

Custom color definitions, one per line in the format TRAIT_TYPEtTRAIT_VALUEtHEX_CODE

--lat-longs

Latitudes and longitudes for geography traits. See this file for the format:

<https://github.com/nextstrain/augur/blob/30.0.1/augur/data/lat_longs.tsv>. This file provides the default set of latitudes and longitudes. An additional file specified by this option will extend the default set. Duplicates based on the first two columns will be resolved by taking the coordinates from the user-provided file.

OPTIONAL MINIFY SETTINGS

By default, output JSON files (both main and sidecar) are automatically minimized if the size of the un-minified main JSON file exceeds 5 MB. Use these options to override that behavior.

--minify-json

always export JSONs without indentation or line returns.

Default: False

--no-minify-json

always export JSONs to be human readable.

Default: False

OPTIONAL ROOT-SEQUENCE SETTINGS

The root-sequences describe the sequences (nuc + aa) for the parent of the tree’s root-node. They may represent a reference sequence or the inferred sequence at the root node, depending on how they were generated. The data is taken directly from the reference key within the provided node-data JSONs. These arguments are mutually exclusive.

--include-root-sequence

Export as an additional JSON. The filename will follow the pattern of <OUTPUT>_root-sequence.json for a main auspice JSON of <OUTPUT>.json

Default: False

--include-root-sequence-inline

Export the root sequence within the dataset JSON. This should only be used for small genomes for file size reasons.

Default: False

OTHER OPTIONAL SETTINGS

--validation-mode

Possible choices: error, warn, skip

Control if optional validation checks are performed and what happens if they fail.

‘error’ and ‘warn’ modes perform validation and emit messages about failed validation checks. ‘error’ mode causes a non-zero exit status if any validation checks failed, while ‘warn’ does not.

‘skip’ mode performs no validation.

Note that some validation checks are non-optional and as such are not affected by this setting.

Default: error

--skip-validation

Skip validation of input/output files, equivalent to –validation-mode=skip. Use at your own risk!

--output-auspice-config

Write out the merged auspice configuration file for debugging purposes etc. File is only written if you provide multiple config files via –auspice-config.

v1

Export version 1 JSON schema (separate meta and tree JSONs) for visualization with Auspice

augur export v1 [-h] --tree TREE --metadata FILE
                [--metadata-delimiters METADATA_DELIMITERS [METADATA_DELIMITERS ...]]
                --node-data NODE_DATA [NODE_DATA ...]
                [--output-tree OUTPUT_TREE] [--output-meta OUTPUT_META]
                [--auspice-config AUSPICE_CONFIG] [--colors FILE]
                [--lat-longs LAT_LONGS] [--tree-name TREE_NAME]
                [--minify-json] [--output-sequence OUTPUT_SEQUENCE]
                [--reference REFERENCE]
                [--reference-translations REFERENCE_TRANSLATIONS]

REQUIRED

--tree, -t

tree to perform trait reconstruction on

--metadata

sequence metadata

--metadata-delimiters

delimiters to accept when reading a metadata file. Only one delimiter will be inferred.

Default: (',', '\t')

--node-data

JSON files with meta data for each node

--output-tree

JSON file name that is passed on to auspice (e.g., zika_tree.json).

--output-meta

JSON file name that is passed on to auspice (e.g., zika_meta.json).

--auspice-config

file with auspice configuration

OPTIONS

--colors

Custom color definitions, one per line in the format TRAIT_TYPEtTRAIT_VALUEtHEX_CODE

--lat-longs

file latitudes and longitudes, overrides built in mappings

--tree-name

Tree name (needed for tangle tree functionality)

Default: False

--minify-json

export JSONs without indentation or line returns

Default: False

--output-sequence

JSON file name that is passed on to auspice (e.g., zika_seq.json).

--reference

reference sequence for export to browser, only vcf

--reference-translations

reference translations for export to browser, only vcf