biotite 0.41.1__cp312-cp312-macosx_10_16_arm64.whl

biotite/structure/io/mmtf/encode.pyx

@@ -0,0 +1,183 @@
+# 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.io.mmtf"
+__author__ = "Patrick Kunzmann"
+__all__ = ["encode_array"]
+
+cimport cython
+cimport numpy as np
+
+import numpy as np
+
+ctypedef np.int8_t int8
+ctypedef np.int16_t int16
+ctypedef np.int32_t int32
+ctypedef np.uint8_t uint8
+ctypedef np.uint16_t uint16
+ctypedef np.uint32_t uint32
+ctypedef np.uint64_t uint64
+ctypedef np.float32_t float32
+
+
+def encode_array(np.ndarray array, int codec, int param):
+    # Pass-through: 32-bit floating-point number array
+    if   codec == 1:
+        array = array.astype(np.float32, copy=False)
+        return array.astype(">f4").tobytes()
+    # Pass-through: 8-bit signed integer array
+    elif codec == 2:
+        array = array.astype(np.int8, copy=False)
+        return array.astype(">i1").tobytes()
+    # Pass-through: 16-bit signed integer array
+    elif codec == 3:
+        array = array.astype(np.int16, copy=False)
+        return array.astype(">i2").tobytes()
+    # Pass-through: 32-bit signed integer array
+    elif codec == 4:
+        array = array.astype(np.int32, copy=False)
+        return array.astype(">i4").tobytes()
+    # UTF8/ASCII fixed-length string array
+    elif codec == 5:
+        dtype = np.dtype("U" + str(param))
+        array = array.astype(dtype, copy=False)
+        return array.astype(np.dtype("S" + str(param))).tobytes()
+    # Run-length encoded character array
+    elif codec == 6:
+        array = array.astype("U1", copy=False)
+        array = _encode_run_length(np.frombuffer(array, dtype=np.int32))
+        return array.astype(">i4").tobytes()
+    # Run-length encoded 32-bit signed integer array
+    elif codec == 7:
+        array = array.astype(np.int32, copy=False)
+        return _encode_run_length(array).astype(">i4").tobytes()
+    # Delta & run-length encoded 32-bit signed integer array
+    elif codec == 8:
+        array = array.astype(np.int32, copy=False)
+        return _encode_run_length(_encode_delta(array)).astype(">i4").tobytes()
+    # Integer & run-length encoded 32-bit floating-point number array
+    elif codec == 9:
+        array = array.astype(np.float32, copy=False)
+        return _encode_run_length(
+                    _encode_integer(param, array).astype(np.int32)
+                ).astype(">i4").tobytes()
+    # Integer & delta encoded
+    # & two-byte-packed 32-bit floating-point number array
+    elif codec == 10:
+        array = array.astype(np.float32, copy=False)
+        return _encode_packed(
+                    True, _encode_delta(
+                        _encode_integer(param, array).astype(np.int32)
+                    )
+                ).astype(">i2").tobytes()
+    # Integer encoded 32-bit floating-point number array
+    elif codec == 11:
+        array = array.astype(np.float32, copy=False)
+        return _encode_integer(param, array).astype(">i2").tobytes()
+    # Integer & two-byte-packed 32-bit floating-point number array
+    elif codec == 12:
+        array = array.astype(np.float32, copy=False)
+        return _encode_packed(
+                    True, _encode_integer(param, array).astype(np.int32) 
+                ).astype(">i2").tobytes()
+    # Integer & one-byte-packed 32-bit floating-point number array
+    elif codec == 13:
+        array = array.astype(np.float32, copy=False)
+        return _encode_packed(
+                    False, _encode_integer(param, array).astype(np.int32)
+                ).astype(">i1").tobytes()
+    # Two-byte-packed 32-bit signed integer array
+    elif codec == 14:
+        array = array.astype(np.int32, copy=False)
+        return _encode_packed(True, array).astype(">i2").tobytes()
+    # One-byte-packed 32-bit signed integer array
+    elif codec == 15:
+        array = array.astype(np.int32, copy=False)
+        return _encode_packed(False, array).astype(">i1").tobytes()
+    else:
+        raise ValueError(f"Unknown codec with ID {codec}")
+
+
+def _encode_delta(int32[:] array):
+    cdef int32[:] output = np.zeros(array.shape[0], np.int32)
+    output[0] = array[0]
+    cdef int i = 0
+    for i in range(1, array.shape[0]):
+        output[i] = array[i] - array[i-1]
+    return np.asarray(output)
+
+
+def _encode_run_length(int32[:] array):
+    # Pessimistic allocation of output array
+    # -> Run length is 1 for every element
+    cdef int32[:] output = np.zeros(array.shape[0] * 2, dtype=np.int32)
+    cdef int i=0, j=0
+    cdef int val = array[0]
+    cdef int run_length = 0
+    cdef int curr_val
+    for i in range(array.shape[0]):
+        curr_val = array[i]
+        if curr_val == val:
+            run_length += 1
+        else:
+            # New element -> Write element with run-length
+            output[j] = val
+            output[j+1] = run_length
+            j += 2
+            val = curr_val
+            run_length = 1
+    # Write last element
+    output[j] = val
+    output[j+1] = run_length
+    j += 2
+    # Trim to correct size
+    return np.asarray(output)[:j]
+
+
+@cython.cdivision(True)
+def _encode_packed(bint two_byte, int32[:] array):
+    cdef int min_val, max_val
+    cdef int i=0, j=0
+    if two_byte:
+        min_val = np.iinfo(np.int16).min
+        max_val = np.iinfo(np.int16).max
+    else:
+        min_val = np.iinfo(np.int8).min
+        max_val = np.iinfo(np.int8).max
+    # Get length of output array
+    # by summing up required length of each element
+    cdef int number
+    cdef int length = 0
+    for i in range(array.shape[0]):
+        number = array[i]
+        if number < 0:
+            length += number // min_val +1
+        elif number > 0:
+            length += number // max_val +1
+        else:
+            # e = 0
+            length += 1
+    # Fill output
+    cdef int16[:] output = np.zeros(length, dtype=np.int16)
+    cdef int remainder
+    j = 0
+    for i in range(array.shape[0]):
+        remainder = array[i]
+        if remainder < 0:
+            while remainder <= min_val:
+                remainder -= min_val
+                output[j] = min_val
+                j += 1
+        elif remainder > 0:
+            while remainder >= max_val:
+                remainder -= max_val
+                output[j] = max_val
+                j += 1
+        output[j] = remainder
+        j += 1
+    return np.asarray(output)
+
+
+def _encode_integer(int divisor, np.ndarray array):
+    return np.multiply(array, divisor)

