acryo.molecules package

Submodules

acryo.molecules.core module

class acryo.molecules.core.Molecules(pos: Union[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]], bool, int, float, complex, str, bytes, numpy._typing._nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]], rot: scipy.spatial.transform._rotation.Rotation | None = None, features: Optional[Union[polars.dataframe.frame.DataFrame, numpy._typing._array_like._SupportsArray[numpy.dtype[Any]], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]], bool, int, float, complex, str, bytes, numpy._typing._nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]], dict[str, Union[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]], bool, int, float, complex, str, bytes, numpy._typing._nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]]]]] = None)

Bases: object

Object that represents position- and orientation-defined molecules.

Positions are represented by a (N, 3) np.ndarray and orientations are represented by a scipy.spatial.transform.Rotation object. Features of each molecule can also be recorded by the features property.

Parameters

• pos (ArrayLike) – Moleculs positions.

• rot (scipy.spatial.transform.Rotation object) – Molecule orientations.

• features (dataframe, optional) – Molecule features.

affine_matrix(src: numpy.ndarray, dst: numpy.ndarray | None = None, inverse: bool = False) → numpy.ndarray[Any, numpy.dtype[numpy.float32]]

Construct affine matrices using positions and angles of molecules.

Parameters

• src (np.ndarray) – Source coordinates.

• dst (np.ndarray, optional) – Destination coordinates. By default the coordinates of molecules will be used.

• inverse (bool, default is False) – Return inverse mapping if true.

Returns

Array of concatenated affine matrices.

Return type

(N, 4, 4) array

append(other: Molecules) → Self

Mutably append molecules.

Parameters

other (Molecules) – Molecules to be appended. They must only have the subset of features, otherwise this method will raise ValueError.

Returns

Same instance with updated values.

Return type

Molecules

classmethod concat(moles: Iterable[Molecules], concat_features: bool = True, nullable: bool = True) → Self

Concatenate Molecules objects.

concat_with(other: Molecules, /, nullable: bool = True) → Self

Concatenate the molecules with the others.

Parameters

• other (Molecules) – Molecules to be concatenated.

• nullable (bool, default is True) – If true, missing features in either of the molecules will be filled with null. Raise error otherwise.

copy() → Self

Make a copy of the object.

count() → int

Return the number of molecules.

cutby(by: str, bins: list[float]) → acryo.molecules._cut.MoleculeCutGroup

Cut molecules into sub-groups by binning.

drop_features(columns: str | Sequence[str], *more_columns: str) → Self

Return a new instance with updated features.

classmethod empty(feature_labels: Iterable[str] = ())

euler_angle(seq: str = 'ZXZ', degrees: bool = False) → numpy.ndarray[Any, numpy.dtype[numpy.float64]]

Calculate Euler angles that transforms a source vector to vectors that belong to the object.

Parameters

• seq (str, default is "ZXZ") – Copy of scipy.spatial.transform.Rotation.as_euler. 3 characters belonging to the set {“X”, “Y”, “Z”} for intrinsic rotations, or {“x”, “y”, “z”} for extrinsic rotations. Adjacent axes cannot be the same. Extrinsic and intrinsic rotations cannot be mixed in one function call.

• degrees (bool, default is False) – Copy of scipy.spatial.transform.Rotation.as_euler. Returned angles are in degrees if this flag is True, else they are in radians.

Returns

Euler angles.

Return type

(N, 3) ndarray

property features: polars.dataframe.frame.DataFrame

Molecules features.

filter(predicate: pl.Expr | str | pl.Series | list[bool] | np.ndarray) → Self

Filter molecules by its features.

classmethod from_axes(pos: np.ndarray, z: np.ndarray | None = None, y: np.ndarray | None = None, x: np.ndarray | None = None) → Self

Construct molecule cloud with orientation from two of their local axes.

classmethod from_csv(path: PathLike, pos_cols: list[str] = ['z', 'y', 'x'], rot_cols: list[str] = ['zvec', 'yvec', 'xvec'], **pl_kwargs) → Self

Load csv as a Molecules object.

classmethod from_dataframe(df: pl.DataFrame, pos_cols: list[str] = ['z', 'y', 'x'], rot_cols: list[str] = ['zvec', 'yvec', 'xvec']) → Self

Construct Molecules object from a DataFrame.

