[glstott]

Summary

Addresses #1743

Adds browser-based export of MicrobeTrace phylogenetic trees as Auspice v2 JSON, allowing users to visualize their data in auspice.us or a local auspice view instance without running a Nextstrain/Augur build.

Changes

• Added an Auspice JSON option to the Phylogenetic Tree export dialog.
• Added filename generation and .json extension normalization.
• Added advanced export controls for:
  • exporting the complete tree or currently displayed subtree;
  • selecting node metadata;
  • selecting fields available in Auspice’s Color By menu;
  • selecting fields available in Auspice’s Filters menu.
• Built an Auspice v2 exporter that:
  • preserves tree topology, branch rotations, tip order, and cumulative divergence;
  • generates deterministic, collision-safe internal-node names;
  • exports safe scalar tip and identifiable internal-node metadata;
  • supports categorical, ordinal, continuous, boolean, and temporal colorings;
  • preserves saved MicrobeTrace palettes and custom legend labels;
  • exports selected and visible node state;
  • preserves compatible bootstrap support as branch labels;
  • omits raw sequences, layout data, tree bookkeeping fields, and unsupported Auspice sidecar data.
• Added geographic export support for:
  • exact latitude and longitude values;
  • country, state/division, county, ZIP code, census tract, and site fields;
  • coordinates resolved from MicrobeTrace’s bundled map data;
  • grouping samples that share coordinates into a common deme;
  • centroid calculation for named administrative demes;
  • partial or invalid coordinate data without blocking otherwise valid exports.
• Added temporal-tree support that:
  • preserves complete structured num_date values from imported Auspice datasets;
  • recognizes explicitly dated Newick annotations;
  • preserves supplied ancestral dates without inferring or modifying them;
  • falls back to divergence-only output when temporal data is incomplete or malformed.
• Improved Auspice importing and round trips by:
  • preserving the visual sibling order used by Auspice;
  • retaining structured num_date values internally;
  • selecting the configured or most useful geographic resolution;
  • restoring coordinates from site and MicrobeTrace-generated geographic resolutions;
  • rejecting invalid or out-of-range coordinates.
• Added validation and error handling for:
  • missing or duplicate tip IDs;
  • ambiguous session-node matches;
  • tree tips without exact session-node matches;
  • negative or non-finite branch lengths;
  • reserved, unsafe, and colliding metadata keys;
  • malformed coordinate strings.
• Added pinned official Auspice schema files and AJV-based schema validation.
• Added unit coverage for the exporter, dated-Newick parser, Auspice importer, geography, temporal data, field selection, palettes, bootstrap support, tree scope, and validation failures.
• Expanded Cypress coverage for:
  • Auspice export and re-import;
  • full-tree versus visible-subtree export;
  • metadata, coloring, and filter customization;
  • explicitly dated Newick export;
  • computed trees and uploaded-tree context-menu operations.
• Added synthetic fixtures covering Newick, FASTA, node lists, distance matrices, distance links, dated trees, geography, internal-node metadata, and validation failures.
• Added user documentation, example exports, manual test data, and a Nextstrain review packet containing compatibility results and outstanding review questions.

Validation

• Generated examples conform to the pinned official Auspice v2 schema.
• Documentation records successful augur validate export-v2 validation.
• Example datasets were verified with auspice.us and local auspice view.
• Rotation testing confirmed that exported trees retain MicrobeTrace’s displayed tip order.
• Exported datasets can be re-imported into MicrobeTrace with supported topology, metadata, dates, and coordinates retained.

Notes

• Export occurs entirely in the browser; MicrobeTrace does not upload the file.
• Users should avoid uploading identifiable or restricted data to public Auspice services and can use a local Auspice server when needed.
• The exporter intentionally does not infer ancestral dates or geography. Future work could incorporate rudimentary ancestral state reconstruction though.

Testing datasets

Synthetic testing fixtures are included for the supported input paths:

Full-feature input bundles cover Newick, FASTA, node-list, distance-matrix, and distance-link inputs.

Explicitly dated Newick fixtures verify preservation of supplied num_date values.

Manual and negative test fixtures cover duplicate or ambiguous IDs, invalid branch lengths, internal-node metadata, palettes, geography, and computed trees.

Ready-made Auspice examples include minimal, rich, and temporal-map datasets under docs/integrations/examples.

auspice-export-pr-test-bundle.zip