aspire.volume package

Submodules

aspire.volume.symmetry_groups module

class aspire.volume.symmetry_groups.CnSymmetryGroup(order, dtype)

Bases: SymmetryGroup

Cyclic symmetry group.

CnSymmetryGroup instance that serves up a Rotation object containing rotation matrices of the symmetry group (including the identity) accessed via the matrices attribute.

Parameters:

  • order – The cyclic order for the symmetry group (int).

  • dtype – Numpy dtype to be used for rotation matrices.

generate_rotations()

The Cn symmetry group contains all rotations about the z-axis by multiples of 2pi/n.

In the case of an AsymmetricVolume or LegacyVolume, symmetry_group contains only the identity.

Returns:

Rotation object containing the Cn symmetry group and the identity.

property to_string

String denoting the symmetry type.

class aspire.volume.symmetry_groups.DnSymmetryGroup(order, dtype)

Bases: SymmetryGroup

Dihedral symmetry group.

DnSymmetryGroup instance that serves up a Rotation object containing rotation matrices of the symmetry group (including the Identity) accessed via the matrices attribute. Note, this is the chiral dihedral symmetry group which does contain reflections.

Parameters:

  • order – The cyclic order for the symmetry group (int).

  • dtype – Numpy dtype to be used for rotation matrices.

generate_rotations()

The Dn symmetry group contains all elements of the Cn symmetry group. In addition, for each element of the Cn symmetric group we rotate by pi about a perpendicular axis, in this case the y-axis.

Returns:

Rotation object containing the Dn symmetry group and the identity.

property to_string

String denoting the symmetry type.

class aspire.volume.symmetry_groups.IdentitySymmetryGroup(dtype)

Bases: CnSymmetryGroup

The identity symmetry group.

IdentitySymmetryGroup instance that serves up a Rotation object containing the identity matrix.

Parameters:

dtype – Numpy dtype to be used for rotation matrices.

class aspire.volume.symmetry_groups.OSymmetryGroup(dtype)

Bases: SymmetryGroup

Octahedral symmetry group.

OSymmetryGroup instance that serves up a Rotation object containing rotation matrices of the symmetry group (including the Identity) accessed via the matrices attribute. Note, this is the chiral octahedral symmetry group which does not contain reflections.

Parameters:

dtype – Numpy dtype to be used for rotation matrices.

generate_rotations()

The symmetry group elements of the octahedral symmetry group O are the identity, the elements of 3 C4 rotation groups whose axes pass through two opposite vertices of the regular octahedron, 4 C3 rotation groups whose axes pass through the midpoints of two of its opposite faces, and 6 C2 rotation groups whose axes pass through the midpoints of two of its opposite edges.

Returns:

Rotation object containing the octahedral symmetry group and the identity.

property to_string

String denoting the symmetry type.

class aspire.volume.symmetry_groups.SymmetryGroup(dtype)

Bases: ABC

Base class for symmetry groups.

Parameters:

dtype – Numpy dtype to be used for rotation matrices.

abstract generate_rotations()

Method for generating a Rotation object for the symmetry group.

property matrices
static parse(symmetry, dtype)

Takes a SymmetryGroup instance or a string, ie. ‘C1’, ‘C7’, ‘D3’, ‘T’, ‘O’, and returns a concrete SymmetryGroup object with the specified dtype.

Parameters:

  • symmetry – A string (or SymmetryGroup instance) indicating the symmetry of a molecule.

  • dtype – dtype for rotation matrices.

Returns:

Concrete SymmetryGroup object.

abstract property to_string

String denoting the symmetry type.

class aspire.volume.symmetry_groups.TSymmetryGroup(dtype)

Bases: SymmetryGroup

Tetrahedral symmetry group.

TSymmetryGroup instance that serves up a Rotation object containing rotation matrices of the symmetry group (including the Identity) accessed via the matrices attribute. Note, this is the chiral tetrahedral symmetry group which does not contain reflections.

Parameters:

dtype – Numpy dtype to be used for rotation matrices.

generate_rotations()

A tetrahedron has C3 symmetry along the 4 axes through each vertex and perpendicular to the opposite face, and C2 symmetry along the axes through the midpoints of opposite edges. We convert from axis-angle representation of the symmetry group elements into rotation vectors to generate the rotation matrices via the from_rotvec() method.

Returns:

Rotation object containing the tetrahedral symmetry group and the identity.

property to_string

String denoting the symmetry type.

aspire.volume.volume module

class aspire.volume.volume.BasisVolume(basis)

