biotite 1.1.0__cp313-cp313-win_amd64.whl → 1.2.0__cp313-cp313-win_amd64.whl

biotite/structure/geometry.py

@@ -60,9 +60,9 @@ def displacement(atoms1, atoms2, box=None):
         The displacement vector(s). The shape is equal to the shape of
         the input `atoms` with the highest dimensionality.
 
-    See also
+    See Also
     --------
-    index_displacement
+    index_displacement : The same calculation, but using atom indices.
     """
     v1 = coord(atoms1)
     v2 = coord(atoms2)
@@ -191,7 +191,7 @@ def index_displacement(*args, **kwargs):
     copy is found for non-orthorhombic boxes; this is especially true
     for heavily skewed boxes.
 
-    See also
+    See Also
     --------
     displacement
     """
@@ -224,9 +224,9 @@ def distance(atoms1, atoms2, box=None):
         The shape is equal to the shape of the input `atoms` with the
         highest dimensionality minus the last axis.
 
-    See also
+    See Also
     --------
-    index_distance
+    index_distance : The same calculation, but using atom indices.
     """
     diff = displacement(atoms1, atoms2, box)
     return np.sqrt(vector_dot(diff, diff))
@@ -282,7 +282,7 @@ def index_distance(*args, **kwargs):
     copy is found for non-orthorhombic boxes; this is especially true
     for heavily skewed boxes.
 
-    See also
+    See Also
     --------
     distance
     """
@@ -312,9 +312,9 @@ def angle(atoms1, atoms2, atoms3, box=None):
         of the input `atoms` with the highest dimensionality minus the
         last axis.
 
-    See also
+    See Also
     --------
-    index_angle
+    index_angle : The same calculation, but using atom indices.
     """
     v1 = displacement(atoms1, atoms2, box)
     v2 = displacement(atoms3, atoms2, box)
@@ -371,7 +371,7 @@ def index_angle(*args, **kwargs):
     copy is found for non-orthorhombic boxes; this is especially true
     for heavily skewed boxes.
 
-    See also
+    See Also
     --------
     angle
     """
@@ -404,8 +404,8 @@ def dihedral(atoms1, atoms2, atoms3, atoms4, box=None):
 
     See Also
     --------
