Utility Functions

dive.utils.FWHM2sigma(FWHM: float) → float

Converts full width at half maximum (FWHM) to standard deviation.

Parameters:

FWHM (float) – The full width at half maximum of a Gaussian.

Returns:

sigma – The standard deviation of the Gaussian.

Return type:

float

dive.utils.addnoise(V: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], sig: float) → _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]

Adds Gaussian noise with standard deviation sig to signal.

Parameters:

  • V (ArrayLike) – The signal to add noise to.

  • sig (float) – The standard deviation of the noise to add.

Returns:

Vnoisy

Return type:

ArrayLike

See also

np.random.normal

dive.utils.dipolarkernel(t: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], r: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → ndarray

Calculates the dipolar kernel matrix.

Generates given a time vector t in microseconds and a distance vector r in nanometers.

Parameters:

  • t (ArrayLike) – The time vector, in microseconds.

  • r (ArrayLike) – The distance vector, in nanometers.

Returns:

K – The dipolar kernel matrix.

Return type:

np.ndarray

dive.utils.fnnls(AtA: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], Atb: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], tol: float | None = None, maxiter: int | None = None, verbose: bool = False)

Fast non-negative least-squares algorithm.

x = fnnls(AtA,Atb) solves the problem min ||b - Ax|| if AtA = A’*A and Atb = A’*b. A default tolerance of TOL = MAX(SIZE(AtA)) * NORM(AtA,1) * EPS is used for deciding when elements of x are less than zero. This can be overridden with x = fnnls(AtA,Atb,TOL).

[x,w] = fnnls(AtA,Atb) also returns dual vector w where w(i) < 0 where x(i) = 0 and w(i) = 0 where x(i) > 0.

Parameters:

  • AtA (ArrayLike) – The matrices/vectors to use in the FNNLS algorithm.

  • Atb (ArrayLike) – The matrices/vectors to use in the FNNLS algorithm.

  • tol (float, optional) – The tolerance. If not provided, it will be automatically calculated.

  • maxiter (int, optional) – The maximum number of iterations. If not provided, it will be automatically calculated.

  • verbose (bool, default=False) – Whether to print the status of solution-finding.

Returns:

x – The solution to the optimization problem.

Return type:

np.ndarray

References

dive.utils.get_rhats(trace: InferenceData) → Series

Gets the r-hat statistics for each variable in a trace.

R-hat is the ratio of interchain to intrachain variance and is a good indicator of convergence. When R-hat is close to 1, the chains are converged.

Parameters:

trace (az.InferenceData) – The trace to be analyzed.

Returns:

rhats – A pd.Series object containing the variable names and their r-hat values.

Return type:

pd.Series

See also

prune_chains, az.summary

dive.utils.prune_chains(trace: InferenceData, max_remove: int | None = None, max_allowed: float = 1.05, min_change: float = 0, return_chain_nums: bool = False, depth: int = 0, chain_nums: list[int] | None = None) → InferenceData | list[int]

Prunes chains from a trace to attain convergence.

The algorithm drops chains one by one and iteratively removes the chain that reduces maximum r-hat the most when dropped. This process continues until the maximum r-hat is less than max_allowed. This only removes up to max_remove of the chains, and only if removing the chain reduces maximum r-hat by more than min_change.

Returns the trace with clean chains, unless return_chain_nums is set to True.

Parameters:

  • trace (az.InferenceData) – The trace to be pruned.

  • max_remove (int, optional) – The maximum number of chains to be removed. Defaults to half the number of chains in the trace.

  • max_allowed (float, default=1.05) – The maximum allowable value of r-hat. When reached, the function will stop pruning.

  • min_change (float, default=0) – The minimum reduction in r-hat for a chain to be pruned.

  • return_chain_nums (bool, default=False) – Whether or not to return the numbers of the chains to be kept, instead of the pruned trace.

  • depth (int, default=0) – Internal parameter to keep track of recursion.

  • chain_nums (list of int, optional) – Internal parameter to keep track of remaining chains.

Returns:

to_return – Either the pruned trace or the list of chain numbers to keep, depending on the value of return_chain_nums.

Return type:

az.InferenceData or list of int

See also

get_rhats, az.sel

dive.utils.sigma2FWHM(sigma) → float

Converts standard deviation to full width at half maximum (FWHM)

Parameters:

sigma (float) – The standard deviation of a Gaussian

Returns:

FWHM – The full width at half maximum of the Gaussian.

Return type:

float