Usage:
measure property arguments

The measure command performs various calculations and sends results to the Reply Log. Possible values of property:

• area - calculate total area of an existing surface
• buriedArea - calculate surface area buried between two sets of atoms
• center - calculate center of mass of map and/or atoms
• contactArea - report the area of one surface within a cutoff distance of another
• correlation - report correlation of two maps
• distance - report distances between atoms and surfaces
• fieldLines - display electric field lines for an electrostatic potential map
• inertia - calculate inertia ellipsoid
• mapStats - calculate map mean, standard deviation from the mean, and RMS deviation from zero
• mapSum - sum map values above a specified threshold
• mapValues - interpolate map values at atom positions, assign as an attribute
• pathLength - report the total length of specified bonds
• rotation - report transformation of one model relative to another
• spine - calculate a path along the center line of a segmentation region
• symmetry - identify map symmetry
• volume - calculate volume enclosed by an existing surface

See also: distance, angle, Structure Measurements

Calculate the total area of each specified surface piece by summing over its triangles. The surface pieces in a surface model can be specified collectively by model number, or individually by selection from the screen and using the word sel, selected, or picked. Like Measure Volume and Area, the calculation uses the full surface even if it is partly hidden by clipping or zoning.

Note that the solvent-excluded and solvent-accessible surface areas of a molecular surface are reported in the Reply Log when the surface is first shown.

See also: surface, volume

Calculate the surface area buried between two specified sets of atoms. A surface is calculated for each set of atoms separately (surfA, surfB) and for their combination (surfAB). The surfaces are not created or displayed, but calculated internally. The difference in total area between the separate and combined states is reported for each set, as well as the average over the two sets. Buried areas are reported for both solvent-excluded and solvent-accessible surfaces. Only the averages are sent to the status line, but full results can be viewed in the Reply Log.

The atoms are grouped as specified regardless of surface category, and a set may span multiple models. Be careful to specify only the intended atoms, which could mean excluding or deleting beforehand any solvent, ligands, ions, and/or alternate location atoms. New Surfaces preference settings are not used; disjoint surfaces are always included, and the default probe radius and vertex density are 1.4 Šand 2.0/Ų, respectively.

Atoms are assigned the attributes buriedSESArea (buried solvent-excluded surface area) and buriedSASArea (buried solvent-accessible surface area) with their individual contributions to the specified interface. These can be summed over selected atoms with Attribute Calculator, for example to determine the contribution from carbons only.

For surfaces without associated atomic coordinates, see measure contactArea. See also: surface, intersurf, Area/Volume from Web

Calculate the center of mass of each density map and/or set of atoms in spec. Map centers are reported in grid indices, atomic centers of mass in the atomic coordinate system. The level option indicates using only map regions above contour-level. If mark is true, a marker will be placed at at each computed center, with radius marker-radius (default based on the contents of spec) and color marker-color (default gray). The marker-color can be any color name that specifies a single color. The marker model is opened as number model-number (default next unused number) with name model-name (default based on the contents of spec).

Report the surface area of one surface model (surf-model1) that lies within a cutoff distance of another surface model (surf-model2). Unless show false or offset 0 is specified, a new surface model is created to show the corresponding patch of surf-model1. The patch-color can be any color name that specifies a single color (default red). The new surface can be offset from the original surf-model1 by a distance d specified in physical units, typically Å (default 1.0). An offset of zero indicates recoloring surf-model1 to show the patch instead of creating a new surface model. The slab option overrides any offset and generates a slab of finite thickness instead of a single layer of surface. If a single value is supplied for the slab width, its inner and outer layers will be offset from surf-model1 by ±½(width). Alternatively, two values separated by a comma but no spaces can be used to specify the offsets of the two slab layers independently. Patch or slab offsets can be positive (outward) or negative (inward). Offsets affect only the display, not the area measurement, which is taken at the surf-model1 surface. The smooth option smooths the new surface but is generally not recommended. The optimize setting speeds up the calculation by disregarding far-apart portions of the surfaces. Currently, each model must contain only a single surface piece (it may be necessary to turn off surface capping, see sop cap).

