FIT Module 

fetch_dosy_par(s, difflist=None, bp=True)[source]

Reads the acquisition parameters to get the DOSY parameters.

Creates the self.dosy_par attribute.

Parameters:

sDOSY object: Input spectrum that contains the ngdic attribute
difflist1darray or None: Gradient list in Gauss/cm, if existing. If None, it will be read as well from <s.datadir>/difflist
bpbool: True if the sequence uses bipolar gradients, False if it does not. It is needed because in the former case the little delta is 2 * p30

get_fit_lines(what='result')[source]

Calculates the components, and the total fit curve used as initial guess, or as fit results.

Parameters:

whatstr: 'iguess' or 'result'

Returns:

totalslist of 1darray: Sum of all the signals, per region
componentslist of 2darray: Components fitted for each region. Note that regions with only one component will be 2darrays anyways.

iguess(filename=None, ext='idy', diff_c_0=1e-10)[source]

Either makes or reads an initial guess file for the fit. The resulting dictionary will be saved in self.i_guess

Parameters:

filenamestr: Will try to read <filename>.<ext>. If it does not exist, will write in <filename>.idy
extstr: Extension for the file, either idy or fdy
diff_c_0float: Initial default value for the diffusion coefficient.

Returns:

None

See also

load_fit(filename=None, n=-1, ext='fdy')[source]

Reads a file with fit.read_dy and stores the result in self.result.

Parameters:

filename: str: Path to the .fdy file to be read. If None, “<self.filename>.fdy” is used.
n: int: Index of the fit to be read (default: last one)
ext: str: Extension of the file to be used

Returns:

None

See also

klassez.fit.fit_dosy()

klassez.fit.plot_fit_dosy()

static parse_pprog(pprog)[source]

Tries to understand from the name of the pulse program if the experiment was acquired with single or double stimulated echoes, and with or without bipolar gradients.

Parameters:

pprogstr: Name of the pulse program

Returns:

dstebool: Double (True) or single (False) stimulated echo
bpbool: Bipolar gradients (True) or without (False)

plot(what='result', show_res=False, res_offset=0, filename=None, ext='svg', dpi=600, dim=None)[source]

Plots either the initial guess or the result of the fit, and saves all the figures. Calls fit.plot_fit_dosy(). The figures will be saved in the directory Figures_<filename>/<what>/<label>.svg.

Parameters:

whatstr: ‘iguess’ to plot the initial guess, ‘result’ to plot the fitted data
show_resbool: Show the plot of the residuals
res_offsetfloat: Displacement of the residuals plot from 0, to be given as a fraction of the height of the experimental data. res_offset > 0 will move the residuals BELOW the zero-line!
filenamestr: Determines the name of the directory where the figures will be saved. If None, <self.filename> is used
extstr: Format of the saved figures
dpiint: Resolution of the figures, in dots per inches
dimtuple: Dimension of the figure in inches

Returns:

None

See also

select_model(dste, bp)[source]

Select the model on the following scheme:

dste = False and bp = False: klassez.fit.model_ste()
dste = False and bp = True: klassez.fit.model_stebp()
dste = True and bp = False: klassez.fit.model_dste()
dste = True and bp = True: klassez.fit.model_dstebp()

The selected function will be stored in self.model.

Parameters:

dstebool: Single (False) or double (True) stimulated echo
bpbool: Uses bipolar gradients (True) or not (False).

class klassez.fit.DosyFit_pp3D(S, datadir=None, filename=None)[source]

Bases: DosyFit

Interface for the fitting of a klassez.Spectra.DOSY_T1 object, i.e. a 3D spectrum where the DOSY is acquired along the 31 dimension and the big delta (d20) is increased along F2.

Attributes:

datadirstr

Path where to save files and figures

filenamestr

Name for files, figures, and so on

planeslist of klassez.Spectra.pDOSY object

Projection of the original spectrum along the 31 direction

g1darray

Gradient strength in T/m

dosy_pardict

Dictionary of dosy parameters.

dosy_par = {
        'gamma' : # gyromagnetic ratio in MHz/T,
        'D'     : # list of big delta in seconds,
        'd'     : # little delta in seconds,
        'tau'   : # tau in seconds,
        'p90'    : # 90° pulse duration in seconds,
        }

keyslist of str

Identifiers for the profiles to fit

datadict of 2darray

Each time you call for it you will get a dictionary with the labels for each profile

i_guesslist of dict

Dictionary of the initial guess, generated by self.iguess.

i_guess = [{
    'I' : # intensity factor (1darray, long as planes),
    'q' : # offset (1darray, long as planes),
    'diff_c' : # diffusion coefficients (1darray, long as components),
    'diff_f' : # fractions (2darray, (planes, components))
    'diff_e' : # fit errors for the diffusion coefficients (1darray, long as components),
    } for _ in self.keys]

resultlist of dict

Dictionary of fit results, generated by either self.dofit or self.read_fit. Same structure and shape of self.i_guess

Methods

`data_from_integrals`(input_data)	Fetch data from the integrals dictionary
`data_from_vf`(input_data)	Fetch data from the fit list
`dofit`([seq, filename, d_bds, f_bds, vary_q])	Performs the fit of the profiles.
`fetch_dosy_par`(s[, bp])	Reads the acquisition parameters to get the DOSY parameters.
`get_fit_lines`([what])	Computes the fit lines using the internal methods of `klassez.fit.DosyFit`, and then collects it together.
`iguess`([filename, ext, diff_c_0, ref])	Either makes or reads an initial guess file for the fit.
`integrate_planes`([keys, use_bas])	Get/compute the integrals for all the planes.
`load_fit`([filename, ext])	Reads the output of an already performed fit by reading the files <plane.filename>.<ext> for all the planes, reorganizes them, and stores the outcome in `self.result`
`merge_planes`([what])	Rewrites either the `self.i_guess` or `self.result` attribute by merging the information relative to each plane.
`model`(g, diff_c, gamma, D, d[, tau, p90, k])	Calls `self._model`, instanced by `klassez.DosyFit_pp3D.select_model()`, with the passed arguments and, if the bigdelta `D` is an array, to plane `k`.
`parse_pprog`(pprog)	Tries to understand from the name of the pulse program if the experiment was acquired with single or double stimulated echoes, and with or without bipolar gradients.
`plot`([what, only_all, show_res, res_offset, ...])	Plots either the initial guess or the result of the fit, and saves all the figures.
`select_model`(dste, bp)	Select the model on the following scheme:

__init__(S, datadir=None, filename=None)[source]

Initialize the class. This function will slice S along the DOSY dimension (31) and store the planes in the self.planes attribute. Then, it will try to load the integrals. If these are not found, it will ask you to integrate the first plane, and it will compute all the integrals by itself.

Parameters:

Sklassez.Spectra.DOSY_T1 object: Input dataset, after processing
datadirstr: Custom path where to save files and figures. If None, ./``filename`` is created
filenamestr: Custom filename for files and figures. If None, S.filename is used.

dofit(seq=False, filename=None, d_bds=3, f_bds=[0, 3], vary_q=False)[source]

Performs the fit of the profiles. Saves a .fdy file and stores the results in the attribute self.result.

Parameters:

seqbool: If False, the fit is performed by forcing the diffusion coefficient to be the same across the same region in different planes. If True, the diffusion coefficient can vary, and the fit is performed using the internal fit method of the planes objects.
filenamestr or None: File where to save the results of the fit: <filename>.fdy
d_bdsfloat or list: See klassez.fit.fit_dosy()
f_bdsfloat or list: See klassez.fit.fit_dosy()
vary_qbool: Include the offset in the fit strongly discouraged

Returns:

None

See also

klassez.fit.fit_dosy()

klassez.fit.DosyFit.get_fit_lines()

fetch_dosy_par(s, bp=True)[source]

Reads the acquisition parameters to get the DOSY parameters.

Creates the self.dosy_par attribute.

Parameters:

sDOSY object: Input spectrum that contains the ngdic attribute
bpbool: True if the sequence uses bipolar gradients, False if it does not. It is needed because in the former case the little delta is 2 * p30

get_fit_lines(what='result')[source]

Computes the fit lines using the internal methods of klassez.fit.DosyFit, and then collects it together.

Parameters:

whatstr: 'iguess' or 'result'

Returns:

totals3darray: Collection of the total dosy profiles, per plane. Dimension: (number of planes, number of regions, pts)
components4darray: Collection of the components that generate the correspondant total trace. Dimension: (number of planes, number of regions, number of components, pts)

See also

iguess(filename=None, ext='idy', diff_c_0=1e-10, ref=0)[source]

Either makes or reads an initial guess file for the fit. Operates only on _one_ plane, chosen as reference. The resulting dictionary will be saved in self.i_guess

