NPK: ProcessDosy.py Wed Oct 14 15:25:36 2009
    This module contains all the routines needed to process DOSY spectra
    
    The following functions realize a set of operations, needed for DOSY processing,
    It is based on an implementation of the Inverse Fourier Transform, by Maximum Entropy
    
    Processing are divided in pre - Transform - Post phases.
    For instance a typical DOSY procesing, would be

    pre_2d()
    pre_ft_2df2()
    ft_2df2()
    post_ft_2df2()
    pre_ilt_2df1()
    ilt_2df1()
    post_ilt_2df1()
    post_2d()

    but other combinations are possible.

    Most functions take the following arguments :
    arguments :
    audit
        the opened audit file, if empty or set to none, audit will go to the stdout
    filein      the file name of the input file, 
        will be loaded before operation, if name is "memory", then processing takes place on the current 2D kernel buffer
    fileout     the file name of the input file, can be "memory"
        will be written after operation, if name is "memory", then processing results is left in 2D kernel buffer
    p_in        the dictionary containing all the processing parameters
        most entries are optionnal as entries are protected with try / except
    f_in        the dictionary containing all the details on the spectrum "filein"
    f_out       details on the spectrum "fileout" will be put in this dictionary
    location    the directory where the output files will be written
 
PreDosy2D(audit,p_in_arg,f_in,f_out,inputfilename,outputfilename)
        
    prepare a 2D for processing of a 2D DOSY experiment

    ends with a half processed file
    uses  :
        pre_2d()        ( from Process2D )
        pre_ft_2df2()   ( from Process2D )
        ft_2df2()       ( from Process2D )
        post_ft_2df2()  ( from Process2D )
        pre_dosy()

 
PreDosy3D(audit,p_in_arg,f_in,f_out,inputfilename,outputfilename)
        
    prepare a 3D for processing of a 3D DOSY experiment

    experiment should be organized as a decaying series along F1 of regular 2D along F2-F3.
    ends with a half processed file
    uses  :
        process3DF2F3()        ( from Process3D )
        pre_dosy()

 
Dosy2D(audit,p_in_arg,f_in,f_out,inputfilename,outputfilename)
        
    processing of a 2D DOSY experiment

    starts with a half processed file

 
Dosy3D(audit,p_in_arg,f_in,f_out,inputfilename,outputfilename)
        
    processing of a small 3D DOSY experiment
    larger DOSY3D should be processed with Process3D.DOSY3D()
    
    starts with a half processed file

 
pre_dosy(audit, filein, fileout, p_in, f_in, f_out)
        
This macro is simply a wrapper around proc_2d() to realise a f2 baseline correction at the end of the PreDosy2D processing
This is somewhat ad-hoc, and may be changed sometimes

it implements
- f2_baseline   : baseline correction
- select_state  : enforce the final state of the data

Input Domain in F2:   frequency
Output Domain in F2:   frequency

Author:   Marc-Andre Delsuc
Version:   6.0
Actions

    baseline correction
    baseline correction of the hald-processed DOSY spectrum

  • f2_baseline:   boolean / default 1


  • f2_bcorr_algo:   enum offset linear spline / default linear

    • offset : removes a automatically determined offset
    linear - spline : uses the list of user determined pivot points to define the baseline,
    : fit with a straight line or a spline
    %action% change other post_2d() default actions

  • autophase_2d:   boolean / default 0


  • f1_baseline:   boolean / default 0


  • projection:   boolean / default 0

    select_state
    permit to choose the state complex / real of the output file
    complex data are changed to real by dropping the imaginary part
    real data are changed to complex by computing the Hilbert transform with tocomplex()
    this is usually not required as all processing commands prepare the state themselves

  • select_state:   boolean / default 1

    • actuallly does the selection

  • f1_state:   enum ignore complex real / default ignore

    • force the f1 axis to real or complex. ignore will let the axis unchanged

  • f2_state:   enum ignore complex real / default real

    • force the f2 axis to real or complex. ignore will let the axis unchanged

 
pre_ilt_2df1( audit, filein, fileout, p_in, f_in, f_out )
        
This macro realizes the pre operation on each F1 decay of the 2D

it implements data massaging before ILT:
- ilt_set-up
    dosy_q2 dosy_tab tosy_q2 tosy_tab
- load tabulated file
    file name
- calibration
- F1 noise evaluation
- wrong points filtering

Input Domain in F1:   tabulated
Output Domain in F1:   tabulated
Dimensionality:   2

