biotite 1.5.0__cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl

biotite/structure/graphics/__init__.py

@@ -0,0 +1,13 @@
+# This source code is part of the Biotite package and is distributed
+# under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
+# information.
+
+"""
+A subpackage for visualizing structure related objects.
+"""
+
+__name__ = "biotite.structure.graphics"
+__author__ = "Patrick Kunzmann, Tom David Müller"
+
+from .atoms import *
+from .rna import *

biotite/structure/graphics/atoms.py

@@ -0,0 +1,243 @@
+# This source code is part of the Biotite package and is distributed
+# under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
+# information.
+
+__name__ = "biotite.structure.graphics"
+__author__ = "Patrick Kunzmann"
+__all__ = ["plot_atoms", "plot_ball_and_stick_model"]
+
+import numpy as np
+from mpl_toolkits.mplot3d import Axes3D
+from mpl_toolkits.mplot3d.art3d import Line3DCollection
+
+
+def plot_atoms(
+    axes,
+    atoms,
+    colors,
+    line_width=1.0,
+    background_color=None,
+    center=None,
+    size=None,
+    zoom=1.0,
+):
+    """
+    Plot an :class:`AtomArray` as lines between bonded atoms.
+
+    The z-axis points into the screen plane.
+
+    Parameters
+    ----------
+    axes : Axes3D
+        The *Matplotlib* 3D-axes to plot the structure on.
+    atoms : AtomArray, shape=(n,)
+        The structure to be plotted.
+        The atom array must have an associated :class:`BondList`, i.e.
+        its ``bonds`` attribute must be defined.
+        One line for each bond is drawn.
+    colors : ndarray, shape=(n,3) or shape=(n,4), dtype=float
+        An array of RGB or RGBA colors for each atom in `atoms`.
+        The values for each color channel are in the range 0 to 1.
+    line_width : float, optional
+        The width of the lines to be drawn.
+    background_color : object
+        A *Matplotlib* compatible color (color name or RGB values).
+        If set, the background is colored with the given value.
+    center : tuple of (float, float, float), optional
+        The coordinates of the structure that are in the center of the
+        plot.
+        By default the complete molecule is centered.
+    size : float, optional
+        The size of each dimension in the plot.
+        The limits of the :class:`Axes3D` are set to
+        ``(center - size/(2*zoom)), (center + size/(2*zoom))``.
+    zoom : float, optional
+        Zoom in or zoom out.
+
+        - ``> 1.0``: Zoom in.
+        - ``< 1.0``: Zoom out.
+
+    Notes
+    -----
+    This is a very simple visualization tools for quick visual analysis
+    of a structure.
+    For publication-ready molecular images the usage of a dedicated
+    molecular visualization tool is recommended.
+    """
+    if not isinstance(axes, Axes3D):
+        raise ValueError("The given axes mut be an 'Axes3D'")
+    if atoms.bonds is None:
+        raise ValueError("The atom array must have an associated bond list")
+
+    # Calculating connections between atoms
+    line_coord = []
+    line_colors = []
+    for index1, index2 in atoms.bonds.as_array()[:, :2]:
+        # Every connection consist of two lines:
+        # One from the first atom to the center
+        # and from from the second atom to the center
+        line_start = atoms.coord[index1]
+        line_end = atoms.coord[index2]
+        line_center = (line_start + line_end) / 2
+
+        # Add line from first atom
+        line_coord.append((line_start, line_center))
+        line_colors.append(colors[index1])
+
+        # Add line from second atom
+        line_coord.append((line_end, line_center))
+        line_colors.append(colors[index2])
+
+    # Plot computed line coordinates and colors
+    # Use 'Line3DCollection' for higher efficiency
+    lines = Line3DCollection(
+        line_coord,
+        color=line_colors,
+        linewidths=line_width,
+        capstyle="round",
+        joinstyle="round",
+    )
+    axes.add_collection(lines)
+
+    # Set viewing angle
+    axes.azim = -90
+    axes.elev = 90
+    # Remove frame
+    axes.axis("off")
+    # Set background color
+    if background_color is not None:
+        axes.set_facecolor(background_color)
+        axes.get_figure().set_facecolor(background_color)
+    _set_box(axes, atoms.coord, center, size, zoom)
+
+
+def plot_ball_and_stick_model(
+    axes,
+    atoms,
+    colors,
+    ball_size=200,
+    line_color="black",
+    line_width=1.0,
+    background_color=None,
+    center=None,
+    size=None,
+    zoom=1.0,
+):
+    """
+    Plot an :class:`AtomArray` as *ball-and-stick* model.
+
+    The z-axis points into the screen plane.
+
+    UNSTABLE: This function is probably subject to future changes.
+
+    Parameters
+    ----------
+    axes : Axes3D
+        The *Matplotlib* 3D-axes to plot the structure on.
+    atoms : AtomArray, length=n
+        The structure to be plotted.
+        The atom array must have an associated :class:`BondList`, i.e.
+        its ``bonds`` attribute must be defined.
+        One line for each bond is drawn.
+    colors : ndarray, shape=(n,3) or shape=(n,4), dtype=float
+        An array of RGB or RGBA colors for each atom in `atoms`, that
+        is used to color the *balls* of the model.
+        The values for each color channel are in the range 0 to 1.
+    ball_size : int or iterable of int, shape=(n,)
+        The size of the *balls* in the model in *pt*.
+        Either a single value for all atoms or an iterable object of
+        values for each atom.
+    line_color : object
+        A *Matplotlib* compatible color value for the *sticks* of the
+        model.
+    line_width : float, optional
+        The width of the *sticks* in the model in *pt*.
+    background_color : object
+        A *Matplotlib* compatible color (color name or RGB values).
+        If set, the background is colored with the given value.
+    center : tuple of (float, float, float), optional
+        The coordinates of the structure that are in the center of the
+        plot.
+        By default the complete molecule is centered.
+    size : float, optional
+        The size of each dimension in the plot.
+        The limits of the :class:`Axes3D` are set to
+        ``(center - size/(2*zoom)), (center + size/(2*zoom))``.
+    zoom : float, optional
+        Zoom in or zoom out.
+
+        - ``> 1.0``: Zoom in.
+        - ``< 1.0``: Zoom out.
+
+    Notes
+    -----
+    This is a very simple visualization tools for quick visual analysis
+    of a structure.
+    For publication-ready molecular images the usage of a dedicated
+    molecular visualization tool is recommended.
+    """
+    if not isinstance(axes, Axes3D):
+        raise ValueError("The given axes mut be an 'Axes3D'")
+    if atoms.bonds is None:
+        raise ValueError("The atom array must have an associated bond list")
+
+    # Calculating connections between atoms
+    line_coord = [
+        (atoms.coord[index1], atoms.coord[index2])
+        for index1, index2 in atoms.bonds.as_array()[:, :2]
+    ]
+
+    # Plot sticks
+    # Use 'Line3DCollection' for higher efficiency
+    sticks = Line3DCollection(
+        line_coord,
+        color=line_color,
+        linewidths=line_width,
+        capstyle="round",
+        joinstyle="round",
+    )
+    axes.add_collection(sticks)
+
+    # Plot balls
+    axes.scatter(*atoms.coord.T, s=ball_size, c=colors, linewidth=0, alpha=1)
+
+    # Set viewing angle
+    axes.azim = -90
+    axes.elev = 90
+    # Remove frame
+    axes.axis("off")
+    # Set background color
+    if background_color is not None:
+        axes.set_facecolor(background_color)
+        axes.get_figure().set_facecolor(background_color)
+    _set_box(axes, atoms.coord, center, size, zoom)
+
+
+def _set_box(axes, coord, center, size, zoom):
+    """
+    This ensures an approximately equal aspect ratio in a 3D plot under
+    the condition, that the :class:`Axes` is quadratic on the display.
+    """
+    if center is None:
+        center = (
+            (coord[:, 0].max() + coord[:, 0].min()) / 2,
+            (coord[:, 1].max() + coord[:, 1].min()) / 2,
+            (coord[:, 2].max() + coord[:, 2].min()) / 2,
+        )
+
+    if size is None:
+        size = np.array(
+            [
+                coord[:, 0].max() - coord[:, 0].min(),
+                coord[:, 1].max() - coord[:, 1].min(),
+                coord[:, 2].max() - coord[:, 2].min(),
+            ]
+        ).max()
+
+    axes.set_xlim(center[0] - size / (2 * zoom), center[0] + size / (2 * zoom))
+    axes.set_ylim(center[1] - size / (2 * zoom), center[1] + size / (2 * zoom))
+    axes.set_zlim(center[2] - size / (2 * zoom), center[2] + size / (2 * zoom))
+
+    # Make the axis lengths of the 'plot box' equal
+    # The 'plot box' is not visible due to 'axes.axis("off")'
+    axes.set_box_aspect([1, 1, 1])

