# tensiometer.utilities¶

This file contains some utilities that are used in the tensiometer package.

tensiometer.utilities.KL_decomposition(matrix_a, matrix_b)[source]

Computes the Karhunen–Loeve (KL) decomposition of the matrix A and B.

Notice that B has to be real, symmetric and positive.

The algorithm is taken from this link. The algorithm is NOT optimized for speed but for precision.

Parameters: matrix_a – the first matrix. matrix_b – the second matrix. the KL eigenvalues and the KL eigenvectors.
tensiometer.utilities.PDM_to_vector(pdm)[source]

Transforms a positive definite matrix of dimension $$d \times d$$ into an unconstrained vector of dimension $$d(d+1)/2$$. This does not use the Cholesky decomposition since we need guarantee of strictly positive definiteness.

The absolute values of the elements with indexes of the returned vector that satisfy:

np.tril_indices(d, 0) == np.tril_indices(d, 0)


are the eigenvalues of the matrix. The sign of these elements define the orientation of the eigenvectors.

Note that this is not strictly the inverse of tensiometer.utilities.vector_to_PDM() since there are a number of discrete symmetries in the definition of the eigenvectors that we ignore since they are irrelevant for the sake of representing the matrix.

Parameters: pdm – the input positive definite matrix. output vector representation. https://arxiv.org/abs/1906.00587
tensiometer.utilities.QR_inverse(matrix)[source]

Invert a matrix with the QR decomposition. This is much slower than standard inversion but has better accuracy for matrices with higher condition number.

Parameters: matrix – the input matrix. the inverse of the matrix.
tensiometer.utilities.bernoulli_thin(chain, temperature=1, num_repeats=1)[source]

Function that thins a chain with a Bernoulli process.

Parameters: chain – MCSamples the input chain. temperature – temperature of the Bernoulli process. If T=1 then this produces a unit weight chain. num_repeats – number of repetitions of the Bernoulli process. a MCSamples chain with the reweighted chain.
tensiometer.utilities.clopper_pearson_binomial_trial(k, n, alpha=0.32)[source]

http://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval alpha confidence intervals for a binomial distribution of k expected successes on n trials.

Parameters: k – number of success. n – total number of trials. alpha – (optional) confidence level. lower and upper bound.
tensiometer.utilities.from_chi2_to_sigma(val, dofs, exact_threshold=6)[source]

Computes the effective number of standard deviations for a chi squared variable. This matches the probability computed from the chi squared variable to the number of standard deviations that an event with the same probability would have had in a Gaussian distribution as in Eq. (G1) of (Raveri and Hu 18).

$n_{\sigma}^{\rm eff}(x, {\rm dofs}) \equiv \sqrt{2} {\rm Erf}^{-1}({\rm CDF}(\chi^2_{\rm dofs}(x)))$

For very high statistical significant events this function switches from the direct formula to an accurate asyntotic expansion.

Parameters: val – value of the chi2 variable dofs – number of degrees of freedom of the chi2 variable exact_threshold – (default 6) threshold of value/dofs to switch to the asyntotic formula. the effective number of standard deviations.
tensiometer.utilities.from_confidence_to_sigma(P)[source]

Transforms a probability to effective number of sigmas. This matches the input probability with the number of standard deviations that an event with the same probability would have had in a Gaussian distribution as in Eq. (G1) of (Raveri and Hu 18).

$n_{\sigma}^{\rm eff}(P) \equiv \sqrt{2} {\rm Erf}^{-1}(P)$
Parameters: P – the input probability. the effective number of standard deviations.
tensiometer.utilities.from_sigma_to_confidence(nsigma)[source]

Gives the probability of an event at a given number of standard deviations in a Gaussian distribution.

Parameters: nsigma – the input number of standard deviations. the probability to exceed the number of standard deviations.
tensiometer.utilities.get_separate_mcsamples(chain)[source]

Function that returns separate MCSamples for each sampler chain.

Parameters: chain – MCSamples the input chain. list of MCSamples with the separate chains.
tensiometer.utilities.is_outlier(points, thresh=3.5)[source]

Returns a boolean array with True if points are outliers and False otherwise.

Parameters: points – An num-observations by num-dimensions array of observations thresh – The modified z-score to use as a threshold. Observations with a modified z-score (based on the median absolute deviation) greater than this value will be classified as outliers. A num-observations-length boolean array. Boris Iglewicz and David Hoaglin (1993), “Volume 16: How to Detect and Handle Outliers”, The ASQC Basic References in Quality Control: Statistical Techniques, Edward F. Mykytka, Ph.D., Editor.
tensiometer.utilities.make_list(elements)[source]

Checks if elements is a list. If yes returns elements without modifying it. If not creates and return a list with elements inside.

Parameters: elements – an element or a list of elements. a list containing elements.
tensiometer.utilities.min_samples_for_tension(nsigma, sigma_err)[source]

Computes the minimum number of uncorrelated samples that are needed to quantify a tension of a given significance with a given error through binomial trials.

This function works by inverting the Clopper Pearson binomial trial and likely delivers an underestimate of the points needed.

Parameters: nsigma – number of effective sigmas of the given tension. sigma_err – the desired error on the determination of nsigma. minimum number of samples.
tensiometer.utilities.random_samples_reshuffle(chain)[source]

Performs a coherent random reshuffle of the samples.

Parameters: chain – MCSamples the input chain. a MCSamples chain with the reshuffled chain.
tensiometer.utilities.vector_to_PDM(vec)[source]

Transforms an unconstrained vector of dimension $$d(d+1)/2$$ into a positive definite matrix of dimension $$d \times d$$. In the input vector the eigenvalues are in the positions where

The absolute values of the elements with indexes of the input vector that satisfy:

np.tril_indices(d, 0) == np.tril_indices(d, 0)


are the eigenvalues of the matrix. The sign of these elements define the orientation of the eigenvectors.

The purpose of this function is to allow optimization over the space of positive definite matrices that is either unconstrained or has constraints on the condition number of the matrix.

Parameters: pdm – the input vector. output positive definite matrix. https://arxiv.org/abs/1906.00587
tensiometer.utilities.whiten_samples(samples, weights)[source]

Rescales samples by the square root of their inverse covariance. The resulting samples have identity covariance. This amounts to a change of coordinates so the physical meaning of different coordinates is changed.

Parameters: samples – the input samples. weights – the input weights of the samples. whitened samples with identity covariance.