Needed Command Functionality

Chimera2 command functionality needed for early release(s) based on EarlyReleaseRequirements.

This is somewhat high-level; more detailed guidelines and examples are in ​Chimera2 Command-Structure Thoughts. See also ​Chimera2 User Guide, manpage mockups:

• ​atomspec
• ​surface
• ​color (omnibus, including color-by-value; currently I favor this over separate color-by-value ​vcolor)
• ​transparency
• ​alias (we decided to make this namespec)
• ​macro (we decided to leave this as alias)

Potential renaming of Chimera1 commands (up for discussion):

• Chimera1 freeze → Chimera2 stop (done) (the latter no longer used for exiting the program; if no ongoing motion stop should remind user of this!)
• ~select/select (whole-model activation/deactivation function) → freeze/~freeze
• window, focus → view spec (done)
• windowsize → window
• scale → zoom (done)
• display/modeldisplay → show/hide
• alias (target-defining function) → namespec
• 2dlabels → title (done)
• ribbon → cartoon (done but we still have ribbon as a synonym)

Late summer release

Initial versions (not necessarily full implementations, could be partial) of:

• open (suggest same general syntax as Chimera1, possibly adjusting prefixes; covers both local files and web-fetch)
  • for this release: PDB, PDB/mmCIF, density maps, sessions
  • as of Nov 2 2015 done for the above except sessions
  • prefixes (e.g. pdb: should allow opening file with non-standard suffix as that format; currently only treats the string as an ID code)
• close (done for models; might want to add session option later)
• exit, quit or equivalent (done)
  • maybe stop should instead work like Chimera1 freeze (stop motion), and freeze could be repurposed for deactivation (the older function of Chimera1 ~select)
• something like Chimera1 focus and/or window (although I might rename as view) (done)
  • window may be better for windowsize specification
• display, modeldisplay (maybe replace with show/hide)
  • this could control pseudobonds indirectly if they are hidden automatically when endpoint atoms are hidden, but we may want to make it act on them directly, or else setattr (see below) might be the only way
  • as of Nov 2 2015 implemented as display and its options (EM: seems good to me)
• cartoon including spline, path-smoothing, and any other whole-chain parameters as options
  • see ​ribbons writeup
  • for this release, just ribbons (not pipes/cylinders or worm-by-attr)
  • as of Nov 2 2015 partial implementation: protein only, no controls for style (width, thickness, cross-sectional shape; would this be in cartoon or style?)
• surface solvent-excluded molecular surface
  • see SurfaceCategories discussion of categories and command design
  • see ​surface command mockup based on subsequent discussion
  • as of Nov 2 2015 a fairly extensive surface implementation including calculation options, showing/hiding down to the level of atomic patches
  • EM remaining thoughts:
    • do we want to add ~surface as synonym for surface hide?
    • do we need mesh or dot options, and if so, via what command (surface or style or other?)
