### Version Option Example

Source: https://lbc-lnbio.github.io/pyKVFinder/plugins/cli/index.html

Example of how to display the pyKVFinder version.

```bash
$ pyKVFinder --version

```

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

### Summary installation steps

Source: https://lbc-lnbio.github.io/pyKVFinder/_sources/plugins/pymol/index.rst.txt

A consolidated list of commands for setting up the environment, installing PyMOL and pyKVFinder, and launching PyMOL.

```bash
conda create -n pymol python=3.10
conda activate pymol
conda install -c conda-forge -c schrodinger pymol-bundle
pip install pyKVFinder
pymol
```

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

### Help Option Example

Source: https://lbc-lnbio.github.io/pyKVFinder/plugins/cli/index.html

Examples of how to display the help message using short and long options.

```bash
$ pyKVFinder -h
$ pyKVFinder --help

```

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

### Step Option Example

Source: https://lbc-lnbio.github.io/pyKVFinder/plugins/cli/index.html

Examples of setting the grid spacing in Angstroms using short and long options.

```bash
$ pyKVFinder (<.pdb> | <.xyz>) -s <float>
$ pyKVFinder (<.pdb> | <.xyz>) --step <float>

```

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

### Standard Workflow

Source: https://lbc-lnbio.github.io/pyKVFinder/_sources/package/tutorial/index.rst.txt

Run the standard workflow for cavity detection with spatial and constitutional characterization.

```python
>>> import os
>>> pdb = os.path.join(os.path.dirname(pyKVFinder.__file__), 'data', 'tests', '1FMO.pdb')
>>> results = pyKVFinder.run_workflow(pdb)
>>> results
<pyKVFinderResults object>
```

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

### Example usage of _get_vertices_from_residues

Source: https://lbc-lnbio.github.io/pyKVFinder/_modules/pyKVFinder/grid/geometry.html

Shows how to define residues and padding to get vertices.

```python
>>> [box]
>>> residues = [ [ "resnum", "chain", "resname",], [ "resnum", "chain",
... "resname", ] ]
>>> padding =  3.5
```

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

### Cavity Detection Example

Source: https://lbc-lnbio.github.io/pyKVFinder/_sources/package/tutorial/index.rst.txt

Demonstrates how to detect cavities using the `pyKVFinder.detect` function and shows the output for the number of cavities and the cavity grid.

```python
>>> ncav_la, cavities_la = pyKVFinder.detect(atomic, vertices, latomic=latomic, ligand_cutoff=ligand_cutoff)
>>> ncav_la
2
>>> cavities_la
array([[[-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1],
      ...,
      [-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1]],

     ...,

     [[-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1],
      ...,
      [-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1]]], dtype=int32)
```

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

### Example usage of _get_vertices_from_box

Source: https://lbc-lnbio.github.io/pyKVFinder/_modules/pyKVFinder/grid/geometry.html

Demonstrates how to define box coordinates and get vertices.

```python
>>> [box]
>>> p1 = [x1, y1, z1]
>>> p2 = [x2, y2, z2]
>>> p3 = [x3, y3, z3]
>>> p4 = [x4, y4, z4]
```

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

### Install from PyPI

Source: https://lbc-lnbio.github.io/pyKVFinder/_sources/package/installation/index.rst.txt

Installs the latest release of pyKVFinder from the Python Package Index.

```bash
pip install pyKVFinder
```

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

### Creating a box configuration file

Source: https://lbc-lnbio.github.io/pyKVFinder/_sources/package/tutorial/index.rst.txt

This snippet demonstrates how to create a TOML file for box configuration using Python.

```python
>>> fn = 'box.toml'
>>> box = """
	[SETTINGS.visiblebox.p1]
	x = 3.11
	y = 7.34
	z = 1.59

	[SETTINGS.visiblebox.p2]
	x = 11.51
	y = 7.34
	z = 1.59

	[SETTINGS.visiblebox.p3]
	x = 3.11
	y = 10.74
	z = 1.59

	[SETTINGS.visiblebox.p4]
	x = 3.11
	y = 7.34
	z = 6.19
  """
>>> with open(fn, 'w') as f:
...     toml.dump(toml.loads(box), f)
```

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

