pyKVFinder.Molecule

class pyKVFinder.Molecule(molecule: str | Path, radii: str | Path | Dict[str, Any] | None = None, model: int | None = None, nthreads: int | None = None, verbose: bool = False)

A class for representing molecular structures.

Parameters:

• molecule (Union[str, pathlib.Path]) – A file path to the molecule in either PDB or XYZ format

• radii (Union[str, pathlib.Path, Dict[str, Any]], optional) – A file path to a van der Waals radii file or a dictionary of VDW radii, by default None. If None, apply the built-in van der Waals radii file: vdw.dat.

• model (int, optional) – The model number of a multi-model PDB file, by default None. If None, keep atoms from all models.

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

_atomic

A numpy array with atomic data (residue number, chain, residue name, atom name, xyz coordinates and radius) for each atom.

Type:

numpy.ndarray

_dim

Grid dimensions.

Type:

tuple

_grid

Molecule points in the 3D grid (grid[nx][ny][nz]). Grid array has integer labels in each position, that are:

• 0: molecule points;

• 1: solvent points.

Type:

numpy.ndarray

_molecule

A file path to the molecule in either PDB or XYZ format.

Type:

Union[str, pathlib.Path]

_padding

The length to add to each direction of the 3D grid.

Type:

float

_probe

Spherical probe size to define the molecular surface based on a molecular representation.

Type:

float

_radii

A dictionary containing radii values, by default None.

Type:

Dict[str, Any]

_representation

Molecular surface representation. Keywords options are vdW (van der Waals surface), SES (Solvent Excluded Surface) or SAS (Solvent Accessible Surface), by default SES.

Type:

str, optional

_rotation

A numpy.ndarray with sine and cossine of the grid rotation angles (sina, cosa, sinb, cosb).

Type:

numpy.ndarray

_step

Grid spacing (A).

Type:

float

_vertices

A numpy.ndarray or a list with xyz vertices coordinates (origin, X-axis, Y-axis, Z-axis).

Type:

numpy.ndarray

nthreads

Number of threads for parallel processing.

Type:

int

verbose

Whether to print extra information to standard output.

Type:

bool

Note

The van der Waals radii file defines the radius values for each atom by residue and when not defined, it uses a generic value based on the atom type. The function by default loads the built-in van der Waals radii file: vdw.dat.

See also

read_vdw

Example

The Molecule class loads the target molecular structure (ClO4) into pyKVFinder. class.

>>> import os
>>> from pyKVFinder import Molecule
>>> pdb = os.path.join(os.path.dirname(pyKVFinder.__file__), 'data', 'tests', 'ClO4.pdb')
>>> molecule = Molecule(pdb)
>>> molecule
>>> <pyKVFinder.main.Molecule object at 0x7f5ddacf2230>

The van der Waals radii can be define by:

• creating a Python dictionary:

>>> # PyMOL (v2.5.0) vdW radii values
>>> vdw = {'GEN': {'CL': 1.75, 'O': 1.52}}
>>> molecule = Molecule(pdb, radii=vdw)
>>> molecule.radii
{'GEN': {'CL': 1.75, 'O': 1.52}}

• specifying a .dat file following template of van der Waals radii file.

>>> from pyKVFinder import read_vdw
>>> # ChimeraX vdW radii values
>>> with open('vdw.dat', 'w') as f:
...     f.write('>GEN\nCL\t\t1.98\nO\t\t1.46\n')
>>> vdw = read_vdw('vdw.dat')
>>> molecule = Molecule(pdb, radii=vdw)
>>> molecule.radii
{'GEN': {'CL': 1.98, 'O': 1.46}}

property atomic: ndarray

Get _atomic attribute.

property dim: Tuple[int, int, int]

Get _dim attribute

export(fn: str | Path = 'molecule.pdb') → None

Export molecule points (H) to a PDB-formatted file.

Parameters:

fn (Union[str, pathlib.Path], optional) – A file path to the molecular volume in the grid-based rerpesentation in PDB format, by default “molecule.pdb”.

Raises:

TypeError – fn must be a string or a pathlib.Path.

Example

