User guide

Everything is done from the List view (Home) or the Tree view (Trees). The basic workflow is to create a list of scientific names (species or higher taxa), click on Get tree, then view the tree. If you only know common names instead of scientific names (e.g., "raven" instead of "Corvus corax"), check the FAQ item How do I find scientific names?.

If you don't have lists of your own, try a public list. Create custom lists by selecting from the Make a New List menu:

  • Upload my list: upload a pre-made list of names (one per line, or DwC-A)
  • Extract from doc: create a list by scraping names from a file
  • Extract from web: create a list by scraping names from a web page
  • Choose taxon: create a list by sampling from a taxon
The new list will appear in My Lists. At any time, you can click on Home and select a list to view it.

If you don't have any trees, select a list and choose Get tree. Retrieved trees are saved and can be accessed in Trees at any time from the My trees list.

The list view (Home) shows available lists (left), a list viewer (center), and a menu for making new lists (right). Click a list to view its contents in the list viewer. Now you can

  • select or unselect names before requesting a tree
  • view a taxon matching report
  • download the list as text
  • delete or rename the list

To view a tree, from Trees view, select a tree name from My Trees or Public Trees. We sometimes don't get the size of the tree right: you may need to use your browser's zoom feature.

Use the control panel (above) to modify features that affect the whole tree (e.g., line width), or to download an image. "Show node labels" often reveals useful taxonomic names on internal nodes. Click on individual nodes to access options such as

  • highlight this group or branch
  • retrieve an image for this species
  • see a web page about this species in the Encyclopedia of Life

Using the menu at right, you can rename, delete, or export the tree. Select Export to save the tree in Newick (New Hampshire) format.

From Home, choose Upload my list from the menu at right. You can upload your own custom list of taxa as either a text (.txt) file with one name per line, or as a Darwin Core Archive (DwC-A) file. The DwC-A format allows you to maintain metadata such as a description and author with your list of names (click here for a template you can modify).

The portal will immediately try to match your names against OpenTree's taxonomy.

From Home, choose Extract from doc from the menu at right, then select a file (.pdf, .txt, .doc, .docx, .xls, .xlsx) that includes scientific names (it can also include other text). The file will be processed in 3 steps:

  1. text will be extracted (or recognized by OCR-- very slow)
  2. name-like strings will be identified
  3. the name-like strings will be matched against GlobalNames resources
and the new list will appear in My Lists.

From Home, choose Extract from web from the menu at right, then enter a URL. The resource will be processed in 3 steps:

  1. text will be extracted
  2. name-like strings will be identified
  3. the name-like strings will be matched against GlobalNames resources
and the new list will appear in My Lists.

From Home, choose Choose taxon from the menu at right, then enter a scientific name for a higher taxon such as a genus or family ("Canidae", "Felidae", "Passerina"). If desired, choose one of the options to get a subset of that taxon

  • location - checks iNaturalist for occurrence records in designated country
  • has genome in NCBI - checks NCBI for species with genome record
  • random subset - picks a random subset of species from the named taxon
The new list will appear in My Lists.

Important note: You can choose a taxon of any size if you subset by "has genome in NCBI", but if you try to enter the name of a taxon with > 1000 species (e.g., "Aves", "Mammalia") and you are not subsetting by genome, you will be disappointed-- we just don't have the capacity for that yet.

When viewing a list created by any method, pressing the "Get tree" button (bottom of screen) will extract a tree for the selected list items from Open Tree's synthetic tree. Because the synthetic tree lacks branch lengths, this is the unscaled tree. The web portal will automatically try to rescale the tree to geologic time. Use the control panel to change the tree version from "unscaled" to one of the following

  • Median: tree scaled by DateLife's median summary method
  • OpenTree: tree scaled from a dated version of the Open Tree of Life
  • SDM: tree scaled using DateLife's implementation of the Supertree Distance Matrix method. This is very slow, so this option is available only for very small trees.


FAQ

Your modifications (e.g., highlights, thumbnail images) were lost when you navigated away from the tree. We're sorry about that. Until this is fixed, be sure to save your modified tree view as an image file before navigating away.

