Processing of NMR data-sets

NPK - the python front end for processing NMR data-sets
=======================================================

USAGE
    i)    interactive mode
        NPK
                to start an interact session
    or
    ii)   script execution
        NPK -e script.py
                to execute in NPK the script : script.py
    or
    iii)  NPK help
                to show this documentation
    or
    iv)   inline commande
        NPK action input_datafile output_datafile { processing_parameterfile } { additional parameters }
        where
            action is the processing to apply
            input_datafile and output_datafile are gifa binary files
            processing_parameterfile contains all the needed parameters for the processing
                is optionnal, if omited, default values will be systematically used
                however, must be present (even empty) if additional parameters are to be used.

    All python commands, as well as NPK commands are available in the four types of usage.

    Note :
    i) a regular python 2.1 console, type ^D to exit (^Z in Windows)

    ii) a regular python 2.1 interpretor

    iv) is the standard way of invoking NMR processing



IN-LINE COMMAND mode:
====================

NPK action input_datafile output_datafile { processing_parameterfile } { additional parameters }

ACTION
    possible actions are :
        FT1D         - perfoms 1D Fourier Analysis
                       see details in Process1D documentation
        MaxEnt1D     - perfoms 1D Maximum Entropy Analysis
                       see details in Process1D documentation
        FT2D         - perfoms 2D Fourier Analysis
                       see details in Process2D documentation
        MaxEnt2D     - perfoms 2D Maximum Entropy Analysis
                       see details in Process2D documentation
        PreDOSY2D    - prepares for DOSY analysis
                       see details in Process2D documentation
        DOSY2D       - performs a DOSY analysis
                       see details in ProcessDosy documentation
        PDOSY2D      - same as DOSY2D; but will start a parrallel process instead
                       see details in batch_dosy documentation
        FT3D         - perfoms 2D Fourier Analysis
                       see details in Process3D documentation
        ImportBruker - Import from Bruker XWinNMR/TopSpin format, a file or a set of files
        ImportVarian - Import from Varian VNMR format, a file or a set of files
        CHECK        - no action, permits to chek syntax
        help         - this help file

NMR BINARY FILES
    NPK reads only Gifa files.
    These files are read and created by the various versions of the Gifa program
        Gifa v4, see https://bioserv.cbs.cnrs.fr
    and Gifa v5, see http://www.NMRtec.com
    The programm NMRNoteBook, developped by NMRtec is also able to export and import Gifa files
    
    File extensions :
    Back in Gifa v4 time, no extension was used to specify the NMR Gifa binary files.
    With Gifa V5 a new convention has been set-up for the file extensions :
            time domain     freq domain
    1D          .gf1            .gs1
    2D          .gf2            .gs2
    3D          .gf3            .gs3
    These extensions are now enforced by NPK
    It should be noted that no provision is made to specify a file in an intermediate state (processed in F2 but not in F1)
    it is up to you name these files depending on what you want to do with them afterwards.

    If you want to import NMR binary files from you spectrometer, you can
    - either use one of the Gifa v4 importers found on the WEB site (the util sub directory)
    - use the provided python importers : ImportBruker, ImportVarian
    - use any other importer

PARAMETER FILES

    The NMR processing is controled by parameters described in the respective documentation.
    Each and every parameter has a default value which is not too silly, so usually, giving no parameter may give you some result.
    However, you will have to modify the processing results by changing these parameters.

    Parameters are given either through a parameter file, or by inline commands.
    parameter files have the .gtb extention
    parameter files contains parameters in the form of a property list :

        #some comment
        param1=value string
        param2=value string    ... etc ...

    Addtional parameters can be given to the processing, independently to the parameter file
    by directly giving the parameter on the calling line, in the form additionnal_param=value
    
    WINDOWS users:  = is used as a separator in windows, so you will have to type "additionnal_param=value"
    
    additional parameterfiles are also associated to the binary data files
        input_datafile.gtb
            should be present near the input_datafile
            and contains details on the data not found in the binary gifa file format.
        output_datafile.gtb
            is created by the processing and contains processing details

