biotite 1.0.1__cp312-cp312-macosx_11_0_arm64.whl → 1.2.0__cp312-cp312-macosx_11_0_arm64.whl

biotite/structure/util.py

@@ -3,14 +3,23 @@
 # information.
 
 """
-Utility functions for in internal use in `Bio.Structure` package
+Utility functions for in internal use in `Bio.Structure` package.
 """
 
 __name__ = "biotite.structure"
 __author__ = "Patrick Kunzmann"
-__all__ = ["vector_dot", "norm_vector", "distance", "matrix_rotate"]
+__all__ = [
+    "vector_dot",
+    "norm_vector",
+    "distance",
+    "matrix_rotate",
+    "coord_for_atom_name_per_residue",
+]
 
 import numpy as np
+from biotite.structure.atoms import AtomArrayStack
+from biotite.structure.error import BadStructureError
+from biotite.structure.residues import get_residue_masks, get_residue_starts
 
 
 def vector_dot(v1, v2):
@@ -19,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.
 
@@ -54,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.
 
@@ -94,3 +103,66 @@ def matrix_rotate(v, matrix):
     if orig_ndim > 2:
         v = v.reshape(*orig_shape)
     return v
+
+
+def coord_for_atom_name_per_residue(atoms, atom_names, mask=None):
+    """
+    Get the coordinates of a specific atom for every residue.
+
+    If a residue does not contain the specified atom, the coordinates are `NaN`.
+    If a residue contains multiple atoms with the specified name, an exception is
+    raised.
+
+    Parameters
+    ----------
+    atoms : AtomArray, shape=(n,) or AtomArrayStack, shape=(m,n)
+        The atom array or stack to get the residue-wise coordinates from.
+    atom_names : list of str, length=k
+        The atom names to get the coordinates for.
+    mask : ndarray, shape=(n,), dtype=bool, optional
+        A boolean mask to further select valid atoms from `atoms`.
+
+    Returns
+    -------
+    coord: ndarray, shape=(k, m, r, 3) or shape=(k, r, 3)
+        The coordinates of the specified atom for each residue.
+    """
+    is_multi_model = isinstance(atoms, AtomArrayStack)
+    residue_starts = get_residue_starts(atoms)
+    all_residue_masks = get_residue_masks(atoms, residue_starts)
+
+    if is_multi_model:
+        coord = np.full(
+            (len(atom_names), atoms.stack_depth(), len(residue_starts), 3),
+            np.nan,
+            dtype=np.float32,
+        )
+    else:
+        coord = np.full(
+            (len(atom_names), len(residue_starts), 3),
+            np.nan,
+            dtype=np.float32,
+        )
+
+    for i, atom_name in enumerate(atom_names):
+        specified_atom_mask = atoms.atom_name == atom_name
+        if mask is not None:
+            specified_atom_mask &= mask
+        all_residue_masks_for_specified_atom = all_residue_masks & specified_atom_mask
+        number_of_specified_atoms_per_residue = np.count_nonzero(
+            all_residue_masks_for_specified_atom, axis=-1
+        )
+        if np.any(number_of_specified_atoms_per_residue > 1):
+            raise BadStructureError(f"Multiple '{atom_name}' atoms per residue")
+        residues_with_specified_atom = number_of_specified_atoms_per_residue == 1
+        coord_of_specified_atoms = atoms.coord[..., specified_atom_mask, :]
+        if is_multi_model:
+            # Swap dimensions due to NumPy's behavior when using advanced indexing
+            # (https://numpy.org/devdocs/user/basics.indexing.html#combining-advanced-and-basic-indexing)
+            coord[i, ..., residues_with_specified_atom, :] = (
+                coord_of_specified_atoms.transpose(1, 0, 2)
+            )
+        else:
+            coord[i, residues_with_specified_atom, :] = coord_of_specified_atoms
+
+    return coord

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.0.1'
-__version_tuple__ = version_tuple = (1, 0, 1)
+__version__ = version = '1.2.0'
+__version_tuple__ = version_tuple = (1, 2, 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.0.1.dist-info → biotite-1.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: biotite
-Version: 1.0.1
+Version: 1.2.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
@@ -53,7 +53,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: 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'
@@ -184,5 +188,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>`_.