Saturday, 18 June 2016

Detecting pervasive positive selection with site-models from CodeML / PAML

Disclaimer: Please don't hesitate to contact me (rstuder [at] ebi [dot] ac [dot] uk) if there is anything which is not working on your computer, or any thing unclear, or even comments to improve it.


Theoretical principles:
 
When mutations are advantageous for the fitness, they are propagated at a higher rate in the population. The selective pressure can be computed by the dN/dS ratio (ω). dS represents the synonymous rate (keeping the same amino acid) and dN the non-synonymous rate (changing the amino acid). In the absence of evolutionary pressure (genetic drift), the synonymous and non-synonymous rates are supposed to be equal, so the dN/dS ratio is equal to 1. Under purifying selection, natural selection prevents the replacement of amino acidS, so the dN will be lower than the dS, and dN/dS < 1. And under positive selection, when mutations are advantageous for the fitness, they are propagated at a higher rate in the population, so the replacement rate of amino acid is favoured by selection, and dN/dS > 1.

We can distinguish two types of positive selection: pervasive positive selection and episodic positive selection. The former implies that a site will be under continuous changes (i.e. adapting to pathogens under arm-race), while the later implies that a site will change once and then be kept in the clade (i.e. providing an advantage in a new environment). We can detect the later using the branch-site model, for which I wrote the previous tutorial:

http://evosite3d.blogspot.co.uk/2011/09/identifying-positive-selection-in.html

To detect pervasive positive selection, we will use the site models from CodeML/PAML. Those models allow the clustering of aligned columns (sites) in different groups, each group having a different dN/dS value. There are many different sites models in CodeML, all assuming that the dN/dS ratio is the same across branches, but different between sites.


Here are the different models we will use in this tutorial:

M0: one unique dN/dS for all sites. This is the most basic model.

M1a: assumes two categories of sites: sites with dN/dS<1 (negative selection) and sites with dN/dS =1 (neutral evolution).

M2a: assumes three categories of sites: sites with dN/dS<1 (negative selection), sites with dN/dS=1 (neutral evolution) and sites with dN/dS>=1 (positive selection).

M3: assumes multiple categories of selection, not necessarily positive selection.

M7:
assumes 10 categories following a beta-distribution of sites, all with different dN/dS <=1.

M8: assumes 10 categories following a beta-distribution of sites, grouped, all with
different dN/dS <=1, and an additional 11th category with dN/dS >=1 (positive selection allowed).

M8a: assumes 10 categories following a beta-distribution of sites, grouped, all with dN/dS <=1, and an additional 11th
category with dN/dS =1 (no positive selection allowed).



Requirements:

For this practical, you will have to install some tools and downloadS some of my scripts.

- Python2: https://www.python.org/
- BioPython: http://biopython.org/
- Jalview: http://www.jalview.org/
- MAFFT: http://mafft.cbrc.jp/alignment/software/
- Newick utilities: http://cegg.unige.ch/newick_utils
- PAML: http://abacus.gene.ucl.ac.uk/software/paml.html
- PyMOL: https://www.pymol.org/
- R: https://www.r-project.org/
- RevTrans: http://www.cbs.dtu.dk/services/RevTrans-2.0/web/download.php
- TrimAl: http://trimal.cgenomics.org/

You can install many of these packages with Homebrew or Linuxbrew:
http://evosite3d.blogspot.co.uk/2016/04/using-package-manager-homebrew-mac-osx.html 

brew install python
brew install R
brew install homebrew/science/mafft
brew install homebrew/science/newick-utils
brew install homebrew/science/paml
brew install homebrew/science/pymol
brew install homebrew/science/trimal 


The python scripts you need to install:

- convert_fasta2phylip.py
- extract_sequences.py
- get_position_cds_trimal.py
- remove_ensembl_name_in_tree.py
- translate_dna.py

You can download them from my GitHub account: https://github.com/romainstuder/evosite3d

And install them in any accessible directory (i.e. in the working directory or in the $PATH list).




Practical

We will focus on the major histocompatibility complex (MHC) protein, which detects peptides from pathogens. As this gene is in the front line against invaders, it is submitted to strong selective pressure to rapidly detect new antigenic peptides. Early work on positive selection was focused on the MHC, so this is a very good example for this practical.

The uniprot code is HLA class II histocompatibility antigen, DQ beta 1 chain.
The Ensembl gene id is: ENSG00000179344.

# Download data from Ensembl: http://www.ensembl.org

Go on Ensembl website, and search for ENSG00000179344


1) Download orthologues sequence:
Comparative Genomics => Orthologues => Download orthologues 





Then choose: Fasta, Unaligned sequences – CDS).



2) Download subtree:

Comparative Genomics => Gene tree
Click on the blue node to select the following group: “Placental mammals ~100 MYA (Boreoeutheria)”
Gene Count    32





=> Export sub-tree   Tree or Alignment
=> Format Newick, options "Full (web)" and "Final (merged) tree".

You have now two starting files:

Sequences file: Human_HLA_DQB1_orthologues.fa
Tree file: HLA_DQB1_gene_tree.nh

We are now going to process these files, in order to generate an alignment, visualise it, remove spurious sequences and columns.


# First, let’s rename these files to have shorter names

cp Human_HLA_DQB1_orthologues.fa HLA_DQB1.cds.fasta
cp HLA_DQB1_gene_tree.nh HLA_DQB1.nh



# Remove the species tag in the gene name

./remove_ensembl_name_in_tree.py HLA_DQB1.nh > HLA_DQB1.tree


# Extract gene names with Newick Utilities 


nw_labels -I HLA_DQB1.tree > HLA_DQB1_names.txt 


# Extract CDS sequences that are in the tree, according to the extracted names

./extract_sequences.py HLA_DQB1_names.txt HLA_DQB1.cds.fasta > HLA_DQB1_subset.cds.fasta


# Translate CDS sequences to Amino Acid sequences using python script:

./translate_dna.py HLA_DQB1_subset.cds.fasta > HLA_DQB1_subset.aa.fasta


# Make an alignment of these Amino Acid sequences

mafft-linsi HLA_DQB1_subset.aa.fasta > HLA_DQB1_subset.aa.mafft.fasta


# Align CDS sequences by mapping them on the AA Alignment

revtrans.py HLA_DQB1_subset.cds.fasta HLA_DQB1_subset.aa.mafft.fasta > HLA_DQB1_subset.cds.mafft.fasta


# With Jalview, load Human_HLA_DQB1_orthologues_subset.cds.mafft.fasta

# Visualise the alignment to see if there isn’t anything wrong.
# Move human sequence (ENSP00000364080) on top (use the key arrows). This 

# is to tell CodeML to use ENSP00000364080 as reference.
# Save the alignment as FASTA file again (CTRL-S).

