biotite 1.5.0__cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl

biotite/sequence/sequence.py

@@ -0,0 +1,373 @@
+# 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.
+
+"""
+The module contains the :class:`Sequence` superclass and :class:`GeneralSequence`.
+"""
+
+__name__ = "biotite.sequence"
+__author__ = "Patrick Kunzmann"
+__all__ = ["Sequence"]
+
+import abc
+import numbers
+import numpy as np
+from biotite.copyable import Copyable
+from biotite.sequence.alphabet import LetterAlphabet
+
+_size_uint8 = np.iinfo(np.uint8).max + 1
+_size_uint16 = np.iinfo(np.uint16).max + 1
+_size_uint32 = np.iinfo(np.uint32).max + 1
+
+
+class Sequence(Copyable, metaclass=abc.ABCMeta):
+    """
+    The abstract base class for all sequence types.
+
+    A :class:`Sequence` can be seen as a succession of symbols, that are
+    elements in the allowed set of symbols, the :class:`Alphabet`.
+    Internally, a :class:`Sequence` object uses a *NumPy*
+    :class:`ndarray` of integers, where each integer represents a
+    symbol.
+    The :class:`Alphabet` of a :class:`Sequence` object is used to
+    encode each symbol, that is used to create the
+    :class:`Sequence`, into an integer. These integer values are called
+    symbol code, the encoding of an entire sequence of symbols is
+    called sequence code.
+
+    The size of the symbol code type in the array is determined by the
+    size of the :class:`Alphabet`:
+    If the :class:`Alphabet` contains 256 symbols or less, one byte is
+    used per array element; if the :class:`Alphabet` contains
+    between 257 and 65536 symbols, two bytes are used, and so on.
+
+    Two :class:`Sequence` objects are equal if they are instances of the
+    same class, have the same :class:`Alphabet` and have equal sequence
+    codes.
+    Comparison with a string or list of symbols evaluates always to
+    false.
+
+    A :class:`Sequence` can be indexed by any 1-D index a
+    :class:`ndarray` accepts.
+    If the index is a single integer, the decoded symbol at that
+    position is returned, otherwise a subsequence is returned.
+
+    Individual symbols of the sequence can also be exchanged in indexed
+    form: If the an integer is used as index, the item is treated as a
+    symbol. Any other index (slice, index list, boolean mask) expects
+    multiple symbols, either as list of symbols, as :class:`ndarray`
+    containing a sequence code or another :class:`Sequence` instance.
+    Concatenation of two sequences is achieved with the '+' operator.
+
+    Each subclass of :class:`Sequence` needs to overwrite the abstract
+    method :func:`get_alphabet()`, which specifies the alphabet the
+    :class:`Sequence` uses.
+
+    Parameters
+    ----------
+    sequence : iterable object, optional
+        The symbol sequence, the :class:`Sequence` is initialized with.
+        For alphabets containing single letter strings, this parameter
+        may also be a :class`str` object.
+        By default the sequence is empty.
+
+    Attributes
+    ----------
+    code : ndarray
+        The sequence code.
+    symbols : list
+        The list of symbols, represented by the sequence.
+        The list is generated by decoding the sequence code, when
+        this attribute is accessed. When this attribute is modified,
+        the new list of symbols is encoded into the sequence code.
+    alphabet : Alphabet
+        The alphabet of this sequence. Cannot be set.
+        Equal to `get_alphabet()`.
+
+    Examples
+    --------
+    Creating a DNA sequence from string and print the symbols and the
+    code:
+
+    >>> dna_seq = NucleotideSequence("ACGTA")
+    >>> print(dna_seq)
+    ACGTA
+    >>> print(dna_seq.code)
+    [0 1 2 3 0]
+    >>> print(dna_seq.symbols)
+    ['A' 'C' 'G' 'T' 'A']
+    >>> print(list(dna_seq))
+    ['A', 'C', 'G', 'T', 'A']
+
+    Sequence indexing:
+
+    >>> print(dna_seq[1:3])
+    CG
+    >>> print(dna_seq[[0,2,4]])
+    AGA
+    >>> print(dna_seq[np.array([False,False,True,True,True])])
+    GTA
+
+    Sequence manipulation:
+
+    >>> dna_copy = dna_seq.copy()
+    >>> dna_copy[2] = "C"
+    >>> print(dna_copy)
+    ACCTA
+    >>> dna_copy = dna_seq.copy()
+    >>> dna_copy[0:2] = dna_copy[3:5]
+    >>> print(dna_copy)
+    TAGTA
+    >>> dna_copy = dna_seq.copy()
+    >>> dna_copy[np.array([True,False,False,False,True])] = "T"
+    >>> print(dna_copy)
+    TCGTT
+    >>> dna_copy = dna_seq.copy()
+    >>> dna_copy[1:4] = np.array([0,1,2])
+    >>> print(dna_copy)
+    AACGA
+
+    Reverse sequence:
+
+    >>> dna_seq_rev = dna_seq.reverse()
+    >>> print(dna_seq_rev)
+    ATGCA
+
+    Concatenate the two sequences:
+
+    >>> dna_seq_concat = dna_seq + dna_seq_rev
+    >>> print(dna_seq_concat)
+    ACGTAATGCA
+    """
+
+    def __init__(self, sequence=()):
+        self.symbols = sequence
+
+    def copy(self, new_seq_code=None):
+        """
+        Copy the object.
+
+        Parameters
+        ----------
+        new_seq_code : ndarray, optional
+            If this parameter is set, the sequence code is set to this
+            value, rather than the original sequence code.
+
+        Returns
+        -------
+        copy
+            A copy of this object.
+        """
+        # Override in order to achieve better performance,
+        # in case only a subsequence is needed,
+        # because not the entire sequence code is copied then
+        clone = self.__copy_create__()
+        if new_seq_code is None:
+            clone.code = np.copy(self.code)
+        else:
+            clone.code = new_seq_code
+        self.__copy_fill__(clone)
+        return clone
+
+    @property
+    def symbols(self):
+        return self.get_alphabet().decode_multiple(self.code)
+
+    @symbols.setter
+    def symbols(self, value):
+        alph = self.get_alphabet()
+        dtype = Sequence.dtype(len(alph))
+        self._seq_code = alph.encode_multiple(value, dtype)
+
+    @property
+    def code(self):
+        return self._seq_code
+
+    @code.setter
+    def code(self, value):
+        dtype = Sequence.dtype(len(self.get_alphabet()))
+        if not isinstance(value, np.ndarray):
+            raise TypeError("Sequence code must be an integer ndarray")
+        self._seq_code = value.astype(dtype, copy=False)
+
+    @property
+    def alphabet(self):
+        return self.get_alphabet()
+
+    @abc.abstractmethod
+    def get_alphabet(self):
+        """
+        Get the :class:`Alphabet` of the :class:`Sequence`.
+
+        This method must be overwritten, when subclassing
+        :class:`Sequence`.
+
+        Returns
+        -------
+        alphabet : Alphabet
+            :class:`Sequence` alphabet.
+        """
+        pass
+
+    def reverse(self, copy=True):
+        """
+        Reverse the :class:`Sequence`.
+
+        Parameters
+        ----------
+        copy : bool, optional
+            If set to False, the code :class:`ndarray` of the returned
+            sequence is an array view to the sequence code of this
+            object.
+            In this case, manipulations on the returned sequence would
+            also affect this object.
+            Otherwise, the sequence code is copied.
+
+        Returns
+        -------
+        reversed : Sequence
+            The reversed :class:`Sequence`.
+
+        Examples
+        --------
+
+        >>> dna_seq = NucleotideSequence("ACGTA")
+        >>> dna_seq_rev = dna_seq.reverse()
+        >>> print(dna_seq_rev)
+        ATGCA
+        """
+        reversed_code = np.flip(self._seq_code, axis=0)
+        if copy:
+            reversed_code = np.copy(reversed_code)
+        return self.copy(reversed_code)
+
+    def is_valid(self):
+        """
+        Check, if the sequence contains a valid sequence code.
+
+        A sequence code is valid, if at each sequence position the
+        code is smaller than the size of the alphabet.
+
+        Invalid code means that the code cannot be decoded into
+        symbols. Furthermore invalid code can lead to serious
+        errors in alignments, since the substitution matrix
+        is indexed with an invalid index.
+
+        Returns
+        -------
+        valid : bool
+            True, if the sequence is valid, false otherwise.
+        """
+        return (self.code < len(self.get_alphabet())).all()
+
+    def get_symbol_frequency(self):
+        """
+        Get the number of occurences of each symbol in the sequence.
+
+        If a symbol does not occur in the sequence, but it is in the
+        alphabet, its number of occurences is 0.
+
+        Returns
+        -------
+        frequency : dict
+            A dictionary containing the symbols as keys and the
+            corresponding number of occurences in the sequence as
+            values.
+        """
+        counts = np.bincount(self._seq_code, minlength=len(self.get_alphabet()))
+        return {
+            symbol: count
+            for symbol, count in zip(self.get_alphabet().get_symbols(), counts)
+        }
+
+    def __getitem__(self, index):
+        alph = self.get_alphabet()
+        sub_seq = self._seq_code.__getitem__(index)
+        if isinstance(sub_seq, np.ndarray):
+            return self.copy(sub_seq)
+        else:
+            return alph.decode(sub_seq)
+
+    def __setitem__(self, index, item):
+        alph = self.get_alphabet()
+        if isinstance(index, numbers.Integral):
+            # Expect a single symbol
+            code = alph.encode(item)
+        else:
+            # Expect multiple symbols
+            if isinstance(item, Sequence):
+                code = item.code
+            elif isinstance(item, np.ndarray):
+                code = item
+            else:
+                # Default: item is iterable object of symbols
+                code = alph.encode_multiple(item)
+        self._seq_code.__setitem__(index, code)
+
+    def __len__(self):
+        return len(self._seq_code)
+
+    def __iter__(self):
+        alph = self.get_alphabet()
+        i = 0
+        while i < len(self):
+            yield alph.decode(self._seq_code[i])
+            i += 1
+
+    def __eq__(self, item):
+        if not isinstance(item, type(self)):
+            return False
+        if self.get_alphabet() != item.get_alphabet():
+            return False
+        return np.array_equal(self._seq_code, item._seq_code)
+
+    def __str__(self):
+        alph = self.get_alphabet()
+        if isinstance(alph, LetterAlphabet):
+            return (
+                alph.decode_multiple(self._seq_code, as_bytes=True)
+                .tobytes()
+                .decode("ASCII")
+            )
+        else:
+            return ", ".join([str(e) for e in alph.decode_multiple(self._seq_code)])
+
+    def __add__(self, sequence):
+        if self.get_alphabet().extends(sequence.get_alphabet()):
+            new_code = np.concatenate((self._seq_code, sequence._seq_code))
+            new_seq = self.copy(new_code)
+            return new_seq
+        elif sequence.get_alphabet().extends(self.get_alphabet()):
+            new_code = np.concatenate((self._seq_code, sequence._seq_code))
+            new_seq = sequence.copy(new_code)
+            return new_seq
+        else:
+            raise ValueError("The sequences alphabets are not compatible")
+
+    @staticmethod
+    def dtype(alphabet_size):
+        """
+        Get the sequence code dtype required for the given size of the
+        alphabet.
+
+        Parameters
+        ----------
+        alphabet_size : int
+            The size of the alphabet.
+
+        Returns
+        -------
+        dtype
+            The  :class:`dtype`, that is large enough to store symbol
+            codes, that are encoded by an :class:`Alphabet` of the given
+            size.
+        """
+        if alphabet_size <= _size_uint8:
+            return np.uint8
+        elif alphabet_size <= _size_uint16:
+            return np.uint16
+        elif alphabet_size <= _size_uint32:
+            return np.uint32
+        else:
+            return np.uint64

