spike.plugins.NMR package — spike 0.99.23 documentation

# spike.plugins.NMR package

## Submodules

## spike.plugins.NMR.Bruker_NMR_FT module

This plugin implement the set of Fourier Transform used for NMR

and some other related utilities commands starting with bk_ emulates (kind of) the topspin commands

MAD September 2015

class `spike.plugins.NMR.Bruker_NMR_FT.` `Bruker_NMR_FT`(methodName='runTest')

  Bases: `unittest.case.TestCase`

  `test_1D`()

    Test mostly syntax

  `test_2D`()

    Test mostly syntax

`spike.plugins.NMR.Bruker_NMR_FT.` `bruker_corr`(self)

  applies a correction on the spectrum for the time offset in the FID. time offset is stored in the axis property zerotime

`spike.plugins.NMR.Bruker_NMR_FT.` `bruker_proc_phase`(self, correct_zerotime=True)

  applies a phase correction on the spectrum from proc file parameters. correct_zerotime == True (default) the zerotime correct ( bruker_corr ) is also applied

`spike.plugins.NMR.Bruker_NMR_FT.` `check_cpx`(data, axis)

`spike.plugins.NMR.Bruker_NMR_FT.` `check_real`(data, axis)

`spike.plugins.NMR.Bruker_NMR_FT.` `conv_n_p`(self)

  realises the n+p to SH conversion

`spike.plugins.NMR.Bruker_NMR_FT.` `ftF1`(data)

  emulates Bruker ft of a 2D in F1 depending on FnMode

  None 0 QF 1 QSEQ 2 TPPI 3 States 4 States-TPPI 5 Echo-AntiEcho 6

`spike.plugins.NMR.Bruker_NMR_FT.` `ftF2`(data)

  emulates Bruker ft of a 2D in F1 depending on FnMode

`spike.plugins.NMR.Bruker_NMR_FT.` `ft_n_p`(data, axis='F1')

  F1-Fourier transform for N+P (echo/antiecho) 2D

`spike.plugins.NMR.Bruker_NMR_FT.` `ft_phase_modu`(data, axis='F1')

  F1-Fourier transform for phase-modulated 2D

`spike.plugins.NMR.Bruker_NMR_FT.` `ft_seq`(data)

  performs the fourier transform of a data-set acquired on a Bruker in simultaneous mode Processing is performed only along the F2 (F3) axis if in 2D (3D)

  (Bruker QSEQ mode)

`spike.plugins.NMR.Bruker_NMR_FT.` `ft_sh`(data, axis='F1')

  States-Haberkorn F1 Fourier transform

`spike.plugins.NMR.Bruker_NMR_FT.` `ft_sh_tppi`(data, axis='F1')

  States-Haberkorn / TPPI F1 Fourier Transform

`spike.plugins.NMR.Bruker_NMR_FT.` `ft_sim`(data)

  performs the fourier transform of a data-set acquired on a Bruker in simultaneous mode Processing is performed only along the F2 (F3) axis if in 2D (3D)

  (Bruker QSIM mode)

`spike.plugins.NMR.Bruker_NMR_FT.` `ft_tppi`(data, axis='F1')

  TPPI F1 Fourier transform

`spike.plugins.NMR.Bruker_NMR_FT.` `rem_dsp`(self, coeff=1.0)

  remove the leading part of the fid created by the DSP coeff allows to extend or reduce the zone, 1.0 is exactly the zone see zero_dsp

`spike.plugins.NMR.Bruker_NMR_FT.` `wdw`(data, axis=1)

  emulates Bruker window function

`spike.plugins.NMR.Bruker_NMR_FT.` `xf1`(data)

  emulates xf1 command from topspin

`spike.plugins.NMR.Bruker_NMR_FT.` `xf2`(data)

  emulates xf2 command from topspin

`spike.plugins.NMR.Bruker_NMR_FT.` `xfb`(data)

  emulates xfb command from topspin