# Remove spurious sequences and columns with TrimAl

trimal -automated1 -in HLA_DQB1_subset.cds.mafft.fasta -resoverlap 0.75 -seqoverlap 85 -out HLA_DQB1_subset.cds.mafft.trimal.fasta -htmlout HLA_DQB1_subset.cds.mafft.trimal.html -colnumbering > HLA_DQB1_subset.cds.mafft.trimal.cols

# Convert trimed sequences from FASTA to PHYLIP

convert_fasta2phylip.py HLA_DQB1_subset.cds.mafft.trimal.fasta HLA_DQB1_subset.cds.mafft.trimal.phy


# Extract gene names to id.list

grep ">" HLA_DQB1_subset.cds.mafft.trimal.fasta | cut -c 2- > id.list


# Using Newick Utilities, we load the id file to extract a pruned subtree from the starting tree (contains only the taxa from the alignment).

id_list=`cat id.list`
echo "$id_list"
nw_prune -v HLA_DQB1.tree $id_list > HLA_DQB1_subset.tree



# Now we end up with two files:

Alignment: HLA_DQB1_subset.cds.mafft.trimal.phy
Tree: HLA_DQB1_subset.tree




2) Estimation of evolutionary values

This is the core of the tutorial. We will use codeml with three different control files (.ctl). Each computation could take up to 30-60 minutes, depending of your CPU.

# Compute many different site models: M0, M1a, M2a, M3 and M7. Save the following commandS in HLA_DQB1_M0M1M2M3M7M8.ctl file.


     seqfile = HLA_DQB1_subset.cds.mafft.trimal.phy  * sequence data file name
    treefile = HLA_DQB1_subset.tree                  * tree structure file name
     outfile = HLA_DQB1_M0M1M2M3M7M8.mlc             * main result file name

       noisy = 9   * 0,1,2,3,9: how much rubbish on the screen
     verbose = 1   * 1: detailed output, 0: concise output
     runmode = 0   * 0: user tree;  1: semi-automatic;  2: automatic
                   * 3: StepwiseAddition; (4,5):PerturbationNNI; -2: pairwise

     seqtype = 1   * 1:codons; 2:AAs; 3:codons-->AAs
   CodonFreq = 2   * 0:1/61 each, 1:F1X4, 2:F3X4, 3:codon table
       clock = 0   * 0: no clock, unrooted tree, 1: clock, rooted tree
      aaDist = 0   * 0:equal, +:geometric; -:linear, {1-5:G1974,Miyata,c,p,v}
       model = 0   * models for codons:
                   * 0:one, 1:b, 2:2 or more
dN/dS ratios for branches
     NSsites = 0 1 2 3 7 8 * 0:one w; 1:NearlyNeutral; 2:PositiveSelection;       
                           * 3:discrete; 4:freqs; 5:gamma;6:2gamma;
                           * 7:beta;8:beta&w;9:beta&gamma;10:3normal

       icode = 0   * 0:standard genetic code; 1:mammalian mt; 2-10:see below
       Mgene = 0   * 0:rates, 1:separate; 2:pi, 3:kappa, 4:all
   fix_kappa = 0   * 1: kappa fixed, 0: kappa to be estimated
       kappa = 2   * initial or fixed kappa
   fix_omega = 0   * 1: omega or omega_1 fixed, 0: estimate
       omega = 1   * initial or fixed omega, for codons or codon-based AAs

       getSE = 0       * 0: don't want them, 1: want S.E.s of estimates
RateAncestor = 0       * (0,1,2): rates (alpha>0) or ancestral states (1 or 2)
  Small_Diff = .45e-6  * Default value.
   cleandata = 0       * remove sites with ambiguity data (1:yes, 0:no)?
 fix_blength = 0       * 0: ignore, -1: random, 1: initial, 2: fixed


# And execute it (this can take ~ 30-45 minutes)::

codeml HLA_DQB1_M0M1M2M3M7.ctl


# Important! Copy rst file to another name:

cp rst HLA_DQB1_M0M1M2M3M7.rst.txt


# One last thing is to compute site model M8a, which is the same as M8, except we fix the dN/dS to 1 (only negative selection and neutral evolution allowed). Save the following commandS in the file
"HLA_DQB1_M8a.ctl":

     seqfile = HLA_DQB1_subset.cds.mafft.trimal.phy   * sequence data file name
    treefile = HLA_DQB1_subset.tree                  * tree structure file name
     outfile = HLA_DQB1_M8a.mlc                      * main result file name

       noisy = 9   * 0,1,2,3,9: how much rubbish on the screen
     verbose = 1   * 1: detailed output, 0: concise output
     runmode = 0   * 0: user tree;  1: semi-automatic;  2: automatic
                   * 3: StepwiseAddition; (4,5):PerturbationNNI; -2: pairwise

     seqtype = 1   * 1:codons; 2:AAs; 3:codons-->AAs
   CodonFreq = 2   * 0:1/61 each, 1:F1X4, 2:F3X4, 3:codon table
       clock = 0   * 0: no clock, unrooted tree, 1: clock, rooted tree
      aaDist = 0   * 0:equal, +:geometric; -:linear, {1-5:G1974,Miyata,c,p,v}
       model = 0   * models for codons:
                   * 0:one, 1:b, 2:2 or more dN/dS ratios for branches
     NSsites = 8   * 0:one w; 1:NearlyNeutral; 2:PositiveSelection; 3:discrete;
                   * 4:freqs; 5:gamma;6:2gamma;

                   * 7:beta;8:beta&w;9:beta&gamma;10:3normal
       icode = 0   * 0:standard genetic code; 1:mammalian mt; 2-10:see below
       Mgene = 0   * 0:rates, 1:separate; 2:pi, 3:kappa, 4:all
   fix_kappa = 0   * 1: kappa fixed, 0: kappa to be estimated
       kappa = 2   * initial or fixed kappa
   fix_omega = 1   * 1: omega or omega_1 fixed, 0: estimate
       omega = 1   * initial or fixed omega, for codons or codon-based AAs

       getSE = 0       * 0: don't want them, 1: want S.E.s of estimates
RateAncestor = 0       * (0,1,2): rates (alpha>0) or ancestral states (1 or 2)
  Small_Diff = .45e-6  * Default value.
   cleandata = 0       * remove sites with ambiguity data (1:yes, 0:no)?
 fix_blength = 0       * 0: ignore, -1: random, 1: initial, 2: fixed


# And execute (this can take ~ 5-10 minutes):

codeml HLA_DQB1_M8a.ctl



3) Results

3.1) Identification of positive selection

Have a look at the mlc files. If you want to retrieve the log-likelihood values:
grep "lnL" *.mlc

