Omnibus Color Command Mockup (Exploratory)

• Chimera2 color manpage
• Chimera2 commands needed for initial release (wiki)
• Chimera2 command guidelines
• red - will this be in Chimera2?
• olive - other notes

Usage:
color  spec  colorname  [ target  string ]

Usage:
color  spec  method  method-options  general-options

The color command (synonym colour) can assign single colors or map multiple colors to the values of some descriptor or property. Still not settled where the spec should go. Examples below. See also: transparency

The colorname for simple coloring can be:

• any of 169 built-in color names (same list as in Chimera1, including element symbols?)
• an R,G,B or R,G,B,A tuple, where R is the red component, G is the green component, B is the blue component, and A is the opacity (1 – transparency), each in the range 0–1. The values should be separated by commas only, not spaces. Example: 1,0.25,0.8,0.3
• a Tk (hexadecimal) color code such as #7fffd4 or #b0b030306060
• a name defined previously with colordef
• colorpanel, fromeditor, or editor - the color currently defined in the Color Editor
• byelement - a color-by-element scheme; only applies to atomic representations and per-atom patches of molecular surfaces. The color names are the same as the element symbols. For example, a colored-by-element sulfur atom may look yellow, but is actually the color S (slightly different than yellow).
• byhet or byhetero - same as byelement, except leaving carbon atoms unchanged
• byatom - color other targets (molecular surface patches, etc.) to match the corresponding atoms

• sequential  level - sequentially per residue, secondary structure element, chain, or model
• attribute  attr-name - by atom, residue, or model numerical attribute value
• volume  volume-model - by volume (grid) data value or gradient interpolated to atom centers and/or surface vertices
• radial - by distance from a point to atoms and/or surface vertices
• cylindrical - by distance from an axis to atoms and/or surface vertices
• topographic - by distance from a plane to atoms and/or surface vertices
• zone atom-spec - to color surfaces to match nearby atoms or markers

The target option allows coloring only a subset of the possible displays of a given atom, residue, etc. The string can be any combination of the following letters, without commas or spaces:

• a - atoms/bonds (halfbond coloring)
• l - atom labels and bond labels?
• s - surfaces (molecular surfaces divisible to per-atom patches, all surface models divisible to selected triangles)
• c - cartoons (divisible to per-residue segments)
• r - residue labels
• n - nonmolecular models (model-level color)
• m - molecular models (model-level color)
• b - bonds only (halfbond mode off) with both end atoms specified
• p - pseudobonds with both end atoms specified
• d - distances and other pseudobond labels
  Can bonds/pbonds be specified by selection of the bond/pbond alone?

The default target for multicoloring includes atoms/bonds, labels, surfaces, and cartoons (target alscr), except that coloring by atom attribute is further limited to just atoms/bonds and their associated labels and surface patches (als) when spec contains only explicit specifications of atoms by atom name, atom type, element, and/or atom attribute.

Is this doable? By explicit specification I mean that although higher levels could be included in spec, all the “leaves” would be down to the atom level, for example:

Examples

color /A,B:12,260-275  hot pink  target a
- color residues 12 and 260-275 in chains A and B, atoms/bonds only
color  sequential res
- rainbow-color residues blue → red in each biopolymer chain
color  seq res  target c
- rainbow-color residues blue → red in each biopolymer chain, cartoons only
color /A  attribute bfactor  target ac  residueVal max
- rainbow-color chain A atoms by atomic bfactor, cartoon segments by maximum atomic bfactor per residue
color #0  volume #1  cmap redblue  cmapRange -10,10  newAttr esp
- color model #0 by values in map #1; if #0 includes atoms (as opposed to surface-only), create new atom attribute named esp
color #0  volume #1  cmap -10,red:0,white:10,medium blue  newAttr esp
- same as previous except use medium blue instead of blue
color  seq mol  initial true
- reset molecule models to default initial colors

Multicoloring Methods

Keywords can be truncated to unique strings, and their case does not matter. Synonyms for true: True, 1. Synonyms for false: False, 0. A vertical bar “|” designates mutually exclusive options, and default settings are indicated with bold.

Color sequentially according to the specified level:

• residues - assign a different color to each residue, starting over for each biopolymer chain; with the default color mapping, this rainbow-colors residues from blue at the N-terminus to red at the C-terminus of a peptide chain
  (I reversed the “rainbow” cmap relative to Chimera1 and made it the default so that color seq res would be like Chimera1 rainbow)
