Chimera2 Command-Structure Thoughts

May 6 2015 gestalt conclusions after coming up with and discarding many command-revision ideas as logically flawed:

• I'd been mentally overemphasizing consolidation. Consolidation actually tends to decrease ease of use.
• By and large, Chimera1 commands are actually much more well thought out and honed into usability than we give them (ourselves) credit for.
• The set/setattr approach is growing on me. You just know what a setting or attribute is called and you set it. Thus there are as many potential commands as settings. In many ways, this is simpler than having fancy commands with numerous keywords to get to these individual underlying settings.
• I'm still not sure whether (atom)specs should always be at the end or whether a more Englishy order where they immediately follow command/subcommands is better, at least for commands without structured spec requirements (where the target is open-ended and could be blank).

Potential components of a command:

1. command or command-subcommand name (e.g. color, measure area)
2. required arguments in required order
3. optional keyword-value arguments in any order

Atomspecs (or other target specs, e.g. volume models, surface pieces):

• could be in either of the argument types above (#2:required/non-keyword or #3:optional/keyword) or at the end
• if #2, typically a basic hierarchical spec #/:@ (e.g. match, angle, vop add)
• blank=all compatible with #3 (keyword default=all) or placement at the end ** need to check w/ test command if also true for case #2 **
• complicated boolean with spaces can be used; with greedy parsing, need quotes around back-to-back specs (e.g. match) but not isolated spec or spec indicated by keyword

See also: Chimera2 User Guide, Chimera2 atomspec writeup, Chimera2 commands for initial release (wiki), Chimera2 manpage mockups:

• surface
• color (omnibus; exploratory, but I currently favor it over a separate color-by-value vcolor)
• transparency
• macro (will remain as alias)
• alias (will be namespec instead)

• Chimera1 freeze → Chimera2 stop (the latter no longer used for exiting the program) (done)
• window, focus → view (done)
• windowsize → window (deemed unnecessary, now that it can be truncated)
• scale → zoom (done)
• display/modeldisplay → show/hide (agreed to do)
• 2dlabels → title (I'm neutral on this one, but Eric and TomG have discussed it) (done)
• ribbon → cartoon (done but we still have ribbon as a synonym)

General Command Guidelines

• where reasonable, group functions as subcommands of single main command (e.g. measure, volume)
• command and keyword truncation allowed for all commands
• truncation-friendly keywords (where reasonable, avoid starting with same long string)
• analogous keywords of different commands should be the same
• same synonyms for T/F everywhere
• same kinds of colorspecs (rgbs, hex codes, names, names with spaces?) allowed in all commands with color arguments
• keyword policy: 5/14/15 agreed to use camelCaps in command documentation (although users wouldn't have to capitalize anything) as per Chimera2 ticket #71

Further notes:

• consider lumping ribbons, tubes, and pipe/plank-type representations as “cartoons” (see ribbons writeup)
• consider putting things in more English-y order, for example:

  command: color C green
  menu: Show/Hide... Cartoons
  menu: Style... Cartoons... [cartoon style options]

• consider consolidating commands, e.g. repr/ribrepr/ribscale/surfrepr could become style, see examples below; HOWEVER, I keep waffling about this because we need easy-to-type commands for such frequently used functionality, and consolidation makes for fewer but more complicated, longer (harder-to-type) commands.
• below I suggest combining display/modeldisplay into show/hide... to really go all-out with consolidation, it could also cover ribbons and surfaces; however, the problem is that while display and ribbon in Chimera1 just toggle atom/bond and ribbon segment visibility and could be combined, surface includes many other things, like calculation parameters. Also, if cylinder and spline options are combined with ribbon and it becomes cartoon (or something like that), it will also become more complex.
• will there be a correspondence between menu and command structure? When I used SYBYL near the dawn of time, there was a direct translation between menu and command, so if you saw how to do it in the menu, you could create a command (although the resulting command was quite long). I don't know if it is still like that, and I don't remember the details, but commands could be something like “Menu.Submenu1.Submenu2.Action.” I believe there were also shorter commands for the same thing.

Examples

style  spec  [atoms | cartoon | surface | pbonds] style-type style-type-options
- or maybe -
style  spec  style-type1 [style-type1-options] [style-type2 [style-type2-options]] ...

...or, if including the sub-options is too complicated:

style  spec  [atoms atoms-style] [cartoon cartoon-style] [surface surface-style] [pbonds pbonds-style]
- or -
style  spec  style-type1 [style-type2] ...

• consolidates repr, ribrepr, surfrepr
• atom (default) is short for atoms/bonds, their types could be our current repr choices, and sub-options could include stick radius, ring fill and bond multiplicity display
• cartoon is a generalization of ribbons (see ribbons writeup); maybe we could create some default styles that combine our current notions of cross-section and scaling, plus at least one more for cylinders, or use the current ribrepr choices (plus something with cylinders) as the types, with scalings or individual scaling settings (strand width, helix width, helix cylinder radius, etc.) as further options; path-related parameters should go into the cartoon command instead
• style should cover individually settable styles (otherwise spec is irrelevant); set or other command would be used for global settings
• in the second of each pair of options above, atoms etc. is not specified; instead, each style-type would apply only to the relevant items:
  • stick/sphere/bs and line (or wire) would affect atoms/bonds, with possible further options including stick radius, bond multiplicity display, ring fill, line width
  • stick and line would also affect pseudobonds
  • dotted/dashed/dotdash (or maybe dottedStick/dashedStick/dotdashStick or dotStick/dashStick/dotdashStick if there will also be dottedLine/dashedLine/dotdashLine or dotLine/dashLine/dotdashLine) could affect pseudobonds only or both bonds and pseudobonds; may need some way of distinguishing pseudobonds from regular bonds via spec (Chimera1 only via sel, but maybe pseudobonds could have a different model number or something like that in Chimera2), with possible further options of dot/dash spacing, separation
  • mesh/solid would affect surfaces (dots? don't want confusion with dotted if item-type is inferred rather than specified directly)
  • cartoon styles (say smooth, edged, maybe flat showing secondary structure, tube with constant radius) would affect cartoons
    • attributes could affect multiple styles, e.g. cartoonThickness would affect all non-flat styles; helixWidth, strandWidth, arrowWidth would affect secondary-structure-showing styles; helixPipes true could instead use helixRadius value unless helixRadiusAuto was also true (these could probably be chain-level attributes although the style whould be residue-level)
  • if including further (sub)options of individual styles in the style command is too complicated, they could be covered by setattr
  • we could consider folding target into style names but allowing them to be truncated, e.g., solid = solidSurface, smooth = smoothCartoon, and so on
• could include nucleotide styles and options, but that could become hairy; nucleotides may be better as a separate command
• nucleotides could redundantly control ringfill for nucleic acid bases, or it could be limited to base-slab, sugar-tube, and ladder

cartoon spec cartoon-options

• cartoon is a generalization of ribbon (see ribbons writeup), mainly toggles cartoon display
• the cartoon-options could include spline and path-smoothing parameters à la ribspline, maybe whether cylinders are shown, maybe whether backbone atom display is simultaneously enabled à la ribbackbone; hard to decide what should be specified at initial display vs. changed later with style (analogous to surface vs. surfrepr)
• I lean toward keeping cartoon-by-attr (worms) separate
• Scooter suggests a preceding (show/hide), see below

surface spec surface-options

• see surface command mockup
• see discussion on wiki of surface command and categories
• if there can be multiple surfaces for the same atoms, how is the proliferation of surface models controlled?
• Scooter suggests a preceding (show/hide), see below

show/hide [atoms | models] spec

• consolidates display and modeldisplay
• should it also act on pseudobonds directly, or is indirectly (autohidden when end atoms hidden) enough? will pseudobond groups have their own model numbers?
• replaces our current show, which I find dispensible
• in this case it seemed more Englishy to have the spec at the end, but atoms is default and can be omitted
• I thought about including ribbons/cartoons and surfaces (potentially per residue and per atom, respectively), but that leaves the dilemma of whether those objects are persistent and can merely be display-toggled, or whether this would require regenerating them with some set of parameters that would otherwise be specified in the cartoon or surface command... Scooter proposes consolidation analogous to the first proposal for style, except with spec after the level, but I'm not that enthusiastic about it:
         show/hide [atoms | models | cartoon | surface | pbonds]  spec  level-specific-options

color spec colorspec [target alscrnmbpd]
transparency spec percent [target alscrnmbpd] [ frames N ]
  (target: atoms/bonds, atom/bond labels, surfaces, cartoons, residue labels, nonmolecular models, molecular models, bonds-only, pseudobonds, distances and other pseudobond labels; default further limited to als when spec contains only explicitly specified atoms)

• just run target options together into a string, similar to Chimera1 swapaa criteria except that order is irrelevant
• presumably surface models could be specified by their (unique?) model numbers, but s is convenient for coloring all surfaces
• see color command mockup; above is just the first type of usage (single-color) but I also propose merging with all the multicoloring-by-value functionality
• vcolor command mockup is color-by-value only (deprecated)
• see transparency command mockup, analogous to the single-color usage of color
• although surfaces are included in these general command examples, I'm not opposed to having display/style/coloring of volume isosurfaces also controlled by a more specific volume command since it is useful to specify them in parallel with contour level

setattr  spec  level  attr-name attr-value
- or (Chimera1 order) -
setattr  level  attr-name attr-value  spec

set setting-name setting-value
- or -
set  category  setting-name1 setting-value1 [setting-name2 setting-value2 ...]

...could be one value at a time, or a group of related values (e.g. the subcommand could be a category and the subsequent options the settings in that category):

set transparencyLayers (single | multiple)
set transparency [layers single | multiple] [angleDependent T | F] [transp-parm3 value] [transp-parm4 value] ...
set bgColor color-spec
set background [ solid color-spec | gradient gradient-spec | image image-spec [placement-options]] [transparent T | F]