pyKVFinder.openings

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

[WIP] Identify openings of the detected cavities and calculate their areas.

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.
depths (Optional[numpy.ndarray], optional) – A numpy.ndarray with depth of cavity points (depth[nx][ny][nz]), by default None. If None, depths is calculated from cavities.
step (Union[float, int], optional) – Grid spacing (A), by default 0.6.
openings_cutoff (int, optional) – The minimum number of voxels an opening must have, by default 1.
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:

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

Raises:

TypeError – cavities must be a numpy.ndarray.
ValueError – cavities has the incorrect shape. It must be (nx, ny, nz).
TypeError – depths must be a numpy.ndarray.
ValueError – depths 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 – openings_cutoff must be an integer.
ValueError – openings_cutoff must be a positive integer.
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

Example

With the cavity points identified with detect, we can characterize their openings, that includes number and area of openings and defining opening points:

>>> from pyKVFinder import openings
>>> nopenings, openings, aopenings = openings(cavities)
>>> nopenings
16
>>> openings
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]]])
>>> aopenings
{'KAA': {'OAA': 47.41, 'OAG': 3.6}, 'KAB': {'OAB': 25.84}, 'KAC': {'OAC': 53.62}, 'KAD': {'OAD': 12.59}, 'KAE': {'OAE': 26.3}, 'KAF': {'OAF': 18.46}, 'KAG': {'OAH': 12.83}, 'KAH': {'OAK': 59.96}, 'KAJ': {'OAI': 16.11}, 'KAL': {'OAJ': 17.3}, 'KAM': {'OAL': 35.27}, 'KAO': {'OAM': 8.49}, 'KAP': {'OAN': 13.71}, 'KAQ': {'OAO': 13.16}, 'KAR': {'OAP': 15.36}}

With the cavity and opening points identified, we can:

Export cavity points with opening points mapped on them:

>>> from pyKVFinder import export
>>> export("cavities_with_openings.pdb", cavities, None, vertices, B=openings)

Export opening points with same nomenclature from aopenings:

>>> from pyKVFinder import export_openings
>>> export_openings("openings.pdb", openings, vertices)