EXAMPLES
========
    NPK FT1D input.gf1 output.gs1 

        launch the processing of a 1D FID, called input.gf1, and create the file output.gs1
        if the file is present, it is used as the processing parameter file, otherwise default parameters are used

    NPK FT2D input.gf2 output.gs2 processing.gtb

        launch the processing of a 2D experiment, called input.gf2, and create the 2D spectrum output.gs2
        the file processing.gtb is used as the processing parameter file.
        Note that this file may be empty.

    NPK DOSY2D Post_F2.gs2 DOSY.gs2 processing.gtb audittrail=test1.html  me_details=1  me_size=512

        launch the processing of a DOSY, on a dataset called Post_F2.gs2, and create the 2D DOSY spectrum DOSY.gs2
        the file processing.gtb is used as the processing parameter file.
        additionnal parameters are used :
            audittrail=test1.html overwrite the default audittrail file name
            me_details=1  me_size=512   overwrite the size of the Inverse Laplace processing defined in the processing.gtb file

STARTING NPK  & POSSIBLE ERRORS
    NPK requires a certain number of environment files to be present.
    $JAVA and $NPK_HOME are defined in the NPK shell script.

    The following sequence of event takes place when you start NPK 
    - a java virtual machine (JVM) must be available (found in $JAVA)
    - the jython code is launched in the JVM (found in $NPK_HOME/Java)
    - additional jython libraries are loaded (found in $NPK_HOME/python/Lib)
    - NPK code is initialized
        - loading the binary libraries (found in $NPK_HOME/Java)
        - loading and compiling the NPK python library (found in $NPK_HOME/python/NPK)
    - command line is parsed and processing starts ( found in $NPK_HOME/python/NPK/Launch.py )
    
See also:
    some additional code is provided in the Console code which is loaded when entering the interactive mode :
    
    - status()     : displays the internal state of the Kernel
    - import Graph : opens a minimum graphic interface to the 1D buffer (resize to redraw)

    print a summary of the internal state of the kernel

    
    inputfilename can be either a file (fid or ser) or a directory

    
    inputfilename can be either a file (fid) or a directory

    calls the routine to realise a processing in parrallel
    phase : additional parameter LAUNCH / FINAL

            if (action == "FT1D"):
                FT1D(audit,p_in,f_in,f_out,inputfilename,outputfilename)
            elif (action == "MaxEnt1D"):
                MaxEnt1D(audit,p_in,f_in,f_out,inputfilename,outputfilename)
            elif (action == "FT2D"):
                FT2D(audit,p_in,f_in,f_out,inputfilename,outputfilename)
            elif (action == "MaxEnt1D"):
                print "Sorry, MaxEnt1D Not Fully implemented yet"
            elif (action == "MaxEnt2D"):
                MaxEnt2D(audit,p_in,f_in,f_out,inputfilename,outputfilename)
            elif (action == "PreDOSY2D"):
                PreDosy2D(audit,p_in,f_in,f_out,inputfilename,outputfilename)
            elif (action == "DOSY2D"):
                Dosy2D(audit,p_in,f_in,f_out,inputfilename,outputfilename)
            elif (action == "PDOSY2D"):
                PDOSY2D("LAUNCH",audit,inputfilename,outputfilename)
            elif (action == "PDOSYCollect"):
                PDOSY2D("FINAL",audit,inputfilename,outputfilename)
            elif (action == "ImportBruker"):
                ImportBruker(audit,inputfilename,outputfilename)
            elif (action == "ImportVarian"):
                ImportVarian(audit,inputfilename,outputfilename)
            elif (action == "FT3D"):
                FT3D(audit,p_in,f_in,f_out,inputfilename,outputfilename)
            elif (action == "CHECK" or action == "check" ):
                print "CHECK command"
                print ("action: %s  input: %s  output: %s  param: %s"%(action,inputfilename,outputfilename,paramfilename))
                sys.exit()
                
            else:
                print "Action -" + action + "- unknown\n"
                print "Possible actions : help CHECK FT1D FT2D FT3D PreDOSY2D DOSY2D PDOSY2D MaxEnt1D MaxEnt2D ImportBruker ImportVarian\n"

def auditname(filename,action):