plinder.eval.batch

Evaluate folders of predictions against PLINDER reference structures.

plinder.eval.batch.evaluate_predictions(predictions: str | Path | DataFrame, *, output_dir: str | Path, release: PlinderRelease | None = None, mode: Literal['ligands', 'interfaces', 'both'] = 'both', num_workers: int = 1, include_all_ligands: bool = False, posebusters: bool = True, ligand_smiles: Mapping[str, str] | None = None, ligand_ccd_codes: Mapping[str, str] | None = None, ligand_chains: Sequence[str] = (), ligand_options: Sequence[str] = (), interface_options: Sequence[str] = (), ost_executable: str | Path = 'ost') → dict[str, DataFrame]

Evaluate a CSV/TSV/Parquet input table or reference-ID prediction folders.

Tables use input_id, structure_path, reference_id and optional ligand_path columns. Repeat an input row for multiple ligand SDFs. Relative paths are resolved from the table directory; DataFrames use the working directory. Table input_id values identify predictions in results.

A reference ID is a PLINDER system/interface ID, or a four-character PDB ID to compare against all its systems/interfaces. Each mmCIF (also .mmcif or gzip-compressed) is a separate prediction. Interface comparisons also accept PDB files (.pdb or .pdb.gz), passed directly to OST. For ligand evaluation, pair a receptor PDB/mmCIF with model.sdf or model.ligands/*.sdf; each SDF contains one ligand in the receptor’s coordinate frame. An empty ligand folder represents zero predicted poses. Otherwise ligands are extracted from a complete mmCIF. mode selects ligand or interface evaluation, or both. References come from the selected release.

num_workers limits concurrent prediction processes. PoseBusters runs without its own process pool. When calling from a Python script, put the call inside if __name__ == '__main__':.

Ligand rows correspond to proper reference ligands by default; set include_all_ligands to include reference ions/artifacts too. Predictions are not filtered by artifact status or receptor proximity. Missing poses remain as unassigned reference rows. Preparation/tool errors retain error rows and are listed separately, not converted to scientific scores.

CCD/SMILES mappings and ligand_chains are passed to prepare_prediction for every model. ligand_options and interface_options pass additional native OST flags to the respective actions.

Returns tables keyed by ligands, interfaces, posebusters, and failures; also writes the first three as Parquet and failures.tsv. Ligand metrics keep separate rmsd_model_ligand/lddt_pli_model_ligand assignments. Join either to PoseBusters on prediction and model_ligand. PoseBusters covers all candidate predicted ligands, including unmatched ones. Native JSON, CSV, logs and prepared coordinates remain under details/. Every call reruns comparisons and replaces the summary tables; old details are never read as results.