FoldX tools in YASARA

Preface

In this section we explain the various FoldX functionalities inside YASARA. It is recommended that you have practiced with YASARA and FoldX before. But don't worry, all commands are straightforward and easy to use. That's the point of the plugin . However, we will refer to YASARA specific nomenclature such as Objects and Molecules. Their definition can be found in the YASARA documentation on your computer in yasara/doc/index.html.

Sometimes we will not explain all details on the FoldX commands provided in this plugin but refer to the detailed FoldX manual which can be downloaded at http://foldx.crg.es.

The output of FoldX calculations is always printed to the YASARA console when the plugin ends. The console should open by default, but when it fails, you can enter the console by pressing the spacebar once or twice.

FoldX tools menu in YASARA

All FoldX tools in YASARA can be accessed by clicking:

Analyze > FoldX > ...

Context menus

A subset of the FoldX tools is also accessible via the atom-, residue-, molecule- and object-context menus. The atom context menu appears when an atom is selected and the right-mouse button is clicked. The residue context menu appears when a residue in the sequence selector is right-clicked (see screenshot below).

Residue-context menu appears when a residue in the sequence selector is right-clicked

This way of accessing some of the FoldX tools has been made to speed up quick analysis, as the right-clicked atom or residue is automatically selected for analysis. When selecting calculations on a YASARA Object through these context menus, the selected Object is the one the right-clicked atom or residue belongs to.

The object and molecule context menus appear when an object or molecule is right-clicked in the top-right head-up-display (HUD) (see screenshot below).

Object-context menu appears when an object in the HUD is right-clicked

FoldX energies

The main focus of FoldX is the prediction of free energy changes, e.g. what happens to the free energy of the protein when we mutate an Asp to a Tyr? FoldX will then calculate the free energy of the wild type (WT) and the mutant (MT) and make the difference:

<math>\Delta\Delta</math>G(change) = <math>\Delta</math>G(MT) - <math>\Delta</math>G(WT)

FoldX is trained to make <math>\Delta\Delta</math>G(change) approach experimental values. It is important to realize that <math>\Delta</math>G(WT) and <math>\Delta</math>G(MT) are meaningless numbers as such. These do not correlate with experimental values. Only <math>\Delta\Delta</math>G(change) does.

As a rule of thumb we use:

<math>\Delta\Delta</math>G(change) > 0 : the mutation is destabilizing

<math>\Delta\Delta</math>G(change) < 0 : the mutation is stabilizing

The error margin of FoldX is approximately 0.5 kcal/mol, so changes in that range are insignificant.

Number of runs

This option affects the FoldX BuildModel command, which is behind the plugin commands Mutate residue, Mutate multiple residues and Build homology model. It tells FoldX how many times it should do the specified mutations. We recommend the default number of 3 runs. This is to see if the algorithm has achieved convergence, or in other words if the solution offered is the optimal or a trapped solution. Note that a high number of runs will take equivalent more time for the algorithm to finish the mutagenesis.

When it is larger than 1 the algorithm will do the same mutations but changing the rotamer set used and the order of the rotamer moves. In this way other alternative solutions could be explored. For most of the mutations this will not result in significant differences from one run to the other. However, in some cases, like mutations involving Arg (as mutation site or as residue close to the mutation site) with many degrees of freedom in the sidechain, significant differences could be found.

Calculation speed

The calculations were performed on a Linux pc with an Intel Core Duo2 2,8GHz processor with 3MB of RAM memory. Repairing a structure is the most computationally intensive procedure as all sidechains have to be re-evaluated for their energy. This takes on average 2-5 minutes for a protein of about 300 residues. One point mutation takes a few seconds for mutating to small amino acids to 1-2 minutes for larger amino acids with more degrees of freedom in their sidechain (R,K). Calculation of interaction energy is a matter of seconds.

Protein, DNA, nucleotides and metals recognized by FoldX

Below are lists of molecules that are recognized by FoldX. This implies that FoldX can include these in the free energy predictions. For example, it is thus possible to predict the effect of an amino acid mutation on DNA binding or metal binding .

List of amino acids

