Batch access to iTOL

iTOL batch uploader is a standard CGI script, available at http://itol.embl.de/batch_uploader.cgi. Use a standard POST request when submiting your data. Available parameters are described below.

Script will produce plain text output (Content-type text/plain), as follows:

• An error occured during upload: first line will start with the keyword ERR, followed by a numeric error code and longer description
• Upload was successful, without warnings: first line will start with the keyword SUCCESS:, followed by a space character and the iTOL tree ID
• Upload was successful, warnings occured: warnings will be printed one per line, and the last line will start with the keyword SUCCESS:, followed by a space character and the iTOL tree ID

If your upload was successful, store the returned iTOL tree ID for further use.

Upload script parameters

These are the options (and supported values for some of them) which the uploader script recognizes.

General options

treeFile

tree file; make sure your POST request is properly formed (Content type should be form-data or related, depending on your implementation), so that tree and dataset files are properly submitted.

treeFormat

tree format (newick, nexus or phyloxml)

treeName

tree name

treeDescription

longer description of the tree, used only if uploading into an iTOL account

uploadID

Your upload ID, which is generated when you enable batch uploading in your account (in the 'Account settings').

projectName

Required if uploadID is specified. Project name is case sensitive, and should be unique in your account. We recommend creating a separate project for batch uploaded trees.

showInternalIDs

displays internal node IDs in popups when you mouseover them

fontStylesFile

defines font styles for leaf labels in exported trees

internalNamesFile

defines custom names for internal nodes in the tree

HGTFile

defines horizontal gene transfers

colorDefinitionFile

defines color ranges, leaf label and clade colors

preCollapsedFile

defines which clades should be collapsed by default; useful for large trees

branchLabelsFile

defines text labels for tree nodes

assignTaxonomy

if your tree uses NCBI tax IDs, the names for leaves and internal nodes will be automatically assigned during upload

midpointRoot

tree will be mipoint re-rooted during upload

ncbiFile

instead of uploading a tree, iTOL can automatically generate one from a file containing a list of NCBI tax IDs. NCBI taxonomy will be pruned based on your IDs and a Newick tree generated.

ncbiFormat

format of the tree generated using NCBI tax IDs:

'namesFull'

generated tree will contain scientific names and internal nodes will not be collapsed

'namesCollapsed'

scientific names will be used, and internal nodes with only one child removed

'idsFull'

tree will contain NCBI taxonomy IDs and internal nodes will not be collapsed

'idsCollapsed'

NCBI taxonomy IDs will be used, and internal nodes with only one child removed

Dataset upload options

Up to 10 datasets can be uploaded, replace 'dataset1' as needed for others (ie. dataset2 for the second dataset and so on). Dataset file, label, separator and type are required, other parameters are optional.

dataset1File

file containing the dataset

dataset1Label

label for the dataset, used in the legends

dataset1Separator

field separator used in the dataset file: 'space', 'tab' or 'comma'

dataset1Type

dataset type

'binary'

Binary data

'simplebar'

Simple bar chart

'multibar'

Multi-value bar chart or Pie chart

'gradient'

Color gradient

'colorstrip'

Color strips

'time'

Time series

'domains'

Protein domain architecture

'heatmap'

Heatmap

'boxplot'

Boxplot

dataset1Color

used in the legends and for datasets where the color is not specified in the dataset file

dataset1StripWidth

used in 'gradient' and 'colorstrip'; strip will have the specified width in pixels (valid range: 10 - 100)

dataset1PreventOverlap

used in 'gradient' and 'colorstrip'; if set to 1, all other dataset types will start after the end of the last strip dataset

dataset1MultiBarAlign

used in 'multibar'; if set to 1, each individual field's start value will be aligned

dataset1PieTransparent

used in 'multibar'; if transprent, you will be able to see overlapping pie charts, but the colors will be slightly changed

dataset1PieRadiusMax

used in 'multibar'; pie chart radii will be scaled to match the selected values (valid range 10-500)

dataset1PieRadiusMin

used in 'multibar'; pie chart radii will be scaled to match the selected values (valid range 10-500)

dataset1BarSizeMax

used in 'multibar', 'simplebar' and 'time'; maximum value in the dataset will have this pixel size (valid range 1-5000)

