Wasabi plugin API

Wasabi plugin API reference


 

The Wasabi plugin API allows to describe command-line tool options and corresponding Wasabi interface in JSON format.
Each option is specified with an object containing one or more attributes (described below).

  • Valid values in JSON are: boolean (true/false), string (“somevalue”) or number (0.01), wrapped in {object} or [array].
  • The interface elements are generated in the same order as their objects appear in JSON.

Tip: You can use native Javascript objects instead of JSON for less stringent formatting rules.

 

Used terms:

  • program – command-line executable
  • options – 1) additional parameters added to the program launch command
    2) descriptions of program parameters in the plugin JSON file
  • attributes – JSON-formatted text fields for describing plugin/program options
  • tracked name – name of an option in JSON (set with name or option attribute)
  • input – HTML input element (a textbox, checkbox or selection menu) in the generated plugin interface in Wasabi
  • string/boolean/array/object – valid (Javascript) value types for attributes

 

Valid attributes in the plugin JSON object


 

  • “program”: string
    Name of the executable file to be launched from its Wasabi plugins folder (or from the global path).
  • “options”: array
    Array can contain strings (displayed as text) and option objects (described in the next section).
    You can group options to multiple “options” arrays by wrapping each array to an {object} together with one of the optional attributes:

    • “group”: string – options (input elements) are displayed in a collapsible section below the label string.
      • “collapsed”: boolean – sets whether the options section is initially collapsed (default: true)
    • “section”: string – options are displayed in a bordered section below a horizontal line and label string.
    • “line”: string – option inputs are displayed in one line (wrapped if necessary)
    • “select”: string – display options in a selectable list. Same as {“type”:“select”, “title”:string} (see “type” attribute).
      Tip: Leave the label string empty (“”) for untitled section.

Optional plugin attributes:

    • “desc”: string
      Description of the program. Displayed on top of the Wasabi interface window.
      HTML is allowed (web addresses are automatically parsed to HTML links).
    • “menudesc”: string
      Short description of the program.
      Displayed as tooltip in the Wasabi tools menu (on mouseover).
    • “name”: string
      Name of the program. Displayed in tools menu and window title.
    • “icon”: string / array
      Icon of the program. Displayed in the tools menu and interface window title.
      Recommended size: 25*25px.
      String can be:

      • SVG path. Example: “M 11.193359 0.55078125 z”
      • Image data URI: Example: “data:image/gif;base64,R0lGODlhEA…”
      • Path to image file (in the plugin folder). Example: “images/icon.jpg”
        It’s recommended to provide an array with both SVG and JPG/PNG image.
    • “outfile”: string / object / array
      Specifies (partial or full) name of the the expected main output file. Use array of strings for alternative considerations.
      This attribute tells Wasabi which file to use for the “Open” button in the analysis library.
      Tip: Use objects for conditional output naming (see “default” attribute) or a comma-separated string for opening multiple files (e.g. “seqfile.fa,treefile.nwk”)
  • “translate_names”: boolean
    If set to true, all sequence names in input file(s) are converted to simple IDs (“seq1”, “seq2”, …),
    which are translated back to the original names when output is opened in Wasabi.
    Default: false (input file(s) retain names, with spaces converted to underscore)
  • “libraryname”: string
    Default name for the stored results in the analysis library (default: “my analysis”).
  • “submit”: string / object / array
    String is a label displayed on the submit button in Wasabi interface (default: “Send job”).
    Use (array of) objects for conditional labeling (see “default” attribute).
  • “prefix”: string
    Specifies leading character(s) for each parameter name in the command line (default: “-“).
    Can also be set per option/option group.
  • “valuesep”: string
    Specifies the character separating parameter name from its value in the command line (default: ” “).
  • “version”: string
    The version of the program the plugin is written for.
  • “disable”: true | “enable”: false “tree” “sequence” “data”
    Disable the plugin or require an imported tree/sequence/either data (as file input) to enable the plugin.
  • “debug”: true / string
    Write debug messages to the javascript console to keep track of plugin JSON parsing and value changes of all (if set to true) or one specific (if set to option name string) option in the interface.