Author:   Marc-Andre Delsuc
Version:   6.0
Actions

    ilt_set-up
    determines the kind of analysis to perform

  • ilt_type:   enum dosy tosy / default dosy


  • sampling_type:   enum regular tabulated / default regular


  • sampling_tab_file:   file_name

    • sampling_type == tabulated implies sampling_tab_file

    ilt_tosy_calibration
    Calibrate ilt axis on physical parameters for Tosy

  • ilt_tosy_unit:   enum usec msec sec / default sec

    • value of the Laplace axis unity

    ilt_dosy_calibration
    Calibrate ilt axis on physical parameters for Dosy

  • dosy_big_delta:   float

    • "Big Delta" : diffusion delay in msec

  • dosy_little_delta:   float

    • "little Delta" : gradient duration in msec

  • dosy_seq_typ:   enum pgse ste bpp_ste ste_2echoes bpp_ste_2echoes oneshot / default ste

    • the type of DOSY sequence used

  • dosy_nucleus:   enum 1H 2H 13C 15N 17O 19F 31P / default 1H

    • the observed nucleus

  • recovery_gradient_delay:   float / default 0.0


  • conditions:   (recovery_gradient_delay >= 0 )

    • Gradient recovery delay

  • max_grad:   float nonnegative / default 50.0

    • Maximum Amplificator Gradient Intensity, in G/cm

  • conditions:   (max_grad > 0 )


  • max_tab:   float / default 100.0

    • Maximum Tabulated Gradient Value in the tabulated file.
    Bruker users use 100 here
    Varian users use 32768 here

  • conditions:   (max_tab > 0 )


  • gradient_shape:   float / default 1.0

    • integral factor depending on the gradient shape used
    typical values are :
    1.0 for rectangular gradients
    0.6366 = 2/pi for sine bell gradients
    0.4839496 for 4% truncated gaussian (Bruker gauss.100 file)

  • conditions:   [ (gradient_shape > 0.0 ) and (gradient_shape <= 1.0 )]

    f1_noise
    evaluate noise, estimated by finding an empty zone on a given 1D spectrum

  • f1_noise:   boolean / default 1


  • f1_noise_n:   integer / default 30

    • number of different zones where noise is evaluated

  • f1_noise_row:   integer / default get_si1_2d()

    • the index of the row on which the noise is evaluated

  • f1_noise_weight:   float / default 1.0

    • the noise used during the MaxEnt iteration is weigthed with this scalar,
    this permits to compensate for over- or under-estimate of the noise level

  • conditions:   [ noise_weight > 0.0 ]


  • returned value:   noise_in_f1_domain

    f1_ignore_point
    enter the list of the point to ignore along the (gradient) axis

  • f1_ignore_point:   boolean / default 0


  • f1_ignore_point_list:   (list of integer) / default ()

    • list of points to ignore

 
ilt_2df1( audit, filein_arg, fileout, p_in, f_in, f_out)
        
This macro realizes the ILT operation on the F1 decay of the 2D

it implements the spectral analysis step :


- damp_width        dmin dmax
- minimum S/N
- col_selection
- me_preset
- me_details
    size
    iteration
    ndisp
    lambcont
    lambsp
    miniter
- ILT
- reverse           : reverses laplace axis


Input Domain in F1:   tabulated
Output Domain in F1:   damping
Dimensionality:   2

Author:   Marc-Andre Delsuc
Version:   6.0
Actions

    damp_width
    sets-up the border for the laplace spectrum

  • damp_width:   enum diff_standard from_tab defined / default diff_standard

    • defines how the window will be defined
    diff_standard is the set-up for a standard solution : 10-5000 um^2 sec-1
    from_tab : the borders are computed from the tabulated values
    defined : the values

  • dmin:   float > 0 / default 10


  • dmax:   float > 0 / default 5000


  • conditions:   [ dmin < dmax ]

    minimum_sn
    defines the minimum Signal/Noise ratio required for ILT processing
    No data will ever be processed if the S/N is below this value, independently of the col_selection set-up
    It is considered unsafe to go below 10 for this parameter.

  • minimum_sn:   float / default 32.0

    col_selection
    set-up the conditions for selecting the column to be processed by ILT for DOSY

  • col_selection:   boolean / default 0


  • col_selection_mode:   enum valthreshold zone list none / default none

    • none : no selection (only minimum_sn stands)
    valthreshold : absolute value theshold, will not be used if below minimum_sn
    zone : only points within that spectral zone will be considered
    list : explicit list of the columns to consider


  • col_valthreshold:   float



  • col_list:   (integer list)

    • list og the columns to consider, given in index (real part only)


  • col_selection_left:   float / default 10.0

    • the left border of the selection zone, in unit

  • col_selection_left_unit:   enum ppm hz index / default ppm

    • the unit in which selection_left is given

  • col_selection_right:   float / default 0.0

    • the right border of the selection zone, in unit

  • col_selection_right_unit:   enum ppm hz index / default ppm

    • the unit in which selection_right is given

  • conditions:   (col_selection_left{index} < col_selection_right{index})


  • returned value:   col_selection_left

    • the left coordinate of the selection zone in index

  • returned value:   col_selection_right

    • the right coordinate of the selection zone in index

    me_preset
    presets the MaxEnt parameters to default values

  • me_preset_value:   enum 0 1 2 3 4 5 / default 3

    • sets the parameter for a balance between speed (1) and quality (5), 0 is for fit

    me_details
    if this flag is on, default parameters can be set.

  • me_details:   boolean / default 0


  • me_size:   integer


  • me_iteration:   integer


  • me_int_iteration:   


  • me_ncheck:   integer


  • me_lambda_control:   integer


  • me_lambda_speed:   


  • me_algo:   enum Fit MaxEnt

    dump_preset
    dump all the parameters to a gtb file
    usually used to check the parameter or to prepare for a parallel run

  • dump_preset:   boolean / default 0


  • dump_preset_file:   file / default dosy_preset.gtb

    ILT
    perform the ILT computation itself

  • execute_ilt:   boolean / default 1

    f1_reverse

  • f1_reverse:   boolean / default 0

 
post_ilt_2df1( audit, filein, fileout, p_in, f_in, f_out )
        
This macro realizes the post F1-ILT operation on a 2D spectrum

- smoothing     : F2 smoothing of DOSY

Input Domain in F2:   time
Output Domain in F2:   time
Dimensionality:   2

Author:   Marc-Andre Delsuc
Version:   6.0