biotite/setup_ccd.py

@@ -0,0 +1,197 @@
+__author__ = "Patrick Kunzmann"
+__all__ = []
+
+import gzip
+import logging
+from collections import defaultdict
+from io import StringIO
+from pathlib import Path
+import numpy as np
+import requests
+from biotite.structure.io.pdbx import *
+
+OUTPUT_CCD = Path(__file__).parent / "structure" / "info" / "components.bcif"
+CCD_URL = "https://files.wwpdb.org/pub/pdb/data/monomers/components.cif.gz"
+
+
+def concatenate_ccd(categories=None):
+    """
+    Create the CCD in BinaryCIF format with each category contains the
+    data of all blocks.
+
+    Parameters
+    ----------
+    categories : list of str, optional
+        The names of the categories to include.
+        By default, all categories from the CCD are included.
+
+    Returns
+    -------
+    compressed_file : BinaryCIFFile
+        The compressed CCD in BinaryCIF format.
+    """
+
+    logging.info("Download and read CCD...")
+    ccd_cif_text = gzip.decompress(requests.get(CCD_URL).content).decode()
+    ccd_file = CIFFile.read(StringIO(ccd_cif_text))
+
+    compressed_block = BinaryCIFBlock()
+    if categories is None:
+        categories = _list_all_category_names(ccd_file)
+    for category_name in categories:
+        logging.info(f"Concatenate and compress '{category_name}' category...")
+        compressed_block[category_name] = compress(
+            _concatenate_blocks_into_category(ccd_file, category_name)
+        )
+
+    logging.info("Write concatenated CCD into BinaryCIF...")
+    compressed_file = BinaryCIFFile()
+    compressed_file["components"] = compressed_block
+    return compressed_file
+
+
+def _concatenate_blocks_into_category(pdbx_file, category_name):
+    """
+    Concatenate the given category from all blocks into a single
+    category.
+
+    Parameters
+    ----------
+    pdbx_file : PDBxFile
+        The PDBx file, whose blocks should be concatenated.
+    category_name : str
+        The name of the category to concatenate.
+
+    Returns
+    -------
+    category : BinaryCIFCategory
+        The concatenated category.
+    """
+    columns_names = _list_all_column_names(pdbx_file, category_name)
+    data_chunks = defaultdict(list)
+    mask_chunks = defaultdict(list)
+    for block in pdbx_file.values():
+        if category_name not in block:
+            continue
+        category = block[category_name]
+        for column_name in columns_names:
+            if column_name in category:
+                column = category[column_name]
+                data_chunks[column_name].append(column.data.array)
+                if column.mask is not None:
+                    mask_chunks[column_name].append(column.mask.array)
+                else:
+                    mask_chunks[column_name].append(
+                        np.full(category.row_count, MaskValue.PRESENT, dtype=np.uint8)
+                    )
+            else:
+                # Column is missing in this block
+                # -> handle it as data masked as 'missing'
+                data_chunks[column_name].append(
+                    # For now all arrays are of type string anyway,
+                    # as they are read from a CIF file
+                    np.full(category.row_count, "", dtype="U1")
+                )
+                mask_chunks[column_name].append(
+                    np.full(category.row_count, MaskValue.MISSING, dtype=np.uint8)
+                )
+
+    bcif_columns = {}
+    for col_name in columns_names:
+        data = np.concatenate(data_chunks[col_name])
+        mask = np.concatenate(mask_chunks[col_name])
+        data = _into_fitting_type(data, mask)
+        if np.all(mask == MaskValue.PRESENT):
+            mask = None
+        bcif_columns[col_name] = BinaryCIFColumn(data, mask)
+    return BinaryCIFCategory(bcif_columns)
+
+
+def _list_all_column_names(pdbx_file, category_name):
+    """
+    Get all columns that exist in any block for a given category.
+
+    Parameters
+    ----------
+    pdbx_file : PDBxFile
+        The PDBx file to search in for the columns.
+    category_name : str
+        The name of the category to search in.
+
+    Returns
+    -------
+    columns_names : list of str
+        The names of the columns.
+    """
+    columns_names = set()
+    for block in pdbx_file.values():
+        if category_name in block:
+            columns_names.update(block[category_name].keys())
+    return sorted(columns_names)
+
+
+def _list_all_category_names(pdbx_file):
+    """
+    Get all categories that exist in any block.
+
+    Parameters
+    ----------
+    pdbx_file : PDBxFile
+        The PDBx file to search in for the columns.
+
+    Returns
+    -------
+    columns_names : list of str
+        The names of the columns.
+    """
+    category_names = set()
+    for block in pdbx_file.values():
+        category_names.update(block.keys())
+    return sorted(category_names)
+
+
+def _into_fitting_type(string_array, mask):
+    """
+    Try to find a numeric type for a string ndarray, if possible.
+
+    Parameters
+    ----------
+    string_array : ndarray, dtype=string
+        The array to convert.
+    mask : ndarray, dtype=uint8
+        Only values in `string_array` where the mask is ``MaskValue.PRESENT`` are
+        considered for type conversion.
+
+    Returns
+    -------
+    array : ndarray
+        The array converted into an appropriate dtype.
+    """
+    mask = mask == MaskValue.PRESENT
+    # Only try to find an appropriate dtype for unmasked values
+    values = string_array[mask]
+    try:
+        # Try to fit into integer type
+        values = values.astype(int)
+    except ValueError:
+        try:
+            # Try to fit into float type
+            values = values.astype(float)
+        except ValueError:
+            # Keep string type
+            pass
+    array = np.zeros(string_array.shape, dtype=values.dtype)
+    array[mask] = values
+    return array
+
+
+def main():
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s:%(message)s")
+    OUTPUT_CCD.parent.mkdir(parents=True, exist_ok=True)
+
+    compressed_ccd = concatenate_ccd(["chem_comp", "chem_comp_atom", "chem_comp_bond"])
+    compressed_ccd.write(OUTPUT_CCD)
+
+
+if __name__ == "__main__":
+    main()

