------------------------------------------
- |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`).