### Install plinder Python Package

Source: https://github.com/plinder-org/plinder/blob/main/docs/tutorial/api.ipynb

Provides instructions for installing the `plinder` library using pip, the standard Python package installer. This command should be executed in a terminal or command prompt.

```bash
pip install plinder
```

--------------------------------

### Clone Plinder GitHub Repository

Source: https://github.com/plinder-org/plinder/blob/main/docs/contribution/development.md

Clones the official Plinder GitHub repository to your local machine, which is the first step for development.

```console
git clone https://github.com/plinder-org/plinder.git
```

--------------------------------

### Install Additional Data Dependencies

Source: https://github.com/plinder-org/plinder/blob/main/docs/contribution/development.md

Installs additional dependencies required for 'plinder.data' that are not easily pip-installable, using the 'requirements_data.txt' file.

```console
pip install -r requirements_data.txt
```

--------------------------------

### Enable Pre-commit Hooks

Source: https://github.com/plinder-org/plinder/blob/main/docs/contribution/development.md

Installs pre-commit hooks that run code quality checks, ensuring consistency with CI checks before committing changes.

```console
pre-commit install
```

--------------------------------

### Install Documentation Build Dependencies

Source: https://github.com/plinder-org/plinder/blob/main/docs/contribution/documentation.md

Installs the required Python packages for building the PLINDER documentation. These dependencies are specified as extra requirements within the project's `pyproject.toml` file.

```console
$ pip install -e ".[docs]"
```

--------------------------------

### Install PLINDER Python Package

Source: https://github.com/plinder-org/plinder/blob/main/README.md

This snippet provides the command to install the `plinder` Python package. The package is available on PyPI, making it easily installable using the `pip` package manager, which is the standard tool for installing Python packages.

```Shell
pip install plinder
```

--------------------------------

### Retrieve plinder Configuration Settings

Source: https://github.com/plinder-org/plinder/blob/main/docs/tutorial/api.ipynb

Illustrates how to import `plinder.core` and use the `get_config()` function to retrieve the current `plinder` configuration. The snippet then prints the paths for the local cache directory and the remote data directory, verifying correct setup.

```python
import plinder.core.utils.config

cfg = plinder.core.get_config()
print(f"local cache directory: {cfg.data.plinder_dir}")
print(f"remote data directory: {cfg.data.plinder_remote}")
```

--------------------------------

### Create and Activate Conda Environment

Source: https://github.com/plinder-org/plinder/blob/main/docs/contribution/development.md

Creates a new Conda environment for 'plinder' using the 'environment.yml' file and then activates it, preparing the development environment.

```console
mamba env create -f environment.yml
mamba activate plinder
```

--------------------------------

### Install Plinder in Editable Mode

Source: https://github.com/plinder-org/plinder/blob/main/docs/contribution/development.md

Installs the 'plinder' package in editable mode within the activated Conda environment, allowing for direct development changes to be reflected.

```console
pip install -e .
```

--------------------------------

### Run Tox Tests, Type Checks, and Linting

Source: https://github.com/plinder-org/plinder/blob/main/docs/contribution/development.md

Executes various development checks using 'tox', including running tests, performing type checks, and linting the code for quality assurance.

```console
tox -e test
tox -e type
tox -e lint
```

--------------------------------

### Import Plinder and Core Libraries

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/6_custom_split.ipynb

This snippet imports necessary modules from the `plinder` library, including data splitting utilities and core configuration functions. It also initializes the `plinder` configuration and determines the local storage path for data.

```python
from pathlib import Path
import plinder 

from plinder.data.splits import (
    split,
    get_default_config,
)
from plinder.core.scores import query_index

plinder_cfg = plinder.core.get_config()
plinder_local_storage = plinder_cfg.data.plinder_dir
```

--------------------------------

### Initialize PlinderDataset with Filters

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/5_dataset_and_loader.ipynb

Demonstrates how to instantiate a PlinderDataset for validation data, applying specific filters. This example filters for systems with a single protein chain and ATP as a ligand, while also disabling the loading of alternate structures for efficiency.

```python
val_dataset = PlinderDataset(
    split="val",
    filters=[
        ("system_num_protein_chains", "==", 1),
        ("ligand_unique_ccd_code", "in", {"ATP"}),
    ],
    use_alternate_structures=False,
)
len(val_dataset)
```

--------------------------------

### Filter plinder Annotations Table by Criteria

Source: https://github.com/plinder-org/plinder/blob/main/docs/tutorial/api.ipynb

Shows how to apply advanced filtering to the annotation table using the `filters` argument in `query_index()`. This example queries for single-ligand systems by specifying a logical comparison on the `system_num_ligand_chains` column.

```python
from plinder.core.scores import query_index

cols_of_interest = ["system_id", "entry_pdb_id", "entry_release_date", "entry_oligomeric_state", "entry_validation_clashscore", "entry_resolution"]
filters = [("system_num_ligand_chains", "==", 1)]
query_index(columns=cols_of_interest, filters=filters)
```

--------------------------------

### Example Data Rows from Protein Similarity Parquet File

Source: https://github.com/plinder-org/plinder/blob/main/docs/dataset.md

Shows a sample of rows from a `.parquet` file, demonstrating the column structure and typical data entries for protein similarity metrics, including `query_system`, `target_system`, `metric`, and `search_db`.