Name	3-letter	1-letter	Mutable in FoldX	Mutable in plugin
Alanine	Ala	A	Yes	Yes
Arginine	Arg	R	Yes	Yes
Asparagine	Asn	N	Yes	Yes
Aspartic acid	Asp	D	Yes	Yes
Cysteine	Cys	C	Yes	Yes
Phenylalanine	Phe	F	Yes	Yes
Glutamine	Gln	Q	Yes	Yes
Glutamic acid	Glu	E	Yes	Yes
Glycine	Gly	G	Yes	Yes
Histidine	His	H	Yes	Yes
Isoleucine	Ile	I	Yes	Yes
Leucine	Leu	L	Yes	Yes
Lysine	Lys	K	Yes	Yes
Methionine	Met	M	Yes	Yes
Proline	Pro	P	Yes	Yes
Serine	Ser	S	Yes	Yes
Threonine	Thr	T	Yes	Yes
Tryptophan	Trp	W	Yes	Yes
Tyrosine	Tyr	Y	Yes	Yes
Valine	Val	V	Yes	Yes
Phosphotyrosine	Ptr	y	Yes	Yes
Phosphothreonine	Tpo	p	Yes	Yes
Phosphoserine	Sep	s	Yes	Yes
Sulphotyrosine	Tys	z	Yes	Yes

List of DNA nucleotides

Name	PDB file code	1-letter	Mutable in FoldX	Mutable in plugin
Adenosine	A	a	Yes	Yes
Guanine	G	g	Yes	Yes
Cytosine	C	c	Yes	Yes
Thymidine	T	t	Yes	Yes
6-methylated adenosine	6MA	b	Yes	No
5-methylated cytosine	5CM	d	Yes	No

List of nucleotides

Name	PDB file code
Adenosine diphosphate	ADP
Adenosine triphosphate	ATP
Guanosine diphosphate	GDP
Guanosine triphosphate	GTP

List of metals

Name	PDB file code
Calcium	CA
Magnesium	MG
Manganese	MN
Sodium	NA
Zinc	ZN
Iron	FE
Copper	CU
Cobalt	CO
Potassium	K

Waters

Name	PDB file code
Water	HOH

Fix residues

FoldX commands such as RepairPDB (the FoldX energy minimization) and BuildModel (make mutations or complete models) will move residues by default. RepairPDB minimizes a structure by rearranging the sidechains to find a new energy minimum. BuildModel will rearrange neighbouring residues of a mutation spot to optimize the mutated protein.

There are cases where the user does not want certain residues to move, either during RepairPDB or BuildModel.

The 'Fix residues' command lets you select residues that will not move during a RepairPDB or BuildModel.

The fixed residues will be colored in yellow (see screenshot). Do not confuse Fixed residues from the FoldX plugin with fixed residues from the simulation menu from YASARA (only in YASARA Dynamics and YASARA Structure). These are totally independent.

Fixed residues are colored in yellow

Free residues

In case you want to unfix one or multiple residues that have previously been fixed with the Fix residues command, you can use the Free residues command.

The 'Free residues' command unfixes previously fixed residues. These freed residues will be allowed to move during a RepairPDB or BuildModel.

Repair object

This command executes the FoldX RepairPDB command. RepairPDB minimizes the energy of a protein structure by rearranging the amino acid sidechains in order to get a better free energy of the protein (see screenshot). RepairPDB only rearranges sidechains, not the backbone. Residues that should not be rearranged should be fixed by using the 'Fix residues' command.

'Repair object' does an energy minimization of the selected Object by running the FoldX RepairPDB command and is required to get accurate 

results when subsequently calculating the stability, interaction energy or when making mutations with FoldX.

Result of a RepairPDB run with the repaired structure in green

The way RepairPDB operates is the following:

1. First it looks for all Asn, Gln and His residues and flips them by 180 degrees. This is done to prevent incorrect rotamer assignment in the structure due to the fact that the electron density of Asn and Gln carboxamide groups is almost symmetrical and the correct placement can only be discerned by calculating the interactions with the surrounding atoms. The same applies to His.
2. We do a small optimization of the side chains to eliminate small VanderWaals’ clashes. This way we will prevent moving side chains in the final step.
3. We identify the residues that have very bad energies and we mutate them and their neighbors to themselves exploring different rotamer combinations to find new energy minima.

We refer to the FoldX manual for an even more detailed explanation on repairing PDB structures.

Stability of object

The FoldX Stability command calculates the free energy of unfolding (delta G). This is the difference in free energy between the folded state and the unfolded state. The lower the energy, the more stable the structure is.

'Stability of object' calculates the free energy difference of a selected Object.

To get the most accurate results, we recommend to use the Repair object command first.

It should be noted that stability values (in contrast to stability changes) do not reflect experimental values, but large (> 10kcal/mol) positive values might indicate a problem in the overall architecture of the structure).

The stability in kcal/mol is shown in the YASARA console

Alanine scan of object

'Alanine scan of object' mutates every residue in an object to alanine and calculates the energy difference upon mutation to alanine.

A custom settings menu is available to set the following options:

Set FoldX options

