aspire.utils package

Submodules

aspire.utils.bot_align module

This code is an ASPIRE port of Ruiyi Yang’s Bayesian Optimal Transport Alignment.

https://github.com/RuiyiYang/BOTalign

https://arxiv.org/pdf/2305.12310.pdf

aspire.utils.bot_align.align_BO(vol_ref, vol_given, loss_type='wemd', loss_params=None, downsampled_size=32, refinement_downsampled_size=32, max_iters=200, refine=True, tau=0.001, surrogate_max_iter=500, surrogate_min_grad=0.1, surrogate_min_step=0.1, verbosity=0, dtype=None)

This function returns a rotation matrix R that best aligns vol_ref with the rotated version of vol_given.

Parameters:

  • vol_ref – The reference Volume

  • vol_given – The Volume to be aligned

  • loss_type – ‘wemd’ or ‘euclidean’. Default ‘wemd’. If the heterogeneity between vol_ref and vol_given is high, ‘euclidean’ is recommended.

  • loss_params – Optional dictionary for overriding parameters in aspire.utils.bot_align.loss_types. Defaults to empty dictionary.

  • downsampled_size – Downsampling (pixels). Integer, defaults to 32. If alignment fails try larger values.

  • refinement_downsampled_size – Downsampling (pixels) used with refinement. Integer, defaults to 32.

  • max_iters – Maximum iterations. Integer, defaults 200. If alignment fails try larger values.

  • refine – Whether to perform refinement. Boolean, defaults True.

  • tau – Regularization parameter for surrogate problems. Numeric, defaults 1e-3.

  • surrogate_max_iter – Stopping criterion for surrogate problems–maximum iterations. Interger, defaults 500.

  • surrogate_min_grad – Stopping criterion for surrogate problems–minimum gradient norm. Numeric, defaults 0.1.

  • surrogate_min_step – Stopping criterion for surrogate problems–minimum step size. Numeric, defaults 0.1.

  • verbosity – Surrogate problem optimization detail level. integer, defaults 0 (silent). 2 is most verbose.

  • dtype – Numeric dtype to perform computations with. Default None infers dtype from vol_ref.

Returns:

Rotation matrix R_init (without refinement) or (R_init, R_est) (with refinement).

aspire.utils.cell module

class aspire.utils.cell.Cell2D(rows, cols, dtype=<class 'numpy.float32'>)

Bases: object

Define a base class of Cell to perform similar cell functions in MATLAB.

mat2cell(mat, rows, cols)

aspire.utils.coor_trans module

General purpose math functions, mostly geometric in nature.

aspire.utils.coor_trans.cart2pol(x, y)

Convert Cartesian to Polar Coordinates. All input arguments must be the same shape.

Parameters:

  • x – x-coordinate in Cartesian space

  • y – y-coordinate in Cartesian space

Returns:

A 2-tuple of values: theta: angular coordinate/azimuth r: radial distance from origin

aspire.utils.coor_trans.cart2sph(x, y, z)

Transform cartesian coordinates to spherical. All input arguments must be the same shape.

Parameters:

  • x – X-values of input co-ordinates.

  • y – Y-values of input co-ordinates.

  • z – Z-values of input co-ordinates.

Returns:

A 3-tuple of values, all of the same shape as the inputs. (<azimuth>, <elevation>, <radius>) azimuth and elevation are returned in radians.

This function is equivalent to MATLAB’s cart2sph function.

aspire.utils.coor_trans.common_line_from_rots(r1, r2, ell)

Compute the common line induced by rotation matrices r1 and r2.

Parameters:

  • r1 – The first rotation matrix of 3-by-3 array.

  • r2 – The second rotation matrix of 3-by-3 array.

  • ell – The total number of common lines.

Returns:

The common line indices for both first and second rotations.

aspire.utils.coor_trans.crop_pad_2d(im, size, fill_value=0)

Crop/pads im according to size.

Padding will use fill_value. Return’s host/GPU array based on im.

Parameters:

  • im – A >=2-dimensional numpy array

  • size – Integer size of cropped/padded output

Returns:

Array of shape (…, size, size)

aspire.utils.coor_trans.crop_pad_3d(vol, size, fill_value=0)

Crop/pads vol according to size.

Padding will use fill_value. Return’s host/GPU array based on vol.

Parameters:

  • vol – A >=3-dimensional numpy array

  • size – Integer size of cropped/padded output

Returns:

Array of shape (…, size, size, size)

aspire.utils.coor_trans.get_aligned_rotations(rots, Q_mat, flag)

Get aligned rotation matrices to reference ones.

Calculated aligned rotation matrices from the orthogonal transformation that best aligns the estimated rotations to the reference rotations.

Parameters:

  • rots – The reference rotations to which we would like to align in the form of a n-by-3-by-3 array.

  • Q_mat – optimal orthogonal 3x3 transformation matrix

  • flag – flag==1 then J conjugacy is required and 0 is not

Returns:

regrot, aligned rotation matrices

aspire.utils.coor_trans.get_rots_mse(rots_reg, rots_ref)

