Molecular dating analysis

Posted on In
Molecular Dating Analysis Using PhyloSuite v2

This tutorial uses a set of example data to provide detailed guidance on how to efficiently and accurately perform the entire workflow of molecular dating analysis and visualization using PhyloSuite v2, offering researchers a user-friendly solution.

Figure 1. PhyloSuite Molecular Dating Analysis Suite Entry

Users can hover over the “Phylogeny” option on the main PhyloSuite interface (Figure 1) and find three plugins in the dropdown menu: MDGUI, TimeTreeAnno, MCMCTracer.

System Requirements & Download

PhyloSuite is mainly written in Python and is compiled for Windows, Mac OS, and Linux versions. To avoid missing dependencies, it is recommended to download the version with bundled plugins. The latest version of PhyloSuite can be downloaded from: http://phylosuite.jushengwu.com/dongzhang0725.github.io/installation/#Chinese_download_link

Tips: Users can download example files from the official website to test the software and debug: http://phylosuite.jushengwu.com/example.zip

1. MDGUI-MCMCtree

MDGUI includes two components: MCMCtree and r8s. Users can select based on their needs.

1.1 File Input & Preparation

Figure 1.1a. Drag-and-Drop File Import in MDGUI
  1. Sequence Alignment File (Alignment): Drag multi-sequence alignment files (FASTA, NEXUS, PHYLIP formats supported) into the file input box (Figure 1.1a).
  2. Tree File (Treefile): Similarly, import a tree file with species phylogenetic relationships (recommended in nwk format). Tips: MDGUI supports three import methods: drag-and-drop, button import, or automatic import from upstream results (see Figures 1.1b, 1.1c).
  3. After importing, the program will automatically detect the sequence type (AAs, nucleotides, codon) and display it in the “seqtype” option.
  4. After importing the tree, click “Add calibration points in tree” to open the fossil calibration visualization interface (see Section 1.1.1).
  5. The software automatically detects the number of species and displays it. Ensure species names match between alignment and tree files; mismatches will trigger a warning.

Tips: MCMCtree requires a rooted tree, and the root must have a calibration point. Otherwise, MDGUI will prompt an error during the run. See next section for solutions.

Tips: For viral sequences with temporal information in sequence names, enable “Enabling tip-dating analyses” for tip-dating analyses (link).

Figure 1.1b. Automatic Import from Upstream Analysis in MDGUI
  1. At startup, MDGUI automatically detects results from upstream programs (IQ-TREE, MrBayes, FastTree) and prompts for selection (Figure 1.1b).
  2. Choose the folder containing the results to import.
  3. PhyloSuite automatically populates the “Alignment” and “Treefile” input boxes.

Figure 1.1c. Button-Based File Import in MDGUI
  1. Click the folder icon next to “Alignment” or “Treefile” to open a file browser (Figure 1.1c).
  2. Files are filtered for compatible types; select the file and click “Open”.

1.1.1 Adding Fossil Calibration Points

Figure 1.2. Fossil Calibration Visualization Interface
  1. Right-click a node to add or remove calibration information.
  2. For unrooted trees, select a root node and use “set as outgroup (root tree)”.
  3. Click “Add calibration” to open the settings dialog with three tabs: “MCMCtree”, “MCMCtree root node”, and “r8s” (Figure 1.3a).
  4. “Remove calibration” deletes all calibration info for that node.
  5. Save settings with the “M” button or close the dialog.
  6. For r8s analysis, save all r8s calibration info with the “r” button.

Tips: MCMCtree requires a root node calibration.

Figure 1.3a. Setting MCMCtree Root Node Calibration
  1. Set root node time in the “MCMCtree root node” tab, or use the Rootage parameter on the main interface.

Figure 1.3b. Setting MCMCtree Fossil Calibrations
  1. Set calibration for other nodes in the “MCMCtree” tab (Figure 1.3b).
    Common soft-bound formats:
  • Between bounds: “>0.06<0.08” or “B(0.06,0.08)”
  • Minimum only: “>0.06” or “L(0.06)”
  • Maximum only: “<0.08” or “U(0.08)”
    Soft bounds allow small probability (e.g., 2.5%) to exceed limits.
    Advanced distributions:
  • Gamma: “G(alpha,beta)”
  • Skew Normal: “SN(location,scale,shape)”
  • Skew t: “ST(location,scale,shape,df)”

Figure 1.3c. Setting r8s Fossil Calibration
  1. Use “r8s” tab when analyzing with r8s.
  2. Select supported formats, modify values, click “OK”.
    r8s commands for node ages: calibration, constraint, fixage, unfixage node.

1.1.2 Parameter Settings

Figure 1.4. MDGUI-MCMCtree Parameter Settings

MDGUI simplifies parameter settings and automates some MCMCtree steps. Key points:

  1. burnin: set as proportion (e.g., 10%).
  2. usedata: approximate likelihood mode automates Hessian matrix calculation.
  3. Thread: run multiple independent MCMC chains; results merged automatically.
  4. Repeat for convergence: divides chains into 2 repeats for convergence check.