• helix or helices - assign a different color to each protein α-helix, starting over for each chain; strand, coil, and nonproteins are ignored
• strands - assign a different color to each protein β-strand, starting over for each chain; helix, coil, and nonproteins are ignored
• SSEs - assign a different color to each protein secondary structure element (helix or strand), starting over for each chain; coil (non-helix, non-strand) and nonproteins are ignored
• chains - assign a different color to each chain, starting over for each molecular model
• molmodels [ initial true | false ] - assign a different color to each molecular model
  ...and maybe either or both of the following?
• volmodels [ initial true | false ] - assign a different color to each volume model
• allmodels [ initial true | false ] - assign a different color to each model

Regardless of the level, sequential coloring always applies to entire models (not parts of models). This should recognize SSEs as defined in the input even if they don't have any intervening coil, unlike Chimera1 rainbow, which (for example) treats abutting helices as one long helix. Perhaps this could be optional, since sometimes they are clearly separate helices, but sometimes look more like parts of a single bent helix... 4s0v illustrates both of these situations.

The *models levels also set model-level colors. Specifying initial true indicates ignoring any colormap settings and instead restoring default initial colors. Would molecule models still have hetatm coloring?

For a plain white or black background, default initial colors for molecule models are 0:tan, 1:sky blue, 2:plum, 3:light green, 4:salmon, 5:light gray, 6:deep pink, 7:gold, 8:dodger blue and 9:purple (see named colors):

#0

#1

#2

#3

#4

#5

#6

#7

#8

#9

Thereafter, or for other backgrounds, an algorithm is used to produce colors distinguishable from the background and from other models. Similarly, a set of default initial colors for volume data sets is shown in the Volume Viewer data display options:

Color by the values of a numerical attribute. An atom attribute can be used to color atoms/bonds, cartoons (by residue values derived from the atomic values as per residueValues) and per-atom patches in molecular surfaces. A residue attribute can be used to color atoms/bonds, per-residue segments in cartoons, and per-residue patches in molecular surfaces. Coloring by model attribute also sets model-level colors. The raiseDialog option specifies raising the attribute-rendering dialog, which shows a histogram of the attribute values and can be used to adjust the colormapping.