biotite/structure/graphics/rna.py

@@ -0,0 +1,298 @@
+# This source code is part of the Biotite package and is distributed
+# under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
+# information.
+
+__name__ = "biotite.structure.graphics"
+__author__ = "Tom David Müller"
+__all__ = ["plot_nucleotide_secondary_structure"]
+
+import shutil
+from itertools import repeat
+import numpy as np
+from biotite.application.viennarna import RNAplotApp
+from biotite.structure import pseudoknots
+
+
+def plot_nucleotide_secondary_structure(
+    axes,
+    base_labels,
+    base_pairs,
+    length,
+    layout_type=RNAplotApp.Layout.NAVIEW,
+    draw_pseudoknots=True,
+    pseudoknot_order=None,
+    angle=0,
+    bond_linewidth=1,
+    bond_linestyle=None,
+    bond_color="black",
+    backbone_linewidth=1,
+    backbone_linestyle="solid",
+    backbone_color="grey",
+    base_text=None,
+    base_box=None,
+    annotation_positions=None,
+    annotation_offset=8.5,
+    annotation_text=None,
+    border=0.03,
+    bin_path="RNAplot",
+):
+    """
+    Generate 2D plots of nucleic acid secondary structures using the
+    interface to *RNAplot*, which is part of the *ViennaRNA* software
+    package.
+
+    Internally a :class:`biotite.application.viennarna.RNAplotApp`
+    instance is created to generate coordinates for each individual base
+    on a 2D plane. *ViennaRNA* must be installed in order to use this
+    function.
+
+    Parameters
+    ----------
+    axes : Axes
+        A *Matplotlib* axes, that is used as plotting area.
+    base_labels : iterable
+        The labels denoting the type of each base.
+    base_pairs : ndarray, shape=(n,2)
+        Each row corresponds to the positions of the bases in the
+        sequence. The positions are counted from zero.
+    length : int
+        The number of bases in the sequence.
+    layout_type : RNAplotApp.Layout, optional
+        The layout type according to the *RNAplot* documentation.
+    draw_pseudoknots : bool, optional
+        Whether pseudoknotted bonds should be drawn.
+    pseudoknot_order : iterable, optional
+        The pseudoknot order of each pair in the input `base_pairs`.
+        If no pseudoknot order is given, a solution determined by
+        :func:`biotite.structure.pseudoknots` is picked at random.
+    angle : int or float, optional
+        The angle the plot should be rotated.
+    bond_linewidth : float or int or iterable, optional
+        The linewidth of each bond. Provide a single value to set the
+        linewidth for all bonds or an iterable to set the linewidth for
+        each individual bond.
+    bond_linestyle : str or iterable, optional
+        The *Matplotlib* compatible linestyle of each bond. Provide a
+        single value to set the linewidth for all bonds or an iterable
+        to set the linewidth for each individual bond. By default, solid
+        lines are used for non-pseudoknotted bonds and dashed lines are
+        used for pseudoknotted bonds.
+    bond_color : str or ndarray, shape(n,) or shape(n,3) or shape(n,4), optional
+        The *Matplotlib* compatible color of each bond. Provide a single
+        string to set the color for all bonds or an array to set the
+        color for each individual bond.
+    backbone_linewidth : float, optional
+        The linewidth of the backbone.
+    backbone_linestyle : str, optional
+        The *Matplotlib* compatible linestyle of the backbone.
+    backbone_color : str or ndarray, shape=(3,) or shape=(4,), dtype=float, optional
+        The *Matplotlib* compatible color of the backbone.
+    base_text : dict or iterable, optional
+        The keyword parameters for the *Matplotlib* ``Text`` objects
+        denoting the type of each base. Provide a single value to set
+        the parameters for all labels or an iterable to set the
+        parameters for each individual label.
+        The default is ``{'size': 'small'}``.
+    base_box : dict or iterable, optional)
+        The *Matplotlib* compatible properties of the ``FancyBboxPatch``
+        surrounding the base labels. Provide a single dictionary to
+        set the properties of all base lables or an iterable to set the
+        properties for each individual label.
+        The default is ``{'pad'=0, 'color'='white'}``.
+    annotation_positions : iterable, optional
+        The positions of the bases to be numbered. By default every
+        second base is annotated. Please note that while the positions
+        in the sequence are counted from zero, they are displayed on the
+        graph counted from one.
+    annotation_offset : int or float, optional
+        The offset of the annotations from the base labels.
+    annotation_text : dict or iterable, optional
+        The keyword parameters for the *Matplotlib* ``Text`` objects
+        annotating the sequence. Provide a single value to set the
+        parameters for all annotations or an iterable to set the
+        parameters for each individual annotation.
+        The default is ``{'size': 'small'}``.
+    border : float, optional
+        The percentage of the coordinate range to be left as whitespace
+        to create a border around the plot.
+    bin_path : str, optional
+        Path to the *RNAplot* binary.
+    """
+
+    # Check if RNAplot is installed
+    if shutil.which(bin_path) is None:
+        raise FileNotFoundError(
+            "RNAplot is not installed at the specified location, unable to "
+            "plot secondary structure."
+        )
+
+    # Get the unknotted base pairs
+    if pseudoknot_order is None:
+        # Get a random unknotted structure retaining the maximum number
+        # of base pairs.
+        pseudoknot_order = pseudoknots(base_pairs, max_pseudoknot_order=0)[0]
+    unknotted_base_pairs = base_pairs[pseudoknot_order == 0]
+
+    # If `bond_linewidth` is a single value, extrapolate
+    if isinstance(bond_linewidth, int) or isinstance(bond_linewidth, float):
+        bond_linewidth = np.full(base_pairs.shape[0], bond_linewidth)
+
+    # If `bond_color` is not an array, extrapolate
+    if not isinstance(bond_color, np.ndarray):
+        bond_color = np.full(base_pairs.shape[0], bond_color)
+
+    # Set the default properties of the Matplotlib `bbox` surrounding
+    # the base labels
+    if base_box is None:
+        base_box = np.full(length, {"pad": 0, "color": "white"})
+    # if `base_box` is a dictionary, extrapolate
+    elif isinstance(base_box, dict):
+        base_box = np.full(length, base_box)
+
+    # By default pseudoknotted bonds are denoted as dashed lines, while
+    # unknotted bonds are denoted as solid lines
+    if bond_linestyle is None:
+        bond_linestyle = np.full(base_pairs.shape[0], "solid", dtype="object")
+        bond_linestyle[pseudoknot_order != 0] = "dashed"
+    # If `bond_linestyle` is a string, extrapolate
+    elif isinstance(bond_linestyle, str):
+        bond_linestyle = np.full(base_pairs.shape[0], bond_linestyle, dtype="object")
+
+    # If pseudoknots are not to be drawn, remove pseudoknotted bonds,
+    # regardless of the given linestyles
+    if not draw_pseudoknots:
+        # Ensure that the array can hold the 'None' value
+        # (not possible with 'U1' dtype for example)
+        bond_linestyle = np.asarray(bond_linestyle, dtype="object")
+        bond_linestyle[pseudoknot_order != 0] = "None"
+
+    # Set the default properties of the base labels
+    if base_text is None:
+        base_text = np.full(length, {"size": "small"})
+    elif isinstance(base_text, dict):
+        base_text = np.full(length, base_text)
+
+    # If no specific annotation positions are given, annotate every
+    # second base pair
+    if annotation_positions is None:
+        annotation_positions = range(0, length, 2)
+
+    # Set the default font properties of the base annotations
+    if annotation_text is None:
+        annotation_text = repeat({"size": "small"})
+    elif isinstance(annotation_text, dict):
+        annotation_text = repeat(annotation_text)
+
+    # Get coordinates for secondary structure plot
+    coordinates = RNAplotApp.compute_coordinates(
+        base_pairs=unknotted_base_pairs,
+        length=length,
+        bin_path=bin_path,
+        layout_type=layout_type,
+    )
+
+    # Rotate Coordinates
+    if angle != 0:
+        angle = np.deg2rad(angle)
+        rot_matrix = np.array(
+            [[np.cos(angle), -np.sin(angle)], [np.sin(angle), np.cos(angle)]]
+        )
+        for i, coord in enumerate(coordinates):
+            coordinates[i] = np.dot(rot_matrix, coord)
+
+    # Remove axes and frame
+    axes.set_xticks([])
+    axes.set_yticks([])
+    axes.xaxis.set_tick_params(
+        top=False, bottom=False, labeltop=False, labelbottom=False
+    )
+    axes.yaxis.set_tick_params(
+        top=False, bottom=False, labeltop=False, labelbottom=False
+    )
+    axes.set_frame_on(False)
+
+    # Define buffer area (Border)
+    coord_range = abs(np.max(coordinates)) + abs(np.min(coordinates))
+    buffer = border * coord_range
+
+    # Adjust display
+    axes.set_xlim(
+        np.min(coordinates[:, 0]) - buffer, np.max(coordinates[:, 0]) + buffer
+    )
+    axes.set_ylim(
+        np.min(coordinates[:, 1]) - buffer, np.max(coordinates[:, 1]) + buffer
+    )
+    axes.set_aspect(aspect="equal")
+
+    # Draw backbone
+    axes.plot(
+        coordinates[:, 0],
+        coordinates[:, 1],
+        color=backbone_color,
+        linestyle=backbone_linestyle,
+        linewidth=backbone_linewidth,
+    )
+
+    # Draw base labels
+    for coords, label, box, text in zip(coordinates, base_labels, base_box, base_text):
+        t = axes.text(
+            x=coords[0], y=coords[1], s=label, ha="center", va="center", **text
+        )
+        t.set_bbox(box)
+
+    # Draw bonds
+    for (base1, base2), color, style, width in zip(
+        base_pairs, bond_color, bond_linestyle, bond_linewidth
+    ):
+        base1_coords = coordinates[base1]
+        base2_coords = coordinates[base2]
+        x = base1_coords[0], base2_coords[0]
+        y = base1_coords[1], base2_coords[1]
+        axes.plot(x, y, color=color, linestyle=style, linewidth=width)
+
+    # Draw annotations
+    for i, text in zip(annotation_positions, annotation_text):
+        if (i > 0) and ((i + 1) < length):
+            # Get the average of the direction vectors to the next and
+            # previous base
+            vector_to_previous = np.array(
+                [
+                    coordinates[i - 1][0] - coordinates[i][0],
+                    coordinates[i - 1][1] - coordinates[i][1],
+                ]
+            )
+            vector_to_previous = vector_to_previous / np.linalg.norm(vector_to_previous)
+            vector_to_next = np.array(
+                [
+                    coordinates[i][0] - coordinates[i + 1][0],
+                    coordinates[i][1] - coordinates[i + 1][1],
+                ]
+            )
+            vector_to_next = vector_to_next / np.linalg.norm(vector_to_next)
+            vector = (vector_to_next + vector_to_previous) / 2
+        elif i > 0:
+            # For the last base get the direction vector to the previous
+            # base
+            vector = np.array(
+                [
+                    coordinates[i - 1][0] - coordinates[i][0],
+                    coordinates[i - 1][1] - coordinates[i][1],
+                ]
+            )
+        else:
+            # For the first base get the direction vector to the next
+            # base
+            vector = np.array(
+                [
+                    coordinates[i][0] - coordinates[i + 1][0],
+                    coordinates[i][1] - coordinates[i + 1][1],
+                ]
+            )
+        # Normalize the vector
+        vector = vector / np.linalg.norm(vector)
+        # Get the perpendicular vector
+        vector = np.array([vector[1], -vector[0]])
+        # The annotations are offset in the direction of the
+        # perpendicular vector
+        x, y = coordinates[i] + (annotation_offset * vector)
+        axes.text(x=x, y=y, s=i + 1, ha="center", va="center", **text)