biotite 0.41.1__cp312-cp312-macosx_10_16_arm64.whl

biotite/visualize.py

@@ -0,0 +1,251 @@
+# 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"
+__author__ = "Patrick Kunzmann"
+__all__ = ["colors", "set_font_size_in_coord", "AdaptiveFancyArrow"]
+
+import abc
+from collections import OrderedDict
+import numpy as np
+from numpy.linalg import norm
+
+
+# Biotite themed colors
+colors = OrderedDict([
+    ("brightorange" , "#ffb569ff"),
+    ("lightorange"  , "#ff982dff"),
+    ("orange"       , "#ff8405ff"),
+    ("dimorange"    , "#dc7000ff"),
+    ("darkorange"   , "#b45c00ff"),
+    ("brightgreen"  , "#98e97fff"),
+    ("lightgreen"   , "#6fe04cff"),
+    ("green"        , "#52da2aff"),
+    ("dimgreen"     , "#45bc20ff"),
+    ("darkgreen"    , "#389a1aff"),
+])
+
+
+def set_font_size_in_coord(text, width=None, height=None, mode="unlocked"):
+    """
+    Specifiy the font size of an existing `Text` object in coordinates
+    of the object's reference coordiante system.
+
+    Instead of having the font size fixed in 'pt', the size of the text
+    scales to the specied width/height and adapts to changes in the
+    plot's width/height.
+    The scaling can be proportional or non-proportional, depending
+    the `mode`.
+
+    Parameters
+    ----------
+    text : Text:
+        The matplotlib `Text` to be scaled.
+    width, height : float, optional
+        The new width/height of `text` in its
+        reference coordinate system.
+        At least one value must be supplied.
+    mode : {'proportional', 'unlocked', 'maximum', 'minimum'}, optional
+        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.
+              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.
+
+    Notes
+    -----
+    This function uses the :func:`get_window_extent()` method of the
+    :class:`Text` object.
+    According to experience, this function does not give the the exact
+    visual boundaries of the text.
+    Consequently, the scaled text might be slightly smaller or larger
+    than the specified width/height.
+    This behavior is not equal for all initial font sizes (in 'pt'),
+    the boundaries for an initial size of 1 'pt' seem to be most exact.
+    """
+    from matplotlib.transforms import Bbox, Affine2D
+    from matplotlib.patheffects import AbstractPathEffect
+
+    class TextScaler(AbstractPathEffect):
+        def __init__(self, text, width, height, mode):
+            self._text = text
+            self._mode = mode
+            self._width = width
+            self._height = height
+
+        def draw_path(self, renderer, gc, tpath, affine, rgbFace=None):
+            ax = self._text.axes
+            try:
+                renderer = ax.get_figure().canvas.get_renderer()
+            except:
+                # Use cached renderer for backends, where
+                # `get_renderer()` is not available
+                # Based on the strategy from `Text.get_window_extent()`
+                renderer = ax.get_figure()._cachedRenderer
+            if renderer is None:
+                raise
+            bbox = text.get_window_extent(renderer)
+            bbox = Bbox(ax.transData.inverted().transform(bbox))
+
+            if self._mode == "proportional":
+                if self._width is None:
+                    # Proportional scaling based on height
+                    scale_y = self._height / bbox.height
+                    scale_x = scale_y
+                elif self._height is None:
+                    # Proportional scaling based on width
+                    scale_x = self._width / bbox.width
+                    scale_y = scale_x
+            elif self._mode == "unlocked":
+                scale_x = self._width / bbox.width
+                scale_y = self._height / bbox.height
+            elif self._mode == "minimum":
+                scale_x = self._width / bbox.width
+                scale_y = self._height / bbox.height
+                scale = max(scale_x, scale_y)
+                scale_x, scale_y = scale, scale
+            elif self._mode == "maximum":
+                scale_x = self._width / bbox.width
+                scale_y = self._height / bbox.height
+                scale = min(scale_x, scale_y)
+                scale_x, scale_y = scale, scale
+
+            affine = Affine2D().scale(scale_x, scale_y) + affine
+            renderer.draw_path(gc, tpath, affine, rgbFace)
+
+    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"
+            )
+    elif mode == "proportional":
+        if  not (width  is None and height is not None) or \
+            not (height is None and width  is not None):
+                raise TypeError(
+                    f"Either width or height must be set in '{mode}' mode"
+                )
+    else:
+        raise ValueError(
+                f"Unknown mode '{mode}'"
+            )
+    text.set_path_effects([TextScaler(text, width, height, mode)])
+
+try:
+    # Only create this class when matplotlib is installed
+    from matplotlib.transforms import Bbox
+    from matplotlib.patches import FancyArrow
+
+    class AdaptiveFancyArrow(FancyArrow):
+        """
+        A `FancyArrow` with fixed head shape.
+
+        The length of the head is proportional to the width of the head
+        in display coordinates.
+        If the head length is longer than the length of the entire
+        arrow, the head length is limited to the arrow length.
+
+        Parameters
+        ----------
+        x,y  : float
+            The arrow's start position.
+        dx, dy : float
+            The arrow's direction vector, inclduing the arrow head.
+        tail_width, head_width : float
+            The width of the arrow's tail and head in its reference
+            coordinate system
+        head_ratio : float, optional
+            The length of the arrow head as faction of the arrow width
+            (display coordinates).
+        draw_head: bool, optional
+            If false, the arrow has no head. The result is a rectangle.
+        shape : str, optional
+            The `shape` parameter in the constructor of `FancyArrow`.
+        **kwargs
+            Other parameters that are used in the constructor of
+            `FancyArrow`.
+        """
+
+        def __init__(self, x, y, dx, dy,
+                     tail_width, head_width, head_ratio, draw_head=True,
+                     shape="full", **kwargs):
+            self._x = x
+            self._y = y
+            self._dx = dx
+            self._dy = dy
+            self._tail_width = tail_width
+            self._head_width = head_width
+            self._head_ratio = head_ratio
+            self._draw_head = draw_head
+            self._shape = shape
+            self._kwargs = kwargs
+            if not draw_head:
+                head_width = tail_width
+            super().__init__(
+                x, y, dx, dy,
+                width=tail_width, head_width=head_width,
+                overhang=0, shape=shape,
+                length_includes_head=True, **kwargs
+            )
+
+        def draw(self, renderer):
+            arrow_box = Bbox([(0,0), (0,self._head_width)])
+            arrow_box_display = self.axes.transData.transform_bbox(arrow_box)
+            head_length_display = np.abs(
+                arrow_box_display.height * self._head_ratio
+            )
+            arrow_box_display.x1 = arrow_box_display.x0 + head_length_display
+            # Transfrom back to data coordinates for plotting
+            arrow_box = self.axes.transData.inverted().transform_bbox(
+                arrow_box_display
+            )
+            head_length = arrow_box.width
+            arrow_length = norm((self._dx, self._dy))
+            if head_length > arrow_length:
+                # If the head would be longer than the entire arrow,
+                # only draw the arrow head with reduced length
+                head_length = arrow_length
+            if not self._draw_head:
+                head_length = 0
+
+            # Renew the arrow's properties
+            super().__init__(
+                self._x, self._y, self._dx, self._dy,
+                width=self._tail_width, head_width=self._head_width,
+                overhang=0, shape=self._shape,
+                head_length=head_length, length_includes_head=True,
+                axes=self.axes, transform=self.get_transform(), **self._kwargs
+            )
+            self.set_clip_path(self.axes.patch)
+            super().draw(renderer)
+
+        # Override to replace docstring
+        # Removes warning:
+        # unknown document: /tutorials/intermediate/constrainedlayout_guide
+        def get_in_layout(self):
+            """
+            """
+            return super().get_in_layout()
+        def set_in_layout(self, in_layout):
+            """
+            """
+            return super().set_in_layout(in_layout)
+
+except ImportError:
+
+    # Dummy class that propagates a meaningful error,
+    # i.e. that Matplotlib is not installed
+    class AdaptiveFancyArrow():
+        def __init__(*args, **kwargs):
+            raise ModuleNotFoundError(f"No module named 'matplotlib'")

