documentation

Archaeopteryx Documentation

Introduction

Under development!

Last updated: 2020-05-20

Current version: 0.9929 beta (200520)

Documentation, tutorial, and examples for visualization, analysis, and editing of phylogenetic trees with Archaeopteryx. Some (older) documentation can also be found here.

Archaeopteryx.js is the official JavaScript-based version of Archaeopteryx for online ("web") visualization and exploration of phylogenetic trees (demo).

For programmers: Information on the underlying forester framework is available here.

Authors: Christian Zmasek, Anna Sheydina

Copyright (C) 2020 Christian M Zmasek. All rights reserved.

Download and Example Files

• Executable files ("forester_xxx.jar") are here

• Other files (examples, configuration files, etc.) are here

• Previous versions are here

  • Source code is GitHub

How to Launch Archaeopteryx

GUI

• Clicking on "forester.jar" will launch Archaeopteryx and use the configuration file ("_aptx_configuration_file.txt") if it is in the same directory as the jar file.

Command line

• without use of a configuration file, or a configuration file named "_aptx_configuration_file.txt" is in the same directory as the jar file:

  • java -cp path\to\forester.jar org.forester.archaeopteryx.Archaeopteryx

• using a configuration file anywhere in the file system:

  • java -cp path\to\forester.jar org.forester.archaeopteryx.Archaeopteryx -c path\to\_aptx_configuration_file.txt

• directly opening a treefile and using a configuration file anywhere in the file system:

  • java -cp path\to\forester.jar org.forester.archaeopteryx.Archaeopteryx -c path\to\_aptx_configuration_file.txt <treefile>

Increasing memory

Since the Java default memory allocation is quite small, it might by necessary (for trees with more than around 5000 external nodes) to increase the memory which Java can use, with "-Xmx" Java command line option. For example:

• java -Xmx2048m -cp path\to\forester.jar org.forester.archaeopteryx.Archaeopteryx -c path\to\_aptx_configuration_file

Windows batch file

To avoid typing, it is easiest to create at batch (.bat) file. For example create a new file named "aptx.bat" and put a line like this into it:

java -Xmx2048m -cp "C:\path\to\forester.jar" org.forester.archaeopteryx.Archaeopteryx -c "C:\path\to\_aptx_configuration_file"

Clicking on "aptx.bat" should now start Archaeopteryx.

Configuration

While not required for basic use, many features of Archaeopteryx can be controlled by a configuration file (an example configuration can be downloaded here: _aptx_configuration_file.txt).

Examples:

• Basic default tree display settings:

  • font_family: Arial,Helvetica,Sans-serif

  • font_size: 10