```text
                    query_system target_system protein_mapping protein_mapper  ...    source                            metric  mapping search_db
1070886    1b5d__1__1.A_1.B__1.D        1b49_A         1.A:0.A       foldseek  ...    mmseqs         protein_qcov_weighted_max  1.A:0.A       apo
1070887    1b5d__1__1.A_1.B__1.D        1b49_A         1.A:0.A       foldseek  ...    mmseqs                  protein_qcov_max  1.A:0.A       apo
1070888    1b5d__1__1.A_1.B__1.D        1b49_A         1.A:0.A       foldseek  ...      both       protein_fident_weighted_max  1.A:0.A       apo
1070889    1b5d__1__1.A_1.B__1.D        1b49_A         1.A:0.A       foldseek  ...      both                protein_fident_max  1.A:0.A       apo
1070890    1b5d__1__1.A_1.B__1.D        1b49_A         1.A:0.A       foldseek  ...    mmseqs  protein_fident_qcov_weighted_max  1.A:0.A       apo
...
213471528      7eek__1__1.A__1.I        1uor_A         1.A:0.A       foldseek  ...  foldseek    protein_lddt_qcov_weighted_max  1.A:0.A       apo
213471529      7eek__1__1.A__1.I        1uor_A         1.A:0.A       foldseek  ...  foldseek             protein_lddt_qcov_max  1.A:0.A       apo
213471536      7eek__1__1.A__1.I        1uor_A         1.A:0.A       foldseek  ...  foldseek                       pocket_lddt     None       apo
213471540      7eek__1__1.A__1.I        6zl1_A         1.A:0.A       foldseek  ...  foldseek                       pocket_lddt     None       apo
213471541      7eek__1__1.A__1.I        6zl1_B         1.A:0.B       foldseek  ...  foldseek                       pocket_lddt     None       apo
```

--------------------------------

### Annotation Tables in `index/` Directory

Source: https://github.com/plinder-org/plinder/blob/main/docs/dataset.md

Details the contents of the `index/` directory, which contains Parquet files listing all systems and their annotations. It includes `annotation_table.parquet` for all systems and `annotation_table_nonredundant.parquet` for a subset without redundant systems. It also clarifies the meaning of 'Mandatory' and 'Example' for column values.

```APIDOC
index/:
  annotation_table.parquet: Lists all systems and their annotations.
  annotation_table_nonredundant.parquet: Subset of systems without redundant systems.

Mandatory: The column has a non-empty, non-NaN value in for all PLINDER systems.
Example: An example non-empty, non-NaN value for the given column in a PLINDER system.
```

--------------------------------

### Initialize PlinderSystem and Get Holo Structure

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/4_align_mask_crop.ipynb

Demonstrates how to instantiate a `PlinderSystem` object using a specific system ID and then access its `holo_structure` attribute, which represents the solved (holo) structure of the system for further processing.

```python
from plinder.core import PlinderSystem

plinder_system = PlinderSystem(system_id="4agi__1__1.C__1.W")

system_structure = plinder_system.holo_structure
```

--------------------------------

### Initialize Plinder Split Properties Plotter from Files

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/6_custom_split.ipynb

This snippet initializes the `SplitPropertiesPlotter` by loading data from the specified `plinder` local storage directory and the newly created custom split file. The plotter is then ready to generate various visualizations of the split's characteristics.

```python
plotter = SplitPropertiesPlotter.from_files(
    data_dir = Path(plinder_local_storage),
    split_file = Path(f'{plinder_local_storage}/splits/split_{split_name}.parquet'),
)
```

--------------------------------

### Import Plotting Utility for Plinder Split Properties

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/6_custom_split.ipynb

This snippet imports the `SplitPropertiesPlotter` class from the `plinder.core.split.plot` module. This class is essential for visualizing various properties and distributions of a dataset split, aiding in the analysis of the newly generated custom split.

```python
from plinder.core.split.plot import SplitPropertiesPlotter
```

--------------------------------

### Query Plinder Index for Custom Dataset Creation

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/6_custom_split.ipynb

This code queries the `plinder` index to create a custom dataset. It specifies a list of columns of interest, including system and ligand properties, and retrieves data from all available splits (train, val, test, removed) to form a base DataFrame for further filtering.

```python
cols_of_interest = [
    "system_id",
    "entry_pdb_id",
    "ligand_ccd_code",
    "ligand_binding_affinity",
    "ligand_is_proper",
    "ligand_molecular_weight",
    "system_has_binding_affinity",
]
custom_df = query_index(
    columns=cols_of_interest, splits=["train", "val", "test", "removed"] 
)
```

--------------------------------

### Query Protein Similarity Dataset with Filters

Source: https://github.com/plinder-org/plinder/blob/main/docs/tutorial/api.ipynb

This snippet demonstrates how to use the `query_protein_similarity` function from `plinder.core.scores` to query protein similarity data. It shows an example of querying the 'holo' dataset, filtering by query and target systems (train/test sets), metric ('pli_unique_qcov'), and a similarity threshold.

```python
from plinder.core.scores import query_protein_similarity

# Example train systems
train = ["7jxf__1__1.A_1.B__1.G", "1jtu__1__1.A_1.B__1.C_1.D",
         "8f9d__2__1.C_1.D__1.G", "6a9a__1__1.A_2.A__2.C_2.D",
         "1b5e__2__1.A_1.B__1.D"]
# Example test systems
test = ["1b5d__1__1.A_1.B__1.D", "1s2g__1__1.A_2.C__1.D",
       "4agi__1__1.C__1.W", "4n7m__1__1.A_1.B__1.C",
         "7eek__1__1.A__1.I"]

metric = "pli_unique_qcov"
threshold = 50
query_protein_similarity(
        search_db="holo",
        columns=["query_system", "target_system", "similarity"],
        filters=[
                ("query_system", "in", test),
                ("target_system", "in", train),
                ("metric", "==", metric),
                ("similarity", ">=", str(threshold))
            ]
)
```

