{ "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": 1, "metadata": {}, "outputs": [], "source": [ "import os\n", "from pathlib import Path\n", "\n", "release = \"2024-06\"\n", "iteration = \"tutorial\"\n", "os.environ[\"PLINDER_RELEASE\"] = release\n", "os.environ[\"PLINDER_ITERATION\"] = iteration\n", "os.environ[\"PLINDER_REPO\"] = str(Path.home()/\"plinder-org/plinder\")\n", "os.environ[\"PLINDER_LOCAL_DIR\"] = str(Path.home()/\".local/share/plinder\")\n", "os.environ[\"GCLOUD_PROJECT\"] = \"plinder\"\n", "version = f\"{release}/{iteration}\"" ] }, { "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}`get_plindex()`: access full annotation table\n", "- {func}`get_split`: access full split 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": 2, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "local cache directory: /Users/yusuf/.local/share/plinder/2024-06/tutorial\n", "remote data directory: gs://plinder/2024-06/tutorial\n" ] } ], "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` and\n", "`entry_pdb_id`.\n", "However, the function could 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": [ "from plinder.core.scores import query_index\n", "# Get system_id and entry_pdb_id columns\n", "query_index()" ] }, { "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\",\n", "\"entry_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": [ ":::{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 row and 500 columns, it has a significant memory footprint 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": 85, "metadata": {}, "outputs": [ { "name": "stderr", "output_type": "stream", "text": [ "2024-08-27 11:32:47,823 | plinder.core.utils.cpl.download_paths:24 | INFO : runtime succeeded: 0.00s\n", "2024-08-27 11:32:47,978 | plinder.core.scores.protein.query_protein_similarity:24 | INFO : runtime succeeded: 2.12s\n" ] }, { "data": { "text/html": [ "
\n", " | query_system | \n", "target_system | \n", "similarity | \n", "
---|---|---|---|
0 | \n", "1b5d__1__1.A_1.B__1.D | \n", "1b5e__2__1.A_1.B__1.D | \n", "83 | \n", "
1 | \n", "1b5d__1__1.A_1.B__1.D | \n", "6a9a__1__1.A_2.A__2.C_2.D | \n", "83 | \n", "
2 | \n", "1b5d__1__1.A_1.B__1.D | \n", "1jtu__1__1.A_1.B__1.C_1.D | \n", "67 | \n", "
3 | \n", "1b5d__1__1.A_1.B__1.D | \n", "7jxf__1__1.A_1.B__1.G | \n", "67 | \n", "
4 | \n", "4n7m__1__1.A_1.B__1.C | \n", "8f9d__2__1.C_1.D__1.G | \n", "50 | \n", "