{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Python API tutorial\n", "\n", "## Setup\n", "\n", "### Installation\n", "\n", "`plinder` is available on *PyPI*.\n", "\n", "```\n", "pip install plinder\n", "```\n", "\n", "### Environment variable configuration\n", "\n", "We need to set environment variables to point to the release and iteration of choice.\n", "For the sake of demonstration, this will be set to point to a smaller tutorial example\n", "dataset, which are `PLINDER_RELEASE=2024-06` and `PLINDER_ITERATION=tutorial`.\n", "\n", ":::{note}\n", "The version used for the preprint is `PLINDER_RELEASE=2024-04` and\n", "`PLINDER_ITERATION=v1`, while the current version with updated annotations to be used\n", "for the MLSB challenge is`PLINDER_RELEASE=2024-06` and `PLINDER_ITERATION=v2`.\n", ":::" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "%env PLINDER_LOG_LEVEL=0\n", "%env PLINDER_ITERATION=tutorial" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "As alternative these variables could also be set from terminal via `export` (*UNIX*) or\n", "`set` (*Windows*)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Overview\n", "\n", "The user-facing subpackage of `plinder` is {mod}`plinder.core`.\n", "This provides access to the underlying utility functions for accessing the dataset,\n", "split and annotations.\n", "It provides access to five top-level functions:\n", "\n", ":::{currentmodule} plinder.core\n", ":::\n", "\n", "- {func}`get_config()`: access *PLINDER* global configuration\n", "- {func}`query_index()`: access and query annotation table\n", "\n", ":::{currentmodule} plinder\n", ":::\n", "\n", "In addition, it provides access to the data class {class}`PlinderSystem` for\n", "reconstituting a *PLINDER* system from its `system_id`.\n", "\n", "To supplement these data, {mod}`plinder.core.scores` provides functionality for\n", "querying metrics, such as protein/ligand similarity and cluster identity." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Getting the configuration\n", "\n", "At first we get the configuration to check that all parameters are correctly set. \n", "In the snippet below, we will check, if the local and remote *PLINDER* paths point to\n", "the expected location." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import plinder.core.utils.config\n", "\n", "cfg = plinder.core.get_config()\n", "print(f\"local cache directory: {cfg.data.plinder_dir}\")\n", "print(f\"remote data directory: {cfg.data.plinder_remote}\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Query annotations" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Query specific columns \n", "\n", ":::{currentmodule} plinder.core.scores\n", ":::\n", "\n", "To query the annotations table for specific columns or filter by specific criteria, use\n", "{func}`query_index()`.\n", "The function could be called without any argument to yield a [`pandas`](https://pandas.pydata.org) dataframe of `system_id`,\n", "`entry_pdb_id`, and `split`, and by default only loads systems present in the `train` and `val` splits." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "from plinder.core.scores import query_index\n", "\n", "# Get system_id, entry_pdb_id, and split columns of train and val splits\n", "query_index()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The function can be called by passing `columns` argument, which is a list of\n", "[column names](#annotation-table-target). " ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# Get specific columns from the annotation table\n", "cols_of_interest = [\"system_id\", \"entry_pdb_id\", \"entry_release_date\", \"entry_oligomeric_state\", \"entry_validation_clashscore\", \"entry_resolution\"]\n", "query_index(columns=cols_of_interest)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Query annotations with specific filters\n", "\n", "We could also pass additional `filters`, where each filter is a logical comparison\n", "of a column name with some given value.\n", "Only those rows, that fulfill all conditions, are returned.\n", "See the description of\n", "[`pandas.read_parquet()`](https://pandas.pydata.org/docs/reference/api/pandas.read_parquet.html)\n", "for more information on the filter syntax." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# Query for single-ligand systems\n", "filters = [(\"system_num_ligand_chains\", \"==\", 1)]\n", "query_index(columns=cols_of_interest, filters=filters)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Query systems in test, removed, or unassigned splits\n", "\n", "The `splits` parameter is set to [\"train\", \"val\"] by default but can take one or more of [\"train\", \"val\", \"test\", \"removed\", \"all\"]. By querying with [\"*\"], we get all 1.3 million rows, including those from the test and removed splits as well ion systems and systems with >5 protein and/or ligand chains (labelled \"unassigned\"):" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "df = query_index(columns=cols_of_interest, splits=[\"*\"])\n", "df.drop_duplicates(\"system_id\")[\"split\"].value_counts()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ ":::{note}\n", ":::{currentmodule} plinder.core\n", ":::\n", "To load all the columns, users can use the function {func}`get_plindex()` which returns all the columns in the dataframe. However, since this table has over 1.3 million rows and over 700 columns, it has a significant memory footprint (~24G RAM) and users are advised to query only columns they need.\n", ":::" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Query protein similarity\n", "The are three kinds of similarity datasets we provide:\n", "- Similarity between ligand bound structures (`holo`)\n", "- Similarity between ligand bound and unbound protein structures (`apo`)\n", "- Similarity between ligand bound and Alphafold predicted structures (`pred`)\n", "Any of these could be specified with {func}`query_protein_similarity()`" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ ":::{note} With the full dataset, some similarity queries might require a large amount of memory. For example, `query_protein_similarity(search_db=\"holo\", filters=[(\"similarity\", \">\", \"50\")]) will use up >500G RAM.:::" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Here, we will query protein similarity dataset to assess the protein-ligand interaction similarity between example training and test set" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "from plinder.core.scores import query_protein_similarity\n", "\n", "# Example train systems\n", "train = [\"7jxf__1__1.A_1.B__1.G\", \"1jtu__1__1.A_1.B__1.C_1.D\",\n", " \"8f9d__2__1.C_1.D__1.G\", \"6a9a__1__1.A_2.A__2.C_2.D\",\n", " \"1b5e__2__1.A_1.B__1.D\"]\n", "# Example test systems\n", "test = [\"1b5d__1__1.A_1.B__1.D\", \"1s2g__1__1.A_2.C__1.D\",\n", " \"4agi__1__1.C__1.W\", \"4n7m__1__1.A_1.B__1.C\",\n", " \"7eek__1__1.A__1.I\"]\n", "\n", "metric = \"pli_unique_qcov\"\n", "threshold = 50\n", "query_protein_similarity(\n", " search_db=\"holo\",\n", " columns=[\"query_system\", \"target_system\", \"similarity\"],\n", " filters=[\n", " (\"query_system\", \"in\", test),\n", " (\"target_system\", \"in\", train),\n", " (\"metric\", \"==\", metric),\n", " (\"similarity\", \">=\", str(threshold)),\n", " ],\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Working with a PLINDER system\n", "\n", "A {class}`PlinderSystem` is the representation of a single System.\n", "This object provides access to all PDB entry and system level annotations, as well as\n", "the structures of the system components." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Load systems from IDs\n", "\n", "To reconstitute PLINDER systems directly from a set of IDs use class {class}`PlinderSystem`.\n" ] }, { "cell_type": "code", "execution_count": 8, "metadata": {}, "outputs": [], "source": [ "from plinder.core import PlinderSystem\n", "\n", "plinder_system = PlinderSystem(system_id=\"4agi__1__1.C__1.W\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Users can choose the granularity level of input:\n", "In the cases above the systems were specified by their system ID, but as alternative\n", "passing PDB IDs (or their two middle characters) is also possible, which gives you all\n", "systems corresponding to the given PDB IDs." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Accessing annotations\n", "\n", "The `PlinderSystem.entry` property provides PDB entry-level annotations for that system.\n", "Here, we will list the accessible categories of entry annotations and access the\n", "oligomeric state of a given system." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "entry_annotations = plinder_system.entry\n", "print(list(entry_annotations.keys()))\n", "print(entry_annotations[\"oligomeric_state\"])" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Instead, `PlinderSystem.system` returns annotations on the system level.\n", "Here, we will extract the SMILES string of the first ligand of a given system." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "system_annotations = plinder_system.system\n", "print(list(system_annotations.keys()))\n", "# Show ligand smiles of the first ligand of a given system\n", "print(system_annotations[\"ligands\"][0][\"rdkit_canonical_smiles\"])" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Getting structure file paths\n", "\n", "The `PlinderSystem` also provides access to the structure files the system is based on.\n", "This could be helpful for loading the structures for training a model or performing\n", "other calculations that require structural information." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "print(plinder_system.ligand_sdfs)\n", "print(plinder_system.smiles)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The same can be done for the receptor protein." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "print(plinder_system.receptor_pdb)\n", "print(plinder_system.receptor_cif)\n", "print(plinder_system.sequences)" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.10.15" } }, "nbformat": 4, "nbformat_minor": 4 }