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, int, int]) → numpy.ndarray[Any, numpy.dtype[numpy.float32]][source]

Return the affine matrix.

label: int

Alias for field number 0

quat: numpy.ndarray[Any, numpy.dtype[numpy.float32]]

Alias for field number 2

score: float

Alias for field number 3

shift: numpy.ndarray[Any, numpy.dtype[numpy.float32]]

Alias for field number 1

class acryo.alignment.BaseAlignmentModel(template: Union[numpy.ndarray[Any, numpy.dtype[numpy.float32]], Sequence[numpy.ndarray[Any, numpy.dtype[numpy.float32]]]], mask: Optional[Union[numpy.ndarray[Any, numpy.dtype[numpy.float32]], Callable[[numpy.ndarray[Any, numpy.dtype[numpy.float32]]], numpy.ndarray[Any, numpy.dtype[numpy.float32]]]]] = None)[source]

Bases: abc.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)

>>> def optimize(self, template, reference, max_shifts, quaternion, pos, backend):
>>>     ...
>>> def pre_transform(self, image, backend):
>>>     ...
align(img: Union[numpy.ndarray[Any, numpy.dtype[numpy.float32]], acryo.backend._api.AnyArray[numpy.float32]], max_shifts: tuple[float, float, float], quaternion: numpy.ndarray[Any, numpy.dtype[numpy.float32]] | None = None, pos: numpy.ndarray[Any, numpy.dtype[numpy.float32]] | None = None, backend: acryo.backend._api.Backend | None = None) → acryo.alignment._base.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: numpy.ndarray[Any, numpy.dtype[numpy.float32]], max_shifts: tuple[float, float, float], cval: float | None = None, backend: acryo.backend._api.Backend | None = None) → tuple[numpy.ndarray[Any, numpy.dtype[numpy.float32]], acryo.alignment._base.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: numpy.ndarray[Any, numpy.dtype[numpy.float32]], max_shifts: tuple[float, float, float], quaternion: numpy.ndarray[Any, numpy.dtype[numpy.float32]] | None = None, pos: numpy.ndarray[Any, numpy.dtype[numpy.float32]] | None = None, upsample: int = 1, backend: acryo.backend._api.Backend | None = None) → numpy.ndarray[Any, numpy.dtype[numpy.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: numpy.ndarray[Any, numpy.dtype[numpy.float32]]

The mask image.

property niter: int

Number of templates.

abstract pre_transform(image: acryo.backend._api.AnyArray[numpy.float32], backend: acryo.backend._api.Backend) → acryo.backend._api.AnyArray[numpy.complex64][source]

Pre-transformation applied to input images (including template).

property template: numpy.ndarray[Any, numpy.dtype[numpy.float32]]

The template image.

classmethod with_params(**params)[source]

Create a BaseAlignmentModel instance with parameters.

class acryo.alignment.PCCAlignment(template: Union[numpy.ndarray[Any, numpy.dtype[numpy.float32]], Sequence[numpy.ndarray[Any, numpy.dtype[numpy.float32]]]], mask: Optional[Union[numpy.ndarray[Any, numpy.dtype[numpy.float32]], Callable[[numpy.ndarray[Any, numpy.dtype[numpy.float32]]], numpy.ndarray[Any, numpy.dtype[numpy.float32]]]]] = None, rotations: Optional[Union[tuple[tuple[float, float], tuple[float, float], tuple[float, float]], scipy.spatial.transform._rotation.Rotation]] = None, cutoff: float | None = None, tilt: acryo.tilt._base.TiltSeriesModel | tuple[float, float] | None = None, tilt_range: tuple[float, float] | None = None)[source]

Bases: acryo.alignment._base.TomographyInput

Alignment model using phase cross correlation.

class acryo.alignment.RotationImplemented(template: Union[numpy.ndarray[Any, numpy.dtype[numpy.float32]], Sequence[numpy.ndarray[Any, numpy.dtype[numpy.float32]]]], mask: Optional[Union[numpy.ndarray[Any, numpy.dtype[numpy.float32]], Callable[[numpy.ndarray[Any, numpy.dtype[numpy.float32]]], numpy.ndarray[Any, numpy.dtype[numpy.float32]]]]] = None, rotations: Optional[Union[tuple[tuple[float, float], tuple[float, float], tuple[float, float]], scipy.spatial.transform._rotation.Rotation]] = None)[source]

Bases: acryo.alignment._base.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: numpy.ndarray[Any, numpy.dtype[numpy.float32]], max_shifts: tuple[float, float, float], quaternion: numpy.ndarray[Any, numpy.dtype[numpy.float32]] | None = None, pos: numpy.ndarray[Any, numpy.dtype[numpy.float32]] | None = None, backend: acryo.backend._api.Backend | None = None) → acryo.alignment._base.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: numpy.ndarray[Any, numpy.dtype[numpy.float32]], max_shifts: tuple[float, float, float], cval: float | None = None, backend: acryo.backend._api.Backend | None = None) → tuple[numpy.ndarray[Any, numpy.dtype[numpy.float32]], acryo.alignment._base.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: Optional[Union[tuple[tuple[float, float], tuple[float, float], tuple[float, float]], scipy.spatial.transform._rotation.Rotation]] = None) → acryo.alignment._bound.ParametrizedModel[Self][source]