classmethod from_euler(pos: np.ndarray, angles: ArrayLike, seq: str = 'ZXZ', degrees: bool = False, order: str = 'xyz', features: pl.DataFrame | None = None) → Self

Create molecules from Euler angles.

classmethod from_file(path: PathLike, pos_cols: list[str] = ['z', 'y', 'x'], rot_cols: list[str] = ['zvec', 'yvec', 'xvec']) → Self

Load a file as a Molecules object using proper reader.

classmethod from_matrix(pos: np.ndarray, matrix: np.ndarray, features: pl.DataFrame | None = None) → Self

Create molecules from rotation matrices.

classmethod from_parquet(path: PathLike, pos_cols: list[str] = ['z', 'y', 'x'], rot_cols: list[str] = ['zvec', 'yvec', 'xvec']) → Self

Load parquet as a Molecules object.

classmethod from_quat(pos: np.ndarray, quat: ArrayLike, features: pl.DataFrame | None = None) → Self

Create molecules from quaternions.

classmethod from_random(pos: np.ndarray, seed: int | None = None, features: pl.DataFrame | None = None) → Self

Create randomly oriented molecules from given positions.

classmethod from_rotvec(pos: np.ndarray, vec: ArrayLike, features: pl.DataFrame | None = None) → Self

Create molecules from rotation vectors.

group_by(by, *more_by)

Group molecules into sub-groups.

groupby(by: Union[str, polars.expr.expr.Expr]) → acryo.molecules._group.MoleculeGroup[str]

groupby(by: Union[Sequence[Union[str, polars.expr.expr.Expr]], tuple[Union[str, polars.expr.expr.Expr], ...]]) → acryo.molecules._group.MoleculeGroup[tuple[str, ...]]

groupby(by: Union[str, polars.expr.expr.Expr], *more_by: Union[str, polars.expr.expr.Expr]) → acryo.molecules._group.MoleculeGroup[tuple[str, ...]]

Group molecules into sub-groups.

head(n: int = 10) → Self

Return the first n molecules.

linear_transform(shift: ArrayLike, rotator: Rotation, inv: bool = False) → Self

Shift and rotate molecules around their own coordinate.

local_coordinates(shape: tuple[int, int, int], scale: float = 1.0, *, squeeze: bool = True) → numpy.ndarray[Any, numpy.dtype[numpy.float32]]

Generate local coordinates at the neighborhood of each molecule.

Parameters

• shape ((int, int, int)) – Shape of the local coordinates.

• scale (float, default is 1.0) – Scale of the local coordinates.

• squeeze (bool, default is True) – If ture and the number of molecules is 1, the first axis will be removed.

Returns

World coordinates. array[i] can be directly used as the coordinates for ndi.map_coordinates.

Return type

(N, D, Z, Y, X) array

matrix() → numpy.ndarray[Any, numpy.dtype[numpy.float64]]

Calculate rotation matrices that align molecules in such orientations that vec belong to the object.

Returns

Rotation matrices. Rotations represented by these matrices transform molecules to the same orientations, i.e., align all the molecules.

Return type

(N, 3, 3) ndarray

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

Positions of molecules.

quaternion(canonical: bool = False) → numpy.ndarray[Any, numpy.dtype[numpy.float64]]

Calculate quaternions that transforms a source vector to vectors that belong to the object.

Returns

Quaternions.

Return type

(N, 4) ndarray

rotate_by(rotator: Rotation, copy: bool = True) → Self

Rotate molecule with a Rotation object.

Note that Rotation object satisfies following equation.

>>> rot1.apply(rot2.apply(v)) == (rot1*rot2).apply(v)

Parameters

• rotator (Rotation) – Molecules will be rotated by this object.

• copy (bool, default is True) – If true, create a new instance, otherwise overwrite the existing instance.

Returns

Instance with updated orientation.

Return type

Molecules

rotate_by_euler_angle(angles: ArrayLike, seq: str = 'ZXZ', degrees: bool = False, order: Literal['xyz', 'zyx'] = 'xyz', copy: bool = True) → Self

Rotate molecules using Euler angles, with their position unchanged.

Parameters

• angles (array-like) – Euler angles of rotation.

• copy (bool, default is True) – If true, create a new instance, otherwise overwrite the existing instance.

Returns

Instance with updated orientation.

Return type

Molecules

