TreeDyn User's Manual
TreeDyn Scripting Commands
Abstract

Scripting enables the use of a simple language dedicated to tree graphical management. This language is based on a list of commands with one or more argument(s), and can be used either interactively at the Scripting panel prompt and/or listed and saved in a script file (text format, TreeDyn scripts use the .tds suffix). Scripts files can be loaded with the "Open script..." option of the "File" menu (Main panel or Scripting panel). A TreeDyn script is a useful way to save graphicals treatments of trees and for the automation of repetitive tasks. Scripting may use TreeDyn annotations files. A given script can be applied to several trees, and several scripts may be used on a given tree.


Table of contents
Table of contents:

  1. The Scripting Console
  2. Commands library

Conventions:
  • M1 = Left Mouse Button
  • M3 = Right Mouse Button
  • CM = Contextual Menu with M3
The Scripting Console

The Scripting console is activated from the "Scripting Panel" option of the "View" menu (main TreeDyn panel). It gives the possibility to enter TreeDyn commands interactively.

operation l01: the current graphical operation is set to "Leaf Foreground Color"

color red: the current color is set to red

find A*: find leaves begining with an A, the result is hightlight using the current operation and color (foreground color to red)

operation n01: the current graphical operation is now "Node Background Color"

color grey: the current color is now grey

find C*: find leaves begining with a C, the result is hightlight using the current operation and color (background sub-tree in grey)

Commands library

Commands (alphabetic order) AN | ANmatrix | color | find | font | ID | legend | operation | shape | stipple | symbol | tabulation | text |
text The text command use a string argument. For instance, text "Hello world !". The current text value is used for adding text to tree, sub-trees (nodes), or in regards of leaves. For instance the script "operation l07 ; text + ; find A*" will puts the "+" character in regards (as a column) of leaves begining with an "A"
symbol The symbol command has 2 arguments. The first one is an index setting which symbol you want to use. All the available symbols with their corresponding Id are list in the table below. The second argument of the symbol command is the size of the symbol you want to use. For instance, symbol 34 12 will set the "x" symbol at size 12. Note that the symbol system of TreeDyn is based on font using the Winddings or Webding family. These font may not be available on your system. Also I know there is a bug with the Postcript exportation without respect of symbols representation.

font The font is specified with a 3 elements list. The first element is the font family: Times, Helvetica, Courrier and so on. The second element is the font size, and the third is a list of font style parameters like normal, bold, roman, italic, underline, and overstrike. For instance, to specify a Times 12 both bold and italic font, you have to use the followinf command: font {times 12 {bold italic}}
legend the legend command has one argument which is either "on" or "off". For instance the following script annotate leaves as a column of one symbol in several colors depending the first character of the leaves names (find process). In this example the legend will have 2 symbols, the first one in red (leaves starting with an "A") and the second one in blue (leaves starting with an "B"). Note that the query for leaves starting with a "C" character with the symbol in green will not be added to the legend because of the "legend off" raw. The command "legend on" with "legend off" give you the possibility to build several legends in a given script.
operation l07
legend on
symbol 21 10
color red
find A*
color blue
find B*
legend off
color green
find C*
stipple

The stipple command is mainly used in conjunction with a node background operation (n01). Stipples are indexed in the following table. For instance the comand "stipple 0" specify a full pattern. This is the value by default. Stipple are not color dependant. I will add stipple with color transparency.
shape

