===================================================
Readme/Help for MetalS2 (Metal-binding sites structural alignment tool)
Version: 0.1
Date: 06/03/2013
===================================================

Welcome to MetalS2!

MetalS2 is a new software tool for the structural alignment of Minimal Functional Sites (MFSs) in metal-binding biological macromolecules. The main application of the tool is detection of structural and functional similarities.

MetalS2 can align strucures from both protein and nucleotide molecules. The tool also copes with cases of shared protein/nucleotide compositional features. 

The program expects as inputs standard PDB files or PDB-like coordinate files downloaded from the MetalPDB database

This project was born due to the lack of existing programs that manage to achieve structural alignment of metal-binding sites, therefore MetalS2 works when other programs fail or give doubtful results.

===================================================

CONTENTS:
---------
I.	LICENSE INFORMATION
II.	SYSTEM REQUIREMENTS
III.	PREREQUISITES
IV.     INSTALLATON INSTRACTIONS
V.	DISTRIBUTION STRUCTURE
VI.     FEATURES AND FUNCTIONALITY
VII.    GENERAL USE INFORMATION
VIII.   COMMAND LINE ARGUMENTS
IX.     QUICK EXAMPLES
X.      SUPPORTED DATA TYPES
XI.     PROGRAM OUTPUT
XII.    REPORT A BUG

===================================================

I. LICENSE INFORMATION

MetalS2 is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation.

MetalS2 is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Foobar. If not, see <http://www.gnu.org/licenses/>.

===================================================

II. SYSTEM REQUIREMENTS

This release has been tested on the following environments:
 * System: Linux
 * System type : 64-bit
 * Distribution: Scientific Linux Release 6.3 (Carbon)
 * Processor: Intel(R) Core(TM) i5 CPU 650@ 3.20GHz
 * Installed memory: 3.7 GiB

Note: MetalS2 is computationally expensive and it is recommended that you run the program if you have a fairly powerful machine.

===================================================

III. PREREQUISITES 

Before running the program you will may need to prepare your development environment:

(1) The first step is to install Python if you haven't already. Python is available from the Python project page at http://www.python.org/. Click on the link corresponding to your platform, and follow the instructions described there.
MetalS2 has been tested on Python 2.6, but it should work also on later versions.

(2) The second step is to get and install NumPy and SciPy packages. The release facility is accessed through the project page, http://numpy.scipy.org/.

===================================================

IV. INSTALLATON INSTRACTIONS

The package comes in the form of Python source code. You can extract it anywhere and run.

===================================================

V. DISTRIBUTION STRUCTURE

Packages distributions have the following directory structure:

Packages_directory/
  p3d/		     Python module for structural bioinformatics
  MetalS2/           MetalS2 library modules
  MetalS2.py         Python script to be excecuted for alignment
  ReadMe.txt         The file you're reading now
  License.txt	     The terms and conditions for use, reproduction, and distribution of source code

All names of files and directories are as given above, except packages_directory which is the name of the package distribution directory given by the author. 

===================================================

VI. FEATURES AND FUNCTIONALITY

Available features are:

(1) Pairwise structural alignment of metal-binding sites, if sites structures are supplied as an input.

(2) Pairwise structural alignment of metal-binding sites from PDB files. It is expected that extraction and saving of metal-binding sites according to the definition, will be done to to perform alignment. MetalS2 produces structural alignments between all metal-binding sites in the PDB, if multiple sites are present and metal option unspecified.

(3) The user can specify a metal-binding site denoted by a metal determining structure of the site. It is expected that multiple sites are present in an input PDB and a number given along with the metal option coincides with a sequence number of the metal of interest.  

(4) MetalS2 provides a structure-based sequence alignment. Ligands and equivalent residues are highlighted.

(5) A visualisation script is produced along with aligned structures. Running in PyMOL the script allows uploding structures and representing them in intelligible way.

To get more information on output data format and content go to the PROGRAM OUTPUT section.

===================================================

VII. GENERAL USE INFORMATION

The interface is command driven. The program should be run from the Linux console and does not provide the graphical user interface.

Launch the following command:
pyhton MetalS2.py [input parameter] <file1> [input parameter] <file2> [input options] <output directory>

===================================================

VIII. COMMAND LINE ARGUMENTS

The following valid options may be specified anywhere on the command line:

  --qp | --tp | --qs | --ts <file>
  (*required*) Specifies the type of input files. 

  --qp <PDB file with query structure>         
  --tp <PDB file with target structure>
  --qs <file with query structure of metal-binding site>
  --ts <file with target structure of metal-binding site>

You can customize your alignment query by setting the following parameters:

  --qm | --tm <number>
  (optional) Specifies a metal-binding site of interest. The option is to be mandatory followed by a number and may be set for both PDB files.
  <number> Sequence number of metal atom trapping metal-binding site structure.
   
  -d <number>
  (optional) Sets the distance cutoff value, in Angstroms, that allows controlling the upper bound of area where atoms may be coupled.
  <number> Cutoff value can be any non-negative floating point number. The default value is 5.0 Angstroms. A value of 0 prevents the program from running at all.

  <output directory>
  (optional) Name or path to a directory where program output will be stored.
  If output directory is omitted the output will be stored in a current directory.

  -h | --help
  (flag) Prints help information.

  -u | --usage
  (flag) Print usage summary.
 
===================================================

IX. QUICK EXAMPLES

The following examples each list two or three command options that you can use to perform specific operations. Enter only one command.

To perform an alignment of two sites, use the following command:
   $ python MetalS2.py --qs qurey-site-name --ts target-site-name output-directory-name 

To align sites from two PDB structures, run:
   $ python MetalS2.py --qp qurey-pdb-name --tp target-pdb-name output-directory-name

To align two sites from PDB files with known reference metals, run:
   $ python MetalS2.py --qp qurey-pdb-name --qm number --tp target-pdb-name --tm number output-directory-name

To align PDB with site, run:
   $ python MetalS2.py --qp qurey-pdb-name --ts target-site-name output-directory-name

For a full list of MetalS2 arguments, use the --help flag (or -h):
   $ python MetalS2.py --help

===================================================

X. SUPPORTED INPUT DATA TYPES

MetalS2 takes either nucleotide or protein structures stored in recognised PDB or PDB-like format files. It will reformat standard PDB format and translate to the format of metal-binding site files before proceed to alignment.

Each PDB file may include multiple metal-binding sites.

===================================================

XI. PROGRAM OUTPUT

The program generates and stores results under the output direstory organized as followed:
   
   sites/
   score.txt
   sequence.txt

(1) score.txt: a text file with a score value of alignment based on a scoring function. The function incorporates root mean square deviation, relative size of alignment, and takes into account chemical semilarity over the aligned region once two structures have been superimposed.

(2) sequence.txt: a text file with a structure-based sequence alignment written to a text file.
 *Important to note: currently, only residues that are structurally
aligned are presented in the output sequences.

(3) Fitted coordinates of superimposed structures written into files and stored under "sites" directory. You can then feed the output files to a viewer to illustrate site structures.

(4) Script to automate visualization of the alignment stored along with site files. Opened by PyMOL program the script loads two sites, represents structures in the cartoon mode and displaies metal atoms.
 
To use this script execute: 
   $ pymol visualisation.pml

By default results are stored in the same directory where the script run from. You can specify the directory where output goes to with a command-line argument. 

When running a pairwise alignment of a multi-sites structures, it may report multiple threads.

===================================================

XII. REPORT A BUG

If you have feature suggestions, bug reports, questions, and even flattering comments, please contact me: valasatava@cerm.unifi.it

===================================================