Parameters:

filenamestr: Will try to read <filename>.<ext>. If it does not exist, will write in <filename>.idy
extstr: Extension for the file, either idy or fdy
diff_c_0float: Initial default value for the diffusion coefficient.
refint: Index of the reference plane (python numbering)

Returns:

None

See also

klassez.misc.key_to_limits()

integrate_planes(keys=None, use_bas=False)[source]

Get/compute the integrals for all the planes. Stores the integrals in self.data

Parameters:

keyslist of str: Keys that identify the regions to integrate. If None, the integration is performed interactively through GUI
use_basbool: Use the baseline or not.

Returns:

None

See also

klassez.Spectra.pDOSY.integrate()

load_fit(filename=None, ext='fdy')[source]

Reads the output of an already performed fit by reading the files <plane.filename>.<ext> for all the planes, reorganizes them, and stores the outcome in self.result

Parameters:

extstr: 'fdy' or 'idy'

Returns:

None

See also

klassez.fit.plot_fit_dosy()

merge_planes(what='iguess')[source]

Rewrites either the self.i_guess or self.result attribute by merging the information relative to each plane.

Parameters:

whatstr: 'iguess' or 'result'. Determines which attribute to read and write.

model(g, diff_c, gamma, D, d, tau=0, p90=0, k=None)[source]

Calls self._model, instanced by klassez.DosyFit_pp3D.select_model(), with the passed arguments and, if the bigdelta D is an array, to plane k.

Parameters:

g1darray: Gradient strength T/m
diff_cfloat: Diffusion coefficient m^2/s
gammafloat: Gyromagnetic ratio MHz/T
Dlist or float: Big delta seconds
dfloat: Little delta seconds
taufloat: Tau seconds
kint or None: Index for the difflist that corresponds to the actual bigdelta. If None and D is a sequence, all the models will be computed.

Returns:

y1darray: Computed model

plot(what='result', only_all=False, show_res=False, res_offset=0, figdir=None, filename=None, ext='svg', dpi=100, dim=None)[source]

Plots either the initial guess or the result of the fit, and saves all the figures. Calls fit.plot_fit_dosy(). The figures will be saved in the directory <figdir>/<what>/<label>.<ext>.

Parameters:

whatstr: ‘iguess’ to plot the initial guess, ‘result’ to plot the fitted data
only_all = bool: Plot only the figure with all the planes together
show_resbool: Show the plot of the residuals
res_offsetfloat: Displacement of the residuals plot from 0, to be given as a fraction of the height of the experimental data. res_offset > 0 will move the residuals BELOW the zero-line!
figdirstr: Base path for the figure. This function will create a directory named <figdir>/<what> and will save all the plots therein. The default is Figures_<self.filename>.
filenamestr: Determines the name of the directory where the figures will be saved. If None, <self.filename> is used
extstr: Format of the saved figures
dpiint: Resolution of the figures, in dots per inches
dimtuple: Dimension of the figure in inches

Returns:

None

See also

klassez.fit.plot_fit_dosy_multi()

select_model(dste, bp)[source]

Select the model on the following scheme:

dste = False and bp = False: klassez.fit.model_ste()
dste = False and bp = True: klassez.fit.model_stebp()
dste = True and bp = False: klassez.fit.model_dste()
dste = True and bp = True: klassez.fit.model_dstebp()

The selected function will be stored in self.model.

Parameters:

dstebool: Single (False) or double (True) stimulated echo
bpbool: Uses bipolar gradients (True) or not (False).

class klassez.fit.Peak(acqus, u=None, fwhm=5, k=1, b=0, phi=0, N=None, group=0)[source]

Bases: object

Class to represent the characteristic parameters of an NMR peak, and to compute it.

Attributes:

t: 1darray: Timescale for the FID
SFO1: float: Nucleus Larmor frequency
o1p: float: Carrier position
N: int: Number of points of the spectrum, i.e. after eventual zero-filling
u: float: Chemical shift /ppm
fwhm: float: Linewidth /Hz
k: float: Intensity, relative
b: float: Fraction of gaussianity (b=0 equals pure lorentzian)
phi: float: Phase /degrees
group: int: Identifier for the component of a multiplet

Methods

`__call__`([A, cplx, get_fid])	Generates a voigt signal on the basis of the stored attributes, in the time domain.
`get_fid`([A])	Compute and returns the FID encoding for that signal.
`par`()	Creates a dictionary with the currently stored attributes and returns it.

__call__(A=1, cplx=False, get_fid=False)[source]

Generates a voigt signal on the basis of the stored attributes, in the time domain. Then, makes the Fourier transform and returns it after the eventual zero-filling.

Parameters:

Afloat: Absolute intensity value
cplxbool: Returns the complex (True) or only the real part (False) of the signal
get_fidbool: If True, returns the FID instead of the transformed signal. Always complex!

Returns:

sgn1darray: generated signal according to get_fid and cplx

__init__(acqus, u=None, fwhm=5, k=1, b=0, phi=0, N=None, group=0)[source]

Initialize the class with the configuration parameters, and with defauls values, if not given.

Parameters:

acqus: dict: It should contain “t”, “SFO1”, “o1p”, and “N”
u: float: Chemical shift /ppm
fwhm: float: Linewidth /Hz
k: float: Intensity, relative
b: float: Fraction of gaussianity (b=0 equals pure lorentzian)
phi: float: Phase /degrees
N: int: Number of points of the spectrum, i.e. after eventual zero-filling. None means to not zero-fill
group: int: Identifier for the component of a multiplet

get_fid(A=1)[source]

Compute and returns the FID encoding for that signal.

Parameters:

Afloat: Absolute intensity value

Returns:

sgn1darray: generated signal in the time domain

par()[source]

Creates a dictionary with the currently stored attributes and returns it.

Returns:

dic: dict: Dictionary of parameters

class klassez.fit.SINC_ObjFunc(gamma1=10, gamma2=0.01, gamma3=0, e1=0, e2=0)[source]

Bases: object

Computes the objective function as explained in M. Sawall et al., Journal of Magnetic Resonance 289 (2018), 132-141. The cost function is computed as:

\[f(d) = \sum_{i=1}^3 \gamma_i g_i(d|e_i)\]

where d is the real part of the NMR spectrum.

Attributes:

gamma1float: Weighting factor for function g1
gamma2float: Weighting factor for function g2
gamma3float: Weighting factor for function g3
e1float: Tolerance value for function g1
e2float: Tolerance value for function g2

Methods

`__call__`(d)	Computes the objective function f as explained in the paper
`g1`(d[, e1])	Penalty function for negative entries of the spectrum
`g2`(d[, e2])	Regularization function that favours the smallest integral.
`g3`(d)	Regularization function for the smoothing.

__call__(d)[source]: Computes the objective function f as explained in the paper

__init__(gamma1=10, gamma2=0.01, gamma3=0, e1=0, e2=0)[source]

Initialize the coefficients used to weigh the objective function.

Parameters:

gamma1float: Weighting factor for function g1
gamma2float: Weighting factor for function g2
gamma3float: Weighting factor for function g3
e1float: Tolerance value for function g1
e2float: Tolerance value for function g2

static g1(d, e1=0)[source]

Penalty function for negative entries of the spectrum

Parameters:

d1darray: Spectrum
e1float: Tolerance for negative entries

static g2(d, e2=0)[source]

Regularization function that favours the smallest integral.

Parameters:

d1darray: Spectrum
e2float: Tolerance for ideal baseline

static g3(d)[source]

Regularization function for the smoothing.

Parameters:

d1darray: Spectrum

class klassez.fit.Voigt_Fit(ppm_scale, S, t_AQ, SFO1, o1p, nuc=None, filename='fit')[source]

Bases: object

This class offers an “interface” to fit a 1D NMR spectrum.

Attributes:

ppm_scale1darray: Self-explanatory
S1darray: Spectrum to fit. Only real part
t_AQ1darray: acquisition timescale of the spectrum
SWfloat: Spectral width /Hz
SFO1float: Larmor frequency of the nucleus
o1pfloat: Pulse carrier frequency
filenamestr or Path: Root of the names of the files that will be saved
X_labelstr: Label for the chemical shift axis in the figures
i_guesslist of dict: Initial guess for the fit, read by a .ivf file with klassez.fit.read_vf()
resultlist of dict: Result the fit, read by a .fvf file with klassez.fit.read_vf()

Methods

