acryo.molecules package

Submodules

acryo.molecules.core module

class acryo.molecules.core.Molecules(pos: _Array1D | _Array2D, rot: Rotation | None = None, features: FrameInitTypes | None = None)[source]

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: ndarray, dst: ndarray | None = None, inverse: bool = False) → ndarray[tuple[int, ...], dtype[float32]][source]

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[source]

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[source]: Concatenate Molecules objects.

concat_with(other: Molecules, /, nullable: bool = True) → Self[source]

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[source]: Make a copy of the object.

count() → int[source]: Return the number of molecules.

cutby(by: str, bins: list[float]) → MoleculeCutGroup[source]: Cut molecules into sub-groups by binning.

drop_features(columns: str | Sequence[str], *more_columns: str) → Self[source]: Return a new instance with updated features.

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

euler_angle(seq: str = 'ZXZ', degrees: bool = False) → ndarray[tuple[int, ...], dtype[float64]][source]

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: DataFrame: Molecules features.

filter(predicate: pl.Expr | str | pl.Series | list[bool] | np.ndarray) → Self[source]: Filter molecules by its features.

classmethod from_axes(pos: _Array2D, z: _Array2D | None = None, y: _Array2D | None = None, x: _Array2D | None = None) → Self[source]: 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[source]: 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[source]: Construct Molecules object from a DataFrame.

classmethod from_euler(pos: _Array2D, angles: _Array2D, seq: str = 'ZXZ', degrees: bool = False, order: Literal['xyz', 'zyx'] = 'xyz', features: pl.DataFrame | None = None) → Self[source]: 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[source]: Load a file as a Molecules object using proper reader.

classmethod from_matrix(pos: _Array2D, matrix: np.ndarray, features: pl.DataFrame | None = None) → Self[source]: 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[source]: Load parquet as a Molecules object.

classmethod from_quat(pos: _Array2D, quat: _Array2D, features: pl.DataFrame | None = None) → Self[source]: Create molecules from quaternions.

classmethod from_random(pos: _Array2D, seed: int | None = None, features: pl.DataFrame | None = None) → Self[source]: Create randomly oriented molecules from given positions.

classmethod from_rotvec(pos: _Array2D, vec: _Array2D, features: pl.DataFrame | None = None) → Self[source]: Create molecules from rotation vectors.

group_by(by: str | Expr) → MoleculeGroup[str][source]
group_by(by: Sequence[str | Expr] | tuple[str | Expr, ...]) → MoleculeGroup[tuple[str, ...]]
group_by(by: str | Expr, *more_by: str | Expr) → MoleculeGroup[tuple[str, ...]]: Group molecules into sub-groups.

groupby(by, *more_by): Group molecules into sub-groups.

head(n: int = 10) → Self[source]: Return the first n molecules.

linear_transform(shift: _Array2D, rotator: Rotation, inv: bool = False) → Self[source]: Shift and rotate molecules around their own coordinate.

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

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() → ndarray[tuple[int, ...], dtype[float64]][source]

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: ndarray[tuple[int, ...], dtype[float32]]: Positions of molecules.

quaternion(canonical: bool = False) → ndarray[tuple[int, ...], dtype[float64]][source]

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[source]

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:

acryo.molecules package

Submodules

acryo.molecules.core module

Module contents