### Spatial Characterization Example

Source: https://lbc-lnbio.github.io/pyKVFinder/_sources/package/tutorial/index.rst.txt

Shows how to perform spatial characterization on detected cavities to obtain surface points, volume, and area.

```python
>>> surface, volume, area = pyKVFinder.spatial(cavities, step=step)
>>> surface
array([[[-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1],
      ...,
      [-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1]],

     ...,

     [[-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1],
      ...,
      [-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1]]], dtype=int32)
>>> volume
{'KAA': 137.16, 'KAB': 47.52, 'KAC': 66.96, 'KAD': 8.21, 'KAE': 43.63, 'KAF': 12.53, 'KAG': 6.26, 'KAH': 520.13, 'KAI': 12.31, 'KAJ': 26.57, 'KAK': 12.31, 'KAL': 33.91, 'KAM': 23.11, 'KAN': 102.82, 'KAO': 6.05, 'KAP': 15.55, 'KAQ': 7.99, 'KAR': 7.78}
>>> area
{'KAA': 126.41, 'KAB': 62.37, 'KAC': 74.57, 'KAD': 19.06, 'KAE': 57.08, 'KAF': 22.77, 'KAG': 15.38, 'KAH': 496.97, 'KAI': 30.58, 'KAJ': 45.64, 'KAK': 30.58, 'KAL': 45.58, 'KAM': 45.25, 'KAN': 129.77, 'KAO': 12.28, 'KAP': 25.04, 'KAQ': 13.46, 'KAR': 16.6}
```

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

### Install from PyPI

Source: https://lbc-lnbio.github.io/pyKVFinder/package/installation/index.html

Installs the latest stable release of pyKVFinder from the Python Package Index.

```bash
pip install pyKVFinder

```

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

### Install from source (developmental version)

Source: https://lbc-lnbio.github.io/pyKVFinder/_sources/package/installation/index.rst.txt

Clones the repository and installs the developmental version of pyKVFinder in editable mode.

```bash
git clone https://github.com/LBC-LNBio/pyKVFinder.git
pip install -e pyKVFinder
```

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

### Standard and Full Workflows

Source: https://lbc-lnbio.github.io/pyKVFinder/_sources/package/tutorial/index.rst.txt

This snippet shows how to run the standard and full workflows of pyKVFinder using a PDB file and a custom box configuration.

```python
>>> pdb = os.path.join(os.path.dirname(pyKVFinder.__file__), 'data', 'tests', '1FMO.pdb')
>>> # Box configuration filepath
>>> fn = os.path.join(os.path.dirname(pyKVFinder.__file__), 'data', 'tests', 'custom-box.toml')
>>> # Standard workflow
>>> results = pyKVFinder.run_workflow(pdb, box=fn)
>>> # Full workflow
>>> results = pyKVFinder.run_workflow(pdb, box=fn, include_depth=True, include_hydropathy=True, hydrophobicity_scale='EisenbergWeiss')
```

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

### Default Cavity Detection Parameters

Source: https://lbc-lnbio.github.io/pyKVFinder/_sources/package/tutorial/index.rst.txt

Example demonstrating how to use pyKVFinder.detect with default parameters and showing the output.

```python
>>> # Default Grid Spacing (step): 0.6
>>> step = 0.6  
>>> # Default Probe In (probe_in): 1.4
>>> probe_in = 1.4
>>> # Default Probe Out (probe_out): 4.0
>>> probe_out = 4.0
>>> # Default Removal Distance (removal_distance): 2.4
>>> removal_distance = 2.4
>>> # Default Volume Cutoff (volume_cutoff): 5.0
>>> volume_cutoff = 5.0
>>> # Default Surface Representation (surface): 'SES'
>>> surface = 'SES'
>>> ncav, cavities = pyKVFinder.detect(atomic, vertices, step=step, probe_in=probe_in, probe_out=probe_out, removal_distance=removal_distance, volume_cutoff=volume_cutoff, surface=surface)
>>> ncav
18
>>> cavities
array([[[-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1],
      ...,
      [-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1]],

     ...,

     [[-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1],
      ...,
      [-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1]]], dtype=int32)
```

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

### Number of Threads Option Example