For atomic structures, measure buriedArea may be more appropriate.

Calculate the correlation between two volume data sets (maps) in two ways:

	<u,v>
correlation =
	|u||v|

	<u–uave,v–vave>
correlation about mean =
	|u–uave||v–vave|

where vector u contains the values of the first map (map-model1) and u_ave is a vector with all components equal to the average of the components of u. Vectors v and v_ave are defined analogously for the second map (map-model2), except that the values are sampled at the grid point locations of the first map using trilinear interpolation.

• If aboveThreshold is true (default), the calculation will include only the grid points in the first map with values above its lowest contour level in Volume Viewer. Otherwise, all nonzero-valued grid points will be included.
• Specifying rotationAxis allows calculating the correlation multiple times for different orientations of the first map about an axis, described by an atom-spec of exactly two atoms (not necessarily bonded or in the same model) or one bond. If two atoms, the order of specification defines a handedness, and right-handed rotations are positive. If a bond, the handedness is not under user control. A bond can only be specified by selecting it and using the word selected, sel, or picked; any atoms also selected at the time will be ignored. The calculations are performed internally, without moving the map in the display.
• The angleRange arguments control how many correlation calculations should be performed and at what angles of the first map relative to its current position. By default, start = 0°, end = 360°, and step = 2°.
• If plot is true (default), the correlation values will be graphed in a separate window in addition to being tabulated in the Reply Log. Clicking and dragging in the plot window will show a vertical line and rotate the first map to the indicated angle.

See also: volume, molmap, fitmap, Fit to Segments

Report the closest distance between one set of atoms and/or surface pieces (atoms-surfs1) and another set (atoms-surfs2). Surface models and their pieces can be specified by model number or as a selection (details...). Atoms or surface pieces belonging to both sets are removed from the second set. Distances to surfaces are computed to the vertices of the surface mesh. All surface vertices are considered, even if hidden. Setting multiple to true gives the closest distance from each atom and surface piece in the first set to any in the second set. Lines depicting the distances can be displayed with show true, and the line-color can be any color name that specifies a single color (default cyan). The lines are generated as a surface model.

See also: distance, zonesel

Calculate electric field lines for one or more electrostatic potential maps. The lines option specifies the number N of field lines to generate per map (default 1000). The lines originate at grid points with potential magnitudes greater than startAbove cutoff value (default the highest contour level displayed for that map, or 10 if no contour levels are displayed) and are traced along the map gradient in steps of s (default 0.5) times the maximum grid spacing of the map (details...). The field lines are added as a new model with ID number model-number (default next unused number), and the line-color can be any color name that specifies a single color (default 0.7,0.7,0.7,1).

The lines will be shown as wires of lineWidth width (default 1) unless a radius for tube display is given and/or markers is set to true. In the case of markers true, tubes will be created as a marker set, with default radius 0.5 times the maximum grid spacing. In the case of markers false, the wires or tubes will be created as a surface model, with M facets (default 12) used to approximate the circular cross-section of tubes. Surface models can subsequently be colored by the potential using Electrostatic Surface Coloring or the command scolor.

If the command runs without error but no lines (or few) are visible, perhaps many short lines not protruding above the surface were generated. It may be helpful to use a higher startAbove value, and secondarily, to increase the total number of lines (details...).

Calculate the inertia ellipsoid for atom-spec, which could include atoms and/or surface pieces. Atoms are mass-weighted; surface pieces are treated as thin shells with mass proportional to surface area (details...). If both atoms and surfaces are specified, two separate ellipsoids are calculated (a combined calculation cannot be performed). Principal axes, lengths, moments, and center are reported for each ellipsoid, using the model coordinate system of the first atom or surface piece specified to define it. The vectors v1, v2, and v3 are the principal axes (longest to shortest). The lengths a, b, c are half-diameters along axes v1, v2, and v3, respectively. The moments r1, r2, and r3 are calculated as (inertia/mass)^½ about axes v1, v2, and v3, respectively. They can be considered effective radii; placing all of the mass at that distance from the center would reproduce the moment of inertia calculated for the structure around that axis.