Bases: Volume

A stack of one or more volumes.

This is a wrapper of numpy.ndarray which provides methods for common processing tasks.

The stack can be multidimensional with n_vols equal to the product of the stack dimensions. Singletons will be expanded into a stack with one entry.

The last three axes represent the volume size, and are checked to be cubic.

Parameters:

  • data – Numpy array containing volume data with shape (…, resolution, resolution, resolution).

  • dtype – Optionally cast data to this dtype. Defaults to data.dtype.

  • pixel_size – Optional voxel_size in angstroms. When provided will be saved with map/mrc metadata. Default of None will not write to file, but will be considered unit pixels (1) for FSC.

  • symmetry_group – A SymmetryGroup instance or string indicating symmetry of the Volume.

Returns:

A Volume instance holding data.

evaluate()
class aspire.volume.volume.BispecVolume(data, dtype=None, pixel_size=None, symmetry_group=None)

Bases: Volume

A stack of one or more volumes.

This is a wrapper of numpy.ndarray which provides methods for common processing tasks.

The stack can be multidimensional with n_vols equal to the product of the stack dimensions. Singletons will be expanded into a stack with one entry.

The last three axes represent the volume size, and are checked to be cubic.

Parameters:

  • data – Numpy array containing volume data with shape (…, resolution, resolution, resolution).

  • dtype – Optionally cast data to this dtype. Defaults to data.dtype.

  • pixel_size – Optional voxel_size in angstroms. When provided will be saved with map/mrc metadata. Default of None will not write to file, but will be considered unit pixels (1) for FSC.

  • symmetry_group – A SymmetryGroup instance or string indicating symmetry of the Volume.

Returns:

A Volume instance holding data.

expand(basis)
class aspire.volume.volume.CartesianVolume(data, dtype=None, pixel_size=None, symmetry_group=None)

Bases: Volume

A stack of one or more volumes.

This is a wrapper of numpy.ndarray which provides methods for common processing tasks.

The stack can be multidimensional with n_vols equal to the product of the stack dimensions. Singletons will be expanded into a stack with one entry.

The last three axes represent the volume size, and are checked to be cubic.

Parameters:

  • data – Numpy array containing volume data with shape (…, resolution, resolution, resolution).

  • dtype – Optionally cast data to this dtype. Defaults to data.dtype.

  • pixel_size – Optional voxel_size in angstroms. When provided will be saved with map/mrc metadata. Default of None will not write to file, but will be considered unit pixels (1) for FSC.

  • symmetry_group – A SymmetryGroup instance or string indicating symmetry of the Volume.

Returns:

A Volume instance holding data.

expand(basis)
class aspire.volume.volume.FBBasisVolume(basis)

Bases: BasisVolume

A stack of one or more volumes.

This is a wrapper of numpy.ndarray which provides methods for common processing tasks.

The stack can be multidimensional with n_vols equal to the product of the stack dimensions. Singletons will be expanded into a stack with one entry.

The last three axes represent the volume size, and are checked to be cubic.

Parameters:

  • data – Numpy array containing volume data with shape (…, resolution, resolution, resolution).

  • dtype – Optionally cast data to this dtype. Defaults to data.dtype.

  • pixel_size – Optional voxel_size in angstroms. When provided will be saved with map/mrc metadata. Default of None will not write to file, but will be considered unit pixels (1) for FSC.

  • symmetry_group – A SymmetryGroup instance or string indicating symmetry of the Volume.

Returns:

A Volume instance holding data.

class aspire.volume.volume.PolarVolume(data, dtype=None, pixel_size=None, symmetry_group=None)

Bases: Volume

A stack of one or more volumes.

This is a wrapper of numpy.ndarray which provides methods for common processing tasks.

The stack can be multidimensional with n_vols equal to the product of the stack dimensions. Singletons will be expanded into a stack with one entry.

The last three axes represent the volume size, and are checked to be cubic.

Parameters:

  • data – Numpy array containing volume data with shape (…, resolution, resolution, resolution).

  • dtype – Optionally cast data to this dtype. Defaults to data.dtype.

  • pixel_size – Optional voxel_size in angstroms. When provided will be saved with map/mrc metadata. Default of None will not write to file, but will be considered unit pixels (1) for FSC.

  • symmetry_group – A SymmetryGroup instance or string indicating symmetry of the Volume.

Returns:

A Volume instance holding data.

expand(basis)
class aspire.volume.volume.Volume(data, dtype=None, pixel_size=None, symmetry_group=None)

