pyKVFinder.spatial

pyKVFinder.spatial(cavities: ndarray, step: float | int = 0.6, selection: List[int] | List[str] | None = None, nthreads: int | None = None, verbose: bool = False) → Tuple[ndarray, Dict[str, float], Dict[str, float]][source]

Spatial characterization (volume and area) of the detected cavities.

Parameters:

cavities (numpy.ndarray) –
Cavity points in the 3D grid (cavities[nx][ny][nz]). Cavities array has integer labels in each position, that are:
- -1: bulk points;
- 0: biomolecule points;
- 1: empty space points;
- >=2: cavity points.
The empty space points are regions that do not meet the chosen volume cutoff to be considered a cavity.
step (Union[float, int], optional) – Grid spacing (A), by default 0.6.
selection (Union[List[int], List[str]], optional) – A list of integer labels or a list of cavity names to be selected, by default None.
nthreads (int, optional) – Number of threads, by default None. If None, the number of threads is os.cpu_count() - 1.
verbose (bool, optional) – Print extra information to standard output, by default False.

Returns:

surface (numpy.ndarray) – Surface points in the 3D grid (surface[nx][ny][nz]). Surface array has integer labels in each position, that are:
- -1: bulk points;
- 0: biomolecule or empty space points;
- >=2: surface points.
The empty space points are regions that do not meet the chosen volume cutoff to be considered a cavity.
volume (Dict[str, float]) – A dictionary with volume of each detected cavity.
area (Dict[str, float]) – A dictionary with area of each detected cavity.

Note

The cavity nomenclature is based on the integer label. The cavity marked with 2, the first integer corresponding to a cavity, is KAA, the cavity marked with 3 is KAB, the cavity marked with 4 is KAC and so on.

Raises:

TypeError – cavities must be a numpy.ndarray.
ValueError – cavities has the incorrect shape. It must be (nx, ny, nz).
TypeError – step must be a positive real number.
ValueError – step must be a positive real number.
TypeError – selection must be a list of strings (cavity names) or integers (cavity labels).
ValueError – Invalid selection: {selection}.
TypeError – nthreads must be a positive integer.
ValueError – nthreads must be a positive integer.
TypeError – verbose must be a boolean.

See also

detect, hydropathy, export

Example

With the cavity points identified with detect, we can perform a spatial characterization, that includes volume, area and defining surface points:

>>> from pyKVFinder import spatial
>>> surface, volume, area = spatial(cavities)
>>> 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}