deerlab.diststats

diststats(r, P, Puq=None, verbose=False, threshold=None)[source]

Computes statistical quantities for the location, spread, and shape of a distance distribution, with or without their corresponding uncertainties.

This function calculates various statistical quantities of a distance distribution, such as its mean, median, mode, etc. It can also calculate the uncertainty of these quantities using moment-based or bootstrapped uncertainty quantification, if provided. The function allows to specify whether to print a summary of the results and the peak detection threshold for the calculation of the mode of the distribution.

Parameters:
rarray_like

Distance axis, in nm. The distances in the distribution.

Parray_like

Distance distribution, does not have to be normalized. The probability or relative frequency of the distances in r.

Puqdeerlab.UQResult, optional

Uncertainty quantification of the distance distribution. If Puq is not given, a single output is returned without any uncertainty estimation. If given, two outputs are returned containing the uncertainty estimation.

verboseboolean, optional

Print a summary of all statistical quantities (and their uncertainties if calculated).

thresholdfloat, optional

Peak detection threshold for the calculation of modes of a distribution. The default is max(P)/10.

Returns:
estimatorsdict

Dictionary of shape, location, and spread descriptors of the input distance distribution:

General parameters

  • 'rmin' - Minimum distance in the distribution range, in nm

  • 'rmax' - Maximum distance in the distribution range, in nm

  • 'int' - Integral of the distance distribution

Location parameters

  • 'mean' or 'moment1' - Mean distance, in nm (see more)

  • 'median' - Median distance, in nm (see more)

  • 'iqm' - Interquartile mean (IQM) distance, in nm (see more)

  • 'mode' - First modal distance, in nm (see more)

  • 'modes' - All modal distances, in nm (see more)

Spread parameters

  • 'iqr' - Interquartile range, in nm (see more)

  • 'mad' - Mean absolute deviation (MAD), in nm (see more)

  • 'std' - Standard deviation, in nm (see more)

  • 'var' or 'moment2' - Variance, in nm² (see more)

  • 'entropy' - Shannon entropy, in nat (see more)

Shape parameters

  • 'modality' - Modality (number of modes)

  • 'skewness' or 'moment3' - Skewness (see more)

  • 'kurtosis' - Excess kurtosis (see more)

  • 'moment4' - 4th moment (kurtosis) (see more)

uqdict of deerlab.UQResult

Dictionary of the parameters moment-based uncertainty quantification. See above for the dictionary keys. Only calculated if Puq is provided.

Notes

For the 'mode', 'modes' and 'modality' parameters, moment-based uncertainties are not available. Uncertainties can, however, be calculated via bootsrapping of these quantities, e.g.

def analyze_rmode(V):
    fit = dl.fitmodel(V,t,r)
    rmode = dl.diststats(fit.P,r)[0]['mode']
    return rmode
# Bootstrap analysis of distance mode
rmode_uq = dl.bootstrap_analysis(V,Vfit,analyze_rmode)