HLA_DQB1_M0M1M2M3M7M8.mlc:lnL(ntime: 32  np: 34):  -4838.327776      +0.000000
HLA_DQB1_M0M1M2M3M7M8.mlc:lnL(ntime: 32  np: 35):  -4711.107980      +0.000000
HLA_DQB1_M0M1M2M3M7M8.mlc:lnL(ntime: 32  np: 37):  -4692.732347      +0.000000
HLA_DQB1_M0M1M2M3M7M8.mlc:lnL(ntime: 32  np: 38):  -4692.078126      +0.000000
HLA_DQB1_M0M1M2M3M7M8.mlc:lnL(ntime: 32  np: 35):  -4718.466841      +0.000000
HLA_DQB1_M0M1M2M3M7M8.mlc:lnL(ntime: 32  np: 37):  -4690.545425      +0.000000
HLA_DQB1_M8a.mlc:         lnL(ntime: 32  np: 36):  -4706.268471      +0.000000

 


The order of lines being: M0, M1, M2, M3, M7, M8 and M8a. For each model, you directly get the number of parameters (np) and the log-likelihood value:

Model
n.p.
lnL
M0
34
-4838.3278
M1a
35
-4711.1080
M2a
37
-4692.7323
M3
38
-4692.0781
M7
35
-4718.4668
M8
37
-4690.5454
M8a
36
-4706.2685


Using these models, we can construct four likelihood-ratio tests (LRT), where three of them will tell us if there is significant positive selection or not.


1) M0-M3: this one is an exception and will only tell us if there are different categories of sites under different selective pressures. This test is not used to detect positive selection, and it is nearly always significant.

2x(L1-L0) = 2x[(-4692.0781) – (-4838.3278)] = 292.4993
d.f. = 38-34 = 4
=> 4.49405E-62


2) M1a-M2a: this test was the first site model developed to detect positive selection. We contrast a model with 2 classes of sites against a model with 3 classes of sites. Degree of freedom = 2.

2x(L1-L0) = 2x[(-4692.7323) – (-4711.1080)] = 36.7513
d.f. = 37-35 = 2
=> 1.04608E-08

The test is significant, so there is positive selection. This model is very conservative, and can lack power under certain conditions.


3) M7-M8: this test also detects positive selection. We contrast a model with 10 classes of sites against a model with 11 classes of sites. Degree of freedom = 2.

2x(L1-L0) = 2x[(-4690.5454) – (-4838.3278)] = 55.842832
d.f. = 37-35 = 2
=> 7.47968E-13

The test is significant, so there is positive selection. However, this model can have problem power under certain conditions, and the following LRT is preferred.


4) M8-M8a: this is the latest test. We contrast a model with 11 classes of sites where positive is not allowed (dN/dS=1) against a model with 11 classes of sites where positive is allowed (dN/dS >=1). Degree of freedom = 1.

2x(L1-L0) = 2x[(-4690.5454) – (-4706.2685)] = 31.446092
d.f. = 37-36 = 1
=> 1.48446E-07


This is the preferred test, combining power and robustness.



3.2) Identification of sites 

As these tests are significant, we can move to the next step, which is the precise identification of sites under positive selection. If the previous step was not significant, we should not move to this stage.

In your mlc file, under the section of Model M2a and M8 (the only ones that allow positive selection), you will find a section called “Bayes Empirical Bayes (BEB) analysis (Yang, Wong & Nielsen 2005. Mol. Biol. Evol. 22:1107-1118)”. This section contains the list that have a BEB score [Pr(w>1)] higher than 50%. BEB values higher than 95% are indicated by * and sites with values higher than 99% are indicated by **. Sometimes, there is no site detected, which means there is probably a problem in your analysis or dataset if your test is signficant. Sometimes, you will find a lot of sites, which seems worrying, but it just means the average BEB (baseline) is slightly above 50%. The most interesting sites are those with a BEB>95% (* or **).



Bayes Empirical Bayes (BEB) analysis (Yang, Wong & Nielsen 2005. Mol. Biol. Evol. 22:1107-1118)
Positively selected sites (*: P>95%; **: P>99%)
(amino acids refer to 1st sequence: ENSP00000364080)

            Pr(w>1)     post mean +- SE for w
     4 R      0.961*        2.858 +- 0.698
    36 F      0.671         2.150 +- 1.019
    53 L      0.999**       2.956 +- 0.610
    84 D      1.000**       2.957 +- 0.608
    97 G      0.649         2.098 +- 1.018
   112 V      0.969*        2.888 +- 0.695
   114 F      0.999**       2.955 +- 0.611
   115 R      0.743         2.367 +- 1.093
   116 G      1.000**       2.957 +- 0.609
   121 R      0.835         2.593 +- 0.993
   247 R      0.617         2.050 +- 1.110


The column correspondS to the position in the trimmed alignment (i.e. not related to the position in the reference sequence, which is ENSP00000364080, the human). However, the amino acid correspondS exactly to the reference sequence.

One of the site with the strongest BEB value is 84, with 1.000.  Its own dN/dS value is 2.957, with a standard deviation of 0.608. As I said previously, the sites given by CodeML don’t correspond to the human sequence. You can use the following script to extract the real position in the human sequence:
 

./get_position_cds_trimal.py HLA_DQB1_subset.cds.mafft.fasta HLA_DQB1_subset.cds.mafft.trimal.cols "ENSP00000364080" 84
 
=> 84 89 D

=> This site 84 in CodeML (Trimal) correspondS to amino acid site 89 in the human sequence and codes for an aspartic acid.


# In total, we have six sites that are strongly interesting (BEB>95%): 4, 53, 84, 112, 114 and 116. Let’s repeat the same for all these sites:
 

site_list="4 53 84 112 114 116" 
for site in $site_list; do ./get_position_cds_trimal.py HLA_DQB1_subset.cds.mafft.fasta HLA_DQB1_subset.cds.mafft.trimal.cols "ENSP00000364080" $site; done

  4   8 R
 53  58 L
 84  89 D
112 117 V
114 119 F
116 121 G



# We can do the same for sites with 50%<BEB<95%:

site_list="36 97 115 121 247"

for site in $site_list; do ./get_position_cds_trimal.py HLA_DQB1_subset.cds.mafft.fasta HLA_DQB1_subset.cds.mafft.trimal.cols "ENSP00000364080" $site; done

 36  41 F
 97 102 G
115 120 R
121 126 R
247 252 R



