Userguide


CompPhy is a web platform dedicated to the collaborative handling of phylogenetic trees. Users can freely manage collections of trees, associated documents, and communicate on a common project. CompPhy offers functionalities covering tree edition, tree comparison, supertree inference, data management and, most specifically, collaborative work, e.g. allowing several persons to work together at the same time on same project. CompPhy relies on web technologies to offer shared tree visualization, (a)synchronous manipulation of trees, data exchange/storage, as well as a timeline and a forum on each project to keep track of the dataset analysis progress.

A project can be private or public. When public, any non-member with the link can view the trees of the project with limited functionalities, but cannot modify the trees or anything in the project. Private projects are only accessible by the project members, whose list is maintained by the project administrator.

The main input to a CompPhy's project consist of trees in Newick format, such as:

       (STAAT_2_PE2456:0.01,(STAAE_1_PE2425:0.02,(STAAC_1_PE2417:0.01,STAA8_1_PE2683:0.03)90.5:0.007)20:0.02);

You can also import trees in nhx format. It's like newick, but you can also add custom tags for a node in a key-value format like that: [&key=value]. Current keys recognized by compphy are color or branchColor for the branch color, and collapsed for collapse a node. The nexus format is also accepted, which include a nhx string.

Compatibles browsers

CompPhy has been successfully tested on Mozilla Firefox and Google Chrome. We recommend to use these browsers. Our technologies are not compatible with Internet Explorer. Please use another browser.
firefox chrome

We present below the different parts of CompPhy's interface when on a project page and the functionalities available therein.

Interface zones

CompPhy online interface

 

Zone 1

Zone 1  mostly contains the website navigation bar. The public  /private  status of the project is indicated next to the project's name. By default, projects are created with a private status meaning that only the project’s members can access the data, after being identified by CompPhy. This policy guarantees data privacy while still allowing data sharing. In contrast, a public project can be accessed by any guest to which the URL would have been sent. Without opening an account on CompPhy and being project's member, they can see the project’s trees and examine them on the workbenches, but they are not allowed to perform changes to the trees or data of the project.

Zone 2

Zone 2 contains the project's menu that presents tabs specific to the project: trees (the main project page), forum, documents and settings. Then it displays two boxes, one under the other. Each one provides users with a brief overview of a tree collection (currently CompPhy handles two collections). Every tree has its name on top and can be moved to a different place within the collection by dragging it from this name. A transparent blue blox on the left, resp. right, side of a tree indicates that this tree is currently displayed on the left, resp. right workbench (Zone 3). Click on the tool icon open a menu to rename or delete the corresponding tree.
Finally, on the right-hand side, a collaborative box lists the connected members and displays the information related to the interaction of a project's members. The member with the crown is the administrator of the project.

Zone 3

Zone 3 displays two workbenches, showing in full size two trees side by side to ease their comparison. Any tree from Zone 2 can be put on the left/right workbench by dragging there its sketched picture (or by clicking on it with the left/right mouse button). Tools available in this zone either apply to each of these trees separately or make use of both trees together. Some links are available to download the data of a specific tree (the picture or the whole data of this tree).

Tools applying to one or both tree(s):

Left/Right arrows
Clicking on these arrows allows users to quickly navigate among trees of a same collection, in the workbench below.


Custom tools

Custom tools
Open a dialog to configure tree customization. On branch click: color branches, clade, subtrees, taxa ; change branch thickness. On node click: collapse a node, or swap children nodes. Tools are enabled only when the dialog box is opened (can be minimized), but disabled when it is closed.


Zoom

Zoom
Zoom dialog is automatically opened on zoom with ctrl + mouse wheel, and is closed few seconds after the zoom ended. You can also open it permanently by clicking on the zoom icon in the toolbar between the two trees.
At the top of the dialog, the back-filled arrow icon point to the workbench represented in the frame below. You can click on the arrows to change of workbench. Below, the black-frame represents the whole tree, and the red frame the part of the tree visible in the workbench.
Below, the three icons represent (from the left to the right): zoom +, zoom -, reset zoom.
The last line of buttons to select the type of zoom (from the left to the right): bidirectionnal (default), expand horizontally only, expand vertically only, or select the zone on the tree into zoom.


Zoom

Search for taxa
Search taxa that contains a keyword. The matching taxa are blinking. Then, you can highlight these taxa with a predefined color.


Zoom

Display options
A menu to select default display options:

  • Inner labels : show branch length, branch support, both or none.
  • Show or hide taxa names.

Zoom