Bases: object

Volume is an (N1 x …) x L x L x L array, along with associated utility methods.

A stack of one or more volumes.

This is a wrapper of numpy.ndarray which provides methods for common processing tasks.

The stack can be multidimensional with n_vols equal to the product of the stack dimensions. Singletons will be expanded into a stack with one entry.

The last three axes represent the volume size, and are checked to be cubic.

Parameters:

  • data – Numpy array containing volume data with shape (…, resolution, resolution, resolution).

  • dtype – Optionally cast data to this dtype. Defaults to data.dtype.

  • pixel_size – Optional voxel_size in angstroms. When provided will be saved with map/mrc metadata. Default of None will not write to file, but will be considered unit pixels (1) for FSC.

  • symmetry_group – A SymmetryGroup instance or string indicating symmetry of the Volume.

Returns:

A Volume instance holding data.

property T

Abbreviation for transpose.

Returns:

Volume instance.

asnumpy()

Return volume data as a (<stack>, resolution, resolution, resolution) read-only array view.

Returns:

read-only ndarray view

astype(dtype, copy=True)

Return Volume instance with the prescribed dtype.

Parameters:

  • dtype – Numpy dtype

  • copy – Boolean, optionally avoid copying if Volume.dtype already matches. Defaults to True.

Returns:

Volume instance

denoise()
downsample(ds_res, mask=None, zero_nyquist=True)

Downsample each volume to a desired resolution (only cubic supported).

Parameters:

  • ds_res – Desired resolution.

  • zero_nyquist – Option to keep or remove Nyquist frequency for even resolution. Defaults to zero_nyquist=True, removing the Nyquist frequency.

  • mask – Optional NumPy array mask to multiply in Fourier space.

static empty_like(v)

Return a new empty volume instance with the shape and dtype of v.

Parameters:

v – Volume instance

Returns:

Volume instance

flatten()

Util function for flatten operation on volume data array.

Returns:

ndarray

flip(axis=-3)

Flip volume stack data along axis using numpy.flip

Parameters:

axis – Optionally specify axis as integer or tuple. Defaults to axis=-3.

Returns:

Volume instance.

classmethod from_vec(vec)

Returns a Volume instance from a (N, resolution**3) array or (resolution**3) array.

Returns:

Volume instance.

fsc(other, cutoff=None, method='fft', plot=False)

Compute the Fourier shell correlation between two volumes.

Volumes are assumed to be well aligned.

The FSC 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 } }\]
Parameters:

  • other – Volume instance to compare.

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

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

  • plot – Optionally plot to screen or file. Defaults to False. True plots to screen. Passing a filepath as a string will attempt to save to file.

Returns:

tuple(estimated_resolution, FSC), where estimated_resolution is in angstrom and FSC is a Numpy array of correlations.

classmethod load(filename, permissive=True, dtype=None, symmetry_group=None)

Load an mrc file as a Volume instance.

Parameters:

  • filename – Data filepath to load.

  • permissive – Allows problematic files to load with warning when True. Defaults to permissive=True.

  • dtype – Optionally specifiy data type. Defaults to dtype of the data.

  • symmetry_group – A SymmetryGroup instance or string indicating symmetry of the Volume.

Returns:

Volume instance.

project(rot_matrices, zero_nyquist=True)

Using the stack of rot_matrices, project images of Volume. When projecting over a stack of volumes, a singleton Rotation or a Rotation with stack size self.n_vols must be used. In the case of a singleton Rotation, each Volume in the stack will be projected using the single Rotation. In the case of a Volume stack and a Rotation stack, the i’th Volume will be projected using the i’th Rotation.

Parameters:

  • rot_matrices – Stack of rotations. Rotation or ndarray instance.

  • zero_nyquist – Option to keep or remove Nyquist frequency for even resolution. Defaults to zero_nyquist=True, removing the Nyquist frequency.

Returns:

Image instance.

rotate(rot_matrices, zero_nyquist=True)

Rotate volumes, within a fixed grid, by rot_matrices. If rot_matrices is a single rotation, each volume will be rotated by that rotation. If rot_matrices is a stack of rotations of length n_vols, the ith volume will be rotated by the ith rotation.

Parameters:

  • rot_matrices – Rotation object of length 1 or n_vols.

  • zero_nyquist – Option to keep or remove Nyquist frequency for even resolution. Defaults to zero_nyquist=True, removing the Nyquist frequency.

Returns:

Volume instance.

save(filename, overwrite=False)