biotite/structure/__init__.py

@@ -0,0 +1,135 @@
+# 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 handling molecular structures.
+
+In this context an atom is described by two kinds of attributes: the
+coordinates and the annotations. The annotations include information
+about polypetide chain id, residue id, residue name, hetero atom
+information, atom name and optionally more. The coordinates are a
+`NumPy` float :class:`ndarray` of length 3, containing the x, y and z
+coordinates.
+
+An :class:`Atom` contains data for a single atom, it stores the
+annotations as scalar values and the coordinates as length 3
+:class:`ndarray`.
+
+An :class:`AtomArray` stores data for an entire structure model
+containing *n* atoms.
+Therefore the annotations are represented as :class:`ndarray` objects of
+length *n*, the so called annotation arrays.
+The coordinates are a *(n x 3)* :class:`ndarray`.
+
+An :class:`AtomArrayStack` stores data for *m* models, where each model
+contains the same atoms at different positions.
+Hence, the annotation arrays are represented as :class:`ndarray` objects
+of length *n* like the :class:`AtomArray`, while the coordinates are a
+*(m x n x 3)* :class:`ndarray`.
+
+Like an :class:`AtomArray` can be iterated to obtain :class:`Atom`
+objects, an :class:`AtomArrayStack` yields :class:`AtomArray` objects.
+All three types must not be subclassed.
+
+The following annotation categories are mandatory:
+
+=========  ===========  =================  =======================================
+Category   Type         Examples           Description
+=========  ===========  =================  =======================================
+chain_id   string (U4)  'A','S','AB', ...  Polypeptide chain
+res_id     int          1,2,3, ...         Sequence position of residue
+ins_code   string (U1)  '', 'A','B',..     PDB insertion code (iCode)
+res_name   string (U5)  'GLY','ALA', ...   Residue name
+hetero     bool         True, False        False for ``ATOM``, true for ``HETATM``
+atom_name  string (U6)  'CA','N', ...      Atom name
+element    string (U2)  'C','O','SE', ...  Chemical Element
+=========  ===========  =================  =======================================
+
+For all :class:`Atom`, :class:`AtomArray` and :class:`AtomArrayStack`
+objects these annotations are initially set with default values.
+Additionally to these annotations, an arbitrary amount of annotation
+categories can be added via :func:`add_annotation()` or
+:func:`set_annotation()`.
+The annotation arrays can be accessed either via the method
+:func:`get_annotation()` or directly (e.g. ``array.res_id``).
+
+The following annotation categories are optionally used by some
+functions:
+
+=========  ===========  =================   =========================================
+Category   Type         Examples            Description
+=========  ===========  =================   =========================================
+atom_id    int          1,2,3, ...          Atom serial number
+b_factor   float        0.9, 12.3, ...      Temperature factor
+occupancy  float        .1, .3, .9, ...     Occupancy
+charge     int          -2,-1,0,1,2, ...    Electric charge of the atom
+sym_id     string       '1','2','3', ...    Symmetry ID for assemblies/symmetry mates
+=========  ===========  =================   =========================================
+
+For each type, the attributes can be accessed directly.
+Both :class:`AtomArray` and :class:`AtomArrayStack` support
+*NumPy* style indexing.
+The index is propagated to each attribute.
+If a single integer is used as index,
+an object with one dimension less is returned
+(:class:`AtomArrayStack` -> :class:`AtomArray`,
+:class:`AtomArray` -> :class:`Atom`).
+If a slice, index array or a boolean mask is given, a substructure is
+returned
+(:class:`AtomArrayStack` -> :class:`AtomArrayStack`,
+:class:`AtomArray` -> :class:`AtomArray`)
+As in *NumPy*, these are not necessarily deep copies of the originals:
+The attributes of the sliced object may still point to the original
+:class:`ndarray`.
+Use the :func:`copy()` method if a deep copy is required.
+
+Bond information can be associated to an :class:`AtomArray` or
+:class:`AtomArrayStack` by setting the ``bonds`` attribute with a
+:class:`BondList`.
+A :class:`BondList` specifies the indices of atoms that form chemical
+bonds.
+Some functionalities require that the input structure has an associated
+:class:`BondList`.
+If no :class:`BondList` is associated, the ``bonds`` attribute is
+``None``.
+
+Based on the implementation in *NumPy* arrays, this package furthermore
+contains a comprehensive set of functions for structure analysis,
+manipulation and visualization.
+
+The universal length unit in this package is Å.
+"""
+
+__name__ = "biotite.structure"
+__author__ = "Patrick Kunzmann"
+
+from .atoms import *
+from .basepairs import *
+from .bonds import *
+from .box import *
+from .celllist import *
+from .chains import *
+from .charges import *
+from .compare import *
+from .density import *
+from .dotbracket import *
+from .error import *
+from .filter import *
+from .geometry import *
+from .hbond import *
+from .integrity import *
+from .mechanics import *
+from .molecules import *
+from .pseudoknots import *
+from .rdf import *
+from .repair import *
+from .residues import *
+from .rings import *
+from .sasa import *
+from .sequence import *
+from .sse import *
+from .superimpose import *
+from .tm import *
+from .transform import *
+# util and segments are used internally