`spike.plugins.NMR.Bruker_NMR_FT.` `zero_dsp`(self, coeff=1.0)

  set to 0.0 the leading part of the fid created by the DSP coeff allows to extend or reduce the zone, 1.0 is exactly the zone a value slightly larger than 1.0 can remove some strong baseline problems. see rem_dsp

## spike.plugins.NMR.Bucketing module

A set of tools for computing bucketing for 1D and 2D NMR spectra

First version by DELSUC Marc-André on 2015-09-06. extended in 2017

This plugin implements the bucketing routines developped in the work

Automatic differential analysis of NMR experiments in complex samples Laure Margueritte, Petar Markov, Lionel Chiron, Jean-Philippe Starck, Catherine Vonthron-Sénécheau, Mélanie Bourjot, and Marc-André Delsuc Magn. Reson. Chem., (2018) 80 (5), 1387. http://doi.org/10.1002/mrc.4683

It implements 1D and 2D bucketing each bucket has a constant progammable size in ppm, for each buckets, following properties are computes:

> center, normalized area, max, min, standard deviation, bucket_size

The results are printed in cvs format either on screen or into a file

class `spike.plugins.NMR.Bucketing.` `BucketingTests`(methodName='runTest')

  Bases: `unittest.case.TestCase`

  `announce`()
  `setUp`()

    Hook method for setting up the test fixture before exercising it.

`spike.plugins.NMR.Bucketing.` `bucket1d`(data, zoom=0.5, 9.5, bsize=0.04, pp=False, sk=False, thresh=10, file=None)

  This tool permits to realize a bucket integration from the current 1D data-set. You will have to give (all spectral values are in ppm)

  > - zoom (low,high), : the starting and ending ppm of the integration zone in the spectrum

  > - bsize: the size of the bucket

  > - pp: if True, the number of peaks in the bucket is also added

  >     - peaks are detected if intensity is larger that thresh*noise

  > - sk: if True, skewness and kurtosis computed for each bucket

  > - file: the filename to which the result is written

  For a better bucket integration, you should be careful that :

    - the bucket size is not too small, size is better than number !

    - the baseline correction has been carefully done

    - the spectral window is correctly determined to encompass the meaningfull spectral zone.

`spike.plugins.NMR.Bucketing.` `bucket2d`(data, zoom=0.5, 9.5, 0.5, 9.5, bsize=0.1, 0.1, pp=False, sk=False, thresh=10, file=None)

  This tool permits to realize a bucket integration from the current 2D data-set. You will have to give the following values: (all spectral values are in ppm)

  > - zoom (F1limits, F2limits), : the starting and ending ppm of the integration zone in the spectrum

  > - bsize (F1,F2): the sizes of the bucket

  > - pp: if True, the number of peaks in the bucket is also added

  >     - peaks are detected if intensity is larger that thresh*noise

  > - sk: if True, skewness and kurtosis computed for each bucket

  > - file: the filename to which the result is written

  For a better bucket integration, you should be careful that :

    - the bucket size is not too small, size is better than number !

    - the baseline correction has been carefully done

    - the spectral window is correctly determined to encompass the meaningfull spectral zone.

## spike.plugins.NMR.Integrate module

A set of tools for computing Integrals for 1D NMR spectra

If present, it can guess integral zones from an existing peak-list Adds .integrals into NPKDataset which is an object with its own methods.

First version by DELSUC Marc-André on May-2019.

class `spike.plugins.NMR.Integrate.` `Integralitem`(start, end, curve, value)

  Bases: `object`

  `update`(data, bias, calibration=1)

    given a dataset and a constant bias, recompute the curve and the value

