#!/usr/bin/perl -w

# dammin_reconstruction_series.pl
# -------------------------------------------------------------------
# This script is a wrapper to run a series of ab initio structure 
# reconstructions from SAXS data using the program DAMMIN.
# Running multiple reconstructions for the same SAXS profile
# is useful in order to test the reproducibility and robustness of the
# the structure reconstructions. 
#
# Author: Jan Lipfert
# Date: 11/1/2007
# 
### --- ACKNOWLEDGEMENT AND CITATION --- ###
# If you find this script useful, please cite it as
#
# Jan Lipfert, Rhiju Das, Vincent B. Chu, Madhuri Kudaravalli, Nathan Boyd, 
# Daniel Herschlag, and Sebastian Doniach   
# "Structural Transitions and Thermodynamics of a Glycine-Dependent Riboswitch from Vibrio cholerae" 
# J. Mol. Biol. 365:1393-1406 (2007)
#
#
#
# The script calls the program DAMMIN: 
# D.I. Svergun
# "Restoring low resolution structure of biological macromolecules from solution scattering 
#  using simulated annealing." Biophys. J., 76:2879-2886 (1999)
#
# 
###--- BEFORE THE SCRIPT CAN BE USED ---###
# The script requires a working copy of DAMMIN to be installed
# and executable on the system. DAMMIN can be downloaded from
# http://www.embl-hamburg.de/ExternalInfo/Research/Sax/dammin.html
# 
# To let the script know which version of dammin to run 
# (and possibly the path to where DAMMIN is installed), 
# set the $DAMMIN_exec variable (in the script after this header) 
# Examples: 
# $DAMMIN_exec = 'dammin51.osx';
# (Example for use with the Mac-OS and with the executable in the path)
# $GNOM_exec = '/home/lipfert/software/dammin/dammin51.l86';
# (Example for use on a Linux operating system, with specification of the full path)
#
###--- USAGE OF THE SCRIPT AND OUTPUT ---###
# After the $DAMMIN_exec has been set,
# the script can be run from the command line with 4 arguments:
#
# 1) <gnom_file.out> is the input. This should be the output of the program GNOM.
# To run GNOM for a series of Dmax values, see the script gnom_Dmax_scan.pl. 
#
# 2) <projectname (NO DOTS!)> is an arbitrary name, which cannot have dots in the file name
# and cannot be longer than 8 characters in length. It determines the name of the output files. 
# The output files will be called
# <projectname>_SA.extension to <projectname>_SB.extension
# The letter S denotes the "slow" mode in which dammin is run (see below).
# A and B are the first and last index used (see below).
# "extension" denotes the file extension (see below)
# 
# 3) and 4) The 3rd and 4th argument are the first and last index to be used;
# The script will run reconstructions with indices from the first to the last index,
# incrementing by 1.
# In order to run e.g. 10 reconstructions use 0 and 9 as the first and last index. 
#
#
### --- OUTPUT FILES --- ###
# The program output are 5 files per reconstruction 
# (each reconstruction run is denoted by an index, "?" below); 
# <projectname>_S?.fit has the fit to the desmeared and smoothed data from GNOM.
# <projectname>_S?.fir fit to the experimental data
# <projectname>_S?-0.pdb is a PDB file with the beads of the initial search volume
# <projectname>_S?-1.pdb is a PDB file with the beads of the final reconstruction
# <projectname>_S?.log is the DAMMIN log file
#
#
### --- FURTHER TOOLS --- ###
# The reconstructed models can be visualized with any PDB viewer,
# e.g. VMD (http://www.ks.uiuc.edu/Research/vmd/), 
# PyMol (http://pymol.sourceforge.net/), RasMol, etc.
#
# In order to render the reconstructed models as an electron density,
# you can use the software Situs (http://situs.biomachina.org/; follow the link "SAXS Info")
#
# To compare different models, and to build consensus models, 
# the models from a series of reconstructions
# can be averaged and compared using the programs DAMAVER and SUPCOMB.
# The script damaver_series_average.pl provides a convenient wrapper for this.
#
### --- DIFFERENT RECONSTRUCTION MODES/PARAMETERS --- ###
# This script defaults to using the "slow" mode for DAMMIN
# reconstructions (which provides higher resolution than the FAST mode)
# and default parameters. To use different parameters, the 
# options written to the input ("run") file can be changed below.
# Consult the DAMMIN manual for options and syntax:
# http://www.embl-hamburg.de/ExternalInfo/Research/Sax/manual_dammin.html 



###---   Set this variable to the name and path of the DAMMIN executable   ---###
$DAMMIN_exec = "/home/lipfert/software/dammin/dammin51.l86";


###---   START OF SCRIPT    ---###
if(!(defined($ARGV[0])) || !(defined($ARGV[1])) || !(defined($ARGV[2])) || !(defined($ARGV[3])) )
{
    die "Usage: ./dammin_reconstruction_series.pl <gnom_file.out> <projectname (NO DOTS!)> <1st #> <last #> \n";
}
 

$gnomfile = $ARGV[0];
$basename = $ARGV[1];
$first_recon = $ARGV[2];
$last_recon = $ARGV[3];

### Check whether GNOM file exists ###
if(!(-e $gnomfile))
{
    die "GNOM file $gnomfile does not exist!\n";
}

### Now do the reconstructions ###

for($i=$first_recon; $i<($last_recon + 1); $i++)
{
    ### Make the input file for DAMMIN ###
    $runname = "run." . $basename . "_S" . "$i";
    open OUT, ">$runname" or die "Can't open $runname \n";
    $jobname = $basename. "_S" . "$i";

    print OUT "S\n";   # Run DAMMIN in slow mode; change to "F" for fast mode
    print OUT "$jobname\n";
    print OUT "$gnomfile\n";
    print OUT "$jobname\n";
    print OUT "1\n";
    print OUT "1.0\n";
    print OUT " \n";
#    print OUT "P2\n"; # For P2 symmetry
    print OUT "P1\n";  # Use P1 symmetry (i.e.no symmetry)
    print OUT "U\n";   # Unknown initial shape of the molecule
    close OUT;

    ### --- Set the name and path of the DAMMIN executable above after the header --- ###
    system("$DAMMIN_exec < $runname");

    system("rm $runname");
}