acryo.alignment package

Module contents

class acryo.alignment.AlignmentResult(label: int, shift: NDArray[np.float32], quat: NDArray[np.float32], score: float)[source]

Bases: NamedTuple

The optimal alignment result.

affine_matrix(shape: tuple[int, ...]) → ndarray[tuple[int, ...], dtype[float32]][source]: Return the affine matrix.

label: int: Alias for field number 0

quat: ndarray[tuple[int, ...], dtype[float32]]: Alias for field number 2

score: float: Alias for field number 3

shift: ndarray[tuple[int, ...], dtype[float32]]: Alias for field number 1

class acryo.alignment.BaseAlignmentModel(template: ndarray[tuple[int, ...], dtype[float32]] | Sequence[ndarray[tuple[int, ...], dtype[float32]]], mask: ndarray[tuple[int, ...], dtype[float32]] | Callable[[ndarray[tuple[int, ...], dtype[float32]]], ndarray[tuple[int, ...], dtype[float32]]] | None = None)[source]

Bases: ABC

The base class to implement alignment method.

This class supports subvolume masking, pre-transformation of subvolumes and template, optimization of spatial transformation.

subvolume template

|

v v

( soft-masking )

|

v v

(pre-transformation)

|

v

(alignment)

Abstract Methods

>>> def optimize(self, template, reference, max_shifts, quaternion, pos, backend):
>>>     ...
>>> def pre_transform(self, image, backend):
>>>     ...

align(img: ndarray[tuple[int, ...], dtype[float32]] | AnyArray[float32], max_shifts: tuple[float, float, float], quaternion: ndarray[tuple[int, ...], dtype[float32]] | None = None, pos: ndarray[tuple[int, ...], dtype[float32]] | None = None, backend: Backend | None = None) → AlignmentResult[source]

Align an image using current alignment parameters.

Parameters:

img (np.ndarray) – Subvolume to be aligned
max_shifts (tuple[float, float, float]) – Maximum shifts along z, y, x axis in pixel.

Returns:

Result of alignment.

Return type:

AlignmentResult

fit(img: ndarray[tuple[int, ...], dtype[float32]], max_shifts: tuple[float, float, float], cval: float | None = None, backend: Backend | None = None) → tuple[ndarray[tuple[int, ...], dtype[float32]], AlignmentResult][source]

Fit image to template based on the alignment model.

Parameters:

img (np.ndarray) – Input image that will be transformed.
max_shifts (tuple[float, float, float]) – Maximum shifts along z, y, x axis in pixel.
cval (float, optional) – Constant value for padding.

Returns:

Transformed input image and the alignment result.

Return type:

np.ndarray, AlignmentResult

property has_hetero_templates: bool: If the alignment model has different type of templates.

property has_rotation: bool: If the alignment model has rotation optimization.

property input_shape: tuple[int, ...]: Return the array shape of input images and template.

property is_multi_templates: bool: Whether alignment parameters requires multi-templates. “Multi-template” includes alignment with subvolume rotation.

landscape(img: ndarray[tuple[int, ...], dtype[float32]], max_shifts: tuple[float, float, float], quaternion: ndarray[tuple[int, ...], dtype[float32]] | None = None, pos: ndarray[tuple[int, ...], dtype[float32]] | None = None, upsample: int = 1, backend: Backend | None = None) → ndarray[tuple[int, ...], dtype[float32]][source]

Calculate correlation landscape of the input image.

Parameters:

img (np.ndarray) – Subvolume for the landscape calculation.
max_shifts (tuple[float, float, float]) – Maximum shifts along z, y, x axis in pixel.

Returns:

N (if single template) or N+1 (if multi-template) dimensional array of correlation landscape.

Return type:

np.ndarray

property mask: ndarray[tuple[int, ...], dtype[float32]]: The mask image.

property niter: int: Number of templates.

abstract pre_transform(image: AnyArray[float32], backend: Backend) → AnyArray[complex64][source]: Pre-transformation applied to input images (including template).

