With Anaconda already setup, Phyloacc can be installed with the command conda install phyloacc. For more detailed installation instructions, see the install page.

Note that PhyloAcc is currently only compatible on Linux and OSX operating systems, though can be run on Windows with the Windows Subsystem for Linux (WSL).

You will need the following data to perform an analysis with PhyloAcc

1. A set of alignments for a set of species from the regions you wish to estimate substitution rates for (e.g. CNEEs).
2. A phylogenetic tree in Newick format from the same set of species with branch lengths estimated in terms of relative number of substitutions corresponding to neutral/background substitution rates.
3. A transition rate matrix for bases in the neutral/background model.

(2) and (3) can be obtained running phyloFit on alignments of likely neutrally evolving sites (e.g. 4-fold degenerate sites in genes) and will be given in a single .mod file output from that program.

4. For running the gene tree model, a phylogenetic tree with the same topology as the one provided in (2), but with branch lengths in coalescent units. This can be obtained from species tree inference methods like MP-EST or ASTRAL. PhyloAcc has the capability to to estimate this directly from the input alignments with the --theta option, by building locus trees using IQ-TREE and then using those as input to ASTRAL. This will be done for at most the 5000 longest alignments that are longer than 100bp and have at least 20% informative sites. These requirements are to ensure there is phylogenetic signal to infer this tree given that some inputs to PhyloAcc may be conserved and have few variable sites. However, you must be sure the alignments you are estimating rates for with PhyloAcc are also suitable for tree inference if you use this option. Also note that using the --theta option may significantly add to the runtime of the workflow.

PhyloAcc version 2 now facilitates parallelization on computing clusters by using Python to batch loci and Snakemake to submit those batches to the cluster. This results in a three-step process to run PhyloAcc:

1. Process and batch input alignments with the PhyloAcc interface (phyloacc.py).
2. Submit the batches as jobs on the SLURM cluster (snakemake [generated snakefile]).
3. Gather outputs from batches into single files (phyloacc-post.py).

Below we outline several ways to batch loci ("Setting up batches") as well as examples of how to submit the snakefile and gather the outputs.

NOTE: As of v2.3.1, you can now specify options to the phyloacc.py script in two ways:

1. By passing the options in the command line (e.g. phyloacc.py -d [alignment directory] -m [mod file] -o [output directory] ...), as outlined here.
2. By specifying the option and value in a config file (e.g. phyloacc.py --config [config file]). See below for more info.

phyloacc.py \
    -d [directory containing multiple FASTA formatted nucleotide alignments] \
    -m [mod file from phyloFit with input tree and neutral rate matrix] \
    -o [desired output directory] \
    -t "[semi-colon separated list of target branches in the species tree]" \
    -j [number of jobs/batches to split the input alignments into] \
    -p [processes to use per job/batch of alignments] \
    -batch [number of alignments per job/batch] \
    -part "[comma separated list of SLURM partitions to submit batches to as jobs]"

phyloacc.py \
    -d [directory containing multiple FASTA formatted nucleotide alignments] \
    -m [mod file from phyloFit with input tree and neutral rate matrix] \
    -r gt \
    -l [file with Newick formatted species tree with branch lengths in coalescent units] \
    -o [desired output directory] \
    -t "[semi-colon separated list of target branches in the species tree]" \
    -j [number of jobs/batches to split the input alignments into] \
    -p [processes to use per job/batch of alignments] \
    -batch [number of alignments per job/batch] \
    -part "[comma separated list of SLURM partitions to submit batches to as jobs]"

phyloacc.py \
    -d [directory containing multiple FASTA formatted nucleotide alignments] \
    -m [mod file from phyloFit with input tree and neutral rate matrix] \
    -r adaptive \
    -l [file with Newick formatted species tree with branch lengths in coalescent units] \
    -o [desired output directory] \
    -t "[semi-colon separated list of target branches in the species tree]" \
    -j [number of jobs/batches to split the input alignments into] \
    -p [processes to use per job/batch of alignments] \
    -batch [number of alignments per job/batch] \
    -part "[comma separated list of SLURM partitions to submit batches to as jobs]"

Starting with v2.3.1, options for phyloacc.py can be specified either in the command line, as above, or in a configuration file in YAML format and by using the --config [config file] syntax.