biotite-0.41.1.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.3
+Name: biotite
+Version: 0.41.1
+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-File: LICENSE.rst
+Classifier: Development Status :: 4 - Beta
+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
+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-Dist: msgpack>=0.5.6
+Requires-Dist: networkx>=2.0
+Requires-Dist: numpy<2.0,>=1.14.5
+Requires-Dist: requests>=2.12
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Description-Content-Type: text/x-rst
+
+.. image:: https://img.shields.io/pypi/v/biotite.svg
+   :target: https://pypi.python.org/pypi/biotite
+   :alt: Biotite at PyPI
+.. image:: https://img.shields.io/pypi/pyversions/biotite.svg
+   :alt: Python version
+.. image:: https://github.com/biotite-dev/biotite/actions/workflows/test_and_deploy.yml/badge.svg
+   :target: https://github.com/biotite-dev/biotite/actions/workflows/test_and_deploy.yml
+   :alt: Test status
+
+.. image:: https://www.biotite-python.org/_static/assets/general/biotite_logo_m.png
+   :alt: The Biotite Project
+
+Biotite project
+===============
+
+*Biotite* is your Swiss army knife for bioinformatics.
+Whether you want to identify homologous sequence regions in a protein family
+or you would like to find disulfide bonds in a protein structure: *Biotite*
+has the right tool for you.
+This package bundles popular tasks in computational molecular biology
+into a uniform *Python* library.
+It can handle a major part of the typical workflow
+for sequence and biomolecular structure data:
+   
+   - Searching and fetching data from biological databases
+   - Reading and writing popular sequence/structure file formats
+   - Analyzing and editing sequence/structure data
+   - Visualizing sequence/structure data
+   - Interfacing external applications for further analysis
+
+*Biotite* internally stores most of the data as *NumPy* `ndarray` objects,
+enabling
+
+   - fast C-accelerated analysis,
+   - intuitive usability through *NumPy*-like indexing syntax,
+   - extensibility through direct access of the internal *NumPy* arrays.
+
+As a result the user can skip writing code for basic functionality (like
+file parsers) and can focus on what their code makes unique - from
+small analysis scripts to entire bioinformatics software packages.
+
+If you use *Biotite* in a scientific publication, please cite:
+
+| Kunzmann, P. & Hamacher, K. BMC Bioinformatics (2018) 19:346.
+| `<https://doi.org/10.1186/s12859-018-2367-z>`_
+
+
+Installation
+------------
+
+*Biotite* requires the following packages:
+
+   - **numpy**
+   - **requests**
+   - **msgpack**
+   - **networkx**
+
+Some functions require some extra packages:
+
+   - **mdtraj** - Required for trajetory file I/O operations.
+   - **matplotlib** - Required for plotting purposes.
+
+*Biotite* can be installed via *Conda*...
+
+.. code-block:: console
+
+   $ conda install -c conda-forge biotite
+
+... or *pip*
+
+.. code-block:: console
+
+   $ pip install biotite
+
+
+Usage
+-----
+
+Here is a small example that downloads two protein sequences from the
+*NCBI Entrez* database and aligns them:
+
+.. code-block:: python
+
+   import biotite.sequence.align as align
+   import biotite.sequence.io.fasta as fasta
+   import biotite.database.entrez as entrez
+
+   # Download FASTA file for the sequences of avidin and streptavidin
+   file_name = entrez.fetch_single_file(
+       uids=["CAC34569", "ACL82594"], file_name="sequences.fasta",
+       db_name="protein", ret_type="fasta"
+   )
+
+   # Parse the downloaded FASTA file
+   # and create 'ProteinSequence' objects from it
+   fasta_file = fasta.FastaFile.read(file_name)
+   avidin_seq, streptavidin_seq = fasta.get_sequences(fasta_file).values()
+
+   # Align sequences using the BLOSUM62 matrix with affine gap penalty
+   matrix = align.SubstitutionMatrix.std_protein_matrix()
+   alignments = align.align_optimal(
+       avidin_seq, streptavidin_seq, matrix,
+       gap_penalty=(-10, -1), terminal_penalty=False
+   )
+   print(alignments[0])
+
+.. code-block::
+
+   MVHATSPLLLLLLLSLALVAPGLSAR------KCSLTGKWDNDLGSNMTIGAVNSKGEFTGTYTTAV-TA
+   -------------------DPSKESKAQAAVAEAGITGTWYNQLGSTFIVTA-NPDGSLTGTYESAVGNA
+
+   TSNEIKESPLHGTQNTINKRTQPTFGFTVNWKFS----ESTTVFTGQCFIDRNGKEV-LKTMWLLRSSVN
+   ESRYVLTGRYDSTPATDGSGT--ALGWTVAWKNNYRNAHSATTWSGQYV---GGAEARINTQWLLTSGTT
+
+   DIGDDWKATRVGINIFTRLRTQKE---------------------
+   -AANAWKSTLVGHDTFTKVKPSAASIDAAKKAGVNNGNPLDAVQQ
+
+More documentation, including a tutorial, an example gallery and the API
+reference is available at `<https://www.biotite-python.org/>`_.
+
+
+Contribution
+------------
+
+Interested in improving *Biotite*?
+Have a look at the
+`contribution guidelines <https://www.biotite-python.org/contribute.html>`_.
+Feel free to join or community chat on `Discord <https://discord.gg/cUjDguF>`_.