Valid attributes in each JSON object describing an option in the “options” array:


 

  • “type”: “bool” / “tickbox” / “checkbox” / “int” / “float” / “number” / “text” (default) / “string” / “file” / “hidden” / “select” / “output”
    Sets the type (format) for the program option.
    Available types:

    • “file” – option accepts input datafile.
      Additional attributes:

      • “source”: “current sequence” (default) / “current tree” / “current data” / “filedrop” / “fileselect” / “import” / “filedrop fileselect” / “filedrop import”
        File data source: currently open dataset or local file added by user (using drag-drop or a file browser button).
        Tip: use “title” property to add custom text to the filedrop area
        Tip: use “desc” property to add custom text next to the filedata that user has added
      • “fileformat”: “fasta” (default for sequence) / “newick” (default for tree)/ “extended newick” / “phyloxml” / “hsaml” / “phylip” / “nexus” / “original”
        File will be converted to specified format before feeding to the program.
        Use “original” to skip file conversion.
        Tip: Use multiple ([“fasta”,“newick”]) or merged (“phyloxml”) file formats if both tree and sequence data is expected.
        Tip: The input file will be stored as “input_somename.(fa|txt|xml|nwk)”. You can set somename with “name” attribute (with or without file extension).
    • “dirpath” – for giving the program a directory path
      Use this option if the program parameter (named via “option” attribute) value needs a full path to the working directory. Otherwise works as the “hidden” option type.
      Tip: you can add a filename to the directory path with “default” attribute.
    • “hidden” – automatically added option without user input. Use “default” attribute to set its value.
      With “option” attribute, “default” sets pre-defined program arguments (string/number) or flags (true/false).
      Tip: “hidden” options can use “value” attribute as alias to “default”.
      Tip: “hidden” option with an empty/false value excludes it from the command line.
      Note: The program output stream (console output) will be written to text file output.log.
      If the program prints its results to screen, direct it to another file: {“hidden”:“outfile.fa”,“prefix”:“>”}
    • “select” – list of options (or values for an option) where only one can be selected.
      Additional attributes:

      • “selection”: array of strings/numbers/objects
        Mutually exclusive list of items to choose from.
        Tip: strings/numbers are shorthand for {“title”:value}.
        Valid attributes for selection list objects:

          • “title”: string – text to be displayed in the list.
            Tip: {“title”: “mytitle”} can be written as “mytitle”.
            “title” is also the selection item value (unless “value” is set).
          • “option”: string / array / object – other program option(s) to be set when this item is selected.
            Program options can be set as {“argname”:“argvalue”} or as “argname” for boolean options (command-line flags).
            Tip: “title” can be omitted if “option” is set as string.
          • “value”: string / number / “no value”
            Sets the value for the program option/selection when this list item is selected.
            “no value” assigns an empty value (“”). When “value” attribute is omitted, “title” is used instead.
          • “desc”: string – additional text (shown via info icon) for the selected item.
          • “default”: true / “yes” / string – sets the item as the initial selection.
            Tip: “default”:string is shorthand for {“title”:string, “default”:true}.
      • “extendable”: true / “yes” / “configurations”
        Allows users to add custom options to the selection list.
        “configurations” enables to select or store sets of values for all the plugin options.
    • “bool” / “tickbox” / “checkbox” / “switch” – tickbox element. Boolean value that adds/removes the option from command line.
    • “text” / “string” – text input box. Text input is assigned to an option (see “option” attribute) and/or tracked name (“name” attribute).
    • “number” / “int” / “float” – same as “text”, but accepts only numerical input. “int” restricts input to whole numbers.

      Tip: “type”, “title” and “option” attributes can be combined to type:string shorthand syntax (option types “text”/“number”/“tickbox”/“select”). Example: {“number”:“argname”}. When “name” attribute is present (or “type” is “select”), the syntax sets just the “title” (e.g. not a command line argument).
      Tip: “type”:“default” shorthand syntax is available for option types “output”/“hidden” (Example: {“output”:“outfile.fas”}), while “type”:“source” can be used for “file” option (Example: {“file”:“filedrop”}).

  • “title”: string
    Shows a text label next to the input element (except for option type “hidden”).
  • “option”: string
    Sets the command-line argument name. Also sets a reference name for its value tracking (see “name” attribute).
    You can include a prefix to override global “prefix” attribute. Set to empty string (“”) for positional arguments.
    Note: options are passed to the program in the order of appearance in JSON.
    Tip: use the “name” attribute to differentiate between multiple options with the same argument name.
  • “desc”: string
    Tooltip text, displayed when hovering the title (or form element when title is missing).
  • “name”: string
    Enables option value tracking. String is unique reference name that can be used by other options (see e.g. “enable” and “default” attributes).
    Overrides the “option” attribute as reference name for tracking.
    Note: Don’t use reserved plugin API keywords in a trackable name: “DNA”,“RNA”,“codons”,“protein”,“sequence”,“tree”
  • “enable” / “disable”: boolean / string / object / array
    Includes or excludes the program argument(s) from command line, its input element(s) from the interface, and clear the input value (revert the option to its “default” or empty value).
    String or object (or array of these) define rules for conditional enabling/disabling (see “default” attribute).
    Examples: {“enable”: “option_name is not ticked”} or {“disable”: {“‘option name’ is more than 10”: “yes”}} or {“enable”: “no tree”}
    Note: You can check if “option_name is disabled” in a conditional rule.
  • “check”: string / object
    Checks the option value and displays the message string whenever the input element is empty, or when
    a rule object is used ({“rule” : string}), the “rule” is a logic expression (see “default” attribute) to check the input element value against, and string is corresponding error message to be displayed.
  • “required”: string / object
    Same as “check” attribute, except 1) checks the value and displays the error message only after the “submit” button is clicked, and 2) an error prevents the plugin launch.
  • “default”: value / object / array
    Initial/default value for an option. Can be overriden by user input, unless input element is disabled with “fixed”, “disabled” or “hidden” attribute.
    Note: For text inputs, it is assumed that the default value does not need to be added to the program command line parameters, and is shown just for information when user has not inserted any value. If it’s not the case, make the program option compulsory with the “required” attribute.


    Note: conditionals
    The value for the “default” (and many other) option attributes can change according to a logical expression (conditional) and the values of the current (or any other) option. The conditional values are defined in the plugin JSON as {“condition”: “resulting value”} objects. Alternative “condition” => “result” objects can be ordered in an array: [{“condition1”: “result1”}, {“condition2”: “result2”}, …].

    The conditional strings can use Javascript logical operators, which in the plugin JSON can be replaced with API keywords:
    “is”/“equals” (=), “contains”, “not”/“is not” (!=), “and” (&&), “or” (||), “ticked”/“selected”/“on”/“enable” (true), “no”/“off”/“disable” (false)/“invert” (!).

    Both the “condition” and “result” strings can use the option input values via each option’s tracked name (set by the “option” or “name” attributes). Together with the logic expressions, you can construct rules to check for a value of an option and change an option attribute accordingly.

    Examples: {“disable”: {“option_name is not ticked”: true}} or {“check”: {“option_name is 10”: “you typed 10”}} or {“default”: {“option_name is more than other_option_name and no third_option”: “numeric_option + 0.5”}}.

    Predefined option names “tree”/“sequence” and keywords “DNA”/“RNA”/“codons”/“protein” can be used to check for the tree and the type of sequence data currently open (imported) in the Wasabi interface.
    Examples: {“sequence and no tree”: “ticked”} or {“sequence is DNA”: 0.5}
    The “tree”/“sequence” keywords can also be used to check the content of user-supplied file data. Remember to quote the keywords (also see the note below).
    Example: {“name_of_file_input contains \”sequence\””: “result value”}.

    Note: Wrap tracked/option names to single quotes (“‘option name'”) if it contains spaces. Wrap tracked names to escaped double quotes (“\”optionName\””) to use the name as text (instead of the option’s value).
    Examples: {“‘some argument’ equals \”some argument\”” : “The option value is now its name:\”some argument\”.” }.

  • “fixed”: “yes” / true / string / object / array
    Input element cannot be changed by user. String or object (or array of these) define rules for conditional fixing (see “enable” attribute).
    If input element is disabled by “fixed”, the default value (see “default” attribute) overrides input value from user.
  • “format”: “invert” / expression_string / object
    Do some postprocessing with the value of this option (this_option_name) before passing to the program.
    “invert” is same as “invert this_option_name” (only useful for boolean type options).
    expression_string is a fixed value or javascript code for formatting.
    Example: “this_option_name + \’ concatenated text\'”.
    Objects can be used for conditional formatting (see “default” attribute).
    Example: { “this_option_name is less than 0”: “Math.abs( this_option_name )” }
    Note: the type of the variable this_option_name is defined by “type” attribute (string/bool/number)
    Note: in javascript expression, use spaces around option_name, \’quoted text\’ and other tokens
  • “line”: bool
    Options marked with “line” property are displayed in one line (alternative to grouping with the “line” attribute)
  • “prefix”: string
    Option-specific command-line prefix (overrides global “prefix” attribute).

Tip: You can inspect/debug imported plugins via Javascript console. Example: console.log( Plugins[“plugin name”] );