# We can also plot the dN/dS value per sites. At the bottom of the rst file "HLA_DQB1_M0M1M2M3M7.rst.txt", extract the last part which looks like this and save as “beb.txt”:

   1 K   0.02943 0.13133 0.20099 0.20092 0.16262 0.11574 0.07524 0.04540 0.02539 0.01292 0.00002 ( 3)  0.395 +-  0.198
   2 A   0.00278 0.02154 0.05527 0.09166 0.12189 0.14109 0.14752 0.14134 0.12323 0.09274 0.06093 ( 7)  0.737 +-  0.535
   3 L   0.00726 0.04637 0.09959 0.13896 0.15621 0.15361 0.13717 0.11292 0.08526 0.05671 0.00595 ( 5)  0.551 +-  0.270
   4 R   0.00000 0.00000 0.00000 0.00003 0.00019 0.00082 0.00248 0.00582 0.01104 0.01731 0.96230 (11)  2.860 +-  0.696
   5 I   0.44686 0.24476 0.14583 0.08007 0.04205 0.02141 0.01061 0.00510 0.00234 0.00099 0.00000 ( 1)  0.168 +-  0.149
   6 P   0.34022 0.22595 0.16343 0.10859 0.06876 0.04207 0.02495 0.01430 0.00780 0.00391 0.00001 ( 1)  0.221 +-  0.187



1st column = position in the trimmed alignment.
2nd column = amino acid from the reference sequence.
3rd to 13th column = BEB score for each class (10 neutral + 1 allowing positive selection).
14th = most likely class.
15th = estimated dN/dS value at this position.
16th = standard deviation for this dN/dS value.

You can see that position 4, the most likely class is 11th (BEB=0.96) with a dN/dS = 2.86+-0.70.



# CodeML output uses a fixed delimitation. To parse it in R, we need to remove the space between bracket and number:

cat beb.txt | perl -pe "s/\( /\(/g" > tmp.txt; mv tmp.txt beb.txt


# Here are some commandS to use in R, to produce the following plot:

if (!require("ggplot2")) {
   install.packages("ggplot2", dependencies = TRUE)
   library(ggplot2)
}

df<-read.table("beb.txt", sep = "")

df$beb <- "No"
df$beb[df$V13 > 0.50] <- "Yes"

p <- ggplot(df, aes(V1, V15))
p + geom_point(aes(colour = factor(beb)))+
    geom_hline(yintercept = 1)+
    scale_color_manual(values = c("black", "red"))+
    labs(x = "Residue position")+
    labs(y = "Selective pressure [dN/dS]")+
    theme_bw()+
    theme(legend.position="none")+
    theme(axis.line = element_line(colour = "black"),
    panel.grid.major = element_blank(),
    panel.grid.minor = element_blank(),
    panel.background = element_blank())
ggsave("beb.png", height=3, width=4)



We can see that sites under positive selection represent only a small fraction, and most sites are under strong purifying selection.


4) Visualisation of sites in 3D structure

We found that sites seems randomly distributed according to their residue position. It would be interesting to see if they form a pattern in the 3D structure. Go download the following pdb file 1uvq:

wget http://files.rcsb.org/download/1UVQ.pdb

Or download it from the webpage: http://www.rcsb.org/pdb/explore.do?structureId=1UVQ

Then load it in PyMOL:

pymol 1UVQ.pdb &

# First, define the different molecules to their associated polypeptide chains:

select HLA_DQA1, chain A
select HLA_DQB1, chain B
select peptide,  chain C


# We highlight in cartoon/sticks and colour chains and peptide in different colours:

hide everything
show cartoon, HLA_DQA1
show cartoon, HLA_DQB1
show sticks, peptide
colour white, HLA_DQA1
colour grey60, HLA_DQB1
colour green, peptide

 
# To spice things up, the site numbering in many PDB files doesn’t correspond to the human sequence. So we have to renumber it:

renumber HLA_DQB1, 35

# Highlight sites with BEB>95%:

select sites_BEB95, HLA_DQB1 and resi 58+89+117+119+121
show spheres, sites_BEB95
colour yellow, sites_BEB95


# Highlight sites with 50%<BEB<95%:

select sites_BEB50, HLA_DQB1 and resi 41+102+120+126+252
show sticks, sites_BEB50
colour yellow, sites_BEB50


=> Most sites under positive selection (in yellow) are exactly in the binding site (in green), facing the target peptide. This example with the MHC has been widely described in the literature [Hugues AL et al. 1988]. To my disappointement, there are not so many exemples that selective pressure, 3D structural and experimental validation: 

http://evosite3d.blogspot.co.uk/2014/06/is-there-any-example-of-study-on-amino.html


To have a nice finish as in the figure above, rotate the structure the way you want and type: 

bg_color white
util.cnc
select none
ray 2000
save 1UVQ_positive_sites.png


Et voila! I hope this tutorial was helpful.

Friday, 22 April 2016

Using package manager Homebrew (Mac OSX) for science / computational biology


I am using Mac OSX on a daily use for many reasons.

One reasons is that you can use the classical tools from the Windows world (Microsoft Office, Endnote) that don't exist on Linux. It is important to me as many of my external collaborators are using Windows, so it can be problematic when sharing documents. I don't exclude that I would shift one day to Linux.

The second reason, and I think it was one of the best strategy from Apple, was the transition to Unix in 2001. This greatly improved the compatibility and access to tons of scientific softwares. The installation of unix tools from source is usually done by the classical "./configure; make; sudo make install".

Hopefully, package managers exist to avoid this task, and to keep the system tidy, especially with library dependencies. At the very beginning, when I started my PhD in 2005, I was using Fink. I then switched to MacPort. Last year, I encountered some problems with MacPort and some versions of GCC. Everything was messy and I decided, as I switched to El Capitan from 10.8, to move to Homebrew. So I remove my MacPort installation and installed HomeBrew. And Homebrew is really great!