The two most common reasons are

  • More than 1000 matching names. You can maintain a list with > 1000 names, but currently we can't get a tree that large. This will be fixed in the future.
  • Less than 3 matching names. This can happen if your list is mostly extinct taxa: many such taxa are recognized in taxonomies but are not in our phylogeny resources.
If you failed to get a tree for some other reason, please tell us about it using the feedback form (include your email address, and paste your downloaded list into the form).

If you uploaded your own list (text or DwC-A), unrecognized names appear below the list viewer: you can edit the name and click Search to try again. Most failures are due to spelling errors, but sometimes the name just isn't in our sources (to find out if a name is in OpenTree, use the search box in the upper right of this page).

If you attempted to scrape names from a file or web page, then your list will be missing both (1) names that were not recognized by GNRD, and (2) names that were recognized by GNRD but did not match any of its taxonomies. You can try to debug this problem by going directly to Global Names Recognition and Discovery, but the practical work-around is to download the extracted list, add the missing names, and upload it again (see "How can I add, remove or change a species in my list?").

If you start the "Choose taxon" workflow with a taxon that is too large, the job may terminate before a list is returned (see the user guide above). The same thing will happen if you submit a resource for name-scraping that is enormous. The solution is to scale down your ambitions.

If the issue is not size, it is probably something to do with format, language, or encoding. If you are trying to use a DwC-A input, compare the format carefully to the template provided. See this stackoverflow thread for ways to find non-standard characters. If you can't fix the original resource (e.g., a web page you don't own), make a copy and fix it.

If you still can't make a list, contact us using the feedback form and be sure to include your email address.

Currently the tree viewer supports only minimal editing and customization, and the Export function only includes the tree topology and names-- not images, link-outs, or high-lighting. In the future, we will provide a way to export Phylotastic trees with images and link-outs, so that they can be modified using other tree-viewers-- but first we have to convince other developers to agree with us on annotation standards.

Phylotastic trees are retrieved from existing sources that store trees or merge them into supertrees. Currently all Phylotastic trees are based on the supertree developed by the OpenTree project (their "synthetic tree"). OpenTree begins with a taxonomy covering millions of species, and a database of curated "source trees". The source trees are then used to add phylogenetic information to the taxonomy, using the method of Redelings and Holder, 2017.

List editing is not fully implemented. The work-around is:

  • in the list viewer, select the names you want to keep
  • choose "Download selected taxa as text"
  • edit the file, and then upload it as a new list
  • delete the old list if desired

Our image service harvests thumbnails from the Encyclopedia of Life (EOL) project. Full-size images can be found by clicking on a node and following the "EOL" link. Note that the authors of images frequently retain rights to their use (the use of thumbnails is allowed under the Fair Use doctrine).

In the future, we will provide some support for common names like "raven" (Corvus corax) or "Minke whale" (Balaenoptera acutorostrata). At present, you need to supply scientific names. They are not hard to find-- you can search Wikipedia or NCBI taxonomy, or just use Google (for best results, combine the name with "species" or "taxonomy"), e.g.,

Our ability to deliver trees instantly depends on resources that provide pre-computed trees. Currently, OpenTree is the only resource we are using. Large parts of OpenTree's synthetic tree are based on taxonomy alone: this is why there are so many polytomies. If you know of published phylogenies that would cover some of these gaps, and you want to help, see "How can I make the world a better place?".

Our ability to deliver results quickly and conveniently depends on the availability of other resources that have programmable interfaces and provide good-quality data. Click on "About" (above) to see a list of these resources.

By making it incredibly easy to find results, the Phylotastic project exposes both the strengths and weaknesses of these resources. If the results obtained here are misleading or incomplete, this means that the underlying resources can be improved. For instance, if you find a part of the tree that is unresolved, and you are aware of published trees that provide more information, you can help out by notifying OpenTree or, better, becoming a curator yourself and adding the tree to OpenTree's database, so that it will be included automatically the next time a supertree is computed.

Currently, the only way to make a list public is to use the DwC-A format. This is because we want public lists to be documented with author, description, source, and so on.

Supporting studies are publications on which the tree is based. In the case of trees derived by subtree extraction from OpenTree's synthetic tree (supertree), the supporting studies provide the trees used to refine the taxonomy to make a supertree, by the method of Redelings and Holder, 2017. The studies listed for your subtree provide support for specific nodes in your subtree.