--------------------------------

### Preview First Rows of Newly Generated Plinder Split

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/6_custom_split.ipynb

This snippet displays the first four rows of the `new_split_df` DataFrame. It provides a quick preview of the data structure and content of the newly generated custom dataset split, allowing for initial verification of the resplit operation.

```python
new_split_df.head(4)
```

--------------------------------

### Retrieve and Inspect Default Split Configuration

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/6_custom_split.ipynb

This code retrieves the default configuration for dataset splitting using `get_default_config()`. It then prints the current settings for the validation set size, test set size, and the minimum cluster size required for the validation set, providing insight into the default split parameters.

```python
cfg = get_default_config() 
print(f'Validation set size: {cfg.split.num_val}')
print(f'Test set size: {cfg.split.num_test}')
print(f'Minimum size of each cluster in the validation set: {cfg.split.min_val_cluster_size}')
```

--------------------------------

### Filter Custom Plinder Dataset by Ligand and System Properties

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/6_custom_split.ipynb

This code filters the `custom_df` DataFrame based on specific criteria. It retains only entries where the ligand is proper, the system has a binding affinity, and the ligand's molecular weight exceeds 400 g/mol, refining the dataset to include only relevant systems.

```python
custom_df = custom_df[
    (custom_df["ligand_is_proper"] == True) &
    (custom_df["system_has_binding_affinity"] == True) &
    (custom_df["ligand_molecular_weight"] > 400)
]
```

--------------------------------

### Adjust Plinder Dataset Split Configuration Parameters

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/6_custom_split.ipynb

This snippet modifies the default `plinder` dataset split configuration. It reduces the maximum size of both the test and validation sets to 500 samples each, and decreases the minimum required size for validation set clusters to 5, optimizing the split for smaller datasets or specific analysis needs.

```python
cfg.split.num_test = 500 # Reduce the max size of the test set
cfg.split.num_val = 500 # Reduce the max size of the validation set
cfg.split.min_val_cluster_size = 5 # Reduce the minimum required size of each cluster in the validation set
```

--------------------------------

### Download PLINDER Dataset using `gsutil` Command Line Tool

Source: https://github.com/plinder-org/plinder/blob/main/docs/tutorial/dataset.md

Illustrates how to download a specific release and iteration of the PLINDER dataset directly from Google Cloud Storage using `gsutil`. This involves setting environment variables for the release and iteration, creating a local directory structure, and recursively copying all files from the specified bucket path.

```bash
export PLINDER_RELEASE=2024-06
export PLINDER_ITERATION=tutorial
mkdir -p ~/.local/share/plinder/${PLINDER_RELEASE}/${PLINDER_ITERATION}/
gsutil -m cp -r "gs://plinder/${PLINDER_RELEASE}/${PLINDER_ITERATION}/*" ~/.local/share/plinder/${PLINDER_RELEASE}/${PLINDER_ITERATION}/
```

--------------------------------

### plinder.core Module API Reference

Source: https://github.com/plinder-org/plinder/blob/main/docs/tutorial/api.ipynb

Documents key functions and classes within the `plinder.core` module, providing access to global configuration settings and the `PlinderSystem` data class for reconstituting PLINDER systems.

```APIDOC
plinder.core:
  - get_config():
      Description: Accesses the global PLINDER configuration.
      Returns: Configuration object.
  - PlinderSystem:
      Description: Data class for reconstituting a PLINDER system from its system_id.
```

--------------------------------

### Download PLINDER Dataset using Python `plinder` Package

Source: https://github.com/plinder-org/plinder/blob/main/docs/tutorial/dataset.md

Demonstrates how to download a specific release and iteration of the PLINDER dataset using the `plinder_download` command-line tool from the `plinder` Python package. The `--yes` flag skips confirmation prompts, making the download process non-interactive.

```bash
plinder_download --release 2024-06 --iteration tutorial --yes
```

--------------------------------

### Load PlinderSystem Object from System ID

Source: https://github.com/plinder-org/plinder/blob/main/docs/tutorial/api.ipynb

This snippet demonstrates how to instantiate a `PlinderSystem` object by providing a specific system ID. This is the primary way to load and interact with a single PLINDER system.

```python
from plinder.core import PlinderSystem

plinder_system = PlinderSystem(system_id="4agi__1__1.C__1.W")
```

--------------------------------

### Set Plinder Log Level

Source: https://github.com/plinder-org/plinder/blob/main/docs/contribution/development.md

Sets the 'PLINDER_LOG_LEVEL' environment variable to '10' (DEBUG), allowing for more verbose logging during debugging sessions.

```console
export PLINDER_LOG_LEVEL=10
```

--------------------------------

### Download Plinder Dataset using CLI Tool

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/1_download.ipynb

Demonstrates how to use the `plinder_download` command-line utility to download the complete Plinder dataset. It shows the available options for specifying release, iteration, and skipping confirmation. Note that this downloads a large amount of data and can take a significant amount of time.

```bash
plinder_download --help
usage:
    Download the full plinder dataset for the current configuration.
    Note that even though this is wrapped in a progress bar, the estimated
    completion time can vary wildly as it iterates over larger files vs.
    smaller ones.
    

optional arguments:
  -h, --help            show this help message and exit
  --release RELEASE     plinder release
  --iteration ITERATION
                        plinder iteration
  -y, --yes             skip confirmation
```

