biotite 1.0.0__cp311-cp311-macosx_11_0_arm64.whl → 1.1.0__cp311-cp311-macosx_11_0_arm64.whl

biotite/structure/io/pdbx/encoding.pyx

@@ -287,7 +287,8 @@ class FixedPointEncoding(Encoding):
         The data type of the array to be encoded.
         Either a NumPy dtype or a *BinaryCIF* type code is accepted.
         The dtype must be a float type.
-        If omitted, 32-bit floats are assumed.
+        If omitted, the data type is taken from the data the
+        first time :meth:`encode()` is called.
 
     Attributes
     ----------
@@ -304,7 +305,7 @@ class FixedPointEncoding(Encoding):
     [987 654]
     """
     factor: ...
-    src_type: ... = TypeCode.FLOAT32
+    src_type: ... = None
 
     def __post_init__(self):
         if self.src_type is not None:
@@ -315,6 +316,14 @@ class FixedPointEncoding(Encoding):
                 )
 
     def encode(self, data):
+        # If not given in constructor, it is determined from the data
+        if self.src_type is None:
+            self.src_type = TypeCode.from_dtype(data.dtype)
+            if self.src_type not in (TypeCode.FLOAT32, TypeCode.FLOAT64):
+                raise ValueError(
+                    "Only floating point types are supported"
+                )
+
         # Round to avoid wrong values due to floating point inaccuracies
         return np.round(data * self.factor).astype(np.int32)
 
@@ -340,7 +349,8 @@ class IntervalQuantizationEncoding(Encoding):
         The data type of the array to be encoded.
         Either a NumPy dtype or a *BinaryCIF* type code is accepted.
         The dtype must be a float type.
-        If omitted, 32-bit floats are assumed.
+        If omitted, the data type is taken from the data the
+        first time :meth:`encode()` is called.
 
     Attributes
     ----------
@@ -367,13 +377,17 @@ class IntervalQuantizationEncoding(Encoding):
     min: ...
     max: ...
     num_steps: ...
-    src_type: ... = TypeCode.FLOAT32
+    src_type: ... = None
 
     def __post_init__(self):
         if self.src_type is not None:
             self.src_type = TypeCode.from_dtype(self.src_type)
 
     def encode(self, data):
+        # If not given in constructor, it is determined from the data
+        if self.src_type is None:
+            self.src_type = TypeCode.from_dtype(data.dtype)
+
         steps = np.linspace(
             self.min, self.max, self.num_steps, dtype=data.dtype
         )
@@ -524,7 +538,8 @@ class DeltaEncoding(Encoding):
         first time :meth:`encode()` is called.
     origin : int, optional
         The starting value from which the differences are calculated.
-        If omitted, the origin is set to 0.
+        If omitted, the value is taken from the first array element the
+        first time :meth:`encode()` is called.
 
     Attributes
     ----------
@@ -535,11 +550,14 @@ class DeltaEncoding(Encoding):
     --------
 
     >>> data = np.array([1, 1, 2, 3, 5, 8])
-    >>> print(DeltaEncoding().encode(data))
-    [1 0 1 1 2 3]
+    >>> encoding = DeltaEncoding()
+    >>> print(encoding.encode(data))
+    [0 0 1 1 2 3]
+    >>> print(encoding.origin)
+    1
     """
     src_type: ... = None
-    origin: ... = 0
+    origin: ... = None
 
     def __post_init__(self):
         if self.src_type is not None:
@@ -549,6 +567,8 @@ class DeltaEncoding(Encoding):
         # If not given in constructor, it is determined from the data
         if self.src_type is None:
             self.src_type = TypeCode.from_dtype(data.dtype)
+        if self.origin is None:
+            self.origin = data[0]
 
         data = data - self.origin
         return np.diff(data, prepend=0).astype(np.int32, copy=False)
@@ -582,7 +602,8 @@ class IntegerPackingEncoding(Encoding):
     is_unsigned : bool, optional
         Whether the values should be packed into signed or unsigned
         integers.