• Temperature: Temperature (K).
• pH: At the moment only used for pH effects on metal binding. Will not affect the protonation of charged groups in this version.
• Ionic strength: Ionic strength of the solution (M) x 100. The multiplication by 100 was needed for YASARA implementation since no decimal numbers are allowed in menus. So the default of 5 is actually 0.05M.
• Van der Waals design: When set to 2, it considers rotamer penalizations due to internal clashes, maximum penalization for interresidue VanderWaals’ clashes, a ceiling for the VanderWaals’ clashes between two atoms of 5 kcal/mol and strict H-bond geometry. When set to zero there is a weak rotamer penalization, there is a ceiling for the VanderWaals’ clashes of 1 kcal/mol and we use a relaxed H-bond geometry. This option should be set to 0 when doing an Ala scanning mutagenesis of a protein (default set to 0 in the plugin for alanine scanning). Whenever doing design, or repairing a PDB, it should be set to 2.

The results of the alanine scan are displayed in the console (see screenshot). Press the spacebar twice to enlarge the console. The same results are also listed in a tab-delimited text file called FOLDXSUMMARY.out in the cache folder. This file can be saved in a custom folder alone or together with all other output files using the option Save last calculation.

Result of an alanine scan is displayed in the console

Energy analysis of object

'Energy analysis of object' prints a full energy decomposition per residue in the selected objects.

This command runs the FoldX SequenceDetail command and prints the energy contribution per residue in the structure as well as a decomposition of the per-residue energy in its separate terms. Other per-residue information such as dihedral angles, residue burial and secondary structure is also printed.

The results are stored in the FOLDXSUMMARY.out file which can be saved by choosing 'Save last calculation'.

To get the most accurate results, it is necessary to run the Repair object command first.

Hydrogen bonds of object

This command draws hydrogen bonds between donor and acceptor atoms as calculated with the PrintNetworks command from FoldX.

After selecting one or more objects, an option menu is presented:

Options for showing hydrogen bonds

1. Color all bonds in same color: all detected hydrogen bonds will be magenta lines
2. Color weak and strong HBonds using cut-off below: hydrogen bond strength is calculated by FoldX from 0 till 1 depending on the distance and angles between donor and acceptor atoms. Hydrogen bonds below the cut-off will be considered as weak and colored green, hydrogen bonds above the cut-off are then strong bonds and are colored magenta.
3. Only show interface HBonds: choose this option when your object contains more than one molecule and you want to show the intermolecular hydrogen bonds only.

Remark: In order for this command to work properly, all molecules should have unique names, i.e. no two molecules should have the same name. Pay extra attention because water molecules and metals can have the same molecule name as a protein chain. In that case delete the waters and metals or rename them all at once by right-clicking on them in the HUD and choose Rename.

In order to make this option compatible with YASARA View, drawing all hydrogen bonds in large structures may take some time (minutes).

We recommend to use both this FoldX command and the YASARA hydrogen bonds to have a complete view of the hydrogen bonds in the object. Depending on the way these programs calculate hydrogen bonds, the results can differ.

Interaction energy of molecules

This option executes the FoldX AnalyseComplex command. It determines the interaction energy between 2 selections of Molecules.
It is allowed to select more than 1 molecule in each selection window. E.g. if you select molecules A and B in the first selection and C in the second selection, A and B are joined in one entity AB. The interaction energy between AB and C is then calculated. The results are displayed in the console.

The way it operates is by unfolding the selected targets and determining the stability of the remaining molecules and then subtracting the sum of the individual energies from the global energy. In case there is a metal bound between the two molecules it will assign it to the one which makes the stronger interactions with the metal. So, clearly:

'Interaction energy of molecules' calculates the interaction energy between two selections of Molecules.

More negative energies indicate better binding. Positive energies indicate no binding.

As an extra, this command also lists the residues at the interface of the selected molecules in the console.

Result of interaction energy calculation between joined molecules ABD and molecule C. Also the interface residues are printed.

To get the most accurate results, we recommend to use the Repair object command first.

Burial of residue

'Burial of residue' calculates the burial (or vice versa the solvent accessibility) of one or more residues.

This command executes the FoldX SequenceDetail command and parses the residue burial from the output. The burial is then displayed in the YASARA console (Figure below).

Result of residue burial calculation in the YASARA console.

Residue burial is expressed as a value from 0 to 1 where:

0 is completely exposed

1 is completely buried

'Burial of residue' will always output the burial for the mainchain (MC Burial) and burial for the sidechain (SC Burial) of the selected residue(s). This command is also available in the atom- and residue-context menus.

Mutate residue

'Mutate residue' mutates one amino acid residue or DNA nucleotide to one or more new amino acid residues or DNA nucleotides using FoldX BuildModel.

