CCD Utilities#

atomworks.io.utils.ccd.aa_chem_comps() → frozenset[str][source]#

Set of amino acid chemical components.

Returns:

Set of amino acid chemical components (e.g., {‘ALA’, ‘ARG’, …}).

atomworks.io.utils.ccd.add_annotations_from_ccd(atom_array: AtomArray, annotations: list[str] | None = None, overwrite: dict[str, bool] | bool = False, ccd_mirror_path: PathLike = None, hydrogen_policy: Literal['keep', 'remove'] = 'keep', on_mismatch: Literal['ignore', 'error_heavy', 'error'] = 'ignore', match_alt_atom_ids: bool = False) → AtomArray[source]#

Add CCD structural annotations to atoms in an existing AtomArray.

Matches atoms to CCD templates by residue and copies specified annotations.

Parameters:

  • atom_array – Structure to annotate.

  • annotations – List of annotation names to add. If None, adds all core structural annotations: ["charge", "stereo", "is_aromatic", "is_leaving_atom", "is_backbone_atom", "is_n_terminal_atom", "is_c_terminal_atom", "nhyd"].

  • overwrite – Control overwriting of existing annotations. If bool, applies to all. If dict, maps annotation name to overwrite policy. Example: {"charge": False, "stereo": True} keeps existing charges but overwrites stereochemistry. Defaults to False.

  • ccd_mirror_path – Path to local CCD mirror.

  • hydrogen_policy – Whether to use the "keep" or "remove" CCD template. When "remove", the template has nhyd set on heavy atoms so that implicit H counts are copied to atom_array before bond inference.

  • on_mismatch –

    How to handle residue atoms whose names are not in the CCD template. One of:

    • "ignore" (default): silently skip unmatched atoms (debug log only).

    • "error_heavy": raise ValueError if any unmatched atom is a heavy atom

    • "error": raise ValueError on any unmatched atom.

  • match_alt_atom_ids – If True, use the template’s alt_atom_id column for the entire residue when it matches more heavy atoms than atom_name. Ties use standard names. Defaults to False.

Returns:

AtomArray with CCD annotations added (modified in-place).

Raises:

ValueError – If on_mismatch is "error" or "error_heavy" and unmatched atoms are found.

atomworks.io.utils.ccd.atom_array_from_bundled_ccd_code(ccd_code: str, ccd_mirror_path: PathLike = None, **parse_ccd_cif_kwargs) → AtomArray[source]#

Retrieve a component from the bundled CCD, bypassing the custom registry.

Parameters:

  • ccd_code – The chemical component code.

  • ccd_mirror_path – Path to local CCD mirror.

  • **parse_ccd_cif_kwargs – Additional args passed to parse_ccd_cif().

atomworks.io.utils.ccd.atom_array_from_ccd_code(ccd_code: str, ccd_mirror_path: PathLike = None, **parse_ccd_cif_kwargs) → AtomArray[source]#

Retrieves a component from the Chemical Component Dictionary.

Checks custom registry first (overriding standard CCD), then uses the local mirror if configured (never falling back to biotite), or biotite if no mirror and allowed.

Parameters:

  • ccd_code – The chemical component code

  • ccd_mirror_path – Path to local CCD mirror

  • **parse_ccd_cif_kwargs – Additional args passed to parse_ccd_cif()

Returns:

AtomArray of the requested component

Note

Registry entries override standard CCD definitions. Use register_custom_ccd_entry() to provide custom templates that will be used instead of standard CCD data.

atomworks.io.utils.ccd.build_ccd_entries_from_cif_block(cif_block: CIFBlock, on_mismatch: Literal['ignore', 'error_heavy', 'error'] = 'error_heavy') → dict[str, AtomArray][source]#

Build CIF component templates, supplementing only name-compatible CCD entries.

Authored fields win. CCD fallback requires heavy-atom names from one CCD naming convention; otherwise missing types are inferred from names. Multi-atom entries require bonds. on_mismatch rejects unmatched heavy atoms by default ("error_heavy"), or any unmatched atom with "error". "ignore" keeps incompatible components without supplementation.