Calculate MSE between the estimated orientations to reference ones.

Parameters:

  • rots_reg – The estimated rotations after alignment in the form of a n-by-3-by-3 array.

  • rots_ref – The reference rotations.

Returns:

The MSE value between two sets of rotations.

aspire.utils.coor_trans.grid_1d(n, shifted=False, normalized=True, dtype=<class 'numpy.float32'>)

Generate one dimensional grid.

Parameters:

  • n – the number of grid points.

  • shifted – shifted by half of grid or not when n is even.

  • normalized – normalize the grid in the range of (-1, 1) or not.

Returns:

the rectangular and polar coordinates of all grid points.

aspire.utils.coor_trans.grid_2d(n, shifted=False, normalized=True, indexing='yx', dtype=<class 'numpy.float32'>)

Generate two dimensional grid.

Parameters:
Returns:

the rectangular and polar coordinates of all grid points.

aspire.utils.coor_trans.grid_3d(n, shifted=False, normalized=True, indexing='zyx', dtype=<class 'numpy.float32'>)

Generate three dimensional grid.

Parameters:
Returns:

the rectangular and spherical coordinates of all grid points.

aspire.utils.coor_trans.mean_aligned_angular_distance(rots_est, rots_gt, degree_tol=None)

Register estimates to ground truth rotations and compute the mean angular distance between them (in degrees).

Parameters:

  • rots_est – A set of estimated rotations of size nx3x3.

  • rots_gt – A set of ground truth rotations of size nx3x3.

  • degree_tol – Option to assert if the mean angular distance is less than degree_tol degrees. If None, returns the mean aligned angular distance.

Returns:

The mean angular distance between registered estimates and the ground truth (in degrees).

aspire.utils.coor_trans.register_rotations(rots, rots_ref)

Register estimated orientations to reference ones.

Finds the orthogonal transformation that best aligns the estimated rotations to the reference rotations.

Parameters:

  • rots – The rotations to be aligned in the form of a n-by-3-by-3 array.

  • rots_ref – The reference rotations to which we would like to align in the form of a n-by-3-by-3 array.

Returns:

o_mat, optimal orthogonal 3x3 matrix to align the two sets; flag, flag==1 then J conjugacy is required and 0 is not.

aspire.utils.coor_trans.rots_to_clmatrix(rots, n_theta)

Compute the common lines matrix induced by all pairs of rotation matrices, rots, provided.

Parameters:

  • rots – n_rotsx3x3 array of rotation matrices.

  • n_theta – Number of theta values for common lines indices.

Returns:

n_rots x n_rots common lines matrix.

aspire.utils.coor_trans.uniform_random_angles(n, seed=None, dtype=<class 'numpy.float32'>)

Generate random 3D rotation angles

Parameters:

  • n – The number of rotation angles to generate

  • seed – Random integer seed to use. If None, the current random state is used.

Returns:

A n-by-3 ndarray of rotation angles

aspire.utils.logging module

Miscellaneous Utilities that relate to logging.

class aspire.utils.logging.LogFilterByCount(logger: Logger, max_count: int)

Bases: object

Provide a context manager for filtering repetitive log messages.

Initialize context manager based on logger and max_count.

Parameters:

  • logger – Logger instance.

  • max_count – Global limit for count of each message encountered inside context.

filter(record)

Increment msg_cache for record.

filter returns True when seen <= count for this context. True implies the logger will pass the message.

Parameters:

record – Log record. Will be reduced by hash(str()),

Returns:

Boolean

msg_cache = {-8110217801779269803: 1, -2990690814988176866: 1, -2454593599215834667: 1, -806412488498955098: 1, -553964804050338585: 1, 6175167813153837294: 1, 6772053498534573390: 1}
aspire.utils.logging.getConsoleLoggingLevel()

Returns the Python logging level of the root logger’s StreamHandler, i.e. console output. This is the same as the logging.console_level option in ASPIRE’s configuration file unless the console logging level has been changed dynamically during a session. (e.g. by a CLI option)

Returns:

The current console logging level name as a string. One of “DEBUG”. “INFO”, “WARNING”,

“ERROR”, “CRITICAL”.

aspire.utils.logging.getFileLoggingLevel()

Returns the Python logging level of the root logger’s FileHandler, i.e. log file output. This is the same as the logging.log_file_level option in ASPIRE’s configuration file unless the file logging level has been changed dynamically during a session. (e.g. by a CLI option)

Returns:

The current file logging level name as a string. One of “DEBUG”, “INFO”, “WARNING”,

“ERROR”, “CRITICAL”.

aspire.utils.logging.get_full_version()

Get as much version information as we can, including git info (if applicable) This method should never raise exceptions!

Returns:

A version number in the form: <maj>.<min>.<bld>

If we’re running as a package distributed through setuptools

<maj>.<min>.<bld>.<rev>

If we’re running as a ‘regular’ python source folder, possibly locally modified

<rev> is one of:

’src’: The package is running as a source folder <git_tag> or <git_rev> or <git_rev>-dirty: A git tag or commit revision, possibly followed by a suffix