dataset1ProtSizeMax

used in 'domains'; longest protein in the dataset will have this pixel size (valid range 1-5000)

dataset1BoxplotSize

used in 'boxplot'; largest value in the dataset will be at this pixel (valid range 1-5000)

dataset1BoxplotRawData

used in 'boxplot'; if you provide the raw data, iTOL will automatically calculate the values needed to display the boxplots

dataset1BoxplotUpperPercentile

used in 'boxplot'; values above the set percentile will be included in the box (valid range 0-99)

dataset1BoxplotLowerPercentile

used in 'boxplot'; values below the set percentile will be included in the box (valid range 1-100)

dataset1BoxplotStepConstant

used in 'boxplot'; this constant multiplied with the box size will define the related whisker size (valid value >0)

dataset1BoxplotCalculateExtremes

used in 'boxplot'; if set to 0, only the boxes and whiskers will be calculated

dataset1BranchColoringType

used in 'colorstrip'; specifies the effect of the dataset on branch coloring:

'none'

no coloring, show only leaf boxes (Default)

'branch'

color branches only, don't display boxes

'both'

color branches and show boxes

dataset1HeatmapTreeFile

optionally used with 'heatmap' datasets; You can upload an additional Newick formated tree file, which will be used to sort the dataset labels, and the tree will be displayed above the dataset (when in normal display mode).

dataset1HeatmapBoxWidth

used in 'heatmap'; pixel width of an individual value's box in the heatmap. Total width for the dataset cannot exceed 5000 px.

dataset1MinPointValue

used in 'heatmap'; minimum value

dataset1MidPointValue

used in 'heatmap'; mid-point value

dataset1MaxPointValue

used in 'heatmap'; maximum value

dataset1MinPointColor

used in 'heatmap'; color of the minimum value

dataset1MidPointColor

used in 'heatmap'; color of the mid-point value

dataset1MaxPointColor

used in 'heatmap'; color of the maximum value

dataset1CirclesMinR

used in 'circles'; Maximum radius will depend on the available space between leaves, and minimum radius will be calculated based on the percentage specified here (valid range 0-100)

dataset1CirclesHorizontalGrid

used in 'circles'; Display horizontal grid connecting the circles

dataset1CirclesVerticalGrid

used in 'circles'; Display vertical grid connecting the circles

dataset1CirclesSpacing

used in 'circles'; horizontal spacing between circles (in pixels, valid range 0-500)

dataset1CirclesFill

used in 'circles'; Should the circles be filled or empty? Filled circles will be fully opaque by default, unless 'dataset1CirclesTransparent' is defined.

dataset1CirclesTransparent

used in 'circles'; filled circles will be transparent; ignored if 'dataset1CirclesFill' is not defined

Enabling batch upload to your personal account

If you want to batch upload trees into your iTOL account, you must first enable the batch access and generate a unique upload ID. Click on 'Account settings' in the upper right corner of your account page and select 'Enable/disable batch upload'. Here you can enable and disable the batch access, or generate new upload IDs. The upload ID shown here must be supplied to the batch uploader via uploadID option. Please note that you must also specify the project name (via projectName option) which will receive the uploaded tree.

Example uploader scripts

Perl

iTOL_uploader.pl is an example uploader script, written in Perl. It is freely available for download. It is fully functional, and supports all the upload options specified above. Feel free to modify it to your needs or use it as provided. It requires the following modules (which are most likely included in your standard perl distribution):

• HTTP::Request::Common
• LWP::UserAgent
• Pod::Usage
• Getopt::Regex
• Config::File::Simple

Use your nearest CPAN mirror if you're missing any of them.

After you have all the modules installed, run

perl iTOL_uploader.pl --help

to see the available command line options. All options can also be specified in a configuration file (see the help for --config option). You can see an example upload config file here.

Python

Albert Wang kindly provided a Python implementation of the scripts. You can download the code from GitHub. Please contact Mr. Wang directly with any questions.

iTOL batch downloader is a standard CGI script, available at http://itol.embl.de/batch_downloader.cgi. Use a standard POST or GET request when submiting your download parameters. Available parameters are described below.

The script will generate output as follows:

• An error occured during export: Output will in Content-type: text/html, and the error will be described in detail.
• Export was succesfull: Output will be in the Content-type matching your selected format (text/plain for newick and nexus, image/svg+xml for SVG, image/png for PNG, application/postscript for PS and EPS and application/pdf for PDF). Make sure your downloader handles the incoming binary data properly.

Export script parameters

These are the options (and supported values for some of them) which the downloader script recognizes.

'png'

Portable Network Graphics; bitmap format

'svg'

Scalable Vector Graphics; vector format

'eps'

Encapsulated Postscript; vector format

'ps'

Postscript; vector format

'pdf'

Portable Document Format; vector format

'nexus'

Nexus tree file; plain text

'newick'

Newick tree file; plain text

Options for graphical formats

displayMode

tree display mode; normal or circular

alignLabels

should the leaf labels be aligned? (0 or 1)

omitLegend

if set to 1, dataset and other legends will not be displayed

ignoreBRL

branch lengths will be ignored if set to 1

showBRL

branch lenght values will be displayed on the tree. Overrides --showBS if both are specified

showBS

bootstraps will be displayed on the tree

BSdisplayValue

specify which bootstrap will be displayed. You must specify the numeric value and choose the direction using the letters 'M' (for more than) or 'L' (for less than). For example:

  display bootstraps above 60: BSdisplayValue=M60  
  display bootstraps below 0.3: BSdisplayValue=L0.3

BSdisplayType

'text' or 'symbol'

BSsymbolMaxSize

if 'symbol' is used to display bootstraps, use this option to specify the maximum circle size (in pixels)

hideRanges

if the tree has colored ranges defined, you can omit them from the exported tree by setting this to 1

rangesCover

'clades' or 'leaves'

if the tree has colored ranges defined, specify their extent using this option

colorBranches

if the tree has colored branches, use this option to use the colors in the exported tree

rotation

for circular display mode, specify the rotation angle in degrees

arc

for circular display mode, specify the arc in which the tree should be displayed (in degrees, default is 350)

inverted

if set to 1, the circular tree will be inverted

resolution

image resolution in DPI (dots per inch), used only when exporting to PNG

hideLabels

do not display leaf labels

fontSize

font size to be used for leaf labels

lineWidth

line width in pixels (default is 3)

collapsedSmall

if the tree has collapsed clades, their labels will be the same size as regular leaves

scaleFactor

the default horizontal tree scale will be multiplied with the specified value

showInternalLabels

internal node IDs will be displayed if this option is set to 1

pruneList

comma separated list of leaf IDs which should be included in the tree. If not specified, complete tree will be exported.

collapseList

comma separated list of internal node IDs which will be collapsed. If the tree does not have internal nodes defined, you can specify them using two leafs IDs instead. Separate leaf IDs with a vertical line ('|'). The last common ancestor of each pair will be collapsed. For example:

 collapseList=Homo_sapiens|Gallus_gallus,Escherichia_coli|Mycoplasma_pneumoniae

datasetList

comma separated list of dataset IDs to include in the exported tree. For example:

 datasetList=dataset1,dataset3,dataset4

omitDashedLines

used only when datasets are included in the exported tree. When set, dataset values will not be connected to tree's leaves using dashed lines.

Options for plain text formats

newickExportFormat

output options for Newick format

'withIDs'

Include internal node IDs in the tree. Example output: ((A:0.1, B:0.1)INTid1:0.2[95]);

'withoutIDs'

Only bootstraps and branch lengths will be included. Example output: ((A:0.1, B:0.1)95:0.2);

Example downloader scripts

Perl

iTOL_downloader.pl is an example downloader script, written in Perl. It is freely available for download. It is fully functional, and supports all the export options specified above. Feel free to modify it to your needs or use it as provided. It requires the following modules (which are most likely included in your standard perl distribution):

• HTTP::Request::Common
• LWP::UserAgent
• Pod::Usage
• Getopt::Regex
• Config::File::Simple

Use your nearest CPAN mirror if you're missing any of them.

After you have all the modules installed, run

perl iTOL_downloader.pl --help

to see the available command line options. All options can also be specified in a configuration file (see the help for --config option). You can see an example upload config file here.

Python

Albert Wang kindly provided a Python implementation of the scripts. You can download the code from GitHub. Please contact Mr. Wang directly with any questions.