• Which buttons to show, and their initial values ('display'/'nodisplay' controls whether the button is being displayed, 'yes'/'no' controls the button's initial value):

  • phylogram: display ?

  • rollover: display yes

  • color_according_to_species: display no

  • show_domain_architectures: nodisplay no

• Which click-to menu items to show, and their initial values ('display'/'nodisplay' controls whether the menu item is being displayed):

  • click_to: display_node_data display

  • click_to: collapse_uncollapse nodisplay

• Default colors (in RGB format):

  • display_color: background 0x000000

  • display_color: sequence 0xDCDCDC

  • display_color: taxonomy 0xB4B4B4

• Species colors (in RGB format):

  • species_color: BRAFL 0x00FFFF

  • species_color: SPHGR 0x9620F0

Reading and Writing of Trees

Input and Output Formats

Archaeopteryx can read and write phylogenetic trees in a variety of formats, including:

• • phyloXML: an XML language for evolutionary biology and comparative genomics, necessary for many of Archaeopteryx' advanced features

• New Hampshire/Newick: produced by most major phylogenetic analysis software (e.g. PHYLIP)

• Nexus: the format used by PAUP*, MrBayes, TreeBASE, and many others

• ToL Response XML Format: the format currently used by the Tree of Life project webservices (input only)

  • Important note. While Archaeopteryx currently (May 2014) still allows input in NHX format, support for this format is expected to be removed in future versions. Therefore it is strongly recommended to prepare for migration to phyloXML (use phyloxml_converter with -f=dummy option to convert NHX formatted trees to phyloXML).

Reading of Trees from Online Resources

Archaeopteryx can directly download phylogenetic trees from any URL or web-service (provided they are formatted appropriately). Additionally, the current version of Archaeopteryx is configured to directly read phylogenetic trees from:

• TreeBASE

• Pfam

• TreeFam

• Tree of Life Web Project (ToL)

TreeBASE

To read individual trees from TreeBase, open the "File" menu, select "Read Tree from TreeBASE...", and then enter a tree ID number (without the "Tr"). For example, enter "72589" to load one tree from the paper "Dynamic evolution of mitochondrial ribosomal proteins in Holozoa" by Scheel and Hausdorf.

Depending on the nature of the data contained in a tree downloaded from TreeBASE, it is possible to use Archaeopteryx to add more information to a tree, e.g.:

1. To attempt to add sequence information (if, for example, the node names are recognized sequence identifiers), open the "Tools" menu, and select "Obtain Sequence Information".

2. To attempt to add taxonomic information (from the UniProt database), open the "Tools" menu, and select "Obtain Detailed Taxonomic Information" [use "Obtain Detailed Taxonomic Information (deletes nodes!)" to remove nodes for which no information can be found].

3. If all external nodes have appropriate taxonomy information, it becomes possible to infer ancestral taxonomies by opening "Analysis" and then executing "Infer Ancestor Taxonomies".

4. Finally, subtrees can be colored automatically via taxonomic rank by opening "Tools" and selecting "Colorize Subtrees via Taxonomic Rank".

Coloring of subtrees by selecting their parent nodes.

Coloring of Drosophila, Caenorhabditis, and Nematostella subtrees by searching for DRO, CAE, and NEMVE.

Node Shape, Size, Fill and Color

Individual node shapes, sizes, fill-types, and colors can be set in Archaeopteryx by using the phyloXML "property" element (with 'ref="style:"') to store node fonts and colors. For example:

<clade>

<property ref="style:node_shape" datatype="xsd:token" applies_to="node">rectangle</property>

<property ref="style:node_size" datatype="xsd:float" applies_to="node">12.0</property>

<property ref="style:node_color" datatype="xsd:token" applies_to="node">#ff00ff</property>

<property ref="style:node_fill_type" datatype="xsd:token" applies_to="node">gradient</property>

</clade>

Values for "style:node_fill_type"

• none

• solid

• gradient

Values for "style:node_shape"

• circle

• rectangle

Editing of Trees

Deletion of External Nodes

Archaeopteryx can be used to automatically remove unwanted external nodes (to, for example, simplify large trees), either via positive or negative selection:

1. Select all external nodes to be deleted or retained, either manually—by choosing/right-clicking "Select Node(s)", or via "Search" (A and/or B) if all nodes to be deleted/retained have a searchable feature in common (for example, all nodes for which the taxonomy code is "HUMAN" ).

2. Delete all selected external nodes by executing "Delete Selected Nodes" in the "Tools" menu. To delete all but the selected nodes, choose on "Retain Selected Nodes" in the "Tools" menu.

Examples:

• To keep only nodes representing human sequences, search for "HUMAN", and then execute "Tools"|"Retain Selected Nodes".

• To delete all sequences from E. coli, search for "ECOLI", and then execute "Tools"|"Delete Selected Nodes".

Display of Domain Architectures

Checkbox "Domain Architectures" (under "Display Data") controls whether domain architectures are shown or not. Colors for individual domains are calculated from their name (so that the identical domains always have the same color) unless domain colors are controlled via the configuration file (e.g. domain_color: TIR 0x900000).

Control of domain architecture size and confidence threshold

The length of domain architectures can be adjusted with the "d-" and "d+" buttons under "Domain Architectures" (press the "F" button to re-adjust the image size). The "-" and "+" buttons under "Domain Architectures" control the confidence threshold (usually E-value based) for displayed domains.

Alignment of domain architectures

In the cladogram display type, domain architectures are always lined up. In the phylogram display type, the lining-up of domain architectures is controlled via the "Line Up Diagrams" checkbox in the "Options" menu. Domain architectures can also be right-aligned; this is set via the "Right-align Domain Architectures" checkbox in the "Options" menu.

Domain labels

Checkbox "Domain Labels" (in the "Options" menu) controls whether domain labels are shown or not.

Annotation of Sequences

• First, select all nodes with sequences to be annotated, either:

  • manually, by choosing/right-clicking "Select Node(s)", or

  • via "Search" if all nodes to be colored have a searchable feature in common (for example all nodes for which the sequence name contains "bcl2").

  • Second, execute "Annotate Sequences of Selected Nodes" from the "Tools" menu. This allows to enter annotations in the form of references (e.g. "GO:0006915", "EC:2.7.1.41", "KEGG:R00960") and/or descriptions (e.g. "apoptosis"). Sequences can be associated with unlimited number of annotations.

• To unselect all selected/found nodes, use "Reset" in the Search tool.

Annotation of sequences

To turn on/off display of sequence annotations

• Checkbox "Seq Annotations" controls whether sequence annotations are being displayed or not.

To turn on/off display of annotation reference sources

• Checkbox "Show Seq Annotation Ref Sources" in "Options" menu controls whether reference sources (e.g. the "GO:" in "GO:0006915") are being displayed or not.

To colorize node labels by sequence annotations

• Checkbox "Colorize by Annotation" controls whether node labels are colorized by their annotations.

Reading and Displaying of Expression and Other Vector Data

Archaeopteryx can be used to display vector data (e.g. expression data) associated with tree nodes:

1. Ensure the configuration file contains this line: "show_vector_data: display yes".

2. Start Archaeopteryx and read in a tree (example tree).

3. Open "Tools" menu and select "Attach Vector/Expression Values" to read in a matrix (of, for example, expression values) (example expression values).

4. Checkbox "Vector Data" controls whether the vector data is being displayed.

Display of expression data

Setting of Vector Data Display Colors and Size

The colors and size for vector data display can be modified with the configuration file.

Example:

vector_data_min_color: 0x0000FF

vector_data_max_color: 0xFFFF00

vector_data_mean_color: 0x000000

vector_data_width: 120

vector_data_height: 12

How-To's and Workflows

How to use simple node labels for colorization according to gene names and species

Most programs produce phylogentic trees in New Hampshire (Newick) or Nexus format, which means node labels are simple, short and untyped strings. Oftentimes, users encode gene and species names into these strings, for example "bcl2_VB129Mouse".

In the following is a short workflow for using such labels to colorize node labels according to gene names and branches depending on species (in this example we assume that there are two genes "bcl2" and "bclx" and three species "Mouse", "Human" and "Brafl" and node labels are "bcl2_VB129Mouse", "bclx_XS293Mouse", "bcl2_RD4832Human", ...):

1. Type "bcl2" into "Search (A)", all labels containing "bcl2" should be highlighted

2. Right-click on one of the highlighted nodes and choose "Colorize Node(s)", select a color

3. Click on "Reset" (under the search box)

4. Do the same thing for "bclx"

5. Type "Mouse" into "Search (A)", all labels containing "Mouse" should be highlighted

6. Right-click on one of the highlighted nodes and choose "Colorize Subtree(s)", select a color

7. Click on "Reset" (under the search box)

8. Do the same thing for "Human"

9. Do the same thing for "Brafl"

Note. While this approach is workable, it is very limited, mainly due to a poorly thought out sequence label scheme. A significant improvement would be to have sequence labels in the form "bcl2_RD4832_HUMAN" (by separating the species identifier from the rest with a underscore, and using proper UniProt taxonomy code/mnemonics). In this case, Tools|"Extract from Taxonomic Data from Node Names" could be used, which in turn opens up a wide variety of further analysis and visualization options.

Common Issues and Questions

Internal Node Names are Confidence Vales

Issue: Certain programs produce New Hampshire formatted trees (possibly inside a Nexus file) where internal tree nodes have both branch length as well as confidence (support) values [e.g. "(a:0.1,b:0.2)0.90:0.1"]. By default, Archaeopteryx interprets these confidence values (the "0.90" in the example) as node names. In most situations this is not a big problem, except if the trees are to be re-rooted—then the "confidence values" move to the wrong branches (because node names are attached to a node and not to a branch like support values). More information on this issue is available here: http://biorxiv.org/content/early/2015/12/25/035360

Solution: To correctly interpret such internal numbers as support values, check "Internal Node Names are Confidence Values" under the Options|Newick/NHX/Nexus Read menu before reading the tree file.

GUI Reference

Main Menu

• Phylogram: to switch between the phylogram and the cladogram display

• Dyna Hide: to hide external labels depending on expected visibility

• Rollover: to enable mouse rollover display of the node data, allowed to obtain an additional node information which was hidden by disabling of “Display data functions”

• Show Internal Data: allows or disallows display of data for internal nodes

• Colorize by Sequence: to colorize node labels as a function of sequence names.

• Colorize by Taxonomy: to colorize taxonomy and sequence labels as a function of taxonomy

• Colorize by Annotation: to colorize sequence annotation labels as a function of sequence annotation

• Visual Styles/Branch Colors: to display visual styles (node colors, fonts) and branch colors, if present

• Branch Widths: to use branch width values, if present

Display data

This controls which data elements are being displayed (if present in current), such as:

• Node name: to switch on/off name of the node

• Taxonomy Code:to switch on/off name of taxonomy code (e.g. "DROME")

  • Taxonomy Scientific: to switch on/off name of the taxonomy information ("Drosophila melanogaster")

• Taxonomy Common: to switch on/off display of the "common" taxonomy name ("fruit fly")

• Seq Name: to switch on/off of the sequence name

• Gene Name: to switch on/off of the gene name

• Seq Symbol: to switch on/off of the symbol of sequence

• Seq Accession: to switch on/off of the accession number of sequence

• Seq Annotations: to switch on/off annotation of sequence

• Confidence value: to switch on/off of the confidence value

• Branch Length Value: to switch on/off of the branch length value

• Binary Characters:

• Binary Char Counts:

• Domain Architectures:

• Multiple Seq Alignment:

• Node Events:

• Vector Data:

• Properties:

• Taxonomy Images: to switch on/off taxonomy images.

Node Menu

• Display Node Data: to display and edit node information, this information will be saved in a tree

• Collapse/Uncollapse: to collapse or uncollapse a sub-tree at a selected node

• Root/Reroot: to introduce the root-node into the parent branch of the selected node

• Go to Sub-/Super-Tree: to get sub- or super-tree if it is available

• Swap Descendants: to swap descendants

• Colorize Node(s): to colorize node (this change will be store at a tree)

• Change Node Font(s):to change node font (this change will be store at a tree)

• Colorize Subtree(s):to colorize subtree with all children (the change will be store at the tree)

• Open sequence DB:to open sequence DB, if present

• Open PDB: to open PDB, if present

• Open Taxonomy DB: to open Taxonomy DB, if present

• Launch BLAST:to launch BLAST, if present

• Select Node(s): to select one or more nodes for following editing

• return User Selected Data:

• Cut Subtree: to cut a subtree

• Copy Subtree:to copy a subtree

• Paste Subtree: to paste a subtree

• Delete Subtree/Node: to delete a subtree

• Add New Node: to add new node (either as sibling or descendant of the selected node)

• Edit Node Data: to edit node information

• Zoom Menu

  • Y+button: to vertical zoom in

  • Y-button: to vertical zoom out

  • +button: to horizontal zoom in

  • - button :to horizontal zoom out

  • F button: to fit complete phylogeny to the current display size

• Back to Super Tree:

• Order Subtrees:

• Uncollapse All: to uncollapse collapsed subtrees

Search options

• There are two search windows for independent search by one or two parameters

  • Enter text to search for. Use ',' for multiple searches (logical OR) and '+' for logical AND

  • Accept regular expressions as a text for search

File

• Read Tree from File: to read a file in any format: phyloXML, New Hampshire/Newick, Nexus phyloXML,ToL Response XML, NHX, txt

• Read Tree from URL/Webservice: to download a phylogenetic tree from a URL or web-service

• Read Tree(s) from TreeBASE Study: to read all tree associated with a TreeBASE study

• Read Tree from TreeBASE: to read a tree from TreeBASE

• Read Domain Tree from Pfam: to read a domain tree from Pfam

• Read Gene Tree from TreeFam: to read metazoan gene trees (including inferred gene duplications) from the TreeFam database

• Read Tree(s) from Tree of Life: to load a species trees from the Tree of Life Web Project (ToL)

• New: to create a new tree with one node as source for manual tree construction

  • Save Tree As: to save a tree to a specified location in any of following file formats: phyloXML, New Hampshire/Newick, and Nexus

• Save All Trees As: to save all displayed trees in one file

• There are several option to export a tree as an image:

  • Export to PDF file

  • Export to PNG file

  • Export to JPG file

  • Export to GIF file

  • Export to BMP file

• Print: to print a tree (options for printing are under the "Options" menu)

• Close Tab: to close the current panel

• Exit: to end a current session

Inference

• From Multiple Sequence Alignment: basic phylogenetic inference from MSA. This function allow to visualize a tree based on a multiple sequence alignment or unaligned sequences using the Neighbour-Joining (NJ) method

• From Unaligned Sequences: to get a basic phylogenetic inference including multiple sequence alignment

Analysis

• GSDI (Generalized Speciation Duplication Inference): to infer duplication events on a gene tree given a trusted species tree

• GSDIR (GSDI with re-rooting): to infer duplication events on a gene tree given a trusted species tree with re-rooting

• Load Species tree: to upload species tree for GSDI analysis

• Infer Ancestor Taxonomies: to show an inference of ancestor taxonomies/lineages

Tools

• Colorize Branches Depend on Confidence: to visualize the branches depend on confidence value

• Colorize Branches via Taxonomic Rank: to colorize branches based on class level, for instance colorize mammal specific subtree red

• Taxonomy Colorize Branches: to colorize branches based on taxonomy color chart, taxonomies for species specific subtrees

• Delete All Visual Styles From Nodes: to remove all node visual styles (fonts and colors) from the current phylogeny

• Delete All Colors From Branches: to delete branch color values from the current phylogeny

• Annotate Sequence of Selected Nodes: to add annotation to the previously selected branches via “Search” function

• Midpoint-Root: to perform Mid-point rooting: the root of an unrooted tree is placed at the mid-point of the longest distance between two taxa in a tree

• Delete Selected Nodes

• Retain Selected Nodes

• Collapse Species Specific Subtrees: to reversibly collapse species-specific subtrees

• Collapse Branches with Confidence Below Threshold into Multifurcations: to collapse branches with confidence values below a threshold into multifurcations (in the case of multiple confidences per branch: without at least one confidence value above a threshold)

• Collapse Branches with Branch Length Below Threshold into Multifurcations: to permanently collapse branches with branches length below a threshold into multifurcations

• Extract Taxonomic Data from Node Names: to extract taxonomic data as SwissProt/Uniprot taxonomic codes (mnemonics) from nodes names in the form of 'xyz_CAEEL', or Uniprot/NCBI identifiers from nodes names in the form of 'xyz_6239'

• Transfer Node Names to Taxonomic Scientific Names: to interpret node names as taxonomic scientific names

• Transfer Node Names to Sequence Names: to interpret node names as sequence (protein, gene) names

• Obtain Sequence Information: to add additional sequence information

• Obtain Detailed Taxonomic Information: to add additional taxonomic information (from UniProt Taxonomy)

• Obtain Detailed Taxonomic Information (deletes nodes!): to add additional taxonomic information, deletes nodes for which taxonomy cannot found (from UniProt Taxonomy)

• Attach Vector/Expression Values: to add vector (e.g. gene expression) values (beta)

• Attach Molecular Sequences: to add molecular sequences to tree nodes (from Fasta-formated files)

View

• Basic Tree Information: to obtaining the information about name, rooting, rerooting, number of nodes (external and internal), number of branches, depth, maximum distance to root, distinct external taxonomies). As well as with Branch-length, Descendants per node, and support statistics