(Shaun Jackman told me on Twitter that he is maintaining the linux fork of Homebrew, available here: http://linuxbrew.sh/ )



Some reasons I like it:
  • Very easy to use.
  • No need to use super-user, as it installs in the user directory.
  • It tries to use already libraries if possible.
  • There is one way for unix-style software and one way for .dmg package (cask).

To install it, you need:
  • MacOSX 10.9 ou +
  •  Xcode (the most recent). [NB: Xcode is not needed anymore. Save a lot of space!]
  • Command Line Tools (Install with command: xcode-select --install)

You can install Homebrew from there:  http://brew.sh/

You just need this command, and homebrew will auto-install itself:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"


Then it is very easy to use in the Terminal. For example, if your are interested to install "Gimp":

brew search gimp => search for packages that contains the word "gimp".

brew info gimp => describe gimp package, and which dependencies are needed.

brew install gimp => install gimp.

brew list => show everything installed on your computer.


There are other sections in homebrew. For exemple, a category specific to games, or a category specific to science. To include those directly on your homebrew, you can tap them:

brew tap homebrew/games
brew tap homebrew/science

Now, you can install CodeML / PAML:
brew install paml


For example, here is what I have installed from the science category:

brew leaves | grep "science"

homebrew/science/bowtie
homebrew/science/bowtie2
homebrew/science/cd-hit
homebrew/science/clustal-omega
homebrew/science/cytoscape
homebrew/science/dssp
homebrew/science/emboss
homebrew/science/express
homebrew/science/fastml
homebrew/science/fasttree
homebrew/science/gromacs
homebrew/science/hyphy
homebrew/science/mcl
homebrew/science/mrbayes
homebrew/science/muscle
homebrew/science/newick-utils
homebrew/science/paml
homebrew/science/phylip
homebrew/science/phyml
homebrew/science/prank
homebrew/science/pymol
homebrew/science/raxml
homebrew/science/repeatmasker
homebrew/science/rstudio-server
homebrew/science/samtools
homebrew/science/sratoolkit
homebrew/science/trimal
homebrew/science/velvet
homebrew/science/weblogo
homebrew/science/xmgredit

You will recognise many useful tools. Nice, isn't it?



However, there are still some tools that cannot be installed with Homebrew:


brew search biopython => No formula found for "biopython".
brew search jalview => No formula found for "jalview".
brew search pagan => No formula found for "pagan".
brew search njplot => No formula found for "njplot".
brew search netphorest => No formula found for "netphorest".
brew search vmd => not the one I search for. :/

(I will update this list once I installed them)




There is also the CASKROOM, which contains other packages, such as .dmg packages.

https://caskroom.github.io/

Same, you can merge with homebrew:
brew tap caskroom/cask

For example, to install Firefox:

brew cask install --force figtree
=> it will install Firefox in your and create a shortcut in /Users/yourname/Applications

If you want to install in /Applications:
brew cask install --appdir="/Applications" --force figtree

=> it will force the creation of the shortcut to /Applications. But I prefer to install in my own Applications folder, it is cleaner.


Here is my short list:

brew cask list | sort
android-file-transfer
arduino
audacity
avogadro
cathode
dosbox
dropbox
emacs
figtree
filezilla
firefox
gimp
google-earth
grandperspective
handbrake
hex-fiend
java
kid3
kompozer
libreoffice
mplayer-osx-extended
rstudio
scribus
silverlight
skim
skype
slack
teamviewer
thunderbird
unetbootin
unrarx
vlc
vox




Maintenance:

It is easy to maintain and update all your package (except the ones from CASK, I don't know why)

brew doctor => check that everything is ok. It can display lot of warnings, especially if you previously installed programs by hand.

brew update => update your package list definition.

brew upgrade =>  upgrade all your outdated packages

brew upgrade $FORMULA => upgrade only the specific formula (i.e. mrbayes).

brew cleanup
brew cask cleanup

You can run the maintenance in one line:
brew update; brew upgrade; brew cleanup; brew cask cleanup




For the packages from CASK, here is how I update them (with the --force option):

brew cask install --force --srgb --with-cocoa emacs

brew cask install --force java
brew cask install --force arduino
brew cask install --force avogadro
brew cask install --force bittorrent
brew cask install --force cathode
brew cask install --force figtree
brew cask install --force filezilla
brew cask install --force gimp
brew cask install --force grandperspective
brew cask install --force google-earth
brew cask install --force handbrake
brew cask install --force kompozer
brew cask install --force kid3
brew cask install --force mplayer-osx-extended
brew cask install --force rstudio
brew cask install --force scribus
brew cask install --force silverlight
brew cask install --force slack
brew cask install --force teamviewer
brew cask install --force thunderbird
brew cask install --force unetbootin
brew cask install --force unrarx
brew cask install --force vlc
brew cask install --force vox

brew cask install --force --appdir="/Applications" firefox
brew cask install --force --appdir="/Applications" libreoffice
brew cask install --force --appdir="/Applications" skype


You can also do it in one line like this:
brew cask list | xargs brew cask install --force


That's it!

I strongly recommend to use Homebrew, especially if you start from a fresh system. Homebrew community is very active and new packages are put every weeks.


Romain


PS: other interesting blog posts:

Wednesday, 20 April 2016

Tutorial: estimating the stability effect of a mutation with FoldX - release 4

Note: this is the exact same tutorial as published on 25 March 2015, except it is now based on FoldX4. The reason is that we have to update the FoldX license every year (from 31st of December to 1st of January). This means that if you ran jobs over Christmas Holidays, the jobs are killed at New Year's Eve. And the problem is they shifted from release 3 to 4, which was accompanied by a complete change in the interface. Which is good as it is  much simpler now.

They also made some changes in the energy computation by adding some parameters, but this is not documented yet. So if you started your project using FoldX3, and you need again to use FoldX, it is might be better to re-run FoldX4 on your whole dataset, for coherence reasons.

Finally, as usual, if you have any questions or comments, your are welcome!


----------

 
Introduction:

Here is a brief tutorial on how to use FoldX to estimate the stability effect of a mutation in a 3D structure. The stability (ΔG) of a protein is defined by the free energy, which is express in kcal/mol. The lower it is, the more stable it is. ΔΔG is difference in free energy (in kcal/mol) between a wild-type and mutant. A mutation that brings energy (ΔΔG > 0 kcal/mol) will destabilise the structure, while a mutation that remove energy (ΔΔG < 0 kcal/mol) will stabilise the structure. A common threshold is to say that a mutation has a significant effect if ΔΔG is >1 kcal/mol, which roughly corresponds to the energy of a single hydrogen bond.

A good way to compute the free energy is to use molecular dynamics. Main problem: it can be very time-consuming.

FoldX uses an empirical method to estimate the stability effect of a mutation. The executable is available here: http://foldxsuite.crg.eu/

You need to register, but it is free for Academics.

NB: I strongly encourage to read the manual (before or in parallel of this tutorial).
[NB2 (20/04/2016): I haven't found a proper manual for FoldX4. Only html pages per command)]

Manual: http://foldxsuite.crg.eu/manual#manual


FoldX was used in many studies, i.e.:
Tokuriki N, Stricher F, Serrano L, Tawfik DS. How protein stability and new functions trade off. PLoS Comput Biol. 2008 Feb 29;4(2):e1000002 http://dx.doi.org/10.1371/journal.pcbi.1000002

Dasmeh P, Serohijos AW, Kepp KP, Shakhnovich EI. Positively selected sites in cetacean myoglobins contribute to protein stability. PLoS Comput Biol. 2013;9(3):e1002929. http://dx.doi.org/10.1371/journal.pcbi.1002929
And I personally used it in three of my studies:
Studer RA, Christin PA, Williams MA, Orengo CA. Stability-activity tradeoffs constrain the adaptive evolution of RubisCO. Proc Natl Acad Sci U S A. 2014 Feb 11;111(6):2223-8. http://dx.doi.org/10.1073/pnas.1310811111
Studer RA, Opperdoes FR, Nicolaes GA, Mulder AB, Mulder R. Understanding the functional difference between growth arrest-specific protein 6 and protein S: an evolutionary approach. Open Biol. 2014 Oct;4(10). pii: 140121. http://dx.doi.org/10.1098/rsob.140121

Rallapalli PM, Orengo CA, Studer RA, Perkins SJ. Positive selection during the evolution of the blood coagulation factors in the context of their disease-causing mutations. Mol Biol Evol. 2014 Nov;31(11):3040-56. http://dx.doi.org/10.1093/molbev/msu248


Tutorial by example:

The structure is a bacterial cytochrome P450 (PDB:4TVF). You can download its PDB file (4TVF.pdb) from here: http://www.rcsb.org/pdb/explore.do?structureId=4TVF

Or directly with wget:
wget http://ftp.rcsb.org/download/4TVF.pdb

We would like to test the stability of mutation at position 280, from a leucine (L) to an aspartic acid (D). Here is the original structure, with Leu280 in green, and residues around 6Å in yellow:



FoldX works in two steps:


1) Repair the structure.

There are frequent problems in PDB structures, like steric clashes. FoldX will try to fix them and lower the global energy (ΔG). The "RepairPDB" command is better than the "Optimize" command. Here is how to launch FoldX:
foldx --command=RepairPDB --pdb=4TVF.pdb --ionStrength=0.05 --pH=7 --water=CRYSTAL --vdwDesign=2 --outPDB=true --pdbHydrogens=false

We indicate which PDB file it needs to use, that we want to repair it (RepairPDB), that it will use water and metal bonds from the PDB file (--water=CRYSTAL) and that we want a PDB as output (--outPDB=true). All other parameter are by default.

This process is quite long (around 10 minutes). Here is the result (the original structure is now in white, while the repaired structure is in yellow/green):

 We can see that some side chains have slightly moved (in particular Phe16).

The starting free energy ΔG was +73.22 kcal/mol, and it was lowered to -46.97 kcal/mol, which is now stable (remember that a "+" sign means unstable while a "-" sign means stable).

Once it's finished, it will produce a file named "4TVF_Repair.pdb", which you will use in the next step.


2) Perform the mutation

The mutation itself is performed by the BuildModel function. There are other methods, but the BuildModel is apparently the most robust (I said apparently, but there are no proper benchmarks against the other method PositionScan or PSSM). You also need to specify the mutation in a separate file "individual_list.txt". Here is the file "individual_list.txt" (yes, just one line):
LA280D;
It contains the starting amino acid (L), the chain (A), the position (280) and the amino acid you want at the end (D). One line correspond to one mutant. It means you can mutate many residues at the same per line (mutant) and also  produce different mutants by different numbers of lines.

In the following command line, you will see that is 4TVF_Repair.pdb and not 4TVF.pdb that is mutated. You will also notice "--numberOfRuns=3". This is because some residues can have many rotamers and could have some convergence problems. You may to increase this values to 5 or 10, in case you are mutating long residues (i.e. Arginine) that have many rotamers.

You can run it by:
foldx --command=BuildModel --pdb=4TVF_Repair.pdb --mutant-file=individual_list.txt --ionStrength=0.05 --pH=7 --water=CRYSTAL --vdwDesign=2 --outPDB=true --pdbHydrogens=false --numberOfRuns=3
It is much faster this time (i.e. a few seconds) and will produce many files.

FoldX will first mutate the target residue (L) to itself (L) and move it as well as all neighbouring side chains multiple times. We can see that Leu280 (green) was rotated:

=> This is will give the free energy of the wild-type (let's call it ΔGwt).

Then, it will mutate the target residue (L) to the desired mutant (D) and move it as well as all neighbouring side chains multiple times. We can see that Leu280 is mutated to Asp280 (see the two oxygen atoms in red):


=> This is will give the free energy of the mutant (let's call it ΔGmut).


The difference in free energy (ΔΔG) is given by ΔGmut-ΔGwt.

In the file "Raw_4TVF_Repair.fxout", you can retrieve the energy of the three runs for both WT and Mutant.

Run1:
  • ΔGmut = 4TVF_Repair_1.pdb = -42.7114 kcal/mol
  • ΔGwt = WT_4TVF_Repair_1_0.pdb = -47.6248 kcal/mol
  • => ΔΔG = ΔGmut-ΔGwt = (-42.7114)-(-47.6248) = +4.9134 kcal/mol

One file contains the average difference over all runs: "Average_4TVF_Repair.fxout".

(You will notice that the difference in free energy ΔΔG is +4.85 kcal/mol [+- 0.06 kcal/mol]).

=> It means the mutation L280D is highly destabilising (positive value, and much above 1.0 kcal/mol).


PS: A way to define the threshold is to use the standard deviation (SD) by multiple:

The reported accuracy of FoldX is 0.46 kcal/mol (i.e., the SD of the difference
between ΔΔGs calculated by FoldX and the experimental values). We can bin the ΔΔG values into seven categories:
  1. highly stabilising (ΔΔG < −1.84 kcal/mol); 
  2. stabilising (−1.84 kcal/mol ≤ ΔΔG < −0.92 kcal/mol); 
  3. slightly stabilising (−0.92 kcal/mol ≤ ΔΔG < −0.46 kcal/mol); 
  4. neutral (−0.46 kcal/mol < ΔΔG ≤ +0.46 kcal/mol);
  5. slightly destabilising (+0.46 kcal/mol < ΔΔG ≤ +0.92 kcal/mol);
  6. destabilising (+0.92 kcal/mol < ΔΔG ≤ +1.84 kcal/mol);
  7. highly destabilising (ΔΔG > +1.84 kcal/mol).



Friday, 27 November 2015

Cleaning Python scripts with Pylint and GNU/Expand

Python is a wonderful programming language. But it can be quite syntax error tolerant. For example, the indentation is really important, but you can use either tabulations or spaces. You can also mix them in Python 2 (forbidden in Python 3).

These days, I am trying to stick to the rules (I am getting old). For that, there is the PEP8 style guide: https://www.python.org/dev/peps/pep-0008/

For example, the official format for identation is 4 spaces per indentation level.

I found Pylint, which check your code for such errors: http://www.pylint.org/

It gives a list of all erors line by line, and a global score.

Let's give a try. Here is a code to print fibonacci numbers, which you can download it from here: https://drive.google.com/open?id=0BxcXpZeUylGbSTNCZDVCQmRQZTA

Save it as fibo.py and launch it:

python fibo.py 9
0 1
1 1
1 2
2 3
3 5
5 8
8 13
13 21
(9, 21)

It works! Great!

But let's have a look with Pylint:


Global evaluation
-----------------
Your code has been rated at 0.83/10

Ouch, this hurts!

Many problems apparently:

************* Module fibo
C:  9, 0: Exactly one space required after comma
    i,j = 1,0
     ^ (bad-whitespace)
C:  9, 0: Exactly one space required after comma
    i,j = 1,0
           ^ (bad-whitespace)
C: 11, 0: Exactly one space required after comma
    for k in range(1,n + 1):
                    ^ (bad-whitespace)
W: 12, 0: Found indentation with tabs instead of spaces (mixed-indentation)
C: 12, 0: Exactly one space required after comma
        i,j = j, i + j
      ^ (bad-whitespace)
C: 13, 0: Trailing whitespace (trailing-whitespace)
W: 13, 0: Found indentation with tabs instead of spaces (mixed-indentation)
C: 13, 0: Exactly one space required after comma
        print i,j
            ^ (bad-whitespace)
C: 15, 0: Trailing whitespace (trailing-whitespace)
W: 11, 8: Unused variable 'k' (unused-variable)
W:  3, 0: Unused import os (unused-import)

First problem, there is a mix and match with tab and space. It is easy to manually correct a small file, it can be tough with a very big file. GNU/UNIX provides some tools for that:

1) command cat 

https://www.gnu.org/software/coreutils/manual/html_node/cat-invocation.html
 
With Linux: cat -A fibo.py
With MacOSX: cat -e -t  fibo.py
With Windows: guru meditation error, sorry.

=> space will be displayed as space, but tab will now be displayed as "^I". Easier to see any problem.

2) command expand

http://www.gnu.org/software/coreutils/manual/html_node/expand-invocation.html
 
expand -t 4 fibo.py > tmp.txt  # Change all tab to 4-space
mv tmp.txt fibo.py  # move back the filename.
chmod +x fibo.py  # make it executable again.


And now try again
cat -e -t  fibo.py
pylint fibo.py

Global evaluation
-----------------
Your code has been rated at 2.50/10 (previous run: 0.83/10, +1.67)


Good, there is some progresses.


C:  9, 0: Exactly one space required after comma
    i,j = 1,0
     ^ (bad-whitespace)
C:  9, 0: Exactly one space required after comma
    i,j = 1,0
           ^ (bad-whitespace)
C: 11, 0: Exactly one space required after comma
    for k in range(1,n + 1):
                    ^ (bad-whitespace)
C: 12, 0: Exactly one space required after comma
        i,j = j, i + j
         ^ (bad-whitespace)
C: 13, 0: Trailing whitespace (trailing-whitespace)
C: 13, 0: Exactly one space required after comma
        print i,j
               ^ (bad-whitespace)
C: 15, 0: Trailing whitespace (trailing-whitespace)
W: 11, 8: Unused variable 'k' (unused-variable)
W:  3, 0: Unused import os (unused-import)

The rest of the code is more styling errors:
- Add space after the comma.
- Remove import os
- Remove trailing white-space (visible with cat -A / cat -e -t)

And now:
Your code has been rated at 9.09/10.
Much better!

The last problem is an unused variable k. We can let it like this or change it with a more elegant way (i.e. with a while loop).


So, recommandation:

- Do your code properly since the begining.
- Use Pylint to identify errors.
- Correct the errors.
- Have a look to see if your code is not changed (i.e. identation shifted).
- Run your code again to check if it is working.


PS: It looks like Emacs 25.0 is properly handling the tab key, aka adding 4-spaces in the file instead of a tab.



Wednesday, 25 November 2015

Generate a PDF version of the Google Scholar citation histogram

Google Scholar provides a nice way to illustrate your citation records as histogram:

I wanted to add it to my publication record document, but the problem is we cannot save as a picture. We could save as a screenshot but as bitmap, it will look blurry. Hopefully, I find a nice way to reproduce the plot with R (https://www.r-project.org/) and ggplot2 (http://ggplot2.org/).

First, create a simple file called "google_record.txt", which contains the following information:
2015 208
2014 159
2013 100
2012 58
2011 44
2010 30
2009 22
These numbers are simply obtained by rolling the mouse over the plot in the webpage of google scholar. Of course, don't forget to change the values by your numbers. ;)

Then, launch R and type the following commands:
if (!require("ggplot2")) {
   install.packages("ggplot2", dependencies = TRUE)
   library(ggplot2)
}

df <- read.table("google_record.txt")

ggplot(df,aes(x=factor(V1), y=V2))+geom_bar(stat = "identity", fill="gray40")+
    theme(panel.background= element_blank())+
    theme(panel.grid.major.x = element_blank())+
    theme(panel.grid.major.y = element_line(size=0.5, color="grey"))+
    theme(panel.grid.minor.y = element_line(size=0.5, color="grey"))+
    theme(axis.ticks = element_line(size = 0.5, colour="grey"))+
    theme(axis.text = element_text(colour="black", size=rel(1.2)))+
    labs(title = "Citations per year", x="", y="", size=rel(1.3))

ggsave("google_record.pdf",height=3,width=5)

You will then obtain a clean PDF file to include in your document.

Wednesday, 25 March 2015

Tutorial: estimating the stability effect of a mutation with FoldX

Introduction:

Here is a brief tutorial on how to use FoldX to estimate the stability effect of a mutation in a 3D structure. The stability (ΔG) of a protein is defined by the free energy, which is express in kcal/mol. The lower it is, the more stable it is. G is difference of free energy between a wild-type and mutant. A mutation that brings energy (ΔΔG>kcal/mol) will destabilise the structure, while a mutation that remove energy (ΔΔG<kcal/mol) will stabilise the structure. A common threshold is to say that a mutation has a significant effect if ΔΔG is >1 kcal/mol, which roughly corresponds to a single hydrogen bond.

A way to compute the free energy is to use molecular dynamics. Main problem: it can be very time-consuming.

FoldX uses an empirical method to estimate the stability effect of a mutation. The executable is available here: http://foldx.crg.es/

NB: I strongly encourage to read the manual (before or in parallel of this tutorial).

Foldx was used in many studies, i.e.:
Tokuriki N, Stricher F, Serrano L, Tawfik DS. How protein stability and new functions trade off. PLoS Comput Biol. 2008 Feb 29;4(2):e1000002 http://dx.doi.org/10.1371/journal.pcbi.1000002

Dasmeh P, Serohijos AW, Kepp KP, Shakhnovich EI. Positively selected sites in cetacean myoglobins contribute to protein stability. PLoS Comput Biol. 2013;9(3):e1002929. http://dx.doi.org/10.1371/journal.pcbi.1002929
And I personally used it in three of my studies:
Studer RA, Christin PA, Williams MA, Orengo CA. Stability-activity tradeoffs constrain the adaptive evolution of RubisCO. Proc Natl Acad Sci U S A. 2014 Feb 11;111(6):2223-8. http://dx.doi.org/10.1073/pnas.1310811111
Studer RA, Opperdoes FR, Nicolaes GA, Mulder AB, Mulder R. Understanding the functional difference between growth arrest-specific protein 6 and protein S: an evolutionary approach. Open Biol. 2014 Oct;4(10). pii: 140121. http://dx.doi.org/10.1098/rsob.140121

Rallapalli PM, Orengo CA, Studer RA, Perkins SJ. Positive selection during the evolution of the blood coagulation factors in the context of their disease-causing mutations. Mol Biol Evol. 2014 Nov;31(11):3040-56. http://dx.doi.org/10.1093/molbev/msu248

Example:

The structure is a bacterial cytochrome P450 (PDB:4TVF). You can download it PDB file (4TVF.pdb) from here: http://www.rcsb.org/pdb/explore.do?structureId=4TVF

We would to test the stability of mutatinf the leucine (L) at position 280 to an aspartic acid (D).

Here is the original structure, with Leu280 in green, and residues around 6Å in yellow:



FoldX has different modes to run it, but I use the mode "runfile", which contains COMMANDS and OPTIONS in one single file.


FoldX works in two steps:


1) Repair the structure.

There are frequently problems in PDB structures, like steric clashes. FoldX will try to fix them and lower the global energy (ΔG). The command "RepairPDB" is better than the "Optimize" command. Here is the command file "foldx_repair.txt":
<TITLE>FOLDX_runscript;
<JOBSTART>#;
<PDBS>4TVF.pdb;
<BATCH>#;
<COMMANDS>FOLDX_commandfile;
<RepairPDB>#;
<END>#;
<OPTIONS>FOLDX_optionfile;
<Temperature>298;
<R>#;
<pH>7;
<IonStrength>0.050;
<water>-CRYSTAL;
<metal>-CRYSTAL;
<VdWDesign>2;
<OutPDB>true;
<pdb_hydrogens>false;
<END>#;
<JOBEND>#;
<ENDFILE>#;
We indicate which PDB file it needs to use, that we want to repair it (<RepairPDB>), that it will use water and metal bonds from the PDB file (<water>-CRYSTAL; <metal>-CRYSTAL;) and that we want a PDB as output (<OutPDB>true).

You have to run the command file "foldx_repair.txt" like this:
foldx3b6 -runfile foldx_repair.txt
This process is quite long (around 10 minutes). Here is the result (the original structure is now in white, while the repaired structure is in yellow/green):

 We can see that some side chains have slightly move (in particular Phe16).

The starting free energy ΔG was 64.99 kcal/mol, and it was lowered to -48.15 kcal/mol, which is now stable (remember that a "+" sign means unstable while a "-" sign means stable).

Once it's finished, it will produce a file named "RepairPDB_4TVF.pdb", which you will use in the next step.


2) Perform the mutation

