Command: measure

Usage:
measure  property  arguments

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

• area – report the area of an existing surface (sum of surface triangles)
• blob – measure surface area, enclosed volume, and dimensions of a disconnected surface blob
• buriedarea – calculate solvent-accessible surface area buried between two sets of atoms
• center – calculate center of mass of map, atoms, and/or surface
• contactarea – report the area of one surface within a cutoff distance of another
• convexity – calculate convexity at each surface vertex, color the surface accordingly
• correlation – report map-map correlation
• inertia – calculate inertia ellipsoid
• length – sum bond lengths
• mapstats – report volume data min, max, mean, SD, and RMSD values
• mapvalues – calculate volume data values at atom positions and assign them as an atom attribute
• motion – show changes in surface position by drawing lines
• rotation – report transformation of one model relative to another
• sasa – calculate solvent-accessible surface area
• symmetry – check map for certain symmetries in standard orientations
• volume – report the volume enclosed by an existing surface
• weight – report the sum of atomic weights in daltons

See also: surface, surface zone, VDW radii, measurements

Report the total surface area of an existing surface model, computed as the sum of the areas of its triangles. The includeMasked option controls whether to include parts of the surface that have been hidden, such as with surface dust or surface zone. Parts hidden by clipping are always included, however (details...). See also: measure sasa, surface splitbycolor, Measure Volume and Area

Report measurements for the blob (disconnected surface part) in the specified surface model containing triangleNumber  N. The surface-model specification cannot be blank. Although not generally known in advance, the triangle number is included in the command echoed to the Log when the pick blob mouse mode is used, so that the action could be replicated in a script. Measurements include:

• volume enclosed in the blob
• area of its triangulated surface
• if reportSize is true (default), the size in dimensions from longest to shortest of the bounding box aligned with principal axes (details...)

Blob color is left unchanged unless a color is given. The outline option shows the bounding box as an outline in the specified outlineColor (default lime ). See also: marker connected, Measure and Color Blobs

Calculate the solvent-accessible surface (SAS) area buried between two sets of atoms, defined as:

½ (sasa1 + sasa2 – sasa12)

where  sasa1 is the area of the SAS enclosing the atoms in  atom-spec1,  sasa2 is the area of the SAS enclosing the atoms in  atom-spec2, and  sasa12 is the area of the SAS enclosing both sets of atoms together. The sets of atoms should be specified with care; they should not overlap, and solvent, ions, and ligand residues are not excluded automatically. Unspecified atoms are ignored. The default probeRadius rad for calculating each SAS is 1.4 Å, often used to approximate a water molecule. Residues with at least cutoffArea area buried (default 1.0 Ų) can be:

• listed along with their buried areas in the Log using the listResidues option
• selected with the select option
• colored using color color-spec

The buried area of a residue is its SAS area in the individual set minus that in the combined set. Examples:

measure buriedarea (/c & protein) with (/d & protein)
– calculate buried surface area between the protein parts only of chains C and D

measure buried ligand with protein list T sel T
– select and list residues with ≥ 1.0 Ų area buried between ligand and protein

For surfaces without associated atomic coordinates, see measure contactarea. See also: interfaces