’-dirty’ if source is modified locally

’x’: The revision cannot be determined

aspire.utils.logging.setConsoleLoggingLevel(level_name)

Dynamically sets the console logging level by setting the level of the root logger’s StreamHandler to level_name. Note this will supersede the logging.console_level option stored in ASPIRE’s configuration file.

Parameters:

level_name – One of “DEBUG”, “INFO”, “WARNING”, “ERROR”, “CRITICAL”.

aspire.utils.logging.setFileLoggingLevel(level_name)

Dynamically sets the log file logging level by setting the level of the root logger’s FileHandler to level_name. Note this will supersede the logging.log_file_level option stored in ASPIRE’s configuration file.

Parameters:

level_name – One of “DEBUG”, “INFO”, “WARNING”, “ERROR”, “CRITICAL”.

aspire.utils.logging.tqdm(*args, **kwargs)

Wraps tqdm.tqdm, applying ASPIRE configuration.

Currently setting aspire.config[‘logging’][‘tqdm_disable’] true/false will disable/enable tqdm progress bars.

aspire.utils.logging.trange(*args, **kwargs)

Wraps tqdm.trange, applying ASPIRE configuration.

Currently setting aspire.config[‘logging’][‘tqdm_disable’] true/false will disable/enable tqdm progress bars.

aspire.utils.matlab_compat module

Functions for compatibility with MATLAB behavior. At some point when the package is full validated against MatLab, the ‘order’ arguments in the functions here can be changed to ‘C’, and subsequently, this package deprecated altogether (i.e. the reshape/flatten methods used directly by the caller).

aspire.utils.matlab_compat.m_flatten(x)
aspire.utils.matlab_compat.m_reshape(x, new_shape)
aspire.utils.matlab_compat.stable_eigsh(*args, **kwargs)

A Wrapper function to fix sign problem of eigen-vectors

There is an ambiguous sign problem for the eigenvectors from scipy.sparse.linalg.eigsh function. We need to rescale the eigenvectors and make them consistent for repeated runs.

Parameters:

  • *args –

    Positional arguments

  • **kwargs –

    Keyword arguments

Returns:

Eigenvalues and eigenvectors

aspire.utils.matrix module

Utilties for arrays/n-dimensional matrices.

aspire.utils.matrix.acorr(x, y, axes=None)

Calculate array correlation along given axes

Parameters:

  • x – An array of arbitrary shape

  • y – An array of same shape as x

  • axes – The axis along which to compute the correlation. If None, the correlation is calculated along all axes.

Returns:

The correlation of x along specified axes.

aspire.utils.matrix.ainner(x, y, axes=None)

Calculate array inner product along given axes

Parameters:

  • x – An array of arbitrary shape

  • y – An array of same shape as x

  • axes – The axis along which to compute the inner product. If None, the product is calculated along all axes.

Returns:

aspire.utils.matrix.anorm(x, axes=None)

Calculate array norm along given axes

Parameters:

  • x – An array of arbitrary size and shape.

  • axes – The axis along which to compute the norm. If None, the norm is calculated along all axes.

Returns:

The Euclidean (l^2) norm of x along specified axes.

aspire.utils.matrix.best_rank1_approximation(A)

Computes the best rank-1 approximation of A.

Parameters:

A – A 2D array or a 3D array where the first axis is the stack axis.

Returns:

rank-1 ndarray of same size.

aspire.utils.matrix.eigs(A, k)

Multidimensional partial eigendecomposition

Parameters:

  • A – An array of size sig_sz-by-sig_sz, where sig_sz is a size containing d dimensions. The array represents a matrix with d indices for its rows and columns.

  • k – The number of eigenvalues and eigenvectors to calculate (default 6).

Returns:

A 2-tuple of values V: An array of eigenvectors of size sig_sz-by-k. D: A matrix of size k-by-k containing the corresponding eigenvalues in the diagonals.

aspire.utils.matrix.fix_signs(u)

Negates columns so the sign of the largest element in the column is positive.

For complex values sign is taken as norm(x)/x, zero columns unchanged.

Typically this is used for making eigenvectors deterministically signed.

Parameters:

u – matrix as numpy array

Returns:

matrix as numpy array

aspire.utils.matrix.im_to_vec(im)

Roll up images into vectors

Parameters:

im – An N-by-N-by-… array.

Returns:

An N^2-by-… array.

aspire.utils.matrix.make_psd(A)

Make a matrix positive semi-definite

This is the simplest way by setting negative eigenvalues to zero.

Parameters:

A – A matrix.

Returns:

The positive semi-definite matrix

aspire.utils.matrix.make_symmat(A)

Symmetrize a matrix

Parameters:

A – A matrix.

Returns:

The Hermitian matrix (A+A’)/2.

aspire.utils.matrix.mat_to_vec(mat, is_symmat=False)

Converts a matrix into vectorized form