Shape is mainly used with a node background operation like n01. Available shapes are indexed in the table below.

  • 1: polygon, sub-tree. The default one.
  • 2: rectangular, sub-tree
  • 3: rectangular, sub-tree and leaves
  • 4: rectangular, sub-tree with a tree maximum on the horizontal axis
  • 5: rectangular, sub-tree with integration of annotations
    • operation

    The operation command set the current graphical operation. Operations are now referenced by Ids. For instance, operation l01 set the current graphical operation to Leaf Foreground Color. It means that queries (Find process, Localisation process) will hightlight matching leaves by switching their foreground color to the current color. The script "color red ; operation l01 ; find A*" will update the foreground color to red for leaves begining with the character "A". Operations list Nota Bene: previous scripts using key words for operations are still readables by TreeDyn.

    color

    The color command enables setting of the current color. TreeeDyn recognizes many symbolic color names (eg, red) when specifying colors. The symbolic names recognized by TreeDyn and their 8-bit RGB values are here

    ex.1: color blue set the current color to blue

    tabulation tabulation help you managing the display of text or symbols organised in columns and in regards of leaves.
    • tabulation = 100 annotations start at 100 pixels after leaves names
    • tabulation + 50 add 50 pixels to the current tabulation
    • tabulation - 10 remove 10 pixels to the current tabulation
    • tabulation auto 10 adds 10 pixels between "ID" or "AN" queries as an automatic process.
    find

    the find command help you locating leaves on a tree knowing their name. Patterns may be used on leaves names, helping you to detect clusters. It may be usefull if the leaves names integrate knowledge throught a given code.

    AN

    the AN command is for ANnotation. A labels file is necessary. A first argument is either "LeavesReplace", "LeavesAdd" or Columns.

  • the "LeavesReplace" command will replace the names of leaves.
  • the "LeavesAdd" command will add text in regards of leaves.
  • the "Columns" command will add text in regards of leaves and as a column

    ex.1: AN LeavesReplace {Labels {Name}}
    replace the leaves name by the value of the variable "Name" from the "Labels" file

    ex.2: AN LeavesAdd {Labels {TypeStrain}}
    add the value of the variable "Name" from the "Labels" file

    The AN command have a second argument which is optional. It enables a format of the annotation with a prefix, a suffix and finally a translation on the ordinate axis. For instance the command

    AN LeavesAdd {Labels {TypeStrain}} {prefix "(" suffix ")"}

    will add the strings "(" and ")" before and after the annotation respectively. Moreover the annotation can be translated on the Y axis with the option exposant $value. For instance, with the following command the annotation will be translate of 3 pixels on the Y axis:

    AN LeavesAdd {Labels {TypeStrain}} {prefix "(" exposant -3 suffix ")"}

    Finally, AN Columns {Labels {TypeStrain}} add the values of the TypeStrain variables in regards of leaves and as a column.

    • ID

    The ID command is for IDentification. A labels file is necessary.

    The basic use of this command is SQL like :

    ID EU from [labels file] where [variable] [operator] [value]

    Currently, the available operators are : == ; != ; > ; < ; >= ; <= ; ## (include) and !# (do not include). These two last operators are used for multi-valued variables or for string pattern matching. The query can integrates AND/OR connectors with a priority of resolution described through brackets. For instance, the following query looks for leaves matching the *rna* pattern for the FuncCat variable and with either a Cytoplasmic or Cytoskeletal value for the Subcellular_loc variable.

    ID EU from ypddat where FuncCat ## *rna* AND {Subcellular_loc == Cytoplasmic OR Subcellular_loc == Cytoskeletal}

    The resulting graphical hightlight depends of the current operation and the current color/font

    loadtree

    The loadtree command is for opening a tree file in a new document.

    ex.1: loadlabel t.tre
    load the tree file called t.re which is in the current folder

    ex.2: loadlabel C:/chevenet/phylogeny/t.tre
    load the labels file called t.tree which is in the C:/chevenet/phylogeny/ folder

    Nota Bene you can navigate into the file system using the pwd, cd, dir commands

    loadlabel

    The loadlabel command is for loading a labels file.

    ex.1: loadlabel t.tlf
    load the labels file called t.tlf which is in the current folder

    ex.2: loadlabel C:/chevenet/phylogeny/t.tlf
    load the labels file called t.tlf which is in the C:/chevenet/phylogeny/ folder

    Nota Bene you can navigate into the file system using the pwd, cd, dir commands

    ANmatrix

    ANmatrix is an specific annotation command for binary variables. This command needs an annotations file whith variables having values 1 or 0. Once the annotations file loaded, the ANmatrix command is used with one argument : the list of the variable you want to project as a boxes matrix, with one colmun per variable. For instance, the script ANmatrix sample02 {Sp1 Sp2 Sp3 Sp4 Sp5 Sp6 Sp7 Sp8 Sp9} returns the following result :