Query the release tables

Use plinder.core.query_table() to select and filter release records. The dataset reference defines every table, key, relationship, and column.

import pandas as pd

from plinder.core import PlinderRelease, RELEASE_TABLES, query_table

/home/runner/micromamba/envs/plinder/lib/python3.12/site-packages/vcs_versioning/_backends/_git.py:709: UserWarning: "/home/runner/work/plinder/plinder" is shallow and may cause errors
  pre_parse(wd)

Inspect the available tables

Each registered release table declares what one row represents and its primary key.

release = PlinderRelease()
pd.DataFrame(
    [
        {"table": name, **release.table(name)}
        for name in RELEASE_TABLES
    ]
).set_index("table")

	artifact	row_description	primary_key
table
annotation	annotation_table	ligand	(ligand_id,)
system_validation	system_validation	ligand-binding system validation summary	(system_id,)
entry_chains	entry_chains	polymer chain in a PDB entry	(entry_pdb_id, chain_asym_id)
entry_biounit_chains	entry_biounit_chains	chain instance in a biological assembly	(entry_pdb_id, biounit_id, chain_instance)
entry_metadata	entry_metadata	PDB entry	(entry_pdb_id,)
entry_sources	entry_sources	PDB entry	(entry_pdb_id,)
linked_apo_structures	linked_apo_structures	ranked apo chain linked to a holo ligand	(reference_system_id, rank)
interface_apo_structures	interface_apo_structures	ranked apo chain linked to one protein-interfa...	(reference_system_id, reference_side, rank)
interface_annotations	interface_annotations	protein-chain interface in a biological assembly	(system_id,)
alignment_chain_lookup	alignment_chain_lookup	protein chain in the release search databases	(entry_pdb_id, chain_asym_id)
ligand_pocket_membership	ligand_pocket_membership	ligand directed-set-cover assignment	(ligand_id,)
ligand_pocket_residues	ligand_pocket_residues	receptor residue neighboring a proper ligand	(ligand_id, chain_instance, residue_label_seq_id)
ligand_pocket_representatives	ligand_pocket_representatives	ligand-pocket representative	(representative_ligand_id,)
ligand_clusters	ligand_clusters	ligand cluster assignments	(ligand_id,)
ligand_affinity	ligand_affinity	ligand with sequence-checked BindingDB affinity	(ligand_id,)
bindingdb_measurements	bindingdb_measurements	BindingDB Ki or Kd measurement with a PDB liga...	(source_row, pdb_id, ligand_het_id, endpoint)
ligand_mmp_pairs	ligand_mmp_pairs	matched molecular pair and shared core	(ligand_smiles_id_1, ligand_smiles_id_2, trans...
interface_half_representatives	interface_half_representatives	representative half-interface	(half_interface_id,)
interface_membership	interface_membership	protein-interface representative assignment	(system_id,)
interface_representatives	interface_representatives	protein-interface representative	(representative_system_id,)
interface_clusters	interface_clusters	protein-interface cluster assignments	(system_id,)
protein_sequence_clusters	protein_sequence_clusters	protein-chain sequence cluster assignment from...	(entry_pdb_id, chain_asym_id)
protein_structure_clusters	protein_structure_clusters	protein-chain structure cluster assignment fro...	(entry_pdb_id, chain_asym_id)

Query ligand annotations

Select only the columns needed for the analysis. Columns such as resolution and taxonomy are found in related tables automatically. Conditions in the outer filter list are combined with AND.

ligands = query_table(
    "annotation",
    columns=[
        "system_id",
        "entry_pdb_id",
        "ligand_id",
        "ligand_unique_ccd_code",
        "ligand_molecular_weight",
        "system_num_protein_chains",
        "system_pass_validation_criteria",
        "entry_resolution",
        "entry_source_taxonomy_ids",
    ],
    filters=[
        ("entry_pdb_id", "in", ["4agi", "7eek"]),
        ("ligand_is_proper", "==", True),
        ("ligand_molecular_weight", "<=", 500),
        ("system_num_protein_chains", "==", 1),
    ],
)
ligands.head()

	system_id	entry_pdb_id	ligand_id	ligand_unique_ccd_code	ligand_molecular_weight	system_num_protein_chains	system_pass_validation_criteria	entry_resolution	entry_source_taxonomy_ids
0	4agi__2__1.B__1.Q	4agi	4agi__2__1.Q	SFU	242.00573	1	True	1.6	[5085]
1	4agi__2__1.B__1.P	4agi	4agi__2__1.P	SFU	242.00573	1	True	1.6	[5085]
2	4agi__2__1.B__1.O	4agi	4agi__2__1.O	SFU	242.00573	1	True	1.6	[5085]
3	4agi__2__1.B__1.N	4agi	4agi__2__1.N	SFU	242.00573	1	True	1.6	[5085]
4	4agi__2__1.B__1.M	4agi	4agi__2__1.M	SFU	242.00573	1	True	1.6	[5085]

A system containing several ligands spans several rows. Count unique system_id values when the intended unit is a system.

print(f"Ligand rows: {len(ligands):,}")
print(f"Systems: {ligands['system_id'].nunique():,}")

Ligand rows: 28
Systems: 26

Query protein interfaces

Start from interface_annotations when selecting protein-chain pairs. Resolution and taxonomy are added from the entry table automatically.

interfaces = query_table(
    "interface_annotations",
    columns=[
        "system_id",
        "interface_chain_1",
        "interface_chain_2",
        "interface_num_contact_residue_pairs",
        "prodigy_probability_bio",
        "entry_resolution",
        "entry_source_taxonomy_ids",
    ],
    filters=[
        ("entry_pdb_id", "==", "7cm8"),
        ("interface_num_contact_residue_pairs", ">=", 10),
    ],
)
interfaces

	system_id	interface_chain_1	interface_chain_2	interface_num_contact_residue_pairs	prodigy_probability_bio	entry_resolution	entry_source_taxonomy_ids
0	7cm8__1__1.A--2.A	1.A	2.A	824	1.0	1.9	[71421]

Query chains directly

Use entry_chains when the analysis unit is a polymer chain. This avoids deduplicating chain information from ligand rows.

chains = query_table(
    "entry_chains",
    columns=[
        "entry_pdb_id",
        "chain_asym_id",
        "chain_auth_id",
        "chain_sequence",
        "chain_is_holo",
    ],
    filters=[
        ("entry_pdb_id", "in", ["4agi", "7eek"]),
        ("chain_receptor_type", "==", "protein"),
    ],
)
chains

	entry_pdb_id	chain_asym_id	chain_auth_id	chain_sequence	chain_is_holo
0	4agi	A	A	MSTPGAQQVLFRTGIAAVNSTNHLRVYFQDVYGSIRESLYEGSWAN...	True
1	4agi	B	B	MSTPGAQQVLFRTGIAAVNSTNHLRVYFQDVYGSIRESLYEGSWAN...	True
2	4agi	C	C	MSTPGAQQVLFRTGIAAVNSTNHLRVYFQDVYGSIRESLYEGSWAN...	True
3	4agi	D	D	MSTPGAQQVLFRTGIAAVNSTNHLRVYFQDVYGSIRESLYEGSWAN...	True
4	7eek	A	A	AHKSEVAHRFKDLGEENFKALVLIAFAQYLQQCPFEDHVKLVNEVT...	True
5	7eek	B	B	AHKSEVAHRFKDLGEENFKALVLIAFAQYLQQCPFEDHVKLVNEVT...	True