Density.from_structure#

classmethod Density.from_structure(filename_or_structure, shape=None, sampling_rate=array([1.]), origin=None, weight_type='atomic_weight', weight_type_args={}, chain=None, filter_by_elements=None, filter_by_residues=None)[source]#

Reads in an atomic structure and converts it into a Density instance.

Parameters:
filename_or_structurestr or tme.structure.Structure

Either tme.structure.Structure instance or path to structure file that can be read by tme.structure.Structure.from_file().

shapetuple of int, optional

Shape of the new Density instance. By default, computes the minimum 3D box holding all atoms.

sampling_ratefloat, optional

Sampling rate of the output array along each axis, in the same unit as the atoms in the structure. Defaults to one Ångstroms per axis unit.

origintuple of float, optional

Origin of the coordinate system. If provided, its expected to be in z, y, x form in the same unit as the atoms in the structure. By default, computes origin as distance between minimal coordinate and coordinate system origin.

weight_typestr, optional

Which weight should be given to individual atoms. For valid values see tme.structure.Structure.to_volume().

weight_type_argsdict, optional

Additional arguments for atom weight computation.

chainstr, optional

The chain that should be extracted from the structure. If multiple chains should be selected, they needto be a comma separated string, e.g. ‘A,B,CE’. If chain None, all chains are returned. Default is None.

filter_by_elementsset, optional

Set of atomic elements to keep. Default is all atoms.

filter_by_residuesset, optional

Set of residues to keep. Default is all residues.

Returns:
Density

Newly created Density instance.

References

[1]

Sorzano, Carlos et al (Mar. 2015). Fast and accurate conversion of atomic models into electron density maps. AIMS Biophysics 2, 8–20.

Examples

The following outlines the minimal parameters needed to read in an atomic structure and convert it into a Density instance. For specification on supported formats refer to tme.structure.Structure.from_file().

>>> path_to_structure = "/path/to/structure.cif"
>>> density = Density.from_structure(path_to_structure)

Density.from_structure() will automatically determine the appropriate density dimensions based on the structure. The origin will be computed as minimal distance required to move the closest atom of the structure to the coordinate system origin. Furthermore, all chains will be used and the atom densities will be represented by their atomic weight and accumulated on a per-voxel basis.

The following will read in chain A of an atomic structure and discretize it on a grid of dimension 100 x 100 x 100 using a sampling rate of 2.5 Angstrom per voxel.

>>> density = Density.from_structure(
>>>    filename_or_structure = path_to_structure,
>>>    shape = (100, 100, 100),
>>>    sampling_rate = 2.5,
>>>    chain = "A"
>>> )

We can restrict the generated Density instance to only contain specific elements like carbon and nitrogen:

>>> density = Density.from_structure(
>>>    filename_or_structure = path_to_structure,
>>>    filter_by_elements = {"C", "N"}
>>> )

or specified residues such as polar amino acids:

>>> density = Density.from_structure(
>>>    filename_or_structure = path_to_structure,
>>>    filter_by_residues = {"SER", "THR", "CYS", "ASN", "GLN", "TYR"}
>>> )

In addtion, Density.from_structure() supports a variety of methods to convert atoms into densities, such as Gaussians

>>> density = Density.from_structure(
>>>    filename_or_structure = path_to_structure,
>>>    weight_type = "gaussian",
>>>    weight_type_args={"resolution": 20}
>>> )

experimentally determined scattering factors

>>> density = Density.from_structure(
>>>    filename_or_structure = path_to_structure,
>>>    weight_type = "scattering_factors",
>>>    weight_type_args={"source": "dt1969"}
>>> )

and their lowpass filtered representation introduced in [1]:

>>> density = Density.from_structure(
>>>    filename_or_structure = path_to_structure,
>>>    weight_type = "lowpass_scattering_factors",
>>>    weight_type_args={"source": "dt1969"}
>>> )