score(img: ndarray[tuple[int, ...], dtype[float32]], quaternion: ndarray[tuple[int, ...], dtype[float32]], pos: ndarray[tuple[int, ...], dtype[float32]], backend: Backend | None = None) → float[source]

Calculate the score between the image and the template.

Parameters:: img (np.ndarray) – Input image that will be transformed.
Returns:: Score of the alignment.
Return type:: float

property template: ndarray[tuple[int, ...], dtype[float32]]: The template image.

classmethod with_params(**params)[source]: Create a BaseAlignmentModel instance with parameters.

class acryo.alignment.FSCAlignment(template: ndarray[tuple[int, ...], dtype[float32]] | Sequence[ndarray[tuple[int, ...], dtype[float32]]], mask: ndarray[tuple[int, ...], dtype[float32]] | Callable[[ndarray[tuple[int, ...], dtype[float32]]], ndarray[tuple[int, ...], dtype[float32]]] | None = None, rotations: tuple[tuple[float, float], tuple[float, float], tuple[float, float]] | Rotation | None = None, cutoff: float | None = None, tilt: TiltSeriesModel | tuple[float, float] | None = None, tilt_range: tuple[float, float] | None = None)[source]

Bases: TomographyInput

Alignment model using Fourier shell correlation.

class acryo.alignment.NCCAlignment(template: ndarray[tuple[int, ...], dtype[float32]] | Sequence[ndarray[tuple[int, ...], dtype[float32]]], mask: ndarray[tuple[int, ...], dtype[float32]] | Callable[[ndarray[tuple[int, ...], dtype[float32]]], ndarray[tuple[int, ...], dtype[float32]]] | None = None, rotations: tuple[tuple[float, float], tuple[float, float], tuple[float, float]] | Rotation | None = None, cutoff: float | None = None, tilt: TiltSeriesModel | tuple[float, float] | None = None, tilt_range: tuple[float, float] | None = None)[source]

Bases: TomographyInput

Alignment model using zero-mean cross correlation.

class acryo.alignment.PCCAlignment(template: ndarray[tuple[int, ...], dtype[float32]] | Sequence[ndarray[tuple[int, ...], dtype[float32]]], mask: ndarray[tuple[int, ...], dtype[float32]] | Callable[[ndarray[tuple[int, ...], dtype[float32]]], ndarray[tuple[int, ...], dtype[float32]]] | None = None, rotations: tuple[tuple[float, float], tuple[float, float], tuple[float, float]] | Rotation | None = None, cutoff: float | None = None, tilt: TiltSeriesModel | tuple[float, float] | None = None, tilt_range: tuple[float, float] | None = None)[source]

Bases: TomographyInput

Alignment model using phase cross correlation.

class acryo.alignment.RotationImplemented(template: ndarray[tuple[int, ...], dtype[float32]] | Sequence[ndarray[tuple[int, ...], dtype[float32]]], mask: ndarray[tuple[int, ...], dtype[float32]] | Callable[[ndarray[tuple[int, ...], dtype[float32]]], ndarray[tuple[int, ...], dtype[float32]]] | None = None, rotations: tuple[tuple[float, float], tuple[float, float], tuple[float, float]] | Rotation | None = None)[source]

Bases: BaseAlignmentModel

An alignment model implemented with default rotation optimizer.

If optimize does not support rotation optimization, this class implements simple parameter searching algorithm to it. Thus, optimize only has to optimize shift of images.

align(img: ndarray[tuple[int, ...], dtype[float32]], max_shifts: tuple[float, float, float], quaternion: ndarray[tuple[int, ...], dtype[float32]] | None = None, pos: ndarray[tuple[int, ...], dtype[float32]] | None = None, backend: Backend | None = None) → AlignmentResult[source]

Align an image using current alignment parameters.

Parameters:

img (np.ndarray) – Subvolume to be aligned
max_shifts (tuple of float) – Maximum shifts along z, y, x axis in pixel.

Returns:

Result of alignment.

Return type:

AlignmentResult

fit(img: ndarray[tuple[int, ...], dtype[float32]], max_shifts: tuple[float, float, float], cval: float | None = None, backend: Backend | None = None) → tuple[ndarray[tuple[int, ...], dtype[float32]], AlignmentResult][source]

