Release v1.0.0

Release v1.0.0 - December 2022

• |feature| Introduces multi-spin dipolar EPR spectroscopy models (:pr:385).

  • Implements multi-spin models in dipolarmodel by taking into account all possible two-spin an three-spin interaction pathways in a multi-pin system. Add a new optional argument spins to specify the number of spins in a molecule. From that number and the npathways or experiment arguments, dipolarmodel automatically constructs the full set of multi-spin pathways (including permutations) within the pair-wise pathway factorization approximation. Adds a new keyword argument triangles, required for spins>3 to specify triads of indices of interspin vectors that are connected forming a triangle (must be specified by the user since it defines the geometry of the spins system).
  • Adds a new argument specperm to dipolarmodel, to enable/disable the assumption of spectral permutability of the multi-spin system. This option allows to account for multi-spin system with chemically or spectrally different spin-1/2 centers.
  • Adds and changes the optional argument nKnots in dipolarkernel and dipolarmodel to gridsize. Changing the specification from knots to grid points allows a finer control of the computation costs due to the highly non-linear scaling of grid points with number of knots in a spherical grid.
  • Implements a new utility function sophegrid to generate SOPHE grids based on a port of the Easyspin sphgrid function.
  • The multi-spin models in dipolarmodel have at the moment a hard-coded unimodal normal multi-variate distance distribution at its core. This could be adapted in the future to be modular to specify multi-modal distributions and other multi-variate basis functions.

• |feature| Implements different parametrization strategies for dipolar EPR models (:pr:409). Implements a new optional argument parametrization for dipolarmodel, which specifies the parametrization strategy of the dipolar pathway refocusing times. Can be one of the following:

  • 'reftimes' - Each refocusing time is represented individually as a parameter. The current behavior.
  • ``'delays'``` - The pulse delays are introduced as parameters from which the refocusing times are computed
  • 'shift' - A time shift is introduced as a parameter to represent the variability of the refocusing times from their theoretical values.

• |feature| Expands the toolset for asserting the goodness-of-fit of model estimates robustly (:pr:388).

  • Adds new option gof to FitResults.plot() method to add plots to aid goodness-of-fit assessment. Besides the plot of the data and the model fit, now adds a plot of the residuals with its mean and noise level estimates shown as lines, a plot of the normalized residual histogram compared to the standard normal distribution, and a plot of the autocorrelation in the data along the confidence region expected from white noise.
  • Adds a new quantity, Residuals autocorr. to the results summary. The value of this quantity is computed as abs(2 - dDW), where dDW is the Durbin–Watson statistic. It allows a quick assessment of the autocorrelation in the fit residuals. This quantity is also returned by the fit function as FitResults.stats['autocorr']
  • Remove the AIC quantity specified for each dataset from the fit's summary.
  • Add a new automatic system that colorizes the chi2red and Residuals autocorr. values depending on their severity, indicating a wrong estimate. Yellow coloring alerts the user of potential failures and red of confidently wrong estimates.

• |efficiency| |fix| Implements a new NNLS solver function qpnnls that uses the Goldfarb/Idnani dual algorithm implemented in the quadprog package (:pr:390). The resulting NNLS solver is more efficient than the current implementation with cvxopt without sacrificing any accuracy. Since NNLS problem-solving is the bottleneck of most applications of DeerLab, it results in a significant improvement in speed when analyzing any models with linear parameters. Since it substitutes cvxopt as the default solver engine, it removes the hard dependency on the cvxopt package and its issues related to the Apple M1 chip (:issue:407).

• |efficiency| Implements a new, more efficient evaluation of multi-pathway dipolar models based to greatly enhance the performance of dipolar EPR spectroscopy analyses (:pr:393). Combined with the new NNLS solver, the analysis time of, e.g., 4-pulse and 5-pulse DEER multi-pathway models, has been reduced on average about 70-80%.

• |enhancement| Improves the interface and definition of dipolar pathways in dipolarmodel (:pr:396).

  • Labels the parameters of the different dipolar pathways included in dipolarmodel via the experiment argument based on the pathway label numbers rather than numerically by order of specification.
  • Harmonizes the pathway ordering of the ex_rev5pdeer and ex_fwd_5pdeer models according to published literature.
  • Adds new figures to the ex_ model functions to show the table of dipolar pathways along a schematic illustration of their intramolecular contributions. Improved the docstrings of the ex_ models in general.

• |enhancement| |fix| Improves and expands the documentation (:pr:397, :pr:408).

  • Adds multiple new examples, fixes errors in existing ones.
  • Fixes several graphical bugs in the website.
  • Thoroughly documents all public and private functions in the code.
  • Adds release instructions for maintainers.
  • Adds a Publications page to the documentation linking to all literature for concepts introduced by DeerLab.

• |api| Removes the subpackage deerlab.utils and makes its functions part of the main package for simpler maintenance (:pr:408). Removes multiple unused private functions.

.. rubric:: fit

• |enhancement| The function now returns a full uncertainty quantification for the normalization factor of any model parameter with a normalization condition (:pr:372).
• |efficiency| |api| Removes the automatic computation of the modelUncert output containing the propagated uncertainty estimate of the model's response (:pr:401). This significantly speeds up the runtime of the function by disabling the automatic propagation of uncertainty to the model's response which could take from several seconds to several minutes in complex models (:issue:391).

.. rubric:: dipolarkernel

• |feature| Implements multi-spin dipolar pathways up to three-spin interactions (:pr:385). The function takes now a list of distance vectors [r1,r2,...,rQ] for multi-spin kernels.
• |feature| Expands the function to be able to account for arbitrary experimental time coordinates (:pr:385). Now a list of time vectors [t1,t2,...,tD] can be specified to construct a D-dimensional dipolar kernel.
• |enhancement| : Refactors most code in the function (:pr:385). THe code should now be more logically ordered using mathematical symbols for clearer equations.
• |api| Introduces a new and clearer syntax for defining dipolar pathways (:pr:385). Now, instead of specifying a list of pathways, where each pathway is a list of values (being the amplitude, refocusing time, and harmonic in that order), now pathways are specified as a list of dictionaries, e.g. pathways = [{'amp':0.5}, 'reftime':0, 'harmonic':1].
• |feature| |efficiency| Adds a new optional argument tinterp to construct a dipolar kernel for a pathway and interpolate other pathways from that one (:pr:393).

.. rubric:: dipolarbackground

• |feature| Implements multi-spin dipolar pathways up to three-spin interactions (:pr:385).
• |feature| Expands the function to be able to account for arbitrary experimental time coordinates (:pr:385). Now a list of time vectors [t1,t2,...,tD] can be specified to construct a D-dimensional dipolar background function.
• |api| Introduces the same new syntax for defining dipolar pathways as in dipolarkernel (:pr:385).

.. rubric:: correctphase

• Adds a new optional argument offset to enable a numerical optimization of the phase while accounting for a non-zero imaginary component offset (:issue:392, :pr:395).

.. rubric:: snlls

• Adds an optional argument modeluq to enable /disable the model uncertainty propagation (:pr:401).