MrBUMP - version 0.4.1
Automated search model generation and Molecular Replacement

###################################
About MrBUMP
###################################

MrBUMP is an automated scheme for Molecular Replacement. Given 
a target sequence and experimental structure factors, it will 
search for homologous structures, create a set of suitable 
search models from the template structures, do molecular 
replacement, and test the solutions with some rounds of restrained 
refinement.

** IMPORTANT * IMPORTANT * IMPORTANT **

MrBUMP relies heavily on the use of web-based sevices and applications 
for carrying out the template search part of the procedure. It also
retrieves PDB files from the web to construct the search models. If
you are sensitive about your target sequence data it is suggested that
you download and install the fasta34 program so that you can run the 
sequence-based searches locally. This is availble from the EBI site:

http://www.ebi.ac.uk/fasta/

###################################
Installation: Linux/Mac
###################################

1. Prerequisites
   Before installing MrBUMP the following should be installed on your system:
      -   CCP4 version 6.0 or later 
            (available from: http://www.ccp4.ac.uk/download/)
      -   Python version 2.3 or later
            (This may have been installed with your CCP4 installation but it can
             also be found here: ftp://ftp.ccp4.ac.uk/python/) 
      -   Clustalw sequence alignment program
            (available from http://www.ebi.ac.uk/clustalw/)
                 -- and/or --
      -   Mafft sequence alignment program
            (available from http://www.biophys.kyoto-u.ac.jp/~katoh/programs/align/mafft/)
                 -- and/or --
      -   Probcons sequence alignment program
            (available from http://probcons.stanford.edu)
                 -- and/or --
      -   T_coffee sequence alignment program
            (available from http://www.tcoffee.org)
   The following optional programs are also recommended:
      -   Graphviz version 2.2 or later
            This is required for enabling the CCP4i DBviewer feature.
            (available from http://www.graphviz.org)
      -   Fasta34 for sequence based searching
            (available from http://www.ebi.ac.uk/fasta/)
      -   Perl + SOAP-Lite perl module (for SSM search)

   Mac OSX notes:
     Perl 5.8.6 on OS X is missing libwww-perl, required by SOAP::Lite
       perl -MCPAN -e 'install Bundle::LWP'
       perl -MCPAN -e 'install SOAP::Lite'

2. Installation
   a. Download the mrbump tarred zip file and save it to a convenient place on your computer.
   b. Unzip and un-tar the file.
   c. Go into the mrbump-0.4.0 folder and type:
     
      "python setup.py"
         
      This will automatically run through the installation procedure. If there are missing
      dependencies the script will give warning or error messages. If this happens, 
      install the missing dependencies and re-run "python setup.py".
   d. If everything is succesful you may delete the zip file and temporary folder. 
   c. The final thing to do is install the CCP4i task interface to MrBUMP and the CCP4i
      dbviewer. To do this follow the instructions in the section "Installing the MrBUMP
      tasks in CCP4i" below.    

3. Internet Connection - *** IMPORTANT ***
   MrBUMP makes use of several online resources for performing its template model searches
   and for downloading PDB files. Therefore, an internet connection is required (except for
   the case when using locally held PDB files). If you have to use a proxy server to get to
   the internet you will have to have it set in the environment of the shell from where you 
   launch ccp4i. For example, if you are using bash shell you might set the proxy like this:
   
   export http_proxy="http://www.mysiteproxy.ac.uk:8080/"

   Note also that you must restart CCP4i after you update the environment.

###################################
Installation: Windows (XP/Vista)
###################################

1. Prerequisites
   Before installing MrBUMP the following should be installed on your system:
      -   CCP4 version 6.0 or later 
            (available from: http://www.ccp4.ac.uk/download/)
      -   Python version 2.3 or later
            (available from ftp://ftp.ccp4.ac.uk/python/ - for Windows we recommend
             ActivePython)
      -   Clustalw sequence alignment program
            (available from http://www.ebi.ac.uk/clustalw/ - we recommend placing the
             clustalw.exe executable in your CCP4 bin folder so that it is accessible
             via the system path)
   The following optional programs are also recommended:
      -   Graphviz version 2.2 or later
            This is required for enabling the CCP4i DBviewer feature.
            (available from http://www.graphviz.org)
      -   Fasta34 for sequence based searching
            (available from http://www.ebi.ac.uk/fasta/)
      -   Perl + SOAP-Lite perl module (for SSM search)

2. Installation
   a. Download the mrbump zip file and save it to a convenient place on your computer.
   b. Unzip and extract the files to some temporary folder on your computer.
   c. Double click the "setup.cmd" program. This will automatically run through the 
      installation procedure. If there are missing dependencies the script will give
      warning or error messages. If this happens, install the missing dependencies
      and re-run "setup.cmd".
   d. If everything is succesful you may delete the zip file and temporary folder. 
   c. The final thing to do is install the CCP4i task interface to MrBUMP and the CCP4i
      dbviewer. To do this follow the instructions in the section "Installing the MrBUMP
      tasks in CCP4i" below.    

3. Internet Connection - *** IMPORTANT ***
   MrBUMP makes use of several online resources for performing its template model searches
   and for downloading PDB files. Therefore, an internet connection is required (except for
   the case when using locally held PDB files). If you have to use a proxy server to get to
   the internet you will have to set "http_proxy" in the environment on your machine.   

   To do this go the "Control Panel", select "System", then select the "Advanced" tab. 
   At the botton of this menu click on "Environment Variables". Enter a new variable as 
   follows:
  
   variable name: "http_proxy"

   variable value: "http://www.mysiteproxy.ac.uk:8080/" (replace with your local proxy name)
   
   Note also that you must restart CCP4i after you update the environment.

########################################
Installing the MrBUMP tasks in CCP4i
########################################

To install the MrBUMP CCP4i task carry out the following steps:

  1. Start the CCP4i gui, click on the 'System Administration'
     tab and select 'Install/uninstall Tasks'.
 
  2. Where it says 'Run the Installation Manager to' select 
     'install a new task'.

     (Note: Uninstall any existing version of the MrBUMP interface
     if you already have it installed. This is done by following
     steps 1 & 2 except you select 'uninstall an existing task'
     in step 2.) 

  3. Under the 'Install Package Information' section, where
     it says 'Task Archive', browse to the MrBUMP-ccp4i.tar.gz file
     which should be in the folder:
     $CCP4/ccp4i (on Windows this might be C:/CCP4-Packages/ccp4-6.0.2/ccp4i)

  4. When you have selected the MrBUMP-ccp4i.tar.gz file click on the
     'Apply' button.

  5. Restart ccp4i. The MrBUMP tasks should appear in the 
     'Program List' and 'Molecular Replacement' menus. The CCP4i dbviewer
     task should appear in the 'Program List' menu.

########################################
Running MrBUMP
########################################

MrBUMP:
   MrBUMP can be used via the CCP4i gui or from the command line. Here
   is an example of how to use MrBUMP on the command-line:

   mrbump HKLIN foo_in.mtz SEQIN foo.seq HKLOUT foo_out.mtz XYZOUT foo.pdb 
 
   MrBUMP is similar to other CCP4 programs in that it requires keywords.
   The user will be prompted for these keywords at the begining of a 
   job or they can be written to a file and passed into the program 
   on the command line.

   For details of the keywords for MrBUMP see the mrbump_doc.html file in the 
   $CCP4/html folder.

CCP4i DBviewer:
   If you have Graphviz installed you can access the CCP4i DBviewer to view 
   the state of a MrBUMP or access previously run MrBUMP jobs. You can also
   view previously run projects but any new projects added after the installation
   of MrBUMP will not be viewable in the interface.

#####################
New in version 0.4.1
#####################

1. Users can now enter pre-determined fix components in the MR search. This new 
   feature is a first step towards enabling MrBUMP to handle complexes automatically.
   The MrBUMP task interface includes a new section where fixed PDB files can be
   entered for use in the Molecular Replacement search. Supported by both Molrep and Phaser.
2. Another new addition to the task interface is the ability to set the name of a
   proxy server. If you need to use a proxy server at your site to access the internet
   you can enter the value for it in the "Additional options" section of the interface.

#####################
New in version 0.4.0
#####################

1. Support added for viewing the progress of a MrBUMP job using the CCP4i DB viewer. Note
   that this requires Graphviz to be installed on your machine. 
2. Removed the requirement for inputting an MTZ file when running in "Generate Models Only"
   mode.
3. Added windows support.

#####################
New in version 0.3.3
#####################

1. Added support for enantiomorphic spacegroups. If an enantiomorphic spacegroup
   exists for the target data then the user has the option to run MR in both spacegroups.
2. Added Acorn. Models can now be post-processed in Acorn to improve the phases in the map.
3. Support for other multiple alignment programs: PROBCONS and T_COFFEE.
4. Improvements to the database update mechanism.
5. Some tidying of the log output, and several bugs fixed.

#####################
New in version 0.3.2
#####################

1. Users can now add their own, locally stored PDB files to the search.
2. Any PDB id's included in the search by the user are automatically included
   in the MR stage, regardless of how they score in the multiple alignment.
3. FASTA search can be turned off if the user specifies search models.   
4. Updated GUI, includes a new section for user specified search models.
5. Fix for handling NMR models - 1st model in PDB file is extracted and 
   used as a search model.
6. SSM search fixed. 
7. Scoring of marginal and full solutions relaxed slightly.
8. Resolution of template PDBs output to log file. 
9. Phaser ensemble fixed.
10. Several other fixes.

#####################
New in version 0.3.1
#####################

1. Update to MR stage - can run Molrep/Phaser or both now.
2. Chains inclusion moved to Template search stage.
3. TRYALL keyword - all search models tried in MR or exit
   after first solution is found.
4. HTML output is now optional.

#####################
New in version 0.3.0
#####################

1. Display space group of the target MTZ file. 
2. Ability to run in "model generation only" mode.

#####################
New in version 0.2.5
#####################

1. Ability to include specific "chains" in the search models.
2. User entry of no. of molecules in the a.s.u.
3. User entry for PACK keyword in Phaser (clashing tolerence).

########################################
Authors
########################################

Ronan Keegan, CCP4, Daresbury Laboratory
email: r.m.keegan@dl.ac.uk

Martyn Winn, CCP4, Daresbury Laboratory
email: m.d.winn@dl.ac.uk