-    index_dihedral
-    dihedral_backbone
+    index_dihedral : The same calculation, but using atom indices.
+    dihedral_backbone : Calculate the dihedral angle along a peptide backbone.
     """
     v1 = displacement(atoms1, atoms2, box)
     v2 = displacement(atoms2, atoms3, box)
@@ -472,7 +472,7 @@ def index_dihedral(*args, **kwargs):
     copy is found for non-orthorhombic boxes; this is especially true
     for heavily skewed boxes.
 
-    See also
+    See Also
     --------
     dihedral
     dihedral_backbone
@@ -486,7 +486,7 @@ def dihedral_backbone(atom_array):
 
     Parameters
     ----------
-    atoms: AtomArray or AtomArrayStack
+    atom_array : AtomArray or AtomArrayStack
         The protein structure to measure the dihedral angles for.
         For missing backbone atoms the corresponding angles are `NaN`.
 
@@ -568,7 +568,7 @@ def centroid(atoms):
 
     Parameters
     ----------
-    atoms: ndarray or AtomArray or AtomArrayStack
+    atoms : ndarray or AtomArray or AtomArrayStack
         The structures to determine the centroid from.
         Alternatively an ndarray containing the coordinates can be
         provided.
@@ -603,7 +603,7 @@ def _call_non_index_function(
                 box = atoms.box
             else:
                 raise ValueError(
-                    "If `atoms` are coordinates, " "the box must be set explicitly"
+                    "If `atoms` are coordinates, the box must be set explicitly"
                 )
     else:
         box = None

biotite/structure/hbond.py

@@ -43,30 +43,28 @@ def hbond(
     ----------
     atoms : AtomArray or AtomArrayStack
         The atoms to find hydrogen bonds in.
-    selection1, selection2: ndarray or None
+    selection1, selection2 : ndarray, optional
         Boolean mask for atoms to limit the hydrogen bond search to
         specific sections of the model. The shape must match the
         shape of the `atoms` argument. If None is given, the whole atoms
-        stack is used instead. (Default: None)
-    selection1_type: {'acceptor', 'donor', 'both'}, optional (default: 'both')
+        stack is used instead.
+    selection1_type : {'acceptor', 'donor', 'both'}, optional
         Determines the type of `selection1`.
         The type of `selection2` is chosen accordingly
         ('both' or the opposite).
-        (Default: 'both')
     cutoff_dist : float, optional
         The maximal distance between the hydrogen and acceptor to be
-        considered a hydrogen bond. (Default: 2.5)
+        considered a hydrogen bond.
     cutoff_angle : float, optional
         The angle cutoff in degree between Donor-H..Acceptor to be
-        considered a hydrogen bond (default: 120).
-    donor_elements, acceptor_elements: tuple of str
+        considered a hydrogen bond.
+    donor_elements, acceptor_elements : tuple of str
         Elements to be considered as possible donors or acceptors
         (Default: O, N, S).
     periodic : bool, optional
         If true, hydrogen bonds can also be detected in periodic
         boundary conditions.
         The `box` attribute of `atoms` is required in this case.
-        (Default: False).
 
     Returns
     -------
@@ -82,6 +80,10 @@ def hbond(
         `triplets` is present in the model *m* of the input `atoms`.
         Only returned if `atoms` is an :class:`AtomArrayStack`.
 
+    See Also
+    --------
+    hbond_frequency : Compute the frequency of each bond over the models.
+
     Notes
     -----
     The result of this function may include false positives:
@@ -92,6 +94,11 @@ def hbond(
     considered as acceptor atom by this method, although this does
     make sense from a chemical perspective.
 
+    References
+    ----------
+
+    .. footbibliography::
+
     Examples
     --------
     Calculate the total number of hydrogen bonds found in each model:
@@ -122,15 +129,6 @@ def hbond(
         A      15  GLY N      N         8.320   -3.632   -0.318
         A      16  ARG N      N         8.043   -1.206   -1.866
         A       6  TRP NE1    N         3.420    0.332   -0.121
-
-    See Also
-    --------
-    hbond_frequency
-
-    References
-    ----------
-
-    .. footbibliography::
     """
     if not (atoms.element == "H").any():
         warnings.warn(
@@ -400,7 +398,7 @@ def hbond_frequency(mask):
 
     Parameters
     ----------
-    mask: ndarray, dtype=bool, shape=(m,n)
+    mask : ndarray, dtype=bool, shape=(m,n)
         Input mask obtained from `hbond` function.
 
     Returns
@@ -412,7 +410,7 @@ def hbond_frequency(mask):
 
     See Also
     --------
-    hbond
+    hbond : Returns the mask that can be input into this function.
 
     Examples
     --------

biotite/structure/info/atoms.py

@@ -18,7 +18,7 @@ NON_HETERO_RESIDUES = set([
 # fmt: on
 
 
-def residue(res_name):
+def residue(res_name, allow_missing_coord=False):
     """
     Get an atom array, representing the residue with the given name.
 
@@ -30,6 +30,11 @@ def residue(res_name):
     ----------
     res_name : str
         The up to 3-letter name of the residue.
+    allow_missing_coord : bool, optional
+        Whether to allow missing coordinate values in the residue.
+        If ``True``, these will be represented as ``nan`` values.
+        If ``False``, a ``ValueError`` is raised when missing coordinates
+        are encountered.
 
     Returns
     -------
@@ -74,7 +79,11 @@ def residue(res_name):
     from biotite.structure.io.pdbx import get_component
 
     try:
-        component = get_component(get_ccd(), res_name=res_name)
+        component = get_component(
+            get_ccd(),
+            res_name=res_name,
+            allow_missing_coord=allow_missing_coord,
+        )
     except KeyError:
         raise KeyError(f"No atom information found for residue '{res_name}' in CCD")
     component.hetero[:] = res_name not in NON_HETERO_RESIDUES

biotite/structure/info/ccd.py

@@ -44,7 +44,6 @@ def get_ccd():
     ----------
 
     .. footbibliography::
-
     """
     # Avoid circular import
     from biotite.structure.io.pdbx.bcif import BinaryCIFFile
@@ -123,7 +122,6 @@ def get_from_ccd(category_name, comp_id, column_name=None):
     ----------
 
     .. footbibliography::
-
     """
     try:
         start, stop = _residue_index(category_name)[comp_id]

biotite/structure/info/groups.py

@@ -61,7 +61,6 @@ def amino_acid_names():
     ----------
 
     .. footbibliography::
-
     """
     return _get_group_members(_AMINO_ACID_TYPES)
 
@@ -83,7 +82,6 @@ def nucleotide_names():
     ----------
 
     .. footbibliography::
-
     """
     return _get_group_members(_NUCLEOTIDE_TYPES)
 
@@ -105,7 +103,6 @@ def carbohydrate_names():
     ----------
 
     .. footbibliography::
-
     """
     return _get_group_members(_CARBOHYDRATE_TYPES)
 

biotite/structure/info/misc.py

@@ -127,7 +127,6 @@ def one_letter_code(res_name):
     alpha-D-mannopyranose
     >>> print(one_letter_code("MAN"))
     None
-
     """
     column = get_from_ccd("chem_comp", res_name.upper(), "one_letter_code")
     if column is None:

biotite/structure/info/radii.py

@@ -26,37 +26,106 @@ _PROTOR_RADII = {
     ("S",  1, 0) : 1.77,
     ("S",  2, 0) : 1.77, # Not official, added for completeness (MET)
     ("S",  2, 1) : 1.77,
-    ("F",  1, 0) : 1.47, # Taken from _SINGLE_RADII
-    ("CL", 1, 0) : 1.75, # Taken from _SINGLE_RADII
-    ("BR", 1, 0) : 1.85, # Taken from _SINGLE_RADII
+    ("F",  1, 0) : 1.47, # Taken from _SINGLE_ATOM_VDW_RADII
+    ("CL", 1, 0) : 1.75, # Taken from _SINGLE_ATOM_VDW_RADII
+    ("BR", 1, 0) : 1.85, # Taken from _SINGLE_ATOM_VDW_RADII
     ("I",  1, 0) : 1.98, # Taken from _SINGLE_RADII
 }
 
-_SINGLE_RADII = {
-    "H":  1.20,
+_SINGLE_ATOM_VDW_RADII = {
+    # Main group
+    # Row 1 (Period 1)
+    "H":  1.10,
     "HE": 1.40,
 
+    # Row 2 (Period 2)
+    "LI": 1.81,
+    "BE": 1.53,
+    "B":  1.92,
     "C":  1.70,
     "N":  1.55,
     "O":  1.52,
     "F":  1.47,
     "NE": 1.54,
 
+    # Row 3 (Period 3)
+    "NA": 2.27,
+    "MG": 1.73,
+    "AL": 1.84,
     "SI": 2.10,
     "P":  1.80,
     "S":  1.80,
     "CL": 1.75,
     "AR": 1.88,
 
+    # Row 4 (Period 4)
+    "K":  2.75,
+    "CA": 2.31,
+    "GA": 1.87,
+    "GE": 2.11,
     "AS": 1.85,
     "SE": 1.90,
-    "BR": 1.85,
+    "BR": 1.83,
     "KR": 2.02,
 
+    # Row 5 (Period 5)
+    "RB": 3.03,
+    "SR": 2.49,
+    "IN": 1.93,
+    "SN": 2.17,
+    "SB": 2.06,
     "TE": 2.06,
     "I":  1.98,
     "XE": 2.16,
+
+    # Row 6 (Period 6)
+    "CS": 3.43,
+    "BA": 2.68,
+    "TL": 1.96,
+    "PB": 2.02,
+    "BI": 2.07,
+    "PO": 1.97,
+    "AT": 2.02,
+    "RN": 2.20,
+
+    # Row 7 (Period 7)
+    "FR": 3.48,
+    "RA": 2.83,
+
+    # Transition metals (relevant ones only)
+    # Row 1
+    "FE": 2.05,
+    "CU": 2.00,
+    "ZN": 2.10,
+    "MN": 2.05,
+    "CO": 2.00,
+    "NI": 2.00,
+
+    # Row 2
+    'MO': 2.10,
+    'RU': 2.05,
+
+    # Row 3
+    'W': 2.10,
+    'PT': 2.05,
+    'AU': 2.10,
 }
+"""
+Van der Waals radii for main group and transition elements.
+
+Main group:
+Source: https://pubs.acs.org/doi/10.1021/jp8111556, Table 12 (Mantina et al. 2009)
+
+Transition metals:
+Source: RDKit, 2024.9.4 Release
+https://github.com/rdkit/rdkit/blob/af6347963f25cfe8fe4db0638410b2f3a8e8bd89/Code/GraphMol/atomic_data.cpp#L51
+
+Where available, these values were cross-checked vs the CRC Handbook of
+Chemistry and Physics (105th edition) and verified that they are closely
+in line (barring very minor discrepancies, usually < 0.05 Å).
+We cannot use the CRC values directly as they are not permissively licensed.
+"""
+
 # fmt: on
 
 # A dictionary that caches radii for each residue
@@ -65,16 +134,15 @@ _protor_radii = {}
 
 def vdw_radius_protor(res_name, atom_name):
     """
-    Estimate the Van-der-Waals radius of an non-hydrogen atom,
+    Estimate the Van-der-Waals radius of a heavy atom,
     that includes the radius added by potential bonded hydrogen atoms.
     The respective radii are taken from the ProtOr dataset.
     :footcite:`Tsai1999`
 
     This is especially useful for macromolecular structures where no
     hydrogen atoms are resolved, e.g. crystal structures.
-    The valency of the non-hydrogen atom and the amount of normally
-    bonded hydrogen atoms is taken from the chemical compound dictionary
-    dataset.
+    The valency of the heavy atom and the amount of normally
+    bonded hydrogen atoms is taken from the *Chemical Component Dictionary*.
 
     Parameters
     ----------
@@ -86,12 +154,13 @@ def vdw_radius_protor(res_name, atom_name):
 
     Returns
     -------
-    The Van-der-Waals radius of the given atom.
-    If the radius cannot be estimated for the atom, `None` is returned.
+    radius : float
+        The Van-der-Waals radius of the given atom.
+        If the radius cannot be estimated for the atom, `None` is returned.
 
-    See also
+    See Also
     --------
-    vdw_radius_single
+    vdw_radius_single : *Van-der-Waals* radii for structures with annotated hydrogen atoms.
 
     References
     ----------
@@ -114,7 +183,7 @@ def vdw_radius_protor(res_name, atom_name):
         # Use cached radii for the residue, if already calculated
         if atom_name not in _protor_radii[res_name]:
             raise KeyError(
-                f"Residue '{res_name}' does not contain an atom named " f"'{atom_name}'"
+                f"Residue '{res_name}' does not contain an atom named '{atom_name}'"
             )
         return _protor_radii[res_name].get(atom_name)
     else:
@@ -166,8 +235,8 @@ def _calculate_protor_radii(res_name):
 
 def vdw_radius_single(element):
     """
-    Get the Van-der-Waals radius of an atom from the given element.
-    :footcite:`Bondi1964`
+    Get the *Van-der-Waals* radius of an atom from the given element.
+    :footcite:`Mantina2009`
 
     Parameters
     ----------
@@ -176,12 +245,13 @@ def vdw_radius_single(element):
 
     Returns
     -------
-    The Van-der-Waals radius of the atom.
-    If the radius is unknown for the element, `None` is returned.
+    radius : float
+        The Van-der-Waals radius of the atom.
+        If the radius is unknown for the element, `None` is returned.
 
-    See also
+    See Also
     --------
-    vdw_radius_protor
+    vdw_radius_protor : *Van-der-Waals* radii for structures without annotated hydrogen atoms.
 
     References
     ----------
@@ -194,4 +264,4 @@ def vdw_radius_single(element):
     >>> print(vdw_radius_single("C"))
     1.7
     """
-    return _SINGLE_RADII.get(element.upper())
+    return _SINGLE_ATOM_VDW_RADII.get(element.upper())

biotite/structure/info/standardize.py

@@ -125,8 +125,7 @@ def standardize_order(atoms):
         if chem_comp_atom is None:
             # If the residue is not in the CCD, keep the current order
             warnings.warn(
-                f"Residue '{res_name}' is not in the CCD, "
-                f"keeping current atom order"
+                f"Residue '{res_name}' is not in the CCD, keeping current atom order"
             )
             reordered_indices[start:stop] = np.arange(start, stop)
             continue

biotite/structure/integrity.py

@@ -47,7 +47,7 @@ def check_atom_id_continuity(array):
     Returns
     -------
     discontinuity : ndarray, dtype=int
-        Contains the indices of atoms after a discontinuity
+        Contains the indices of atoms after a discontinuity.
     """
     ids = array.atom_id
     return _check_continuity(ids)
@@ -69,7 +69,7 @@ def check_res_id_continuity(array):
     Returns
     -------
     discontinuity : ndarray, dtype=int
-        Contains the indices of atoms after a discontinuity
+        Contains the indices of atoms after a discontinuity.
     """
     ids = array.res_id
     return _check_continuity(ids)
@@ -96,10 +96,8 @@ def check_linear_continuity(array, min_len=1.2, max_len=1.8):
 
     See Also
     --------
-    biotite.structure.filter.filter_linear_bond_continuity :
-        A function to filter for atoms preserving the continuity (used here).
-    biotite.structure.bonds.BondList :
-        A class that doesn't depend on the atoms' order to identify bonds.
+    filter_linear_bond_continuity : A function to filter for atoms preserving the continuity (used here).
+    BondList : A class that doesn't depend on the atoms' order to identify bonds.
     """
     con_mask = filter_linear_bond_continuity(array, min_len, max_len)
     # The continuity mask `con_mask` points to atoms for which the next atom is continuous.

biotite/structure/io/general.py

@@ -34,7 +34,7 @@ def load_structure(file_path, template=None, **kwargs):
         The path to structure file.
     template : AtomArray or AtomArrayStack or file-like object or str, optional
         Only required when reading a trajectory file.
-    kwargs
+    **kwargs
         Additional parameters will be passed to either the
         :func:`get_structure()` or :func:`read()` method of the file
         object.
@@ -146,7 +146,7 @@ def save_structure(file_path, array, **kwargs):
         The path to structure file.
     array : AtomArray or AtomArrayStack
         The structure to be saved.
-    kwargs
+    **kwargs
         Additional parameters will be passed to the respective `set_structure`
         method.
 

biotite/structure/io/gro/file.py

@@ -48,7 +48,6 @@ class GROFile(TextFile):
     >>> file = GROFile()
     >>> file.set_structure(array_stack_mod)
     >>> file.write(os.path.join(path_to_directory, "1l2y_mod.gro"))
-
     """
 
     def get_model_count(self):
@@ -89,13 +88,13 @@ class GROFile(TextFile):
             The return type depends on the `model` parameter.
         """
 
-        def get_atom_line_i(model_start_i, model_atom_counts):
+        def _get_atom_line_i(model_start_i, model_atom_counts):
             """
             Helper function to get the indices of all atoms for a model
             """
             return np.arange(model_start_i + 1, model_start_i + 1 + model_atom_counts)
 
-        def set_box_dimen(box_param):
+        def _set_box_dimen(box_param):
             """
             Helper function to create the box vectors from the values
             in the GRO file
@@ -145,7 +144,7 @@ class GROFile(TextFile):
 
             # Line indices for annotation determination is determined
             # from model 1
-            annot_i = get_atom_line_i(model_start_i[0], length)
+            annot_i = _get_atom_line_i(model_start_i[0], length)
         else:
             if model == 0:
                 raise ValueError("The model index must not be 0")
@@ -160,7 +159,7 @@ class GROFile(TextFile):
             length = model_atom_counts[model - 1]
             array = AtomArray(length)
 
-            annot_i = get_atom_line_i(model_start_i[model - 1], length)
+            annot_i = _get_atom_line_i(model_start_i[model - 1], length)
 
         # Replace empty strings for elements with guessed types
         # i is index in array, line_i is line index
@@ -183,11 +182,11 @@ class GROFile(TextFile):
             # Box is stored in last line (after coordinates)
             box_i = atom_i[-1] + 1
             box_param = [float(e) * 10 for e in self.lines[box_i].split()]
-            array.box = set_box_dimen(box_param)
+            array.box = _set_box_dimen(box_param)
 
         elif isinstance(array, AtomArrayStack):
             for m in range(len(model_start_i)):
-                atom_i = get_atom_line_i(model_start_i[m], model_atom_counts[m])
+                atom_i = _get_atom_line_i(model_start_i[m], model_atom_counts[m])
                 for i, line_i in enumerate(atom_i):
                     line = self.lines[line_i]
                     array.coord[m, i, 0] = float(line[20:28]) * 10
@@ -196,7 +195,7 @@ class GROFile(TextFile):
                 # Box is stored in last line (after coordinates)
                 box_i = atom_i[-1] + 1
                 box_param = [float(e) * 10 for e in self.lines[box_i].split()]
-                box = set_box_dimen(box_param)
+                box = _set_box_dimen(box_param)
                 # Create a box in the stack if not already existing
                 # and the box is not a dummy
                 if box is not None:
@@ -311,7 +310,7 @@ class GROFile(TextFile):
 
             for i in range(array.stack_depth()):
                 self.lines.append(
-                    f"Generated by Biotite at {datetime.now()}, model={i+1}"
+                    f"Generated by Biotite at {datetime.now()}, model={i + 1}"
                 )
                 self.lines.append(str(array.array_length()))
 

biotite/structure/io/mol/convert.py

@@ -52,7 +52,7 @@ def set_structure(
     ----------
     mol_file : MOLFile
         The MOL file.
-    array : AtomArray
+    atoms : AtomArray
         The array to be saved into this file.
         Must have an associated :class:`BondList`.
         Bond type fallback for the *Bond block*, if a