:::::::: sparky2mrb.py ::::::::

Author   : Nicolas Sapay, Ph.D. student at IBCP - France
Contact  : n.sapay@ibcp.fr
Version  : 1.0
Creation : Sept 2004 - last update Jan 2005

SYNOPSIS :
==========
	This Python script is the stand alone version of the BMRB 
submission form SPARKY EXTENSION. It provides methods to
create a BMRB submission form from a SPARKY resonance list (Only 
for amino acids). Methods defined here include :
	- methods to detect possible atom nomenclature mistakes
	- methods to detect redundant assignation in the resonance list
	- methods to detect strong chemical shift Standard Deviation (SD)

	A NMR STAR template file is required to run the extension. The 
template file can be generated on the BMRB web site:
                www.bmrb.wisc.edu/elec_dep/gen_aa.html

	sparky2bmrb will create a BMRB submission form in 6 steps:
	> Step 1 : template file reading
	
	> Step 2 : resonance list reading. The list can be genrerated from 
	  Sparky using the Peak>Resonances> Resonance List menu or the <rl>
	  command. The resonance file have to be in the following format:

   Group  Atom   Nuc    Shift   SDev   Assignments
    S1     CA    13C   58.153  1.000       5
    S1     HA     1H    4.251  0.000       3
     |      |      |     |      |          |  
     |      |      |     |      |          +-- Number of assignments  
     |      |      |     |      +------------- Standard Deviation of the chemical shift  
     |      |      |     +-------------------- Chemical shift  
     |      |      +-------------------------- Type of the nucleus
     |      +--------------------------------- Atom name
     +---------------------------------------- Atom group (in 1 or 3 letter code)

	  In case of redundant assignment, i.e. an atom assigned 2 time with 2
	  different chemical shift values, the user will be prompt to select
	  the correct resonance.

	> Step 3 : Atom name translation in BMRB nomenclature. Wrong atom name
	  are reported in the log file.

	> Step 4 : Atom retrieval and ambiguity assignment. The script try to
	  retrieve atom from the resonance list in the template file and vice
	  versa. Non retrieved atoms are reported in th log file.

	> Step 5 : large SD resonance removal. The removal can be set
	  interactively or automatically using the -[i|a] options. SD
	  threshold can be set unsing the --[H|C|N] options

	> step 6 : Output file creation.

OPTION :
========
   -h|--help              Print usage message

   -i|-a                  Execution mode, i.e. interactive or automatic.
                          Default is automatic, i.e. minimum question 
                          will be ask to the user.

   --[iupac|xplor|ucsf]   Atom nomenclature used in the Sparky chemical shift
                          list. Default is xplor.

   --[H|C|N|O|S|P]        Threshold value used to detect and remove resonace
                          with a large standard-deviation. Default is 0.005 
                          for H nucleus, 0.1 for C nucleus and 0.01 for N 
                          nucleus

   -o|--[output|out]      Name of the output file. If not define, Sparky
                          chemical shift list file name will be used with the 
                          <.bmrb> extension.

   -l|--log               Name of the file where remaining data are written.
                          those data correspond to chemical shifts excluded
                          from the list during the process. Default is 
                          <remaining_data.log>

USAGE :
=======
	sparky2bmrb.py [OPTION]  <BMRB template file>  <Sparky chemical shifts list>

	Example:
	--------
	sparky2bmrb.py --xplor --C=0.2 -o foo.bmrb template.star myshift.shifts

	This will set the atom nomenclature to the XPLOR nomenclature, the SD
	threshold of 13C nucleus to 0.2 ppm. The BMRB submission form will be
	<foo.bmrb>.