moleculekit.tools.voxeldescriptors module#

moleculekit.tools.voxeldescriptors.getCenters(mol=None, buffer=0, boxsize=None, center=None, voxelsize=1)#

Get a set of centers for voxelization.

Parameters:

  • mol (Molecule | None) – Use this together with the buffer option.

  • buffer (float) – The buffer space to add to the bounding box. This adds zeros to the grid around the protein so that properties which are at the edge of the box can be found in the center of one. Should be usually set to localimagesize/2.

  • boxsize (list | None) – If this argument is None, the function will calculate the bounding box of the molecule, add to that the buffer argument to expand the bounding box in all dimensions and discretize it into voxels of voxelsize xyz length. In this case, the center argument is ignored. If a list of [x, y, z] lengths is given in Angstrom, it will create a box of those dimensions centered around the center argument.

  • center (list | None) – The [x, y, z] coordinates of the center. Use this only in combination with the boxsize argument.

  • voxelsize (float) – The voxel size in A

Returns:

  • centers (numpy.ndarray) – A (nvoxels, 3) array with the xyz coordinates of the center of each voxel.

  • nvoxels (numpy.ndarray) – A (3,) array with the number of voxels along the x, y and z dimensions.

moleculekit.tools.voxeldescriptors.getChannels(mol, aromaticNitrogen=False, version=2, validitychecks=True)#

Computes the voxelization channels (atom property descriptors) of a molecule.

For each atom it computes a set of property channels (hydrophobic, aromatic, hydrogen-bond acceptor, hydrogen-bond donor, positive/negative ionizable, metal and occupancy). Boolean channels are scaled by the van der Waals radius of each atom.

Parameters:

  • mol (Molecule) – The molecule for which to compute the channels.

  • aromaticNitrogen (bool) – If True, treats aromatic nitrogens as a separate atom type.

  • version (int) – The version of the atom typing to use. Version 1 uses PDBQT atom type properties directly, version 2 recomputes PDBQT atom types and charges and derives features from them.

  • validitychecks (bool) – If True, performs validity checks on the molecule before atom typing.

Returns:

  • channels (numpy.ndarray) – A (natoms, nchannels) array of the per-atom property channels.

  • mol (moleculekit.molecule.Molecule or SmallMol object) – A copy of the input molecule (with atom types and charges assigned for version 2).

moleculekit.tools.voxeldescriptors.getVoxelDescriptors(mol, boxsize=None, voxelsize=1, buffer=0, center=None, usercenters=None, userchannels=None, usercoords=None, aromaticNitrogen=False, method='C', version=2, validitychecks=True)#

Calculate descriptors of atom properties for voxels in a grid bounding the Molecule object.

Parameters:

  • mol (Molecule) – A molecule

  • boxsize (list | None) – If this argument is None, the function will calculate the bounding box of the molecule, add to that the buffer argument to expand the bounding box in all dimensions and discretize it into voxels of voxelsize xyz length. In this case, the center argument is ignored. If a list of [x, y, z] lengths is given in Angstrom, it will create a box of those dimensions centered around the center argument.

  • voxelsize (float) – The voxel size in A

  • buffer (float) – The buffer space to add to the bounding box. This adds zeros to the grid around the protein so that properties which are at the edge of the box can be found in the center of one. Should be usually set to localimagesize/2.

  • center (list | None) – The [x, y, z] coordinates of the center. Use this only in combination with the boxsize argument.

  • usercenters (ndarray | None) – A 2D array specifying the centers of the voxels. If None is given, it will calculate the centers from the above options

  • userchannels (ndarray | None) – A 2D array of size (mol.numAtoms, nchannels) where nchannels is the number of channels we want to have. Each column i then has True (or a float) in the rows of the atoms which belong to channel i and False (or 0) otherwise. Such boolean arrays can be obtained for example by using mol.atomselect. If the array is boolean, each atom will get assigned its VdW radius. If the array is float, these floats will be used as the corresponding atom radii. Make sure the numpy array is of dtype=bool if passing boolean values. If no channels are given, the default (‘hydrophobic’, ‘aromatic’, ‘hbond_acceptor’, ‘hbond_donor’, ‘positive_ionizable’, ‘negative_ionizable’, ‘metal’, ‘occupancies’) channels will be used.

  • usercoords (ndarray | None) – A numpy array containing the molecule coordinates. You can use this with userchannels and usercenters instead of passing a mol object (set it to None if that’s the case).

  • aromaticNitrogen (bool) – Set to True if you want nitrogens in aromatic rings to be added to the aromatic channel.

  • method (str) – The method used to compute the voxel occupancies.

  • version (int) – Setting version to 1 will use the old voxelization code which requires you to first obtain pdbqt atom types for the protein. By default it uses version 2 which does the atom typing internally.

  • validitychecks (bool) – Set to False to disable validity checks for atomtyping. This improves performance but only use it if you are sure you have properly prepared your molecules.

Returns:

  • features (numpy.ndarray) – A 2D array of size (centers, channels) containing the effect of each channel in the voxel with that center.

  • centers (numpy.ndarray) – A list of the centers of all boxes

  • N (numpy.ndarray) – Is returned only when no user centers are passed. It corresponds to the number of centers in each of the x,y,z dimensions

Examples

>>> mol = Molecule('3PTB')
>>> mol.filter('protein')
>>> features, centers, N = getVoxelDescriptors(mol, buffer=8)
>>> # Features can be reshaped to a 4D array (3D for each grid center in xyz, 1D for the properties) like this:
>>> features = features.reshape(N[0], N[1], N[2], features.shape[1])
>>> # The user can provide his own centers
>>> features, centers = getVoxelDescriptors(mol, usercenters=[[0, 0, 0], [16, 24, -5]])
moleculekit.tools.voxeldescriptors.rotateCoordinates(coords, rotations, center)#

Rotates a set of coordinates around a center point.

The rotation is applied sequentially around the x, y and z axes by the angles given in rotations.

Parameters:

  • coords (ndarray) – The coordinates to rotate, with shape (natoms, 3).

  • rotations (list) – The rotation angles in radians around the x, y and z axes as a list of three values [rx, ry, rz].

  • center (list) – The [x, y, z] coordinates of the center point around which to rotate.

Returns:

coords – The rotated coordinates.

Return type:

ndarray

moleculekit.tools.voxeldescriptors.viewVoxelFeatures(features, centers, nvoxels, voxelsize=None, draw='wireframe', featurenames=('hydrophobic', 'aromatic', 'hbond_acceptor', 'hbond_donor', 'positive_ionizable', 'negative_ionizable', 'metal', 'occupancies'))#

Visualize in VMD the voxel features produced by getVoxelDescriptors.

Parameters:

  • features (ndarray) – An array of (n_centers, n_features) shape containing the voxel features of each center

  • centers (ndarray) – An array of (n_centers, 3) shape containing the coordinates of each voxel center

  • nvoxels (ndarray) – An array of (3,) shape containing the number of voxels in each X, Y, Z dimension

  • voxelsize (ndarray | None) – An array of (3,) shape containing the voxel size in each X, Y, Z dimension. If None it is inferred from the centers.

  • draw (str) – The drawing method passed to VMD for the isosurfaces.

  • featurenames (list) – The names of the features to visualize.

Example

>>> feats, centers, N = getVoxelDescriptors(mol)
>>> viewVoxelFeatures(feats, centers, N)