Structure Measurements

The Structure Measurements panel has four sections:

Distances - monitor distances
Angles/Torsions - monitor angles and torsions
Adjust Torsions (now located in Build Structure) - rotate bonds
Axes/Planes/Centroids - show axes, planes, and centroids based on sets of atoms, perform related measurements

Only one section is shown at a time, and clicking the tab for another brings it to the front. Each section is listed as a tool in the Structure Analysis category. Tools can be started in several ways. See also: Metal Geometry, Ramachandran Plot, CASTp Data, measure

Atomspec display style in the Labels preferences controls how atoms are listed in the Structure Measurements dialog. The Distances figure shows the simple style (residue name, residue specifier, and atom name). For an example of command-line specifiers, see the Adjust Torsions figure.

Save saves measurements to a file. Close closes the measurements panel, and Help opens this manual page in a browser window.

Distances

The Distances section of Structure Measurements is a table of distance monitors (measurements that update if there are changes). Distance monitors are saved in sessions. See also: FindHBond, distance

There are several ways to start Distances, a tool in the Structure Analysis category. Distance monitors can be created in several ways:

Selecting exactly two atoms, then clicking the Create button on the dialog. With default mouse settings, two atoms can be picked (selected from the graphics window) by Ctrl-clicking the first and Shift-Ctrl-clicking the second.
Doubleclick-picking an atom when one other atom is already selected, then choosing Show Distance from the resulting context menu.
Doubleclick-picking an atom when 0 or >3 other atoms are already selected, then choosing Show Distances to Nearby Residues from the resulting context menu.
Using the distance command.

Distances - simple atom listings

The distance list can be sorted by the values in any column by clicking the header. Clicking the header once sorts the entries in order of increasing value and places an up arrowhead (triangle) in the header. Clicking again sorts the entries in decreasing order and places a down arrowhead (inverted triangle) in the header.

A distance monitor can be chosen by clicking on its line, and more than one can be chosen at a time. Chosen lines are highlighted in the dialog. Ctrl-click toggles the status of a line, while clicking on the first (or last) line of a contiguous block and then Shift-clicking on the last (or first) chooses all of the lines in the block.

Choosing a distance listing selects the corresponding distance pseudobond. The Choosing in table... option allows additionally selecting the corresponding atoms. Remove deletes the chosen distance monitors. If there is only one, it is not necessary to choose it before using Remove.

The Labels setting applies to all distance monitors and can be switched among:

None - no label
ID - distance monitor ID number (the first column in the table)
Distance - distance value in the same units as the atomic coordinates, normally Å

The formatting options Decimal places and Show Angstrom symbol control how distance values are shown in the table and (when Labels is set to Distance) in labels. The Decimal places can be changed by clicking or holding down one of the arrows on either side of the value. Of course, decimal places beyond those present in the input coordinates are not very meaningful. Changes in distance formatting options are automatically saved in a user's preferences file and also apply to distances shown with FindHBond.

The lines representing distance monitors are pseudobonds in a group named distance monitor. The following depiction options apply to the whole group:

Distance color (a color well) - pseudobond group color, see coloring hierarchy
Line width - linewidth in pixels
Line style - whether solid, dashed, dotted, etc.
Save as defaults - save the current distance color, linewidth, and line style settings in the user's preferences file

Settings of individual pseudobonds (as well as pseudobond groups) can be changed using the the Selection Inspector or the command setattr.

Angles/Torsions

The Angles/Torsions section of Structure Measurements is a table of angle monitors (measurements that update if there are changes). A “bond angle” is measured for three atoms and a “torsion angle” for four atoms; however, it is not necessary for the atoms to be contiguous or even bonded to one another. Angle monitors are saved in sessions.

Angles/Torsions reports changes but cannot be used to change the angles. Angles can be changed using Adjust Bond Angles and Adjust Torsions.

There are several ways to start Angles/Torsions, a tool in the Structure Analysis category. Angle monitors can be created in various ways:

Selecting exactly three atoms for a bond angle or four atoms for a torsion angle, then clicking the Create button on the dialog. With default mouse settings, atoms can be picked (selected from the graphics window) by Ctrl-clicking the first and Shift-Ctrl-clicking additional atoms.
Doubleclick-picking an atom when two other atoms are already selected, then choosing Measure Angle from the resulting context menu.
Doubleclick-picking an atom when three other atoms are already selected, then choosing Measure Torsion from the resulting context menu.

