This is swMutSel, a program to estimate fitnesses of amino acids in protein-
coding genes using the evolution model of Halpern and Bruno (1998) and Tamuri et
al. (2012, 2014). The program takes as input an alignment of protein-coding
gene sequences and a phylogeny (tree) of the sequences, and outputs the
fitnesses of each amino acid at each location in the protein-coding gene.
SYNOPSIS
Analyse Data Using the SwMutSel Model:
java -jar swmutsel.jar
-name <run_name>
-sequences <sequence_file_name>
-tree <tree_file_name | tree_newick_string>
-geneticcode <standard | vertebrate_mit | plastid>
[-penalty mvn,<sigma> | dirichlet,<alpha>]
[-kappa <kappa>]
[-pi <T>,<C>,<A>,<G>]
[-scaling <branch_scaling_factor>]
[-fitness <site>,A,R,N,D,C,Q,E,G,H,I,L,K,M,F,P,S,T,W,Y,V [-fitness ...], ...]
[-fix mutation|branches|all [-fix mutation|branches|all], ...]
[-threads <cpu_cores>]
[-distributed -host <host>:<port> [-host <host>:<port>], ...]
[-sites <site>|<site_range>]
[-restart-opt <no_of_restarts> [-restart-int <n_iterations>]]
[-clademodel clade_label,clade_label[,clade_label[,...]]]
[-hessian]
[-help]
Simulate Data Using the SwMutSel Model:
java -jar swmutsel.jar
-simulate
-name <run_name>
-tree <tree_file_name | tree_newick_string>
-geneticcode <standard | vertebrate_mit | plastid>
-sites <number_of_sites>
-kappa <kappa>
-pi <T>,<C>,<A>,<G>
-scaling <branch_scaling_factor>
[-fitness A,R,N,D,C,Q,E,G,H,I,L,K,M,F,P,S,T,W,Y,V [-fitness ...], ...]
[-fitnessfile <filename> [-fitnessfile <filename>], ...]
[-clademodel <clade_labels>]
[-shiftfrac <percentage>]
OPTIONS
Required
-n, -name
Specifies name for the run. Output files are prefixed with this name.
Be careful! The program will overwrite files with the same name.
-s, -sequences
Coding sequences alignment file name in PHYLIP format. Spaces are
not allowed in sequence names.
-t, -tree
Newick-formatted tree file name. The tree string can be supplied
instead e.g. "-tree (A:0.1,(B:0.1,C:0.1));". Spaces are not allowed
in the string.
-gc, -geneticcode
The genetic code for the coding-sequences:
-gc standard : The Standard Code
-gc vertebrate_mit : The Vertbrate Mitochondrial Code
-gc plastid : The Bacterial, Archaeal and Plant Plastid Code
Model Parameters
-p, -penalty
The penalty to use for the penalised likelihood method. If not
supplied, the usual (unpenalised) maximum likelihood method is used.
Valid options are:
-p mvn,<s> : Multivariate normal penalty with variance 2*<s>^2
-p dirichlet,<a> : Dirichlet-based penalty with shape <a>
-k, -kappa
The starting parameter value for the transition-transversion rate
ratio. If you "-fix mutation" the parameter will not be estimated.
DEFAULT: 1.0
-pi
The starting parameter value for nucleotide base frequencies. Must
be comma-separated with order T,C,A,G. The values are normalised to
sum to 1. If you "-fix mutation" the parameter will not be estimated.
DEFAULT: [0.25]
-c, -scaling
The starting parameter value for branch scaling factor (applied to
all branches). If you "-fix mutation" the parameter will not be
estimated.
DEFAULT: 1.0
-f, -fitness
Comma-separated fitness parameters in canonical amino acid order.
It is recommended that you do not construct these by hand but
rather use the output generated by the program itself.
DEFAULT: [0]
Optimisation
-fix
Indicate whether you want the program to skip estimation of
mutational parameters, branch lengths or all parameters. For example,
if you want to calculate fitness only: "-fix mutation -fix branches"
-fix mutation : Fix the values (k, pi, c) of the mutational
model.
-fix branches : Fix the branch lengths on the tree.
-fix all : Calculate the log-likelihood only.
-restart-opt
Specifies the number of optimiser restarts for site-wise fitness
parameter estimation. The is to prevent estimates being stuck at a
local optima. The program will restart fitness estimation, with
random initial values, the specified number of times.
DEFAULT: 1
-restart-int
Specify how often to estimate fitness parameters with multiple
restarts. Restarting the fitness parameter estimation is expensive
and, in many cases, not necessary. The value supplied here defines
how frequently to perform the robust fitness estimation, where a
single round is one iteration of mutation, branch length and fitness
estimation.
DEFAULT: 5
-sites
Specify a single site, or a range of sites, for site-wise fitness
estimation. If you provide this option, you implicitly fix the
mutation and branch length parameters, "-fix mutation,branches".
A range is specified using a dash e.g. "-sites 10-20" will estimate
the site-wise fitnesses for all sites between site 10 and site 20,
inclusive.
Parallelisation
-T, -threads
Specify the number of cores to use for multi-threaded operation.
-D, -distributed
Indicate the program will run in distributed mode. This requires the
initialisation of (usually) multiple slaves. Each slave will have
an associated IP address (or hostname) and port (which you supply
using "-H")
-H, -host
If the program is running in distributed mode (using the "-D" option),
supply slaves' host IP and port using "-H <slave_ip>:<port>"
USAGE
Simplest example:
java -jar swmutsel.jar -n test -s aln.phy -t aln.tree -gc standard
Options can also be placed in file but each argument should be on a new
line. For example:
cat > test_options.txt
-s
aln.phy
-t
aln.tree
-gc
standard
^D
Note each space in a typical command-line argument becomes a newline. You
can now run the program using:
java -jar swmutsel.jar @test_options.txt -n test
During parameter optimisation, the program will write checkpoint files.
You can restart the program from a saved checkpoint, for example:
java -jar swmutsel.jar @test_CHKPNT_9.txt -n test_restart
CITATION
Halpern AL and Bruno WJ. (1998) Evolutionary distances for protein-coding
sequences: modeling site-specific residue frequencies. Molecular Biology
and Evolution, 15: 910-917.
Tamuri AU, dos Reis M and Goldstein R. (2012) Estimating the distribution
of selection coefficients from phylogenetic data using sitewise mutation-
selection models. Genetics, 190: 1101-1115.
Tamuri AU, Goldman N and dos Reis M. (2014) A penalized likelihood method
for estimating the distribution of selection coefficients from
phylogenetic data. Genetics, 197: 257-271.