class `spike.plugins.NMR.Integrate.` `Integrals`(data, *args, autothresh=10.0, calibration=None, bias=0.0, separation=3, wings=5, compute=True, **kwds)

  Bases: `list`

  the class to hold a list of Integral

  an item is [start, end, curve as np.array(), value] start and end are in index !

  `calibrate`(calibration=None)

    computes integration values from curves either use calibration value as a scale, if calibration is None put the largest to 100.0

  `display`(integoff=0.3, integscale=0.5, color='red', label=False, labelxposition=1, labelyposition=None, regions=False, zoom=None, figure=None, curvedict=None, labeldict=None)

    displays integrals

    figure mpl axes to draw on - will create one if None zoom zoom

    integoff offset of drawing 0..1 integscale scale of the largest integral color color regions highlight regions curvedict additional parameters for the drawing label draw integral values labelxposition position of label in x 0..1 with respect to the integral drawing labelyposition position of label in y 0..1 with respect to the screen - None means top of integral labeldict additional parameters for the labels

  `do_compute`()

    realize the computation, using internal parameters

  property `integvalues`

    the list of calibrated values

  property `integzones`

    the list of (start, end) of integral zones

  `peakstozones`()

    computes integrals zones from peak list, separation : if two peaks are less than separation x width n they are aggregated, default = 3 wings : integrals sides are extended by wings x width, default = 5

  `recalibrate`(entry, calib_value)

    on a dataset already integrated, the integrals are adapted so that the given entry is set to the given value.

  `report`()
  `to_pandas`()

    export extract of current integrals list to pandas Dataframe

  `zonestocurves`()

    from integral lists, computes curves and values

`spike.plugins.NMR.Integrate.` `calibrate`(npkd, entry, calib_value)

  on a dataset already integrated, the integrals are adapted so that the given entry is set to the given value.

`spike.plugins.NMR.Integrate.` `display`(npkd, integoff=0.3, integscale=0.5, color='red', label=False, labelxposition=1, labelyposition=None, regions=False, zoom=None, figure=None, curvedict=None, labeldict=None)

  displays integrals

  figure mpl axes to draw on - will create one if None zoom zoom

  integoff offset of drawing 0..1 integscale scale of the largest integral color color regions highlight regions curvedict additional parameters for the drawing label draw integral values labelxposition position of label in x 0..1 with respect to the integral drawing labelyposition position of label in y 0..1 with respect to the screen - None means top of integral labeldict additional parameters for the labels

`spike.plugins.NMR.Integrate.` `integrate`(npkd, **kw)

  computes integral zones and values from peak list,

  separation : if two peaks are less than separation x width n they are aggregated, default = 3 wings : integrals sides are extended by wings x width, default = 5 bias: this value is substracted to data before integration calibration: a coefficient to multiply all integrals / if None (default) largest is set at 100

## spike.plugins.NMR.PALMA module

complete DOSY processing, using the PALMA algorithm

This program uses the PALMA algorithm, presented in the manuscript

Cherni, A., Chouzenoux, E., & Delsuc, M.-A. (2017). PALMA, an improved algorithm for DOSY signal processing. Analyst, 142(5), 772–779. http://doi.org/10.1039/c6an01902a

see manuscript for details.

Authors: Afef Cherni, Emilie Chouzenoux, and Marc-André Delsuc

Licence: CC-BY-NC-SA https://creativecommons.org/licenses/by-nc-sa/4.0/

`spike.plugins.NMR.PALMA.` `Import_DOSY`(fname, nucleus=None, verbose=False)

  Import and calibrate DOSY data-set from a Bruker ser file

`spike.plugins.NMR.PALMA.` `Import_DOSY_proc`(fname, nucleus='1H', verbose=False)

  Import and calibrate DOSY data-set from a Bruker 2rr file

`spike.plugins.NMR.PALMA.` `L1`(x)

  computes L1 norm of x

`spike.plugins.NMR.PALMA.` `PPXAplus`(K, Binv, y, eta, nbiter=1000, lamda=0.1, prec=1e-12, full_output=False)

  performs the PPXA+ algorithm K : a MxN matrix which transform from data space to image space Binv : inverse of (Id + K.t K) y : a M vector containing the data a : an estimate of $sum{x}$ where x is final image - used as a bayesian prior of x eta : an estimate of the standard deviation of the noise in y nbiter : maximum number of iteration to do lamda: is in [0..1], the weigth of l1 vs MaxEnt regularisation

  > lamda = 0 is full L1 lamda = 1 is full MaxEnt

  prec: precision of the result, algo will stop if steps are below this evel full_output: if True, will compute additional terms during convergence (slower):

  > parameters = (lcrit, lent, lL1, lresidus)

  >   with lcrit: the optimized criterion len: evolution of -entropy lL1: evolution of L1(x) lresidus: evolution of the distance ||Kx-y||

  > if False, returns the number of performed iterations

  returns (x, parameters), where x is the computed optimal image