atomworks.io.utils.ccd.check_ccd_codes_are_available(ccd_codes: Iterable[str], ccd_mirror_path: PathLike = None, mode: Literal['warn', 'raise'] = 'warn') → bool[source]#

Checks if the provided CCD codes are available in the current environment

atomworks.io.utils.ccd.chem_comp_to_one_letter() → dict[str, str][source]#

Dictionary mapping the chemical components to their 1-letter code.

Note

Chemical components historically used to be 3-letter codes, but nowadays longer codes exist.

Returns:

Dictionary mapping chemical component names to their 1-letter codes.

References

RCSB Chemical Component Dictionary Biotite CCD Module

atomworks.io.utils.ccd.clear_custom_ccd_registry() → int[source]#

Clear all custom CCD entries. Returns number of entries cleared.

atomworks.io.utils.ccd.custom_ccd_residues(entries: dict[str, AtomArray]) → Generator[None, None, None][source]#

Temporarily register custom CCD entries. Restores registry state on exit.

Parameters:

entries – Dict mapping CCD codes to AtomArrays.

Example

>>> with custom_ccd_residues({"ALA": custom_ala, "GLY": custom_gly}):
...     ala = atom_array_from_ccd_code("ALA")
atomworks.io.utils.ccd.dna_chem_comps() → frozenset[str][source]#

Set of DNA chemical components.

Returns:

Set of DNA chemical components (e.g., {‘DA’, ‘DC’, …}).

atomworks.io.utils.ccd.get_atom_names_for_residue(res_name: str, ccd_mirror_path: str) → tuple[frozenset[str], frozenset[str], dict[str, str]][source]#

Get atom name sets and alt→standard mapping from a CCD template.

Parameters:

  • res_name – Residue name (3-letter code).

  • ccd_mirror_path – Path to CCD mirror (as string), or empty string to use Biotite’s built-in CCD.

Returns:

Tuple of (std_names_set, alt_names_set, alt_to_std_mapping). Returns (frozenset(), frozenset(), {}) if template unavailable.

atomworks.io.utils.ccd.get_available_ccd_codes(ccd_mirror_path: PathLike | None = None) → frozenset[str][source]#

Returns all available CCD codes including registry entries.

atomworks.io.utils.ccd.get_available_ccd_codes_in_biotite() → frozenset[str][source]#

Set of all CCD codes available in Biotite’s built-in Chemical Component Dictionary.

atomworks.io.utils.ccd.get_available_ccd_codes_in_mirror(ccd_mirror_path: PathLike = None) → frozenset[str][source]#

Set of all CCD codes available in the local mirror.

Only counts codes when they adhere to the CCD mirror layout (e.g. …/H/HEM/HEM.cif)

Parameters:

ccd_mirror_path – Path to the CCD mirror directory.

Returns:

Set of all available CCD codes in the mirror.

References

RCSB Chemical Component Dictionary CCD Mirror Layout

atomworks.io.utils.ccd.get_ccd_component_from_biotite(ccd_code: str, **parse_ccd_cif_kwargs) → AtomArray[source]#

Retrieve an isolated copy of a cached component from Biotite’s built-in CCD.

Parameters:

ccd_code (-) – The three-letter code of the chemical component to retrieve.

Returns:

The atomic structure of the requested component.

Return type:

  • AtomArray

atomworks.io.utils.ccd.get_ccd_component_from_mirror(ccd_code: str, ccd_mirror_path: PathLike = None, **parse_ccd_cif_kwargs) → AtomArray[source]#

Retrieves and parses a component from a local mirror of the Chemical Component Dictionary.

Parameters:

  • ccd_code – The three-letter code of the chemical component.

  • ccd_mirror_path – Path to the root of the CCD mirror directory.

  • **parse_ccd_cif_kwargs –

    Additional keyword arguments passed to parse_ccd_cif.

    • coords: Type of coordinates to use (“model”, “ideal_pdbx”, “ideal_rdkit”, or None).

      Defaults to “ideal_pdbx”.

    • add_properties: Whether to include RDKit-computed properties. Defaults to True.

    • add_mapping: Whether to include external resource mappings, such as e.g. the ChEMBL ID.

      Defaults to False.

Returns:

The parsed atomic structure of the requested component.

Return type:

AtomArray

Example

>>> atom_array = get_ccd_component_from_mirror("ALA", coords="ideal_pdbx")
atomworks.io.utils.ccd.get_ccd_descriptors(ccd_code: str, ccd_mirror_path: PathLike = None) → dict[str, str][source]#

Extract SMILES and InChI descriptors from a CCD entry.

Parses the _pdbx_chem_comp_descriptor category to retrieve molecular descriptors. Available descriptor types depend on the CCD entry.

Parameters:

  • ccd_code – The CCD code for the component.

  • ccd_mirror_path – Path to the local CCD mirror.

Returns:

Dictionary with descriptor types as keys and descriptor values as values. Common keys include: “SMILES”, “SMILES_CANONICAL”, “InChI”, “InChIKey”. Returns empty dict if the CCD code is not found or has no descriptors.

Example

>>> get_ccd_descriptors("ATP")
{'SMILES_CANONICAL': 'Nc1ncnc2c1ncn2...', 'InChI': 'InChI=1S/...', ...}
atomworks.io.utils.ccd.get_chain_type_from_ccd_code(ccd_code: str, ccd_mirror_path: PathLike = None) → ChainType[source]#

Get the ChainType enum corresponding to a CCD code.

atomworks.io.utils.ccd.get_chain_type_from_chem_comp_type(chem_comp_type: str) → ChainType[source]#

Get the ChainType enum corresponding to a chemical component type.

atomworks.io.utils.ccd.get_chem_comp_type(ccd_code: str, atom_names: set[str] | None = None, mode: Literal['warn', 'raise'] = 'warn', ccd_mirror_path: PathLike = None) → str[source]#

Get the chemical component type for a CCD code.

Routes through atom_array_from_ccd_code() so the custom CCD registry is the single interception point. Falls back to inference from atom_names when the code is unknown.

Parameters:

  • ccd_code – The CCD code for the component. E.g. "ALA" for alanine.

  • atom_names – Atom names used to infer the type when the code is not in the CCD.

  • mode – How to handle unknown chemical component types.

  • ccd_mirror_path – Path to the local CCD mirror directory.

Example

>>> get_chem_comp_type("ALA")
'L-PEPTIDE LINKING'
atomworks.io.utils.ccd.get_custom_ccd_entries() → frozenset[str][source]#

Get set of currently registered custom CCD codes.

atomworks.io.utils.ccd.get_parent_comp_id(ccd_code: str, ccd_mirror_path: PathLike = None) → str | None[source]#

Return the canonical parent residue for a modified CCD code, or None.

Uses the local CCD mirror when configured, falling back to biotite’s built-in CCD.

atomworks.io.utils.ccd.get_parent_template_atom_names(parent_code: str, ccd_mirror_path: str = '', hydrogen_policy: Literal['keep', 'remove'] = 'remove') → set[str][source]#

Return the set of atom names from a parent CCD template.

atomworks.io.utils.ccd.get_polymerization_atoms(res_name: str, chain_type: ChainType | None = None) → tuple[str | None, str | None][source]#

Return candidate (leaving_atom, entering_atom) sites for a polymer bond.

Looks up the canonical atoms for the chemical component type via get_chem_comp_type() against CHEM_TYPE_POLYMERIZATION_ATOMS (falling back to ChainTypeInfo.ATOMS_AT_POLYMER_BOND), and returns them when the component actually carries those atom names. A component that does not carry them falls back to CCD_POLYMERIZATION_ATOM_OVERRIDES, and then to _derive_polymerization_atoms_from_template(). Each side is resolved independently and may be None. For caps, chain_type supplies candidate sites (NH2 gives (None, "N")), but does not establish that a bond exists.

atomworks.io.utils.ccd.get_standard_ccd_codes(ccd_mirror_path: PathLike | None = None) → frozenset[str][source]#

Returns standard CCD codes (from mirror + Biotite). Cached.

atomworks.io.utils.ccd.get_std_to_alt_atom_name_map(ccd_code: str, ccd_mirror_path: PathLike = None) → dict[str, str][source]#

Get a map from standard atom names to alternative atom names.