Parameters:

  • mat – An array of size N-by-N-by-… containing the matrices to be vectorized.

  • is_symmat – Specifies whether the matrices are symmetric/Hermitian, in which case they are stored in packed form using symmat_to_vec (default False).

Returns:

The vectorized form of the matrices, with dimension N^2-by-… or N*(N+1)/2-by-… depending on the value of is_symmat.

aspire.utils.matrix.mdim_mat_fun_conj(X, d1, d2, f)

Conjugate a multidimensional matrix using a linear mapping

Parameters:

  • X – An N_1-by-…-by-N_d1-by-N_1…-by-N_d1-by-… array, with the first 2*d1 dimensions corresponding to matrices with columns and rows of dimension d1.

  • d1 – The dimension of the input matrix X

  • d2 – The dimension of the output matrix Y

  • f – A function handle of a linear map that takes an array of size N_1-by-…-by-N_d1-by-… and returns an array of size M_1-by-…-by-M_d2-by-… .

Returns:

An array of size M_1-by-…-by-M_d2-by-M_1-by-…-by-M_d2-by-… resulting from applying fun to the rows and columns of the multidimensional matrix X.

aspire.utils.matrix.nearest_rotations(A, allow_reflection=False)

Uses the SVD method to compute the set of nearest rotations to the set A of noisy rotations.

Note when allow_reflection is True, results may contain reflections.

Parameters:

  • A – A 2D array or a 3D array where the first axis is the stack axis.

  • allow_reflection – Optionally allow reflections (disables correction).

Returns:

ndarray of rotations of equal size to A.

aspire.utils.matrix.roll_dim(X, dim)
aspire.utils.matrix.symmat_to_vec(mat)

Packs a symmetric matrix into a lower triangular vector

Parameters:

mat – An array of size N-by-N-by-… where the first two dimensions constitute symmetric or Hermitian matrices.

Returns:

A vector of size N*(N+1)/2-by-… consisting of the lower triangular part of each matrix.

Note that a lot of acrobatics happening here (swapaxes/triu instead of tril etc.) are so that we can get column-major ordering of elements (to get behavior consistent with MATLAB), since masking in numpy only returns data in row-major order.

aspire.utils.matrix.symmat_to_vec_iso(mat)

Isometrically maps a symmetric matrix to a packed vector

Parameters:

mat – An array of size N-by-N-by-… where the first two dimensions constitute symmetric or Hermitian matrices.

Returns:

A vector of size N*(N+1)/2-by-… consisting of the lower triangular part of each matrix, reweighted so that the Frobenius inner product is mapped to the Euclidean inner product.

aspire.utils.matrix.unroll_dim(X, dim)
aspire.utils.matrix.vec_to_im(X)

Unroll vectors to images

Parameters:

X – N^2-by-… array.

Returns:

An N-by-N-by-… array.

aspire.utils.matrix.vec_to_mat(vec, is_symmat=False)

Converts a vectorized matrix into a matrix

Parameters:

  • vec – The vectorized representations. If the matrix is non-symmetric, this array has the dimensions N^2-by-…, but if the matrix is symmetric, the dimensions are N*(N+1)/2-by-… .

  • is_symmat – True if the vectors represent symmetric matrices (default False)

Returns:

The array of size N-by-N-by-… representing the matrices.

aspire.utils.matrix.vec_to_symmat(vec)

Convert packed lower triangular vector to symmetric matrix

Parameters:

vec – A vector of size N*(N+1)/2-by-… describing a symmetric (or Hermitian) matrix.

Returns:

An array of size N-by-N-by-… which indexes symmetric/Hermitian matrices that occupy the first two dimensions. The lower triangular parts of these matrices consists of the corresponding vectors in vec.

aspire.utils.matrix.vec_to_symmat_iso(vec)

Isometrically map packed vector to symmetric matrix

Parameters:

vec – A vector of size N*(N+1)/2-by-… describing a symmetric (or Hermitian) matrix.

Returns:

An array of size N-by-N-by-… which indexes symmetric/Hermitian matrices that occupy the first two dimensions. The lower triangular parts of these matrices consists of the corresponding vectors in vec, reweighted so that the Euclidean inner product maps to the Frobenius inner product.

aspire.utils.matrix.vec_to_vol(X)

Unroll vectors to volumes

Parameters:

X – N^3-by-… array.

Returns:

An N-by-N-by-N-by-… array.

aspire.utils.matrix.vecmat_to_volmat(X)

Roll up vector matrices into volume matrices

Parameters:

X – A vector matrix of size L1^3-by-L2^3-by-…

Returns:

A volume “matrix” of size L1-by-L1-by-L1-by-L2-by-L2-by-L2-by-…

aspire.utils.matrix.vol_to_vec(X)

Roll up volumes into vectors

Parameters:

X – N-by-N-by-N-by-… array.

Returns:

An N^3-by-… array.

aspire.utils.matrix.volmat_to_vecmat(X)

Unroll volume matrices to vector matrices

Parameters:

X – A volume “matrix” of size L1-by-L1-by-L1-by-L2-by-L2-by-L2-by-…

Returns:

A vector matrix of size L1^3-by-L2^3-by-…

aspire.utils.misc module

Miscellaneous Utilities that have no better place (yet).

aspire.utils.misc.J_conjugate(A)

Conjugate the 3x3 matrix A by the diagonal matrix J=diag((-1, -1, 1)).

Parameters:

A – A 3x3 matrix, or nx3x3 matrix.

Returns:

J@A@J

aspire.utils.misc.abs2(x)

Compute complex modulus squared.

aspire.utils.misc.all_pairs(n, return_map=False)

All pairs indexing (i,j) for i<j and a pairs-to-linear index mapping.

Parameters:

  • n – The number of items to be indexed.

  • return_map – Option to return pairs-to-linear index map. Default is False.

Returns:

  • n x 2 array of pairs (i, j), i<j.

  • n x n array with pairs-to-linear index map.

aspire.utils.misc.all_triplets(n)

All 3-tuples (i,j,k) where i<j<k.

Parameters:

n – The number of items to be indexed.

Returns:

All 3-tuples (i,j,k), i<j<k.

aspire.utils.misc.bump_3d(size, spread=1, dtype=<class 'numpy.float64'>)

Returns a centered 3D bump function in a (size)x(size)x(size) numpy array.

Parameters:

  • size – The length of the dimensions of the array (pixels.

  • spread – A factor controling the spread of the bump function.

  • dtype – dtype of returned array

Returns:

Numpy array (3D)

aspire.utils.misc.circ(size, x0=0, y0=0, radius=1, peak=1, dtype=<class 'numpy.float64'>)

Returns a 2d circ function in a square 2d numpy array.

where for r = sqrt(x**2 + y**2)

circ(x,y) = peak0 <= r <= radius

0 : otherwise

Default is a centered circle of spread=peak=1.

Parameters:

  • size – The height and width of returned array (pixels)

  • x0 – x cordinate of center (pixels)

  • y0 – y cordinate of center (pixels)

  • radius – radius of circle

  • peak – peak height at center

  • dtype – dtype of returned array

Returns:

Numpy array (2D)

aspire.utils.misc.cyclic_rotations(order, dtype=<class 'numpy.float64'>)

Build all rotation matrices that rotate by multiples of 2pi/order about the z-axis.

Parameters:

order – The order of cyclic symmetry

Returns:

A Rotation object containing an (order)x3x3 array of rotation matrices.

aspire.utils.misc.fuzzy_mask(L, dtype, r0=None, risetime=None)

Create a centered 1D to 3D fuzzy mask of radius r0.

Made with an error function with effective rise time.

Parameters:

  • L – The sizes of image in tuple structure. Must be 1D, 2D square, or 3D cube.

  • dtype – dtype for fuzzy mask.

  • r0 – The specified radius. Defaults to floor(0.45 * L)

  • risetime – The rise time for erf function. Defaults to floor(0.05 * L)

Returns:

The desired fuzzy mask

aspire.utils.misc.gaussian_1d(size, mu=0, sigma=1, dtype=<class 'numpy.float64'>)

Returns the 1D Gaussian

\[g(x)=\exp\left(\frac{ -(x - \mu)^2}{2\sigma^2}\right)\]

in a 1D numpy array.

Parameters:

  • size – The length of the returned array (pixels)

  • mu – mean or center (pixels)

  • sigma – standard deviation of the Gaussian

  • dtype – dtype of returned array

Returns:

Numpy array (1D)

aspire.utils.misc.gaussian_2d(size, mu=(0, 0), sigma=(1, 1), indexing='yx', dtype=<class 'numpy.float64'>)

Returns the 2D Gaussian

\[g(x,y)=\exp\left(\frac{-(x - \mu_x)^2}{2\sigma_x^2} + \frac{-(y - \mu_y)^2}{2\sigma_y^2}\right)\]

in a square 2D numpy array.

Parameters:

  • size – The length of each dimension of the returned array (pixels)

  • mu – Iterable of len(2), \((\mu_x, \mu_y)\), indicating the center of the Gaussian

  • sigma – Iterable of len(2) or constant, \((\sigma_x, \sigma_y)\), of the standard deviation in the x and y directions. A single value, \(\sigma\), can be used when \(\sigma_x = \sigma_y\).

  • indexing – The order of axis indexing, passed to aspire.utils.grid_2d

  • dtype – dtype of returned array

Returns:

Numpy array (2D)

aspire.utils.misc.gaussian_3d(size, mu=(0, 0, 0), sigma=(1, 1, 1), indexing='zyx', dtype=<class 'numpy.float64'>)

Returns the 3D Gaussian

\[g(x,y,z)=\exp\left(\frac{-(x - \mu_x)^2}{2\sigma_x^2} + \frac{-(y - \mu_y)^2}{2\sigma_y^2} + \frac{-(z - \mu_z)^2}{2\sigma_z^2}\right)\]

in a 3D numpy array.

Parameters:

  • size – The length of each dimension of the returned array (pixels)

  • mu – Iterable of len(3), \((\mu_x, \mu_y, \mu_z)\), indicating the center of the Gaussian

  • sigma – Iterable of len(3) or constant, \((\sigma_x, \sigma_y, \sigma_z)\), of the standard deviation in the x, y, and z directions. A single value, \(\sigma\), can be used when \(\sigma_x = \sigma_y = \sigma_z\)

  • indexing – The order of axis indexing, passed to aspire.utils.grid_3d

  • dtype – dtype of returned array

Returns:

Numpy array (3D)

aspire.utils.misc.importlib_path(package, resource)

Return the path to the resource as an actual file system path. Workaround importlib.resources deprecation of path in Python 3.11. This is expected to be safely removed after the minimal supported Python is 3.9.

See ASPIRE-Python #546.

Parameters:

  • package – Is either a name or a module object which conforms to the Package requirements.

  • resource – Is the name of the resource to open within package; It may not contain path separators and it may not have sub-resources. (i.e. it cannot be a directory)

Returns:

This function returns a context manager for use in a with statement. The context manager provides a pathlib.Path object.

aspire.utils.misc.inverse_r(size, x0=0, y0=0, peak=1, dtype=<class 'numpy.float64'>)

Returns a 2d inverse radius function in a square 2d numpy array.

Where inverse_r(x,y): 1/sqrt(1 + x**2 + y**2)

Default is a centered circle of peak=1.

Parameters:

  • size – The height and width of returned array (pixels)

  • x0 – x cordinate of center (pixels)

  • y0 – y cordinate of center (pixels)

  • peak – peak height at center

  • dtype – dtype of returned array

Returns:

Numpy array (2D)

aspire.utils.misc.powerset(iterable)

Generate all subsets of an iterable. Example:

powerset([1,2,3]) –> () (1,) (2,) (3,) (1,2) (1,3) (2,3) (1,2,3)

Returns:

Generator covering all subsets of iterable.

aspire.utils.misc.rename_with_timestamp(filepath, move=True)

Rename a file by appending a timestamp to the end of the filename.

Parameters:

  • filepath – Filepath to rename.

  • move – Option to rename the file on disk.

Returns:

filepath with timestamp appended.

aspire.utils.misc.sha256sum(filename)

Return sha256 hash of filename.

Parameters:

filename – path to file

Returns:

sha256 hash as hex

aspire.utils.misc.support_mask(L, support_radius=None, dtype=<class 'numpy.float64'>)

Return a mask selecting values within support_radius.

This mask is hard cutoff, boolean type. For a soft cutoff, see fuzzy_mask

Use for selecting signal. Alternatively the mask inverse (~) can be used to select background. Combinations can be used to create bands.

Parameters:

  • L – Resolution in pixels.

  • support_radius – Radius of mask in pixels. Defaults to L // 2.

  • dtype – Dtype used for mask construction and comparison.

Returns:

Boolean mask as (L,L) array.

aspire.utils.multiprocessing module

aspire.utils.multiprocessing.mem_based_cpu_suggestion()

Return an estimate of the number of clone processes that would fit in the currently available memory.

aspire.utils.multiprocessing.num_procs_suggestion()

Resolve and return number of processors to use for multiprocessing.

Query memory and cpu, then makes suggestion.

aspire.utils.multiprocessing.physical_core_cpu_suggestion()

Return the physical cores.

aspire.utils.multiprocessing.virtual_core_cpu_suggestion()

Return the virtual cores.

aspire.utils.random module

Utilities for controlling and generating random numbers.

class aspire.utils.random.Random(seed=None)

Bases: object

A context manager that pushes a random seed to the stack for reproducible results, and pops it on exit.

aspire.utils.random.choice(*args, **kwargs)

Wraps numpy random.choice call in ASPIRE Random context.

aspire.utils.random.rand(size, seed=None)

Note this is for MATLAB repro (see m_reshape).

Other uses prefer use of random.

aspire.utils.random.randi(i_max, size, seed=None)

A MATLAB compatible randi implementation that returns numbers from a discrete uniform distribution. While a direct use of np.random.choice would be convenient, this doesn’t seem to return results identical to MATLAB.

Parameters:

  • iMax – TODO

  • size – size of the resulting np array

  • seed – Random seed to use (None to apply no seed)

Returns:

A np array

aspire.utils.random.randn(*args, **kwargs)

Calls rand and applies inverse transform sampling to the output.

aspire.utils.random.random(*args, **kwargs)

Wraps numpy.random.random with ASPIRE Random context manager.

aspire.utils.relion_interop module

class aspire.utils.relion_interop.RelionStarFile(filepath)

Bases: StarFile

A star file generated by RELION representing particles, micrographs, or movies.

Initialize either from a path to a STAR file or from an OrderedDict of ndarrays

get_merged_data_block()

Return the dictionary containing particle/micrograph/movie information for this STAR file.

Returns:

A dictionary containing the data from this RELION STAR file.

aspire.utils.relion_interop.dict_to_relion_types(d)

Convert STAR file strings to data type for each field in a dict loaded via aspire.storage.StarFile. Columns without a specified data type are read as dtype=str.

Parameters:

d – A StarFile block represented as a dictionary.

Returns:

A dict with types converted where possible.

aspire.utils.resolution_estimation module

This module contains code for estimating resolution achieved by reconstructions.

class aspire.utils.resolution_estimation.FourierCorrelation(a, b, pixel_size=None, method='fft')

Bases: object

Compute the Fourier correlations between two arrays.

Underlying data (images/volumes) are assumed to be well aligned.

The Fourier correlation is defined as:

\[c(i) = \frac{ \operatorname{Re}( \sum_i{ \mathcal{F}_1(i) * {\mathcal{F}^{*}_2(i) } } ) }{\ \sqrt{ \sum_i { | \mathcal{F}_1(i) |^2 } * \sum_i{| \mathcal{F}^{*}_2}(i) |^2 } }\]

This implementation supports Numpy style broadcasting resulting in up to two stack dimensions. For example, to compute all pairs supply signal with stack shapes (m,1) and (1,n) to yield an (m,n) table of results. Note that plotting is limited to a single reference signal.

Parameters:

  • a – Input array a, shape(…, *dim).

  • b – Input array b, shape(…, *dim).

  • pixel_size – Pixel size in angstrom. Default None implies “pixel” units.

  • method – Selects either ‘fft’ (on Cartesian grid), or ‘nufft’ (on polar grid). Defaults to ‘fft’.

analyze_correlations(cutoff)

Convert from the Fourier correlations to frequencies and resolution.

Parameters:

cutoff – Cutoff value, traditionally .143. Note cutoff=None evaluates as cutoff=1.

property correlations

Compute and return the Fourier correlations of signal stacks a cross b.

Returns:

Numpy array

plot(cutoff=None, save_to_file=False, labels=None)

Generates a Fourier correlation plot.

Parameters:

  • cutoff – Cutoff value, traditionally .143. Default None implies cutoff=1 and excludes plotting cutoff line.

  • save_to_file – Optionally, save plot to file. Defaults False, enabled by providing a string filename. User is responsible for providing reasonable filename. See https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.savefig.html.

class aspire.utils.resolution_estimation.FourierRingCorrelation(a, b, pixel_size=None, method='fft')

Bases: FourierCorrelation

See FourierCorrelation.

Parameters:

  • a – Input array a, shape(…, *dim).

  • b – Input array b, shape(…, *dim).

  • pixel_size – Pixel size in angstrom. Default None implies “pixel” units.

  • method – Selects either ‘fft’ (on Cartesian grid), or ‘nufft’ (on polar grid). Defaults to ‘fft’.

dim = 2
class aspire.utils.resolution_estimation.FourierShellCorrelation(a, b, pixel_size=None, method='fft')

Bases: FourierCorrelation

See FourierCorrelation.

Parameters:

  • a – Input array a, shape(…, *dim).

  • b – Input array b, shape(…, *dim).

  • pixel_size – Pixel size in angstrom. Default None implies “pixel” units.

  • method – Selects either ‘fft’ (on Cartesian grid), or ‘nufft’ (on polar grid). Defaults to ‘fft’.

dim = 3

aspire.utils.rotation module

Define a Rotation Class for customized rotation operations used by ASPIRE.

class aspire.utils.rotation.Rotation(matrices, gimble_lock_warnings=True)

Bases: object

Initialize a Rotation object

Parameters:

  • matrices – Rotation matrices to initialize Rotation object.

  • gimble_lock_warnings – Optionally show gimble lock warnings. Defaults to True, setting to False filters warnings.

static about_axis(axis, angles, dtype=None, gimble_lock_warnings=True)

Build rotation object from axis and angles of rotation.

Parameters:

  • axis – A string denoting the axis of rotation. “x”, “y”, or “z”.

  • angles – Rotation angles in radians. angles can be a single value, or an array of shape (N,) or (N,1).

  • dtype – Optional output dtype. Infers from angles by default when possible, otherwise defaults to float32.

  • gimble_lock_warnings – Optionally show gimble lock warnings. Defaults to True, setting to False filters warnings.

Returns:

Rotation object

static angle_dist(r1, r2, dtype=None)

Find the angular distance between two sets of rotation matrices. We first compute the rotation between the two sets of rotation matrices, r = r1 @ r2.T. Then using the axis-angle representation of r we find the angle between r1 and r2. Computations will broadcast in the case of a singleton rotation and a set of rotations.

Parameters:

  • r1 – An nx3x3 array of rotation matrices, a singleton rotation, or a Rotation object.

  • r2 – An nx3x3 array of rotation matrices, a singleton rotation, or a Rotation object.

  • dtype – Computation datatype. Default None infers from r1.

Returns:

The element-wise angular distance between r1 and r2 in radians.

property angles

Rotation matrices as a n x 3 array

Type:

return

apply_registration(Q_mat, flag)

Get aligned Rotation object to reference ones.

Calculated aligned rotation matrices from the orthogonal transformation that best aligns the estimated rotations to the reference rotations.

Parameters:

  • Q_mat – optimal orthogonal 3x3 transformation matrix

  • flag – flag==1 then J conjugacy is required and 0 is not

Returns:

regrot, aligned Rotation object

as_rotvec()

Return this Rotation object as a rotation vector.

A rotation vector is a 3D vector which is co-directional to the axis of rotation and whose norm gives the angle of rotation in radians. The angle of rotation is counter-clockwise about the axis.

See from_rotvec.

Returns:

(…, 3) array

common_lines(i, j, ell)

Compute the common line induced by rotation matrices i and j.

Parameters:

  • i – The index of first rotation matrix of 3-by-3 array.

  • j – The index of second rotation matrix of 3-by-3 array.

  • ell – The total number of common lines.

Returns:

The common line indices for both first and second rotations.

property dtype

dtype of Rotation matrices

Type:

return

find_registration(rots_ref)

Register estimated orientations to reference ones.

Finds the orthogonal transformation that best aligns the estimated rotations to the reference rotations.

Parameters:

rots_ref – The reference Rotation object to which we would like to align with data matrices in the form of a n-by-3-by-3 array.

Returns:

o_mat, optimal orthogonal 3x3 matrix to align the two sets; flag, flag==1 then J conjugacy is required and 0 is not.

static from_euler(values, dtype=None)

build rotation object from Euler angles in radians

Parameters:

  • values – Rotation angles in radians, as a n x 3 array

  • dtype – Optional output dtype. Infers from values by default when possible, otherwise defaults to float32.

Returns:

new Rotation object

static from_matrix(values, dtype=None)

build rotation object from rotational matrices

Parameters:

  • dtype – Optional output dtype. Infers from values by default.

  • values – Rotation matrices, as a n x 3 x 3 array

Returns:

new Rotation object

static from_rotvec(vec, dtype=None)

Build a Rotation object from rotation vectors. A rotation vector is a 3D vector which is co-directional to the axis of rotation and whose norm gives the angle of rotation in radians. The angle of rotation is counter-clockwise about the axis.

Parameters:

  • vec – array_like, shape (N, 3) or (3,)

  • dtype – Optional output dtype. Infers from vec by default.

Returns:

Rotation object

static generate_random_rotations(n, seed=None, dtype=<class 'numpy.float32'>)

Generate Rotation object with random 3D rotation matrices

Parameters:

  • n – The number of rotation matrices to generate

  • seed – Random integer seed to use. If None, the current random state is used.

  • dtype – data type for rotational angles and matrices

Returns:

A new Rotation object

invert()

Apply transpose operation to all rotation matrices

Returns:

The set of transposed matrices

property matrices

Rotation matrices as a n x 3 x 3 array

Type:

return

static mean_angular_distance(rots_1, rots_2, dtype=None)

Find the mean angular distance between two sets of rotation matrices. Computations will broadcast in the case of a singleton rotations and a set of rotations.

Parameters:

  • rots_1 – An nx3x3 array of rotation matrices, a singleton rotation, or a Rotation object.

  • rots_2 – An nx3x3 array of rotation matrices, a singleton rotation, or a Rotation object.

  • dtype – Data type for computation. Default infers dtype from rots_1.

Returns:

The mean angular distance between rotations in radians.

mse(rots_ref)

Calculate MSE between the estimated orientations to reference ones.

Parameters:

  • rots_reg – The estimated Rotation object after alignment with data matrices in the form of a n-by-3-by-3 array.

  • rots_ref – The reference Rotation object.

Returns:

The MSE value between two sets of rotations.

register(rots_ref)

Estimate global orientation and return an aligned Rotation object.

Parameters:

rots_ref – The reference Rotation object to which we would like to align with data matrices in the form of a n-by-3-by-3 array.

Returns:

an aligned Rotation object

aspire.utils.types module

Miscellaneous utilities for common data type operations.

aspire.utils.types.complex_type(realtype)

Get Numpy complex type from corresponding real type

Parameters:

realtype – Numpy real type

Return complextype:

Numpy complex type

aspire.utils.types.real_type(complextype)

Get Numpy real type from corresponding complex type

Parameters:

complextype – Numpy complex type

Return realtype:

Numpy real type

aspire.utils.types.utest_tolerance(dtype)

Return ASPIRE tolerance for unit tests based on dtype.

aspire.utils.units module

Miscellaneous utilities for common unit conversions.

aspire.utils.units.ratio_to_decibel(p)

Convert a ratio of powers to decibel (log) scale.

Follows numpy broadcasting rules.

Parameters:

p – Power ratio.

Returns:

Power ratio in log scale

aspire.utils.units.voltage_to_wavelength(voltage)

Convert from electron voltage to wavelength.

Parameters:

voltage – float, The electron voltage in kV.

Returns:

float, The electron wavelength in angstroms.

aspire.utils.units.wavelength_to_voltage(wavelength)

Convert from electron voltage to wavelength.

Parameters:

wavelength – float, The electron wavelength in angstroms.

Returns:

float, The electron voltage in kV.

Module contents