--------------------------------

### Get Protein Unique Residue Names in Plinder

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/4_align_mask_crop.ipynb

Accesses the protein_unique_residue_names property to retrieve a list of all unique residue names present in the protein structure.

```python
system_structure.protein_unique_residue_names
```

--------------------------------

### Get Protein Unique Atom Names in Plinder

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/4_align_mask_crop.ipynb

Accesses the protein_unique_atom_names property to retrieve a list of all unique atom names as they appear in the protein structure.

```python
system_structure.protein_unique_atom_names
```

--------------------------------

### Get Protein Unique Residue Numbers in Plinder

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/4_align_mask_crop.ipynb

Accesses the protein_unique_residue_ids property to retrieve a list of unique residue numbers as they appear sequentially in the protein structure.

```python
system_structure.protein_unique_residue_ids
```

--------------------------------

### Load and inspect PLINDER annotation table with Pandas

Source: https://github.com/plinder-org/plinder/blob/main/docs/tutorial/dataset.md

Demonstrates how to load the `index/annotation_table.parquet` file using the pandas library in Python and inspect its column names. This table contains detailed annotations for all PLINDER systems.

```python
df = pd.read_parquet("index/annotation_table.parquet")
df.columns
```

--------------------------------

### Get Total Protein Atom Count in Plinder

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/4_align_mask_crop.ipynb

Accesses the protein_n_atoms property to retrieve the total number of atoms that constitute the protein molecules within the structure.

```python
system_structure.protein_n_atoms
```

--------------------------------

### Get Protein Atom Coordinates in Plinder

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/4_align_mask_crop.ipynb

Accesses the protein_coords property to retrieve the 3D spatial coordinates for all atoms belonging to protein molecules within the structure.

```python
system_structure.protein_coords
```

--------------------------------

### Unpack PLINDER System Structure Files

Source: https://github.com/plinder-org/plinder/blob/main/docs/tutorial/dataset.md

Provides a shell command to unpack zipped structure files located within the `systems` directory of the downloaded PLINDER dataset. The command iterates through all `.zip` archives, extracts their contents, and creates a `_done` marker file for each processed archive to indicate completion.

```bash
cd ~/.local/share/plinder/${PLINDER_RELEASE}/${PLINDER_ITERATION}/systems; for i in `ls *zip`; do unzip $i; touch ${i//.zip/}_done; done
```

--------------------------------

### Get Ordered Protein Chains in Plinder

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/4_align_mask_crop.ipynb

Accesses the protein_chain_ordered property to retrieve a list of protein chain identifiers, maintaining the order in which they appear within the structure.

```python
system_structure.protein_chain_ordered
```

--------------------------------

### Access PlinderSystem Entry-Level Annotations

Source: https://github.com/plinder-org/plinder/blob/main/docs/tutorial/api.ipynb

This snippet shows how to access PDB entry-level annotations for a `PlinderSystem` object using the `.entry` property. It demonstrates listing available annotation categories and retrieving a specific annotation like 'oligomeric_state'.

```python
entry_annotations = plinder_system.entry
print(list(entry_annotations.keys()))
print(entry_annotations["oligomeric_state"])
```

--------------------------------

### Build PLINDER Documentation with Sphinx

Source: https://github.com/plinder-org/plinder/blob/main/docs/contribution/documentation.md

Executes the Sphinx build command to generate the documentation. It processes the source files located in the `docs` directory and outputs the generated documentation to a specified output directory.

```console
$ sphinx-build docs <output directory>
```

--------------------------------

### Get Protein Sequence from Structure in Plinder

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/4_align_mask_crop.ipynb

Accesses the protein_sequence_from_structure property to extract the amino acid sequence directly derived from the protein's atomic coordinates in the structure.

```python
system_structure.protein_sequence_from_structure
```

--------------------------------

### Download PLINDER Dataset with gsutil

Source: https://github.com/plinder-org/plinder/blob/main/README.md

This snippet demonstrates how to download the PLINDER dataset from a Google Cloud Storage bucket using the `gsutil` command-line tool. It sets environment variables for the current release and iteration, creates a local directory, and then recursively copies the dataset files into the specified local path.

```Shell
export PLINDER_RELEASE=2024-06 # Current release
export PLINDER_ITERATION=v2 # Current iteration
mkdir -p ~/.local/share/plinder/${PLINDER_RELEASE}/${PLINDER_ITERATION}/
gsutil -m cp -r "gs://plinder/${PLINDER_RELEASE}/${PLINDER_ITERATION}/*" ~/.local/share/plinder/${PLINDER_RELEASE}/${PLINDER_ITERATION}/
```

--------------------------------

### Get All Protein Chain IDs in Plinder

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/4_align_mask_crop.ipynb

Accesses the protein_chains property to retrieve a list of all unique protein chain identifiers present in the structure, without preserving their original order of appearance.

```python
system_structure.protein_chains
```

--------------------------------

### PLINDER Dataset Local Directory Structure

Source: https://github.com/plinder-org/plinder/blob/main/docs/tutorial/dataset.md

Describes the hierarchical organization of the PLINDER dataset after download, detailing the purpose of key subdirectories such as `clusters` (pre-calculated cluster labels), `dbs` (raw files and IDs), `entries` (raw annotations), `index` (consolidated tabular annotations), `ligands` (ligand data), `splits` (split files), and `systems` (structure files).