biotite/structure/io/mmtf/file.py

@@ -0,0 +1,233 @@
+# 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.io.mmtf"
+__author__ = "Patrick Kunzmann"
+__all__ = ["MMTFFile"]
+
+import io
+from collections.abc import MutableMapping
+import struct
+import copy
+import numpy as np
+import msgpack
+import warnings
+from ....file import File, is_binary, is_open_compatible
+from ...error import BadStructureError
+from .decode import decode_array
+from .encode import encode_array
+
+
+class MMTFFile(File, MutableMapping):
+    """
+    This class represents a MMTF file.
+
+    When reading a file, the *MessagePack* unpacker is used to create
+    a dictionary of the file content.
+    This dictionary is accessed by indexing the :class:`MMTFFile`
+    instance directly with the dictionary keys.
+    If the dictionary value is an encoded array, the value automatically
+    decoded.
+    Decoded arrays are always returned as :class:`ndarray` instances.
+
+    DEPRECATED: Use :class:`biotite.structure.io.pdbx.BinaryCIFFile`
+    instead.
+
+    Examples
+    --------
+
+    >>> import os.path
+    >>> mmtf_file = MMTFFile.read(os.path.join(path_to_structures, "1l2y.mmtf"))
+    >>> print(mmtf_file["title"])
+    NMR Structure of Trp-Cage Miniprotein Construct TC5b
+    >>> print(mmtf_file["chainNameList"])
+    ['A' 'A' 'A' 'A' 'A' 'A' 'A' 'A' 'A' 'A' 'A' 'A' 'A' 'A' 'A' 'A' 'A' 'A'
+     'A' 'A' 'A' 'A' 'A' 'A' 'A' 'A' 'A' 'A' 'A' 'A' 'A' 'A' 'A' 'A' 'A' 'A'
+     'A' 'A']
+    """
+
+    def __init__(self):
+        warnings.warn(
+            "'MMTFFile' is deprecated, use 'BinaryCIFFile' instead",
+            DeprecationWarning
+        )
+        super().__init__()
+        self._content = {}
+        self._content["mmtfVersion"] = "1.0.0"
+        self._content["mmtfProducer"] = "UNKNOWN"
+
+    @classmethod
+    def read(self, file):
+        """
+        Read a MMTF file.
+
+        Parameters
+        ----------
+        file : file-like object or str
+            The file to be read.
+            Alternatively a file path can be supplied.
+
+        Returns
+        -------
+        file_object : MMTFFile
+            The parsed file.
+        """
+        mmtf_file = MMTFFile()
+        # File name
+        if is_open_compatible(file):
+            with open(file, "rb") as f:
+                mmtf_file._content = msgpack.unpackb(
+                    f.read(), use_list=True, raw=False
+                )
+        # File object
+        else:
+            if not is_binary(file):
+                raise TypeError("A file opened in 'binary' mode is required")
+            mmtf_file._content = msgpack.unpackb(
+                file.read(), use_list=True, raw=False
+            )
+        return mmtf_file
+
+    def write(self, file):
+        """
+        Write contents into a MMTF file.
+
+        Parameters
+        ----------
+        file : file-like object or str
+            The file to be written to.
+            Alternatively, a file path can be supplied.
+        """
+        packed_bytes = msgpack.packb(
+            self._content, use_bin_type=True, default=_encode_numpy
+        )
+        if is_open_compatible(file):
+            with open(file, "wb") as f:
+                f.write(packed_bytes)
+        else:
+            if not is_binary(file):
+                raise TypeError("A file opened in 'binary' mode is required")
+            file.write(packed_bytes)
+
+    def __copy_fill__(self, clone):
+        super().__copy_fill__(clone)
+        clone._content = copy.deepcopy(self._content)
+
+    def get_codec(self, key):
+        """
+        Obtain the codec ID of an MMTF encoded value.
+
+        Parameters
+        ----------
+        key : str
+            The key for the potentially encoded value.
+
+        Returns
+        -------
+        codec : int or None
+            The codec ID. `None` if the value is not encoded.
+        """
+        data = self._content[key]
+        if isinstance(data, bytes) and data[0] == 0:
+            codec = struct.unpack(">i", data[0:4])[0]
+            return codec
+        else:
+            return None
+
+    def get_length(self, key):
+        """
+        Obtain the length of an MMTF encoded value.
+
+        Parameters
+        ----------
+        key : str
+            The key for the potentially encoded value.
+
+        Returns
+        -------
+        codec : int or None
+            The length of the `bytes` array.
+            `None` if the value is not encoded.
+        """
+        data = self._content[key]
+        if isinstance(data, bytes) and data[0] == 0:
+            length = struct.unpack(">i", data[4:8])[0]
+            return length
+        else:
+            return None
+
+    def get_param(self, key):
+        """
+        Obtain the parameter of an MMTF encoded value.
+
+        Parameters
+        ----------
+        key : str
+            The key for the potentially encoded value.
+
+        Returns
+        -------
+        codec : int or None
+            The parameter of the encoded value.
+            `None` if the value is not encoded.
+        """
+        data = self._content[key]
+        if isinstance(data, bytes) and data[0] == 0:
+            param = struct.unpack(">i", data[8:12])[0]
+            return param
+        else:
+            return None
+
+    def set_array(self, key, array, codec, param=0):
+        length = len(array)
+        raw_bytes = encode_array(array, codec, param)
+        data = struct.pack(">i", codec) \
+             + struct.pack(">i", length) \
+             + struct.pack(">i", param) \
+             + raw_bytes
+        self._content[key] = data
+
+    def __getitem__(self, key):
+        data = self._content[key]
+        if isinstance(data, bytes) and data[0] == 0:
+            # MMTF specific format -> requires decoding
+            codec     = struct.unpack(">i", data[0:4 ])[0]
+            length    = struct.unpack(">i", data[4:8 ])[0]
+            param     = struct.unpack(">i", data[8:12])[0]
+            raw_bytes = data[12:]
+            return decode_array(codec, raw_bytes, param)
+        else:
+            return data
+
+    def __setitem__(self, key, item):
+        if isinstance(item, np.ndarray):
+            raise TypeError("Arrays that need to be encoded must be addeed "
+                            "via 'set_array()'")
+        self._content[key] = item
+
+    def __delitem__(self, key):
+        del self._content[key]
+
+    def __iter__(self):
+        return self._content.__iter__()
+
+    def __len__(self):
+        return len(self._content)
+
+    def __contains__(self, item):
+        return item in self._content
+
+
+def _encode_numpy(item):
+    """
+    Convert NumPy scalar types to native Python types,
+    as *Msgpack* cannot handle NumPy types (e.g. float32).
+
+    The function is given to the Msgpack packer as value for the
+    `default` parameter.
+    """
+    if isinstance(item, np.generic):
+        return item.item()
+    else:
+        raise TypeError(f"can not serialize '{type(item).__name__}' object")

