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
• ​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)
  • Nov 5 2015 Greg will add Log message to remind users of stop function if no ongoing motion
• ~select/select (model activation/deactivation) → freeze/~freeze
  • Nov 5 2015 decided activation concept not needed in Chimera2
• window, focus → view spec (done)
• windowsize → window
  • Nov 5 2015 deemed unnecessary now that it can be truncated (since the window command is not present)
• scale → zoom (done)
• display/modeldisplay → show/hide
  • Nov 2 2015 agreed to proceed with this, with ~show as an undocumented alias to hide
• alias (target-defining function) → namespec (previously agreed upon)
  • Nov 5 2015 for the other (command-defining) function of alias, agreed to change syntax for listing and deleting aliases, and to use analogous approach for other commands that also allow the user to assign names to definitions (namespec, colordef, etc....view is already that way)
    • alias → alias list
    • ~alias name → alias delete (name|all)
• 2dlabels → title (done)
• ribbon → cartoon (done but we still have ribbon as a synonym)

Late summer release

Initial versions (not necessarily full implementations) of:

• open (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)
  • Nov 5 2015 intend to add keywords from to specify database for web fetch and format which could be useful for both fetch and local files, and possibly other keywords; retain colon syntax as alternative
• close (done for models; might want to add session and/or all keywords later)
• exit, quit or equivalent (done)
• something like Chimera1 focus and/or window (rename as view) (done)
• display, modeldisplay (plan to replace with show/hide)
  • as of Nov 2 2015 implemented as display and its options
  • Nov 5 2015 some discussion as to whether a show-only option (like Chimera1 show) is possible; there is an undocumented only option but EM and TG think it may be too confusing in combination with the other options of the command
• 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 the above is done but no controls for width, thickness, cross-sectional shape (would this be in cartoon or style?)
• surface solvent-excluded molecular surface (done)
  • see SurfaceCategories discussion of categories and command design
  • see ​surface command mockup based on subsequent discussion
  • Nov 5 2015 plan to add ~surface as undocumented alias to surface hide, if possible
• 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)
  • Nov 5 2015 volume has been ported over from Chimera1 but Tom G will check over it to see which parts are functional (we know at least a few things related to commas are problematic in Chimera2)
• some way to adjust subdivision/smoothness
  • Nov 5 2015 done for atoms/bonds (set subdivision) but not cartoons
  • done for molecular surfaces; surface has grid-spacing, resolution options

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) (done, some via set, some via other commands such as lighting)
  • 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
• 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 (done)

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 (done), atom type
• 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)
    • Nov 5 2015 single-layer done but there is no multi-layer option, thus no control to switch between them
• 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 clipped objects, including surfaces, cartoons, atoms/bonds (set if global, setattr if per-object; could also be an option in clip and/or mclip)
  • Nov 5 2015 surfaces first, the other things may come later
• pseudobonds that could be intermodel (implying need for distance)
  • Nov 5 2015 TomG says there is support for these but no feature that creates them
• 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
      • Nov 5 2015 unresolved, TomG would like to retain the flexibility of supplying the parameter with or without keyword, yet not show both of those ways in the usage info
    • 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 (done), 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?)
  • Nov 5 2015 done for the display and graphics icons; menu doesn't have any actions yet anyway!

Highly desirable

Again listed but not necessarily as commands:

• repr, ribrepr, ribscale, surfrepr (maybe consolidate into 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):
  • atom/bond stick, bs, sphere (implemented via style; do we need a line or wire?)
  • 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
  • Nov 5 2015 decided to leave on the table, revisit when we figure out what comprises a cartoon style and have more of them to play with
• 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
  • merge into maincolor command, see ​color command mockup
  • need to add more palettes, including color-blind-friendly
• 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
• surface style option mesh
• 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