-        If omitted, the values are packed into signed integers.
+        If omitted, first time :meth:`encode()` is called, determines whether
+        the values fit into unsigned integers.
 
     Attributes
     ----------
@@ -601,7 +622,7 @@ class IntegerPackingEncoding(Encoding):
     """
     byte_count: ...
     src_size: ... = None
-    is_unsigned: ... = False
+    is_unsigned: ... = None
 
     def encode(self, data):
         if self.src_size is None:
@@ -610,6 +631,9 @@ class IntegerPackingEncoding(Encoding):
             raise IndexError(
                 "Given source size does not match actual data size"
             )
+        if self.is_unsigned is None:
+            # Only positive values -> use unsigned integers
+            self.is_unsigned = data.min().item() >= 0
 
         data = data.astype(np.int32, copy=False)
         return self._encode(
@@ -672,7 +696,7 @@ class IntegerPackingEncoding(Encoding):
         # Get length of output array
         # by summing up required length of each element
         cdef int number
-        cdef int length = 0
+        cdef long length = 0
         for i in range(data.shape[0]):
             number = data[i]
             if number < 0:
@@ -750,7 +774,7 @@ class StringArrayEncoding(Encoding):
         If omitted, the unique strings are determined from the data the
         first time :meth:`encode()` is called.
     data_encoding : list of Encoding, optional
-        The encodings that are applied to the indiy array.
+        The encodings that are applied to the index array.
         If omitted, the array is directly encoded into bytes without
         further compression.
     offset_encoding : list of Encoding, optional
@@ -837,8 +861,11 @@ class StringArrayEncoding(Encoding):
             raise TypeError("Data must be of string type")
 
         if self.strings is None:
-            # 'unique()' already sorts the strings
-            self.strings = np.unique(data)
+            # 'unique()' already sorts the strings, but this is not necessarily
+            # desired, as this makes efficient encoding of the indices more difficult
+            # -> Bring into the original order
+            _, unique_indices = np.unique(data, return_index=True)
+            self.strings = data[np.sort(unique_indices)]
             check_present = False
         else:
             check_present = True
@@ -888,6 +915,19 @@ _encoding_classes_kinds = {
 
 
 def deserialize_encoding(content):
+    """
+    Create a :class:`Encoding` by deserializing the given *BinaryCIF* content.
+
+    Parameters
+    ----------
+    content : dict
+        The encoding represenet as *BinaryCIF* dictionary.
+
+    Returns
+    -------
+    encoding : Encoding
+        The deserialized encoding.
+    """
     try:
         encoding_class = _encoding_classes[content["kind"]]
     except KeyError:
@@ -898,28 +938,69 @@ def deserialize_encoding(content):
 
 
 def create_uncompressed_encoding(array):
-    dtype = array.dtype
+    """
+    Create a simple encoding for the given array that does not compress the data.
 
