biotite 1.3.0__tar.gz → 1.5.0__tar.gz

{biotite-1.3.0 → biotite-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: biotite
-Version: 1.3.0
+Version: 1.5.0
 Summary: A comprehensive library for computational molecular biology
 Project-URL: homepage, https://www.biotite-python.org
 Project-URL: repository, https://github.com/biotite-dev/biotite

{biotite-1.3.0 → biotite-1.5.0}/src/biotite/application/dssp/app.py

@@ -11,8 +11,13 @@ from tempfile import NamedTemporaryFile
 import numpy as np
 from biotite.application.application import AppState, requires_state
 from biotite.application.localapp import LocalApp, cleanup_tempfile, get_version
-from biotite.structure.io.pdbx.cif import CIFFile
+from biotite.structure.error import BadStructureError
+from biotite.structure.filter import filter_amino_acids
+from biotite.structure.io.pdbx.cif import CIFCategory, CIFColumn, CIFFile
+from biotite.structure.io.pdbx.component import MaskValue
 from biotite.structure.io.pdbx.convert import set_structure
+from biotite.structure.repair import create_continuous_res_ids
+from biotite.structure.residues import get_residue_starts
 
 
 class DsspApp(LocalApp):
@@ -49,17 +54,19 @@ class DsspApp(LocalApp):
     >>> app.start()
     >>> app.join()
     >>> print(app.get_sse())
-    ['C' 'H' 'H' 'H' 'H' 'H' 'H' 'H' 'T' 'T' 'G' 'G' 'G' 'G' 'T' 'C' 'C' 'C'
-     'C' 'C']
+    ['C' 'H' 'H' 'H' 'H' 'H' 'H' 'H' 'T' 'T' 'G' 'G' 'G' 'G' 'T' 'C' 'P' 'P'
+     'P' 'C']
     """
 
     def __init__(self, atom_array, bin_path="mkdssp"):
         super().__init__(bin_path)
 
-        # mkdssp requires also the
-        # 'occupancy', 'b_factor' and 'charge' fields
-        # -> Add these annotations to a copy of the input structure
+        if not np.all(filter_amino_acids(atom_array)):
+            raise BadStructureError("The input structure must contain only amino acids")
         self._array = atom_array.copy()
+        # DSSP requires also the
+        # 'occupancy', 'b_factor' and 'charge' fields
+        # -> Add these placeholder values
         categories = self._array.get_annotation_categories()
         if "charge" not in categories:
             self._array.set_annotation(
@@ -73,6 +80,10 @@ class DsspApp(LocalApp):
             self._array.set_annotation(
                 "occupancy", np.ones(self._array.array_length(), dtype=float)
             )
+        # DSSP>=4 complains about the `pdbx_poly_seq_scheme` category,
+        # if `seq_id` does not start at 1
+        self._array.res_id = create_continuous_res_ids(self._array)
+
         try:
             # The parameters have changed in version 4
             self._new_cli = get_version(bin_path)[0] >= 4
@@ -86,6 +97,9 @@ class DsspApp(LocalApp):
     def run(self):
         in_file = CIFFile()
         set_structure(in_file, self._array)
+        in_file.block["pdbx_poly_seq_scheme"] = _create_pdbx_poly_seq_scheme(
+            self._array, in_file.block["atom_site"]["label_entity_id"].as_array(str)
+        )
         in_file.write(self._in_file)
         self._in_file.flush()
         if self._new_cli:
@@ -157,3 +171,46 @@ class DsspApp(LocalApp):
         app.start()
         app.join()
         return app.get_sse()
+
+
+def _create_pdbx_poly_seq_scheme(atom_array, entity_ids):
+    """
+    Create the ``pdbx_poly_seq_scheme`` category, as required by DSSP.
+
+    Parameters
+    ----------
+    atom_array : AtomArray
+        The atom array to create the category from.
+    entity_ids : ndarray, dtype=str
+        The entity IDs for each atoms.
+
+    Returns
+    -------
+    pdbx_poly_seq_scheme : CIFCategory
+        The ``pdbx_poly_seq_scheme`` category.
+    """
+    res_start_indices = get_residue_starts(atom_array)
+    chain_id = atom_array.chain_id[res_start_indices]
+    res_name = atom_array.res_name[res_start_indices]
+    res_id = atom_array.res_id[res_start_indices]
+    ins_code = atom_array.ins_code[res_start_indices]
+    hetero = atom_array.hetero[res_start_indices]
+    entity_id = entity_ids[res_start_indices]
+
+    poly_seq_scheme = CIFCategory()
+    poly_seq_scheme["asym_id"] = chain_id
+    poly_seq_scheme["entity_id"] = entity_id
+    poly_seq_scheme["seq_id"] = res_id
+    poly_seq_scheme["mon_id"] = res_name
+    poly_seq_scheme["ndb_seq_num"] = res_id
+    poly_seq_scheme["pdb_seq_num"] = res_id
+    poly_seq_scheme["auth_seq_num"] = res_id
+    poly_seq_scheme["pdb_mon_id"] = res_name
+    poly_seq_scheme["auth_mon_id"] = res_name
+    poly_seq_scheme["pdb_strand_id"] = chain_id
+    poly_seq_scheme["pdb_ins_code"] = CIFColumn(
+        ins_code, np.where(ins_code == "", MaskValue.MISSING, MaskValue.PRESENT)
+    )
+    poly_seq_scheme["hetero"] = np.where(hetero, "y", "n")
+
+    return poly_seq_scheme

{biotite-1.3.0 → biotite-1.5.0}/src/biotite/database/afdb/download.py

@@ -16,8 +16,11 @@ from biotite.database.error import RequestError
 _METADATA_URL = "https://alphafold.com/api/prediction"
 _BINARY_FORMATS = ["bcif"]
 # Adopted from https://www.uniprot.org/help/accession_numbers
+# adding the optional 'AF-' prefix and '-F1' suffix used by RCSB
 _UNIPROT_PATTERN = (
-    "[OPQ][0-9][A-Z0-9]{3}[0-9]|[A-NR-Z][0-9]([A-Z][A-Z0-9]{2}[0-9]){1,2}"
+    r"^(?P<prefix>(AF-)|(AF_AF))?"
+    r"(?P<id>[OPQ][0-9][A-Z0-9]{3}[0-9]|[A-NR-Z][0-9]([A-Z][A-Z0-9]{2}[0-9]){1,2})"
+    r"(?P<suffix>-?F1)?$"
 )
 
 
@@ -31,8 +34,8 @@ def fetch(ids, format, target_path=None, overwrite=False, verbose=False):
     ----------
     ids : str or iterable object of str
         A single ID or a list of IDs of the file(s) to be downloaded.
-        They can be either UniProt IDs (e.g. ``P12345``) or AlphaFold DB IDs
-        (e.g. ``AF-P12345F1``).
+        They can be either UniProt IDs (e.g. ``P12345``), AlphaFold DB IDs
+        (e.g. ``AF-P12345-F1``) or computational RCSB IDs (e.g. ``AF_AFP12345F1``).
     format : {'pdb', 'pdbx', 'cif', 'mmcif', 'bcif', 'fasta'}
         The format of the files to be downloaded.
     target_path : str, optional
@@ -142,7 +145,10 @@ def _get_file_url(id, format):
         The URL of the file to be downloaded.
     """
     uniprot_id = _extract_id(id)
-    metadata = requests.get(f"{_METADATA_URL}/{uniprot_id}").json()
+    try:
+        metadata = requests.get(f"{_METADATA_URL}/{uniprot_id}").json()
+    except requests.exceptions.JSONDecodeError:
+        raise RequestError("Received malformed JSON response")
     if len(metadata) == 0:
         raise RequestError(f"ID {id} is invalid")
     # A list of length 1 is always returned, if the response is valid
@@ -167,10 +173,10 @@ def _extract_id(id):
     uniprot_id : str
         The UniProt ID.
     """
-    match = re.search(_UNIPROT_PATTERN, id)
+    match = re.match(_UNIPROT_PATTERN, id)
     if match is None:
         raise ValueError(f"Cannot extract AFDB identifier from '{id}'")
-    return match.group()
+    return match.group("id")
 
 
 def _assert_valid_file(response, id):

{biotite-1.3.0 → biotite-1.5.0}/src/biotite/database/rcsb/download.py

@@ -155,6 +155,7 @@ def _assert_valid_file(response_text, pdb_id):
             "<title>PDB Archive over AWS</title>",
             "No fasta files were found.",
             "No valid PDB IDs were submitted.",
+            "The requested URL was incorrect, too long or otherwise malformed.",
         ]
     ):
         raise RequestError("PDB ID {:} is invalid".format(pdb_id))

{biotite-1.3.0 → biotite-1.5.0}/src/biotite/database/rcsb/query.py

@@ -74,7 +74,7 @@ class SingleQuery(Query, metaclass=abc.ABCMeta):
     A terminal query node for the RCSB search API.
 
     Multiple :class:`SingleQuery` objects can be combined to
-    :class:`CompositeQuery`objects using the ``|`` and ``&`` operators.
+    :class:`CompositeQuery` objects using the ``|`` and ``&`` operators.
 
     This is the abstract base class for all queries that are
     terminal nodes.
@@ -783,7 +783,7 @@ def search(
         The type of the returned identifiers:
 
         - ``'entry'``: Only the PDB ID is returned (e.g. ``'XXXX'``).
-          These can be used directly a input to :func:`fetch()`.
+          These can be used directly as input to :func:`fetch()`.
         - ``'assembly'``: The PDB ID appended with assembly ID is
           returned (e.g. ``'XXXX-1'``).
         - ``'polymer_entity'``: The PDB ID appended with entity ID of

{biotite-1.3.0 → biotite-1.5.0}/src/biotite/interface/pymol/object.py

@@ -388,7 +388,9 @@ class PyMOLObject:
         elif isinstance(selection, str):
             return f"%{self._name} and ({selection})"
         else:
-            sel = self.where(np.asarray(selection))
+            if not isinstance(selection, slice):
+                selection = np.asarray(selection)
+            sel = self.where(selection)
             if sel == "none" and not_none:
                 raise ValueError("Selection contains no atoms")
             return sel

{biotite-1.3.0 → biotite-1.5.0}/src/biotite/interface/rdkit/mol.py

@@ -59,7 +59,7 @@ _STANDARD_ANNOTATIONS = frozenset(
         "charge",
         "b_factor",
         "occupancy",
-        "label_alt_id",
+        "altloc_id",
     }
 )
 
@@ -202,8 +202,8 @@ def to_mol(
             rdkit_atom_res_info.SetOccupancy(atoms.occupancy[i].item())
         if "b_factor" in has_annot:
             rdkit_atom_res_info.SetTempFactor(atoms.b_factor[i].item())
-        if "label_alt_id" in has_annot:
-            rdkit_atom_res_info.SetAltLoc(atoms.label_alt_id[i].item())
+        if "altloc_id" in has_annot:
+            rdkit_atom_res_info.SetAltLoc(atoms.altloc_id[i].item())
         rdkit_atom.SetPDBResidueInfo(rdkit_atom_res_info)
 
         # add extra annotations
@@ -361,7 +361,7 @@ def from_mol(mol, conformer_id=None, add_hydrogen=None):
     atoms.add_annotation("charge", int)
     atoms.add_annotation("b_factor", float)
     atoms.add_annotation("occupancy", float)
-    atoms.add_annotation("label_alt_id", str)
+    atoms.add_annotation("altloc_id", str)
 
     for rdkit_atom in rdkit_atoms:
         _atom_idx = rdkit_atom.GetIdx()
@@ -406,7 +406,7 @@ def from_mol(mol, conformer_id=None, add_hydrogen=None):
         atoms.res_id[_atom_idx] = residue_info.GetResidueNumber()
         atoms.ins_code[_atom_idx] = residue_info.GetInsertionCode()
         atoms.res_name[_atom_idx] = residue_info.GetResidueName()
-        atoms.label_alt_id[_atom_idx] = residue_info.GetAltLoc()
+        atoms.altloc_id[_atom_idx] = residue_info.GetAltLoc()
         atoms.hetero[_atom_idx] = residue_info.GetIsHeteroAtom()
         atoms.b_factor[_atom_idx] = residue_info.GetTempFactor()
         atoms.occupancy[_atom_idx] = residue_info.GetOccupancy()

{biotite-1.3.0 → biotite-1.5.0}/src/biotite/structure/atoms.py

@@ -1554,7 +1554,7 @@ def coord(item):
         Atom coordinates.
     """
 
-    if type(item) in (Atom, AtomArray, AtomArrayStack):
+    if isinstance(item, (Atom, _AtomArrayBase)):
         return item.coord
     elif isinstance(item, np.ndarray):
         return item.astype(np.float32, copy=False)

{biotite-1.3.0 → biotite-1.5.0}/src/biotite/structure/bonds.pyx

@@ -517,14 +517,41 @@ class BondList(Copyable):
         0 1 SINGLE
         1 2 DOUBLE
         """
-        bond_types = self._bonds[:,2]
         for aromatic_type, non_aromatic_type in [
             (BondType.AROMATIC_SINGLE, BondType.SINGLE),
             (BondType.AROMATIC_DOUBLE, BondType.DOUBLE),
             (BondType.AROMATIC_TRIPLE, BondType.TRIPLE),
             (BondType.AROMATIC, BondType.ANY),
         ]:
-            bond_types[bond_types == aromatic_type] = non_aromatic_type
+            mask = self._bonds[:, 2] == aromatic_type
+            self._bonds[mask, 2] = non_aromatic_type
+
+    def remove_kekulization(self):
+        """
+        Remove the bond order information from aromatic bonds, i.e. convert all
+        aromatic bonds to :attr:`BondType.ANY`.
+
+        Examples
+        --------
+
+        >>> bond_list = BondList(3)
+        >>> bond_list.add_bond(0, 1, BondType.AROMATIC_SINGLE)
+        >>> bond_list.add_bond(1, 2, BondType.AROMATIC_DOUBLE)
+        >>> bond_list.remove_kekulization()
+        >>> for i, j, bond_type in bond_list.as_array():
+        ...     print(i, j, BondType(bond_type).name)
+        0 1 AROMATIC
+        1 2 AROMATIC
+        """
+        kekulized_mask = np.isin(
+            self._bonds[:, 2],
+            (
+                BondType.AROMATIC_SINGLE,
+                BondType.AROMATIC_DOUBLE,
+                BondType.AROMATIC_TRIPLE,
+            ),
+        )
+        self._bonds[kekulized_mask, 2] = BondType.AROMATIC
 
     def remove_bond_order(self):
         """
@@ -532,6 +559,41 @@ class BondList(Copyable):
         """
         self._bonds[:,2] = BondType.ANY
 
+    def convert_bond_type(self, original_bond_type, new_bond_type):
+        """
+        convert_bond_type(original_bond_type, new_bond_type)
+
+        Convert all occurences of a given bond type into another bond type.
+
+        Parameters
+        ----------
+        original_bond_type : BondType or int
+            The bond type to convert.
+        new_bond_type : BondType or int
+            The new bond type.
+
+        Examples
+        --------
+
+        >>> bond_list = BondList(4)
+        >>> bond_list.add_bond(0, 1, BondType.DOUBLE)
+        >>> bond_list.add_bond(1, 2, BondType.COORDINATION)
+        >>> bond_list.add_bond(2, 3, BondType.COORDINATION)
+        >>> for i, j, bond_type in bond_list.as_array():
+        ...     print(i, j, BondType(bond_type).name)
+        0 1 DOUBLE
+        1 2 COORDINATION
+        2 3 COORDINATION
+        >>> bond_list.convert_bond_type(BondType.COORDINATION, BondType.SINGLE)
+        >>> for i, j, bond_type in bond_list.as_array():
+        ...     print(i, j, BondType(bond_type).name)
+        0 1 DOUBLE
+        1 2 SINGLE
+        2 3 SINGLE
+        """
+        mask = self._bonds[:, 2] == original_bond_type
+        self._bonds[mask, 2] = new_bond_type
+
     def get_atom_count(self):
         """
         get_atom_count()
@@ -1437,9 +1499,8 @@ _DEFAULT_DISTANCE_RANGE = {
 def connect_via_distances(atoms, dict distance_range=None, bint inter_residue=True,
                           default_bond_type=BondType.ANY, bint periodic=False):
     """
-    connect_via_distances(atoms, distance_range=None, atom_mask=None,
-                          inter_residue=True, default_bond_type=BondType.ANY,
-                          periodic=False)
+    connect_via_distances(atoms, distance_range=None, inter_residue=True,
+                          default_bond_type=BondType.ANY, periodic=False)
 
     Create a :class:`BondList` for a given atom array, based on
     pairwise atom distances.
@@ -1589,7 +1650,7 @@ def connect_via_distances(atoms, dict distance_range=None, bint inter_residue=Tr
 def connect_via_residue_names(atoms, bint inter_residue=True,
                               dict custom_bond_dict=None):
     """
-    connect_via_residue_names(atoms, atom_mask=None, inter_residue=True)
+    connect_via_residue_names(atoms, inter_residue=True, custom_bond_dict=None)
 
     Create a :class:`BondList` for a given atom array (stack), based on
     the deposited bonds for each residue in the RCSB ``components.cif``

{biotite-1.3.0 → biotite-1.5.0}/src/biotite/structure/box.py

@@ -361,7 +361,7 @@ def repeat_box(atoms, amount=1):
     if atoms.box is None:
         raise BadStructureError("Structure has no box")
 
-    repeat_coord, indices = repeat_box_coord(atoms.coord, atoms.box)
+    repeat_coord, indices = repeat_box_coord(atoms.coord, atoms.box, amount)
     # Unroll repeated coordinates for input to 'repeat()'
     if repeat_coord.ndim == 2:
         repeat_coord = repeat_coord.reshape(-1, atoms.array_length(), 3)

{biotite-1.3.0 → biotite-1.5.0}/src/biotite/structure/chains.py

@@ -16,6 +16,7 @@ __all__ = [
     "get_chain_masks",
     "get_chain_starts_for",
     "get_chain_positions",
+    "get_all_chain_positions",
     "chain_iter",
     "get_chains",
     "get_chain_count",
@@ -24,6 +25,7 @@ __all__ = [
 
 from biotite.structure.segments import (
     apply_segment_wise,
+    get_all_segment_positions,
     get_segment_masks,
     get_segment_positions,
     get_segment_starts,
@@ -212,11 +214,43 @@ def get_chain_positions(array, indices):
     -------
     start_indices : ndarray, dtype=int, shape=(k,)
         The indices that point to the position of the chains.
+
+    See Also
+    --------
+    get_all_chain_positions :
+        Similar to this function, but for all atoms in the :class:`struc.AtomArray`.
     """
     starts = get_chain_starts(array, add_exclusive_stop=True)
     return get_segment_positions(starts, indices)
 
 
+def get_all_chain_positions(array):
+    """
+    For each atom, obtain the position of the chain
+    corresponding to this atom in the input `array`.
+
+    For example, the position of the first chain in the atom array is
+    ``0``, the the position of the second chain is ``1``, etc.
+
+    Parameters
+    ----------
+    array : AtomArray or AtomArrayStack
+        The atom array (stack) to determine the chains from.
+
+    Returns
+    -------
+    chain_indices : ndarray, dtype=int, shape=(k,)
+        The indices that point to the position of the chains.
+
+    See Also
+    --------
+    get_chain_positions :
+        Similar to this function, but for a given subset of atom indices.
+    """
+    starts = get_chain_starts(array, add_exclusive_stop=True)
+    return get_all_segment_positions(starts, array.array_length())
+
+
 def get_chains(array):
     """
     Get the chain IDs of an atom array (stack).

{biotite-1.3.0 → biotite-1.5.0}/src/biotite/structure/compare.py

@@ -449,6 +449,8 @@ def lddt(
     # Aggregate the fractions over the desired level
     if isinstance(aggregation, str) and aggregation == "all":
         # Average over all contacts
+        if len(fraction_preserved_bins) == 0:
+            return np.float32(np.nan)
         return np.mean(fraction_preserved_bins, axis=-1)
     else:
         # A string is also a 'Sequence'

{biotite-1.3.0 → biotite-1.5.0}/src/biotite/structure/filter.py

@@ -63,7 +63,8 @@ _canonical_aa_list = [
 ]
 _canonical_nucleotide_list = ["A", "DA", "G", "DG", "C", "DC", "U", "DT"]
 
-_solvent_list = ["HOH", "SOL"]
+# Residue names of solvent molecules non only in CCD, but also from modeling software
+_solvent_list = ["HOH", "DOD", "SOL", "WAT", "H2O", "TIP3", "TIP4", "TIP5"]
 
 _peptide_backbone_atoms = ["N", "CA", "C"]
 _phosphate_backbone_atoms = ["P", "O5'", "C5'", "C4'", "C3'", "O3'"]

{biotite-1.3.0 → biotite-1.5.0}/src/biotite/structure/geometry.py

@@ -19,19 +19,79 @@ __all__ = [
     "dihedral",
     "index_dihedral",
     "dihedral_backbone",
+    "dihedral_side_chain",
     "centroid",
 ]
 
+import functools
 import numpy as np
 from biotite.structure.atoms import AtomArray, AtomArrayStack, coord
 from biotite.structure.box import coord_to_fraction, fraction_to_coord, is_orthogonal
-from biotite.structure.filter import filter_amino_acids
+from biotite.structure.filter import filter_amino_acids, filter_canonical_amino_acids
+from biotite.structure.residues import get_residue_starts
 from biotite.structure.util import (
     coord_for_atom_name_per_residue,
     norm_vector,
     vector_dot,
 )
 
+# The names of the atoms participating in chi angle
+_CHI_ATOMS = {
+    "ARG": [
+        ("N", "CA", "CB", "CG"),
+        ("CA", "CB", "CG", "CD"),
+        ("CB", "CG", "CD", "NE"),
+        ("CG", "CD", "NE", "CZ"),
+    ],
+    "LEU": [
+        ("N", "CA", "CB", "CG"),
+        # By convention chi2 is defined using CD1 instead of CD2
+        ("CA", "CB", "CG", "CD1"),
+    ],
+    "VAL": [("N", "CA", "CB", "CG1")],
+    "ILE": [("N", "CA", "CB", "CG1"), ("CA", "CB", "CG1", "CD1")],
+    "MET": [
+        ("N", "CA", "CB", "CG"),
+        ("CA", "CB", "CG", "SD"),
+        ("CB", "CG", "SD", "CE"),
+    ],
+    "LYS": [
+        ("N", "CA", "CB", "CG"),
+        ("CA", "CB", "CG", "CD"),
+        ("CB", "CG", "CD", "CE"),
+        ("CG", "CD", "CE", "NZ"),
+    ],
+    "PHE": [
+        ("N", "CA", "CB", "CG"),
+        ("CA", "CB", "CG", "CD1"),
+    ],
+    "TRP": [
+        ("N", "CA", "CB", "CG"),
+        ("CA", "CB", "CG", "CD1"),
+    ],
+    "TYR": [
+        ("N", "CA", "CB", "CG"),
+        ("CA", "CB", "CG", "CD1"),
+    ],
+    "ASN": [("N", "CA", "CB", "CG"), ("CA", "CB", "CG", "OD1")],
+    "GLN": [
+        ("N", "CA", "CB", "CG"),
+        ("CA", "CB", "CG", "CD"),
+        ("CB", "CG", "CD", "OE1"),
+    ],
+    "ASP": [("N", "CA", "CB", "CG"), ("CA", "CB", "CG", "OD1")],
+    "GLU": [
+        ("N", "CA", "CB", "CG"),
+        ("CA", "CB", "CG", "CD"),
+        ("CB", "CG", "CD", "OE1"),
+    ],
+    "CYS": [("N", "CA", "CB", "SG")],
+    "HIS": [("N", "CA", "CB", "CG"), ("CA", "CB", "CG", "ND1")],
+    "PRO": [("N", "CA", "CB", "CG"), ("CA", "CB", "CG", "CD")],
+    "SER": [("N", "CA", "CB", "OG")],
+    "THR": [("N", "CA", "CB", "OG1")],
+}
+
 
 def displacement(atoms1, atoms2, box=None):
     """
@@ -492,7 +552,7 @@ def dihedral_backbone(atom_array):
 
     Returns
     -------
-    phi, psi, omega : ndarray
+    phi, psi, omega : ndarray, shape=(m,n) or shape=(n,), dtype=float
         An array containing the 3 backbone dihedral angles for every CA atom.
         `phi` is not defined at the N-terminus, `psi` and `omega` are not defined at the
         C-terminus.
@@ -562,6 +622,96 @@ def dihedral_backbone(atom_array):
     return phi, psi, omg
 
 
+def dihedral_side_chain(atoms):
+    r"""
+    Measure the side chain :math:`\chi` dihedral angles of amino acid residues.
+
+    Parameters
+    ----------
+    atoms : AtomArray or AtomArrayStack
+        The protein structure to measure the side chain dihedral angles for.
+
+    Returns
+    -------
+    chi : ndarray, shape=(m, n, 4) or shape=(n, 4), dtype=float
+        An array containing the up to four side chain dihedral angles for every
+        amino acid residue.
+        Trailing :math:`\chi` angles that are not defined for an amino acid are filled
+        with :math:`NaN` values.
+        The same is True for all residues that are not canonical amino acids.
+
+    Notes
+    -----
+    By convention, the :math:`\chi_2` angle of leucine is defined using ``CD1``
+    instead of ``CD2``.
+
+    Examples
+    --------
+
+    >>> res_ids, res_names = get_residues(atom_array)
+    >>> dihedrals = dihedral_side_chain(atom_array)
+    >>> for res_id, res_name, dihedrals in zip(res_ids, res_names, dihedrals):
+    ...     print(f"{res_name.capitalize()}{res_id:<2d}:", dihedrals)
+    Asn1 : [-1.180 -0.066    nan    nan]
+    Leu2 : [0.923 1.866   nan   nan]
+    Tyr3 : [-2.593 -1.487    nan    nan]
+    Ile4 : [-0.781 -0.972    nan    nan]
+    Gln5 : [-2.557  1.410 -1.776    nan]
+    Trp6 : [3.117 1.372   nan   nan]
+    Leu7 : [-1.33  3.08   nan   nan]
+    Lys8 : [ 1.320  1.734  3.076 -2.022]
+    Asp9 : [-1.623  0.909    nan    nan]
+    Gly10: [nan nan nan nan]
+    Gly11: [nan nan nan nan]
+    Pro12: [-0.331  0.539    nan    nan]
+    Ser13: [-1.067    nan    nan    nan]
+    Ser14: [-2.514    nan    nan    nan]
+    Gly15: [nan nan nan nan]
+    Arg16: [ 1.032 -3.063  1.541 -1.568]
+    Pro17: [ 0.522 -0.601    nan    nan]
+    Pro18: [ 0.475 -0.577    nan    nan]
+    Pro19: [ 0.561 -0.602    nan    nan]
+    Ser20: [-1.055    nan    nan    nan]
+    """
+    is_multi_model = isinstance(atoms, AtomArrayStack)
+
+    chi_atoms = _all_chi_atoms()
+    res_names = atoms.res_name[get_residue_starts(atoms)]
+    chi_atom_coord = coord_for_atom_name_per_residue(
+        atoms, chi_atoms, filter_canonical_amino_acids(atoms)
+    )
+    chi_atoms_to_coord_index = {atom_name: i for i, atom_name in enumerate(chi_atoms)}
+
+    if is_multi_model:
+        shape = (atoms.stack_depth(), len(res_names), 4)
+    else:
+        shape = (len(res_names), 4)
+    chi_angles = np.full(shape, np.nan, dtype=np.float32)
+    for res_name, chi_atom_names_for_all_angles in _CHI_ATOMS.items():
+        res_mask = res_names == res_name
+        for chi_i, chi_atom_names in enumerate(chi_atom_names_for_all_angles):
+            dihedrals = dihedral(
+                chi_atom_coord[
+                    chi_atoms_to_coord_index[chi_atom_names[0]], ..., res_mask, :
+                ],
+                chi_atom_coord[
+                    chi_atoms_to_coord_index[chi_atom_names[1]], ..., res_mask, :
+                ],
+                chi_atom_coord[
+                    chi_atoms_to_coord_index[chi_atom_names[2]], ..., res_mask, :
+                ],
+                chi_atom_coord[
+                    chi_atoms_to_coord_index[chi_atom_names[3]], ..., res_mask, :
+                ],
+            )
+            if is_multi_model:
+                # Swap dimensions due to NumPy's behavior when using advanced indexing
+                # (https://numpy.org/devdocs/user/basics.indexing.html#combining-advanced-and-basic-indexing)
+                dihedrals = dihedrals.T
+            chi_angles[..., res_mask, chi_i] = dihedrals
+    return chi_angles
+
+
 def centroid(atoms):
     """
     Measure the centroid of a structure.
@@ -653,3 +803,15 @@ def _displacement_triclinic_box(fractions, box, disp):
     disp[:] = shifted_diffs[
         np.arange(len(shifted_diffs)), np.argmin(sq_distance, axis=1)
     ]
+
+
+@functools.cache
+def _all_chi_atoms():
+    """
+    Get the names of the atoms participating in any chi angle.
+    """
+    atom_names = set()
+    for angles in _CHI_ATOMS.values():
+        for angle in angles:
+            atom_names.update(angle)
+    return sorted(atom_names)

{biotite-1.3.0 → biotite-1.5.0}/src/biotite/structure/info/atoms.py

@@ -6,6 +6,7 @@ __name__ = "biotite.structure.info"
 __author__ = "Patrick Kunzmann"
 __all__ = ["residue"]
 
+import functools
 from biotite.structure.info.ccd import get_ccd
 
 # fmt: off
@@ -75,6 +76,13 @@ def residue(res_name, allow_missing_coord=False):
      ['CB' 'HB3']
      ['OXT' 'HXT']]
     """
+    # Use a cache internally, but always return a copy,
+    # as the returned AtomArray is mutable
+    return _residue(res_name, allow_missing_coord).copy()
+
+
+@functools.lru_cache(maxsize=100)
+def _residue(res_name, allow_missing_coord=False):
     # Avoid circular import
     from biotite.structure.io.pdbx import get_component