`dofit`([indep, u_lim, f_lim, k_lim, ph_lim, ...])	Perform a lineshape deconvolution fitting.
`edit_iguess`([filename, ext])	Edit the initial guess of the fit, stored in the `self.i_guess` attribute, through the use of a dedicated GUI.
`edit_result`([filename, ext])	Edit the result of the fit, stored in the `self.result` attribute, through the use of a dedicated GUI.
`get_fit_lines`([what, cplx, fid])	Calculates the components, and the total fit curve used as initial guess, or as fit results.
`iguess`([filename, n, ext, auto])	Reads, or computes, the initial guess for the fit.
`load_fit`([filename, n, ext])	Reads a file with `fit.read_vf` and stores the result in `self.result`.
`plot`([what, show_total, show_res, ...])	Plots either the initial guess or the result of the fit, and saves all the figures.
`res_histogram`([what, nbins, density, ...])	Computes the histogram of the residuals and saves it.
`to_tragico`([which, filename])	Writes input 1 and input 2 for a TrAGICo run, on the basis of either the initial guess or the results of a fit.

__init__(ppm_scale, S, t_AQ, SFO1, o1p, nuc=None, filename='fit')[source]

Initialize the class with common values.

Parameters:

ppm_scale1darray: ppm scale of the spectrum
S1darray: Spectrum to be fitted
t_AQ1darray: Acquisition timescale
SFO1float: Larmor frequency of the observed nucleus, in MHz
o1pfloat: Carrier position, in ppm
nucstr: Observed nucleus. Used to customize the x-scale of the figures.
filenamestr: Root of the name of the files that will be saved

dofit(indep=True, u_lim=1, f_lim=10, k_lim=(0, 3), ph_lim=(-180, 180), vary_phase=False, vary_b=True, itermax=10000, fit_tol=1e-08, filename=None, method='leastsq', basl_fit='no')[source]

Perform a lineshape deconvolution fitting. The initial guess is read from the attribute self.i_guess. The components can be considered to be all independent from one to another by setting indep=True: this means that the fit will be done using fit.voigt_fit_indep. The indep=False option has not been implemented yet.

Parameters:

indepbool: True to consider all the components to be independent
u_limfloat: Determines the displacement of the chemical shift (in ppm) from the starting value.
f_limfloat: Determines the displacement of the linewidth (in Hz) from the starting value.
k_limfloat or tuple: If tuple, minimum and maximum allowed values for k during the fit. If float, maximum displacement from the initial guess
ph_limtuple: Minimum and maximum allowed values for the phases of the peaks, in degrees
vary_phasebool: Allow the peaks to change phase (True) or not (False)
vary_bbool: Allow the peaks to change Lorentzian/Gaussian ratio
itermaxint: Maximum number of allowed iterations
fit_tolfloat: Value of the target function to be set as x_tol and f_tol
filenamestr or Path: Path to the output file. If None, “<self.filename>.fvf” is used
methodstr or list of str: Method to be used for the optimization. See lmfit for details. There is the option to run multiple optimizations in series.
basl_fitstr: How to address the baseline fit. The options are: * “no” : Do not use baseline (default) * “fixed” : The baseline is computed once and kept fixed during the optimization * “fit” : The baseline coefficients enter as fit parameters during the nonlinear optimization * “calc” : The baseline coefficients are calculated during the optimization via linear least-squares optimization

Returns:

lmfit_resultslist of lmfit.minimizer.MinimizerResult: Sequence of the fit results, ordered as the regions dictionary

See also

klassez.fit.voigt_fit_indep()

edit_iguess(filename=None, ext='ivf')[source]

Edit the initial guess of the fit, stored in the self.i_guess attribute, through the use of a dedicated GUI. First, compute or load the initial guess by calling self.iguess with the appropriate filename. Then you can call this method to refine.

Remember to read the documentation of the GUI to understand how to use it!

Parameters:

filenamestr or Path: Filename to be saved and read again after the edit. If None, self.filename is used.
extstr: 'ivf' or 'fvf'

Returns:

None

edit_result(filename=None, ext='fvf')[source]

Edit the result of the fit, stored in the self.result attribute, through the use of a dedicated GUI. First, compute or load the initial guess by calling self.dofit or self.load_fit with the appropriate filename. Then you can call this method to refine.

Remember to read the documentation of the GUI to understand how to use it!

Parameters:

filenamestr or Path: Filename to be saved and read again after the edit. If None, self.filename is used.
extstr: 'ivf' or 'fvf'

Returns:

None

get_fit_lines(what='result', cplx=False, fid=False)[source]

Calculates the components, and the total fit curve used as initial guess, or as fit results. The components will be returned as a list, not split by region.

Parameters:

whatstr: ‘iguess’ or ‘result’

Returns:

signalslist of 1darray: Components used for the fit
total1darray: Sum of all the signals
limits_listlist: List of region delimiters, in ppm
whole_basl1darray: Computed baseline

iguess(filename=None, n=-1, ext='ivf', auto=False)[source]

Reads, or computes, the initial guess for the fit. If the file is there already, it just reads it with fit.read_vf. Otherwise, it calls gui.make_iguess to make it.

Parameters:

filename: str or None: Path to the input file. If None, “<self.filename>.ivf” is used
n: int: Index of the initial guess to be read (default: last one)
ext: str: Extension of the file to be used
auto: bool: If True, uses the GUI for automatic peak picking, if False, the manual one

Returns:

None

See also

klassez.gui.make_iguess()

klassez.gui.make_iguess_auto()

klassez.fit.read_vf()

load_fit(filename=None, n=-1, ext='fvf')[source]

Reads a file with fit.read_vf and stores the result in self.result.

Parameters:

filename: str or Path: Path to the .fvf file to be read. If None, “<self.filename>.fvf” is used.
n: int: Index of the fit to be read (default: last one)
ext: str: Extension of the file to be used

Returns:

None

See also

klassez.gui.make_iguess()

klassez.gui.make_iguess_auto()

klassez.fit.read_vf()

plot(what='result', show_total=True, show_res=False, res_offset=0, show_basl=False, labels=None, filename=None, ext='svg', dpi=600, dim=None)[source]

Plots either the initial guess or the result of the fit, and saves all the figures. Calls fit.plot_fit(). The figure <filename>_full will show the whole model and the whole spectrum. The figures labelled with _R<k> will depict a detail of the fit in the k-th fitting region. Optional labels for the components can be given: in this case, the structure of labels should match the structure of self.result (or self.i_guess). This means that the length of the outer list must be equal to the number of fitting region, and the length of the inner lists must be equal to the number of peaks in that region.

Parameters:

whatstr: ‘iguess’ to plot the initial guess, ‘result’ to plot the fitted data
show_totalbool: Show the total trace (i.e. sum of all the components) or not
show_resbool: Show the plot of the residuals
res_offsetfloat: Displacement of the residuals plot from 0, to be given as a fraction of the height of the experimental spectrum. res_offset > 0 will move the residuals BELOW the zero-line!
show_baslbool: If True, displays the baseline on the spectrum and uses it to compute the total trace.
labelslist of list: Optional labels for the components. The structure of this parameter must match the structure of self.result
filenamestr or Path: Root of the name of the figures that will be saved. If None, <self.filename> is used
extstr: Format of the saved figures
dpiint: Resolution of the figures, in dots per inches
dimtuple: Dimension of the figure in inches

Returns:

None

See also

klassez.fit.plot_fit()

res_histogram(what='result', nbins=500, density=True, f_lims=None, xlabel='Residuals', x_symm=True, barcolor='tab:green', fontsize=20, filename=None, ext='svg', dpi=300)[source]

Computes the histogram of the residuals and saves it. Employs klassez.fit.histogram() to make the figure.

Parameters:

whatstr: ‘iguess’ or ‘result’
nbinsint: number of bins to be calculated
densitybool: True for normalize data
f_limstuple or None: limits for the x axis of the figure
xlabelstr or None: Text to be displayed under the x axis
x_symmbool: set it to True to make symmetric x-axis with respect to 0
barcolorstr: Color of the bins
fontsizefloat: Biggest fontsize in the figure
filenamestr or Path: name for the figure to be saved
extstr: Format of the image
dpiint: Resolution of the image in dots per inches

Returns:

None

See also

klassez.fit.histogram()

to_tragico(which='iguess', filename=None)[source]

Writes input 1 and input 2 for a TrAGICo run, on the basis of either the initial guess or the results of a fit. The files will be named ‘<filename>_inp1’ and ‘<filename>_inp2’, respectively.

Parameters:

whichstr: ‘iguess’ or ‘result’
filenamestr or Path: Name of the file that will be saved. If None, the file will be saved in the spectrum directory

class klassez.fit.Voigt_Fit_2D(ppm_f1, ppm_f2, data, acqus, procs=None, label_list=None)[source]

Bases: object

Class that wraps methods for the fit of 2D spectra with a set of 2D Voigtian lines.

Warning

This is work in progress.

Methods