Calculate the center of mass of each density map, surface (other than a map surface), and/or set of atoms in spec. The centers of mass are reported in scene coordinates, and map centers also in grid indices. The approach for surfaces is analogous to that for atoms, except that the points in space are the vertices of the triangulated surface. Each vertex is weighted by ⅓ of the sum of the areas of all attached triangles. This treats the surface as a thin shell. 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 (default #b4b4b4 ). The marker model is opened as number model-number (default next unused number) with name model-name (default based on the contents of spec). Atomic mass-weighting is always used, but the related command define centroid allows calculating the non-mass-weighted center of a set of atoms. See also: cofr

Report the surface area of one surface model (surf-model1) that lies within distance d (default 3.0 Å) 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 default color for the patch is red. The new surface can be offset from the original surf-model1 by a distance d2 (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.

For atomic structures, measure buriedarea may be more appropriate.

Color a surface based on the convexity at each vertex, calculated as 2π minus the cone-angle (in steradians) spanned by the triangles incident at the vertex. Convexity values are smoothed by averaging with neighboring (edge-connected) vertices for a specified number of iterations (default 5). Smoothing is generally recommended, given that this definition of convexity is nonstandard and the unsmoothed values depend strongly on the triangulation: vertices surrounded by large triangles on a smooth surface will have sharper cone angles than vertices surrounded by small triangles. (Normalizing by triangle areas does not help because the patch around a vertex is often irregular in shape.) The surface vertex positions, normals, convexity values, and triangles can be saved to a text file with writeSurfaceData, where filename can be a pathname including the directory location.

The remaining options relate to coloring. The patches option randomly assigns colors to contiguous patches of vertices with convexity values above the convexity-threshold. Otherwise (patches not used), the surface will be colored by the convexity value per vertex, with palette-options as described for color, except with defaults :

palette cyan-gray-maroon  range -1,1

Unsmoothed values typically give mottled coloring. When measure convexity is run interactively (in gui mode and not via a script), the key true option can be used to start Color Key and draw a color key with the corresponding colors and values.

See also: key, coulombic, mlp, color, bumps

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 (volume-spec1) 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 (volume-spec2), except that the values are sampled at the grid point locations of the first map using trilinear interpolation. If envelope 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.

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

Calculate the inertia ellipsoid for  atom-spec,  which could include atoms and/or surfaces. Atoms are mass-weighted; surfaces are treated as thin shells with mass proportional to surface area (details...). If both atoms and surfaces are specified, 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 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 with modelId  model-number (default the next unused number), containing multiple submodels if there are multiple ellipsoids. The replace true option allows replacing an existing model when the specified model-number is already in use. If ellipsoid color is not specified, each ellipsoid will be colored to match the first atom or surface in its calculation.

Another way to generate a low-resolution representation of an atomic structure is with molmap. See also: define, shape ellipsoid, 3D object formats, convex hull recipe

Sum the lengths of all bonds between specified atoms (markers); primarily used to measure the length of traced paths of markers.

Report the minimum value, maximum value, mean, standard deviation (SD) from the mean, and the root-mean-square (RMS) deviation from zero for the specified volume data models, if any, otherwise all such models. The step and subregion options can be used to limit the calculation to a subsample or spatial subregion of the data. The step size must be an integer; 1 indicates all data points (default), 2 indicates every other data point, 3 every third point, etc. 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. A subregion can be specified by:

• 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.
• the word all, indicating the full extent of the data rather than a subregion

The default is to use the current subregion (if cropped) and current step size of each specified map. This command is also implemented as Map Statistics in the Volume Data section of the Tools menu.

Calculate volume data (map) values at atom positions and assign them as an atom attribute. The attribute-name should be enclosed in quotation marks if it contains spaces; if no name is supplied, mapvalue will be used. Atoms that fall outside the map bounds are not assigned values. Assigning an attribute allows coloring the atoms by value with color byattribute, specifying them by value in the command line, etc. The new attribute is saved in session files.

Draw “prickles” to show the change in position between a surface and a volume (map) isosurface, for example, between time steps of a volume series. Prickles are line segments drawn perpendicular to the surface. They are extended from the vertices of surf-model in increments of map grid units (using the smallest spacing along the three axes, if they differ) until they intersect with the map isosurface or reach steps M grid units in length (default 10). Prickles are shown in the specified color (default lime ) and can be amplified or shrunken in length by a scale factor f. If a model number is specified with pricklesModel N, the prickles will be added as a submodel of N. If a model number is not specified, the new model will be a submodel of surf-model.

Report the transformation of model1 relative to model2 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

This command does not evaluate how to best fit or match the two models. It reports the current rotation and translation between the coordinate systems of the two models, which would be zero unless one model was moved relative to the other, either with the mouse (using one of the rotate/translate selected modes) or with some other tool or command such as Fit in Map, align, or matchmaker. (Moving everything collectively, such as rotating or zooming to get a better view, does not change the positions of models relative to each other.)

To get the transformation between atomic structures that are similar but displaced from one another (without actually superimposing them), using the align command with move false and reportMatrix true is recommended instead.

The transformation is expressed in the coordinate system of model2 unless specified otherwise with the coordinateSystem option. If showAxis is true (default), a model showing the axis as a rod will be created, with the specified length (default the largest dimension of the bounding box of the displayed part of model2), radius (default 2.5% of the length), and color (default #d2d264 ). The axisType option specifies whether the axis should be created as a marker model (default) or as an axis object (such as could be used to reorient the view or in various measurements). If showSlabs is true (default false), two rectangular slabs showing the rotation axis and angle and the shift will be created as surface models, with the specified length (default described above), width, and thickness (defaults 50% and 2.5% of the length, respectively) and colored according to color and color2 (defaults #d2d264 and cornflower blue , respectively).

See also: fitmap, view matrix, ChimeraX positions files

Calculate the area of a solvent-accessible surface (SAS) enclosing the atoms in  atom-spec1 and report the total value in the Log. The setAttribute option specifies whether to assign the values per atom and residue as attributes named area (default true). The sum option can be used to report the area contribution from some subset of the atoms (given as  atom-spec2). The calculated SAS is not displayed. The atoms should be specified with care; solvent, ions, and ligand residues are not excluded automatically. Unspecified atoms are ignored, as are atoms in  atom-spec2 that are not also in  atom-spec1. The default probeRadius rad for calculating the SAS is 1.4 Å, often used to approximate a water molecule. Example:

measure sasa #1/a & protein sum :phe,tyr,trp
– calculate the SAS of the protein in model #1 chain A and report both the total area and the collective contribution from phenylalanine, tyrosine, and tryptophan residues

See also: measure area

Check each specified volume data model (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, molmap, and fitmap, and is included in Chimera map format. For direct assignment of a specified symmetry, see 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 (default), assigned to the map in ChimeraX. 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 eight orientations:

• 222 – with two-fold symmetry axes along the X, Y, and Z axes
• 2n5 – with two-fold symmetry along X and 5-fold along Z
• n25 – with two-fold symmetry along Y and 5-fold along Z
• 2n3 – with two-fold symmetry along X and 3-fold along Z
• 222r – same as 222 except rotated 90° about Z
• 2n5r – same as 2n5 except rotated 180° about Y
• n25r – same as n25 except rotated 180° about X
• 2n3r – same as 2n3 except rotated 180° about Y

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.

Report the volume enclosed by an existing surface model. The includeMasked option controls whether to include parts of the surface that have been hidden, such as with surface dust or surface zone. Parts hidden by clipping are always included, however (details...). See also: Measure Volume and Area

Report the total mass in daltons of the specified atoms. Atoms missing from the structure (e.g. hydrogens, truncated sidechains, missing segments) will not be included.

[back to top: surface]

Technical Notes

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.