The perChain option indicates whether to calculate a separate ellipsoid for each chain in atom-spec. If showEllipsoid is true (default), the ellipsoid(s) will be opened as a surface model. The ellipsoid-color can be any color name that specifies a single color. Otherwise, an ellipsoid will be colored to match the first atom or surface piece in its calculation.

See also: define axis, aniso, shape ellipsoid, Measure and Color Blobs, geometric objects

Calculate the mean, standard deviation (SD) from the mean, and root-mean-square (RMS) deviation from zero for each specified map. The step option indicates whether to use the full resolution of the data (step size 1, default) or a specified subsample (step size > 1). Step sizes must be integers. A step size of N indicates using every N^th point. If a single number is supplied, it is used along all three axes; if three numbers are supplied (separated by commas but not spaces), they are used along the X, Y, and Z axes, respectively. The subregion option indicates whether to use the full extents of the data (all, default) or a specified subregion. A subregion can be specified by:

• name previously assigned with volume (see nameRegion) or Volume Viewer (see Named regions)
• grid indices i1–i2 along the X axis, j1–j2 along the Y axis, and k1–k2 along the Z axis. Grid indices must be integers separated by commas but not spaces.

See also: Volume Mean, SD, RMS

For each specified map, sum values above a threshold level, if given (default is no threshold). The step and subregion options are as described for measure mapStats.

Interpolate map-model to obtain values at the positions of the atoms in atom-spec. The values will be assigned as an atom attribute, either named as indicated with name, or (default) derived by prepending “value_” to the name of map-model and replacing any non-alphanumeric characters with underscores. The report option indicates how many values should be reported in the Reply Log, those for the first N atoms (default 10, but 0 can be used) or all.

See also: Values at Atom Positions

Report the total length of the specified bonds, optionally as separate totals for bonds within different connected groups or models. This measurement applies to links between markers as well as to standard bonds.

Report the transformation of model2 relative to model1 as:

• a matrix in which the first three columns describe a rotation and the fourth describes a translation (performed after the rotation)
• an axis of rotation (a unit vector), point on the axis, rotation angle, and shift parallel to the axis