The mutation itself is perform by the BuildModel function. There are other methods, but the BuildModel is the most robust. You need also to specify the mutation in a separate file "individual_list.txt".

In the command file, you will see that is RepairPDB_4K33.pdb and not 4K33.pdb that is mutated. You will also notice "<numberOfRuns>3;". This is because some residues can have many rotamers and could have some convergence problems. You may to increase this values to 5 or 10, in case you are mutated long residues (i.e. Arginine) that have many rotamers.

Here the command file "foldx_build.txt":
<TITLE>FOLDX_runscript;
<JOBSTART>#;
<PDBS>RepairPDB_4TVF.pdb;
<BATCH>#;
<COMMANDS>FOLDX_commandfile;
<BuildModel>#,individual_list.txt;
<END>#;
<OPTIONS>FOLDX_optionfile;
<Temperature>298;
<R>#;
<pH>7;
<IonStrength>0.050;
<water>-CRYSTAL;
<metal>-CRYSTAL;
<VdWDesign>2;
<OutPDB>true;
<numberOfRuns>3;
<END>#;
<JOBEND>#;
<ENDFILE>#;
and the "individual_list.txt" (just one line):
LA280D;
It contains the starting amino acid (L), the chain (A), the position (280) and the amino acid you want at the end (D). One line correspond to one mutant. It means you can mutate many residues at the same per line (mutant) and also  produce different mutants by different numbers of lines.

