spyrit.misc.sampling.sort_by_significance

spyrit.misc.sampling.sort_by_significance(arr: ndarray, sig: ndarray, axis: str = 'rows', inverse_permutation: bool = False, get_indices: bool = False) → ndarray[source]

Returns an array ordered by decreasing significance along the specified dimension.

The significance values are given in the \(sig\) array. The type of the output is the same as the input array \(arr\).

This function is equivalent to (but faster) Permutation_Matrix() and multiplying the input array by the permutation matrix. More specifically, here are the four possible different calls and their equivalent:

h = 64
arr = np.random.randn(h, h)
sig = np.random.randn(h)

# 1
y = sort_by_significance(arr, sig, axis='rows', inverse_permutation=False)
y = Permutation_Matrix(sig) @ arr

# 2
y = sort_by_significance(arr, sig, axis='rows', inverse_permutation=True)
y = Permutation_Matrix(sig).T @ arr

# 3
y = sort_by_significance(arr, sig, axis='cols', inverse_permutation=False)
y = arr @ Permutation_Matrix(sig)

# 4
y = sort_by_significance(arr, sig, axis='cols', inverse_permutation=True)
y = arr @ Permutation_Matrix(sig).T

Note

\(arr\) must have the same number of rows or columns as there are elements in the flattened \(sig\) array.

Args:

arr (np.ndarray or torch.tensor): Array to be ordered by rows or columns. The output’s type is the same as this parameter’s type.

sig (np.ndarray or torch.tensor): Array containing the significance values.

axis (str, optional): Axis along which to order the array. Must be either ‘rows’ or ‘cols’. Defaults to ‘rows’.

inverse_permutation (bool, optional): If True, the permutation matrix is transposed before being used. This is equivalent to using the inverse permutation matrix. Defaults to False.

get_indices (bool, optional): If True, the function returns the indices of the significance values in decreasing order. Defaults to False.

Shape:

  • arr: \((*, r, c)\) or \((c)\), where \((*)\) is any number of

dimensions, and \(r\) and \(c\) are the number of rows and columns respectively.

  • sig: \((r)\) if axis is ‘rows’ or \((c)\) if axis is ‘cols’ (or any shape

that has the same number of elements). Not used if arr is 1D.

  • Output: \((*, r, c)\) or \((c)\)

Returns:

Tuple of np.ndarray:

  • Array \(arr\) ordered by decreasing significance \(sig\)

    along its rows or columns.

  • Indices \(indices\) of the significance values in decreasing

    order. This is useful if you want to reorder other arrays in the same way.