Author: | Oliver Beckstein |
---|---|
Year: | 2011 |
Copyright: | GNU Public License v3 |
The module provides classes and functions to represent volumetric data, in particular densities.
As an input a trajectory is required that
To generate the density of water molecules around a protein:
u = Universe(PSF,DCD)
D = density_from_Universe(u, delta=1.0, atomselection="name OH2")
D.convert_density('TIP3P')
D.export("water.dx")
The positions of all water oxygens are histogrammed on a grid with spacing delta = 1 A. Initially the density is measured in 1/A**3. With the Density.convert_density() method, the units of measurement are changed. In the example we are now measuring the density relative to the literature value of the TIP3P water model at ambient conditions (see the values in MDAnalysis.core.units.water for details). Finally, the density is writte as an OpenDX compatible file that can be read in VMD or PyMOL.
See Density for details. In particular, the density is stored as a NumPy array in Density.grid, which can be processed in any manner.
Bases: gridData.core.Grid
Class representing a density on a regular cartesian grid.
The data (Density.grid) can be manipulated as a standard numpy array. Changes can be saved to a file using the Density.save() method. The grid can be restored using the Density.load() method or by supplying the filename to the constructor.
The attribute Density.metadata holds a user-defined dictionary that can be used to annotate the data. It is also saved with Density.save().
The Density.export() method always exports a 3D object (written in such a way to be readable in VMD and PyMOL), the rest should work for an array of any dimension.
If the input histogram consists of counts per cell then the Density.make_density() method converts the grid to a physical density. For a probability density, divide it by Density.grid.sum() or use normed=True right away in histogramdd().
The user should set the parameters keyword (see docs for the constructor); in particular, if the data are already a density, one must set isDensity == True because there is no reliable way to detect if data represent counts or a density. As a special convenience, if data are read from a file and the user has not set isDensity then it is assumed that the data are in fact a density.
Typical use:
From a histogram (i.e. counts on a grid):
h,edges = numpy.histogramdd(...)
D = Density(h,edges)
D.make_density()
From a saved density file (e.g. in OpenDX format), where the lengths are in Angstrom and the density in 1/A**3:
D = Density("density.dx")
From a saved density file (e.g. in OpenDX format), where the lengths are in Angstrom and the density is measured relative to the density of water at ambient conditions:
D = Density("density.dx", units={'density': 'water'})
From a saved histogram (less common, but in order to demonstrate the parameters keyword) where the lengths are in nm:
D = Density("counts.dx", parameters={'isDensity': False}, units={'length': 'nm'})
D.make_density()
D.convert_length('Angstrom^{-3}')
D.convert_density('water')
After the final step, D will contain a density on a grid measured in Angstrom, with the density values itself measured relative to the density of water.
Density objects can be algebraically manipulated (added, subtracted, multiplied, ...) but there are no sanity checks in place to make sure that units, metadata, etc are compatible!
Note
It is suggested to construct the Grid object from a histogram, to supply the appropriate length unit, and to use Density.make_density() to obtain a density. This ensures that the length- and the density unit correspond to each other.
See also
Grid which is the base class of Density. (Grid has been imported from gridData.Grid which is part of GridDataFormats).
Create a Density from data.
Arguments : |
|
---|
Returns the coordinates of the centers of all grid cells as an iterator.
Check if other can be used in an arithmetic operation.
Raises : | TypeError if not compatible. |
---|
Convert the density to the physical units given by unit.
Grid.convert_to(unit)
unit can be one of the following:
name | description of the unit |
---|---|
Angstrom^{-3} | particles/A**3 |
nm^{-3} | particles/nm**3 |
SPC | density of SPC water at standard conditions |
TIP3P | ... see MDAnalysis.core.units.water |
TIP4P | ... see MDAnalysis.core.units.water |
water | density of real water at standard conditions (0.997 g/cm**3) |
Molar | mol/l |
Note:
- This only works if the initial length unit is provided.
- Conversions always go back to unity so there can be rounding and floating point artifacts for multiple conversions.
There may be some undesirable cross-interactions with convert_length()...
Convert Grid object to the new unit.
Grid.convert_length(<unit>)
Keywords : |
|
---|
This changes the edges but will not change the density; it is the user’s responsibility to supply the appropriate unit if the Grid object is constructed from a density. It is suggested to start from a histogram and a length unit and use make_density().
export density to file using the given format; use ‘dx’ for visualization.
export(filename=<filename>,format=<format>)
The format can also be deduced from the suffix of the filename though the format keyword takes precedence.
The default format for export() is ‘dx’.
Only implemented formats:
dx OpenDX pickle pickle (use Grid.load(filename) to restore); Grid.save()
is simpler than export(format=’python’).
B-spline function over the data grid(x,y,z).
interpolated([x1,x2,...],[y1,y2,...],[z1,z2,...]) -> F[x1,y1,z1],F[x2,y2,z2],...
The interpolation order is set in Grid.interpolation_spline_order.
The interpolated function is computed once and is cached for better performance. Whenever interpolation_spline_order is modified, Grid.interpolated() is recomputed.
The value for unknown data is set in Grid.interpolation_cval (TODO: also recompute when interpolation_cval value is changed.)
>>> XX,YY,ZZ = numpy.mgrid[40:75:0.5, 96:150:0.5, 20:50:0.5]
>>> FF = interpolated(XX,YY,ZZ)
Load saved (pickled or dx) grid and edges from <filename>.pickle
Grid.load(<filename>.pickle) Grid.load(<filename>.dx)
The load() method calls the class’s constructor method and completely resets all values, based on the loaded data.
Convert the grid (a histogram, counts in a cell) to a density (counts/volume).
make_density()
If this is already a density, then a warning is issued and nothing is done.
Resample data to a new grid with edges edges.
resample(edges) –> Grid
or
resample(otherGrid) –> Grid
The order of the interpolation is set by Grid.interpolation_spline_order.
Resample to a new regular grid with factor*oldN cells along each dimension.
Save a grid object to <filename>.pickle
Grid.save(filename)
Internally, this calls Grid.export(filename,format=”python”). A grid can be regenerated from the saved data with
g = Grid(filename=<filename>)
Create a density grid from a MDAnalysis.Universe object.
density_from_Universe(universe, delta=1.0, atomselection=’name OH2’, ...) –> density
Arguments : |
|
---|---|
Keywords : |
|
Returns : |
Create a density grid from a trajectory.
density_from_trajectory(PSF, DCD, delta=1.0, atomselection=’name OH2’, ...) –> density
or
density_from_trajectory(PDB, XTC, delta=1.0, atomselection=’name OH2’, ...) –> density
Arguments : |
|
---|---|
Keywords : |
|
Returns : |
See also
docs for density_from_Universe() (defaults for kwargs are defined there).
Create a density from a single frame PDB.
Typical use is to make a density from the crystal water molecules. The density is created from isotropic gaussians centered at each selected atoms. If B-factors are present in the file then they are used to calculate the width of the gaussian.
Using the sigma keyword, one can override this choice and prescribe a gaussian width for all atoms (in Angstrom), which is calculated as
B = [(8*PI**2)/3] * (RMSF)**2
Note
The current implementation is painfully slow.
See also
Arguments : |
|
---|---|
Keywords : |
|
Returns : | a Density object with a density measured relative to the water density at standard conditions |
Atomic root mean square fluctuation (in Angstrom) from the crystallographic B-factor
B = [(8*PI**2)/3] * (RMSF)**2
Willis & Pryor, Thermal vibrations in crystallography, Cambridge Univ. Press, 1975
Create a density grid from a pdb file using MDAnalysis.
dens = BfactorDensityCreator(pdb,...).Density()
The main purpose of this function is to convert crystal waters in an X-ray structure into a density so that one can compare the experimental density with the one from molecular dynamics trajectories. Because a pdb is a single snapshot, the density is estimated by placing Gaussians of width sigma at the position of all selected atoms.
Sigma can be fixed or taken from the B-factor field, in which case sigma is taken as sqrt(3.*B/8.)/pi (see BFactor2RMSF()).
Construct the density from psf and pdb and the atomselection.
- DC = BfactorDensityCreator(pdb, delta=<delta>, atomselection=<MDAnalysis selection>,
- metadata=<dict>, padding=2, sigma=None)
density = DC.Density()
Arguments : |
|
---|
For assigning X-ray waters to MD densities one might have to use a sigma of about 0.5 A to obtain a well-defined and resolved x-ray water density that can be easily matched to a broader density distribution.
Returns a Density object.
Class to manage a multidimensional grid object.
The export(format=’dx’) method always exports a 3D object, the rest should work for an array of any dimension.
The grid (Grid.grid) can be manipulated as a standard numpy array.
The attribute Grid.metadata holds a user-defined dictionary that can be used to annotate the data. It is saved with save().
Create a Grid object from data.
Arguments : |
|
---|
Returns the coordinates of the centers of all grid cells as an iterator.
Check if other can be used in an arithmetic operation.
Raises : | TypeError if not compatible. |
---|
export density to file using the given format; use ‘dx’ for visualization.
export(filename=<filename>,format=<format>)
The format can also be deduced from the suffix of the filename though the format keyword takes precedence.
The default format for export() is ‘dx’.
Only implemented formats:
dx OpenDX pickle pickle (use Grid.load(filename) to restore); Grid.save()
is simpler than export(format=’python’).
B-spline function over the data grid(x,y,z).
interpolated([x1,x2,...],[y1,y2,...],[z1,z2,...]) -> F[x1,y1,z1],F[x2,y2,z2],...
The interpolation order is set in Grid.interpolation_spline_order.
The interpolated function is computed once and is cached for better performance. Whenever interpolation_spline_order is modified, Grid.interpolated() is recomputed.
The value for unknown data is set in Grid.interpolation_cval (TODO: also recompute when interpolation_cval value is changed.)
>>> XX,YY,ZZ = numpy.mgrid[40:75:0.5, 96:150:0.5, 20:50:0.5]
>>> FF = interpolated(XX,YY,ZZ)
Load saved (pickled or dx) grid and edges from <filename>.pickle
Grid.load(<filename>.pickle) Grid.load(<filename>.dx)
The load() method calls the class’s constructor method and completely resets all values, based on the loaded data.
Resample data to a new grid with edges edges.
resample(edges) –> Grid
or
resample(otherGrid) –> Grid
The order of the interpolation is set by Grid.interpolation_spline_order.
Resample to a new regular grid with factor*oldN cells along each dimension.
Save a grid object to <filename>.pickle
Grid.save(filename)
Internally, this calls Grid.export(filename,format=”python”). A grid can be regenerated from the saved data with
g = Grid(filename=<filename>)