This command executes the FoldX BuildModel command . Subsequently the user is presented with following menus:

Residue selection menu

• Here you can select one residue to mutate to other residue types. Please note that when a DNA nucleotide was selected, its pairbase will also be mutated to the matching type.

Residue selection menu

Select FoldX routines

• RepairPDB: repairs the structure as in Repair object before making the mutation. The mutations will be made using this repaired structure.
• Calculate stability change: calculates and display the stability change upon mutation. So the difference in stability between mutant and wild type structure. This predicts whether a mutation will stabilize or destabilize a structure. Stabilizing mutations will have a negative value (ddG).
• Calculate interaction energy change: this option should only be used when the Object contains multiple Molecules. It calculates and displays the interaction energy change between any possible pair of Molecules in the Object after mutation.
  

Selection menu for FoldX commands

Note: the output will contain a column named 'corrected interaction energy'. This is the interaction energy corrected for intrachain clashes. See the FoldX manual for more information.

Select new residue(s)

• here you can select the residues that should replace the original residue. Each selected residue will result in a new model made with FoldX.

Selection menu for new residues

Set FoldX options (1)

• Move neighbours: this lonely option is on by default and allows residues around the mutation spot to be moved to accommodate the new residue. In case you don't want these neighbours to move, uncheck the option.
• Zoom to mutation site: checking this option will automatically close-up to the mutation site for quick visual inspection.
• Show disrupted and new hydrogen bonds: checking this option adds hydrogens to the structure and shows the hydrogen bonds in the wild type and mutated structure.
• Show VdW clashes in WT and mutant: checking this option will highlight in red Vander Waals clashes in wild type and mutant structures.

First options menu

Set FoldX options (2)

• Number of runs: This option tells the algorithm how many times it should do the specified mutations. Look here for more information.
• Temperature: Temperature (K).
• pH: At the moment only used for pH effects on metal binding. Will not affect the protonation of charged groups in this version.
• Ionic strength: Ionic strength of the solution (M) x 100. The multiplication by 100 was needed for YASARA implementation since no decimal numbers are allowed in menus. So the default of 5 is actually 0.05M.
• Van der Waals design: When set to 2, it considers rotamer penalizations due to internal clashes, maximum penalization for interresidue VanderWaals’ clashes, a ceiling for the VanderWaals’ clashes between two atoms of 5 kcal/mol and strict H-bond geometry. When set to zero there is a weak rotamer penalization, there is a ceiling for the VanderWaals’ clashes of 1 kcal/mol and we use a relaxed H-bond geometry. This option should be set to 0 when doing an Ala scanning mutagenesis of a protein. Whenever doing design, or repairing a PDB, it should be set to 2 (default in the RepairPDB in this plugin).

Second options menu

After the mutation design the Repaired structure (if selected) and all the runs of the mutations will be loaded into YASARA as new Objects. All of these will be structurally aligned (superposition) for direct comparison (see screenshot below).

The requested output (stability change, interaction energy change) will be plotted in the YASARA console (see screenshot below). The individual energies as well as the average energy over all runs will be printed.

Result of a mutation from Val to Arg and Ile in 3 runs each. Each mutation is loaded as a new object and the energy difference is printed in the console

The same results are also listed in a tab-delimited text file called FOLDXSUMMARY.out in the cache folder. This file can be saved in a custom folder together with all other output files using the option Save last calculation.

All models and repaired structures can be saved as PDB files by clicking (for each object separately):

File > Save as > PDB File

Or you can save the entire YASARA scene keeping all Objects, colors and orientation including superposition by clicking:

File > Save as > YASARA Scene

To get the most accurate results, we recommend to use the Repair object command first.

For reference, this table lists all residues with their 1-lettercode and 3-lettercode as used in the plugin

Name	3-letter	1-letter
Alanine	Ala	A
Arginine	Arg	R
Asparagine	Asn	N
Aspartic acid	Asp	D
Cysteine	Cys	C
Phenylalanine	Phe	F
Glutamine	Gln	Q
Glutamic acid	Glu	E
Glycine	Gly	G
Histidine	His	H
Isoleucine	Ile	I
Leucine	Leu	L
Lysine	Lys	K
Methionine	Met	M
Proline	Pro	P
Serine	Ser	S
Threonine	Thr	T
Tryptophan	Trp	W
Tyrosine	Tyr	Y
Valine	Val	V
Phosphotyrosine	Ptr	y
Phosphothreonine	Tpo	p
Phosphoserine	Sep	s
Sulphotyrosine	Tys	z

Mutate multiple residues