Save volume to disk as mrc file

Parameters:

  • filename – Filepath where volume will be saved

  • overwrite – Option to overwrite file when set to True. Defaults to overwrite=False.

shift()
stack_reshape(*args)

Reshape the stack axis.

*argsargs:

Integer(s) or tuple describing the intended shape.

Returns:

Volume instance

property symmetry_group

A SymmetryGroup instance associated with the symmetry of the volume. Access rotation matrices of the symmetry_group via symmetry_group.rotations.

to_vec()

Returns an N x resolution ** 3 array.

transpose()

Returns a new Volume instance with volume data axes transposed.

Returns:

Volume instance.

static zeros_like(v)

Return a new zeros volume instance with the shape and dtype of v.

Parameters:

v – Volume instance

Returns:

Volume instance

aspire.volume.volume.qr_vols_forward(sim, s, n, vols, k)

TODO: Write docstring TODO: Find a better place for this!

Parameters:

  • sim –

  • s –

  • n –

  • vols –

  • k –

Returns:

aspire.volume.volume.rotated_grids(L, rot_matrices)

Generate rotated Fourier grids in 3D from rotation matrices

Parameters:

  • L – The resolution of the desired grids.

  • rot_matrices – An array of size k-by-3-by-3 containing K rotation matrices

Returns:

A set of rotated Fourier grids in three dimensions as specified by the rotation matrices. Frequencies are in the range [-pi, pi].

aspire.volume.volume.rotated_grids_3d(L, rot_matrices)

Generate rotated Fourier grids in 3D from rotation matrices.

Parameters:

  • L – The resolution of the desired grids.

  • rot_matrices – An array of size k-by-3-by-3 containing K rotation matrices

Returns:

A set of rotated Fourier grids in three dimensions as specified by the rotation matrices. Frequencies are in the range [-pi, pi].

aspire.volume.volume_synthesis module

class aspire.volume.volume_synthesis.AsymmetricVolume(L, C, K=64, pixel_size=None, seed=None, dtype=<class 'numpy.float64'>)

Bases: CnSymmetricVolume

An asymmetric Volume constructed of random 3D Gaussian blobs with compact support in the unit sphere.

Parameters:

  • L – Resolution of the Volume(s) in pixels.

  • C – Number of Volumes to generate.

  • order – An integer representing the cyclic order of the Volume(s).

  • K – Number of Gaussian blobs used to construct the Volume(s).

  • pixel_size – Optional voxel_size in angstroms. When provided will be saved with map/mrc metadata. Default of None will not write to file, but will be considered unit pixels (1) for FSC.

  • seed – Random seed for generating random Gaussian blobs.

  • dtype – dtype for Volume(s)

class aspire.volume.volume_synthesis.CnSymmetricVolume(L, C, order, K=16, alpha=1, pixel_size=None, seed=None, dtype=<class 'numpy.float64'>)

Bases: GaussianBlobsVolume

A Volume object with cyclically symmetric volumes constructed of random 3D Gaussian blobs.

Parameters:

  • L – Resolution of the Volume(s) in pixels.

  • C – Number of Volumes to generate.

  • order – An integer representing the cyclic order of the Volume(s).

  • K – Number of Gaussian blobs used to construct the Volume(s).

  • pixel_size – Optional voxel_size in angstroms. When provided will be saved with map/mrc metadata. Default of None will not write to file, but will be considered unit pixels (1) for FSC.

  • seed – Random seed for generating random Gaussian blobs.

  • dtype – dtype for Volume(s)

property n_blobs

The total number of Gaussian blobs used to generate a Volume. This value differs from self.K as it accounts for the blobs which have been duplicated during _symmetrize_gaussians.

class aspire.volume.volume_synthesis.DnSymmetricVolume(L, C, order, K=16, alpha=1, pixel_size=None, seed=None, dtype=<class 'numpy.float64'>)

Bases: CnSymmetricVolume

A Volume object with n-fold dihedral symmetry constructed of random 3D Gaussian blobs.

Parameters:

  • L – Resolution of the Volume(s) in pixels.

  • C – Number of Volumes to generate.

  • order – An integer representing the cyclic order of the Volume(s).

  • K – Number of Gaussian blobs used to construct the Volume(s).

  • pixel_size – Optional voxel_size in angstroms. When provided will be saved with map/mrc metadata. Default of None will not write to file, but will be considered unit pixels (1) for FSC.

  • seed – Random seed for generating random Gaussian blobs.

  • dtype – dtype for Volume(s)

