biotite 1.1.0__cp312-cp312-macosx_11_0_arm64.whl → 1.3.0__cp312-cp312-macosx_11_0_arm64.whl

biotite/structure/transform.py

@@ -10,6 +10,7 @@ that can be applied on structures.
 __name__ = "biotite.structure"
 __author__ = "Patrick Kunzmann", "Claude J. Rogers"
 __all__ = [
+    "AffineTransformation",
     "translate",
     "rotate",
     "rotate_centered",
@@ -20,10 +21,215 @@ __all__ = [
 
 import numpy as np
 from biotite.structure.atoms import Atom, AtomArray, AtomArrayStack, coord
-from biotite.structure.geometry import centroid
 from biotite.structure.util import matrix_rotate, norm_vector, vector_dot
 
 
+class AffineTransformation:
+    """
+    An affine transformation, consisting of translations and a rotation.
+
+    Parameters
+    ----------
+    center_translation : ndarray, shape=(3,) or shape=(m,3), dtype=float
+        The translation vector for moving the centroid into the
+        origin.
+    rotation : ndarray, shape=(3,3) or shape=(m,3,3), dtype=float
+        The rotation matrix.
+    target_translation : ndarray, shape=(m,3), dtype=float
+        The translation vector for moving the structure onto the
+        fixed one.
+
+    Attributes
+    ----------
+    center_translation, rotation, target_translation : ndarray
+        Same as the parameters.
+        The dimensions are always expanded to *(m,3)* or *(m,3,3)*,
+        respectively.
+    """
+
+    def __init__(self, center_translation, rotation, target_translation):
+        self.center_translation = _expand_dims(center_translation, 2)
+        self.rotation = _expand_dims(rotation, 3)
+        self.target_translation = _expand_dims(target_translation, 2)
+
+    def apply(self, atoms):
+        """
+        Apply this transformation on the given structure.
+
+        Parameters
+        ----------
+        atoms : AtomArray or AtomArrayStack or ndarray, shape(n,), dtype=float or ndarray, shape(m,n), dtype=float
+            The structure to apply the transformation on.
+
+        Returns
+        -------
+        transformed : AtomArray or AtomArrayStack or ndarray, shape(n,), dtype=float or ndarray, shape(m,n), dtype=float
+            A copy of the `atoms` structure, with transformations applied.
+            Only coordinates are returned, if coordinates were given in `atoms`.
+
+        Examples
+        --------
+
+        >>> coord = np.arange(15).reshape(5,3)
+        >>> print(coord)
+        [[ 0  1  2]
+         [ 3  4  5]
+         [ 6  7  8]
+         [ 9 10 11]
+         [12 13 14]]
+        >>> # Rotates 90 degrees around the z-axis
+        >>> transform = AffineTransformation(
+        ...     center_translation=np.array([0,0,0]),
+        ...     rotation=np.array([
+        ...         [0, -1,  0],
+        ...         [1,  0,  0],
+        ...         [0,  0,  1]
+        ...     ]),
+        ...     target_translation=np.array([0,0,0])
+        ... )
+        >>> print(transform.apply(coord))
+        [[ -1.   0.   2.]
+         [ -4.   3.   5.]
+         [ -7.   6.   8.]
+         [-10.   9.  11.]
+         [-13.  12.  14.]]
+        """
+        mobile_coord = coord(atoms)
+        original_shape = mobile_coord.shape
+        mobile_coord = _reshape_to_3d(mobile_coord)
+        if (
+            self.rotation.shape[0] != 1
+            and mobile_coord.shape[0] != self.rotation.shape[0]
+        ):
+            raise IndexError(
+                f"Number of transformations is {self.rotation.shape[0]}, "
+                f"but number of structure models is {mobile_coord.shape[0]}"
+            )
+
+        superimposed_coord = mobile_coord.copy()
+        superimposed_coord += self.center_translation[:, np.newaxis, :]
+        superimposed_coord = _multi_matmul(self.rotation, superimposed_coord)
+        superimposed_coord += self.target_translation[:, np.newaxis, :]
+
+        superimposed_coord = superimposed_coord.reshape(original_shape)
+        if isinstance(atoms, np.ndarray):
+            return superimposed_coord
+        else:
+            superimposed = atoms.copy()
+            superimposed.coord = superimposed_coord
+            return superimposed
+
+    def as_matrix(self):
+        """
+        Get the translations and rotation as a combined 4x4
+        transformation matrix.
+
+        Multiplying this matrix with coordinates in the form
+        *(x, y, z, 1)* will apply the same transformation as
+        :meth:`apply()` to coordinates in the form *(x, y, z)*.
+
+        Returns
+        -------
+        transformation_matrix : ndarray, shape=(m,4,4), dtype=float
+            The transformation matrix.
+            *m* is the number of models in the transformation.
+
+        Examples
+        --------
+
+        >>> coord = np.arange(15).reshape(5,3)
+        >>> print(coord)
+        [[ 0  1  2]
+         [ 3  4  5]
+         [ 6  7  8]
+         [ 9 10 11]
+         [12 13 14]]
+        >>> # Rotates 90 degrees around the z-axis
+        >>> transform = AffineTransformation(
+        ...     center_translation=np.array([0,0,0]),
+        ...     rotation=np.array([
+        ...         [0, -1,  0],
+        ...         [1,  0,  0],
+        ...         [0,  0,  1]
+        ...     ]),
+        ...     target_translation=np.array([0,0,0])
+        ... )
+        >>> print(transform.apply(coord))
+        [[ -1.   0.   2.]
+         [ -4.   3.   5.]
+         [ -7.   6.   8.]
+         [-10.   9.  11.]
+         [-13.  12.  14.]]
+        >>> # Use a 4x4 matrix for transformation as alternative
+        >>> coord_4 = np.concatenate([coord, np.ones((len(coord), 1))], axis=-1)
+        >>> print(coord_4)
+        [[ 0.  1.  2.  1.]
+         [ 3.  4.  5.  1.]
+         [ 6.  7.  8.  1.]
+         [ 9. 10. 11.  1.]
+         [12. 13. 14.  1.]]
+        >>> print((transform.as_matrix()[0] @ coord_4.T).T)
+        [[ -1.   0.   2.   1.]
+         [ -4.   3.   5.   1.]
+         [ -7.   6.   8.   1.]
+         [-10.   9.  11.   1.]
+         [-13.  12.  14.   1.]]
+        """
+        n_models = self.rotation.shape[0]
+        rotation_mat = _3d_identity(n_models, 4)
+        rotation_mat[:, :3, :3] = self.rotation
+        center_translation_mat = _3d_identity(n_models, 4)
+        center_translation_mat[:, :3, 3] = self.center_translation
+        target_translation_mat = _3d_identity(n_models, 4)
+        target_translation_mat[:, :3, 3] = self.target_translation
+        return target_translation_mat @ rotation_mat @ center_translation_mat
+
+    def __eq__(self, other):
+        if not isinstance(other, AffineTransformation):
+            return False
+        if not np.array_equal(self.center_translation, other.center_translation):
+            return False
+        if not np.array_equal(self.rotation, other.rotation):
+            return False
+        if not np.array_equal(self.target_translation, other.target_translation):
+            return False
+        return True
+
+
+def _expand_dims(array, n_dims):
+    """
+    Expand the dimensions of an `ndarray` to a certain number of
+    dimensions.
+    """
+    while array.ndim < n_dims:
+        array = array[np.newaxis, ...]
+    return array
+
+
+def _3d_identity(m, n):
+    """
+    Create an array of *m* identity matrices of shape *(n, n)*
+    """
+    matrices = np.zeros((m, n, n), dtype=float)
+    indices = np.arange(n)
+    matrices[:, indices, indices] = 1
+    return matrices
+
+
+def _reshape_to_3d(coord):
+    """
+    Reshape the coordinate array to 3D, if it is 2D.
+    """
+    if coord.ndim < 2:
+        raise ValueError("Coordinates must be at least two-dimensional")
+    if coord.ndim == 2:
+        return coord[np.newaxis, ...]
+    elif coord.ndim == 3:
+        return coord
+    else:
+        raise ValueError("Coordinates must be at most three-dimensional")
+
+
 def translate(atoms, vector):
     """
     Translate the given atoms or coordinates by a given vector.
@@ -33,7 +239,7 @@ def translate(atoms, vector):
     atoms : Atom or AtomArray or AtomArrayStack or ndarray, shape=(3,) or shape=(n,3) or shape=(m,n,3)
         The atoms of which the coordinates are transformed.
         The coordinates can be directly provided as :class:`ndarray`.
-    vector: array-like, shape=(3,) or shape=(n,3) or shape=(m,n,3)
+    vector : array-like, shape=(3,) or shape=(n,3) or shape=(m,n,3)
         The translation vector :math:`(x, y, z)`.
 
     Returns
@@ -64,7 +270,7 @@ def rotate(atoms, angles):
     atoms : Atom or AtomArray or AtomArrayStack or ndarray, shape=(3,) or shape=(n,3) or shape=(m,n,3)
         The atoms of which the coordinates are transformed.
         The coordinates can be directly provided as :class:`ndarray`.
-    angles: array-like, length=3
+    angles : array-like, length=3
         The rotation angles in radians around *x*, *y* and *z*.
 
     Returns
@@ -75,8 +281,8 @@ def rotate(atoms, angles):
 
     See Also
     --------
-    rotate_centered
-    rotate_about_axis
+    rotate_centered : Rotate atoms about the centroid.
+    rotate_about_axis : Rotate atoms about a given axis.
 
     Examples
     --------
@@ -136,7 +342,7 @@ def rotate_centered(atoms, angles):
     atoms : Atom or AtomArray or AtomArrayStack or ndarray, shape=(3,) or shape=(n,3) or shape=(m,n,3)
         The atoms of which the coordinates are transformed.
         The coordinates can be directly provided as :class:`ndarray`.
-    angles: array-like, length=3
+    angles : array-like, length=3
         The rotation angles in radians around axes *x*, *y* and *z*.
 
     Returns
@@ -147,9 +353,12 @@ def rotate_centered(atoms, angles):
 
     See Also
     --------
-    rotate
-    rotate_about_axis
+    rotate : Rotate atoms about the origin.
+    rotate_about_axis : Rotate atoms about a given axis.
     """
+    # Avoid circular import
+    from biotite.structure.geometry import centroid
+
     if len(coord(atoms).shape) == 1:
         # Single value -> centered rotation does not change coordinates
         return atoms.copy()
@@ -193,8 +402,8 @@ def rotate_about_axis(atoms, axis, angle, support=None):
 
     See Also
     --------
-    rotate
-    rotate_centered
+    rotate : Rotate atoms about the origin.
+    rotate_centered : Rotate atoms about the centroid.
 
     Examples
     --------
@@ -293,11 +502,6 @@ def orient_principal_components(atoms, order=None):
         The atoms with coordinates centered at the orgin and aligned with
         xyz axes.
 
-    See Also
-    --------
-    rotate_centered
-    rotate_about_axis
-
     Examples
     --------
     Align principal components to xyz axes (default), or specify the order
@@ -321,8 +525,7 @@ def orient_principal_components(atoms, order=None):
     row, col = coords.shape
     if (row < 3) or (col != 3):
         raise ValueError(
-            f"Expected at least 3 entries, {row} given,"
-            f" and 3 dimensions, {col} given."
+            f"Expected at least 3 entries, {row} given, and 3 dimensions, {col} given."
         )
     if order is None:
         order = np.array([0, 1, 2])
@@ -400,11 +603,6 @@ def align_vectors(
         A copy of the input atoms or coordinates with the applied
         transformation.
 
-    See Also
-    --------
-    rotate
-    rotate_centered
-
     Examples
     --------
     Align two different residues at their CA-CB bond, i.e. the CA and CB
@@ -467,13 +665,11 @@ def align_vectors(
     # check that original and target direction are vectors of shape (3,)
     if origin_direction.shape != (3,):
         raise ValueError(
-            f"Expected origin vector to have shape (3,), "
-            f"got {origin_direction.shape}"
+            f"Expected origin vector to have shape (3,), got {origin_direction.shape}"
         )
     if target_direction.shape != (3,):
         raise ValueError(
-            f"Expected target vector to have shape (3,), "
-            f"got {target_direction.shape}"
+            f"Expected target vector to have shape (3,), got {target_direction.shape}"
         )
     if np.linalg.norm(origin_direction) == 0:
         raise ValueError("Length of the origin vector is 0")
@@ -528,3 +724,13 @@ def _put_back(input_atoms, transformed):
         return moved_atoms
     else:
         return transformed
+
+
+def _multi_matmul(matrices, vectors):
+    """
+    Calculate the matrix multiplication of m matrices
+    with m x n vectors.
+    """
+    return np.transpose(
+        np.matmul(matrices, np.transpose(vectors, axes=(0, 2, 1))), axes=(0, 2, 1)
+    )

biotite/structure/util.py

@@ -3,7 +3,7 @@
 # information.
 
 """
-Utility functions for in internal use in `Bio.Structure` package
+Utility functions for in internal use in `Bio.Structure` package.
 """
 
 __name__ = "biotite.structure"
@@ -28,7 +28,7 @@ def vector_dot(v1, v2):
 
     Parameters
     ----------
-    v1,v2 : ndarray
+    v1, v2 : ndarray
         The arrays to calculate the product from.
         The vectors are represented by the last axis.
 
@@ -63,7 +63,7 @@ def distance(v1, v2):
 
     Parameters
     ----------
-    v1,v2 : ndarray
+    v1, v2 : ndarray
         The arrays to calculate the product from.
         The vectors are represented by the last axis.
 

biotite/version.py

@@ -1,8 +1,13 @@
-# file generated by setuptools_scm
+# file generated by setuptools-scm
 # don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
 TYPE_CHECKING = False
 if TYPE_CHECKING:
-    from typing import Tuple, Union
+    from typing import Tuple
+    from typing import Union
+
     VERSION_TUPLE = Tuple[Union[int, str], ...]
 else:
     VERSION_TUPLE = object
@@ -12,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '1.1.0'
-__version_tuple__ = version_tuple = (1, 1, 0)
+__version__ = version = '1.3.0'
+__version_tuple__ = version_tuple = (1, 3, 0)

biotite/visualize.py

@@ -4,12 +4,16 @@
 
 __name__ = "biotite"
 __author__ = "Patrick Kunzmann"
-__all__ = ["colors", "set_font_size_in_coord", "AdaptiveFancyArrow"]
+__all__ = ["colors", "plot_scaled_text", "set_font_size_in_coord", "AdaptiveFancyArrow"]
 
+import warnings
 from collections import OrderedDict
 import numpy as np
 from numpy.linalg import norm
 
+_FONT_PROPERTY_KEYS = ["family", "style", "variant", "weight", "stretch", "size"]
+
+
 # Biotite themed colors
 colors = OrderedDict(
     [
@@ -27,6 +31,105 @@ colors = OrderedDict(
 )
 
 
+def plot_scaled_text(
+    axes, text, x, y, width=None, height=None, mode="unlocked", **kwargs
+):
+    """
+    Create a :class:`matplotlib.textpath.TextPath`, whose text size is given in
+    coordinates instead of font size.
+
+    Parameters
+    ----------
+    axes : Axes
+        The axes to draw the text on.
+    text : str
+        The text to be drawn.
+    x, y : float
+        The lower left position of the text.
+    width, height : float, optional
+        The width/height `text` should have in its reference coordinate system.
+        At least one value must be supplied.
+    mode : {'proportional', 'unlocked', 'maximum', 'minimum'}, optional
+        Defines how the text size is scaled.
+        The scaling mode:
+
+            - *proportional* - The width and height are scaled by the
+              same extent.
+              Either `width` or `height` must be set for this mode.
+            - *unlocked* - The width and the height are scaled by
+              different extents, changing the aspect ratio of the text.
+              Both `width` and `height` must be set for this mode.
+            - *maximum* - The width and the height are scaled by
+              the same extent, so that they are at maximum as large
+              as the supplied `width`/`height`.
+              Both `width` and `height` must be set for this mode.
+            - *minimum* - The width and the height are scaled by
+              the same extent, so that they are at minimum as large
+              as the supplied `width`/`height`.
+              Both `width` and `height` must be set for this mode.
+
+    **kwargs
+        Additional parameters for the :class:`matplotlib.font_manager.FontProperties`
+        of the text or the created :class:`matplotlib.patches.PathPatch`.
+
+    Returns
+    -------
+    patch : matplotlib.patches.PathPatch
+        The patch that represents the text.
+    """
+    from matplotlib.patches import PathPatch
+    from matplotlib.textpath import TextPath
+    from matplotlib.transforms import Affine2D
+
+    # The larger the size, the more there is an offset at the x-axis
+    # -> Keep font size small to reduce this error to a minimum
+    # The size is transformed to the desired size afterwards anyway
+    font_property_kwargs = {
+        key: kwargs.pop(key) for key in _FONT_PROPERTY_KEYS if key in kwargs
+    }
+    path = TextPath((x, y), text, size=1e-3, prop=font_property_kwargs)
+    bbox = path.get_extents()
+
+    if mode == "proportional":
+        if width is None:
+            # Proportional scaling based on height
+            scale_y = height / bbox.height
+            scale_x = scale_y
+        elif height is None:
+            # Proportional scaling based on width
+            scale_x = width / bbox.width
+            scale_y = scale_x
+        else:
+            raise ValueError(
+                "width or height are mutually exclusive in 'proportional' mode"
+            )
+    elif mode == "unlocked":
+        scale_x = width / bbox.width
+        scale_y = height / bbox.height
+    elif mode == "minimum":
+        scale_x = width / bbox.width
+        scale_y = height / bbox.height
+        scale = max(scale_x, scale_y)
+        scale_x, scale_y = scale, scale
+    elif mode == "maximum":
+        scale_x = width / bbox.width
+        scale_y = height / bbox.height
+        scale = min(scale_x, scale_y)
+        scale_x, scale_y = scale, scale
+
+    path = (
+        Affine2D()
+        .translate(-bbox.x0, -bbox.y0)
+        .scale(scale_x, scale_y)
+        .translate(bbox.x0, bbox.y0)
+        .transform_path(path)
+    )
+    patch = PathPatch(path, **kwargs)
+    axes.add_patch(patch)
+
+    return patch
+
+
 def set_font_size_in_coord(text, width=None, height=None, mode="unlocked"):
     """
     Specifiy the font size of an existing `Text` object in coordinates
@@ -38,6 +141,8 @@ def set_font_size_in_coord(text, width=None, height=None, mode="unlocked"):
     The scaling can be proportional or non-proportional, depending
     the `mode`.
 
+    DEPRECATED: Use :func:`plot_scaled_text()` instead.
+
     Parameters
     ----------
     text : Text:
@@ -125,6 +230,11 @@ def set_font_size_in_coord(text, width=None, height=None, mode="unlocked"):
             affine = Affine2D().scale(scale_x, scale_y) + affine
             renderer.draw_path(gc, tpath, affine, rgbFace)
 
+    warnings.warn(
+        "Deprecated, use 'biotite.graphics.text.plot_scaled_text()' instead.",
+        DeprecationWarning,
+    )
+
     if mode in ["unlocked", "minimum", "maximum"]:
         if width is None or height is None:
             raise TypeError(f"Width and height must be set in '{mode}' mode")

{biotite-1.1.0.dist-info → biotite-1.3.0.dist-info}/METADATA

@@ -1,46 +1,16 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: biotite
-Version: 1.1.0
+Version: 1.3.0
 Summary: A comprehensive library for computational molecular biology
 Project-URL: homepage, https://www.biotite-python.org
 Project-URL: repository, https://github.com/biotite-dev/biotite
 Project-URL: documentation, https://www.biotite-python.org
 Author: The Biotite contributors
-License: BSD 3-Clause License
-        --------------------
-        
-        Copyright 2017, The Biotite contributors
-        All rights reserved.
-        
-        Redistribution and use in source and binary forms, with or without modification,
-        are permitted provided that the following conditions are met:
-        
-        1. Redistributions of source code must retain the above copyright notice, this
-        list of conditions and the following disclaimer.
-        
-        2. Redistributions in binary form must reproduce the above copyright notice,
-        this list of conditions and the following disclaimer in the documentation and/or
-        other materials provided with the distribution.
-        
-        3. Neither the name of the copyright holder nor the names of its contributors
-        may be used to endorse or promote products derived from this software without
-        specific prior written permission.
-        
-        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
-        ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-        WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
-        ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
-        (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-        LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
-        ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-        (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-        SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+License-Expression: BSD-3-Clause
 License-File: LICENSE.rst
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
-Classifier: License :: OSI Approved :: BSD License
 Classifier: Natural Language :: English
 Classifier: Operating System :: MacOS
 Classifier: Operating System :: Microsoft :: Windows
@@ -48,14 +18,16 @@ Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Requires-Dist: biotraj<2.0,>=1.0
 Requires-Dist: msgpack>=0.5.6
 Requires-Dist: networkx>=2.0
 Requires-Dist: numpy>=1.25
+Requires-Dist: packaging>=24.0
 Requires-Dist: requests>=2.12
 Provides-Extra: lint
-Requires-Dist: ruff==0.6.9; extra == 'lint'
+Requires-Dist: numpydoc==1.8.0; extra == 'lint'
+Requires-Dist: ruff==0.9.7; extra == 'lint'
 Provides-Extra: test
 Requires-Dist: pytest; extra == 'test'
 Requires-Dist: pytest-codspeed; extra == 'test'
@@ -186,5 +158,5 @@ Contribution
 
 Interested in improving *Biotite*?
 Have a look at the
-`contribution guidelines <https://www.biotite-python.org/contribute.html>`_.
+`contribution guidelines <https://www.biotite-python.org/latest/contribution/index.html>`_.
 Feel free to join our community chat on `Discord <https://discord.gg/cUjDguF>`_.