Source: https://lbc-lnbio.github.io/pyKVFinder/plugins/cli/index.html

Example of setting the number of threads for parallel routines.

```bash
$ pyKVFinder (<.pdb> | <.xyz>) --nthreads <int>

```

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

### Example Usage

Source: https://lbc-lnbio.github.io/pyKVFinder/_modules/pyKVFinder/grid/depth.html

This snippet shows an example of how to use the depth function and its expected output.

```python
>>> depths, max_depth, avg_depth = depth(cavities)
>>> print(depths)
[[[0. 0. 0. ... 0. 0. 0.]
  [0. 0. 0. ... 0. 0. 0.]
  [0. 0. 0. ... 0. 0. 0.]]

 ...

 [[0. 0. 0. ... 0. 0. 0.]
  [0. 0. 0. ... 0. 0. 0.]
  [0. 0. 0. ... 0. 0. 0.]]])
>>> max_depth
{'KAA': 3.79, 'KAB': 2.68, 'KAC': 2.62, 'KAD': 0.85, 'KAE': 3.0, 'KAF': 0.85, 'KAG': 0.6, 'KAH': 10.73, 'KAI': 0.0, 'KAJ': 2.24, 'KAK': 0.0, 'KAL': 3.0, 'KAM': 1.2, 'KAN': 0.0, 'KAO': 1.04, 'KAP': 2.08, 'KAQ': 0.85, 'KAR': 0.6}
>>> avg_depth
{'KAA': 1.35, 'KAB': 0.91, 'KAC': 0.68, 'KAD': 0.32, 'KAE': 0.99, 'KAF': 0.24, 'KAG': 0.1, 'KAH': 3.91, 'KAI': 0.0, 'KAJ': 0.96, 'KAK': 0.0, 'KAL': 1.07, 'KAM': 0.24, 'KAN': 0.0, 'KAO': 0.29, 'KAP': 0.7, 'KAQ': 0.22, 'KAR': 0.12}
```

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

### Constitutional Characterization Example

Source: https://lbc-lnbio.github.io/pyKVFinder/_sources/package/tutorial/index.rst.txt

Demonstrates how to perform constitutional characterization to identify interface residues.

```python
>>> # Default ignore backbone contacts flag (ignore_backbone): False
>>> ignore_backbone = False
>>> residues = pyKVFinder.constitutional(cavities, atomic, vertices, step=step, probe_in=probe_in, ignore_backbone=ignore_backbone)
>>> residues
```

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

### Verbose Option Example

Source: https://lbc-lnbio.github.io/pyKVFinder/plugins/cli/index.html

Example of using the verbose option to print extra information.

```bash
$ pyKVFinder (<.pdb> | <.xyz>) --verbose

```

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

### Exporting cavity and surface points with depth mapped on B-factor and hydrophobicity scale mapped on Q-factor (advanced)

Source: https://lbc-lnbio.github.io/pyKVFinder/_sources/package/tutorial/index.rst.txt

Advanced example of exporting cavity and surface points with depth mapped on B-factor and hydrophobicity scale mapped on Q-factor.

```python
>>> output_cavity = 'cavity_with_depth.pdb'
>>> pyKVFinder.export(output_cavity, cavities, surface, vertices, step=step, B=depths, Q=scales)
```

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

### Ligand Adjustment for Cavity Detection

Source: https://lbc-lnbio.github.io/pyKVFinder/_sources/package/tutorial/index.rst.txt

Example demonstrating how to read a ligand from a PDB file and use it for cavity detection with pyKVFinder.