```bash
2024-06/                     # The PLINDER release
|-- tutorial                 # The PLINDER iteration
|   |-- clusters             # Pre-calculated cluster labels derived from the protein similarity dataset
|   |-- dbs                  # TSVs containing the raw files and IDs in the foldseek and mmseqs sub-databases
|   |-- entries              # Raw annotations prior to consolidation (split by `two_char_code` and zipped)
|   |-- fingerprints         # Index mapping files for the ligand similarity dataset
|   |-- index                # Consolidated tabular annotations
|   |-- ligand_scores        # Ligand similarity parquet dataset
|   |-- ligands              # Ligand data expanded from entries for computing similarity
|   |-- linked_structures    # Apo and predicted structures linked to their holo systems
|   |-- links                # Apo and predicted structures similarity to their holo structures
|   |-- mmp                  # Ligand matched molecular pairs (MMP) and series (MMS) data
|   |-- scores               # Protein similarity parquet dataset
|   |-- splits               # Split files and the configs used to generate them (if available)
|   |-- systems              # Structure files for all systems (split by `two_char_code` and zipped)
```

--------------------------------

### Display PLINDER clusters directory structure

Source: https://github.com/plinder-org/plinder/blob/main/docs/tutorial/dataset.md

Illustrates the hierarchical directory structure of the PLINDER clusters, organized by similarity metrics, directed/undirected graphs, and clustering thresholds. This helps in understanding how cluster data is stored.

```console
tree clusters

clusters/
├── cluster=communities
│   └── directed=False
│       ├── metric=pli_qcov
│       │   ├── threshold=100
│       │   │   └── data.parquet
│       │   ├── threshold=50
│       │   │   └── data.parquet
│       │   ├── threshold=70
│       │   │   └── data.parquet
│       │   └── threshold=95
│       │       └── data.parquet
│       ├── metric=pli_unique_qcov
│       │   ├── threshold=100
│       │   │   └── data.parquet
│       │   ├── threshold=50
│       │   │   └── data.parquet
│       │   ├── threshold=70
│       │   │   └── data.parquet
│       │   └── threshold=95
│       │       └── data.parquet
```

--------------------------------

### Get Tokenized Protein Sequence in Plinder

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/4_align_mask_crop.ipynb

Accesses the protein_structure_tokenized_sequence property to retrieve the protein sequence converted into integer-based amino acid tokens, typically represented as a tensor for machine learning applications.

```python
system_structure.protein_structure_tokenized_sequence
```

--------------------------------

### Access Plinder Dataset Configuration via Python

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/1_download.ipynb

Illustrates how to use the `plinder.core.utils.config` module in Python to retrieve the local and remote data directories for the Plinder dataset. This method allows for lazy access to the dataset without requiring a full download upfront, making it suitable for exploration and prototyping.

```python
import plinder.core.utils.config

cfg = plinder.core.get_config()
print(f"local directory: {cfg.data.plinder_dir}")
print(f"remote data directory: {cfg.data.plinder_remote}")
```

--------------------------------

### Import PlinderDataset and get_torch_loader

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/5_dataset_and_loader.ipynb

Imports the core PlinderDataset class and the get_torch_loader utility function from the plinder.core.loader.dataset module, essential for setting up data pipelines.

```python
from plinder.core.loader.dataset import PlinderDataset, get_torch_loader
```

--------------------------------

### Get Canonical Protein Sequence (SEQRES) in Plinder

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/4_align_mask_crop.ipynb

Accesses the protein_sequence property to retrieve the canonical SEQRES sequence for the protein. This sequence may differ from the structure-derived sequence due to unresolved terminal residues.

```python
system_structure.protein_sequence
```

--------------------------------

### Retrieve Ligand Structure File Paths and SMILES

Source: https://github.com/plinder-org/plinder/blob/main/docs/tutorial/api.ipynb

This snippet demonstrates how to retrieve the file paths for ligand structure files (SDFs) and the SMILES strings associated with the ligands from a `PlinderSystem` object.

```python
print(plinder_system.ligand_sdfs)
print(plinder_system.smiles)
```

--------------------------------

### Get Reordered Resolved Ligand Coordinates

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/4_align_mask_crop.ipynb

Retrieves the coordinates of the resolved (holo) ligand structure for the first ligand and reorders them using the `holo_atom_order_stack`. This alignment is essential for comparing the resolved coordinates with the input template in a consistent atom order.

```python
system_structure.resolved_ligand_mols_coords[system_structure.ligand_chain_ordered[0]][
    holo_atom_order_stack
]
```

--------------------------------

### Get Reordered Input Ligand Conformer Coordinates

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/4_align_mask_crop.ipynb

Accesses the coordinates of the input ligand conformer for the first ligand and reorders them using the `input_atom_order_stack`. This ensures that the atom order matches the resolved structure, enabling precise comparison of coordinates.

```python
system_structure.input_ligand_conformers_coords[
    system_structure.ligand_chain_ordered[0]
][input_atom_order_stack]
```

--------------------------------

### Initialize PlinderSystem Object in Python

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/3_access_system_files.ipynb

Demonstrates how to import and instantiate the `PlinderSystem` object. This object is used to access and manage system files, automatically downloading and extracting them if not already present. The `system_id` parameter specifies the unique identifier for the desired system.

```python
from plinder.core import PlinderSystem

plinder_system = PlinderSystem(system_id="4agi__1__1.C__1.W")
```

--------------------------------

### Create and Iterate Torch DataLoader

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/5_dataset_and_loader.ipynb

