Export version 2 JSON schema for visualization with Auspice

class augur.export_v2.CustomOrderedDict(*args)

Bases: OrderedDict

Similar to OrderedDict but will convert dictionaries (and dictionaries of dictionaries) into (nested) CustomOrderedDicts. Encountered lists of dicts will be converted to lists of CustomOrderedDict but we will not recursively explore nested lists. Tuples and other iterators are not explored.

move_to_end_if_present(key, **kwargs)

changes the order of keys to match those specified in order as much as possible. Missing keys are ignored. Extra keys will come after those specified in order.

exception augur.export_v2.InvalidOption

Bases: Exception

augur.export_v2.convert_tree_to_json_structure(node, metadata, get_div, div=0)

converts the Biopython tree structure to a dictionary that can be written to file as a json. This is called recursively.

  • node (Bio.Phylo.Newick.Clade)

  • metadata (dict) – Per-node metadata, with keys matching

  • get_div – (None or function) Function returns divergence for this node. Arguments: (node, metadata_for_node) If None then divergence is not defined for this dataset and so β€˜div’ is not set on returned nodes.

  • div (int) – cumulative divergence leading to the current node (root = 0)


See schema-export-v2.json#/$defs/tree for full details. Node names are always set, and divergence is set if applicable

Return type:



Given a numeric count of author papers, return a distinct alphabetical disambiguation suffix.


>>> counter_to_disambiguation_suffix(0)
>>> counter_to_disambiguation_suffix(25)
>>> counter_to_disambiguation_suffix(26)
>>> counter_to_disambiguation_suffix(51)
>>> counter_to_disambiguation_suffix(52)

Gather the authors which appear in the metadata and create the author info structure with unique keys

augur.export_v2.create_branch_labels(branch_attrs, node_data, branch_data)
augur.export_v2.create_branch_mutations(branch_attrs, node_data)
augur.export_v2.get_additional_metadata_columns(config, command_line_metadata_columns, metadata_names)
augur.export_v2.get_values_across_nodes(node_attrs, key)
augur.export_v2.is_node_attr_defined(node_attrs, attr_name)
augur.export_v2.node_div(T, node_attrs)

Scans the provided tree & metadata to see if divergence is defined, and if so returns a function which gets it from individual nodes. Divergence may be defined via a number of sources, and we pick them in the following order: * metadata.mutation_length (typically via augur refine) * metadata.branch_length (typically via augur refine) * Branch lengths encoded in the Newick tree

Returns either: * function with arguments: (node, metadata_for_node) which returns the node divergence * None (indicates that divergence is not available for this dataset)


converts the data dict (where keys are inherently unordered) into an OrderedDict where keys are nicely ordered for human eyes to scan the data when written to JSON. The ordering (mostly) mirrors the schema.

augur.export_v2.parse_node_data_and_metadata(T, node_data, metadata)
augur.export_v2.set_annotations(data_json, node_data)
augur.export_v2.set_branch_attrs_on_tree(data_json, branch_attrs)

Shifts the provided branch_attrs onto the (auspice) data_json. Currently all data is transferred, there is no way for (e.g.) the set of exported labels to be restricted by the user in a config.

augur.export_v2.set_build_url(data_json, config, cmd_line_build_url)
augur.export_v2.set_colorings(data_json, config, command_line_colorings, metadata_names, node_data_colorings, provided_colors, node_attrs, branch_attrs)
augur.export_v2.set_data_provenance(data_json, config)

Set the data provenance from the given config file to the given data JSON.

  • data_json (dict) – auspice JSON to be updated

  • config (dict) – config JSON with an expected data_provenance key


>>> config = {"data_provenance": [{"name": "GISAID"}, {"name": "INSDC"}]}
>>> data_json = {"meta": {}}
>>> set_data_provenance(data_json, config)
>>> data_json["meta"]["data_provenance"][0]["name"]
augur.export_v2.set_description(data_json, cmd_line_description_file)

Read Markdown file provided by cmd_line_description_file and set meta.description in data_json to the text provided.

augur.export_v2.set_display_defaults(data_json, config)
augur.export_v2.set_filters(data_json, config)
augur.export_v2.set_geo_resolutions(data_json, config, command_line_traits, lat_long_mapping, node_attrs)

appropriately combine provided geo resolutions from command line & config files and associate with lat/longs.

augur.export_v2.set_maintainers(data_json, config, cmd_line_maintainers)
augur.export_v2.set_node_attrs_on_tree(data_json, node_attrs, additional_metadata_columns)

Assign desired colorings, metadata etc to the node_attrs of nodes in the tree

  • data_json (dict)

  • node_attrs (dict) – keys: strain names. values: dict with keys -> all available metadata (even β€œexcluded” keys), values -> data (string / numeric / bool)

  • additional_metadata_columns (list) – Requested additional metadata columns to export

augur.export_v2.set_panels(data_json, config, cmd_line_panels)
augur.export_v2.set_title(data_json, config, cmd_line_title)
augur.export_v2.validate_data_json(filename, validation_mode=ValidationMode.ERROR)