```python
>>> ligand = os.path.join(os.path.dirname(pyKVFinder.__file__), 'data', 'tests', 'ADN.pdb')
>>> latomic = pyKVFinder.read_pdb(ligand)
>>> latomic
array([['351', 'E', 'ADN', "C5'", '11.087', '9.79', '2.052', '1.66'],
       ['351', 'E', 'ADN', "O5'", '11.545', '8.52', '1.545', '1.69'],
       ['351', 'E', 'ADN', "C4'", '10.688', '9.68', '3.523', '1.66'],
       ['351', 'E', 'ADN', "O4'", '9.714', '10.725', '3.81', '1.69'],
       ['351', 'E', 'ADN', "C3'", '9.973', '8.374', '3.903', '1.66'],
       ['351', 'E', 'ADN', "O3'", '10.879', '7.361', '4.304', '1.69'],
       ['351', 'E', 'ADN', "C2'", '9.115', '8.82', '5.059', '1.66'],
       ['351', 'E', 'ADN', "O2'", '9.887', '9.034', '6.232', '1.69'],
       ['351', 'E', 'ADN', "C1'", '8.625', '10.16', '4.5', '1.66'],
       ['351', 'E', 'ADN', 'N1', '3.499', '10.104', '4.402', '1.97'],
       ['351', 'E', 'ADN', 'C2', '4.376', '10.259', '5.387', '1.66'],
       ['351', 'E', 'ADN', 'N3', '5.705', '10.249', '5.351', '1.97'],
       ['351', 'E', 'ADN', 'C4', '6.136', '10.087', '4.094', '1.66'],
       ['351', 'E', 'ADN', 'C5', '5.353', '9.952', '2.974', '1.66'],
       ['351', 'E', 'ADN', 'C6', '3.957', '9.957', '3.146', '1.66'],
       ['351', 'E', 'ADN', 'N6', '3.083', '9.826', '2.142', '1.97'],
       ['351', 'E', 'ADN', 'N7', '6.146', '9.791', '1.843', '1.97'],
       ['351', 'E', 'ADN', 'C8', '7.374', '9.872', '2.291', '1.66'],
       ['351', 'E', 'ADN', 'N9', '7.444', '10.056', '3.646', '1.97']],
      dtype='<U32')

>>> # Default Ligand Cutoff (ligand_cutoff): 5.0
>>> ligand_cutoff = 5.0
```

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

### Positional Argument Example

Source: https://lbc-lnbio.github.io/pyKVFinder/plugins/cli/index.html

Example of how to specify the positional argument for a PDB or XYZ file.

```bash
$ pyKVFinder (<.pdb> | <.xyz>)

```

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

### Full Workflow Execution

Source: https://lbc-lnbio.github.io/pyKVFinder/_sources/package/tutorial/index.rst.txt

This code snippet illustrates how to run the full workflow for cavity detection, including spatial, constitutional, hydropathy, and depth characterization, by setting parameters in the `pyKVFinder.run_workflow` function.

```python
>>> results = pyKVFinder.run_workflow(pdb, include_depth=True, include_hydropathy=True, hydrophobicity_scale='EisenbergWeiss')
```

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

### Example Usage

Source: https://lbc-lnbio.github.io/pyKVFinder/package/api_reference/openings.html

Example of how to use the openings function to identify and calculate areas of openings in cavities.

```python
from pyKVFinder import openings
nopenings, openings, aopenings = openings(cavities)
print(nopenings)
print(openings)
print(aopenings)
```

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

### Writing results: Spatial, constitutional, depth and hydropathy characterization

Source: https://lbc-lnbio.github.io/pyKVFinder/_sources/package/tutorial/index.rst.txt

Example of writing results with spatial, constitutional, depth, and hydropathy characterization.

```python
>>> output_results = 'results.toml'
>>> pyKVFinder.write_results(output_results, input=pdb, ligand=None, output=output_cavity, volume=volume, area=area, max_depth=max_depth, avg_depth=avg_depth, avg_hydropathy=avg_hydropathy, residues=residues, frequencies=frequencies, step=step)
```

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

### Install PyMOL Open-Source

Source: https://lbc-lnbio.github.io/pyKVFinder/_sources/plugins/pymol/index.rst.txt

Command to install the open-source version of PyMOL using conda.

```bash
conda install -c conda-forge pymol-open-source
```

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

### Example: Write cavity detection

Source: https://lbc-lnbio.github.io/pyKVFinder/_modules/pyKVFinder/utils.html

Example of writing cavity detection results to a TOML file.

```python
from pyKVFinder import write_results
import os
pdb = os.path.join(os.path.dirname(pyKVFinder.__file__), 'data', 'tests', '1FMO.pdb')
write_results('results.toml', input=pdb, ligand=None, output='cavities.pdb')
```

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

### Writing results: Spatial, constitutional and depth characterization

Source: https://lbc-lnbio.github.io/pyKVFinder/_sources/package/tutorial/index.rst.txt