`draw_coord`([filename, labelsize, ext, dpi])	Makes a figure with the experimental dataset and the peak-picked signals as crosshairs.
`draw_crossmarks`(coord, ax[, label_list, ...])	Draw crossmarks and peak labels on a figure.
`fit`([filename, overwrite, start_index])	Perform the fit of all the 2D peaks, one by one, by reading the starting values from Vi.
`iguess`([filename, start_index, only_edit, ...])	Make the initial guess for all the peaks.
`load_coord`([coord_filename])	Read the values from the coord filename and save them into the attribute "coord".
`load_fit`([filename])	Reads the file with the parameters of the fitted peaks, separates the values and stores them into attributes.
`load_iguess`([filename])	Reads the initial guess file with the parameters of the peaks, separates the values and stores them into attributes.
`make_peaks`(idx, V)	Calculate the set of 2D peaks, given the matrix of their parameters and their index.
`peak_pick`([coord_filename])	Performs peak_picking by calling fit.peak_pick.
`plot`([filename, show_exp, dpi])	Draw a plot of the guessed/fitted peaks.

__init__(ppm_f1, ppm_f2, data, acqus, procs=None, label_list=None)[source]

Initialize the class with ppm scales, experimental spectrum, acqus and procs dictionaries.

Parameters:

ppm_f11darray: ppm scale for the indirect dimension
ppm_f21darray: ppm scale for the direct dimension
data2darray: Spectrum to fit. The dimension should match the scale sizes.
acqusdict: Dictionary of acquisition parameters
procsdict: Dictionary of processing parameters
label_listlist: Labels for the peaks

draw_coord(filename=None, labelsize=8, ext='svg', dpi=600, **kwargs)[source]

Makes a figure with the experimental dataset and the peak-picked signals as crosshairs.

Parameters:

filenamestr or Path or None: Filename for the figure to be saved. If None, it is shown instead.
labelsizefloat: Font size for the peak index
extstr: Format of the image
dpiint: Resolution of the saved image in dots per inches
kwargskeyworded arguments: Additional options for figures.ax2D

static draw_crossmarks(coord, ax, label_list=None, markersize=5, labelsize=8, markercolor='tab:blue', labelcolor='b')[source]

Draw crossmarks and peak labels on a figure.

Parameters:

axmatplotlib.Subplot object: Subplot where to plot the crossmarks and the labels.
label_listlist: Labels for the peaks. If None, they are computed as 1, 2, 3, …
markersizeint: Dimension of the crossmark
labelsizeint: Fontsize for the labels
markercolorstr: Color of the crossmark
labelcolorstr: Color of the labels

fit(filename='fit.out', overwrite=False, start_index=1, **fit_kws)[source]: Perform the fit of all the 2D peaks, one by one, by reading the starting values from Vi.

iguess(filename='peaks.inp', start_index=1, only_edit=None, fwhm0=100, overwrite=False, auto=False)[source]

Make the initial guess for all the peaks.

Parameters:

filenamestr or Path: Path to the file where the peak parameters will be written
start_indexint: Index of the first peak to be guessed.
only_editsequence of ints or None: Index of the peak that have to be guessed interactively. The ones that do not appear here are guessed automatically.
fwhm0float: Default value for fwhm in both dimension for automatic guess
overwritebool: Choose if to overwrite the file or append the new peaks at the bottom
autobool: Allow automatic guess for the peaks. To be used in conjunction with only_edit: if auto is False, all the peaks are guessed interactively!

load_coord(coord_filename='coord.tmp')[source]

Read the values from the coord filename and save them into the attribute “coord”.

Parameters:

coord_filenamestr: Path to the file to be read

load_fit(filename='fit.out')[source]

Reads the file with the parameters of the fitted peaks, separates the values and stores them into attributes. Then, uses these values to compute the peaks and save them into self.peaks. In particular:

idx will contain the peak index (first column of the file),

Vf will contain [u1, u2, fwhm1, fwhm2, Im, b] for each peak,

Wf will contain the fitting interval as ( (L_f1, R_f1), (L_f2, R_f2) )

Parameters:

filename: str: Path to the input file to be read

load_iguess(filename='peaks.inp')[source]

Reads the initial guess file with the parameters of the peaks, separates the values and stores them into attributes. In particular:

idx will contain the peak index (first column of the file),

Vi will contain [u1, u2, fwhm1, fwhm2, Im, b] for each peak,

Wi will contain the fitting interval as ( (L_f1, R_f1), (L_f2, R_f2) )

Parameters:

filenamestr: Path to the input file to be read

make_peaks(idx, V)[source]

Calculate the set of 2D peaks, given the matrix of their parameters and their index. The array of indexes is required in order to recognize the different components that contribute to a single peak. The attribute peaks of the class will be cleared and updated.

Parameters:

idx: 1darray: Array of indexes of the peaks.
V: list or 2darray: List of parameters that describe the peaks.

peak_pick(coord_filename='coord.tmp')[source]

Performs peak_picking by calling fit.peak_pick. Saves the list of peak positions in the attribute coord

Parameters:

coord_filenamestr: Path to the file where to save the peak coordinates

plot(filename=None, show_exp=True, dpi=600, **kwargs)[source]

Draw a plot of the guessed/fitted peaks.

Parameters:

filenamestr or Path or None: Filename for the figure. If it is None, the figure is shown.
show_expbool: Choose if to plot the experimental spectrum or not
dpiint: Resolution of the saved image
kwargskeyworded arguments: Additional parameters to be passed to figures.ax2D.

class klassez.fit.Voigt_Fit_P2D(ppm_scale, S, t_AQ, SFO1, o1p, nuc=None, filename='fit')[source]

Bases: object

This class offers an “interface” to fit a pseudo 2D NMR spectrum.

Attributes:

ppm_scale1darray: Self-explanatory
S2darray: Spectrum to fit. Only real part
t_AQ1darray: acquisition timescale of the spectrum
SFO1float: Larmor frequency of the nucleus
o1pfloat: Pulse carrier frequency
filenamestr: Root of the names of the files that will be saved
X_labelstr: Label for the chemical shift axis in the figures
i_guesslist: Initial guess for the fit, read by a .ivf file with fit.read_vf_P2D
resultlist: Result the fit, read by a .fvf file with fit.read_vf_P2D

Methods

`dofit`([u_tol, f_tol, vary_phase, vary_b, ...])	Perform a lineshape deconvolution fitting by calling `fit.voigt_fit_P2D`.
`get_fit_lines`([what])	Calculates the components, and the total fit curve used as initial guess, or as fit results.
`iguess`([input_file, expno, n])	Reads, or computes, the initial guess for the fit.
`load_fit`([output_file, n])	Reads a file with fit.read_vf_P2D and stores the result in self.result.
`plot`([what, show_total, show_res, ...])	Plots either the initial guess or the result of the fit, and saves all the figures.
`res_histogram`([what, nbins, density, ...])	Computes the histogram of the residuals and saves it in the same folder of the fit figures.

__init__(ppm_scale, S, t_AQ, SFO1, o1p, nuc=None, filename='fit')[source]

Initialize the class with common values.

Parameters:

ppm_scale1darray: ppm scale of the spectrum
S2darray: Spectrum to be fitted
t_AQ1darray: Acquisition timescale
SFO1float: Larmor frequency of the observed nucleus, in MHz
o1pfloat: Carrier position, in ppm
nucstr: Observed nucleus. Used to customize the x-scale of the figures.
filenamestr or None: Root of the name of the files that will be saved

dofit(u_tol=1, f_tol=10, vary_phase=False, vary_b=True, itermax=10000, filename=None)[source]

Perform a lineshape deconvolution fitting by calling fit.voigt_fit_P2D. The initial guess is read from the attribute self.i_guess.

Parameters:

u_tolfloat: Determines the displacement of the chemical shift (in ppm) from the starting value.
f_tolfloat: Determines the displacement of the linewidth (in Hz) from the starting value.
vary_phasebool: Allow the peaks to change phase (True) or not (False)
vary_bbool: Allow the peaks to change Lorentzian/Gaussian ratio
itermaxint: Maximum number of allowed iterations
filenamestr: Path to the output file. If None, “<self.filename>.fvf” is used

get_fit_lines(what='result')[source]

Calculates the components, and the total fit curve used as initial guess, or as fit results.. The components will be returned as a list, not split by region.

Parameters:

whatstr: ‘iguess’ or ‘result’

Returns:

signalslist of list of 1darray: Components used for the fit
total2darray: Sum of all the signals
limits_listlist: List of the region delimiters, in ppm

iguess(input_file=None, expno=0, n=-1)[source]

Reads, or computes, the initial guess for the fit. If the file is there already, it just reads it with fit.read_vf. Otherwise, it calls gui.make_iguess to make it.

