MultiMutate  and  CombinatorialMutate
=====================================

Last updated on 04/03/07
------------------------

Usage
-----

Default usage

  > ./MultiMutate <PDBLIST>
  > ./MultiMutate <PDBLIST> profile
  > ./MultiMutate <PDBLIST>  <  <inputfile>

  (items given in [ ] are optional.)

PDBLIST is a text file which has the PDB names (4-character code) and 
corresponding chain identifiers (use '_' if no chain identifier specified),
listed one below the other as follows:

2CI2 I
2CI2 I
2ACY _
2ACY _
2ACY _
1AHT H
1LBD _
...


If you want to score multiple mutants of the same PDB chain, then the
PDB code and chain have to be repeated as many times. In the example
above, the program will score two mutants of 2CI2, three of 2ACY, and
then one each of 1AHT and 1LBD.

For each PDB, the program asks the user to input the number of residues
to be mutated, followed by the list of the residues in the following 
format:  24 ALA 59 TYR 134 ARG ...


** IMPORTANT ** : The program assumes that there is a directory named
"Profiles" (with a capital P) in the current working directory. By giving 
the command-line option profile (or Profile), the program will write the
residue-wise profile of the PDB chain and store the file inside the
directory Profiles. If the mutant in question is obtained by changing
residue 24 to ALA and residue 59 to TYR in 2CI2 chain I, the profile
will be written to the file 2CI2I_24ALA_59TYR saved inside the
subdirectory Profiles. Similarly, when changing residues 19,39,59, and
79 all to ALA in 2ACY (no chain identifier), the profile will be written
to the file Profiles/2ACY__19ALA_39ALA_59ALA_79ALA.


Examples
  > ./MultiMutate list_mutate
  > ./MultiMutate list_mutate Profile


All the options available for GetProfile can be used for MultiMutate
as well. Thus, to score a bunch of mutants using C-alpha coordinates,
11.2 A distance cut-off, using only the tetrahedra of type 0, 2, and 3,
and to write the profiles involved, one can say

  > ./MultiMutate list_mutate ca 11.2 Profile 3 0 2 3

or

  > ./MultiMutate list_mutate Profile 3 0 2 3 11.2 ca


Read the file Readme_GetProfile to learn more about the various options
available.



To score several mutants in one go, all the required input could be
written up in a text file and fed to the program as input at the 
command line. Consider the following list of mutants:

1. In 2ACY _, change 24 to ALA, 59 to TYR
2. In 2ACY _, change 33 to LEU, 81 to MET, 89 to ARG
3. In 1ERX A, change residues 23, 48, and 81 to GLY
4. In 2CI2 I, change residue 39 to LEU.

Create a list of PDBs and chains (named list_mutate.txt say) which looks
like the following:

2ACY _
2ACY _
1ERX A
2CI2 I


Then create a text file containing all the mutation information 
(named input_mutate.txt) as follows:

2 24 ALA 59 TYR
3 33 LEU 81 MET 89 ARG
3 23 GLY 48 GLY 81 GLY
1 39 LEU

Notice that the first entry in each line gives the number of amino
acids mutated in each case.

Give the following command:


  > ./MultiMutate list_mutate.txt Profile < input_mutate.txt

The program will take all the input from the file inputmutate
(instead of the user interactively typing in the items one by one).
The sign '<' is used to tell the program to take the input from
the file mentioned after the sign.


The additional options can still be used under this set-up -- to
score the above mutants using the 6-residue classification, using
C-beta coordinates, and NOT write profiles, one could say


  > ./MultiMutate list_mutate.txt cb 6 < input_mutate.txt


All the output from the program is written to the screen by default.
To save the output to a file, use the redirection sign '>', and
provide a filename after that, as illustrated below:


  > ./MultiMutate list_mutate.txt Profile < input_mutate.txt > outputmutate.txt


If you want to append the output to an output file (and not overwrite
it), use >> instead of >.

  > ./MultiMutate list_mutate.txt Profile < input_mutate.txt >> outputmutate.txt



CombinatorialMutate
-------------------

CombinatorialMutate works similar to MultiMutate, but can score all
mutants generated by considering multiple combinations of possible
amino acid replacements at multiple sites. The combinations are
generated (and scored) for several chains provided in the PDB_LIST
file list_mutate. All the input could be written to a text file and
provided to the program using the '<' redirection (in the same way as
for MultiMutate). THIS PROGRAM IS IDEALLY USED FOR SCORING HUGE
NUMBERS OF MUTANTS, AND HENCE CURRENTLY DOES NOT WRITE PROFILES FOR
EACH MUTANT. FURTHER, THE PROGRAM DOES NOT PROMPT THE USER FOR ANY
INPUT EITHER. IT IS RECOMMENDED THAT ALL INPUT BE WRITTEN UP IN TEXT
FILES AND PROVIDED USING THE '<' RE-DIRECTION (of course, one could
provide all the input at the command prompt also). For instance,
consider the following combinations that need to scored:

 In 1ERX chain A, consider changing residue 27 to ALA, ILE, or LEU,
 and residue 109 to CYS or HIS. Thus, we need to score 6 (=2x3)
 mutants of 1ERXA.

 In 2CI2 chain I, consider changing residue 25 to ARG, MET, CYS, or
 LEU, residue 47 to ALA, and residue 75 to MET, ARG, or TYR. Thus,
 we need to score 12 (=4x1x3) mutants of 2CI2I.

 In 2ACY (no chain), consider changing residue 42 to ALA and
 residue 67 to ILE. Thus, we need to score only a single (1x1)
 mutant of 2ACY_.


Create the list of chains (list_mutate.txt) with the following lines:

1ERX A
2CI2 I
2ACY _

Then create a text file containing all the mutation information 
(named input_comb.txt) as follows:

2 27 3 ALA ILE LEU 109 2 CYS HIS
3 25 4 ARG MET CYS LEU 47 1 ALA 75 3 MET ARG TYR
2 42 1 ALA 67 1 ILE


Note that the first entry in each line gives the number of sites in
each chain considered for mutation. Further, the residue number of 
each site is followed by the number of alternate amino acids, and then
by the names of the alternate amino acids themselves.


The multiple mutants for each of the three chains can be scored
using the following command:

 > ./SiteCombMutate list_mutate.txt < input_comb.txt

The program writes the output for each chain on to separate files
titled 'Mutants_<pdbname><chain>_<num_mutants>.txt'. For instance, the
details for all the six mutants of 1ERX chain A will be written to the
file Mutants_1ERXA_6.txt, and stored in the working directory. Each
such output file lists the name of each mutant, followed by the score
of the native chain, the change in total score for the mutant.