`spike.plugins.NMR.PALMA.` `approx_lambert`(x)

  approximation of W( exp(x) ) no error below 50, and less than 0.2% error for x>50 and converges toward 0 for x->inf does not overflow ! does not NaN

`spike.plugins.NMR.PALMA.` `auto_damp_width`(d)

  uses the tab buffer to determine the optimum dmin and dmax for ILT processing

`spike.plugins.NMR.PALMA.` `calibdosy`(litdelta, bigdelta, recovery=0.0, seq_type='ste', nucleus='1H', maxgrad=50.0, maxtab=50.0, gradshape=1.0, unbalancing=0.2, os_tau=None, os_version=1)

  returns the DOSY calibrating factor from the parameters

  > > bigdelta float

  > >   “Big Delta” : diffusion delay in msec

  > > litdelta float

  > >   “little Delta” : gradient duration in msec

  > > seq_type enum “pgse”,”ste”,”bpp_ste”,”ste_2echoes”,”bpp_ste_2echoes”,”oneshot” / default ste
  > >   the type of DOSY sequence used

  > >     pgse : the standard hahn echoe sequence ste : the standard stimulated echoe sequence bpp_ste : ste with bipolar gradient pulses ste_2echoes : ste compensated for convection bpp_ste_2echoes : bpp_ste compensated for convection oneshot : the oneshot sequence from Pelta, Morris, Stchedroff, Hammond, 2002, Magn.Reson.Chem. 40, p147

  > >     > uses unbalancing=0.2, os_tau=None, os_version=1 unbalancing is called alpha in the publication os_tau is called tau in the publication os_version=1 corresponds to equation(1) / os_version=2 to (2)

  > > nucleus enum “1H”,”2H”,”13C”,”15N”,”17O”,”19F”,”31P” / default 1H

  > >   the observed nucleus

  > recovery float

  >   Gradient recovery delay

  > maxgrad float

  >   Maximum Amplificator Gradient Intensity, in G/cm / default 50.0

  > maxtab float

  >   Maximum Tabulated Gradient Value in the tabulated file. / default 50.0 Bruker users with gradient list in G/cm (difflist) use maxgrad here Bruker users with gradient list in % use 100 here Varian users use 32768 here

  > gradshape float

  >   integral factor depending on the gradient shape used / default 1.0 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)

  >   Bruker users using difflist use 1.0 here, as it is already included in difflist

`spike.plugins.NMR.PALMA.` `criterion`(x, K, y, lamda, a)

  Compute regularization function, (not used during iteration without full_output)

`spike.plugins.NMR.PALMA.` `dcalibdosy`(npk, nucleus='1H')

  use stored parameters to determine correct DOSY calbiration

`spike.plugins.NMR.PALMA.` `determine_seqtype`(pulprog)

  given the PULPROG name, determines which seq_type is to be used PULPROG should be follow the standard Bruker naming scheme

`spike.plugins.NMR.PALMA.` `do_palma`(npkd, miniSNR=32, mppool=None, nbiter=1000, lamda=0.1, uncertainty=1.2, precision=1e-08)

  realize PALMA computation on each column of the 2D datasets dataset should have been prepared with prepare_palma()

  the noise in the initial spectrum is analysed on the first DOSY increment then each column is processed with palma() if its intensity is sufficient

  miniSNR: determines the minimum Signal to Noise Ratio of the signal for allowing the processing mppool: if passed as a multiprocessing.Pool, it will be used for parallel processing

  the other parameters are transparently passed to palma()

`spike.plugins.NMR.PALMA.` `ent`(x, a)

  computes Entropy of x