Tree options
On each workbench, click on the tool icon opens a menu with several options:

  • Show legend: show the legend for side annotations of the tree.
  • Edit legend: edit this legend (change colors or rename values).
  • Adapt tree tree to the view / Adapt view to the tree.
  • Reverse tree (horizontal flip).
  • Propagate side annotations (to: the other tree / the collection / all trees) : all annotations or colors only.
  • Propagate tree customizations (to: the other tree / the collection / all trees).
  • Reset tree customizations: reset color of branches and subtrees background, and branches thickness.
  • (Un)Collapse all nodes, or auto-collapse by nodes depth.
  • Change inner nodes labels for this tree : branch lengths, support, both or none.
  • Show annotations statistics: for each column of side annotations, see the repartition of annotations on leaves.
  • Show/Hide taxa names for this tree.
  • Export tree as SVG/PNG or save newick.

Context menu
Right-click of some items of the tree to do specific actions:

  • On taxa to rename them.
  • On a branch to reroot the tree using the children subtree as outgroup, or propagate tree customizations of the subtree to other trees.
  • On an inner node to (un)collapse it or see/add annotations to this node (add annotation requires you have the control on the tree).


Tools comparing the two trees displayed on the workbenches:

RF distance

Distance tool
Computes the distance between the two displayed trees : the trees are restricted to their common taxa before computing their distance with the Treedist tool ("symmetric difference" option). The result is the number of branches present in one tree but not in the other (here, a branch is characterized by the list of taxa in the corresponding subtree).
Felsenstein, J. 1993. PHYLIP (Phylogeny Inference Package) version 3.5c. Distributed by the author. Department of Genetics, University of Washington, Seattle.


MAST

MAST consensus tool
Computes a Maximum Agreement SubTree (MAST) of the two trees displayed on the workbenches. A MAST is a subtree common to both input trees that contains a largest subset of taxa. Two new trees will be created in the collection of the trees selected for the MAST. The new trees will be the same as the original ones but blurring the non-common topology (the branches are dashed and the leaves are grayed) to highlight the MAST structure.


Swap

Auto swap tool
Automatically swaps the branches of the right tree according to the left tree, which helps detecting their topological (dis)agreements by imposing a similar taxa order.

Zone 4

Zone 4 proposes editing tree notes, tree side annotations and tree structure:

Add/Show tree notes
Allows you to add custom notes to each tree. You must have the control on the tree to do that. Otherwise, you can see the notes others added, without change them.


Add side annotations
Allows you to add side annotations to the tree shown directly above (Zone 3). Annotations are edited in a table, with for each taxon the value of the annotation in each column. These annotations can be edited manually or imported from a CSV/TSV file (see below for the format).


Manual newick editing
Allows you to modify the structure of the tree shown directly above (Zone 3). Basically, a Tree is a newick string. This tree is transformed in a picture you see above. Users with a basic knowledge of this language can modify the newick string manually.

Zone 5

Zone 5 mainly proposes tools that can be applied on a subset of chosen trees:

Timeline

Timeline & TO DO list
The Timeline of a project is the list of performed steps you decide to emphasize. Everytime you add a historical point in the timeline, you can also save the tree collections in their current state, as a backup. When restoring a previous bakcup, the current tree collections are replaced by those existing at the time the backup was performed (e.g., recent modifications in the trees as well as new trees will be lost).
The TO DO list allows you to plan future steps of the project. TO DO items can be re-ordered and a TO DO item can be transferred in the timeline.


Restrict trees

Restrict trees
Restricts several trees to the taxa they have in common. The user can select two or more trees but the whole set still must have a non-empty common leaf set and each selected source tree has to possess at least two such leaves. The restriction of each selected tree will appear as an additional tree at the end of the same collection.


Reroot trees

Reroot trees
Allows you to reroot specified trees. You have to select the trees you want to reroot, then write a list of desired outgroups. For instance, if you want to reroot the tree by putting the group composed of Mus and Rattus at the root, write: "Mus,Rattus". Beware that taxa names you specify as outgroup must strictly match those indicated in the trees you want to reroot, that is they must be composed of the same ordered list of characters (letters, numbers, ...). Moreover, avoid space characters in the outgroup taxa list.
When several outgroup taxa are indicated, the tree is rerooted if it contains at least one of these taxa and if all the outgroup taxa it contains are in a same group, that moreover does not include any other taxa (as any such taxa is considered to be an ingroup taxa).
When rerooting a tree, the rerooted tree can either replace the original tree in its collection, or be added as a new tree at the end of this collection.


Color trees

Add side annotations
Proposes you to add side annotations to selected trees of the project. Select a CSV/TSV file containing your annotations, and set the correct separator and text separator. This file must have in the first line the name of the columns. In the next lines, the first column is the taxon name, and other columns the different annotations corresponding to column names. Select trees. On each of these trees, add annotations to matching taxa.


Compute an additional supertree