You can run it by:
foldx3b6 -runfile foldx_build.txt
It is much faster this time (i.e. a few seconds) and will produce many files.

FoldX will first mutate the target residue (L) to itself (L) and move it as well as all neighbouring side chains multiple times. We can see that Leu280 (green) was rotated:

=> This is will give the free energy of the wild-type (let's call it ΔGwt).

Then, it will mutate the target residue (L) to the desired mutant (D) and move it as well as all neighbouring side chains multiple times. We can see that Leu280 is mutated to Asp280 (see the two oxygen atoms in red):


=> This is will give the free energy of the mutant (let's call it ΔGmut).



The difference in free energy (ΔΔG) is given by ΔGmut-ΔGwt.

In the file "Raw_BuildModel_RepairPDB_4TVF.fxout", you can retrieve the energy of the three runs for both WT and Mutant.

Run1:
  • ΔGmut = RepairPDB_4TVF_1_0.pdb = -41.1377 kcal/mol
  • ΔGwt = WT_RepairPDB_4TVF_1_0.pdb = -46.0464 kcal/mol
  • => ΔΔG = ΔGmut-ΔGwt = (-41.1377)-(-46.0464) = +4.9087 kcal/mol

One file contains the average difference over all runs: "Average_BuildModel_RepairPDB_4K33.fxout".
You will notice that the difference in free energy ΔΔG is +4.84 kcal/mol (+- 0.06 kcal/mol).

=> It means the mutation L280D is highly destabilising (positive value, and much above 1.0 kcal/mol). Here is the final mutant:


PS: Another way to define the threshold is to use the SD deviation multiple times:

The reported accuracy of FoldX is 0.46 kcal/mol (i.e., the SD of the difference
between ΔΔGs calculated by FoldX and the experimental values). We can bin the ΔΔG values into seven categories:
  1. highly stabilising (ΔΔG < −1.84 kcal/mol); 
  2. stabilising (−1.84 kcal/mol ≤ ΔΔG < −0.92 kcal/mol); 
  3. slightly stabilising (−0.92 kcal/mol ≤ ΔΔG < −0.46 kcal/mol); 
  4. neutral (−0.46 kcal/mol < ΔΔG ≤ +0.46 kcal/mol);
  5. slightly destabilising (+0.46 kcal/mol < ΔΔG ≤ +0.92 kcal/mol);
  6. destabilising (+0.92 kcal/mol < ΔΔG ≤ +1.84 kcal/mol);
  7. highly destabilising (ΔΔG > +1.84 kcal/mol).