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=None)¶
Save volume to disk as mrc file
- Parameters:
filename – Filepath where volume will be saved.
overwrite – Options to control overwrite behavior (default is None): - True: Overwrites the existing file if it exists. - False: Raises an error if the file exists. - None: Renames the old file by appending a time/date stamp.
- 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.