The angles/torsions list can be sorted by the values in any column by clicking the header. Clicking the header once sorts the entries in order of increasing value and places an up arrowhead (triangle) in the header. Clicking again sorts the entries in decreasing order and places a down arrowhead (inverted triangle) in the header.

A measurement in the list can be chosen by clicking on its line, and more than one can be chosen at a time. Chosen lines are highlighted in the dialog. Ctrl-click toggles the status of a line, while clicking on the first (or last) line of a contiguous block and then Shift-clicking on the last (or first) chooses all of the lines in the block.

Choosing an angle monitor also selects the corresponding atoms and bonds when the Choosing in table... option is on. Remove deletes the chosen measurement(s). If there is only one measurement, it is not necessary to choose it before clicking Remove.

The Decimal places setting controls how angles are reported in the table; the number of digits shown after the decimal can be changed by clicking or holding down one of the arrows on either side of the value.

The command angle can also be used to measure bond angles and torsions; however, it yields a static measurement rather than a continuously updating monitor.

dopamine D3 receptor
helix axes, membrane planes
(see Image Gallery entry)

Axes/Planes/Centroids

The Axes/Planes/Centroids section of Structure Measurements allows defining geometric objects (axes, planes, centroids) based on sets of atoms and performing measurements involving the objects. Axes can also be calculated from centroids or some combination of atoms and centroids. Axes are displayed as rods, planes as disks, and centroids as spheres. Objects to be listed in the Axes/Planes/Centroids table can also be created with the command define. Each object is created as a surface model (hidden from the Model Panel) in the coordinate system of the lowest-numbered model involved in its calculation. Axes/Planes/Centroids objects and information are saved in sessions. See also: distance, angle, align, shape, measure inertia, PipesAndPlanks, Thermal Ellipsoids, geometric objects

There are several ways to start Axes/Planes/Centroids, a tool in the Structure Analysis category.

Clicking Define axes... opens a dialog for specifying atom/centroid sets and other axis parameters. Eigenvectors/values are calculated from the coordinates of each set of atoms/centroids after subtracting the position of their collective centroid. Each axis is anchored at the corresponding collective centroid and aligned with the principal (largest) eigenvector of the corresponding coordinates (prior to any helical correction).

Each helix in [models] - define an axis for each peptide/protein helix in the molecule model(s) chosen in the list. Peptide/protein helix assignments are taken from the input structure file or generated with ksdssp. Only the backbone atoms N, CA, C are used to define the axes. Sometimes two helices are adjacent in sequence (not separated by any other residues), and the integer-valued residue attribute ssId is used to distinguish them. Although such cases are detected automatically, ssId can also be set manually with setattr.
Selected atoms/centroids (axis name [name]) - define a single axis named name using all selected atoms and/or centroid objects
Axis Parameters:
- Mass weighting (only available for the Selected atoms/centroids option) - calculate major inertial axis by mass-weighting the atoms/centroids; cannot be combined with helical correction. The radius of a centroid (Å) is used as its “mass” (daltons).
- Use helical correction - adjust axis orientation to reduce the spread of atom-axis distances; cannot be combined with mass weighting. While usually small, helical correction improves results for short helices.
- Replace existing axes - whether to remove any/all pre-existing axis objects
- Color (a color well, default No Color, meaning to match the structure as much as possible)
- Radius
  - average axis-atom distance (default) - if this setting is chosen but an axis is based on only two points (atoms and/or centroid objects), the last used constant value (below) will be applied instead
  - angstroms (a constant value)
Plane normals [planes] - define normal (perpendicular) axis for each of one or more previously defined planes

Only one color well setting and one constant radius value can be specified at a time, but axes with different colors and radii can be created in successive stages when Replace existing axes is turned off. Clicking Apply (or OK, which also closes the dialog) calculates the axes, adds them to the table, and generates the corresponding objects. Axis radii are reported in the Reply Log.

Clicking Define plane... opens a dialog for defining a plane based on the selected atoms. Eigenvectors/values are calculated from the atomic coordinates after subtracting the position of their non-mass-weighted centroid. The plane is anchored at the centroid and aligned with the two largest eigenvectors (the third-largest eigenvector is normal to the plane).

