plinder.data.annotations.save_utils

class plinder.data.annotations.save_utils.AnnotationRow(*args, **kwargs)

Bases: Protocol

Minimal interface shared by dicts and pandas Series.

get(key: str, default: Any = None) → Any

class plinder.data.annotations.save_utils.SystemReconstructionOptions(system_waters: Literal['none', 'interacting', 'all'] = 'interacting', receptor_waters: Literal['none', 'interacting', 'all'] = 'interacting', system_include_ligands: bool = True, system_include_other_protein_chains: bool = False, system_include_other_ligand_chains: bool = False, receptor_include_other_protein_chains: bool = False, validate_biounit_chain_ids: bool = True)

Bases: object

Configure which atoms are present in reconstructed mmCIF views.

system_waters: Literal['none', 'interacting', 'all'] = 'interacting'

receptor_waters: Literal['none', 'interacting', 'all'] = 'interacting'

system_include_ligands: bool = True

system_include_other_protein_chains: bool = False

system_include_other_ligand_chains: bool = False

receptor_include_other_protein_chains: bool = False

validate_biounit_chain_ids: bool = True

class plinder.data.annotations.save_utils.SystemReconstructionOutputs(system_cif: Path | None = None, receptor_cif: Path | None = None, sequences_fasta: Path | None = None)

Bases: object

Explicit output paths; None means that file is not written.

system_cif: Path | None = None

receptor_cif: Path | None = None

sequences_fasta: Path | None = None

class plinder.data.annotations.save_utils.ReconstructedSystem(biounit: AtomArray, system: AtomArray, receptor: AtomArray)

Bases: object

In-memory views rebuilt from a source PDB mmCIF.

biounit: AtomArray

system: AtomArray

receptor: AtomArray

plinder.data.annotations.save_utils.save_ligands(atoms: AtomArray, ligand_chain_ids: list[str] | dict[str, list[str]], output_folder: str | Path) → None

Save one canonical ASU SDF per retained ligand.

RDKit supplies chemically normalized bond/aromaticity information when it can sanitize the ligand. If it cannot, Biotite serializes the source bond graph directly so the canonical coordinate archive remains complete.

Parameters:

atomsAtomArray

Full system atoms with bonds.

ligand_chain_idslist[str] or dict[str, list[str]]

Either a list of chain IDs (one SDF per chain), or a mapping of output name -> member chain IDs. The mapping form writes a single SDF spanning all member chains, so covalently-linked ligand chains (a macrocycle deposited as several chains) are saved as one molecule.

output_folderstr or Path

Directory to write SDF files.

plinder.data.annotations.save_utils.save_cif_file(atoms: AtomArray, name: str, output_cif_file: str | Path, *, source_block: CIFBlock | None = None, source_asym_ids: dict[str, str] | None = None, protein_sequences: dict[str, str] | None = None) → None

Save a self-contained structure as PDBx/mmCIF.

Parameters:

atomsAtomArray

Atoms to save.

namestr

Data block name.

output_cif_filestr or Path

Output path.

source_blockCIFBlock, optional

Source metadata. Relevant entity, polymer, and chemical-component rows are retained for the atoms in the output view.

source_asym_idsdict, optional

Map output chain IDs to label asym IDs in source_block. Assembly instance IDs default to their suffix after the first ..

protein_sequencesdict, optional

Canonical protein sequences keyed by output chain ID. These are used when the source has no polymer metadata.

plinder.data.annotations.save_utils.save_reconstructed_chain(source_mmcif: Path | str, *, assembly_id: str, chain_instance: str, source_asym_id: str, output_cif: Path | str, structure_id: str, superpose_to: AtomArray | None = None, overwrite: bool = False) → Path

Write one biological-assembly chain as a self-contained mmCIF.

If superpose_to is provided, the reconstructed chain is fitted to that protein chain using sequence-matched C-alpha atoms before it is written.

plinder.data.annotations.save_utils.reconstruct_interface(source_mmcif: Path | str, annotation: AnnotationRow) → AtomArray

Rebuild one annotated protein-interface chain pair from a source mmCIF.

plinder.data.annotations.save_utils.save_reconstructed_interface(source_mmcif: Path | str, annotation: AnnotationRow, *, output_cif: Path | str, overwrite: bool = False, reconstructed: AtomArray | None = None) → Path

Write one annotated biological-assembly interface as a valid mmCIF.

plinder.data.annotations.save_utils.reconstruct_system(source_mmcif: Path | str, annotation: AnnotationRow, *, biounit_chains: DataFrame, options: SystemReconstructionOptions = SystemReconstructionOptions(system_waters='interacting', receptor_waters='interacting', system_include_ligands=True, system_include_other_protein_chains=False, system_include_other_ligand_chains=False, receptor_include_other_protein_chains=False, validate_biounit_chain_ids=True)) → ReconstructedSystem

Rebuild system and receptor views from a PDB mmCIF and parquet row.

The annotation row must be one ligand-level row from the system to reconstruct. System-level columns are repeated for every ligand row, so no grouping or coordinate data from the parquet is required.

Parameters:

source_mmcifPath or str

Original PDB mmCIF used for annotation (plain or gzip-compressed).

annotationmapping-like

A dictionary or pandas Series containing the system selection columns.

biounit_chainspandas.DataFrame

Biological-assembly membership rows for this entry.

optionsSystemReconstructionOptions

Atom-content choices for the two returned views.

plinder.data.annotations.save_utils.save_reconstructed_system(source_mmcif: Path | str, annotation: AnnotationRow, *, outputs: SystemReconstructionOutputs, biounit_chains: DataFrame, options: SystemReconstructionOptions = SystemReconstructionOptions(system_waters='interacting', receptor_waters='interacting', system_include_ligands=True, system_include_other_protein_chains=False, system_include_other_ligand_chains=False, receptor_include_other_protein_chains=False, validate_biounit_chain_ids=True), overwrite: bool = False, reconstructed: ReconstructedSystem | None = None) → dict[str, Path]

Reconstruct a system and write exactly the requested mmCIF/FASTA files.

No PDB files or assembly-rotated ligand SDFs are produced. Output parents are created automatically. Existing files are rejected unless overwrite=True. A previously reconstructed in-memory view may be supplied to avoid parsing and expanding the source assembly again.