Shows the process of converting a PlinderDataset into a PyTorch DataLoader using get_torch_loader. It then demonstrates iterating through the loader to obtain a batch of data, which is typically a dictionary of tensors.

```python
val_loader = get_torch_loader(val_dataset)
for data in val_loader:
    test_torch = data
    break
```

--------------------------------

### Check Initial Shape of Custom Plinder DataFrame

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/6_custom_split.ipynb

This snippet displays the dimensions (rows, columns) of the `custom_df` DataFrame after its initial creation. It provides a quick overview of the total number of entries and features available before any filtering is applied.

```python
custom_df.shape
```

--------------------------------

### Download Specific PLINDER Subdirectories using `gsutil`

Source: https://github.com/plinder-org/plinder/blob/main/docs/tutorial/dataset.md

Shows how to selectively download a specific subdirectory (e.g., `splits`) from the PLINDER bucket using `gsutil`. This method is useful for managing local storage space when only certain parts of the large dataset are required for analysis or processing.

```bash
gsutil -m cp -r gs://plinder/${PLINDER_RELEASE}/${PLINDER_ITERATION}/splits ~/.local/share/plinder/${PLINDER_RELEASE}/${PLINDER_ITERATION}/
```

--------------------------------

### Load and inspect PLINDER cluster data with Pandas

Source: https://github.com/plinder-org/plinder/blob/main/docs/tutorial/dataset.md

Shows how to load a specific PLINDER cluster file (`data.parquet`) using pandas, based on pocket sequence similarity from an undirected graph at a 70% threshold. The resulting DataFrame displays system IDs and their assigned cluster labels.

```python
import pandas as pd

clus_file = "clusters/cluster=communities/directed=False/metric=pli_qcov/threshold=70/data.parquet"
df = pd.read_parquet(clus_file)
df
```

--------------------------------

### Check Shape of Newly Generated Plinder Split DataFrame

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/6_custom_split.ipynb

This snippet displays the dimensions (rows, columns) of the `new_split_df` DataFrame, which contains the results of the custom dataset resplit. It confirms the number of entries and features in the newly created split.

```python
new_split_df.shape
```

--------------------------------

### Access PlinderSystem System-Level Annotations

Source: https://github.com/plinder-org/plinder/blob/main/docs/tutorial/api.ipynb

This snippet illustrates how to access system-level annotations for a `PlinderSystem` object via the `.system` property. It demonstrates listing available system annotation categories and extracting specific information, such as the RDKit canonical SMILES string for the first ligand.

```python
system_annotations = plinder_system.system
print(list(system_annotations.keys()))
# Show ligand smiles of the first ligand of a given system
print(system_annotations["ligands"][0]["rdkit_canonical_smiles"])
```

--------------------------------

### Check Filtered Shape of Custom Plinder DataFrame

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/6_custom_split.ipynb

This snippet displays the dimensions (rows, columns) of the `custom_df` DataFrame after applying filtering conditions. It shows the reduced number of entries remaining in the dataset, indicating the effect of the filtering operation.

```python
custom_df.shape
```

--------------------------------

### Create Foldseek and MMseqs Databases Task

Source: https://github.com/plinder-org/plinder/blob/main/docs/contribution/pipeline.md

This task creates `foldseek` and `mmseqs` databases, which serve as a basis for similarity datasets. It uses `cif.gz` data for `foldseek` and `pdb_seqres.txt.gz` (obtained from `download_alternative_datasets`) for `mmseqs`.

```APIDOC
Task: tasks.make_dbs
Purpose: Create foldseek and mmseqs databases
Distribution: Called once
Inputs:
  - cif.gz data (for foldseek)
  - pdb_seqres.txt.gz data (for mmseqs)
```

--------------------------------

### Aligning and Superimposing Protein Structures with Plinder

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/4_align_mask_crop.ipynb

This Python example demonstrates how to load protein structures using `PlinderSystem`, set the chain ID of a predicted structure to match the holo structure, align them using `align_common_sequence`, and then superimpose the cropped structures to calculate RMSD.

```python
plinder_system = PlinderSystem(system_id="4cj6__1__1.A__1.B")
holo = plinder_system.holo_structure
predicted = plinder_system.alternate_structures["P12271_A"]
predicted.set_chain(holo.protein_chain_ordered[0])
holo_cropped, predicted_cropped = holo.align_common_sequence(predicted)
predicted_cropped_superposed, raw_rmsd, refined_rmsd = predicted_cropped.superimpose(
    holo_cropped
)
```

--------------------------------

### PlinderDataset Initialization Parameters

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/5_dataset_and_loader.ipynb

Defines the comprehensive set of parameters available for initializing the PlinderDataset class. These parameters allow for specifying data splits, input structure priorities, custom featurizers, and padding values, enabling flexible data loading configurations.

```APIDOC
Parameters
    ----------
    df : pd.DataFrame | None
        the split to use
    split : str
        the split to sample from
    split_parquet_path : str | Path, default=None
        split parquet file
    input_structure_priority : str, default="apo"
        Which alternate structure to proritize
    featurizer: Callable[
            [Structure, int], dict[str, torch.Tensor]
    ] = structure_featurizer,
        Transformation to turn structure to input tensors
    padding_value : int
        Value for padding uneven array
    **kwargs : Any
        Any other keyword args
```

--------------------------------

### Get File Path for a Specific Linked Structure in PlinderSystem

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/3_access_system_files.ipynb

Retrieves the file path to a specific linked structure, such as an apo or predicted structure. This method takes the `kind` of structure (e.g., 'apo') and its `id` as parameters, enabling direct access to the relevant structural file.