Figure 1.4a. Supported Models in MDGUI-MCMCtree
  1. model: choose from extensive nucleotide, codon, amino acid models. Use “AUTO” for automatic selection with ModelFinder.
  2. Program for generating Hessian matrix: choose MCMCtree or IQ-TREE (supports more models and mixture models).
  3. Using mixture models: recommended when IQ-TREE is selected.

Figure 1.4b. Preview/Edit Configuration
  1. Click “Preview/Edit configuration” to manually edit the generated mcmctree.ctl file and run MCMCtree.

1.2 Running & Real-Time Monitoring

1.2.1 Start Analysis

Figure 1.5. Start MDGUI Analysis
  1. Click “Start” to run.
  2. Modify working directory or output folder name; defaults to “myWorkplace/MOLDAT_results”.

1.2.2 Real-Time Status

Figure 1.6. MDGUI Run Log
  1. Logs show current status; can be saved via “Save to file”.
  2. Click “MCMCTracer” to summarize MCMC samples and check convergence in real-time.

1.2.3 Pause & Resume

Figure 1.7. MDGUI Pause & Resume
  1. Pause: click “Stop”; checkpoints saved.
  2. Resume: click “Continue Previous Analysis” and select folder.

1.2.4 MCMC Summarization

Figure 1.8. Summarize MCMC Results
  1. Click “Summarize MCMC samples and infer time tree” to summarize samples and generate time tree.
  2. Import summarized results into MCMCTracer for plotting and analysis.

1.3 Output Files

Figure 1.9. Post-Run Import to Visualization

1.3.1 Folder Naming

Default folder name: analysis start timestamp. Can be customized.

1.3.1.1 Without “Repeat for Convergence”

Figure 1.10a. Folder Contents without Repeat

Contains run folders, all_mcmc_runs.txt, summarization.out, FigTree.tre.

1.3.1.2 With “Repeat for Convergence”

Figure 1.10b. Folder Contents with Repeat

Contains repeat1 and repeat2 folders, each with run folders; merged outputs also generated.

2. MCMCTracer

MCMCTracer performs statistical analysis, visualization, and convergence diagnostics for MCMC samples (Figure 2.1).

2.1 Trace Tab

Figure 2.1. MCMCTracer Main Interface
  1. Import files via button or drag-and-drop.
  2. Displays all data columns for selection; visualized as Trace, Histogram, Scatter Plot.
  3. Summary statistics show mean, median, 95% CI, ESS, etc.
  4. Export plots in multiple formats.

2.2 Convergence Tab

Figure 2.2. MCMCTracer Convergence Diagnostics
  1. Compare repeat1 and repeat2, or independent chains.
  2. Automatic extraction of summarization.out.txt; scatter plot y=x shows convergence.
  3. Export convergence plots in PNG, JPEG, SVG, PDF.

3. TimeTreeAnno

TimeTreeAnno visualizes and annotates time trees from MCMCtree, BEAST, r8s, MrBayes, etc.

3.1 File Import & Visualization

Figure 3.1. TimeTreeAnno Main Interface
  1. Import tree via button or drag-and-drop.
  2. Select time unit (1MYA/100MYA).
  3. Interface displays file name; right-side panel allows element customization.

Figure 3.2. Annotated Time Tree
  1. TREE tab: adjust size, colors, background.
  2. NODE tab: list nodes, colors, copy names.
  3. ANNOTATION tab: add labels, cluster colors.
  4. Click “Update Figure” to apply changes.

3.2 Export Figures

Figure 3.3. Export TimeTreeAnno Figures
  1. File → Save as; choose format: JPEG, PNG, SVG, PDF.

4. MDGUI-r8s

r8s workflow similar to MCMCtree, but calibration formats and saving differ.

4.1 File Input & Preparation

Figure 4.1. MDGUI-r8s Main Interface (Linux/Mac)
  1. Import alignment and tree as before.

Tips: Windows uses pyr8s; Linux/Mac uses native r8s.

4.1.1 Parameter Settings

Figure 4.2a. Describe Settings
  1. Select output content: cladogram, phylo_description, node_info.

Figure 4.2b. MDGUI-r8s Parameter Settings
  1. Preview/Edit configuration: modify r8s_cmd_data.txt.
  2. Generate config file to run in terminal.

4.2 Results & Output

4.2.1 Folder Naming

Figure 4.3. Rename r8s Result Folder
  1. Default: analysis timestamp; can customize.

4.2.2 Folder Contents

Figure 4.4. r8s Result Folder
  1. Output files depend on describe/plot options: cladogram, chronogram, ratogram.nwk.
  2. r8s_cmd_data.txt contains full commands and tree info.

5. FAQ

5.1

Acknowledgements

Thanks to the PhyloSuite user community for feedback that helped improve the software.