Plane name
Replace existing planes (true/false) - whether to remove any/all pre-existing plane objects
Color (a color well, default No Color, meaning to match the source atoms as much as possible)
Set disk size to enclose atom projections (true/false) - whether the disk radius should be set to span the projections of the defining atoms back onto the plane. If true, an Extra radius (padding) can be specified (default 0.0 Å). If false, a Fixed radius can be specified (default 10.0 Å). The disk center is the non-mass-weighted centroid of the atoms.
Disk thickness (Å)

Clicking Apply (or OK, which also closes the dialog) calculates a plane based on the selected atoms, adds it to the table, and generates the corresponding object. Plane radius is reported in the Reply Log.

Clicking Define centroid... opens a dialog for defining a centroid based on the selected atoms:

Centroid name
Mass weighting (true/false) - whether to mass-weight atoms when calculating the centroid
Replace existing centroids (true/false) - whether to remove any/all pre-existing centroid objects
Color (a color well, default No Color, meaning to match the source atoms as much as possible)
Radius (Å)

Clicking Apply (or OK, which also closes the dialog) calculates a centroid based on the selected atoms, adds it to the table, and generates the corresponding object. Centroid coordinates are reported in the Reply Log.

Columns in the Axes/Planes/Centroids table of objects:

Name
color - an object can be recolored by clicking its color well and using the Color Editor, or by selecting the object and using the Actions... Color menu
ID - object identifier, aN for axes, pN for planes, cN for centroids
Shown - whether the object is displayed
Length - axis length, end-to-end distance needed to span the projections of the defining atoms back onto the axis
Radius - object radius

The table can be sorted by a column by clicking the column header.

An object can be chosen by clicking on its line, and more than one can be chosen at a time. Chosen lines are highlighted in the dialog. Ctrl-click toggles the status of a line, while clicking on the first (or last) line of a contiguous block and then Shift-clicking on the last (or first) chooses all of the lines in the block.

Choosing any two objects reports their applicable geometric relationships below the table and in the Reply Log. For angle measurements, axes and planes are treated as infinite. For distance measurements, axes are treated as finite line segments, while planes are treated as infinite. (However, closest-distance measurements treating plane objects as finite can be made by specifying a single selected plane as sel or two planes as named selections within a measure distance command. Only the plane surface vertices are used.)

Optionally, choosing objects also:

selects object - selects each object (currently nothing can be done to such a selection, but the objects are highlighted in the graphics window)
selects atoms - selects the atoms used to define each object

Conversely, picking an object from the screen will choose it in the table.

Clicking Delete removes the chosen objects. In addition, closing a molecule model or deleting atoms removes any objects defined using those atoms. Rename allows changing the names of the chosen objects; this will change their order in the table if sorting is currently by name.

Report distance measures distances between the chosen objects and selected atoms; results are sent to the Reply Log. If a single atom is selected, the distance to each chosen object is reported; if multiple atoms are selected, the minimum, maximum, and mean distances are reported.

Center and align is available when a single axis or plane object is chosen. It centers and aligns the chosen axis, or centers the chosen plane and aligns its normal vector, along the specified direction in the laboratory coordinate system:

X - horizontal in the plane of the screen
Y - vertical in the plane of the screen
Z - perpendicular to the screen, along the line of sight

There is no control over which end of the axis or normal vector goes in the positive direction, but the view can be flipped 180° with a command, for example:

turn y 180 center view

Axis/plane/centroid information written out with Save includes name and untransformed center coordinates (x_c,y_c,z_c). Axis information also includes length and orientation expressed as a unit vector (x_u,y_u,z_u). Axis endpoint coordinates (x₁,y₁,z₁) (x₂,y₂,z₂) can be generated as follows:

x₁ = x_c – 0.5(length)(x_u)
y₁ = y_c – 0.5(length)(y_u)
z₁ = z_c – 0.5(length)(z_u)

x₂ = x_c + 0.5(length)(x_u)
y₂ = y_c + 0.5(length)(y_u)
z₂ = z_c + 0.5(length)(z_u)

Plane information also includes radius and orientation expressed as a normal unit vector.

UCSF Computer Graphics Laboratory / February 2018