Compute a supertree
Computes a supertree from a set of source trees by one of two methods: MRP (Baum & Ragan 2004) and PhySIC_IST (Scornavacca et al 2008). The former is an optimization method, while the latter is a consensus method. MRP outputs a supertree containing all taxa of the source trees and composed of subtrees supported by more source tree branches than other candidate subtrees. By default, PhySIC_IST outputs a consensus supertree, i.e. a tree whose subtrees are supported by a vast majority of the source trees*. PhySIC_IST can exclude "rogue" taxa from the supertree, that is taxa having a notably different position in different source trees. Moreover, its consensus behavior can be toggled from strict consensus to a kind of majority-rule consensus by decreasing a parameter value (STC) from 1 to 0 (see PhySIC_IST website for more details). Additionnally, PhySIC_IST can produce a new version of each source tree changing due to a significantly conflicting signal present in the other source trees. There is a box that you can check before asking PhySIC_IST to run, so that the tree collection contains these new versions of modified source trees (they appear as new trees in the collection with a red pastille on the top right, with collapsed branches in red and removed taxa in grey, while green pastilles on existing source trees distinguishes those in which no modification was necessary). By default, modifications of the source tree collection are off.

To compute a supertree with a given method, select a set of trees in the left (PhySIC_IST) or right (MRP) part of the panel. Several parameters can be set before computing the supertree:

  • MRP: to combine all trees that most parsimoniously represent the source trees, the official MRP method recommends to resort to a strict consensus tree. Here, a majority-rule and a greedy consensus are also available.
  • PhySIC_IST: the branches of the source trees with a support lower than a specified threshold can be ignored (Support threshold for source clade selection), and the behavior of the method can be tuned from veto to vote (Correction threshold used by STC - see description above). See the PhySIC_IST website for more information on the method and its parameters.

The computed supertree will appear at the end of the Tree collection 2. Note that the MRP method produces an unrooted supertree, that is arbitrarily rooted by Compphy, at the trifurcation indicated in its newick form.

Be aware that computing a supertree can be very long (from a minute to several hours, depending on the number of taxa in the source trees) and that CompPhy will be unavailable while running the supertree computation job. So if you want to compute a supertree from a large data set, we recommend you to go to the PhySIC_IST website, then upload on CompPhy the supertree once it has been computed.

* Note that in both methods, only source trees containing relevant taxa can vote for a given subtree (that is source trees containing at least several taxa of the given subtree). Note that MRP returns trees without branch lengths and PhySIC_IST only provides branch lengths to improve the display of the tree (these lengths do not reprensent evolutionary distances).

Baum BR, Ragan MA. The MRP method. In: Bininda-Emonds ORP, editor. Phylogenetic supertrees: Combining Information to Reveal the Tree of Life . Dordrecht: Kluwer Academic; 2004. pp. 17–34.

Scornavacca C., Berry V., Lefort V., Douzery E.J.P., Ranwez V. BMC Bioinformatics. 2008, Oct 4;9:413.


Change taxa names

Change taxa names
Allows you to change the name of one or several taxa in all or chosen trees. Unlike tree names, taxa names can be quite long. Note that several tools of Compphy use taxa names to compare trees (e.g., computing the MAST of two trees or their Robinson and Foulds distance,  computing a supertree from source trees, ...). In such cases, taxa in different trees are identified only if they have the same name (e.g.Mus, Mus_musculus and  Mus_Musculus_M9B286 will be considered as different taxa).


Upload trees

Upload trees
Allows you to import trees in collection 1 or 2. Imported trees must be in Newick format and can be contained in a file for upload or manually entered in a text field (accepting cut and paste). 


Delete trees

Remove trees
Allows you to delete selected trees in the project. Beware that trees are removed permanently. They can only be recovered if you have performed a backup including these trees (see backup option in the Timeline tool).

 

Zone 6

Zone6 is a right toolbar that proposes different collaborative items:

User parameters

User parameters
Parameters to apply on control ask on a tree:

  • Ask me (default): show a message when control on a tree is requested, with buttons to accept or refuse.
  • Always give it: give the control without prompt.
  • Always refuse: never accept to give the control, without prompt

notifications

Notifications
Notifications are stored here automatically if not closed before. A number indicate the number of unread notifications.


requests

Control requests
Store unanswered requests to a tree control. A number indicate the number of the requests you have.


chat

Chat
Open the chat of the project. Available only on the project main page (the one containing your trees). Used to send short messages to your colleagues. The last 1000 messages are saved and can be read in your next session. For long messages, please prefer the forum.


How to edit a tree?

To edit a tree, you must have the control on it. You can get it by clicking on the "ask control" button on the tree header of a workbench. If tree is green, control will be automatically given to you. If it's orange, there is already somebody controlling this tree. When you ask control, he/she will receive a notification. If he/she accepts, you will have the control. Sometimes, the tree could be red. There is no ask control button because somebody has the control and another body has already asked the control to him. You can ask to be notified when the tree will become askable again.

When you have the control on a tree, you can open the Custom tools (button on zone 3) to custom the tree.