rotate_by_matrix(matrix: ArrayLike, copy: bool = True) → Self

Rotate molecules using rotation matrices, with their position unchanged.

Parameters

• matrix (ArrayLike) – Rotation matrices, whose length must be same as the number of molecules.

• copy (bool, default is True) – If true, create a new instance, otherwise overwrite the existing instance.

Returns

Instance with updated orientation.

Return type

Molecules

rotate_by_quaternion(quat: ArrayLike, copy: bool = True) → Self

Rotate molecules using quaternions, with their position unchanged.

Parameters

• quat (ArrayLike) – Rotation quaternion.

• copy (bool, default is True) – If true, create a new instance, otherwise overwrite the existing instance.

Returns

Instance with updated orientation.

Return type

Molecules

rotate_by_rotvec(vector: ArrayLike, copy: bool = True) → Self

Rotate molecules using rotation vectors, with their position unchanged.

Parameters

• vector (array-like) – Rotation vectors.

• copy (bool, default is True) – If true, create a new instance, otherwise overwrite the existing instance.

Returns

Instance with updated orientation.

Return type

Molecules

rotate_by_rotvec_internal(vector: ArrayLike, copy: bool = True) → Self

Rotate molecules using internal rotation vector.

Vector components are calculated in the molecule-coordinate.

Parameters

• vector (ArrayLike) – Rotation vector(s).

• copy (bool, default is True) – If true, create a new instance, otherwise overwrite the existing instance.

Returns

Instance with updated angles.

Return type

Molecules

rotate_random(copy: bool = True, seed: int | None = None) → Self

Rotate molecules randomly.

Parameters

• copy (bool, default is True) – If true, create a new instance, otherwise overwrite the existing instance.

• seed (int, default is None) – Random seed to generate randomized rotators.

Returns

Instance with updated orientation.

Return type

Molecules

property rotator: scipy.spatial.transform._rotation.Rotation

Return scipy.spatial.transform.Rotation object

rotvec() → numpy.ndarray[Any, numpy.dtype[numpy.float64]]

Calculate rotation vectors that transforms a source vector to vectors that belong to the object.

Returns

Rotation vectors.

Return type

(N, 3) ndarray

sample(n: int = 10, seed: int | None = None) → Self

Return n randomly sampled molecules.

sort(by: IntoExpr | Iterable[IntoExpr], *more_by: IntoExpr, descending: bool = False) → Self

Return a new instance with sorted molecules and features.

Parameters

• by (str or Expr or sequence of them) – Column name or expression to sort by.

• descending (bool, default is False) – If true, sort in descending order.

subset(spec: int | slice | list[int] | NDArray[np.bool_] | NDArray[np.integer]) → Self

Create a subset of molecules by slicing.

Any slicing supported in numpy.ndarray, except for integer, can be used here. Molecule positions and angles are sliced at the same time.

Parameters

spec (int, slice, list of int, or ndarray) – Specifier that defines which molecule will be used. Any objects that numpy slicing are defined are supported. For instance, [2, 3, 5] means the 2nd, 3rd and 5th molecules will be used (zero-indexed), and slice(10, 20) means the 10th to 19th molecules will be used.

Returns

Molecule subset.

Return type

Molecules

tail(n: int = 10) → Self

Return the last n molecules.

to_csv(save_path: Union[str, pathlib.Path], float_precision: int | None = 4) → None

Save molecules as a csv file.

Parameters

• save_path (PathLike) – Save path.

• float_precision (int, default is 4) – Float precision.

to_dataframe() → polars.dataframe.frame.DataFrame

Convert coordinates, rotation and features into a single data frame.

to_file(save_path: Union[str, pathlib.Path]) → None

Save molecules as a file.

to_parquet(save_path: PathLike, *, compression: ParquetCompression = 'zstd', compression_level: int | None = 10) → None

Save molecules as a parquet file.

Parameters

• save_path (PathLike) – Save path.

• compression (str, default is "zstd") – Compression method, by default “zstd”.

translate(shifts: ArrayLike, copy: bool = True) → Self

Translate molecule positions by shifts.

Shifts are applied in world coordinates, not internal coordinates of every molecules. If molecules should be translated in their own coordinates, such as translating toward y-direction of each molecules by 1.0 nm, use translate_internal instead. Translation operation does not convert molecule orientations.

Parameters