atomworks.io.utils.ccd.get_unknown_ccd_code_for_chem_comp_type(chem_comp_type: str) → str[source]#

Get the CCD code for an unknown chemical component type.

atomworks.io.utils.ccd.is_parent_strict_atom_subset(child_code: str, parent_code: str, ccd_mirror_path: str = '', hydrogen_policy: Literal['keep', 'remove'] = 'remove') → bool[source]#

Check if the parent template’s heavy-atom names are a strict subset of the child’s.

Parameters:

  • child_code – Modified residue CCD code (e.g. "ASB").

  • parent_code – Parent residue CCD code (e.g. "ASP").

  • ccd_mirror_path – Path to CCD mirror, or empty string for Biotite’s built-in.

  • hydrogen_policy – Hydrogen handling for templates.

atomworks.io.utils.ccd.na_chem_comps() → frozenset[str][source]#

Set of nucleic acid chemical components.

Returns:

Set of nucleic acid chemical components (e.g., {‘DA’, ‘DC’, …}).

atomworks.io.utils.ccd.parse_ccd_cif(cif: CIFFile, coords: Literal['model', 'ideal_pdbx', 'ideal_rdkit'] | None | tuple[str, ...] = ('ideal_pdbx', 'model', 'ideal_rdkit'), add_properties: bool = False, add_mapping: bool = False) → AtomArray[source]#

Parses a Chemical Component Dictionary CIF file into a Biotite AtomArray structure.

Parameters:

  • cif – The CIF file containing the component data.

  • coords – Type of coordinates to use. Defaults to (“ideal_pdbx”, “model”, “ideal_rdkit”). Can be a single coordinate type or a tuple of fallback preferences (e.g., (“ideal_pdbx”, “model”, “ideal_rdkit”)). - “model”: Use the coordinates that are found in a random (but fixed) pdb file. - “ideal_pdbx”: Use the idealized coordinates computed by the RCSB PDB (sometimes not available). - “ideal_rdkit”: Use the idealized coordinates computed by RDKit (sometimes unrealistic).

  • add_properties – Whether to include RDKit-computed properties. Defaults to False. Properties are available under the properties attribute of the returned AtomArray.

  • add_mapping – Whether to include external resource mappings, such as e.g. the ChEMBL ID. Defaults to False. Mappings are available under the mapping attribute of the returned AtomArray.

Returns:

The parsed atomic structure with requested annotations and properties.

Return type:

AtomArray

Example

>>> cif = pdbx.CIFFile.read("path/to/ALA.cif")
>>> atom_array = parse_ccd_cif(cif, coords="ideal_pdbx")
>>> # With fallback preferences:
>>> atom_array = parse_ccd_cif(cif, coords=["ideal_pdbx", "model", "ideal_rdkit"])
atomworks.io.utils.ccd.register_custom_ccd_entries(entries: dict[str, AtomArray]) → None[source]#

Register multiple custom CCD entries at once.

atomworks.io.utils.ccd.register_custom_ccd_entry(code: str, atom_array: AtomArray) → None[source]#

Register a custom CCD entry to override/supplement standard CCD lookups.

atomworks.io.utils.ccd.register_custom_residues_from_atom_array(atom_array: AtomArray, ccd_mirror_path: PathLike = None) → list[str][source]#

Extract and register non-standard residues from AtomArray.

Compares residue names against standard CCD codes only (not registry). This allows re-registration/overwriting of custom residues.

Parameters:

  • atom_array – Structure containing residues to extract.

  • ccd_mirror_path – Path to CCD mirror for standard codes check.

Returns:

List of CCD codes that were successfully registered.

atomworks.io.utils.ccd.rna_chem_comps() → frozenset[str][source]#

Set of RNA chemical components.

Returns:

Set of RNA chemical components (e.g., {‘A’, ‘C’, …}).

atomworks.io.utils.ccd.snapshot_custom_ccd_registry() → dict[str, AtomArray][source]#

Return a deep copy of the current custom CCD registry.

atomworks.io.utils.ccd.unregister_custom_ccd_entry(code: str) → bool[source]#

Unregister a custom CCD entry. Returns True if entry existed.