|
| Scripting |
|
|
Scripting ?
|
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. |
Try it !
|
|
|
The script (with comments) |
The tree before the script |
The tree after the script
|
Fetch the 3 followings files and start a TreeDyn session. Then first load the tree (1), then the annotations (2) and finally the script (3). This script use an annotations file listing binary variables. This information is used for building a graphical matrix in regard of leaves
|
|
|
The script (with comments) |
The tree before the script |
The tree after the script
|
Fetch the 3 followings files and start a TreeDyn session. Then first load the tree (1), then the annotations (2) and finally the script (3). This script replace leaves names by data organised in a given format
|
|
|
The script (with comments) |
The tree before the script |
The tree after the script
|
Fetch the 3 followings files and start a TreeDyn session. Then first load the tree (1), then the annotations (2) and finally the script (3). This script works on the "Key3" variable from the "sample04" annotations file. It adds several symbols in regards of leaves. One symbol for a given value of the "Key3" variable and one column for a given symbol. All the symbols use the same color (black).
|
|
|
The script (with comments) |
The tree before the script |
The tree after the script
|
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.
|
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.
|
| 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".
Below is the list of the available operations. clic on the textual description for seeing the corresponding graphical effect
|
| 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 |
| tabulation |
tabulation help you managing the display of text or symbols organised in columns and in regards of leaves.
|
| 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.
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. |
| loadtree |
The loadtree command is for opening a tree file in a new document. |
| loadlabel |
The loadlabel command is for loading a labels file. |
| 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 : 
|
Next future
|
New scripting commands are under construction : outgroup, conformation (rectangular, circular, etc.), resizing, built-in annotations (branch lengthd, bootstrap values). If you need new or specific instructions, please don't hesitate to contact me by email or by using the TreeDyn GuestBook. |