• Shows the how a tree looks as phyliXML, as Newick, and as Nexus files

Front Size

• To change a front size as: super tiny, tiny, small, medium or large front

Options menu

Display

This controls which data elements are being displayed (if present in current), such as:

• Lined Up Cladogram: to see tree as lined up cladogram (only present if phylogram in main menu is off)

• Non-Lined Up Cladograms: to see tree as non-lined up cladogram (only present if phylogram in main menu is off)

• Overview: shows a smaller scale version of a tree on the upper left hand corner

• Scale: display a scale

• Shapes for Internal Nodes: to visualize internal nodes by shapes (to pick a shape click the Cycle Node Shape)

• Shapes for External Nodes: to visualize external nodes by shapes (to pick a shape click the Cycle Node Shape)

• Line Up Diagrams (such as Domain Architecture): ...

• Seq Annotation ref Source:

• Colorize by Taxonomic Group: to color branches based on default color scheme (or allows to change at the configuration file?)

• Colorize Labels Same as Parent Branch: to color branches based on relationship, as a parent branch

• Abbreviate Scientific Taxonomic Names: shows full or abbreviated scientific taxonomic names

• Antialias: to reduce the prominence of jaggies, make output smother (turn off to improve graphics performance when displaying very large tree)

• Background Color Gradient: to change the background of three