```python
plinder_system.get_linked_structure("apo", "4uou_B")
```

--------------------------------

### Create MMP and MMS Datasets (tasks.make_mmp_index)

Source: https://github.com/plinder-org/plinder/blob/main/docs/contribution/pipeline.md

This task creates the `mmp` dataset and consolidates the `index` dataset from `structure_qc`. It writes `mmp/plinder_mmp_series.parquet` and `mmp/plinder_mms.csv.gz`.

```APIDOC
tasks.make_mmp_index:
  Description: Creates the `mmp` dataset and consolidates the `index` dataset.
  Type: Single-call task.
  Inputs: `index` dataset created in `structure_qc`.
  Outputs:
    - `mmp/plinder_mmp_series.parquet`
    - `mmp/plinder_mms.csv.gz`
```

--------------------------------

### Resplit Plinder Dataset with Custom Configuration and Systems

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/6_custom_split.ipynb

This snippet performs a custom resplit of the `plinder` dataset. It uses the previously modified configuration (`cfg`) and a set of selected system IDs from the filtered DataFrame to generate a new split, saving it under a specified name. This operation can be memory-intensive.

```python
data_dir = Path(plinder_local_storage)
custom_systems = set(custom_df['system_id'].unique())
split_name = 'custom_1'

new_split_df = split(
    data_dir=data_dir,
    cfg=cfg, # here we use the modified config from earlier
    relpath=split_name,
    selected_systems=custom_systems 
)
```

--------------------------------

### Retrieve Receptor Structure File Paths and Sequences

Source: https://github.com/plinder-org/plinder/blob/main/docs/tutorial/api.ipynb

This snippet shows how to access the file paths for receptor protein structures (PDB, CIF) and their sequences from a `PlinderSystem` object, useful for structural analysis or modeling.

```python
print(plinder_system.receptor_pdb)
print(plinder_system.receptor_cif)
print(plinder_system.sequences)
```

--------------------------------

### Analyze Split Distribution in Filtered Plinder Dataset

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/6_custom_split.ipynb

This code calculates and displays the count of entries for each split category (e.g., 'train', 'val', 'test', 'removed') within the filtered `custom_df` DataFrame. It provides insight into the current distribution of data across different splits before resplitting.

```python
custom_df['split'].value_counts()
```

--------------------------------

### Load and Inspect PLINDER Data Splits with Pandas

Source: https://github.com/plinder-org/plinder/blob/main/docs/tutorial/dataset.md

This Python snippet demonstrates how to load the PLINDER dataset splits, stored in a Parquet file, into a Pandas DataFrame. It reads the `split.parquet` file and displays the first 5 rows, providing an initial view of the data structure. The dataset includes columns such as:
- `system_id`: The PLINDER system ID
- `uniqueness`: An id tag that captures system redundancy based on ligand and pocket similarity
- `split`: Split category, either `train` (training set), `test` (test set)
- `cluster`: Cluster metric used in sampling test dataset.
- `cluster_for_val_split`: Cluster metric used in sampling validation set from training set.
- `system_pass_validation_criteria`: Boolean indicating whether a system pass all the quality criteria
- `system_pass_statistics_criteria`: Boolean indicating whether a system pass the desired statistics criteria
- `system_proper_num_ligand_chains`: Number of chains ligands that are not ions or artifacts
- `system_proper_pocket_num_residues`: Number of pocket residues around ligands that are not ions or artifacts
- `system_proper_num_interactions`: Number of interactions based on ligands that are not ions or artifacts
- `system_proper_ligand_max_molecular_weight`: Maximum molecular weight of ligands that are not ions or artifacts
- `system_has_binding_affinity`: Boolean indicator of whether a system has binding affinity or not
- `system_has_apo_or_pred`: Boolean indicator of whether a system apo or predicted structures linked

```Python
import pandas as pd
df = pd.read_parquet("splits/split.parquet")
df.head()
```

--------------------------------

### plinder.core Package Overview

Source: https://github.com/plinder-org/plinder/blob/main/docs/api/index.md

Overview of the plinder.core package and its sub-packages, detailing their purpose within the PLINDER dataset interaction.

```APIDOC
Package: plinder.core
  Description: Provides utilities for interacting with the PLINDER dataset.
  Sub-packages:
    plinder.core.scores
      Description: For querying parquet collections.
```

--------------------------------

### Access Ligand SDF Files with PlinderSystem

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/3_access_system_files.ipynb

Retrieves the ligand files in SDF format. This attribute provides direct access to the chemical structure data for the ligands associated with the loaded Plinder system.

```python
plinder_system.ligand_sdfs
```

--------------------------------

### Count Systems with Crystal Contacts

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/2_query_filter_index.ipynb

This Python snippet calculates and prints the total number of unique systems that exhibit crystal contacts. It first drops duplicate system IDs to ensure each system is counted only once, then filters for systems where the `system_fraction_atoms_with_crystal_contacts` is greater than zero, and finally sums the boolean results to get the count. This helps identify systems with potential crystallographic artifacts.

```python
(
    plindex.drop_duplicates("system_id").system_fraction_atoms_with_crystal_contacts > 0
).sum()
```

--------------------------------

### Compute Ligand Fingerprints (tasks.compute_ligand_fingerprints)

Source: https://github.com/plinder-org/plinder/blob/main/docs/contribution/pipeline.md

