pyKVFinder.export

pyKVFinder.export(fn: str | Path | None, cavities: ndarray, surface: ndarray | None, vertices: ndarray | list[list[float]], step: float | int = 0.6, B: ndarray | None = None, Q: ndarray | None = None, selection: list[int] | list[str] | None = None, nthreads: int | None = None, append: bool = False, model: int = 0) → str | None[source]

Export cavitiy (H) and surface (HA) points to PDB-formatted file with a variable (B; optional) in B-factor column, and hydropathy to PDB-formatted file in B-factor column at surface points (HA).

Parameters:

  • fn (str | pathlib.Path | None) – A path to PDB file for writing cavities. If None, return a raw string with the PDB-formatted file.

  • 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.

  • surface (numpy.ndarray, optional) –

    Surface points in the 3D grid (surface[nx][ny][nz]). If None, surface is a numpy.zeros array with same shape of cavities. 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.

  • vertices (numpy.ndarray | list[list[float]]) – A numpy.ndarray or a list with xyz vertices coordinates (origin, X-axis, Y-axis, Z-axis).

  • step (float | int, optional) – Grid spacing (A), by default 0.6.

  • B (numpy.ndarray | None, optional) – A numpy.ndarray with values to be mapped on B-factor column in cavity points (B[nx][ny][nz]), by default None.

  • Q (numpy.ndarray | None, optional) – A numpy.ndarray with hydrophobicity scale values to be mapped on B-factor column in surface points (Q[nx][ny][nz]), by default None.

  • selection (list[int] | list[str] | None, optional) – A list of integer labels or a list of cavity names to be selected, by default None.

  • nthreads (int | None, optional) – Number of threads, by default None. If None, the number of threads is os.cpu_count() - 1.

  • append (bool, optional) – Whether to append cavities to the PDB file, by default False.

  • model (int, optional) – Model number, by default 0.

Returns:

A raw string with the PDB-formatted file.

Return type:

str | None

Raises:

  • TypeError – “fn must be a string, a pathlib.Path or None. If None, return a raw string with the PDB-formatted file.”

  • TypeError – cavities must be a numpy.ndarray.

  • ValueError – cavities has the incorrect shape. It must be (nx, ny, nz).

  • TypeError – surface must be a numpy.ndarray.

  • ValueError – surface has the incorrect shape. It must be (nx, ny, nz).

  • TypeError – vertices must be a list or a numpy.ndarray.

  • ValueError – vertices has incorrect shape. It must be (4, 3).

  • TypeError – step must be a positive real number.

  • ValueError – step must be a positive real number.

  • TypeError – B must be a numpy.ndarray.

  • ValueError – B has the incorrect shape. It must be (nx, ny, nz).

  • TypeError – Q must be a numpy.ndarray.

  • ValueError – Q has the incorrect shape. It must be (nx, ny, nz).

  • 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 – append must be a boolean.

  • TypeError – model must be a integer.

  • RuntimeError – User must define surface when not defining cavities.

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. After KZZ, the next cavity is Kaa, Kab, and so on. The naming convention supports up to 1352 cavities.

See also

detect, spatial, depth, hydropathy, write_results

Example

With the cavity and surface points identified and depth and hydrophobicity scale mapped in the 3D grid, we can:

  • Export cavity points

>>> from pyKVFinder import export
>>> export('cavity_wo_surface.pdb', cavities, None, vertices)

  • Export cavity and surface points

>>> export('cavities.pdb', cavities, surface, vertices)

  • Export cavity and surface points with depth mapped on them

>>> export('cavities_with_depth.pdb', cavities, surface, vertices, B=depths)

  • Export surface points with hydrophobicity_scale mapped on them

>>> export('cavities_with_hydropathy.pdb', cavities, surface, vertices, Q=scales)

  • Export all

>>> export('cavities.pdb', cavities, surface, vertices, B=depths, Q=scales)

  • Export to a raw string

>>> string = export(None, cavities, surface, vertices, B=depths, Q=scales)
>>> print(string)
ATOM     1  H   KAA     0       0.000   0.000   0.000  1.00  0.00
...
ATOM  1000  H   KAA     0       0.000   0.000   0.000  1.00  0.00