Doc strings / optional arguments for aliases

[olibclarke@…]

The following bug report has been submitted:
Platform:        Darwin-18.6.0-x86_64-i386-64bit
ChimeraX Version: 0.91 (2019-06-07)
Description
Hi,

Would it be possible to add docstrings (a la python) for aliases? I often write quite quite complicated aliases for Chimera (see example below), and for reuse by others it would be handy if when the user ran the command without arguments it output a docstring(if present) to either the log or the bar below the command line where error/warnings are displayed.

It would also be great to have optional arguments - so an alias has some default behavior which can be modified by an argument if present, but otherwise runs without it. For example, making a modified rainbow command  (with an non standard palette) that defaults to per residue coloring, but can take an argument to specify per chain or per model coloring.

Example alias for fitting two maps (or model and map) in zone around center of rotation. Useful for compring maps that are locally similar but have overall conformational changes:

#locally aligns two maps within a given radius of the center of rotation. Assumes maps are already more or less aligned.
#Usage: local_fitmap #mapid1 ($1) #mapid2 ($2) radius ($3)
alias ^local_fitmap ~sel; ac mc; vop zone $2 sel $3 modelid 10000 minimalbounds true; fitmap $1 #10000; close #10000; close sel; modeldisplay $2

Cheers
Oli

Log:
Startup Messages  
---  
note | available bundle cache has not been initialized yet  
  

> camera ortho

> cofr centerOfView

> volume voxelLimit 100000 showPlane false limitVoxelCount false
voxelLimitForOpen 10000

> alias crosshairs_on cofr centerofview showpivot 5,0.2

> alias crosshairs_off cofr centerofview showpivot false

> alias cootmode volume style mesh step 1 squaremesh false meshlighting true
twosidedlighting false capfaces false; surface cap false; size stickradius
0.05; ~rib; color gold target a; color byhet; lighting flat; lighting
depthcuestart 0.2 depthcueend 0.7; set silhouettes false; set subdivision 1;
crosshairs_on; color #3333851effff target s; style stick; set bgcolor black

> alias cootmode_white volume style mesh step 1 squaremesh false meshlighting
true twosidedlighting false capfaces false; surface cap false; size
stickradius 0.05; ~rib; color orange target a; color byhet; lighting flat;
lighting depthcuestart 0.2 depthcueend 0.7; set silhouettes false; set
subdivision 1; crosshairs_on; color #00000000cccc target s; style stick; set
bgcolor white

> alias carve surface zone #* nearatoms sel distance $1 maxcomponents 1

> alias uncarve surface unzone #*

UCSF ChimeraX version: 0.91 (2019-06-07)  
© 2016-2019 Regents of the University of California. All rights reserved.  
How to cite UCSF ChimeraX  

> open /Users/oliverclarke/Dropbox/Downloads/model_moved.pdb_modified.pdb

Summary of feedback from opening
/Users/oliverclarke/Dropbox/Downloads/model_moved.pdb_modified.pdb  
---  
warnings | Duplicate atom serial number found: 819  
Duplicate atom serial number found: 820  
Duplicate atom serial number found: 821  
Duplicate atom serial number found: 822  
Duplicate atom serial number found: 823  
103573 messages similar to the above omitted  
  
Chain information for model_moved.pdb_modified.pdb #1  
---  
Chain | Description  
A B G I | No description available  
F | No description available  
H J O | No description available  
  

> ui mousemode rightMode clip

> ~clip

> surface cap true

> set subdivision 10

> set subdivision 1

Missing or invalid "objects" argument: empty atom specifier  

> view cofr false

> help view

> alias focus view cofr false

Unknown command: wejlkfh  




OpenGL version: 4.1 ATI-2.9.26
OpenGL renderer: AMD Radeon Pro 580 OpenGL Engine
OpenGL vendor: ATI Technologies Inc.

[Eric Pettersen]

Some of these aliases would make sense as presets instead (user-defined presets possible as of the most recent daily build). Regardless of whether they are presets or not, you can always output information to the log with the "log" command.

[olibclarke@…]

Ah - I did not know about the log command! I will play with that

Oli

[Greg Couch]

Added "alias synopsis name text" that works for a previously added alias.