Parameters:

input_filestr or None: Path to the input file. If None, “<self.filename>.ivf” is used
expnoint: Number of the experiment on which to compute the initial guess, in python numbering
nint: Index of the initial guess to be read (default: last one)

load_fit(output_file=None, n=-1)[source]

Reads a file with fit.read_vf_P2D and stores the result in self.result.

Parameters:

output_filestr: Path to the .fvf file to be read, without the .fvf extension. If None, “<self.filename>” is used.
nint: Index of the fit to be read (default: last one)

plot(what='result', show_total=True, show_res=False, res_offset=0, labels=None, filename=None, ext='svg', dpi=600)[source]

Plots either the initial guess or the result of the fit, and saves all the figures. Calls fit.plot_fit_P2D. The figures <filename>_full will show the whole model and the whole spectrum. The figures labelled with _R<k> will depict a detail of the fit in the k-th fitting region. Optional labels for the components can be given: in this case, the structure of ‘labels’ should match the structure of self.result (or self.i_guess). This means that the length of the outer list must be equal to the number of fitting region, and the length of the inner lists must be equal to the number of peaks in that region.

Parameters:

whatstr: ‘iguess’ to plot the initial guess, ‘result’ to plot the fitted data
show_totalbool: Show the total trace (i.e. sum of all the components) or not
show_resbool: Show the plot of the residuals
res_offsetfloat: Displacement of the residuals plot from 0, to be given as a fraction of the height of the experimental spectrum. res_offset > 0 will move the residuals BELOW the zero-line!
labelslist of list: Optional labels for the components. The structure of this parameter must match the structure of self.result
filenamestr: Root of the name of the figures that will be saved. If None, <self.filename> is used
extstr: Format of the saved figures
dpiint: Resolution of the figures, in dots per inches

res_histogram(what='result', nbins=500, density=True, f_lims=None, xlabel='Residuals', x_symm=True, barcolor='tab:green', fontsize=20, filename=None, ext='svg', dpi=300)[source]

Computes the histogram of the residuals and saves it in the same folder of the fit figures. Employs fit.histogram to make the figure.

Parameters:

whatstr: ‘iguess’ or ‘result’
nbinsint: number of bins to be calculated
densitybool: True for normalize data
f_limstuple or None: limits for the x axis of the figure
xlabelstr or None: Text to be displayed under the x axis
x_symmbool: set it to True to make symmetric x-axis with respect to 0
barcolorstr: Color of the bins
fontsizefloat: Biggest fontsize in the figure
namestr: name for the figure to be saved
extstr: Format of the image
dpiint: Resolution of the image in dots per inches

klassez.fit.ax_histogram(ax, data0, nbins=100, density=True, f_lims=None, xlabel=None, x_symm=False, fitG=True, barcolor='tab:blue', fontsize=10)[source]

Computes an histogram of data and tries to fit it with a gaussian lineshape. The parameters of the gaussian function are calculated analytically directly from data using scipy.stats.norm

Parameters:

axmatplotlib.subplot Object: panel of the figure where to put the histogram
data0ndarray: the data to be binned
nbinsint: number of bins to be calculated
densitybool: True for normalize data
f_limstuple or None: limits for the x axis of the figure
xlabelstr or None: Text to be displayed under the x axis
x_symmbool: set it to True to make symmetric x-axis with respect to 0
fitGbool: Shows the gaussian approximation
barcolorstr: Color of the bins
fontsizefloat: Biggest fontsize in the figure

Returns:

mfloat: Mean of data
sfloat: Standard deviation of data.

klassez.fit.bin_data(data0, nbins=100, density=True, x_symm=False)[source]

Computes the histogram of data, sampling it into nbins bins.

Parameters:

datandarray: the data to be binned
nbinsint: number of bins to be calculated
densitybool: True for normalize data
x_symmbool: set it to True to make symmetric x-axis with respect to 0

Returns:

hist1darray: The bin intensity
bin_scale1darray: Scale built with the mean value of the bin widths.

klassez.fit.build_2D_sgn(parameters, acqus, N=None, procs=None)[source]

Create a 2D signal according to the final parameters returned by klassez.gui.make_iguess_2D(). Process it according to procs.

Parameters:

parameterslist or 2darray: sequence of the parameters: u1, u2, fwhm1, fwhm2, I, b. Multiple components are allowed
acqusdict: 2D-like acqus dictionary containing the acquisition timescales (keys t1 and t2)
Ntuple of int: Zero-filling values (F1, F2). Read only if procs is None
procsdict: 2D-like procs dictionary.

Returns:

peak2darray: rr part of the generated signal

klassez.fit.calc_R2(y, y_c)[source]

Computes the R-squared coefficient of a linear regression as:

\[R^2 = 1 - \frac{ \sum (y - <y>)^2 }{ \sum (y - y_c)^2 }\]

Parameters:

y1darray: Experimental data
y_c1darray: Calculated data

Returns:

R2float: R-squared coefficient

klassez.fit.fit_dosy(x, y, iguess, model, model_args, d_bds=3, f_bds=[0, 3], vary_q=False)[source]

Perform a fit of a DOSY profile using the specified model.

Parameters:

x1darray: Independent variable, typically the gradient strength in T/m
y1darray: Experimental data
iguessdict: Initial guess for the fit, as generated by klassez.gui.make_iguess_dosy_panel()
modelcallable: Model function. Signature:
model_argsdict of kwargs: Additional arguments to model
d_bdsfloat or list: Bounds for the diffusion coefficient. If it is a single float, the bounds will be set to -d_bds and +d_bds orders of magnitude with respect to the initial guess. E.g.: if diffc = 1e-10 and d_bds = 2, the bounds will be [1e-12, 1e-8]. If it is a list of two float``s, the bounds will be set to ``-d_bds[0]` and ``+d_bds[1] orders of magnitude with respect to the initial guess. E.g.: if diffc = 1e-10 and d_bds = [1, 3], the bounds will be [1e-11, 1e-7]
f_bdsfloat or list: Bounds for the fraction of component. If it is a single float, the bounds will be set to -f_bds and +f_bds with respect to the initial fraction. E.g.: if difff = 0.5 and f_bds = 0.3, the bounds will be [0.2, 0.8] If it is a list of two float``s, the bounds will be set to ``f_bds[0]` and ``f_bds[1], regardless of what the initial fraction is.
vary_qbool: Include the computation of the offset in the parameters. Strongly discouraged!

Returns:

dic_resultdict: Dictionary of optimized parameters, with the same format and shape of iguess.

See also

klassez.fit.fit_dosy_multi(x, y, iguess, model, model_args, d_bds=3, f_bds=[0, 3], vary_I=True, vary_q=False)[source]

Perform a fit of a DOSY profile using the specified model.

Parameters:

x1darray: Independent variable, typically the gradient strength in T/m
y1darray: Experimental data
iguessdict: Initial guess for the fit, as generated by klassez.gui.make_iguess_dosy_panel()
modelcallable: Model function. Signature:
model_argsdict of kwargs: Additional arguments to model
d_bdsfloat or list: Bounds for the diffusion coefficient. If it is a single float, the bounds will be set to -d_bds and +d_bds orders of magnitude with respect to the initial guess. E.g.: if diffc = 1e-10 and d_bds = 2, the bounds will be [1e-12, 1e-8]. If it is a list of two float``s, the bounds will be set to ``-d_bds[0]` and ``+d_bds[1] orders of magnitude with respect to the initial guess. E.g.: if diffc = 1e-10 and d_bds = [1, 3], the bounds will be [1e-11, 1e-7]
f_bdsfloat or list: Bounds for the fraction of component. If it is a single float, the bounds will be set to -f_bds and +f_bds with respect to the initial fraction. E.g.: if difff = 0.5 and f_bds = 0.3, the bounds will be [0.2, 0.8] If it is a list of two float``s, the bounds will be set to ``f_bds[0]` and ``f_bds[1], regardless of what the initial fraction is.
vary_Ibool: Include the computation of the intensity factor for each interval. If False, all the intensity differences will be handled by the fractions parameters.
vary_qbool: Include the computation of the offsets in the parameters. Strongly discouraged! If False, the initial value read from the initial guess is kept thoughout the whole fitting.

Returns:

dic_resultdict: Dictionary of optimized parameters, with the same format and shape of iguess.

See also

klassez.sim.f_gaussian()

klassez.fit.fit_int(y, y_c, q=True)[source]

Computes the optimal intensity and intercept of a linear model in the least squares sense. Let $y$ be the experimental data and $y_c$ the model, and let $<w>$ the mean of variable $w$. Then, if q=False:

\[A = \frac{ <y_c y> }{ <y_c^2> }, \qquad q = 0\]