This task computes ligand fingerprints using the `ligands` data. It generates `fingerprints/ligands_per_inchikey.parquet`, `fingerprints/ligands_per_inchikey_ecfp4.npy`, and `fingerprints/ligands_per_system.parquet`.

```APIDOC
tasks.compute_ligand_fingerprints:
  Description: Computes ligand fingerprints.
  Type: Single-call task.
  Inputs: `ligands` data.
  Outputs:
    - `fingerprints/ligands_per_inchikey.parquet`
    - `fingerprints/ligands_per_inchikey_ecfp4.npy`
    - `fingerprints/ligands_per_system.parquet`
```

--------------------------------

### Query plinder Annotations Table (Default Columns)

Source: https://github.com/plinder-org/plinder/blob/main/docs/tutorial/api.ipynb

Demonstrates the basic usage of `query_index()` from `plinder.core.scores` without any arguments. This call retrieves the default columns (`system_id`, `entry_pdb_id`, and `split`) for systems present in the 'train' and 'val' splits.

```python
from plinder.core.scores import query_index

# Get system_id, entry_pdb_id, and split columns of train and val splits
query_index()
```

--------------------------------

### Filter and Display Key Columns of Linked Structures DataFrame

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/3_access_system_files.ipynb

Demonstrates how to select and display specific columns from the `linked_structures` DataFrame. This allows users to focus on critical metrics such as identification, similarity scores, and evaluation metrics for linked structures, aiding in data analysis.

```python
link_info[
    [
        "id",
        "pocket_fident",
        "lddt",
        "bb_lddt",
        "lddt_lp_ave",
        "lddt_pli_ave",
        "bisy_rmsd_ave",
        "sort_score",
        "kind"
    ]
]
```

--------------------------------

### Generate Ligand Data (tasks.make_ligands)

Source: https://github.com/plinder-org/plinder/blob/main/docs/contribution/pipeline.md

This distributed task creates the `ligands` data by processing chunks of PDB IDs. It filters acceptable ligands from `raw_entries` JSON files and writes `ligands/{chunk_hash}.parquet`.

```APIDOC
tasks.make_ligands:
  Description: Creates the `ligands` data.
  Type: Distributed task (parallel processing for chunks of PDB IDs).
  Inputs: JSON files from `raw_entries`.
  Outputs: `ligands/{chunk_hash}.parquet`
  Filters: Ligands acceptable for similarity analysis.
```

--------------------------------

### Input File Schema: split.parquet

Source: https://github.com/plinder-org/plinder/blob/main/docs/evaluation.md

Describes the required columns for the `split.parquet` input file, mapping PLINDER systems to `train` or `test` splits.

```APIDOC
split.parquet:
  system_id: PLINDER system identifier
  split: Mapping to 'train' or 'test'
```

--------------------------------

### Input File Schema: predictions.csv

Source: https://github.com/plinder-org/plinder/blob/main/docs/evaluation.md

Describes the required columns and their purpose for the `predictions.csv` input file, used for protein-ligand pose evaluation.

```APIDOC
predictions.csv:
  id: An identifier for the prediction (same across different ranked poses of the same prediction)
  reference_system_id: plinder system ID to use as reference
  receptor_file: Path to protein CIF file. Leave blank if rigid docking, the system's receptor file will be used.
  rank: The rank of the pose (1-indexed)
  confidence: Optional score associated with the pose
  ligand_file: Path to the pose SDF file or directory of SDF files for multi ligand poses
```

--------------------------------

### Configure plinder Environment Variables in Python

Source: https://github.com/plinder-org/plinder/blob/main/docs/tutorial/api.ipynb

Demonstrates how to set specific environment variables, `PLINDER_LOG_LEVEL` and `PLINDER_ITERATION`, directly within a Python script or interactive session using IPython's `%env` magic command. This configures the `plinder` library's behavior and data access.

```python
%env PLINDER_LOG_LEVEL=0
%env PLINDER_ITERATION=tutorial
```

--------------------------------

### Query plinder Annotations Table (Specific Columns)

Source: https://github.com/plinder-org/plinder/blob/main/docs/tutorial/api.ipynb

Illustrates how to retrieve a specific set of columns from the annotation table by passing a list of column names to the `columns` argument of `query_index()`. This allows users to fetch only the data relevant to their analysis.

```python
from plinder.core.scores import query_index

cols_of_interest = ["system_id", "entry_pdb_id", "entry_release_date", "entry_oligomeric_state", "entry_validation_clashscore", "entry_resolution"]
query_index(columns=cols_of_interest)
```

--------------------------------

### Import Core Libraries for Data Analysis and Visualization

Source: https://github.com/plinder-org/plinder/blob/main/docs/examples/2_query_filter_index.ipynb

This snippet imports essential Python libraries: `matplotlib.pyplot` for plotting, `mols2grid` for molecular grid visualization, and `numpy` for numerical operations. These are foundational for data manipulation and presentation within the PLINDER project.

```python
import matplotlib.pyplot as plt
import mols2grid
import numpy as np
```

--------------------------------

### plinder.core.get_plindex() API Reference

Source: https://github.com/plinder-org/plinder/blob/main/docs/tutorial/api.ipynb

Documents the `get_plindex()` function, which loads the entire annotation table. It includes a warning about the significant memory footprint (~24GB RAM) due to the large number of rows and columns, advising users to query only necessary columns.

```APIDOC
plinder.core.get_plindex():
  Description: Returns all columns in the annotation table.
  Warning: This function has a significant memory footprint (~24G RAM) due to over 1.3 million rows and over 700 columns. Users are advised to query only columns
```