It doesn't let you set symbolic names for $1, etc., so that will need to be in the synopsis.

[Greg Couch]

Tomorrow's daily build will have an "alias usage" command. This supersedes the "alias synopsis" command. Type "usage alias usage" to see the syntax. You can give a URL to the command name that should link to documentation. The synopsis can be set, just like the "alias synopsis" command (which still exists as an alias for now). And the name and description can be set for each argument -- just give the name to change the name, or give "name:description" to set the name and description.

Also, the alias command has changed to allow for optional parts, using $[ and $]. They can not be nested. The rule for optional parts is that all of the referenced $# arguments have to be given for the optional part to show up.

For example:

alias foo xyzzy $1 $[plugh $2$]

gives usage foo:

foo $1 [$2]
    — alias of "xyzzy $1 $[plugh $2$]"
  $1: a text string
  $2: a text string

Then followed by:

alias usage foo synopsis "some info" $1 "maze:twisty passages" $2 alike

gives usage foo:

foo maze [alike]
    — some info
  maze: twisty passages
  alike: a text string

And foo 42 expands to xyzzy 42, and foo 42 93 expands to xyzzy 42 plugh 93.

Feedback welcome and encouraged :-)

[olibclarke@…]

oh this sounds great, thanks Greg! I will add for my aliases as soon as it is available!

Cheers
Oli

[Elaine Meng]

Maybe this is a separate bug, but when I try it in the daily and then show the usage for my alias, it gratuitously appends the usage for existing commands "open" and "open formats".

For example, I had an existing alias "segtest" so I tried this command:

alias usage segtest synopsis "bloppity blop" url https://www.cgl.ucsf.edu/home/meng/index.html

Then when I use "usage segtest" I get this in the Log:

[Elaine Meng]

Added by email2trac

[olibclarke@…]

Yes - I saw the same thing when I tried it for mine

[Eric Pettersen]

That isn't even the usage that you get from "usage open" because the open-command machinery registers it's own "usage open" command in order to give far better information than generic usage would give. That's actually the generic information you're seeing for "open".

[Eric Pettersen]

Is it impossible to get usage for subcommands? I can't seem to get usage for "open formats" even if I use quotes.

[olibclarke@…]

Struggling a little bit with the syntax here. I have an alias:

symclip: alias of "cofr centerofview; clip near -$1 far $1 position cofr"

And I would like to set the usage, so I try:

alias usage symclip synopsis "Clips symmetrically in a slab around the center of rotation." $1:"slab width

But this doesn't work. The syntax of usage is given as:

alias usage name [synopsis a text string] [url a text string] [$1 an argument[:description]]

But I am clearly interpreting the syntax wrong - would it be possible to provide an example of setting the usage in a case where one wants to describe the arguments?

Ceers
Oli

[Elaine Meng]

It took me a fair amount of trial and error, I just wrote a super-simple example, see the bottom of this page:

https://www.cgl.ucsf.edu/home/meng/chimerax/vdocs/user/commands/alias.html

[olibclarke@…]

Ah that makes it a lot clearer, thanks Elaine! I have it working now :)

[Greg Couch]

Currently the usage for an alias shows the usage for the command the alias is aliased to after the usage for the alias itself. So presumably, the alias for segtest expanded to "open ....", which is when the usage for open showed up next. That feature is confusing in this case.

[Elaine Meng]

I think it's a bug, not a feature  :-D

My original alias:

alias segtest open 0557 from emdb; vol threshold #1 min 0; vol scale #2 value uint8; open 6nzk

[Greg Couch]

Made several changes:

1. removed the 'alias synopsis' alias
2. no longer show the usage of the first command that the alias uses
3. don't show an alias synopsis by default
4. show what the alias is defined as after the usage

[Greg Couch]

The command should be:

alias usage symclip synopsis "Clips symmetrically in a slab around the
center of rotation." $1 "slab width"

Note there is no colon after the $1.  $1 is the keyword saying the
following argument is for positional argument 1.  If you want to give
both an argument name and an argument for a positional argument, then
instead of "slab width", use "slab width: a description".  Argument
names for commands in ChimeraX normally do not have spaces in them.  I
will add code to canonicalize "slab width" to "slabWidth".