-    if np.issubdtype(dtype, np.str_):
+    Parameters
+    ----------
+    array : ndarray
+        The array to to create the encoding for.
+
+    Returns
+    -------
+    encoding : list of Encoding
+        The encoding for the data.
+    """
+    if np.issubdtype(array.dtype, np.str_):
         return [StringArrayEncoding()]
     else:
         return [ByteArrayEncoding()]
 
 
 def encode_stepwise(data, encoding):
+    """
+    Apply a list of encodings stepwise to the given data.
+
+    Parameters
+    ----------
+    data : ndarray
+        The data to be encoded.
+    encoding : list of Encoding
+        The encodings to be applied.
+
+    Returns
+    -------
+    encoded_data : ndarray or bytes
+        The encoded data.
+    """
     for encoding in encoding:
         data = encoding.encode(data)
     return data
 
 
 def decode_stepwise(data, encoding):
+    """
+    Apply a list of encodings stepwise to the given data.
+
+    Parameters
+    ----------
+    data : ndarray or bytes
+        The data to be decoded.
+    encoding : list of Encoding
+        The encodings to be applied.
+
+    Returns
+    -------
+    decoded_data : ndarray
+        The decoded data.
+    """
     for enc in reversed(encoding):
         data = enc.decode(data)
     return data
 
 
 def _camel_to_snake_case(attribute_name):
-    return re.sub(CAMEL_CASE_PATTERN, "_", attribute_name).lower()
+    return CAMEL_CASE_PATTERN.sub("_", attribute_name).lower()
 
 
 def _snake_to_camel_case(attribute_name):

biotite/structure/io/trajfile.py

@@ -54,9 +54,9 @@ class TrajectoryFile(File, metaclass=abc.ABCMeta):
 
         Parameters
         ----------
-        file_name : str
+        file_name : str or Path
             The path of the file to be read.
-            A file-like-object cannot be used.
+            Any other file-like object cannot be used.
         start : int, optional
             The frame index, where file parsing is started. If no value
             is given, parsing starts at the first frame.
@@ -101,7 +101,7 @@ class TrajectoryFile(File, metaclass=abc.ABCMeta):
                 chunk_size = ((chunk_size // step) + 1) * step
 
         traj_type = cls.traj_type()
-        with traj_type(file_name, "r") as f:
+        with traj_type(str(file_name), "r") as f:
             if start is None:
                 start = 0
             # Discard atoms before start
@@ -153,9 +153,9 @@ class TrajectoryFile(File, metaclass=abc.ABCMeta):
 
         Parameters
         ----------
-        file_name : str
+        file_name : str or Path
             The path of the file to be read.
-            A file-like-object cannot be used.
+            Any other file-like object cannot be used.
         start : int, optional
             The frame index, where file parsing is started. If no value
             is given, parsing starts at the first frame.
@@ -196,7 +196,7 @@ class TrajectoryFile(File, metaclass=abc.ABCMeta):
         The `step` parameter does currently not work for *DCD* files.
         """
         traj_type = cls.traj_type()
-        with traj_type(file_name, "r") as f:
+        with traj_type(str(file_name), "r") as f:
             if start is None:
                 start = 0
             # Discard atoms before start
@@ -280,9 +280,9 @@ class TrajectoryFile(File, metaclass=abc.ABCMeta):
 
         Parameters
         ----------
-        file_name : str
+        file_name : str or Path
             The path of the file to be read.
-            A file-like-object cannot be used.
+            Any other file-like object cannot be used.
         template : AtomArray or AtomArrayStack
             The template array or stack, where the atom annotation data
             is taken from.
@@ -354,13 +354,13 @@ class TrajectoryFile(File, metaclass=abc.ABCMeta):
 
         Parameters
         ----------
-        file_name : str
-            The path of the file to be written to.
-            A file-like-object cannot be used.
+        file_name : str or Path
+            The path of the file to be read.
+            Any other file-like object cannot be used.
         """
         traj_type = self.traj_type()
         param = self.prepare_write_values(self._coord, self._box, self._time)
-        with traj_type(file_name, "w") as f:
+        with traj_type(str(file_name), "w") as f:
             f.write(**param)
 
     @classmethod
@@ -378,9 +378,9 @@ class TrajectoryFile(File, metaclass=abc.ABCMeta):
 
         Parameters
         ----------
-        file_name : str
-            The path of the file to be written to.
-            A file-like-object cannot be used.
+        file_name : str or Path
+            The path of the file to be read.
+            Any other file-like object cannot be used.
         coord : generator or array-like of ndarray, shape=(n,3), dtype=float
             The atom coordinates for each frame.
         box : generator or array-like of ndarray, shape=(3,3), dtype=float, optional
@@ -398,7 +398,7 @@ class TrajectoryFile(File, metaclass=abc.ABCMeta):
             time = itertools.repeat(None)
 
         traj_type = cls.traj_type()
-        with traj_type(file_name, "w") as f:
+        with traj_type(str(file_name), "w") as f:
             for c, b, t in zip(coord, box, time):
                 if c.ndim != 2:
                     raise IndexError(