Help - Command line options

Note that some of the features described here are not yet implemented in the current version of TreeGraph 2. They will be available in future versions.

Command line options are additional information you can pass to TreeGraph when you start it. You can write them behind the start command of TreeGraph. which is java -jar TreeGraph.jar if you are using a platform independent installation and TreeGraph.exe if you are using the windows version.

Open a file

If you want to edit a file with TreeGraph you can pass it as the first command line parameter. If the file name or the path includes blacks you should put it into double quotes.

If you are using Windows you can assign TreeGraph to a supported file type (e.g. *.xtg) and than you will be able to open these files with a double click, because windows than passes the file name automatically as the first command line parameter. Note that this is only possible if you have a windows specific version installed.

Here are some examples of opening a file. The last example can be used in the windows specific version only.

java -jar TreeGraph.jar tree.xtg
java -jar TreeGraph.jar /home/foo/bar.tgf
java -jar TreeGraph.jar "/home/foo/My Folder/bar.nex"
TreeGraph.exe "C:\My Folder\My File.tre"

Batch conversion

TreeGraph also supports converting files by command line. To use batch conversion the first command line parameter must be -convert followed by the source file. Then the output format must be defined and a the file name of the destination file must be provided. Note that TreeGraph will terminate after the conversion and will not start its graphical user interface. The following example converts a file in the old TGF format used by TreeGraph 1.x to the new XML format used by TreeGraph 2.x or later (second one for the windows specific version):

java -jar TreeGraph.jar -convert tree.tre -xtg tree.xtg
TreeGraph.exe -convert tree.tre -xtg tree.xtg

The input format is detected automatically whereas the output format must be specified by a command line flag. The flags for each format are shown below. Note that the specified output file will not be overwritten if it already exists.

When converting to XTG internal node names of Newick or Nexus files are stored as text labels with the ID "internals".

Input formats

TreeGraph XML format (*.xtg)
Newick files (*.tre)
Nexus format (*.nex; *.tre)
phyloXML (*.xml)

Output formats

TreeGraph XML format (*.xtg) (Flag: -xtg)
Newick files (*.tre) (Flag: -newick)
Nexus format (*.nex; *.tre) (Flag: -nexus)

Generation of images

TreeGraph supports the generation of images from a XTG file in batch mode. To use this function you have to provide -image as the fist command line parameter followed by the input file (*.xtg) and the destination file. The graphic format for the output is determined by the extension of the source file name (*.svg or *.png). The following example shows the conversion of a XTG document to an SVG image and to an PNG image.

java -jar TreeGraph.jar -image tree.xtg tree.svg
java -jar TreeGraph.jar -image tree.xtg tree.png

Furthermore you can pass additional parameters to specify the way the tree is displayed as well as the resolution and the size of generated image. For the way of displaying you can choose the following options:

-clad for a Rectangular Cladogram (default)
-phyl for a Phylogram (accounts branch length values)

Information on the size of the image can be specified by the parameters -width or -height followed by a numeric value. Note that only one of the two parameters can be specified because the aspect ration will be preserved. Both values consist of a floating point number and the unit (without any blanks). Possible units are:

mm for millimeter
pt for points
px for pixels

Additionally the resolution of the image can be specified by the parameter -res followed by a floating point value and a unit. Units can be:

ppm pixels per millimeter
ppi pixels per inch (dots per inch, dpi)

Examples

java -jar TreeGraph.jar -image tree.xtg tree.png

The document in "tree.xtg" is converted to PNG image with default resolution of 70ppi and resulting width and height based on the size of the tree elements specified in millimeters in the document. The tree is displayed as a Rectangular Cladogram by default.

java -jar TreeGraph.jar -image tree.xtg tree.png -phyl -width 100px

The document in "tree.xtg" is converted to PNG image with default resolution of 70ppi and a width of 100 pixels. The resolution has no effect to the absolute size of the image, but it is stored as meta information in the PNG file which can be useful when it is printed. This time the tree is displayed as a phylogram.

java -jar TreeGraph.jar -image tree.xtg tree.png -height 250px

java -jar TreeGraph.jar -image tree.xtg tree.svg -width 600mm -res 120ppi

java -jar TreeGraph.jar -image tree.xtg tree.png -width 600px -res 3.2ppm

Display the version

By passing -version as the only command line parameter you can cause TreeGraph to display its version in the command line. Note that TreeGraph won't start afterwards. The following example shows the usage and a possible output:

java -jar TreeGraph.jar -version

⇒ TreeGraph 2.0.40-185 beta

Grammar

The following EBNF describes the possible command line options of TreeGraph 2 which can be placed behind "java -jar TreeGraph.jar".

commands             = openCommand | convertCommand | imageCommand | versionCommand ;

openCommand          = treeFileName ;

convertCommand       = "-convert" treeFileName treeFlags treeFileName [ branchLengthCommand ] ;
treeFlag             = "-xtg" | "-nexus" | "-newick" ;

imageCommand         = "-image" treeFileName imageFileName [ viewMode ]
                       [ sizeCommand sizeValue ] [ "-res" resolutionValue ] 
                       [ branchLengthCommand ] ;
viewMode             = "-clad" | "-phyl" ;
sizeCommand          = "-width" | "-height" ;
sizeValue            = numericValue [ "mm" | "pt" | "px" ] ;
                       (* No whitespaces between value and unit allowed. *)
resolutionValue      = numericValue [ "ppm" | "ppi" ] ; 
                       (* No whitespaces between value and unit allowed. *)

branchLengthCommand  = ( "-pathLen" | "-brLenUnit" ) lengthValue
lengthValue          = numericValue [ "mm" | "pt" ] ; 
                       (* No whitespaces between value and unit allowed. *)

versionCommand       = "-version" ;

numericValue         = (* Any positive numeric value *)
treeFileName         = (* Any relative or absolute path to 
                          a tree file with a valid extension *)
imageFileName        = (* Any relative or absolute path to 
                          an image file with a valid extension *)