map module

3D maps (electron density, coulombic potential...).

Module author: Michael S. Chapman <chapmami@ohsu.edu>

Authors:

Michael S. Chapman <chapmami@ohsu.edu>,

Oregon Health & Science University
Version:

0.5, March 23, 2016

Changed in version 0.5.1: 8/11/15 Forgives missing Scale/Offset w/ warning.

Changed in version 0.5.0: 2/17/15 Maps written in Xplor/CNS format.

Changed in version 0.5.0: 2/13/15 Xplor/CNS map support for Scale/Offset (aka RAve, RSigma).

Changed in version 0.1.0: 8/13/10 Started

class map.Arguments(imports=[], main=False, *args, **kwargs)

Bases: argparser.ArgumentParser

Argument parser for optimization target function.

Parameters:
  • imports ((list of) ArgumentParser method(s)) – method(s) adding arguments to ArgumentParser instance. (Alternative to ArgumentParser parents w/ better maintained groups.)
  • main (bool) – Parser for main program (i.e. not listed within an ArgumentParser parents argument). Adds default program information.
static export()

Adding options used in both stand-alone and imported modes.

class map.Map

Bases: crystallography.MapOrthogonal

Container for general 3D density map and its properties.

Class allows great freedom in the choice of grid in terms of origin, grid steps and orientation. This means that any arbitrary volume (including negative coordinates, and those well outside the unit cell) can be represented with positive indices in the map array. Alignment with a crystal unit cell is possible, but not required. There is no implicit support for symmetry or periodicity.

Variables:density – in a row-major (C-like) array with slow, medium & fast axes density[s,m,f].
local_view(about=(3.0, 4.0, 5.0), extent=(1, 5, 5), verbose=True)

Reports density of map near “about”.

Parameters:
  • about (tuple or array (3)) – Orthogonal Angstrom coordinates.
  • extent (tuple (3)) – Size of the viewing box.
  • verbose (bool) – print the density view.
Returns:

(density-view, index of 1st corner, index of local maximum)
Return type:

ndarray(type=float, shape=extent), tuple(3), tuple(3)
zeros_like()

Creates a new empty map with the same gridding as self.

Returns:a deepcopy of map self on the same grid as self.
Return type:class Map
class map.ReadMap(filename, permutation='ZYX', magnification=1.0, new_cell=None, normalize=True, verbose=False)

Bases: map.Map

Container for a map read from an external file.

Variables:
  • density – in a row-major (C-like) array with slow, medium & fast axes density[s,m,f].
  • header – documentation
  • abc_grid – ((a_cell, a_min, a_max), (b_cell, b_min, b_max), (c_cell, c_min, c_max)), containing, for each crystal axis, the number of grid spaces per unit cell, the first and last in the map.

Todo

check that it is not the number of points per unit cell

Variables:
  • permutation – eg (‘X’, ‘Y’, ‘Z’) required for xplor format.
  • unit_cell – (a, b, c, alpha, beta, gamma; Angstrom & degrees)
  • _magnification – cumulative magnification that has been applied.
  • scale – internal values of density are (file values) * scale + offset
  • offset – internal values of density are (file values) * scale + offset

Reads an external map into memory.

The header is parsed and stored in file-type specific attributes, such as self.abc_grids. Information is also converted into Map instance attributes that are universal across all map formats.

Parameters:
  • permutation (str) – which axes align with the (slow, medium, fast) indices of the map array? Ignored for Xplor (as read from the map). Some other maps support different permutations (eg. ccp4), but bsoft does not appear to extract the information from the header.
  • magnification (float) – > 1.0 increase the object’s (EM) magnification by decreasing the map (pixel) dimensions, equivalent to reducing unit cell size.
  • new_cell (tuple(6 x float) or NoneType) – Unit cell parameters to use instead of map header. Use very carefully, as could affect map-model compatibility.
  • normalize (bool) – scale to mean of 0.0 and standard deviation of 1.0 x pixel volume
  • verbose (bool) – echo file name etc.
class Scale

Bases: object

Maintains relation: density values = (file values) * scale + offset

input(density, scale, offset)

Input new coefficients and overwrite density w/ scaled values

Parameters:
  • density (ndarray) – unscaled values directly from input file
  • scale (float) – density values to be first multiplied by this
  • offset (float) – this value then to be added
Return internal:
 
Rtype ndarray:
output(density, original_scale=True, magnification=None)

Output density, scaled by the input coefficients.

Parameters:
  • density (ndarray) – internally-saved density values
  • original_scale (bool) – put map back on scale approximately matching input, undoing normalization & scaling to model (if relevant).
  • magnification (float or NoneType) – rescale output to maintain the same total number of electrons through specified change in magnification.
Return out, scale, offset:
 

density ready for output & coefficients
Rtype ndarray, float, float:
 
ReadMap.allow_no_file = False
Var:allow limited functionality without a map file
ReadMap.from_bsoft(filename, verbose=True)

Read map from variety of file formats using bsoft.

Parameters:
  • filename (string) – file name
  • verbose (bool) – diagnostics printed
ReadMap.from_file(filename, verbose=True)

Read map from a variety of file types.

If no file name provided, prepare for a minimalist run.

Parameters:
  • filename (str) –
  • verbose (bool) –
Returns:

map read successfully.
Return type:

bool
ReadMap.from_xplor(filename, verbose=True)

Read from X-plor formatted file.

Parameters:
  • filename (string) – file name
  • verbose (bool) – diagnostics printed
ReadMap.magnify(magnification=1.0)

Change the (EM) magnification.

Parameters:magnification (float) – values > 1.0 increase the object’s (EM) magnification by decreasing the map (pixel) dimensions, equivalent to reducing unit cell size.
Returns:magnification
Return type:float
ReadMap.to_file(filename, verbose=True)

Write map to a variety of file types.

Parameters:
  • filename (str) –
  • verbose (bool) –
Returns:

map written successfully.
Return type:

bool
ReadMap.to_xplor(filename, autodoc=False, verbose=True)

Write to X-plor formatted file.

Parameters:
  • filename (str) – file name
  • autodoc (bool) – appends to header, file name, program, date, user
  • verbose (bool) – diagnostics printed

Error

The final line of xplor/cns map files is often mis-understood with some programs setting offset & scale (RAVE & RSIGMA in CNS) arbitrarily to 0.0 & 1.0 (incl. phenix), others ignoring the line. CNS xmread.f:312 shows stored density = input * RSIGMA + RAVE and CNS xmwrite.f:600 output density = (stored - RAVE) / RSIGMA. RAVE and RSIGMA should usually be the average, standard deviation for a crystal asymmetric unit, which is why they do not match the average & standard deviation for some arbitrary map volume. CNS print statements suggest that densities are on an absolute (e/Å3) scale, so RAVE, RSIGMA are converting between absolute and standard deviation scales. As our program supports maps of arbitrary volume, and does not consider asymmetric units, the appropriate values cannot be calculated. Values obtained from an input xplor/cns map will be used, optionally modified to maintain an absolute scale with changing magnification.