Example of writing results with spatial, constitutional, and depth characterization.

```python
>>> output_results = 'results.toml'
>>> pyKVFinder.write_results(output_results, input=pdb, ligand=None, output=output_cavity, volume=volume, area=area, max_depth=max_depth, avg_depth=avg_depth, residues=residues, frequencies=frequencies, step=step)
```

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

### Exporting cavity and surface points with depth mapped on B-factor and hydrophobicity scale mapped on Q-factor

Source: https://lbc-lnbio.github.io/pyKVFinder/_sources/package/tutorial/index.rst.txt

Example of exporting cavity and surface points with depth mapped on B-factor and hydrophobicity scale mapped on Q-factor.

```python
>>> output_cavity = 'cavity_with_depth.pdb'
>>> pyKVFinder.export(output_cavity, cavities, surface, vertices, step=step, B=depths)
```

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

### Example of calculate_frequencies usage

Source: https://lbc-lnbio.github.io/pyKVFinder/_modules/pyKVFinder/utils.html

This example demonstrates how to use the calculate_frequencies function with pre-identified interface residues.

```python
from pyKVFinder import calculate_frequencies
residues
```

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

### Defining a custom 3D grid using a TOML file with residues and padding

Source: https://lbc-lnbio.github.io/pyKVFinder/_sources/package/tutorial/index.rst.txt

Example of loading a TOML file to define a custom 3D grid based on a list of residues and padding.

```python
>>> fn = os.path.join(os.path.dirname(pyKVFinder.__file__), 'data', 'tests', 'residues-box.toml')
>>> box = toml.load(fn)
>>> box
{'box': {'residues': [['49', 'E', 'LEU'], ['50', 'E', 'GLY'], ['51', 'E', 'THR']], 'padding': 3.5}}
```

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

### Cavity Detection Example

Source: https://lbc-lnbio.github.io/pyKVFinder/package/tutorial/index.html

Example demonstrating the usage of pyKVFinder.detect with default and custom parameters, showing the number of cavities and the cavity points grid.

```python
>>> # Default Grid Spacing (step): 0.6
>>> step = 0.6
>>> # Default Probe In (probe_in): 1.4
>>> probe_in = 1.4
>>> # Default Probe Out (probe_out): 4.0
>>> probe_out = 4.0
>>> # Default Removal Distance (removal_distance): 2.4
>>> removal_distance = 2.4
>>> # Default Volume Cutoff (volume_cutoff): 5.0
>>> volume_cutoff = 5.0
>>> # Default Surface Representation (surface): 'SES'
>>> surface = 'SES'
>>> ncav, cavities = pyKVFinder.detect(atomic, vertices, step=step, probe_in=probe_in, probe_out=probe_out, removal_distance=removal_distance, volume_cutoff=volume_cutoff, surface=surface)
>>> ncav
18
>>> cavities
array([[[-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1],
      ...,
      [-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1]],

     ...,

     [[-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1],
      ...,
      [-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1],
      [-1, -1, -1, ..., -1, -1, -1]]], dtype=int32)

```

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

### Get opening name

Source: https://lbc-lnbio.github.io/pyKVFinder/_modules/pyKVFinder/grid/openings.html

Get opening name, eg OAA, OAB, and so on, based on the index.

```python
import os
import warnings

import numpy

from .cavity import _get_cavity_label, _get_cavity_name, _select_cavities
from .depth import depth


def _get_opening_name(index: int) -> str:
    """Get opening name, eg OAA, OAB, and so on, based on the index.

    Naming convention:
    - 0-675   -> OAA ... OZZ
    - 676-1351 -> Oaa ... Ozz

    Parameters
    ----------
    index : int
        Index in the dictionary.

    Returns
    -------
    opening_name : str
        Opening name
    """
    # Get block and offset
    block = index // (26 * 26)
    offset = index % (26 * 26)

    # Choose ASCII base: uppercase or lowercase
    base = 65 if block == 0 else 97  # 'A' or 'a'

    # Get first and second characters
    first = chr(base + (offset // 26))
    second = chr(base + (offset % 26))

    # Build opening name
    opening_name = f"O{first}{second}"

    return opening_name
```