• shifts ((3,) or (N, 3) array) – Spatial shift of molecules.

• copy (bool, default is True) – If true, create a new instance, otherwise overwrite the existing instance.

Returns

Instance with updated positional coordinates.

Return type

Molecules

translate_internal(shifts: ArrayLike, *, copy: bool = True) → Self

Translate molecule positions internally by shifts.

Shifts are applied in the coordinates of each molecule. If molecules should be translated in world coordinates use translate instead.

Parameters

• shifts ((3,) or (N, 3) array) – Spatial shift of molecules.

• copy (bool, default is True) – If true, create a new instance, otherwise overwrite the existing instance.

Returns

Instance with updated positional coordinates.

Return type

Molecules

translate_random(max_distance: nm, *, seed: int | None = None, copy: bool = True) → Self

Apply random translation to each molecule.

Translation range is restricted by a maximum distance and translation values are uniformly distributed in this region. Different translations will be applied to different molecules.

Parameters

• max_distance (nm) – Maximum distance of translation.

• seed (int, optional) – Random seed, by default None

• copy (bool, default is True) – If true, create a new instance, otherwise overwrite the existing instance.

Returns

Translated molecules.

Return type

Molecules

with_features(exprs: IntoExpr | Iterable[IntoExpr], *more_exprs: IntoExpr, **named_exprs: IntoExpr) → Self

Return a new instance with updated features.

property x: numpy.ndarray[Any, numpy.dtype[numpy.float64]]

Vectors of x-axis.

property y: numpy.ndarray[Any, numpy.dtype[numpy.float64]]

Vectors of y-axis.

property z: numpy.ndarray[Any, numpy.dtype[numpy.float64]]

Vectors of z-axis.

acryo.molecules.core.cross(x: Union[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]], bool, int, float, complex, str, bytes, numpy._typing._nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]], y: Union[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]], bool, int, float, complex, str, bytes, numpy._typing._nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]], axis=None) → numpy.ndarray

Vector outer product in zyx coordinate.

Module contents

class acryo.molecules.Molecules(pos: Union[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]], bool, int, float, complex, str, bytes, numpy._typing._nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]], rot: scipy.spatial.transform._rotation.Rotation | None = None, features: Optional[Union[polars.dataframe.frame.DataFrame, numpy._typing._array_like._SupportsArray[numpy.dtype[Any]], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]], bool, int, float, complex, str, bytes, numpy._typing._nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]], dict[str, Union[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]], bool, int, float, complex, str, bytes, numpy._typing._nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]]]]] = None)

Bases: object

Object that represents position- and orientation-defined molecules.

Positions are represented by a (N, 3) np.ndarray and orientations are represented by a scipy.spatial.transform.Rotation object. Features of each molecule can also be recorded by the features property.

Parameters

• pos (ArrayLike) – Moleculs positions.

• rot (scipy.spatial.transform.Rotation object) – Molecule orientations.

• features (dataframe, optional) – Molecule features.

affine_matrix(src: numpy.ndarray, dst: numpy.ndarray | None = None, inverse: bool = False) → numpy.ndarray[Any, numpy.dtype[numpy.float32]]

Construct affine matrices using positions and angles of molecules.

Parameters

• src (np.ndarray) – Source coordinates.

• dst (np.ndarray, optional) – Destination coordinates. By default the coordinates of molecules will be used.

• inverse (bool, default is False) – Return inverse mapping if true.

Returns

Array of concatenated affine matrices.

Return type

(N, 4, 4) array

append(other: Molecules) → Self

Mutably append molecules.

Parameters

other (Molecules) – Molecules to be appended. They must only have the subset of features, otherwise this method will raise ValueError.

Returns

Same instance with updated values.

Return type

Molecules

classmethod concat(moles: Iterable[Molecules], concat_features: bool = True, nullable: bool = True) → Self

Concatenate Molecules objects.

concat_with(other: Molecules, /, nullable: bool = True) → Self

Concatenate the molecules with the others.

Parameters

• other (Molecules) – Molecules to be concatenated.

• nullable (bool, default is True) – If true, missing features in either of the molecules will be filled with null. Raise error otherwise.

copy() → Self

Make a copy of the object.

count() → int

Return the number of molecules.

cutby(by: str, bins: list[float]) → acryo.molecules._cut.MoleculeCutGroup