else:

\[A = \frac{ <y_c y> - <y_c><y> }{ <y_c^2> - <y_c>^2 }, \qquad q = \frac{ <y_c>^2<y> - <y_c><y_c y> }{ <y_c^2> - <y_c>^2 }\]

Parameters:

y1darray: Experimental data
y_c1darray: Model data
qbool: If True, includes the offset in the calculation. If False, only the intensity factor is computed.

Returns:

Afloat: Optimized intensity
qfloat: Optimized intercept

klassez.fit.gaussian_fit(x, y, s_in=None)[source]

Fit y with a gaussian function, built using x as independent variable

Parameters:

x1darray: x-scale
y1darray: data to be fitted
s_infloat or None: initial guess for the standard deviation of the gaussian. If None, np.std(y) is used

Returns:

ufloat: mean
sfloat: standard deviation
Afloat: Integral

See also

klassez.fit.histogram(data, nbins=100, density=True, f_lims=None, xlabel=None, x_symm=False, fitG=True, barcolor='tab:blue', fontsize=10, filename=None, ext='svg', dpi=600)[source]

Computes an histogram of data and tries to fit it with a gaussian lineshape. The parameters of the gaussian function are calculated analytically directly from data using scipy.stats.norm

Parameters:

datandarray: the data to be binned
nbinsint: number of bins to be calculated
densitybool: True for normalize data
f_limstuple or None: limits for the x axis of the figure
xlabelstr or None: Text to be displayed under the x axis
x_symmbool: set it to True to make symmetric x-axis with respect to 0
fitGbool: Shows the gaussian approximation
barcolorstr: Color of the bins
fontsizefloat: Biggest fontsize in the figure
filenamestr or Path: name for the figure to be saved
extstr: Format of the image
dpiint: Resolution of the image in dots per inches

Returns:

mfloat: Mean of data
sfloat: Standard deviation of data.

See also

klassez.fit.ax_histogram()

klassez.fit.lr(y, x=None, force_intercept=False, w=None)[source]

Performs a linear regression of y with a model $y_c = mx + q$.

If w=None then w = np.ones_like(x).

If force_intercept=False:

\[m = \frac{\sum w x y}{\sum w x^2}, \quad q = 0\]

else, two more parameters are defined:

\[x_w = \frac{ \sum w x }{ \sum w }, \quad y_w = \frac{ \sum w y }{ \sum w }\]

\[m = \frac{ \sum w (x-x_w) (y-y_w)}{\sum w (x - x_w)^2}, \quad q = y_w - m\,x_w\]

Parameters:

y1darray: Data to be fitted
x1darray: Independent variable. If None, the point indexes are used.
force_interceptbool: If True, forces the intercept to be zero.
w1darray or None: Weights to be used for the linear regression.

Returns:

y_c1darray: Fitted trend
valuestuple: (m, q)

klassez.fit.lsp(y, x, n=5, w=None)[source]

Linear-System Polynomion Make a polynomial fit on the experimental data y by solving the linear system

\[y = T c\]

where T is the Vandermonde matrix of the x-scale and c is the set of coefficients that minimize the problem in the least-squares sense. It is also possible to make it weighted by using an array of weights w.

Parameters:

y1darray: Experimental data
x1darray: Independent variable (better if normalized)
nint: Order of the polynomion + 1, i.e. number of coefficients
w1darray: Array of weights for the data. If None, the nonweighted approach is used

Returns:

c1darray: Set of minimized coefficients

klassez.fit.make_iguess_dosy(x, labels, data, model, model_args, diff_c_0=1e-10, filename='dosy_fit')[source]

Make the initial guess for the fit of a DOSY spectrum by using a GUI to visually adjust the value of the diffusion coefficient and the number of components to use. Calls gui.make_iguess_dosy_panel() in a loop. A section of the output file is written at the end of each loop.

Parameters:

x1darray

Independent variable for the model (usually the gradient list)

labelslist of str

Identifier for the region, typically the integration window or peak number

datalist of 1darray or 2darray

Integrated profiles to fit

modelcallable

Functional model for the DOSY profile. Signature:

def model(x, diffc, **model_args):
    return 1darray

model_argsdict of keyworded arguments

Additional parameters for model.

diff_c_0float

Default initial value for the diffusion coefficient, in m^2/s

filenamestr

The output file of the procedure will be <filename>.idy

Returns:

None

See also

klassez.write_dy()

klassez.fit.make_signal(t, u, s, k, b, phi, A, SFO1=701.125, o1p=0, N=None)[source]

Generates a voigt signal on the basis of the passed parameters in the time domain. Then, makes the Fourier transform and returns it.

Parameters:

tndarray: acquisition timescale
ufloat: chemical shift /ppm
sfloat: full-width at half-maximum /Hz
kfloat: relative intensity
bfloat: fraction of gaussianity (0 = Lorentzian, 1 = Gaussian)
phifloat: phase of the signal, in degrees
Afloat: total intensity
SFO1float: Larmor frequency /MHz
o1pfloat: pulse carrier frequency /ppm
Nint or None: length of the final signal. If None, the signal is not zero-filled before to be transformed.

Returns:

sgn1darray: generated signal in the frequency domain

klassez.fit.model_dste(g, diff_c, gamma, D, d, tau, p90)[source]

Model for Double Stimulated Echo. Stejskal-Tanner equation modified by Jerschaw and Müller.

\[y(g) = \exp \{ - D (2 \pi \gamma g \delta)^2 \, (\Delta - 5 \delta / 3 - \tau - 4 p_{90}) \}\]

Parameters:

g1darray: Gradient strength T/m
diff_cfloat: Diffusion coefficient m^2/s
gammafloat: Gyromagnetic ratio MHz/T
Dfloat: Big delta seconds
dfloat: Little delta seconds
taufloat: Tau seconds
p90float: 90 degree pulse seconds

Returns:

y1darray: Computed model

klassez.fit.model_dstebp(g, diff_c, gamma, D, d, tau, p90)[source]

Model for Double Stimulated Echo with Bipolar Gradients. Stejskal-Tanner equation modified by Jerschaw and Müller.

\[y(g) = \exp \{ - D (2 \pi \gamma g \delta)^2 \, (\Delta - 5 \delta / 3 - 3 \tau - 8 p_{90}) \}\]

Parameters:

g1darray: Gradient strength T/m
diff_cfloat: Diffusion coefficient m^2/s
gammafloat: Gyromagnetic ratio MHz/T
Dfloat: Big delta seconds
dfloat: Little delta seconds
taufloat: Tau seconds
p90float: 90 degree pulse seconds

Returns:

y1darray: Computed model

klassez.fit.model_ste(g, diff_c, gamma, D, d)[source]

Model for Stimulated Echo. Basic Stejskal-Tanner equation.

\[y(g) = \exp \{ - D (2 \pi \gamma g \delta)^2 \, (\Delta - \delta / 3) \}\]

Parameters:

g1darray: Gradient strength T/m
diff_cfloat: Diffusion coefficient m^2/s
gammafloat: Gyromagnetic ratio MHz/T
Dfloat: Big delta seconds
dfloat: Little delta seconds

Returns:

y1darray: Computed model

klassez.fit.model_stebp(g, diff_c, gamma, D, d, tau, p90)[source]

Model for Stimulated Echo with Bipolar Gradients. Stejskal-Tanner equation modified by Jerschaw and Müller.

\[y(g) = \exp \{ - D (2 \pi \gamma g \delta)^2 \, (\Delta - \delta / 3 - \tau - 4p_{90}) \}\]

Parameters:

g1darray: Gradient strength T/m
diff_cfloat: Diffusion coefficient m^2/s
gammafloat: Gyromagnetic ratio MHz/T
Dfloat: Big delta seconds
dfloat: Little delta seconds
taufloat: Tau seconds
p90float: 90 degree pulse seconds

Returns:

y1darray: Computed model

klassez.fit.peak_pick_2D(ppm_f1, ppm_f2, data, coord_filename='coord.tmp')[source]

Make interactive peak_picking. The position of the selected signals are saved in coord_filename. If coord_filename already exists, the new signals are appended at its bottom: nothing is overwritten. Calls klassez.anal.select_traces() for the selection.

Parameters:

ppm_f1: 1darray: ppm scale for the indirect dimension
ppm_f2: 1darray: ppm scale for the direct dimension
data: 2darray: Spectrum to peak-pick. The dimension should match the scale sizes.
coord_filename: str or Path: Path to the file where to save the peak coordinates

Returns:

coord: list: List of (u2, u1) for each peak

klassez.fit.plot_fit(S, ppm_scale, regions, t_AQ, SFO1, o1p, show_total=False, show_res=False, res_offset=0, show_basl=False, X_label='$\\delta$ /ppm', labels=None, filename='fit', ext='svg', dpi=600, dim=None)[source]