`spike.plugins.NMR.PALMA.` `eval_dosy_noise`(x, window_size=9, order=3)

  we estimate the noise in x by computing difference from polynomial fitting input: x - a real vector return: the noise level

`spike.plugins.NMR.PALMA.` `lambert_w`(x)

  W Lambert function

`spike.plugins.NMR.PALMA.` `palma`(npkd, N, nbiter=1000, uncertainty=1.0, lamda=0.1, precision=1e-08, full_output=False)

  realize PALMA computation on a 1D dataset containing a decay dataset should have been prepared with prepare_palma on each column, the noise is estimated, then PPXA+ algorithm is applied nbiter: maximum iteration number of the PALMA algo

  uncertainty: noise is estimated on the dataset, and then multiplied by this value

    so uncertainty=1 is full confidence in the noise evaluation algo uncertainty>1 allows more room for algo when data quality is poor

  lamda is the balance between entropy and L1

    lamda = 0 is full L1 lamda = 1 is full Ent

  precision: is the required precision for the convergence full_output is used for debugging purposes, do not use in production

  > check PPXAplus() doc for details

`spike.plugins.NMR.PALMA.` `prepare_palma`(npkd, finalsize, Dmin, Dmax)

  this method prepares a DOSY dataset for processing - computes experimental values from imported parameter file - prepare DOSY transformation matrix

`spike.plugins.NMR.PALMA.` `process`(param)

  do the elemental processing, used by loops

`spike.plugins.NMR.PALMA.` `prox_l1`(x, w)

  Compute proximity operator of L1 norm”

`spike.plugins.NMR.PALMA.` `prox_l1_Sent`(x, lamda, a)

  Compute the proximity operator of L1 + Shannon Entropy

`spike.plugins.NMR.PALMA.` `prox_l2`(x, dx, eta)

  Compute projection of x onto l2 ball ||z-dx||<=eta x and dx are image vectors

`spike.plugins.NMR.PALMA.` `residus`(x, K, y)

  computes distance between y and Kx

`spike.plugins.NMR.PALMA.` `test`(npkd)

## spike.plugins.NMR.apmin module

Autmomatic phase correction for 1D NMR spectra

based on an earlier version from NPK

works by minimizing the negative part of the spectrum WILL NOT WORK on positive/negative spectra (JMOD, W-LOGSY, etc.)

Created by DELSUC Marc-André on 2016-05-23. Copyright (c) 2016 IGBMC. All rights reserved.

`spike.plugins.NMR.apmin.` `apmin`(d, first_order=True, inwater=False, baselinecorr=True, bcpoints=6, apt=False, debug=False)

  automatic 1D phase correction phase by minimizing the negative wing of the 1D spectrum

  first_order = False inhibit optimizing 1st order phase inwater = True does not look to the central zone of the spectrum baselinecorr = True, an advanced baseline correction is applied on the final steps apt = True (Attached proton test) performs the phasing on up-down spectra, such as APT / DEPT 13C spectra.

  performs a grid/simplex search on P0 first then on (P0 P1) the dataset is returned phased and the values are stored in d.axis1.P0 and d.axis1.P1

  P1 is kept to 0 if first_order=False

  note that if baselinecorr is True

    - the algo becomes quite slow !

    - a simple linear baseline correction is always applied anyway anyhow

  adapted from NPK v1 MAD, may 2016

`spike.plugins.NMR.apmin.` `neg_wing`(d, bcorr=False, bcpoints=6, inwater=False, apt=False)

  measure negative wing power of NPKData d

  if bcorr == True, a baseline correction is applied if inwater == True, the 10% central zone is just zeroed if apt == False, computes the std() of the negative points (distance to mean)

  > == True, computes the sum(abs()) of all the points (l_1 norm)

`spike.plugins.NMR.apmin.` `phase_pivot`(d, p0, p1, pivot=0.5)

  three parameter phasing routine pivot = 0 is on left side pivot = 1 is on right side all intermediate values are possible returns actual (P0, P1)

## Module contents