• repr, ribrepr, ribscale, surfrepr (maybe consolidate into a new style command, generalizing ribbon to cartoon as per ​ribbons writeup, and including pseudobonds; I'm not sure consolidation is better, however, since consolidation makes longer commands, and these will be used frequently); styles for this release:
  • atom/bond stick, bs, sphere (implemented via style; do we need a line style?)
  • pseudobond dashedStick (since TomG already added it; could be named something else)
  • stick and line (if we even have the latter) would apply to both atoms/bonds and pseudobonds
  • surface (volume isosurface and molecular surface) solid, mesh
  • a default style or a few possibilities for ribbons/cartoons (say smooth and edged, maybe flat, with default scaling; tube should be easier to implement than those, even though it's down in the Would be nice section)
  • each style could have sub-options (e.g. stick radius), or if it's too complicated to include them in the style command, they could be adjusted with setattr
  • see ​command examples for more detailed thoughts
• color (just the first usage with single colorname in the ​color command mockup (done)
  • leaving color-by-attr as in rangecolor, color-by-scalar-field as in scolor, and rainbow for later
• volume control over isosurface display (redundancy with show/hide/color etc. OK with me, but should review structure and keywords vs. the negotiable ​command guidelines)
  • I think it's done, in that volume has been completely ported over from Chimera1
• some way to adjust subdivision/smoothness; any global setting could be covered by set (see below) and any attribute by setattr, but there could also be options in surface, volume, cartoon and/or a top-level quality command

Extremely useful catchalls that I suggest retaining as permanent commands even though there will be some redundancy:

• set global settings
  • for this release: silhouettes, background color, depth-cuing amount and color, interactive shadows, lighting (ambient occlusion, ambient-only, N-point)
  • if many sub-options, e.g. lighting, could make a separate top-level command; also keeping a redundant but longer set command is OK with me
  • as of Nov 2 2015 at least some of this is done, some via set, some via other commands such as lighting
• setattr attribute values
  • need some way for the user to look up the names and possible values of attributes

For this release, GUI-only or commands? (eventually they should be commands)

• select (including up/down) see ​Chimera1 selection cascades
  • as of Nov 2 2015 a good select command but hierarchy is very limited compared to Chimera1 (presumably will be expanded later) and command doesn't include up/down options
• save session with restore covered by open, or session (save|restore)
• save image with supersampling option

Command accoutrements:

• decide whether we will have ~commands (consensus seems to be yes)
• decide on keyword conventions (see ​command guidelines)
• decide on what kinds of colorspecs are allowed, e.g. can color names include spaces?
  • as of Nov 2 2015 basically done but we could consider adding some easier-to-type alternatives later
• set of built-in color names (done)
• built-in specs solvent, ions, ligand, main, helix, strand, coil (these specific ones are done)
• built-in specs for element and/or atom type
  • element symbols are done/available
• basic hierarchical atomspecs (see ​Chimera2 atomspec writeup)
  • as of Nov 2 2015 mostly done, lacking a few things like wild cards
• some way to look up attribute names/values for setattr

December release

The following functionality is listed for the December release, but not necessarily as commands:

• transparency (similar to color; takes care of individual settings, whereas set or another command would be used for related global parameters) (done)
  • see ​transparency command mockup
  • single-layer transparency (set or other command control)
• cofr or focus-like command (view+cofr) for setting fixed center of rotation (done)
• clip, section, thickness (suggest combining into single command to control global clipping, say clip or gclip)
• mclip per-model clipping, plane or slab
  • capping of all solid objects, including surfaces, cartoons, atoms/bonds (set if global, setattr if per-object; could also be an option in clip and/or mclip)
• pseudobonds that could be intermodel (implying need for distance)
• active/~active, freeze/~freeze or some other command to control model activation for motion (in Chimera1, freeze is something different)
• help to bring up command documentation (done)
  • however, the usage results for almost all commands need improvement
    • prevent both the keyword and non-keyword specifications for some parameter being shown, e.g. usage select
    • get rid of seemingly incorrect nesting, e.g. usage cofr
    • do we want to show several options that aren't yet implemented, e.g. usage color or usage cartoon
• delete (done)

Expanded functionality of existing commands:

• open (including fetch) cellPACK, which would elicit interface for exploring hierarchy
• save reply log, command history
  • as of Nov 2 2015 the log can be saved via the log command and the command history can be saved via its GUI; save itself needs work (session-saving not yet done)
• select all, clear, invert
• set and setattr as mentioned in the previous section

Command accoutrements:

• command documentation (in progress, done for several)
• full atomspecs (see ​Chimera2 atomspec writeup)
• translation of menu actions into commands (if needed for full logging and replay... maybe it's not?)
  • done for the display and graphics icons, not for menu items as far as I know

Highly desirable

Again listed but not necessarily as commands:

• smart molecule display
  • IMO, this implies the need for preset with at least two interactive options: one with all atoms shown and one similar to the smart display; I'd vote for a third one with molecular surface(s) colored to match the corresponding chain's ribbon, possibly transparent
• color-by-attr as in rangecolor, color-by-scalar-field as in scolor, and color sequentially as in rainbow
  • EM: I favor merging with main color command, see ​omnibus color command mockup ( ​color-by-value command mockup is less refined, I stopped working on it)
• defattr would be useful for reading in custom attributes

• findhbond
  • consider option to find salt bridges only
• define geometric objects based on atomic coordinates: axes, planes, centroids, ellipsoids
• shape or other way of defining geometric objects arbitrarily
  • I suggest BILD-like position specification; Chimera1 shape position specification is much too difficult
• scene save, restore, list
• label (possibly merge with rlabel; takes care of individual settings, whereas set or another command would set related global parameters)
  • command control of font/fontsize would be nice
• 2dlabels (has been renamed title)
  • could merge create/change operations into a single operation, possibly without keyword (something like "title t1 text Hello xpos .1 ypos .1”)
  • EM: I think it's been ported over from Chimera1 but I haven't tested or documented it
• colorkey

Expanded functionality of existing commands:

• style options for pseudobonds: dotted and dashed sticks, dotted and dashed lines (but do we really need the latter any more?)
• fancy-shaped selection and clipping (Chimera1 has octant stuff in vop subcommands)
  • potentially options of select, clip, mclip, e.g. to use some previously defined 3D geometric object (an enclosed shape, I assume)
  • projections of 2D shapes or outlines as mentioned in the Would be nice section could also be used
  • EM: I think vop has been completely ported over from Chimera1
• volume
  • isosurface smoothing
  • EM: I think volume has been completely ported over from Chimera1, including the surface smoothing options
  • sop hideDust equivalent (could be separate command, but is this used for anything other than isosurfaces?)
• save PDB, volume data format(s), graphics format(s), etc.
• set (or other command, e.g. background) global settings: background color gradient, multiple-layer transparency (correctly rendered even for multiple models)
• setattr (or other command, e.g. material) individual attributes: material properties
  • EM: there is a material command but I haven't explored it

Command accoutrements:

• more built-in specs like protein, nucleic acid, functional groups, amino acid categories, atom types, etc.

Would be nice

Again listed but not necessarily as commands:

• nucleotides base-slab, sugar-tube, and ladder options
  • need better defaults than in Chimera1, at least for smart display
• findclash (also needed for coloring surface interaction patches)
  • consider facilitating the use of contact defaults (in Chimera1, the overall defaults are the clash defaults, so to use the GUI's contact defaults you have to look up the two values in the documentation and specify them individually in the command)

Expanded functionality of existing commands:

• open Chimera1 sessions (session conversion)
• preset publication options
• cartoon options for pipes and planks
  • that's what the EarlyReleaseRequirements says, but I don't think box-shaped planks are needed (or even desirable) if there is an option for well-smoothed strands similar to our B spline strands in Chimera1; beta-sheet curvature is the rule rather than the exception
  • cylinders (pipes) could be a distinct option for helices and should integrate with helix axes, i.e. the pipes=axes could be used in measurements
  • see ​ribbons writeup
• cartoon style option tube (or something like that, similar to our current rounded licorice)
• surface
  • provisions for multiple surfaces on same atoms, including SAS and/or SES
    • as of Nov 2 2015 done-ish, can have multiple surfaces on same atoms, but there is no SAS capability
  • patch boundary-smoothing, see smoothBorders in the ​surface command mockup
    • as of Nov 2 2015 done-ish, sharpBoundaries option fulfills similar role
• atoms/bonds ring fill, aromaticity, and bond multiplicity display (sub-options of style stick and/or settable with setattr; could also apply to style line, but do we still need that style?)
• smart clipping, leaving individual objects such as multiscale surfaces whole
  • potentially options of clip, mclip
  • in Chimera1, certain things are already only wholly selectable (surface pieces, etc.), but if we become able to select subparts/triangles within surfaces, it could also be an option of select
• set (or other command, e.g. background, lighting, camera) global settings: background images, lighting contrast, camera modes (orthographic, stereo)
  • as of Nov 2 2015 some of these are done, camera command
• setattr per-model silhouettes (remove silhouettes from global settings?)

GUI-only, or do we need commands?

• interactively adjustable light positions
• for surface patch boundary smoothing, individual triangle-hiding or hand-drawn boundaries
• hand-drawn or 2D-shape custom silhouettes (2D outlines? perhaps could be an option of 2dlabels)... also ties in with the fancy-shaped selection in the Highly desirable section

Eventually

• morph
  • atoms/bonds
  • maps
• coordset-like trajectory playback but also the ability to show more than one frame at a time
• vseries (done)
• other motion-scripting and frame-argument commands (see ​Chimera1 movie-related commands)
  • as mentioned above, could make Chimera2 stop act like Chimera1 freeze, and Chimera2 freeze deactivate models for motion like Chimera1 ~select
  • I'm hoping for saved positions and commands for traversing them: savepos/reset/fly... these are useful and much lighter-weight than scenes
    • as of Nov 2 2015 savepos/reset partial implementation in view command
  • although Chimera1 has scenes, it doesn't have command controls analogous to the above for fully scripting timeline playback; our designs for transition and animate commands were never implemented (see ​animation commands writeup)

Uncategorized (priority not yet discussed)

• a command to make user-defined targets (like Chimera1 namesel)
  • we decided to name this namespec (see ​alias command mockup) with currentOnly option to distinguish the evaluate-now or evaluate-upon-use types
• a command to make user-defined commands (like the action-defining part of Chimera1 alias)
  • we decided to keep the name alias for this function (see ​macro command mockup)
  • as of Nov 2 2015 we have this command but syntax not fully resolved
• matchmaker or equivalent
• match or equivalent