v0.13.0

Release v0.13.0 - April 2021

New features

• DeerLab is now distributed via the Anaconda repository and can be installed with the conda package manager (#12, #157). The installation instructions have been expanded to describe the Anaconda installation (#155).
• DeerLab now supports Python 3.9.
• The function fitsignal has been re-named to fitmodel for correctness and consistency with other functions (#102).
• Added new experiment models for RIDME on systems with one to seven harmonic pathways (S=1/2 to S=7/2) to include all higher harmonics (overtones) (#79).
• Bootstrapping is now embedded into fitmodel to automatically bootstrap all output quantities without the need to write additional script lines (#55). In fitmodel a new option uq allows to switch between covariance or bootstrapping uncertainty quantification (#88).
• The function fitmodel now returns Vmod and Vunmod, the modulated and unmodulated contributionsto the fitted dipolar signal, respectively, along their uncertainties as additional outputs (#78).
• Implemented several initialization strategies in fitmultimodel for multi-model components (#67). Three different new strategies 'spread', 'split' and 'merge' will initialize the parameter values of the N-component fit based on the results of the N-1/N+1 component fit to improve quality of results and speed.
• Added contribution guidelines to the documentation and automated list of DeerLab contributors.
• The function snlls now accepts additional custom penalties to include in the optimization (#76, #108).
• All fit functions now return the fit of the data along its uncertainty automatically as part of the FitResult object (#130, #134).
• Implemented a new method UQResult.join() to merge multiple uncertainty quantification objects (#154). This permits error propagation from multiple uncertainty sources to a common function.

Overall changes

• The performance of all fit functions has been considerably accelerated by removing call overheads in built-in DeerLab models (#100, #101, #143).
• Improved robustness of the installation from PyPI (#65):
  • The installer no longer assumes the alias pip to be setup on the system.
  • The installation will now handle cases when system-wide privileges are not available (#52).
  • Improved robustness of the installation in Windows systems to avoid missing DLL errors (#64).
  • The installer will now get the latest Numpy/Scipy releases in Windows systems available at the Gohlke repository.
• Adapted piece of code leading to a VisibleDeprecationWarning visible during execution of certain DeerLab functions.
• Improved interface of built-in plots in FitResult.plot(). The method now returns a Matplotlib figure object (matplotlib.figure.Figure) instead of an axes object (matplotlib.axes._subplots.AxesSubplot) which can be modified more freely to adjust graphical elements (#85). The method now takes an optional keyword FitResult.plot(show=True\False) to enable/disable rendering of the graphics upon calling the method (#87).
• The fit objective values returned in FitResult.cost are now correct (previous versions had an erroneous 1/2 factor) (#80). The value is now returned as a scalar value instead of a single-element list (#81).
• Removed the re-normalization conventions K(t=0,r)=1 and B(t=0)=1 and associated options renormalize and renormpaths in the dipolarkernel and dipolarbackground functions (#99) to avoid identifiability issues between dipolar pathway amplitudes and signal scales during fitting (#76).
• The fit convergence criteria tol (objective function tolerance) and maxiter (iteration limit) are now exposed as keyword argument in all fit functions (#111, #112).
• Multiple improvements and corrections to the documentation (#95, #96, #104, #106, #107, #115, #122)
• Corrections in the metadata of multiple dd_models. The key Parameters of some models contained the wrong names.
• The metadata of the built-in models is now accessible and manipulable via function attributes (e.g. dd_gauss.parameters) rather than trought a returned dictionary (e.g. dd_gauss()['Parameters']) (#143).
• The keyword argument to request uncertainty quantification has been unified across all fitting functions. It is now uq (#120).
• The UncertQuant class has been renamed into UQResult (#123).
• Uncertainty quantification is now tested numerically against an external package (lmfit) to ensue quality and accuracy (#121).
• Expanded the collection of examples in the documentation, and improved existing ones (#144, #148, #153).

Specific changes

• deerload:
  • Fixed behaviour of the function when loading certain 2D-datasets in the BES3T format (#82, #83).
  • In 2D-datasets, the abscissas are now returned as a list of abscissas instead of a single 2D-matrix (#83)).
• fitmodel:
  • Corrected the scaling behaviour of all outputs related to components of the dipolar signal to match the scaling of the original experimental data (#78).
  • The built-in plot method FitResult.plot() now plots the unmodulated component fit as well with its uncertainty (#78).
  • When plotting bootstrapped results with FitResult.plot(), the fit is substituted with the median of the bootstrapped distribution (#148).
  • Extended information included in the verbose summary (#78).
  • Simplified the interface for defining initial values and boundaries of parameters in fitsignal (#71). Now instead of defining, e.g., fitsignal(..., lb = [[],[50],[0.2, 0.5]]) one can define the individual vales/boundaries fitsignal(..., bg_lb = 50, ex_lb = [0.2,0.5]) by using the new keywords.
  • Removed the keyword argument uqanalysis=True/False. The uncertainty quantification can now be disabled via the new keyword uq=None (#98).
  • Corrected the behaviour of built-in start values when manually specifying boundaries (#73). If the built-in start values are outside of the user-specified boundaries the program will now automatically set the start values in the middle of the boundaries to avoid errors (#72).
  • Implemented the constraint Lam0+sum(lam)<=1 to ensure the structural-identifiability of Lam0 and V0 during SNLLS optimization of experiment models with more than one modulated dipolar pathway (i.e. does not affect ex_4pdeer) (#76, #108).
  • The function now accepts any sequence input (lists, arrays, tuples, etc.) instead of just lists (#152).
  • Removed the optional keyword argument regtype (#137).
  • Fixed a bug in the scaling of the distance distribution uncertainty quantification (#148).
• fitregmodel:
  • Corrected the behaviour of the uncertainty quantification when disabling the non-negativity constraint (#121).
• fitparamodel:
  • Made par0 a positional argument instead of an optional keyword (#70). to avoid errors when not defined (#69).
  • Keyword argument rescale has been renamed to fitscale (#128, #129).
• snlls:
  • Corrected bug that was leading to the smoothness penalty being accounted for twice in the least-squares residual during optimization (#103).
  • Now returns the uncertainty quantification of linear and nonlinear parts as separate objects nonlinUncert and linUncert (#108).
  • Improved the covariance-based uncertainty analysis by including correlations between linear and non-linear parameters (#108).
  • Improved the behavior of signal scale determination (#108).
  • Enabled prescaling of the data to avoid scaling issues during uncertainty quantification (#132, #133).
  • Corrected the behaviour of the uncertainty quantification when disabling the regularization penalty (#121).
• diststats:
  • Now compatible with non-uniformly defined distance distributions (#92, #94).
  • Added internal validation step to avoid non-sensical results when confounding the syntax (#91).
• dipolarkernel:
  • Now allows defining pathways without unmodulated components.
  • All optional keyword arguments can only be passed as named and not positional arguments (#138).
  • The keyword pathways now only takes lists of pathways and not modulation depth parameters. A new separate keyword mod takes the modulation depth parameter for the simplified 4-pulse DEER kernel (#118, #138).
  • Renmaed the background argument keyword B into bg (#138).
• regparamrange:
  • Implemented new CSD algorithm to avoid LAPACK library crashes encountered when using multiple DeerLab functions calling regparamrange internally (#68).
• correctphase:
  • Implement new keyword phase to select the criterion for optimizing the phase for correction (#114, #131).
  • Deprecated imaginary offset fitting (#131).
  • Deprecated manual phase correction. Manual correction can be done by the user and is now described in the beginner's guide (#131).