psiz.utils

Module of utilities.

class psiz.utils.ProgressBarRe(total, prefix='', decimals=1, length=100, fill='█')

Display a progress bar in terminal.

update(iteration): Update progress bar to display current iteration.

psiz.utils.affine_mvn(loc, cov, r=None, t=None)

Affine transformation of multivariate normal.

Performs the following operations:: loc_affine = loc @ r + t cov_affine = r^T @ cov @ r

Parameters

loc – Location parameters. shape=(n_dim,) or (1, n_dim)
cov – Covariance. shape=(n_dim, n_dim)
r – Rotation matrix. shape=(n_dim, n_dim)
t – Transformation vector. shape=(n_dim,) or (1, n_dim)

Returns

Rotated location parameters. cov_affine: Rotated covariance.

Return type

loc_affine

Notes

1) np.matmul will prepend (postpend) singleton dimensions if the first (second) argument is a 1D array. This function therefore allows for 1D or 2D loc input. The translation vector t can be 1D or 2D since the additional operation will broadcast it appropriately. 2) This implementation hits the means with a rotation matrix on the RHS, allowing the rows to correspond to an instance and columns to correspond to dimensionality. The more conventional pattern has rows corresponding to dimensionality, in which case the code would be implemented as:

` loc_affine = np.matmul(r, loc) + t cov_affine = np.matmul(r, np.matmul(cov, np.transpose(r))) `

psiz.utils.choice_wo_replace(a, size, p, rng=None)

Fast sampling without replacement.

For each sample, draw elements without replacement. Across samples there may be repetitions.

Parameters

a – An array indicating the eligible elements.
size – A 2-tuple indicating the number of independent samples and the number of draws (without replacement) for each sample. The tuple is ordered such that shape=(n_sample, sample_size).
p – An array indicating the probabilites associated with drawing a particular element. User provided probabilities are already assumed to sum to one. Probability p[i] indicates the probability of drawing index a[i].
rng (optional) – A numpy.random.Generator object.

Returns

A 2D array containing the drawn elements.: shape=(n_sample, sample_size)

Return type

result

See: https://medium.com/ibm-watson/: incredibly-fast-random-sampling-in-python-baf154bd836a

psiz.utils.expand_dim_repeat(x, n_repeat, axis=1): Repeat Tensor along a newly inserted axis.

psiz.utils.m_prefer_n(m_option, n_select)

Return the possible outcomes of an m-prefer-n event.

Given m options, select the n options that are most preferred and rank the selected options.

Parameters

m_option – Integer indicating the number of options.
n_select – Integer indicating the number of most preferred options. Must be less than or equal to m_options.

Returns

A 2D array indicating all possible outcomes where the values indicate indices of the options. Each row corresponds to one outcome. Note the indices refer to the options only and does not include an index for a query or prompt. Also note that the unpermuted index is returned first.

psiz.utils.pairwise_indices(indices, elements='upper', subsample=None, rng=None)

Generate an array of pairwise indices.

Parameters

indices – An scalar integer or an array-like of integers indicating indices. If a scalar, indices are np.arange(n).
elements (optional) – Determines which combinations in the pairwise matrix will be used. Can be one of ‘all’, ‘upper’, ‘lower’, or ‘off’.
subsample (optional) – A float ]0,1] indicating the proportion of all pairs that should be retained. By default all pairs are retained.
rng (optional) – A numpy.random.Generator object. Controls which pairs are subsampled. Only used if subsample is not None.

Returns

An array of pairwise indices.: shape=(n_sample, 2)

psiz.utils.procrustes_rotation(z0, z1, scale=True)

Perform Procrustes superimposition.

Align two sets of coordinates (z0 and z1) by finding the optimal rotation matrix r that rotates z0 into z1. Both z0 and z1 are centered first.

z0_rot = z0 @ r

Parameters

z0 – The first set of points. shape = (n_point, n_dim)
z1 – The second set of points. The data matrices z0 and z1 must have the same shape. shape = (n_point, n_dim)
n_restart (optional) – A scalar indicating the number of restarts for the optimization routine.
scale (optional) – Boolean indicating if scaling is permitted in the affine transformation. By default scaling is allowed, generating a full Procrustes superimposition. Set to false to yield a partial Procrustes superimposition.

Returns

A rotation matrix that operates on the centered data.: shape=(n_dim, n_dim)

Return type

r

psiz.utils.random_combinations(a, k, n_sample, p=None, replace=True, rng=None)

Sample from the possible k-combinations of a.

Parameters

a – The elements used to create combinations. shape=(n_element,)
k – Integer indicating the number of elements in each k-combination.
n_sample – Integer indicating the number of unique combinations to sample. If replace=False, then there is a limit on the number of unique samples; if n_sample is greater than number of unique k-combinations, an exhaustive list of all k-combinations is returned (which will be less than the requested number of samples).
p (optional) – The sampling probability associated with each element in a. If not given, all elements are given equal probability. shape=(n_element,)
replace (optional) – Boolean indicating if the sampling is with or without replacement. The default is True, meaning that a particular k-combination can be sampled multiple times. If unique samples are desired, set replace=False.
rng (optional) – A NumPy random number generator that can be used to control stochasticity.

Returns

A set of k-combinations. If replace=False, the: returned array is sorted both within a sample and across samples. shape=(n_sample, k)

Return type

samples

psiz.utils.rotation_matrix(theta)

Return 2D rotation matrix.

Parameters: theta – Scalar value indicating radians of rotation.

psiz.utils.sort_based_mask(a, n_retain, **kwargs)

Mask 1D or 2D array of values based on ascending sorted order.

For each row, mask elements based on ascending sorted order. If elements should be sorted in descending order, pass in -a.

Parameters

a – A 1D or 2D matrix.
n_retain – The number of elements to retain (keep unmasked) for each row.
kwargs – Key-word arguments to pass to np.argsort.

Returns: mask: A Boolean mask.

psiz.utils.standard_split(obs, shuffle=False, seed=None)

Creata a standard 80-10-10 split of the observations.

Parameters

obs – A set of observations.
shuffle (optional) – Boolean indicating if the data should be shuffled before splitting.
seed – Integer to seed randomness.

Returns

A train set (80%). obs_val: A validation set (10%). obs_test: A test set (10%).

Return type

obs_train