biotite/structure/io/mol/__init__.py

@@ -0,0 +1,20 @@
+# 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 MOL format is used to depict atom positions and bonds for small
+molecules.
+This subpackage is used for reading and writing an :class:`AtomArray`
+in this format.
+Additionally, reading data from the SDF format, which is a wrapper
+around MOL, is also supported.
+"""
+
+__name__ = "biotite.structure.io.mol"
+__author__ = "Patrick Kunzmann"
+
+from .convert import *
+from .header import *
+from .mol import *
+from .sdf import *

biotite/structure/io/mol/convert.py

@@ -0,0 +1,115 @@
+# 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.io.mol"
+__author__ = "Patrick Kunzmann"
+__all__ = ["get_structure", "set_structure"]
+
+from .mol import MOLFile
+from .sdf import SDFile, SDRecord
+from ...bonds import BondType
+
+
+def get_structure(mol_file, record_name=None):
+    """
+    Get an :class:`AtomArray` from the MOL file.
+
+    Ths function is a thin wrapper around
+    :meth:`MOLFile.get_structure()`.
+
+    Parameters
+    ----------
+    mol_file : MOLFile or SDFile or SDRecord
+        The file.
+    record_name : str, optional
+        Has only an effect when `mol_file` is a :class:`SDFile`.
+        The name of the record in the SD file.
+        By default, the first record is used.
+
+    Returns
+    -------
+    array : AtomArray
+        This :class:`AtomArray` contains the optional ``charge``
+        annotation and has an associated :class:`BondList`.
+        All other annotation categories, except ``element`` are
+        empty.
+    """
+    record = _get_record(mol_file, record_name)
+    return record.get_structure()
+
+
+def set_structure(mol_file, atoms, default_bond_type=BondType.ANY,
+                  version=None, record_name=None):
+    """
+    Set the :class:`AtomArray` for the MOL file.
+
+    Ths function is a thin wrapper around
+    :meth:`MOLFile.set_structure()`.
+
+    Parameters
+    ----------
+    mol_file : MOLFile
+        The MOL file.
+    array : AtomArray
+        The array to be saved into this file.
+        Must have an associated :class:`BondList`.
+        Bond type fallback for the *Bond block*, if a
+        :class:`BondType` has no CTAB counterpart.
+        By default, each such bond is treated as
+        :attr:`BondType.ANY`.
+    default_bond_type : BondType, optional
+        Bond type fallback for the *Bond block*, if a :class:`BondType`
+        has no CTAB counterpart.
+        By default, each such bond is treated as :attr:`BondType.ANY`.
+    version : {"V2000", "V3000"}, optional
+        The version of the CTAB format.
+        ``"V2000"`` uses the *Atom* and *Bond* block, while ``"V3000"``
+        uses the *Properties* block.
+        By default, ``"V2000"`` is used, unless the number of atoms or
+        bonds exceeds 999, in which case ``"V3000"`` is used.
+    record_name : str, optional
+        Has only an effect when `mol_file` is a :class:`SDFile`.
+        The name of the record.
+        Default is the first record of the file.
+        If the file is empty, a new record will be created.
+    """
+    record = _get_or_create_record(mol_file, record_name)
+    record.set_structure(atoms, default_bond_type, version)
+
+
+def _get_record(file, record_name):
+    if isinstance(file, (MOLFile, SDRecord)):
+        return file
+    elif isinstance(file, SDFile):
+        # Determine record
+        if record_name is None:
+            return file.record
+        else:
+            return file[record_name]
+    else:
+        raise TypeError(
+            f"Unsupported file type '{type(file).__name__}'"
+        )
+
+
+def _get_or_create_record(file, record_name):
+    if isinstance(file, (MOLFile, SDRecord)):
+        return file
+    elif isinstance(file, SDFile):
+        if record_name is None:
+            if len(file) > 0:
+                # Choose first record by default
+                record_name = next(iter(file.keys()))
+            else:
+                # File is empty -> invent a new record name
+                record_name = "Molecule"
+
+        if record_name not in file:
+            record = SDRecord()
+            file[record_name] = record
+        return file[record_name]
+    else:
+        raise TypeError(
+            f"Unsupported file type '{type(file).__name__}'"
+        )