This option does in many ways the same as the Mutate residue option. The difference is that with this option you can make multiple mutations in one structure, such as double, triple, ... mutations on more than one residue position.

'Mutate multiple residues' allows to select multiple residues and indicate the replacing amino acids for multiple mutations in one structure.

The main differences in the menus that are presented are:

Residue selection menu

• Here you can select multiple residues to mutate with FoldX

Residue selection menu allows to select multiple residues to mutate simultaneously

New amino acids

• In this text box you have to type the new amino acids in sequential order in 1-lettercode as given in the table above. E.g. if you selected in the first menu residues T13, A30, R54 and W67, you indicated that you want to make four simultaneous mutations in the structure. In the text box you then type four replacing amino acids e.g. SLEY. This means that following mutations will be made: T13S, A30L, R54E and W67Y. Note that the amino acid 1-lettercode is case sensitive (!), since this allows for modified amino acids to be handled by FoldX (see the amino acid table above).

In the text box we type in N to C order the replacement residues of those we selected in the previous residue selection menu

The rest of the menus work in the same way as in Mutate residue.

After the mutation design the Repaired structure (if selected) and all the runs of the mutations will be loaded into YASARA as new Objects. All of these will be structurally aligned (superposition) using the Mustang algorithm for direct comparison.

The requested output (stability change, interaction energy change) will be plotted in the YASARA console. The same results are also listed in a tab-delimited text file called FOLDXSUMMARY.out in the cache folder. This file can be saved in a custom folder together with all other output files using the option Save last calculation.

All models and repaired structures can be saved as PDB files by clicking (for each object separately):

File > Save as > PDB File

Or you can save the entire YASARA scene keeping all Objects, colors and orientation including superposition by clicking:

File > Save as > YASARA Scene

To get the most accurate results, we recommend to use the Repair object command first.

Build homology model

When a homology modeling task is desired or the number of mutations to make is too large for the option Mutate multiple residues, the 'Build homology model' option is your choice for the job.

'Build homology model' will run FoldX BuildModel to model a given target sequence on a selected template structure object.

When this option is selected the following menus are presented:

Object selection menu

• A single object that serves as the template structure can be selected here

Select alignment file

• The alignment file is a plain text file containing only two lines. The first line represents the sequence of the template protein. This can also be just a part of the template protein, as long as this sequence exists in the template structure. FoldX will always model in the context of the whole structure, so the part of the template that you did not type in the alignment file will still be in the final model. The second line holds the target sequence of the protein to be modeled. This sequence has to be of the same length as the sequence of the template on the first line and can only contain valid 1-letter amino acid characters. Modeling insertions and deletions is not yet possible in the current version of FoldX.

Tip: Extract the sequence of the template structure using the YASARA command ListRes or click
Analyze > List > Residue to get the exact amino acid sequence of the template structure.
Copy and paste the template sequence (or just the part you want to align) from the Console to a text editor on the first line. 
Then, align it with the target sequence by typing the target sequence on the second line.
Save the alignment to a file and feed this file to the plugin.

Example alignment file:

GSSPKAVALYSFAGEESGDLPFRKGDVITILKKSDSQNDWWTGRVNGREGIFPANYVELV
GSSPRAVALYSYAGDDSGDLPFRKGDLIRGLKKSDSQSDNWTGRMNGRKMIFPANYVELV

First line contains the template sequence (does not have to be the full sequence of the template structure).
Second line contains the target sequence to be modeled.

The rest of the menus work in the same way as in the Mutate residue option.

The resulting homology models (more than one if more than one run) will be loaded as YASARA Objects.

Save last calculation

This option lets you specify a target folder and/or filename prefix for the beginning of all files of the last calculation to be saved. A calculation is either a Repair, Alanine scan, Energy analysis, BuildModel (Mutate residue, Mutate multiple residues, Build homology model), Interaction energy, Stability.

The first selection window lets you choose whether you want to save all files or just the FOLDXSUMMARY.out file. This file contains mutation energies and is only created after an alanine scan or a mutation run.

In the next selection window you can either select a single folder or a folder and filename prefix:

• Folder: E.g. selecting c:\testrun\ will save all last calculation files to that folder.
• Folder with filename prefix: E.g. selecting c:\testrun\MyRun will save all last calculation files to the testrun folder and put MyRun_ before every filename. In this way, it is possible to save more than one calculation in the same folder by using different prefixes.

'Save last calculation' saves the FoldX output files of the last calculation to a user-specified folder with optional filename prefix.

For more information on the content and format of FoldX output files we refer to the FoldX manual that can be downloaded from foldx.crg.es.

Configure plugin

See the section Installation and first use for explanation of this option.