We provide a template config file, which lists all the options for phyloacc.py with no values specified: Config file template.

In this file, options are specified in key: value pairs, with the key being the option name to the left of the colon and the desired value being to the right of the colon.

For example, one could run the program with the following command:

phyloacc.py -a alignment.fa -b loci.bed -m model.mod -t "species1;species2;species3"

OR one could specify the same options in a config file named phyloacc-cfg.yaml like so:

alignment: alignment.fa
bed: loci.bed
mod: model.mod
targets: "species1;species2;species3"

And then run the program with the following command:

phyloacc.py --config phyloacc-cfg.yaml

These are identical ways to run the same inputs.

IMPORTANT: Options given via the command line take precedence over those givin in the config file.

For instance, if I use the same config file above, but run the command:

phyloacc.py --config phyloacc-cfg.yaml -a other_alignment.fa

Then the alignment.fa input in the config file will be ignored and other_alignment.fa will be used instead.

If an option is not specified in either the command line or the config file, a default value will be used. See the Options section for more details.

Boolean options in the config file

For boolean options in the config file (theta_flag, dollo_flag, overwrite_flag, labeltree, summarize_flag, filter_alns, options_flag, append_log_flag, info_flag, version_flag, quiet_flag), you can specify them in the config file as either true or false. In other words:

phyloacc.py --config phyloacc-cfg.yaml --overwrite

is equivalent to setting

overwrite_flag: true

in the config file and running

phyloacc.py --config phyloacc-cfg.yaml

In practice, for many of these boolean options, using the command line option may be easier than changing the config file each time.

snakemake -p -s \
    [path to snakefile.smk] \
    --configfile [path to config file] \
    --profile [path to cluster profile] \
    --dryrun

Note that all files for the snakemake command are automatically generated when running phyloacc.py and the exact command to run will be printed to the screen and written to the log and summary files.

phyloacc_post.py \
    -i [path output directory specified when running phyloacc.py]

After running phyloacc_post.py, outputs from each batch will be combined and a summary HTML file will be created with some preliminary summaries of results. This file will be found in the main output directory from the phyloacc.py command (specified with the -o option).

Raw output files are also available in the output directory specified with phyloacc_post.py, with the default directory name being results/.

The raw files are tab delimited and described below.

Marginal log-likelihood for all models (integrating out parameters and latent states), Bayes factors, rates, and states for each locus.

Maximum log-likelihood configurations of latent state Z under null, accelerated and full model, with Z=-1 (if the element is 'missing' in the branches of outgroup species), 0 (background), 1 (conserved), 2 (accelerated).

Each row corresponds to an input element and each column a branch in the tree. If an element is filtered because of too many alignment gaps all the columns will be zero.

Posterior median of conserved rate, accelerated rate, probability of gain and loss conservation (and \(\beta = P(Z=1\rightarrow Z=2)\)), and posterior probability of being in each latent state on each branch for each element.

From the 7th column and on, there are four columns for each branch in the tree: *_0 indicates whether it's "missing"; *_1, *_2 and *_3 are the posterior probability in the background, conserved and accelerated state respectively. The algorithm will prune "missing" branches within outgroup and set the latent states of them to -1 so that the three posterior probabilities are all zero. Column names indicate the branch and the order of the branch is the same as that in prefix_elem_Z.txt.

Below are the options available for the phyloacc.py script. The REQUIRED options are:

• Sequences: one of (-a and -b) or -d
• Tree and model: -m
• Target species: -t
• Cluster partition: -part

All other parameters are optional or have default values. Options can be specified in the command line or in a config file. While they are optional, it is encouraged to optimize the workflow by specifying the options that are relevant to your analysis. Specifically, a named output directory (-o) will help you organize your files. And the batching and cluster options should be set to match the resources available to you.

Also note that while a cluster partition is required to be specified with -part, if you do not wish to run the resulting batches on a cluster you can specify any string since no checks are done to ensure the partition exists. Then you can run the batches via snakemake without specifying the --profile option, or run the batches individually with the config files generated in [your output directory]/phyloacc-job-files/cfgs/. Though due to the run-time of the model, it his highly recommended to run the batches on a cluster with dedicated compute nodes.