Tree Viewer Macro Syntax

Overview

Treeviewer macros use a SQL-like selection syntax to query and select nodes in the tree and to allow the user to update those nodes. A query language and some added functions specific to trees form the ‘where’ clause of the macro language. For each node selected a ‘do’ clause is then executed to update the properties of those nodes including things like size, color and expanding or collapsing the node.

Each macro has 5 sections each of which starts with a keyword or words:

MACRO M1 "Demo"
VAR color="[0 255 0]"
FOR EACH Node
WHERE isolation_source=lettuce
DO AddToSelectionSet("lettuce", color);
DONE

Section 1 (MACRO)

“M1” is the macro name and is required. The macro description, “Demo”, can be an empty string but quotes must still be provided.

Section 2 (VAR)

Define any number of variables, separated by whitespace, in the form ‘name=value’. The ‘VAR’ section is optional, but if the keyword ‘VAR’ is provided at least one variable must be declared.

Section 3 (FOR EACH)

For Treeviewer, this section always reads exactly as shown.

Section 4 (WHERE)

This is the where clause. Insert the SQL-like query that will select the nodes you want to update. In addition to the usual AND, OR, NOT and comparison operations, functions listed under ‘Functions’ below may also be used.

Section 5 (DO)

This is the Do section. All the functions listed in this section will be run against the each selected node. Each command must end with a semicolon, and this section must end with the keyword ‘Done’. The available functions are listed below.

Functions

The following functions can be used in the ‘where’ clause. The function names are not case-sensitive and, if the function does not have parameters, and empty string must still be passed due to a limitation with the parser.

• IsLeaf(“”): Returns true for leaf nodes, false for non-leaf nodes
• NumChildren(“”): Returns the number of the node’s children. Only includes direct children, not children-of-children.
• IsNull(“property-name”): Returns true if the property ‘property-name’ was not provided for the current node. Note that ‘property-name’ must be in quotes.
• Date(“Date-Time-String”, “Format”): Takes a date-time string in format ‘Format’ and returns the integer number of seconds since midnight January 1 1970 UTC. Allows for date-based comparisons when simple string-based comparisons won’t work. For valid formats see CTimeFormat. The Default format is ‘M/D/Y h:m:s’ and trailing values do not need to be provided, e.g.:
  Date(target_creation_date, “M/D/Y h:m:s”) > Date(“06/04/15”, “M/D/Y h:m:s”)

The following functions can be added to the ‘do’ clause. A ‘do’ clause may list multiple functions separated by semicolons. Functions in the ‘do’ clause ARE case-sensitive.

• SetColor(“color-description”): Set the node’s color to the specified value which may be RGB in the form: ‘[128 255 64]’, HTML: ‘#AABBCC’ or a common color name, e.g. ‘green’.
• SetSize(size): Set the radius of the node to the specified size (in pixels).
• SetProperty(“property-name”, “property-value”) : Set the node property ‘property-name’ to the value ‘property-value’. If this is the first time a property with name ‘property-name’ has been added to the tree, then the new property will be added to the feature dictionary as well. The first parameter should be in quotes since it is a property name not a value, e.g. SetProperty(“creation-date”, “10/12/2016”)
• AddToSelectionSet(“set-name”, “set-color”): Adds the current node to the selection set ‘set-name’ and assigns the color ‘set-color’ to that set. If the selection set ‘set-name’ does not exist it is created. The color is optional and if not provided, a default is assigned.
• SetMarker(“colors”, size): Sets a circular marker for the node divided pie-chart style between the colors in ‘colors’ and with a radius equal to the default node radius times ‘size’. The ‘size’ is optional.
• SetBounding(“bounding-area-parameters”): Sets the bounding parameters for a node.

Examples

Tree property names are in red:

// Set color and size of nodes where isolation_source is lettuce

MACRO M1 "Comment"
VAR color="[0 255 255]" lsize=6
FOR EACH Node
WHERE (isolation_source=lettuce)
DO SetColor(color); SetSize(lsize); DONE

// Set a node marker based on a more complex where-clause

MACRO M1 ""
FOR EACH Node
WHERE ((platform=illumina) and (geo_loc_name=USA) and ((dist >11.0) or (collected_by in (cdc,fda))))
DO SetMarker("[128 0 0] [0 128 0]", 3); DONE

// Add cluster ID for leaf nodes with distance from parent between 15 and 20 and geo_loc_name
// that ends with ‘WI’

MACRO M2 ""
FOR EACH Node WHERE IsLeaf("") and dist between 15.0 and 20.0 and geo_loc_name like *WI
DO SetProperty("cluster-id", 502); DONE

// Three macros that can be run together to put nodes with different isolation_source values
// into different selection sets

MACRO Lettuce ""
VAR color="[0 255 0]"
FOR EACH Node
WHERE (isolation_source=lettuce)
DO AddToSelectionSet("set1", color); DONE

MACRO Culture ""
VAR color="[0 255 255]"
FOR EACH Node WHERE (isolation_source =culture)
DO AddToSelectionSet("set2", color); DONE

MACRO Blood ""
VAR color="[255 0 0]"
FOR EACH Node WHERE (isolation_source =blood)
DO AddToSelectionSet("set3", color); DONE

Demo of using TV Macros API

Live demo

You can use any of the examples above in the live demo. You might need to zoom in and navigate a tree in order to clearly observe the results.

Scope

1. Implements running multiple macros with custom coloration
2. Shows how to retrieve result set (list of node ids) for each distinct macro

Key sample of usage

//handler to receive all affected node IDs

var receiveAffectedNodeIDs = function (res)
{
     res.TV_MacroResults.results.forEach(function(macro){
          console.log('macro_name ', macro.macro_name);
          console.log('affected node ids: ');
          macro.node_ids.forEach(function (nd) {
               console.log('node id:', nd);
               }
          )
          }
     )
     };

//Get a tree viewer object

var tviewer = TreeView.findAppByIndex( 0 );

// Cancel all applied macros tviewer.clearMacros();
// Apply macros to tree viewer object tviewer.applyMacros(macro_txt,receiveAffectedNodeIDs);
// Get nodes objects by node ids
// nodes – comma separated string with node IDs
// callback – function to receive results
// max_nodes – maximum amount of requested objects

tviewer.getNodesObjects = function(nodes,callback,max_nodes)

For more information please refer to:

• BioTreeContainer and its features

Table of Contents

• Tree Viewer documentation home
• Tree Viewer application home
• For Users
  • Release notes
  • Frequently Asked Questions
  • Videos
• User Tutorials
  • User uploaded data
  • Edit Labels Dialog
  • Tree View Search
• For Developers
  • Embedding API manual
  • Tree Viewer Macros manual
  • Other Developer Resources
• Related Resources
  • Sequence Viewer
  • Multiple Sequence Alignment Viewer