Plots either the initial guess or the result of the fit, and saves all the figures. The figure <filename>_full will show the whole model and the whole spectrum. The figures labelled with _R<k> will depict a detail of the fit in the k-th fitting region. Optional labels for the components can be given: in this case, the structure of labels should match the structure of regions. This means that the length of the outer list must be equal to the number of fitting region, and the length of the inner lists must be equal to the number of peaks in that region.

Parameters:

S1darray: Spectrum to be fitted
ppm_scale1darray: ppm scale of the spectrum
regionsdict: Generated by klassez.fit.read_vf()
t_AQ1darray: Acquisition timescale
SFO1float: Larmor frequency of the observed nucleus, in MHz
o1pfloat: Carrier position, in ppm
show_totalbool: Show the total trace (i.e. sum of all the components) or not
show_resbool: Show the plot of the residuals
res_offsetfloat: Displacement of the residuals plot from 0, to be given as a fraction of the height of the experimental spectrum. res_offset > 0 will move the residuals BELOW the zero-line!
show_baslbool: If True, displays the baseline on the spectrum and uses it to compute the total trace.
X_labelstr: Text to show as label for the chemical shift axis
labelslist of list: Optional labels for the components. The structure of this parameter must match the structure of self.result
filenamestr or Path: Root of the name of the figures that will be saved.
extstr: Format of the saved figures
dpiint: Resolution of the figures, in dots per inches
dimtuple: Size of the figure in inches (length, height)

klassez.fit.plot_fit_P2D(S, ppm_scale, regions, t_AQ, SFO1, o1p, show_total=False, show_res=False, res_offset=0, X_label='$\\delta$ /ppm', labels=None, filename='fit', ext='svg', dpi=600)[source]

Plots either the initial guess or the result of the fit, and saves all the figures. A new folder named <filename>_fit will be created. The figure <filename>_full will show the whole model and the whole spectrum. The figures labelled with _R<k> will depict a detail of the fit in the k-th fitting region. Optional labels for the components can be given: in this case, the structure of labels should match the structure of regions. This means that the length of the outer list must be equal to the number of fitting region, and the length of the inner lists must be equal to the number of peaks in that region.

Parameters:

S2darray: Spectrum to be fitted
ppm_scale1darray: ppm scale of the spectrum
regionslist of dict: Generated by fit.read_vf_P2D
t_AQ1darray: Acquisition timescale
SFO1float: Larmor frequency of the observed nucleus, in MHz
o1pfloat: Carrier position, in ppm
nucstr: Observed nucleus. Used to customize the x-scale of the figures.
show_totalbool: Show the total trace (i.e. sum of all the components) or not
show_resbool: Show the plot of the residuals
res_offsetfloat: Displacement of the residuals plot from 0, to be given as a fraction of the height of the experimental spectrum. res_offset > 0 will move the residuals BELOW the zero-line!
X_labelstr: Text to show as label for the chemical shift axis
labelslist of list: Optional labels for the components. The structure of this parameter must match the structure of self.result
filenamestr: Root of the name of the figures that will be saved.
extstr: Format of the saved figures
dpiint: Resolution of the figures, in dots per inches

klassez.fit.plot_fit_dosy(x, label, y, total, yc, region, show_total=True, show_res=False, res_offset=0, filename=None, ext='svg', dpi=600, dim=None)[source]

Make a plot of a DOSY fit.

Parameters:

x1darray: Independent variable, normally the gradient strength in T/m
labelstr: This will appear as figure title
y1darray: Experimental data
total1darray: Total fit trace
yclist of 1darray or 2darray: Component traces
regiondict: Dictionary that contains the fitting values. Used to show the legend entries.
show_totalbool: Show the total trace (i.e. sum of all the components) or not
show_resbool: Show the plot of the residuals
res_offsetfloat: Displacement of the residuals plot from 0, to be given as a fraction of the height of the experimental data. res_offset > 0 will move the residuals BELOW the zero-line!
filenamestr: Filename of the figure that will be saved.
extstr: Format of the saved figures
dpiint: Resolution of the figures, in dots per inches
dimtuple: Size of the figure in inches (length, height)

klassez.fit.plot_fit_dosy_multi(x, yy, totals, components, region, bigdeltas=None, colors=None, filename=None, ext='svg', dpi=300, dim=None)[source]

Makes a cumulative plot of a DOSY fit performed with the klassez.fit.DosyFit_pp3D class.

Parameters:

x1darray: Gradients in T/m
yy2darray: Experimental data. Dimension: (plane, integrals)
totals2darray: Fitted trends.

klassez.fit.polyn_basl(y, n=5, method='huber', s=0.2, c_i=None, itermax=1000)[source]

Fit the baseline of a spectrum with a low-order polynomion using a non-quadratic objective function.

Let y be an array of N points. The polynomion is generated on a normalized scale that goes from -1 to 1 in N steps, and the coefficients are initialized either from outside through the parameter c_i or with the ordinary least squares fit. Then, the guess is refined using the objective function of choice employing the trust-region reflective least-squares algorithm.

Parameters:

y1darray: Experimental data
nint: Order of the polynomion + 1, i.e. number of coefficients
methodstr: Objective function of choice. ‘q’: quadratic, ‘tq’: truncated quadratic, ‘huber’: Huber, ‘atq’: asymmetric truncated quadratic, ‘ahuber’: asymmetric huber
sfloat: Relative threshold value for the non-quadratic behaviour of the objective function
c_isequence or None: Initial guess for the polynomion coefficient. If None, the least-squares fit is used
itermaxint: Number of maximum iterations

Returns:

px1darray: Fitted polynomion
clist: Set of coefficients of the polynomion

klassez.fit.print(*args, c=None, s=None, sep=' ', end='\n', file=None, flush=False)[source]: Functions for performing fits.

klassez.fit.read_dy(filename, n=-1)[source]

Reads a .idy (initial guess) or .fdy (final fit) file, containing the parameters for a DOSY fitting procedure. The file is separated and unpacked into a list of dictionaries, each of which contains the region identifier, the total intensity value and the offset, the diffusion coefficients, relative weight of the components, and the fit errors.

Parameters:

filenamestr or Path: Path to the filename to be read
nint: Number of performed fit to be read. Default: last one. The breakpoints are lines that start with “!”. For this reason, n=0 returns an empty dictionary, hence the first fit is n=1.

Returns:

regions: list: List of dictionaries for running the fit.

See also

klassez.fit.test_randomsign()

klassez.fit.read_vf(filename, n=-1)[source]

Reads a .ivf (initial guess) or .fvf (final fit) file, containing the parameters for a lineshape deconvolution fitting procedure. The file is separated and unpacked into a list of dictionaries, each of which contains the limits of the fitting window, the total intensity value, and a dictionary for each peak with the characteristic values to compute it with a Voigt line.

Parameters:

filenamestr or Path: Path to the filename to be read
nint: Number of performed fit to be read. Default: last one. The breakpoints are lines that start with “!”. For this reason, n=0 returns an empty dictionary, hence the first fit is n=1.

Returns:

regions: list: List of dictionaries for running the fit.

See also

klassez.fit.write_vf()

klassez.fit.read_vf_P2D(filename, n=-1)[source]

Reads a .ivf (initial guess) or .fvf (final fit) file, containing the parameters for a lineshape deconvolution fitting procedure. The file is separated and unpacked into a list of list of dictionaries, each of which contains the limits of the fitting window, and a dictionary for each peak with the characteristic values to compute it with a Voigt line.

Parameters:

filenamestr: Path to the filename to be read
nint: Number of performed fit to be read. Default: last one. The breakpoints are lines that start with “!”. For this reason, n=0 returns an empty dictionary, hence the first fit is n=1.

Returns:

regionslist of list of dict: List of dictionaries for running the fit.

klassez.fit.sinc_phase(data, gamma1=10, gamma2=0.01, gamma3=0, e1=0, e2=0, **fit_kws)[source]

Perform automatic phase correction according to the SINC algorithm, as described in M. Sawall et. al., Journal of Magnetic Resonance 289 (2018), 132–141. The fitting method defaults to “least_squares”.

Parameters:

data1darray: Spectrum to phase-correct
gamma1float: Weighting factor for function g1: non-negativity constraint
gamma2float: Weighting factor for function g2: smallest-integral constraint
gamma3float: Weighting factor for function g3: smoothing constraint
e1float: Tolerance factor for function g1: adjustment for noise
e2float: Tolerance factor for function g2: adjustment for non-ideal baseline
fit_kwskeyworded arguments: additional parameters for the fit function. See lmfit.Minimizer.minimize() for details. Do not use “leastsq” because the cost function returns a scalar value!