Color entire models by volume data such as electron density or electrostatic potential interpolated to the positions of atoms and/or surface vertices (details), where volume-model is the model number (preceded by #) of the volume data set. If gradient is true, the gradient norm of the volume data will be used instead of the primary data. The perPixel option indicates whether to determine color separately for each surface pixel instead of interpolating across surface triangles (details). Per-pixel coloring tends to give smoother color gradations. The colorOutsideVolume option specifies how to color points that fall outside the volume data grid. The colorname can be any color name that specifies a single color; the default is #800080008000 (a dark gray). The offset option specifies how far out from each surface vertex, along its normal, to evaluate the data (default 0.0):

• d - a single offset distance
• start,end,N (three values separated by commas only) - starting distance, ending distance, and how many offsets to evaluate within that range, respectively. For example, offset 1.5,3.0,3 specifies offsets of 1.5, 2.25, and 3.0. Values from multiple offsets are averaged per surface vertex. Specifying multiple offsets turns off any per-pixel coloring.

When the coloring target includes atoms and/or cartoons, the atomic values can be assigned as a new atom attribute with name attr-name using newAttr, with a further option to raise the attribute-rendering dialog.

Color the specified model(s) by atom and/or surface vertex distance from a point. The point can be specified with center, where center can be:

• x,y,z (three values separated by commas only) - an arbitrary point
• an atom-spec of any combination of atoms and surfaces. The center of the bounding sphere of the specified items will be used.

The default is the center of the bounding box of the surface. The coordinateSystem option indicates that x,y,z specifications of center should be interpreted in the coordinate system of a reference model. N is the reference model number preceded by #. The default coordinate system is that of the model being colored.

Color the specified model(s) by atom and/or surface vertex distance from an axis. The axis is defined by any point on the axis and a direction. The point can be specified with center and the direction with axis, where axis can be:

• x - X-axis
• y - Y-axis
• z - Z-axis
• x,y,z (three values separated by commas only) - an arbitrary vector
• an atom-spec of exactly two atoms (not necessarily bonded or in the same model) or one bond. 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 default is the Z-axis in the coordinate system of the surface. The coordinateSystem option indicates that specifications of center and/or axis should be interpreted in the coordinate system of a reference model. N is the reference model number preceded by #. The default coordinate system is that of the model being colored.

Color the specified model(s) by atom and/or surface vertex distance from a plane, or topographic height. The plane is defined by any point on the plane and a vector normal to the plane. The point can be specified with center and the vector with axis. The coordinateSystem option indicates that specifications of center and/or axis should be interpreted in the coordinate system of a reference model. N is the reference model number preceded by #. The default coordinate system is that of the model being colored.

Color patches in surface models to match nearby specified atoms or markers. The range option indicates a cutoff (default 2.0) in physical distance units, typically Å. The autoUpdate option indicates whether to update the coloring of a surface automatically when its shape changes. The ~color command discontinues coloring by zone. Should it instead be something like:

color  surf-model  ~zone
- or -
color  surf-model  zone off

General Options

target  string
The target option allows coloring only a subset of the possible displays of a given atom, residue, etc. The string can be any combination of the following letters, without commas or spaces:

• a - atoms/bonds (halfbond coloring)
• l - atom labels and bond labels?
• s - surfaces (per-vertex colors)
• c - cartoons (per-residue segment colors)
• r - residue labels

The default target for multicoloring is all of the above, except as noted for specific methods. Residue values for coloring cartoons and residue labels may be derived from atomic values.

residueValues min | max | average | sum | primary
Cartoons are divisible into per-residue segments. When cartoons or residue labels are colored by volume, atom attribute, or distance, it is necessary to derive per-residue values from the atomic values. The residueValues option specifies how per-residue values should be derived: the minimum, maximum, average (default), or sum of the constituent atom values, or simply taken from each residue's primary atom (for example, the CA atom in an amino acid). I just made this option up. A worm-by-value command could work similarly. Maybe sum should not be an option, because then the residue range could extend beyond the atom range, with attendant complications for cmapRange. Instead we'd require using something like Chimera1 Attribute Calculator to create a residue sum attribute beforehand.

cmap  palette | value1,color1:value2,color2:...
Use the specified color mapping, which can be either a pre-defined palette (colors listed in ascending value order):

• rainbow (default) - blue, cyan, green, yellow, red
• redblue - red, white, blue
• cyanmaroon - #0f1bc7adcf5b (a dark cyan), white, #9eb820005eb8 (a dark maroon)
• gray - black, white
• a user-defined palette name

... or a series of value,color pairs (no spaces) separated by colons only. Values can be expressed directly on the scale of the data (cmapRange not used) or as fractional values 0.0-1.0 across a range of data specified with cmapRange. Values below the lowest given will map to the same color as the lowest, and values above the highest will map to the same color as the highest. Colors are interpolated (shaded gradually) between specified value-color pairs; discrete coloring can be achieved by specifying the same color for the upper- and lower-bound values of a “bin.” A color can be any color name that specifies a single color. In the case of attribute coloring only, the following terms can be substituted for the corresponding values:

min	minimum value among the specified atoms
max	maximum value among the specified atoms
mid	average of min and max
novalue	no value assigned for the attribute

A pair specified with novalue does not contribute toward the minimum of two value-color pairs because the corresponding color is not involved in any ranges; it is only used to color items without a value for the specified attribute.

cmapRange  low,high | full
What data values should map to the extremes of the cmap palette, or to values 0.0 and 1.0 when cmap value,color pairs are used. The low and high values should be separated by a comma only (no spaces). The full keyword indicates using the minimum and maximum values found at surface vertices (default for pre-defined palettes). When multiple models are colored in a single command, the full range is determined separately for each model. In that case, atomic structure colors wouldn't be on the same scale as colors on the corresponding molecular surface, because they are separate models. Such discordance could be avoided, however, by specifying the actual low and high values, or by coloring only one model or the other. If atoms were colored, the molecular surface could subsequently be colored to match with the zone method.

reverseColors true | false
Whether to reverse the order of the colors in the palette.

key true | false
Whether to start the Color Key tool, filled in with the appropriate colors and values, and set to Use mouse for key placement for creating/positioning the color key in the graphics window. The mouse setting can be toggled to allow moving models with the mouse.

capOnly true | false
Whether to color only surface caps and not the rest of a surface.

autoUpdate true | false
Whether to update the coloring of a surface automatically when its shape changes. For example, the shape of a surface cap changes as clipping is adjusted, and a molecular surface changes shape when it is recomputed with a different probe radius. This updating only accounts for changes in the shape of a surface, not changes in its position or orientation relative to other models.