Fit image to template based on the alignment model.

Unlike BaseAlignmentModel, rotation optimization is executed in parallel to boost calculation.

Parameters:

img (np.ndarray) – Input image that will be transformed.
max_shifts (tuple of float) – Maximum shifts along z, y, x axis in pixel.
cval (float, optional) – Constant value for padding.

Returns:

Transformed input image and the alignment result.

Return type:

np.ndarray, AlignmentResult

property has_rotation: bool: If the alignment model has rotation optimization.

property niter: int: Number of iteration per sub-volume.

classmethod with_params(*, rotations: tuple[tuple[float, float], tuple[float, float], tuple[float, float]] | Rotation | None = None) → ParametrizedModel[Self][source]: Create an alignment model instance with parameters.

class acryo.alignment.TomographyInput(template: ndarray[tuple[int, ...], dtype[float32]] | Sequence[ndarray[tuple[int, ...], dtype[float32]]], mask: ndarray[tuple[int, ...], dtype[float32]] | Callable[[ndarray[tuple[int, ...], dtype[float32]]], ndarray[tuple[int, ...], dtype[float32]]] | None = None, rotations: tuple[tuple[float, float], tuple[float, float], tuple[float, float]] | Rotation | None = None, cutoff: float | None = None, tilt: TiltSeriesModel | tuple[float, float] | None = None, tilt_range: tuple[float, float] | None = None)[source]

Bases: RotationImplemented

An alignment model that implements missing-wedge masking and low-pass filter.

This alignment model is useful for subtomogram averaging of real experimental data with limited tilt ranges. Template image will be masked with synthetic missing-wedge mask in the frequency domain.

get_missing_wedge_mask(quat: ndarray[tuple[int, ...], dtype[float32]], backend: Backend | None = None)[source]

Create a mask that covers tomographical missing wedge.

Parameters:: quat ((4,) array) – Quaternion representation of the orientation of the subvolume.
Returns:: Missing wedge mask array.
Return type:: np.ndarray or 1

mask_missing_wedge(image: ndarray[tuple[int, ...], dtype[complex64]], quaternion: ndarray[tuple[int, ...], dtype[float32]], backend: Backend | None = None) → ndarray[tuple[int, ...], dtype[complex64]][source]: Apply missing wedge mask in the frequency domain.

masked_difference(image: ndarray[tuple[int, ...], dtype[float32]], quaternion: ndarray[tuple[int, ...], dtype[float32]], backend: Backend | None = None) → ndarray[tuple[int, ...], dtype[float32]][source]

Difference between an image and the template, considering the missing wedge.

Parameters:

image (3D array) – Input image, usually a subvolume from a tomogram.
quaternion ((4,) array) – Rotation of the image, usually the quaternion array of a Molecules object.

Returns:

Difference map.

Return type:

3D array

pre_transform(image: AnyArray[float32], backend: Backend) → AnyArray[complex64][source]: Apply low-pass filter without IFFT.

classmethod with_params(*, rotations: tuple[tuple[float, float], tuple[float, float], tuple[float, float]] | Rotation | None = None, cutoff: float | None = None, tilt: TiltSeriesModel | None = None, tilt_range: tuple[float, float] | None = None) → ParametrizedModel[Self][source]: Create an alignment model instance with parameters.

class acryo.alignment.ZNCCAlignment(template: ndarray[tuple[int, ...], dtype[float32]] | Sequence[ndarray[tuple[int, ...], dtype[float32]]], mask: ndarray[tuple[int, ...], dtype[float32]] | Callable[[ndarray[tuple[int, ...], dtype[float32]]], ndarray[tuple[int, ...], dtype[float32]]] | None = None, rotations: tuple[tuple[float, float], tuple[float, float], tuple[float, float]] | Rotation | None = None, cutoff: float | None = None, tilt: TiltSeriesModel | tuple[float, float] | None = None, tilt_range: tuple[float, float] | None = None)[source]

Bases: TomographyInput

Alignment model using zero-mean normalized cross correlation.