Cut molecules into sub-groups by binning.

drop_features(columns: str | Sequence[str], *more_columns: str) → Self

Return a new instance with updated features.

classmethod empty(feature_labels: Iterable[str] = ())

euler_angle(seq: str = 'ZXZ', degrees: bool = False) → numpy.ndarray[Any, numpy.dtype[numpy.float64]]

Calculate Euler angles that transforms a source vector to vectors that belong to the object.

Parameters

• seq (str, default is "ZXZ") – Copy of scipy.spatial.transform.Rotation.as_euler. 3 characters belonging to the set {“X”, “Y”, “Z”} for intrinsic rotations, or {“x”, “y”, “z”} for extrinsic rotations. Adjacent axes cannot be the same. Extrinsic and intrinsic rotations cannot be mixed in one function call.

• degrees (bool, default is False) – Copy of scipy.spatial.transform.Rotation.as_euler. Returned angles are in degrees if this flag is True, else they are in radians.

Returns

Euler angles.

Return type

(N, 3) ndarray

property features: polars.dataframe.frame.DataFrame

Molecules features.

filter(predicate: pl.Expr | str | pl.Series | list[bool] | np.ndarray) → Self

Filter molecules by its features.

classmethod from_axes(pos: np.ndarray, z: np.ndarray | None = None, y: np.ndarray | None = None, x: np.ndarray | None = None) → Self

Construct molecule cloud with orientation from two of their local axes.

classmethod from_csv(path: PathLike, pos_cols: list[str] = ['z', 'y', 'x'], rot_cols: list[str] = ['zvec', 'yvec', 'xvec'], **pl_kwargs) → Self

Load csv as a Molecules object.

classmethod from_dataframe(df: pl.DataFrame, pos_cols: list[str] = ['z', 'y', 'x'], rot_cols: list[str] = ['zvec', 'yvec', 'xvec']) → Self

Construct Molecules object from a DataFrame.

classmethod from_euler(pos: np.ndarray, angles: ArrayLike, seq: str = 'ZXZ', degrees: bool = False, order: str = 'xyz', features: pl.DataFrame | None = None) → Self

Create molecules from Euler angles.

classmethod from_file(path: PathLike, pos_cols: list[str] = ['z', 'y', 'x'], rot_cols: list[str] = ['zvec', 'yvec', 'xvec']) → Self

Load a file as a Molecules object using proper reader.

classmethod from_matrix(pos: np.ndarray, matrix: np.ndarray, features: pl.DataFrame | None = None) → Self

Create molecules from rotation matrices.

classmethod from_parquet(path: PathLike, pos_cols: list[str] = ['z', 'y', 'x'], rot_cols: list[str] = ['zvec', 'yvec', 'xvec']) → Self

Load parquet as a Molecules object.

classmethod from_quat(pos: np.ndarray, quat: ArrayLike, features: pl.DataFrame | None = None) → Self

Create molecules from quaternions.

classmethod from_random(pos: np.ndarray, seed: int | None = None, features: pl.DataFrame | None = None) → Self

Create randomly oriented molecules from given positions.

classmethod from_rotvec(pos: np.ndarray, vec: ArrayLike, features: pl.DataFrame | None = None) → Self

Create molecules from rotation vectors.

group_by(by, *more_by)

Group molecules into sub-groups.

groupby(by: Union[str, polars.expr.expr.Expr]) → acryo.molecules._group.MoleculeGroup[str]

groupby(by: Union[Sequence[Union[str, polars.expr.expr.Expr]], tuple[Union[str, polars.expr.expr.Expr], ...]]) → acryo.molecules._group.MoleculeGroup[tuple[str, ...]]

groupby(by: Union[str, polars.expr.expr.Expr], *more_by: Union[str, polars.expr.expr.Expr]) → acryo.molecules._group.MoleculeGroup[tuple[str, ...]]

Group molecules into sub-groups.

head(n: int = 10) → Self

Return the first n molecules.

linear_transform(shift: ArrayLike, rotator: Rotation, inv: bool = False) → Self

Shift and rotate molecules around their own coordinate.

local_coordinates(shape: tuple[int, int, int], scale: float = 1.0, *, squeeze: bool = True) → numpy.ndarray[Any, numpy.dtype[numpy.float32]]

Generate local coordinates at the neighborhood of each molecule.