property n_blobs

The total number of Gaussian blobs used to generate a Volume. This value differs from self.K as it accounts for the blobs which have been duplicated during _symmetrize_gaussians.

class aspire.volume.volume_synthesis.GaussianBlobsVolume(L, C, K=16, alpha=1, pixel_size=None, seed=None, dtype=<class 'numpy.float64'>)

Bases: SyntheticVolumeBase

A base class for all volumes which are generated with randomized 3D Gaussians.

Parameters:

  • L – Resolution of the Volume(s) in pixels.

  • C – Number of Volumes to generate.

  • K – Number of Gaussian blobs used to construct the Volume(s).

  • alpha – Scaling factor for variance of Gaussian blobs. Default=1.

  • pixel_size – Optional voxel_size in angstroms. When provided will be saved with map/mrc metadata. Default of None will not write to file, but will be considered unit pixels (1) for FSC.

  • seed – Random seed for generating random Gaussian blobs.

  • dtype – dtype for Volume(s)

generate()

Generates a Volume object with specified symmetry that is multiplied by a bump function to give compact support within the unit sphere.

abstract property n_blobs

The total number of Gaussian blobs used to generate a Volume. This value differs from self.K as it accounts for the blobs which have been duplicated during _symmetrize_gaussians.

property symmetry_group

SymmetryGroup object corresponding to the symmetry of the Volume.

class aspire.volume.volume_synthesis.LegacyVolume(L, C=2, K=16, pixel_size=None, seed=0, dtype=<class 'numpy.float64'>)

Bases: AsymmetricVolume

An asymmetric Volume object used for testing of legacy code.

Parameters:

  • L – Resolution of the Volume(s) in pixels.

  • C – Number of Volumes to generate.

  • order – An integer representing the cyclic order of the Volume(s).

  • K – Number of Gaussian blobs used to construct the Volume(s).

  • pixel_size – Optional voxel_size in angstroms. When provided will be saved with map/mrc metadata. Default of None will not write to file, but will be considered unit pixels (1) for FSC.

  • seed – Random seed for generating random Gaussian blobs.

  • dtype – dtype for Volume(s)

generate()

Generates an asymmetric volume composed of random 3D Gaussian blobs.

class aspire.volume.volume_synthesis.OSymmetricVolume(L, C, K=16, alpha=1, pixel_size=None, seed=None, dtype=<class 'numpy.float64'>)

Bases: GaussianBlobsVolume

A Volume object with octahedral symmetry constructed of random 3D Gaussian blobs.

Parameters:

  • L – Resolution of the Volume(s) in pixels.

  • C – Number of Volumes to generate.

  • K – Number of Gaussian blobs used to construct the Volume(s).

  • alpha – Scaling factor for variance of Gaussian blobs. Default=1.

  • pixel_size – Optional voxel_size in angstroms. When provided will be saved with map/mrc metadata. Default of None will not write to file, but will be considered unit pixels (1) for FSC.

  • seed – Random seed for generating random Gaussian blobs.

  • dtype – dtype for Volume(s)

property n_blobs

The total number of Gaussian blobs used to generate a Volume. This value differs from self.K as it accounts for the blobs which have been duplicated during _symmetrize_gaussians.

class aspire.volume.volume_synthesis.SyntheticVolumeBase(L, C, pixel_size=None, seed=None, dtype=<class 'numpy.float64'>)

Bases: ABC

abstract generate()

Called to generate and return synthetic volumes.

Each concrete subclass should implement this.

class aspire.volume.volume_synthesis.TSymmetricVolume(L, C, K=16, alpha=1, pixel_size=None, seed=None, dtype=<class 'numpy.float64'>)

Bases: GaussianBlobsVolume

A Volume object with tetrahedral symmetry constructed of random 3D Gaussian blobs.

Parameters:

  • L – Resolution of the Volume(s) in pixels.

  • C – Number of Volumes to generate.

  • K – Number of Gaussian blobs used to construct the Volume(s).

  • alpha – Scaling factor for variance of Gaussian blobs. Default=1.

  • pixel_size – Optional voxel_size in angstroms. When provided will be saved with map/mrc metadata. Default of None will not write to file, but will be considered unit pixels (1) for FSC.

  • seed – Random seed for generating random Gaussian blobs.

  • dtype – dtype for Volume(s)

property n_blobs

The total number of Gaussian blobs used to generate a Volume. This value differs from self.K as it accounts for the blobs which have been duplicated during _symmetrize_gaussians.

Module contents