biotite 1.1.0__cp313-cp313-macosx_11_0_arm64.whl → 1.3.0__cp313-cp313-macosx_11_0_arm64.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/graphics/rna.py

@@ -57,59 +57,62 @@ def plot_nucleotide_secondary_structure(
         sequence. The positions are counted from zero.
     length : int
         The number of bases in the sequence.
-    layout_type : RNAplotApp.Layout, optional (default: RNAplotApp.Layout.NAVIEW)
+    layout_type : RNAplotApp.Layout, optional
         The layout type according to the *RNAplot* documentation.
-    draw_pseudoknots : bool, optional (default: True)
+    draw_pseudoknots : bool, optional
         Whether pseudoknotted bonds should be drawn.
-    pseudoknot_order : iterable, optional (default: None)
+    pseudoknot_order : iterable, optional
         The pseudoknot order of each pair in the input `base_pairs`.
         If no pseudoknot order is given, a solution determined by
         :func:`biotite.structure.pseudoknots` is picked at random.
-    angle : int or float, optional (default: 0)
+    angle : int or float, optional
         The angle the plot should be rotated.
-    bond_linewidth : float or int or iterable, optional (default: 1)
+    bond_linewidth : float or int or iterable, optional
         The linewidth of each bond. Provide a single value to set the
         linewidth for all bonds or an iterable to set the linewidth for
         each individual bond.
-    bond_linestyle : str or iterable, optional (default: None)
+    bond_linestyle : str or iterable, optional
         The *Matplotlib* compatible linestyle of each bond. Provide a
         single value to set the linewidth for all bonds or an iterable
         to set the linewidth for each individual bond. By default, solid
         lines are used for non-pseudoknotted bonds and dashed lines are
         used for pseudoknotted bonds.
-    bond_color : str or ndarray, shape(n,) or shape(n,3) or shape(n,4), optional (default: 'black')
+    bond_color : str or ndarray, shape(n,) or shape(n,3) or shape(n,4), optional
         The *Matplotlib* compatible color of each bond. Provide a single
         string to set the color for all bonds or an array to set the
         color for each individual bond.
-    backbone_linewidth : float, optional (default: 1)
+    backbone_linewidth : float, optional
         The linewidth of the backbone.
-    backbone_linestyle : str, optional (default: 'solid')
+    backbone_linestyle : str, optional
         The *Matplotlib* compatible linestyle of the backbone.
-    backbone_color : str or ndarray, shape=(3,) or shape=(4,), dtype=float, optional (default: 'grey')
+    backbone_color : str or ndarray, shape=(3,) or shape=(4,), dtype=float, optional
         The *Matplotlib* compatible color of the backbone.
-    base_text : dict or iterable, optional (default: {'size': 'small'})
+    base_text : dict or iterable, optional
         The keyword parameters for the *Matplotlib* ``Text`` objects
         denoting the type of each base. Provide a single value to set
         the parameters for all labels or an iterable to set the
         parameters for each individual label.
-    base_box : dict or iterable, optional (default: {'pad'=0, 'color'='white'})
+        The default is ``{'size': 'small'}``.
+    base_box : dict or iterable, optional)
         The *Matplotlib* compatible properties of the ``FancyBboxPatch``
         surrounding the base labels. Provide a single dictionary to
         set the properties of all base lables or an iterable to set the
         properties for each individual label.
-    annotation_positions : iterable, optional (default: None)
+        The default is ``{'pad'=0, 'color'='white'}``.
+    annotation_positions : iterable, optional
         The positions of the bases to be numbered. By default every
         second base is annotated. Please note that while the positions
         in the sequence are counted from zero, they are displayed on the
         graph counted from one.
-    annotation_offset : int or float, optional (default: 8.5)
+    annotation_offset : int or float, optional
         The offset of the annotations from the base labels.
-    annotation_text : dict or iterable, optional (default: {'size': 'small'})
+    annotation_text : dict or iterable, optional
         The keyword parameters for the *Matplotlib* ``Text`` objects
         annotating the sequence. Provide a single value to set the
         parameters for all annotations or an iterable to set the
         parameters for each individual annotation.
-    border : float, optional (default: 0.03)
+        The default is ``{'size': 'small'}``.
+    border : float, optional
         The percentage of the coordinate range to be left as whitespace
         to create a border around the plot.
     bin_path : str, optional

biotite/structure/hbond.py

@@ -43,30 +43,27 @@ 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
-        Elements to be considered as possible donors or acceptors
-        (Default: O, N, S).
+        considered a hydrogen bond.
+    donor_elements, acceptor_elements : tuple of str
+        Elements to be considered as possible donors or acceptors.
     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 +79,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 +93,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 +128,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 +397,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 +409,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.