Parameters

• shape ((int, int, int)) – Shape of the local coordinates.

• scale (float, default is 1.0) – Scale of the local coordinates.

• squeeze (bool, default is True) – If ture and the number of molecules is 1, the first axis will be removed.

Returns

World coordinates. array[i] can be directly used as the coordinates for ndi.map_coordinates.

Return type

(N, D, Z, Y, X) array

matrix() → numpy.ndarray[Any, numpy.dtype[numpy.float64]]

Calculate rotation matrices that align molecules in such orientations that vec belong to the object.

Returns

Rotation matrices. Rotations represented by these matrices transform molecules to the same orientations, i.e., align all the molecules.

Return type

(N, 3, 3) ndarray

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

Positions of molecules.

quaternion(canonical: bool = False) → numpy.ndarray[Any, numpy.dtype[numpy.float64]]

Calculate quaternions that transforms a source vector to vectors that belong to the object.

Returns

Quaternions.

Return type

(N, 4) ndarray

rotate_by(rotator: Rotation, copy: bool = True) → Self

Rotate molecule with a Rotation object.

Note that Rotation object satisfies following equation.

>>> rot1.apply(rot2.apply(v)) == (rot1*rot2).apply(v)

Parameters

• rotator (Rotation) – Molecules will be rotated by this object.

• copy (bool, default is True) – If true, create a new instance, otherwise overwrite the existing instance.

Returns

Instance with updated orientation.

Return type

Molecules

rotate_by_euler_angle(angles: ArrayLike, seq: str = 'ZXZ', degrees: bool = False, order: Literal['xyz', 'zyx'] = 'xyz', copy: bool = True) → Self

Rotate molecules using Euler angles, with their position unchanged.

Parameters

• angles (array-like) – Euler angles of rotation.

• copy (bool, default is True) – If true, create a new instance, otherwise overwrite the existing instance.

Returns

Instance with updated orientation.

Return type

Molecules

rotate_by_matrix(matrix: ArrayLike, copy: bool = True) → Self

Rotate molecules using rotation matrices, with their position unchanged.

Parameters

• matrix (ArrayLike) – Rotation matrices, whose length must be same as the number of molecules.

• copy (bool, default is True) – If true, create a new instance, otherwise overwrite the existing instance.

Returns

Instance with updated orientation.

Return type

Molecules

rotate_by_quaternion(quat: ArrayLike, copy: bool = True) → Self

Rotate molecules using quaternions, with their position unchanged.

Parameters

• quat (ArrayLike) – Rotation quaternion.

• copy (bool, default is True) – If true, create a new instance, otherwise overwrite the existing instance.

Returns

Instance with updated orientation.

Return type

Molecules

rotate_by_rotvec(vector: ArrayLike, copy: bool = True) → Self

Rotate molecules using rotation vectors, with their position unchanged.

Parameters

• vector (array-like) – Rotation vectors.

• copy (bool, default is True) – If true, create a new instance, otherwise overwrite the existing instance.

Returns

Instance with updated orientation.

Return type

Molecules

rotate_by_rotvec_internal(vector: ArrayLike, copy: bool = True) → Self

Rotate molecules using internal rotation vector.

Vector components are calculated in the molecule-coordinate.

Parameters

• vector (ArrayLike) – Rotation vector(s).

• copy (bool, default is True) – If true, create a new instance, otherwise overwrite the existing instance.

Returns

Instance with updated angles.

Return type

Molecules

rotate_random(copy: bool = True, seed: int | None = None) → Self

Rotate molecules randomly.

Parameters

• copy (bool, default is True) – If true, create a new instance, otherwise overwrite the existing instance.

• seed (int, default is None) – Random seed to generate randomized rotators.

Returns

Instance with updated orientation.

Return type

Molecules

property rotator: scipy.spatial.transform._rotation.Rotation

Return scipy.spatial.transform.Rotation object

rotvec() → numpy.ndarray[Any, numpy.dtype[numpy.float64]]

Calculate rotation vectors that transforms a source vector to vectors that belong to the object.

Returns

Rotation vectors.

Return type

(N, 3) ndarray

sample(n: int = 10, seed: int | None = None) → Self

Return n randomly sampled molecules.

sort(by: IntoExpr | Iterable[IntoExpr], *more_by: IntoExpr, descending: bool = False) → Self

