Evolutionary Rate View

⚠️ Feature in development: This feature is in development and is not yet available on the main MicrobeTrace site.

The Evolutionary Rate view compares sample collection dates with genetic distance to estimate how quickly genetic change accumulates over time. Use it to:

1. Estimate an evolutionary rate from sequence-based SNP or TN93 distances.
2. Estimate an evolutionary rate from root-to-tip distances in a phylogenetic tree.
3. Review potential outliers and export the plot, statistics, or a diagnostic report.

Use case 1: Estimate an evolutionary rate from sequence data

Before you begin

Prepare:

• A FASTA file containing your sequences.
• A node metadata file with one row per sample, an identifier that matches the FASTA sequence names, and a sample collection date field. Dates in YYYY-MM-DD format are recommended.
• At least two samples with different valid collection dates.

You can practice with the FASTA and metadata files in the evolutionary-rate examples.

Steps

1. From the Files view, select Add File(s) and add both the FASTA file and its node metadata file.
2. Confirm that the metadata file is classified as Node data and the sequence file is classified as FASTA data.
3. For the metadata file, choose the field that matches the FASTA sequence names under ID.
4. Select Launch.

5. Open View, then select Evolutionary Rate.
6. Select the settings button in the upper-left corner of the view.
7. On the Data tab, choose the field containing the collection dates under Sample Collection Date.

Before a date field is selected, the view prompts you to choose one:

MicrobeTrace automatically uses the active sequence distance. With SNP distance selected, the reference is the earliest dated sample included in the analysis.

8. Close the settings dialog to review the regression plot and summary statistics.

Understand the results

• Each point represents one sample. The horizontal axis shows the collection date, and the vertical axis shows the active genetic-distance measurement.
• The dashed line is the fitted linear regression.
• Slope (rate) is the estimated genetic change per year. Its units follow the active distance setting, such as SNPs per year or TN93 distance per year.
• X-intercept (TMRCA) is the date where the fitted line reaches zero distance. Treat dates far outside the observed date range cautiously.
• Correlation Coefficient describes the direction and strength of the linear association.
• R² shows the proportion of distance variation explained by collection date in this linear model.
• Residual Mean Squared summarizes the average squared difference between observed and fitted distances.
• The count below the plot shows how many currently visible samples were included or excluded from the calculation.

To analyze TN93 distance instead, open Settings, choose Filtering, and change the global genetic distance measure to TN93. If percentage display is enabled, the vertical axis and rate are shown as percentages.

Customize the view

Steps

1. Select the settings button in the Evolutionary Rate view.
2. Open the Appearance tab.
3. Use Table to show or hide the statistics table.
4. Expand Labels and Tooltips to choose a label field, label size and orientation, and one or more tooltip fields.
5. Expand Shapes and Sizes to set a fixed point size or size points by a numeric node field.
6. Expand Colors to adjust point and regression-line colors.

Global node colors and shapes are also reflected in this view, so the same samples can be recognized across MicrobeTrace visualizations.

Use case 2: Analyze a phylogenetic tree

Before you begin

Prepare:

• A Newick tree with named tips and branch lengths.
• A node metadata file whose identifiers match the tree tip names and that contains a sample collection date field.

You can practice with the Newick and metadata files in the evolutionary-rate examples.

Steps

1. Add the Newick tree and node metadata file in the Files view, confirm their file types, and select Launch.

2. Open View, then select Evolutionary Rate.

3. Open the Evolutionary Rate settings and select the collection date field.

4. Under Root Position, choose one of the following:

   • As provided uses the root in the uploaded Newick tree.
   • Best fit searches positions along the tree and uses the root position that produces the best-fitting date-to-distance regression.

The vertical axis now shows patristic root-to-tip distance. If Best fit is selected, the distance label indicates that the fitted root is being used.

Use case 3: Review potential outliers

Potential outliers are samples whose absolute regression residual is at least two times the residual root mean squared error (RMSE). At least three analyzable points are required. These flags help identify samples for follow-up; they do not by themselves prove that a date, sequence, or tree position is incorrect.

Steps

1. Create the Evolutionary Rate view and choose the collection date field.
2. Look for points outlined by a red dashed box and the Potential outlier (≥ 2 × RMSE) legend.
3. Hover over a point to review its sample information and fitted residual.
4. Check the source metadata, sequence quality, distance choice, and possible epidemiologic explanation before deciding whether to correct or exclude a sample.

Export an outlier report

1. Select the export button in the upper-left corner of the Evolutionary Rate view.
2. Open the Outlier Report tab.
3. Enter a filename.
4. Choose PDF or Markdown, then select Export.

The report includes the regression plot, analysis summary, potential-outlier table, excluded-data section, and suggested follow-up checks.

Work with selections and filters

• Filters limit the analysis to nodes that are currently visible.
• Selecting nodes in a linked view recalculates the regression and statistics for the selected subset while keeping the other visible points on the plot for context.
• Select a point in the Evolutionary Rate plot to select the same node elsewhere in MicrobeTrace. Use Ctrl on Windows or Command on macOS while selecting to build a multi-node selection.
• When the selected subset contains an entire cluster, MicrobeTrace labels the analysis with that cluster name.
• Select the excluded-data count to see which samples were omitted and why. Common causes are a missing or invalid date, a missing active distance, or a tree tip without a usable branch-length path.

Export results

Select the export button in the Evolutionary Rate view, then choose:

• Regression Plot Image for PNG, JPEG, WEBP, or SVG output. Raster exports include scale and quality controls; visible statistics and applicable key tables are included.
• Statistics Table for a CSV file containing the regression summary.
• Outlier Report for a PDF or Markdown diagnostic report.

Helpful controls

• Settings: Select the gear button in the Evolutionary Rate view to change the date field, root method, statistics-table visibility, labels, tooltips, point sizes, and colors.
• Excluded data: Select the numbered excluded-data button to inspect omitted samples and the reason for each omission.
• Global colors and shapes: Use MicrobeTrace's global settings when you want consistent sample styling across multiple views.
• Filters and selections: Use the global filtering and linked-selection tools to focus the calculation on a subset without creating a new dataset.

Quick troubleshooting

• The plot asks for a date field: Open Evolutionary Rate settings and choose the node field containing sample collection dates.
• The plot says there are not enough valid points: Confirm that at least two visible or selected samples have valid dates, finite distances, and different collection dates.
• Many samples are excluded: Select the excluded-data count and correct the listed date, distance, identifier, or tree branch-length problems.
• Sequence distance is unavailable: Confirm that sequence data were loaded and that an active SNP or TN93 distance was calculated.
• Tree distance is unavailable: Confirm that the Newick tree has named tips, branch lengths, and identifiers that match the node metadata.
• No potential outliers appear: Outlier classification requires at least three analyzable samples and measurable residual variation. A perfect or nearly perfect fit may have no outliers.
• The TMRCA looks implausible: Check the date field, active distance, selected subset, tree root method, and whether a linear clock-like relationship is appropriate for the data.