Episodic

A complete pipeline for fitting and testing Fixed Local Clock (FLC) molecular clock models for episodic evolution.

About

Episodic is a tool for fitting and testing Fixed Local Clock (FLC) molecular clock models for episodic evolution. The package is built on top of SNK, and provides a complete pipeline for fitting and testing models of episodic evolution using BEAST.

Episodic implements the ideas of Tay et al. (2022 and 2023) and detects episodic evolution through Bayesian inference of molecular clock models.

Given a multiple sequence alignment and a list of groups to test for episodic evolution, episodic will:

• Configure BEAST analyses for strict, relaxed (UCGD) and fixed local clock models.
• Configure marginal likelihood analyses for each clock model.
• Run all the BEAST and marginal likelihood analyses.
• Plot and summarise the results.
• Compute and plot Bayes factors for the marginal likelihood analyses.
• Produce maximum clade credibility (MCC) trees for each clock model.
• Compute bayes factor on effect size for the FLC models (foreground vs background).
• Run rank and quantile tests on the relaxed clock models.
• Handel the execution of the pipeline on a HPC cluster via snakemake profiles.
• Produce a report of the results (TBD).

Features

• Complete pipeline - episodic provides a complete pipeline for fitting and testing FLC models of episodic evolution.
• Flexible - episodic is built on top of SNK, and provides a flexible framework for fitting and testing FLC models of episodic evolution.
• Easy to use - episodic is easy to use, and provides a simple interface for fitting and testing FLC models of episodic evolution.
• robust - episodic is robust, and provides a robust framework for fitting and testing FLC models of episodic evolution.

Installation

pip install episodic

CLI

Multiple alignment partitions can be supplied by repeating --alignment.

episodic run \
    --alignment partition1.fasta \
    --alignment partition2.fasta \
    --group BA.2.86

Outputs

Episodic produces BEAST logs, trees, summary tables and plots under output.dir (optionally timestamped when output.dated: true).

For the complete output file reference (all targets, side-effect files, and optional branches), see:

• docs/workflow.md

Main output categories include:

• BEAST log files - episodic will produce a BEAST log file for each clock model. These files can be analysed with Beastiary.

• BEAST trees - episodic will produce a BEAST tree file for each clock model.

• MCC trees - episodic will produce a MCC tree for each clock model.

• MCC tree plots - episodic will produce a MCC tree plot for each clock model.

• Marginal likelihoods - episodic will produce a marginal likelihood plot for each clock model.

• Bayes factors on effect size - episodic will calculate a Bayes factors on effect size for each local clock model.

  Rate Column	p_p	p_odds	pos_p	pos_odds	bf
  BA.2.86.rate	0.5034996111543162	1.0140971134481986	1.0	inf	inf

• Rank and quantile tests - episodic will produce a rank and quantile test plot for each relaxed clock model.

• Partition local-rate posterior plots (FLC clocks) - overlaid background vs local posterior densities per partition.

• Clock rate plots - episodic will produce a rate plot for each clock model.

DAG

License

episodic is distributed under the terms of the MIT license.