Return a new instance with sorted molecules and features.

Parameters

• by (str or Expr or sequence of them) – Column name or expression to sort by.

• descending (bool, default is False) – If true, sort in descending order.

subset(spec: int | slice | list[int] | NDArray[np.bool_] | NDArray[np.integer]) → Self

Create a subset of molecules by slicing.

Any slicing supported in numpy.ndarray, except for integer, can be used here. Molecule positions and angles are sliced at the same time.

Parameters

spec (int, slice, list of int, or ndarray) – Specifier that defines which molecule will be used. Any objects that numpy slicing are defined are supported. For instance, [2, 3, 5] means the 2nd, 3rd and 5th molecules will be used (zero-indexed), and slice(10, 20) means the 10th to 19th molecules will be used.

Returns

Molecule subset.

Return type

Molecules

tail(n: int = 10) → Self

Return the last n molecules.

to_csv(save_path: Union[str, pathlib.Path], float_precision: int | None = 4) → None

Save molecules as a csv file.

Parameters

• save_path (PathLike) – Save path.

• float_precision (int, default is 4) – Float precision.

to_dataframe() → polars.dataframe.frame.DataFrame

Convert coordinates, rotation and features into a single data frame.

to_file(save_path: Union[str, pathlib.Path]) → None

Save molecules as a file.

to_parquet(save_path: PathLike, *, compression: ParquetCompression = 'zstd', compression_level: int | None = 10) → None

Save molecules as a parquet file.

Parameters

• save_path (PathLike) – Save path.

• compression (str, default is "zstd") – Compression method, by default “zstd”.

translate(shifts: ArrayLike, copy: bool = True) → Self

Translate molecule positions by shifts.

Shifts are applied in world coordinates, not internal coordinates of every molecules. If molecules should be translated in their own coordinates, such as translating toward y-direction of each molecules by 1.0 nm, use translate_internal instead. Translation operation does not convert molecule orientations.

Parameters

• shifts ((3,) or (N, 3) array) – Spatial shift of molecules.

• copy (bool, default is True) – If true, create a new instance, otherwise overwrite the existing instance.

Returns

Instance with updated positional coordinates.

Return type

Molecules

translate_internal(shifts: ArrayLike, *, copy: bool = True) → Self

Translate molecule positions internally by shifts.

Shifts are applied in the coordinates of each molecule. If molecules should be translated in world coordinates use translate instead.

Parameters

• shifts ((3,) or (N, 3) array) – Spatial shift of molecules.

• copy (bool, default is True) – If true, create a new instance, otherwise overwrite the existing instance.

Returns

Instance with updated positional coordinates.

Return type

Molecules

translate_random(max_distance: nm, *, seed: int | None = None, copy: bool = True) → Self

Apply random translation to each molecule.

Translation range is restricted by a maximum distance and translation values are uniformly distributed in this region. Different translations will be applied to different molecules.

Parameters

• max_distance (nm) – Maximum distance of translation.

• seed (int, optional) – Random seed, by default None

• copy (bool, default is True) – If true, create a new instance, otherwise overwrite the existing instance.

Returns

Translated molecules.

Return type

Molecules

with_features(exprs: IntoExpr | Iterable[IntoExpr], *more_exprs: IntoExpr, **named_exprs: IntoExpr) → Self

Return a new instance with updated features.

property x: numpy.ndarray[Any, numpy.dtype[numpy.float64]]

Vectors of x-axis.

property y: numpy.ndarray[Any, numpy.dtype[numpy.float64]]

Vectors of y-axis.

property z: numpy.ndarray[Any, numpy.dtype[numpy.float64]]

Vectors of z-axis.

acryo.molecules.axes_to_rotator(z: Optional[Union[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]], bool, int, float, complex, str, bytes, numpy._typing._nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]]], y: Union[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]], bool, int, float, complex, str, bytes, numpy._typing._nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]]) → scipy.spatial.transform._rotation.Rotation

Determine the Rotation object that rotates the z-axis to z and the y-axis to y.

acryo.molecules.from_euler_xyz_coords(angles: Union[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]], bool, int, float, complex, str, bytes, numpy._typing._nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]], seq: str = 'ZXZ', degrees: bool = False) → scipy.spatial.transform._rotation.Rotation

Create a rotator using zyx-coordinate system, from Euler angles.