-- Greg

[Elaine Meng]

OK I guess I see what you are saying, it is just an illustration of the sentence I did not understand.

However, I don't like that behavior with more than one argument in a single set of brackets, because as far as I can tell the user will be blissfully unaware that some option is actually being ignored when they fail to give all of the optional arguments; there is no Log message to that effect.

For example, if I do this

alias myzone zone clear; view; zone $1 $[residueDistance $2 label $3$]; view $1:<8

and then give only $2 but not $3

myzone :12 25

according to your explanation (if I understood it) I get a 5-angstrom zone (default).... but there is no message in the Log that my 25 was being ignored. In this case I chose something visually obvious that I was getting 5, not 25, but somebody might have computational steps or use this as part of a long script and so they could be getting some very unexpected results.

For that reason it might be better to avoid having multiple arguments in a single optional bracketed section.

Elaine

[Elaine Meng]

I added another example to illustrate this, but it's kinda blechh.

<https://www.cgl.ucsf.edu/home/meng/chimerax/vdocs/user/commands/alias.html#optional>

[Greg Couch]

Hi Elaine,

You're absolutely right that having multiple positional arguments in an
optional section of an alias can be confusing and should be avoided.  It
needs to work for robustness, but it doesn't necessarily need to be
documented with an example.

And I would rename the Optional Arguments part of the documentation as
Optional Sections.  And in the first sentence of that paragraph, change
argument(s) to section(s).  The positional arguments are only optional
arguments if they only appear in the optionally expanded parts of the
alias (and all of the subsequent positional arguments are optional). 
The optional-ness can be verified with the usage command.

And note the changed output of the usage command for aliases.  By
default there is no synopsis and the alias definition is shown afterwards.

-- Greg

[Elaine Meng]

Hi Greg,
Thanks for checking the "alias" docs!  As you suggested, I changed "optional argument(s)" to "optional section(s)" in a few places.  I'm all in favor of the new output of the "usage" command, as it seems much better to always show the definition regardless of whether there is a synopsis.  I don't think there any documentation changes associated with that.
Elaine

[olibclarke@…]

Hi Greg,

Thanks so much for implementing the usage docstrings - I am gradually adapting this for all of my aliases! One suggestion to make this more accessible/frictionless for users - when a alias is invoked without the required arguments or otherwise triggers an error, would it be possible to print the usage info to the log, in addition to the error?

That way, even if the user is unaware of the "usage" command", they will get the benefit of the docstrings when they need them?

Cheers
Oli

[olibclarke@…]

Added by email2trac

[olibclarke@…]

Also, is there any way to display usage info for all aliases at once?

Currently, if I run "usage all" it shows usage info for all commands - internal and I presume user defined - but if I just want to show usage for the ones in "alias list"? Perhaps an "alias list usage" command would be useful? Or "usage aliases"?

Cheers
Oli

[Greg Couch]

That's reasonable. I'm partial to "usage aliases".

[olibclarke@…]

Great thanks! Another thought in the same vein - if the user types \u201chelp\u201d followed by an alias, perhaps that could redirect to show usage for that alias? Not sure how much work this would be to implement so ignore if impractical 

[Greg Couch]

FYI, 'help command-name' already shows the usage if there is no associated URL. And that works for aliases too.

[olibclarke@…]

Hi Greg - this doesn't work for me. If I try "help local_fitmap" (for which I have a usage string defined) it doesn't show the usage, it shows the url for the first command in the alias (in this case "select")

[Greg Couch]

Ah ha. Yes, help was being too helpful for aliases. That is fixed. Also implemented "usage aliases" in [develop a9c00efb0]. The changes will be in the next daily build.

[olibclarke@…]

Thanks Greg!

One more thought. On small screens (laptops) users will often run ChimeraX with the log either closed or minimized, so as to maximize the are available for visualization/interaction. 

In this case, if I type say "usage local_fitmap" there is no indication in the UI that anything has happened, which may be confusing.

Would it be possible to print a message to the status bar, below the main window (see attached), where errors are printed, indicating that usage info has been printed to the log, to alert users that they should look there? (Not sure how complicated this is, so please ignore if impractical)

Cheers
Oli

[olibclarke@…]

Added by email2trac