---------------------------------------------------------------------------
INTRO
---------------------------------------------------------------------------

Version 1.0
Date 21 Aug 2011

Author: Tomasz Puton
E-mail: tomasz.puton@gmail.com

This is sglib, the implementation of the statistical geometry in sequence 
space algorithm (binary and quaternary space) in Python.

It is mainly applied in biology and sequence analysis in the context of
evolution, e.g. for evaluating evolutionary models.

The sglib allows for checking divergence of a given sequence alignment. 
It allows you to check whether your sequences (RNA, DNA, protein)
follow a tree-like pattern of divergence or a bundle-like pattern. This is
the main capability of the library. It is important to perform the test
in order to see whether a tree can be built for a set of sequences (if they
follow bundle-like divergence, building a tree doesn't make sense at all).
It also allows for checking how various positions in an alignment of
many related sequences are randomized, and therefore concluding which are 
constrained in the process of evolution. This can be done by splitting
sequence alignment positions into two separate sequence alignments 
and then measuring the divergence within each group.

A good starting point is the Biophysical Chemistry paper
by Kay Nieselt-Struwe reviewing the statistical geometry in sequence space 
and all its variants:
http://www.ncbi.nlm.nih.gov/pubmed/9362556

The original description of the statistical geometry algorithm in sequence
space can be found in the paper:
http://www.ncbi.nlm.nih.gov/pubmed/3413065

And an example analysis here:
http://www.ncbi.nlm.nih.gov/pubmed/2497522


---------------------------------------------------------------------------
CONTENTS OF THIS DIRECTORY
---------------------------------------------------------------------------

- README - this file
- LICENSE.rtf - GPL v.3 license
- sglib - directory with the statistical geometry implementation
- test_sglib - tests
- example - directory with example files which are referred to in the USAGE
	section 


---------------------------------------------------------------------------
LICENSE
---------------------------------------------------------------------------

The source code, documentation, etc are licensed under the conditions of 
GPL v.3. license.


---------------------------------------------------------------------------
PREREQUISITES
---------------------------------------------------------------------------

The code will run on any platform on which Python has been installed,
including Linux, Mac OS X and MS Windows.

In order to make use of the sglib package you have to have Python 
installed. The code is compatible with any contemporary Python 2.x release.
At the time of writing the implementation, the code was run in Python 2.5, 
but will work flawlessly under 2.6 and 2.7.

The code is *incompatible* with Python 3.x.

You can get Python 2.x from http://www.python.org/.

There are *two dependencies* that have to be installed:
1. PyCogent >= 1.4,  http://sourceforge.net/projects/pycogent/
2. Numpy >= 1.3, http://sourceforge.net/projects/numpy/files/


---------------------------------------------------------------------------
INSTALLATION
---------------------------------------------------------------------------

Before using sglib package you have to set PYTHONPATH variable.

	On Linux / Mac in bash:

		if you don't have PYTHONPATH type:
		export PYTHONPATH=/some/directory/with/stat_geo/

		if you already have it, type:
		export PYTHONPATH=$PYTHONPATH:/some/directory/with/stat_geo/

		You can always edit ~/.bashrc or ~/.profile file and add the 
		export statement there if you want to set the variable at 
		login.

	On Windows:

		go to Start -> Preferences -> System -> Advanced System
		Preferences and set PYTHONPATH there.


---------------------------------------------------------------------------
VALIDATION
---------------------------------------------------------------------------

Go to test_sglib and type:

python test_quartet.py

	The output should be:
	tomek$ ./test_quartet.py 
    ............................................................................
    ----------------------------------------------------------------------
    Ran 76 tests in 0.492s
	
	OK


python test_translator.py
	
	The output should be:
	tomek$ python test_translator.py 
	....
	----------------------------------------------------------------------
	Ran 4 tests in 0.017s

	OK


---------------------------------------------------------------------------
USAGE
---------------------------------------------------------------------------

Using the sglib library:

It is assomed that you are familiar with
- the Python programming language
- and the basic concepts descibed in the papers listed in the INTRO section 
 (esp. what a quartet is).

To summarize: 
We are using sglib to generate all possible quartets for a given 
sequence alignment, and average values of their parameters.

The following kind of datasets can be used for your calcuation:
I)  1 sequence alignment (all sequences in each quartet come from the same
	sequence alignment)
II) 4 sequence alignments (every sequence in each quartet comes from a different
	sequence alignment)

The procedure of using the library is:

1) Translate your sequence alignment(s) to binary/quaternary aligment(s).

2) Create a Python object representing an average quartet - 
	you can do this by instantiating either 
	AverageBinaryQuartet or AverageQuaternaryQuartet.

3) Generate all the possible quartets for a given translation
   and update AverageBinaryQuartet or AverageQuaternaryQuartet
   using the parameters	calculated for each quartet.

4) Get the average parameters.

5) Check whether your sequences:
- follow a tree-like divergence
- follow a bundle-like divergence
- are completly randomized.

Take a look at the two Python scripts in the examples/ directory, to see the Python
implementation of the above procedure:

	- workflow_one_set.py -> using 1 sequence alignment
	- workflow_four_sets.py -> using 4 sequence alignments
	
The output of workflow_four_sets.py contains the average geometry parameters as well.

---------------------------------------------------------------------------
CREDITS
---------------------------------------------------------------------------

Sandra Smit
Kristian Rother
Anthon Feensta
Jaap Heringa
Janusz M. Bujnicki


---------------------------------------------------------------------------
FUNDING
---------------------------------------------------------------------------

This research would not have been possible without the support from EMBO 
(European Molecular Biologly Organization) to Tomasz Puton, who was awarded
with the short-term fellowship (ASTF 274-2008) in order to conduct the research
in IBIVU - http://www.ibi.vu.nl/ during which the Python implementation was
created.