Create an alignment model instance with parameters.

class acryo.alignment.TomographyInput(template: Union[numpy.ndarray[Any, numpy.dtype[numpy.float32]], Sequence[numpy.ndarray[Any, numpy.dtype[numpy.float32]]]], mask: Optional[Union[numpy.ndarray[Any, numpy.dtype[numpy.float32]], Callable[[numpy.ndarray[Any, numpy.dtype[numpy.float32]]], numpy.ndarray[Any, numpy.dtype[numpy.float32]]]]] = None, rotations: Optional[Union[tuple[tuple[float, float], tuple[float, float], tuple[float, float]], scipy.spatial.transform._rotation.Rotation]] = None, cutoff: float | None = None, tilt: acryo.tilt._base.TiltSeriesModel | tuple[float, float] | None = None, tilt_range: tuple[float, float] | None = None)[source]

Bases: acryo.alignment._base.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: numpy.ndarray[Any, numpy.dtype[numpy.float32]], backend: acryo.backend._api.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: numpy.ndarray[Any, numpy.dtype[numpy.complex64]], quaternion: numpy.ndarray[Any, numpy.dtype[numpy.float32]], backend: acryo.backend._api.Backend | None = None) → numpy.ndarray[Any, numpy.dtype[numpy.complex64]][source]

Apply missing wedge mask in the frequency domain.

masked_difference(image: numpy.ndarray[Any, numpy.dtype[numpy.float32]], quaternion: numpy.ndarray[Any, numpy.dtype[numpy.float32]], backend: acryo.backend._api.Backend | None = None) → numpy.ndarray[Any, numpy.dtype[numpy.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: acryo.backend._api.AnyArray[numpy.float32], backend: acryo.backend._api.Backend) → acryo.backend._api.AnyArray[numpy.complex64][source]

Apply low-pass filter without IFFT.

classmethod with_params(*, rotations: Optional[Union[tuple[tuple[float, float], tuple[float, float], tuple[float, float]], scipy.spatial.transform._rotation.Rotation]] = None, cutoff: float | None = None, tilt: acryo.tilt._base.TiltSeriesModel | None = None, tilt_range: tuple[float, float] | None = None) → acryo.alignment._bound.ParametrizedModel[Self][source]

Create an alignment model instance with parameters.

class acryo.alignment.ZNCCAlignment(template: Union[numpy.ndarray[Any, numpy.dtype[numpy.float32]], Sequence[numpy.ndarray[Any, numpy.dtype[numpy.float32]]]], mask: Optional[Union[numpy.ndarray[Any, numpy.dtype[numpy.float32]], Callable[[numpy.ndarray[Any, numpy.dtype[numpy.float32]]], numpy.ndarray[Any, numpy.dtype[numpy.float32]]]]] = None, rotations: Optional[Union[tuple[tuple[float, float], tuple[float, float], tuple[float, float]], scipy.spatial.transform._rotation.Rotation]] = None, cutoff: float | None = None, tilt: acryo.tilt._base.TiltSeriesModel | tuple[float, float] | None = None, tilt_range: tuple[float, float] | None = None)[source]

Bases: acryo.alignment._base.TomographyInput

Alignment model using zero-mean normalized cross correlation.