moleculekit.volume module#

Volumetric data: densities, maps and grids, drawn alongside molecules.

A Volume is the non-atomic half of a figure: an electron density, a docking grid, an electrostatic potential. It carries its own representations the way a Molecule carries mol.reps, so a scene of a protein and a density is a list of two objects rather than one merged thing.

moleculekit.volume.DEFAULT_VOLUME_COLOR = '#3465a4'#

Isosurface colour used when a representation names none.

class moleculekit.volume.Volume(filename=None, data=None, origin=None, spacing=None)#

Bases: object

Volumetric data on a regular grid, drawable beside molecules.

Parameters:

  • filename (str or None) – A .cube or rDock .grd file. None builds an empty Volume to fill in from arrays.

  • data (numpy.ndarray or None) – A 3D array, when building from memory rather than a file.

  • origin (array_like or None) – Cartesian coordinates of the first grid point, in Angstrom, which is what a cube file stores.

  • spacing (array_like or None) – Grid step along x, y and z, in Angstrom.

Examples

>>> vol = Volume("density.cube")
>>> vol.reps.add(isovalue=0.05, color="#66ccff", opacity=0.6)
>>> render([mol, vol], "figure.png")
read(filename)#

Read volumetric data from a file.

Parameters:

filename (str) – A .cube or rDock .grd file.

Raises:

RuntimeError – If the extension is not one this can read, or if a .grd file describes a grid this cannot represent.

property shape#

The grid dimensions.

suggest_isovalue(quantile=0.999)#

A value worth drawing a surface at, taken from the data.

A density’s useful contour depends on its units and normalisation, so rather than guess a constant this picks a high quantile: the surface then encloses the densest part of the map whatever the scale.

Parameters:

quantile (float) – Fraction of grid points to leave outside the surface.

Returns:

isovalue – The suggested value.

Return type:

float

to_ccp4()#

Serialise to a CCP4/MRC map, the format the viewer parses.

Returns:

ccp4 – The volume as a CCP4 map file’s contents.

Return type:

bytes

to_cube()#

Serialise to Gaussian cube text.

Returns:

cube – The volume as a cube file’s contents.

Return type:

str

class moleculekit.volume.VolumeRepresentations(vol)#

Bases: object

The isosurfaces drawn for a Volume.

Mirrors moleculekit.representations.Representations, so a volume is styled the same way a molecule is.

Parameters:

vol (Volume) – The volume these representations belong to.

Examples

>>> vol = Volume("density.cube")
>>> vol.reps.add(isovalue=0.05, color="#66ccff", opacity=0.6)
>>> vol.reps.add(isovalue=0.15, color="#ff6600")
add(isovalue=None, color=None, opacity=None, wireframe=False, visibility=None)#

Add an isosurface.

Parameters:

  • isovalue (float) – The value to draw the surface at, in the units of the data. None picks a value from the data itself, see Volume.suggest_isovalue().

  • color (str) – SVG colour name or #rrggbb.

  • opacity (float) – 0 is fully transparent, 1 fully opaque.

  • wireframe (bool) – Draw a mesh rather than a solid surface.

  • visibility (bool) – Whether to draw it. A hidden surface keeps its place in the list, so it can be switched back on by index.

remove(index=None)#

Remove one isosurface, or all of them.

Parameters:

index (int | None) – Which to remove. None removes all.

update(index, isovalue=None, color=None, opacity=None, wireframe=None, visibility=None)#

Change one isosurface in place, leaving the rest of it alone.

Its position in the list is kept, so it stays addressable by the same index. Only what is given is changed.

Parameters:

  • index (int) – Which isosurface to change.

  • isovalue (float) – New value to draw the surface at.

  • color (str) – New colour.

  • opacity (float) – New opacity.

  • wireframe (bool) – Whether to draw a mesh rather than a solid surface.

  • visibility (bool) – Whether to draw it at all.