The transformation is expressed in the coordinate system of model1 unless a different coordinateSystem N (model ID number preceded by #) is specified. If showAxis is true (default), a marker set showing the axis as a rod will be opened as a separate model. The rod length equals the largest dimension of the bounding box of model1, and its diameter is set to 5% of the length. If showSlabs is true (default false), two rectangular slabs showing the rotation axis and angle and the shift will be opened as a surface model. The axis and/or slab color can be any color name that specifies a single color.

See also: fitmap, superimposing structures

Calculate and display a path along the center line of each specified segmentation region. The length of the path (spine) and orthogonal diameters at its midpoint are reported. Regions can be specified as a selection (e.g., sel) or with model number(s) (e.g., #1). The longest principal axis of inertia of a region is determined using equal weighting of the enclosed volume grid points. The region is then divided into slices along that axis, with end slices tipLength t thick and interior slices at least spacing s thick. Both distances are specified in physical units (typically Å). The default spacing s is 20 times the minimum segmentation grid plane spacing, and the default tipLength t = 0.2s. The spacing is increased as needed to make the interior slices of equal width. A marker is placed at the geometric center of the grid points within each slice. The markers are linked, and the markers and links together form a path. The path color can be any color name that specifies a single color. For each pair of consecutive links in the path, the curvature is measured as 1/r, where r is the radius of a circle tangent to the midpoints of the links. The minimum, maximum, and average (weighting each value along the path equally) curvatures are assigned as segmentation region attributes named curvature minimum, curvature maximum, and curvature average, respectively.

See also: segment sliceimage, Segment Map

Check each specified volume data set (map) for cyclic, dihedral, tetrahedral, octahedral, and icosahedral symmetries in standard coordinate systems. Helical symmetry can be considered if approximate parameters are supplied. The symmetry assignment can be used by other commands such as sym and fitmap, and is included in Chimera map format. For direct assignment of a specified symmetry, see the command volume symmetry.

If the correlation of the map with itself after symmetry transformation is at least mincorr (default 0.99), the detected type of symmetry will be reported, and if set is true, assigned to the map in Chimera. The correlation calculation uses only map points with values above the displayed contour level; if the number of such points exceeds maxpts (default 10,000), a random sample of maxpts is chosen from them and used. Values in the first copy of the map are compared with the superimposed (interpolated) values in the rotated copy of the map.

Center of point symmetry is considered only at the following:

• the grid point nearest the average indices of grid points with values above the displayed contour level. The map's lowest contour level in Volume Viewer is used.
• one or two grid points based on the overall map dimensions: only the midpoint along axes with odd numbers of points, and along axes with even numbers of points, those on either side of the midpoint. Rather than all possible combinations for axes with even numbers of points, only the two points with all indices lower or all higher are evaluated.

For cyclic and dihedral symmetry, rotation is considered only about the Z axis, and for dihedral symmetry, flipping symmetry only about the X or Y axes. Cyclic (Cn) symmetry is checked for order n up to nMax, default 8. If more than one Cn symmetry meets the criterion, those for which a higher multiple is also found are discarded, and of the remaining, the one with the highest correlation is assigned. For example, if n = 2, 3, 6, and 7 were to meet the criterion, 6-fold would override 2- and 3-fold, and 6-fold or 7-fold symmetry, whichever gave the highest correlation, would be assigned. Tetrahedral symmetry is considered in two orientations:

• 2-folds along X, Y, and Z, with a 3-fold along axis (1,1,1)
• 3-fold along Z, with a second 3-fold in the YZ plane such that rotation about the X axis by ~110° is a symmetry operation (EMAN convention)

Icosahedral symmetries are only considered in the eight orientations listed in the Icosahedron Surface dialog.

The helix option specifies looking for helical symmetry with approximate rise (in physical units of distance, typically Å) and angle (degrees) per asymmetric unit. If this option is used, the other types of symmetry are not considered except for combined helical and cyclic symmetry (for example, EMD-1757, approximately 42 Å rise and 21° twist per subunit). Helical symmetry is infinite, but the number of copies to place when considering that symmetry, n, is necessarily finite. If not given, n will be determined by dividing the apparent length of the helix in the map by the rise and rounding to the nearest positive integer. The opt keyword indicates optimizing the fit of the map copies to itself to identify more accurate helical parameters.

See also: molmap, volume

Calculate the total volume enclosed by each specified surface piece, not including any interior bubbles. The surface pieces in a surface model can be specified collectively by model number, or individually by selection from the screen and using the word sel, selected, or picked. Like Measure Volume and Area, the calculation uses the full surface even if it is partly hidden by clipping or zoning, and holes are treated as if covered by planar caps.

See also: surface, volume

TECHNICAL NOTES

Electric field line placement.
A key issue for measure fieldLines is which lines to compute, out of an infinite number of possibilities. The basic idea is to make the number of lines originating from a charge proportional to the magnitude of the charge. This is approximated by computing the magnitude of the gradient squared divided by the potential at every grid point and using the grid points with the largest N values for starting N field lines. The rationale is as follows: near a point charge, the potential is q/r. The gradient squared divided by the potential is q/r**3 ( = (q/r**2)**2 / (q/r)). If for a chosen point (gradient squared / potential) > C, then q/r**3 > C and r**3 < q/C. The number of grid points around a charge is proportional to the volume r**3, so is linear in charge.

The resulting field lines can vary greatly depending on the charge distribution used to compute the potential. When charges are concentrated on fewer atoms, longer lines are generated, but when charges are distributed onto many atoms, there may be many short lines that do not extend beyond the molecular surface. In that case, it may be helpful to use a higher startAbove cutoff value and a larger number of lines (total) to get more lines that loop beyond the surface.

Inertia calculation.
The command measure inertia computes the moments of inertia of a set of atoms as in classical mechanics:

I_jk = Σ_i (m_i (δ_jk |x_i|² – x_i,jx_i,k))

• For atoms, we show the surface of a uniform-density solid ellipsoid that has the same principal axes and moments as the atoms.
• For surfaces, we show an ellipsoidal surface that as a thin shell has the same axes and moments as the measured surface.