Phylogenetic Tree Viewers
Relevant source files
The following files were used as context for generating this wiki page:
The Phylogenetic Tree Viewer system provides a sophisticated, interactive interface for exploring evolutionary relationships through tree structures. It integrates workspace data, metadata from the Data API, and high-performance rendering via the Archaeopteryx.js library to support both reference trees and user-provided tree files in Newick and phyloXML formats.
Sources: public/js/p3/widget/viewer/PhylogeneticTree.js:15-30, public/js/p3/widget/Phylogeny.js:55-70
Architecture and Component Hierarchy
The system follows a tiered architecture that separates state management, UI orchestration, and the core rendering engine.
1. Viewer Layer
The top-level components, PhylogeneticTree.js and PhylogeneticTree2.js, inherit from ViewerBase. They are responsible for:
- Interpreting the URL/state to locate tree files in the Workspace.
- Parsing ID and label types (e.g.,
genome_id,genome_name). - Fetching supplementary metadata via RQL queries to the Data API.
Sources: public/js/p3/widget/viewer/PhylogeneticTree.js:80-110, public/js/p3/widget/viewer/PhylogeneticTree2.js:105-130
2. Widget Layer
The Phylogeny.js and Phylogeny2.js widgets manage the visual layout, including the Action Bar and the interaction between the tree and the Item Detail Panel.
- Phylogeny.js: Often used for specific GTDB reference phylogenies.
- Phylogeny2.js: A more generalized widget for rendering trees directly from workspace files (nwk/phyloxml).
Sources: public/js/p3/widget/Phylogeny.js:50-100, public/js/p3/widget/Phylogeny2.js:60-110
3. Rendering Engine
Archaeopteryx.js serves as the underlying engine, utilizing D3.js for SVG-based tree manipulation. It handles complex features like node collapsing, color scaling based on metadata, and diverse display modes (Phylogram vs. Cladogram).
Sources: public/js/archaeopteryx/archaeopteryx-dependencies/archaeopteryx.js:1500-1550
The diagram above illustrates the data flow from the initial request to the final rendering and selection management.
Data Processing and Metadata Enrichment
Before a tree is rendered, the system often performs a "findLabels" step. If the tree file contains internal IDs (like genome IDs), the viewer queries the Data API to retrieve human-readable labels (like genome names).
Label Retrieval Flow
- Regex Matching: The system extracts IDs from the Newick/phyloXML string.
- RQL Batch Query: A POST request is sent to the
/genomeor/genome_featureendpoint. - Data Mapping: The resulting docs are mapped into a
labelsobject where keys are IDs and values are display names.
Sources: public/js/p3/widget/viewer/PhylogeneticTree.js:180-210, public/js/p3/widget/viewer/PhylogeneticTree2.js:205-230
| Parameter | Type | Description |
|---|---|---|
idType | String | The identifier field used in the tree (default: genome_id). |
labelType | String | The field to retrieve for node labels (default: genome_name). |
wsTreeFile | String | Path to the tree file in the workspace. |
labelSearch | Boolean | Whether to perform an API lookup for labels. |
Sources: public/js/p3/widget/viewer/PhylogeneticTree.js:90-105, public/js/p3/widget/viewer/PhylogeneticTree2.js:115-130
Visualization Capabilities
Archaeopteryx.js enables high-density annotation through multiple visual channels. These configurations are initialized in the pre_build_options and processTree methods of the Phylogeny widgets.
Visual Trait Mapping
Nodes can be dynamically styled based on their properties:
- Color Selection: Map categorical data (e.g., Country, Host) or linear gradients (e.g., Year) to node fill or label colors.
- Shape Selection: Assign unique shapes (square, diamond, triangle) to specific properties.
- Size Scaling: Adjust node size based on numerical values.
Sources: public/js/archaeopteryx/archaeopteryx-dependencies/archaeopteryx.js:1600-1650, public/js/p3/widget/Phylogeny.js:130-160
Interaction Modes
| Feature | Functionality |
|---|---|
| Reroot | Re-calculates tree topology with a selected node as the root. |
| Swap | Swaps the position of child nodes at a branch point. |
| Collapse | Collapses subtrees at a specific depth or based on common features (e.g., species). |
| Subtree Exploration | Navigates into a specific branch, making it the temporary root. |
Sources: public/js/archaeopteryx/archaeopteryx-dependencies/archaeopteryx.js:2350-2450, public/js/p3/widget/Phylogeny2.js:550-600
This sequence diagram shows how user interactions with the tree trigger metadata retrieval to populate the detail panel.
Implementation Details
Viewer Data Preparation
The prepareTree function handles the handoff from the data retrieval phase to the widget processing phase. It decides whether to initiate a label search or process the data directly.
prepareTree: function (treeDat, idType, labelType, labelSearch, fileType) {
if (labelSearch) {
this.findLabels(treeDat, idType, labelType, fileType);
}
else {
this.viewer.processTreeData(treeDat, idType, fileType);
}
}
Sources: public/js/p3/widget/viewer/PhylogeneticTree2.js:195-203
Integration with Workspace
The viewers check for specific workspace file extensions and object types. For example, PhylogeneticTree.js looks for .nwk files named treeWithGenomeIds.nwk or treeWithGenomeNames.nwk inside result folders.
Sources: public/js/p3/widget/viewer/PhylogeneticTree.js:125-140
Archaeopteryx Launch Configuration
When launching the rendering engine, the widget provides a settings object containing UI constraints and an options object containing visual defaults.
var settings = {
border: '1px solid #909090',
controls0Top: 10,
enableAccessToDatabases: true,
enableDownloads: true,
allowManualNodeSelection: true
};
Sources: public/js/p3/widget/Phylogeny.js:165-180
The Phylogenetic Tree Viewers provide a critical bridge between raw sequence analysis results and biological interpretation. By combining flexible data loading from the workspace with rich, interactive visualizations, they allow researchers to identify clusters, detect evolutionary trends, and integrate diverse metadata directly into the context of genomic relationships.