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

biotite/sequence/seqtypes.py

@@ -4,10 +4,22 @@
 
 __name__ = "biotite.sequence"
 __author__ = "Patrick Kunzmann", "Thomas Nevolianis"
-__all__ = ["GeneralSequence", "NucleotideSequence", "ProteinSequence"]
-
+__all__ = [
+    "GeneralSequence",
+    "NucleotideSequence",
+    "ProteinSequence",
+    "PositionalSequence",
+    "PurePositionalSequence",
+]
+
+from dataclasses import dataclass, field
 import numpy as np
-from biotite.sequence.alphabet import AlphabetError, AlphabetMapper, LetterAlphabet
+from biotite.sequence.alphabet import (
+    Alphabet,
+    AlphabetError,
+    AlphabetMapper,
+    LetterAlphabet,
+)
 from biotite.sequence.sequence import Sequence
 
 
@@ -188,7 +200,6 @@ class NucleotideSequence(Sequence):
         TGCGAA
         >>> print(dna_seq.reverse().complement())
         AAGCGT
-
         """
         # Interpreting the sequence code of this object in the
         # complementary alphabet gives the complementary symbols
@@ -214,7 +225,7 @@ class NucleotideSequence(Sequence):
         complete : bool, optional
             If true, the complete sequence is translated. In this case
             the sequence length must be a multiple of 3.
-            Otherwise all ORFs are translated. (Default: False)
+            Otherwise all ORFs are translated.
         codon_table : CodonTable, optional
             The codon table to be used. By default the default table
             will be used
@@ -224,7 +235,6 @@ class NucleotideSequence(Sequence):
             even if the start codon codes for another amino acid.
             Otherwise the translation starts with the amino acid
             the codon codes for. Only applies, if `complete` is false.
-            (Default: False)
 
         Returns
         -------
@@ -254,7 +264,6 @@ class NucleotideSequence(Sequence):
         ...    print(seq)
         MML*
         ML*
-
         """
         if self._alphabet != NucleotideSequence.alphabet_unamb:
             raise AlphabetError("Translation requires unambiguous alphabet")
@@ -574,6 +583,11 @@ class ProteinSequence(Sequence):
         in the protein and the average isotopic mass of one water
         molecule.
 
+        Parameters
+        ----------
+        monoisotopic : bool
+            Use the mass of the most common isotope.
+
         Returns
         -------
         weight : float
@@ -587,6 +601,120 @@ class ProteinSequence(Sequence):
 
         if np.isnan(weight):
             raise ValueError(
-                "Sequence contains ambiguous amino acids, " "cannot calculate weight"
+                "Sequence contains ambiguous amino acids, cannot calculate weight"
             )
         return weight
+
+
+class PositionalSequence(Sequence):
+    """
+    A sequence where each symbol is associated with a position.
+
+    For each individual position the sequence contains a separate
+    :class:`PositionalSequence.Symbol`, encoded by a custom alphabet for this sequence.
+    In consequence the symbol code is the position in the sequence itself.
+    This is useful for aligning sequences based on a position-specific
+    substitution matrix.
+
+    Parameters
+    ----------
+    original_sequence : seq.Sequence
+        The original sequence to create the positional sequence from.
+    """
+
+    @dataclass(frozen=True)
+    class Symbol:
+        """
+        Combination of a symbol and its position in a sequence.
+
+        Attributes
+        ----------
+        original_alphabet : Alphabet
+            The original alphabet, where the symbol stems from.
+        original_code : int
+            The code of the original symbol in the original alphabet.
+        position : int
+            The 0-based position of the symbol in the sequence.
+        symbol : object
+            The symbol from the original alphabet.
+
+        See Also
+        --------
+        PositionalSequence
+            The sequence type containing :class:`PositionalSymbol` objects.
+        """
+
+        original_alphabet: ...
+        original_code: ...
+        position: ...
+        symbol: ... = field(init=False)
+
+        def __post_init__(self):
+            sym = self.original_alphabet.decode(self.original_code)
+            super().__setattr__("symbol", sym)
+
+        def __str__(self):
+            return str(self.symbol)
+
+    def __init__(self, original_sequence):
+        self._orig_alphabet = original_sequence.get_alphabet()
+        self._alphabet = Alphabet(
+            [
+                PositionalSequence.Symbol(self._orig_alphabet, code, pos)
+                for pos, code in enumerate(original_sequence.code)
+            ]
+        )
+        self.code = np.arange(
+            len(original_sequence), dtype=Sequence.dtype(len(self._alphabet))
+        )
+
+    def reconstruct(self):
+        """
+        Reconstruct the original sequence from the positional sequence.
+
+        Returns
+        -------
+        original_sequence : GeneralSequence
+            The original sequence.
+            Although the actual type of the returned sequence is always a
+            :class:`GeneralSequence`, the alphabet and the symbols of the returned
+            sequence are equal to the original sequence.
+        """
+        original_sequence = GeneralSequence(self._orig_alphabet)
+        original_sequence.code = np.array([sym.original_code for sym in self._alphabet])
+        return original_sequence
+
+    def get_alphabet(self):
+        return self._alphabet
+
+    def __str__(self) -> str:
+        return "".join([str(sym) for sym in self.symbols])
+
+    def __repr__(self):
+        return f"PositionalSequence({self.reconstruct()!r})"
+
+
+class PurePositionalSequence(Sequence):
+    """
+    An object of this class is a 'placeholder' sequence, where each symbol is the
+    position in the sequence itself.
+
+    This class is similar to :class:`PositionalSequence`, but the symbols are not
+    derived from an original sequence, but are the pure position.
+    Hence, there is no meaningful string representation of the sequence and its symbols.
+
+    Parameters
+    ----------
+    length : int
+        The length of the sequence.
+    """
+
+    def __init__(self, length):
+        self._alphabet = Alphabet(range(length))
+        self.code = np.arange(length, dtype=Sequence.dtype(length))
+
+    def get_alphabet(self):
+        return self._alphabet
+
+    def __repr__(self):
+        return f"PurePositionalSequence({len(self)})"

biotite/sequence/sequence.py

@@ -139,7 +139,6 @@ class Sequence(Copyable, metaclass=abc.ABCMeta):
     >>> dna_seq_concat = dna_seq + dna_seq_rev
     >>> print(dna_seq_concat)
     ACGTAATGCA
-
     """
 
     def __init__(self, sequence=()):
@@ -354,7 +353,7 @@ class Sequence(Copyable, metaclass=abc.ABCMeta):
 
         Parameters
         ----------
-        alpahabet_size : int
+        alphabet_size : int
             The size of the alphabet.
 
         Returns

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

@@ -57,14 +57,15 @@ The annotation arrays can be accessed either via the method
 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
@@ -124,9 +125,11 @@ 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

biotite/structure/alphabet/__init__.py

@@ -0,0 +1,25 @@
+# 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 converting structures to structural alphabet sequences.
+
+Structural alphabets represent the local geometry of each residue in a structure as
+symbol in a sequence.
+This allows using sequence-based functionality from :mod:`biotite.sequence` on
+structural data.
+
+For each supported structural alphabet, this subpackage provides a conversion function
+that converts each chain of a given structure into a :class:`Sequence` object from the
+respective structural alphabet.
+
+Note that the structural alphabets use lower-case letters as symbols, in order to
+distinguish them better from the nucleotide and amino acid alphabets.
+"""
+
+__name__ = "biotite.structure.alphabet"
+__author__ = "Martin Larralde, Patrick Kunzmann"
+
+from .i3d import *
+from .pb import *