ChimeraX docs icon

Command: measure

Usage:
measure  property  arguments

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

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

measure area  surf-model  [ includeMasked  true | false ]
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
measure blob  surf-model  triangleNumber  N  [ reportSize  true | false ] [ color  color-spec ] [ outline  true | false ] [ outlineColor  color-spec ]
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: 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
measure buriedarea  atom-spec1  withAtoms2  atom-spec2  [ probeRadius  rad ] [ listResidues  true | false ] [ cutoffArea  area ] [ select  true | false ] [ color  color-spec ]
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 Å2) can be:

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 Å2 area buried between ligand and protein

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

measure center  spec  [ level  contour-level ] [ mark  true | false ] [ radius  marker-radius ] [ color  color-spec ] [ modelId  model-number ] [ name  model-name ]
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
measure contactarea  surf-model1  withSurface  surf-model2  [ distance  d  ] [ color  color-spec ] [ offset  d2 ] [ slab  width | d1,d2 ] [ show  true | false ] [ smooth  true | false ] [ optimize  true | false ]
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.

measure convexity  surf-model  [ smoothingIterations  N ] [ writeSurfaceData  filename ] [ patches  convexity-threshold ] [ key  true | false ]  palette-options 
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

measure correlation  volume-spec1  inMap  volume-spec2  [ envelope  true | false ]
Calculate the correlation between two volume data sets (maps) in two ways:
<u,v>
correlation =  
 |u||v|
<uuave,vvave>
correlation about mean =  
 |uuave||vvave|
where vector u contains the values of the first map (volume-spec1) and uave is a vector with all components equal to the average of the components of u. Vectors v and vave 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

measure inertia  atom-spec  [ perChain  true | false ] [ showEllipsoid  true | false ] [ color  color-spec ] [ modelId  model-number ] [ replace  true | false ]
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

measure length  atom-spec 
Sum the lengths of all bonds between specified atoms (markers); primarily used to measure the length of traced paths of markers.
measure mapstatsvolume-spec ] [ step  N | Nx,Ny,Nz ] [ subregion  i1,j1,k1,i2,j2,k2 | all ]
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: 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.
measure mapvalues  volume-spec  atoms  atom-spec  [ attribute  attribute-name ]
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.
measure motion  surf-model  toMap  map-model  [ color  color-spec ] [ steps  M ] [ scale  f ] [ pricklesModel  N ]
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.
measure rotation  model1  toModel  model2  [ coordinateSystem  model-spec ] [ showAxis  true | false ] [ axisType  markers | object ] [ showSlabs  true | false ] [ length  d ] [ radius  r ] [ color  color-spec ] [ width  w ] [ thickness  t ] [ color2  color-spec ]
Report the transformation of model1 relative to model2 as: 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

measure sasa  atom-spec1  [ probeRadius  rad ] [ setAttribute  true | false ] [ sum  atom-spec2 ]
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
measure symmetry  map-model  [ minimumCorrelation mincorr ] [ nMax n ] [ points maxpts ] [ set  true | false ] [ helix rise,angle[,n][,opt] ]
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:

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:

Icosahedral symmetries are only considered in eight orientations:

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.

measure volume  surf-model  [ includeMasked  true | false ]
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

Technical Notes

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

Ijk = Σi (mijk |xi|2 – xi,jxi,k))
I is a 3x3 matrix with indices j and k (j=1,2,3 and k=1,2,3). Each matrix element is a sum over atoms, where mi and xi are the mass and position of atom i, respectively, and δjk is 1 for j=k, otherwise 0. The principal axes are the eigenvectors of the matrix, and the moments about those axes are the eigenvalues. Basically, the moment is a sum of mass times distance squared from the rotation axis. Before this formula is applied, the center of mass position is subtracted from the atom coordinates, so that the measured quantity is the inertia about the center of mass. The approach for surfaces is analogous, where atoms are replaced by 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 “inertia ellipsoid” shown by ChimeraX is not the same as the one defined in physics. Instead, it is the ellipsoid that has the same inertia as the measured object:


UCSF Resource for Biocomputing, Visualization, and Informatics / May 2024