ScripTree - User manual
Processing
The executable command is "scriptree".
There are 3 main parameters : "-tree", "-script" and "-annotations" :
>scriptree -tree file.nwk
"file.nwk" contains one or several newick string(s). Without any others specifications scripTree use default
settings for the tree(s) rendering
>scriptree -tree
file.nwk -script file.tds
"file.tds" contains scripting commands. Only a sub-set of scripting commands is available because no annotation are used.
>scriptree -tree
file.nwk -script file.tds -annotation file.tlf
"file.tlf" contains annotations.
Another optional flag is -out which enables the setting of a prefix file's name for all the scripTree
outputs.
scripTree Outputs: a PostScript file (.ps), a SVG
file (.svg) and a TGF file (.tgf) Nota Bene: the TGF file is treedyn compatible,
that is to say scripTree user's are able to finalize the graphical analysis using the treedyn stand-alone package.
Scriptree could be used throught a web interface (Scriptree works as CGI and have to be install on a web server).
The user only have to fill the 3 boxes related to the 3 main parameters (-tree, -script, -annotations) and submit the form in order to
download the resulting trees as TGF, SVG, PS, or images files (JPG, TIFF, BMP). See the tutorials for more information.
Tree
The tree's formats readable by ScripTree is the
Newick format with several variations. ScripTree also read tree
collections. In the case of multi trees, concatenate all your newick
strings in a single file. Never forget the ";" character at
the end of the newick string. ScripTree reads the following formats :
symbolic without branch lengths, or bootstrap values/p-values, without the ":" character:
ex: ((a,b),c);
multi-bifurcating trees
ex: ((a,b),c,d);
bootstrap values/p-values without the ":" character
ex: ((Mus,Oryctolagus)100,((Nycticebus,(Lemur,(Propithecus,Microcebus)48)99)76,(Tarsiusxb,...;
newick string with the ":" character and values before it and/or after it
ex: (((((((Prorocentrum:0.0536,Tetrahymena:0.0721)45:0.0038,((Oryza:0.0135,(Lycopersicon:0.0046,...;
ex: ((agl12:0.65147,((((osmads13:0.16224,((ag:0.10194,((agl1:0.0001,((313113:0.08059,4837612:0.05508)...;
Script
A script is a file under text format, sequencing a set of ScriptTree commands. You can add comments to the script using the character "#". Also you can write a command with its arguments on several rows using the character "\". Finally you can write several commands on one row by using the character ";". Example:
# a comment is a row starting with the "#" character
# empty row(s) are possible(s)
# a command with its arguments can be wrote
# using several rows separated by the "\" character
tree -x 10 -y 20 -height 150 -width 50 \
-fg blue -outline black \
-linewidth 1 \
-font {-family Arial -size 8 -slant roman -weight normal -size 8 -overstrike 0 -underline 0}\
-scale {0 0 black}
query_newick -q {H* Ado*} \
-hi {-o {lfg s_foreground_color} -c orange} \
-regexp 0
# multiple commands on one rows are separated by the ";" character
hi -o {l_background_color} -c purple ; query_newick -q {H*}
The ScripTree commands are explained belows.
Annotations
Annotations are meta-information related to the entities under the phylogenetic study: taxonomic descriptions,
geographic distribution, gene functions and so on. Annotations are useful for the analyses of trees and their publications, but can
hardly be encoded within the tree itself (the so-called Newick string), particularly with large trees, multiple trees and multiple
annotation variables. Annotations are used by graphical operators for the highlighting of tree items : modifying the foreground/background
colors, posting symbols or text linked to sub-trees or in regards of leaf labels. For instance, knowing a tree on the one hand and, on the
other hand annotations for some leaf labels, the query "select Leaves from Annotations where VariableX == ValueX1" returns a
list of leaf labels found in the tree and matching the "ValueX1" value for the variable "VariableX". This list is then used
by a highlighting operation which updates the tree aspect (e.g. sub-tree background color to red). scripTree links unique leaf labels
to lists of variables/values pairs of annotations, independently of the tree topologies, remaining fully compatible with the newick
format. An annotations file is a simple text file containing one record per line. Each record begins with the name (label) of a leaf
in a tree followed by a list of key/{value(s)} pairs. For instance for the tree: ((a,B),c); an annotations file is like:
a country {1} species {X}
B country {1 2} species {X}
c country {3} species {Y}
Nota Bene: (1) leaf labels, variables and their values do not contain the following characters:
{, }, (, ), [, ], *, ?, " (2) leaf labels, variable names and values are without space, (3) variable names and values
list are separated by space character or tabulation (4) leaf label must be exactly the same between the graphical representation
and the annotation records. In particular upper/lower cases must be respected, (5) annotation records do not have necessary the
same variables list. In case of unknown values it is nevertheless possible to used generic values such as "0", "Unknown",
"NS", and so on, (6) there is no order to respect in the variable/values pair list between the differents records, (7)
it is possible to organise information on differents annotation sets, (8) a given annotation set may be used for the annotation of
differents trees.
ScripTree Commands
- with or without leaves query/selection- with or without annotations query/selection
- object of annotation : l | s | e (leaf | edge | subtree)
- graphical annotation : string, symbol, arc...
- source of information used for annotation : from the newick string itself or from annotation files
- annotation : quantitative or qualitative