With the molecular surface modelled by Molecule.vdw() or Molecule.surface(), the modelled molecule in the 3D grid can be exported to a PDB-formatted file by running:

>>> molecule.export('model.pdb')

property grid: ndarray

Get _grid attribute.

property molecule: str | Path

Get _molecule attribute.

property nx: int

Get grid units in X-axis.

property ny: int

Get grid units in Y-axis.

property nz: int

Get grid units in Z-axis.

property p1: ndarray

Get origin of the 3D grid.

property p2: ndarray

Get X-axis max of the 3D grid.

property p3: ndarray

Get Y-axis max of the 3D grid.

property p4: ndarray

Get Z-axis max of the 3D grid.

property padding: float

Get _padding attribute.

preview(**kwargs) → None

Preview the molecular surface in the 3D grid.

Example

With the molecular surface modelled by Molecule.vdw() or Molecule.surface(), the modelled molecule in the 3D grid can be previewed by running:

>>> molecule.preview()

property probe: float

Get _probe attribute.

property radii: Dict[str, Any]

Get _radii attribute.

property representation: str

Get _representation attribute.

property rotation: ndarray

Get _rotation attribute.

property step: float

Get _step attribute.

surface(step: float = 0.6, probe: float = 1.4, surface: str = 'SES', padding: float | None = None) → None

Fill the 3D grid with the molecule as the van der Waals surface representation.

Parameters:

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

• probe (float, optional) – Spherical probe size to define the molecular surface based on a molecular representation, by default 1.4.

• surface (str, optional) – Molecular surface representation. Keywords options are vdW (van der Waals surface), SES (Solvent Excluded Surface) or SAS (Solvent Accessible Surface), by default “SES”.

• padding (float, optional) – The length to add to each direction of the 3D grid, by default None. If None, automatically define the length based on molecule coordinates, probe size, grid spacing and atom radii.

Raises:

• TypeError – step must be a positive real number.

• ValueError – step must be a positive real number.

• TypeError – probe_out must be a positive real number.

• ValueError – probe_out must be a positive real number.

Example

The Molecule.surface() method takes the grid spacing, the spherical probe size to model the surface, the surface representation and returns a NumPy array with the molecule points representing the SES in the 3D grid.

The molecular surface can be modelled as:

• Solvent Excluded Surface (SES):

>>> # Surface Representation: SES
>>> surface = 'SES'
>>> # Grid Spacing (step): 0.1
>>> step = 0.1
>>> # Spherical Probe (probe): 1.4
>>> probe = 1.4
>>> molecule.surface(step=step, probe=probe, surface=surface)
>>> molecule.grid
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)

The molecular surface can be modelled as:

• Solvent Accessible Surface (SAS):

>>> # Surface Representation: SAS
>>> surface = 'SAS'
>>> # Grid Spacing (step): 0.1
>>> step = 0.1
>>> # Spherical Probe (probe): 1.4
>>> probe = 1.4
>>> molecule.surface(step=step, probe=probe, surface=surface)
>>> molecule.grid
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)

vdw(step: float = 0.6, padding: float | None = None) → None

Fill the 3D grid with the molecule as the van der Waals surface representation.

Parameters:

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

• padding (float, optional) – The length to add to each direction of the 3D grid, by default None. If None, automatically define the length based on molecule coordinates, probe size, grid spacing and atom radii.

Raises:

• TypeError – step must be a positive real number.

• ValueError – step must be a positive real number.

Example

The Molecule.vdw() method takes a grid spacing and returns a NumPy array with the molecule points representing the vdW surface in the 3D grid.

>>> # Grid Spacing (step): 0.1
>>> step = 0.1
>>> molecule.vdw(step=step)
>>> molecule.grid
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)

property vertices: ndarray

Get _vertices attribute.

volume() → float

Estimate the volume of the molecule based on the molecular surface representation, ie, vdW, SES or SAS representations.

Returns:

volume – Molecular volume (A³).

Return type:

float

Example

With the molecular surface modelled by Molecule.vdw() or Molecule.surface(), the volume can be estimated by running:

>>> molecule.volume()
90.8

property xyzr: ndarray

Get xyz coordinates and radius of molecule atoms.