• Cycle Node Shape Type: to change a node shape from circle to square by mouse click

• Cycle Node Shape Fill Type: to change a filling of node shape by mouse click to none, gradient or solid

• Enter Default Node Shape Size: to change default settings for shape size

• Enter Min Confidence Value: to change default settings of min confidence value (current 0)

• Cycle Overview Placement: to change default setting for overview placement (current upper left)

• Select Colors: to change default setting for color (current Default)

• Select Font: to change default setting for font (Current Verdana 10

Search

Different search options can be cchosen, such as

• Search Case Sensitive

• Match Complete Terms Only

• Search using regular expressions

• Negate Results

Graphics Export & Printing

Several option available to export and print output tree:

• Antialias: to reduce the prominence of jaggies, make output smother

• Export in Black and White

• Use Current Image Size for PDF export and Printing

• Use Current Image Size for PNG, JPG and GIF export

• Limit to Visible (“Screenshot” ) for PNG, JPG and GIF export

• Enter Default Size for Graphics Export (current:612:792)

• Enter Default Line Width for PDF Export (current 0.5)

Newick/NHX/Nexus Input

• Internal Node Names are Confidence Values

• Replace Underscores with Spaces:

• Ignore Distance Value Format Errors

• No Taxonomy Extraction

• Extract Taxonomy Codes/ids from Pfam-style Node Names

• Extract Taxonomy Codes/ids from Pfam-style like Node Names

• Extract Taxonomy Codes/ids/Scientific Names from Node Names

Newick/Nexus Output

Use Brackets for Confident Values

Use Internal Node Names for Confidence Values

Type

Type determines the layout type. Currently the following layout types are available:

• Rectangular

• Euro Type

• Rounded

• Curved

• Triangular

• Convex

• Unrooted

• Circular

Help

• Provides links to Documentation, Archaeopteryx Home, phyloXML Home, phyloXML Reference

• About: provides information about copyright, latest modifications and so on