Returns:

p0float: Fitted zero-order phase correction angle, in degrees
p1float: Fitted first-order phase correction angle, in degrees

klassez.fit.smooth_spl(x, y, s_f=1, size=0, weights=None)[source]

Fit the input data with a 3rd-order spline, given the smoothing factor to be applied. Uses the package csaps.

Parameters:

x1darray: Location of the experimental points
y1darray: Input data to be fitted
s_ffloat: Smoothing factor of the spline. 0=best straight line, 1=native spline.
sizeint: Size of the spline. If size=0, the same dimension as y is chosen.

Returns:

x_s1darray: Location of the spline data points.
y_s1darray: Spline that fits the data.

klassez.fit.test_correl(data, subtract_mean=True)[source]

Tests an array of residuals for their correlation. It compares the unit-lag autocorrelation P of the data (see below) with the theoretical value for non-correlated data T_P:

\[P = \sum_k^{N-1} r[k] \, r[k+1] ;\quad T_P = \sqrt{N-1} \sum_k r[k]^2\]

If $P < T_P$, the residuals are not correlated, and the result is True.

Parameters:

data: 1darray: Residuals to be test
subtract_mean: bool: If True, subtracts from the residuals their mean.

Returns:

test: bool: True if the residuals are non correlated, False otherwise

klassez.fit.test_ks(data, thresh=0.05)[source]

Performs the Kolmogorov-Smirnov test on the residuals to check if they are drawn from a normal distribution. The implementation is scipy.stats.kstest(). The result is True if the residuals are Gaussian.

Parameters:

data1darray: Residuals to test
threshfloat: Significance level for the test. Default is 5%

Returns:

testbool: True if the residuals are Gaussian, False otherwise

klassez.fit.test_randomsign(data, thresh=1.96)[source]

Test an array of residuals for the randomness of the sign changes. The result it True if the sequence is recognized as random.

Parameters:

data1darray: Residuals to test
threshfloat: Significance level. The default is 1.96, which corresponds to 5% significance level.

Returns:

testbool: True if the signs are random, False otherwise

klassez.fit.test_residuals(res, alpha=0.05)[source]

Tests an array of residuals for their randomness, correlation, and underlying distribution. To do this, it uses the functions klassez.fit.test_randomsign(), klassez.fit.test_correl(), klassez.fit.test_ks(). The results of the tests will be print in standard output and returned.

Parameters:

resndarray: Residuals to be tested
alphafloat: Significance level

Returns:

test_randombool: Randomness of the residuals (True = random)
test_correlationbool: Correlation of the residuals (True = non-correlated)
test_gaussianbool: Normal-distribution of the residuals (True = normally-distributed)

See also

klassez.fit.test_correl()

klassez.fit.test_ks()

klassez.fit.voigt_fit_2D(x_scale, y_scale, data, parameters, lim_f1, lim_f2, acqus, N=None, procs=None, utol=(1, 1), s1tol=(0, 500), s2tol=(0, 500), vary_b=False, logfile=None)[source]

Function that performs the fit of a 2D peak using multiple components. The program reads a parameter matrix, that contains: .. code-block:: bash

u1 /ppm, u2 /ppm, fwhm1 /Hz, fwhm2 /Hz, I /a.u., b

in each row. The number of rows corresponds to the number of components used for the computation of the final signal. The function returns the analogue version of the parameters matrix, but with the optimized values.

Warning

Work in progress! Does not work right now.

Parameters:

x_scale1darray: ppm_f2 of the spectrum, full
y_scale1darray: ppm_f1 of the spectrum, full
data2darray: spectrum, full
parameters1darray or 2darray: Matrix (# signals, 6). Read main caption.
lim_f2tuple: Trimming limits for x_scale
lim_f1tuple: Trimming limits for y_scale
acqusdict: Dictionary of acquisition parameters.
Ntuple of ints: len(y_scale), len(x_scale). Used only if procs is None
procsdict: Dictionary of processing parameters.
utoltuple of floats: Tolerance for the chemical shifts (utol_f1, utol_f2). Values will be set to u1 +/- utol_f1, u2 +/- utol_f2
s1toltuple of floats: Range of variations for the fwhm in f1, in Hz
s2toltuple of floats: Range of variations for the fwhm in f2, in Hz
vary_bbool: Choose if to fix the b value or not
logfilestr or None: Path to a file where to write the fit information. If it is None, they will be printed into standard output.

Returns:

out_parameters2darray: parameters, but with the optimized values.

klassez.fit.voigt_fit_P2D(S, ppm_scale, regions, t_AQ, SFO1, o1p, u_tol=1, f_tol=10, vary_phase=False, vary_b=False, itermax=10000, filename='fit')[source]

Performs a lineshape deconvolution fit on a pseudo-2D experiment using a Voigt model. The initial guess must be read from a .ivf file. All components are treated as independent, regardless from the value of the “group” attribute. The fitting procedure operates iteratively one window at the time. During the fit routine, the peak positions and lineshapes will be varied consistently on all the experiments; only the intensities are allowed to change in a different way.

Parameters:

S: 2darray: Experimental spectrum
ppm_scale: 1darray: PPM scale of the spectrum
regions: dict: Generated by fit.read_vf_P2D
t_AQ: 1darray: Acquisition timescale
SFO1: float: Nucleus Larmor frequency /MHz
o1p: float: Carrier frequency /ppm
u_tol: float: Maximum allowed displacement of the chemical shift from the initial value /ppm
f_tol: float: Maximum allowed displacement of the linewidth from the initial value /ppm
vary_phase: bool: Allow the peaks to change phase
vary_b: bool: Allow the peaks to change Lorentzian/Gaussian ratio
itermax: int: Maximum number of allowed iterations
filename: str: Name of the file where the fitted values will be saved. The .fvf extension is added automatically

klassez.fit.voigt_fit_indep(S, ppm_scale, regions, t_AQ, SFO1, o1p, u_lim=1, f_lim=10, k_lim=(0, 3), ph_lim=(-180, 180), vary_phase=False, vary_b=True, itermax=10000, fit_tol=1e-08, filename='fit', method='leastsq', basl_fit='no')[source]

Performs a lineshape deconvolution fit using a Voigt model. The initial guess must be read from a .ivf file. All components are treated as independent, regardless from the value of the group attribute. The fitting procedure operates iteratively one window at the time.

Parameters:

S1darray

Experimental spectrum

ppm_scale1darray

PPM scale of the spectrum

regionsdict

Generated by klassez.fit.read_vf()

t_AQ1darray

Acquisition timescale

SFO1float

Nucleus Larmor frequency /MHz

o1pfloat

Carrier frequency /ppm

u_limfloat

Maximum allowed displacement of the chemical shift from the initial value /ppm

f_limfloat

Maximum allowed displacement of the linewidth from the initial value /ppm

k_limfloat or tuple

If tuple, minimum and maximum allowed values for k during the fit. If float, maximum displacement from the initial guess

ph_limtuple

Minimum and maximum allowed values for the phases, in degrees

vary_phasebool

Allow the peaks to change phase

vary_bbool

Allow the peaks to change Lorentzian/Gaussian ratio

itermaxint

Maximum number of allowed iterations

fit_tolfloat

Target value to be set for x_tol and f_tol

filenamestr or Path

Name of the file where the fitted values will be saved. The .fvf extension is added automatically

methodstr or list of str

Method to be used for the optimization. See lmfit for details. There is the option to run multiple optimizations in series.

basl_fitstr

How to address the baseline fit. The options are:

"no": Do not use baseline (default)
"fixed": The baseline is computed once and kept fixed during the optimization
"fit": The baseline coefficients enter as fit parameters during the nonlinear optimization
"calc": The baseline coefficients are calculated during the optimization via linear least-squares optimization

Returns:

lmfit_results: list of lmfit.Minimizer.MinimizerResult: Sequence of the fit results, ordered as the regions dictionary

See also

lmfit.Minimizer

lmfit.Minimizer.minimize()

lmfit.Minimizer.MinimizerResult

klassez.fit.write_dy(filename, diff_c, diff_f, diff_e, label, intensity, offset, header=False)[source]

Write a section in a fit report file, which shows the fitting region identifier and the parameters to feed into the DOSY model fitting.

Parameters:

filenamestr or Path: Path to the file to be written
diff_clist of float: Diffusion coefficients in m^2/s
diff_flist of float: Fractions of the various components
diff_elist of float or list of None: Fit errors. Initial guess will have None for each entry
labelstr: Region identifier for the fit
intensityfloat: Intensity factor to match the model to the experimental data
offsetfloat: Offset factor to match the model to the experimental data

Returns:

None

See also