Phylomatic Documentation

Version 3

Source

at github

Sending data with `curl`

curl is a handy command line tool for interacting with websites. You can send the data from a web-form back to the server from curl, if you know the parameters. The easiest way to use this to send data to phylomatic is first to create a text file (e.g., phylomatic.dat) with the parameter data:

      storedtree=R20120829&informat=newick&method=phylomatic&
      taxaformat=slashpath&outformat=newick&
      taxa=acanthaceae%2Fbravaisia%2Fbravaisia_sp1%0D
      acanthaceae%2Fsuessenguthia%2Fsuessenguthia_sp1%0D
      ...
      %0D

Note that there should be no line-breaks in your input file. The whole thing should be one long string of text. The %2F and %0D symbols are URL-encoded slashes and newline characters, respectively. Then just send the data to the server with:

      $ curl -d @phylomatic.dat http://phylodiversity.net/phylomatic/pmws > output.new

(The > output.new redirects the output to a file)

Too many taxa for this online version of phylomatic?

If you have more than about 5,000 taxa, a job on this server will take too long and the gateway will timeout. A limit of 5,000 taxa has now been placed on a taxa file. You have two alternatives:

Use the desktop version of phylomatic, available with phylocom, or
Use this (gawk-powered) version of phylomatic on your own computer:
1. Acquire the files from github.
2. Make sure the first line of the pmws file points to your gawk (version >= 4.0) executable.
3. Run with (for example):

      $ echo "informat=newick&storedtree=R20120829&method=phylomatic&taxauri=http://phylodiversity.net/phylomatic/eg/taxa_sample&outformat=newick&local=1" 
        | path/to/pmws > out.new

(Note the local=1 switch!)

Too many taxa for this online version of phylomatic? (Windows!)

(2017-03-30) It seems people are needing to process more and more taxa, and the online phylomatic is insufficient for many users. Here is a more detailed HOWTO for running phylomatic locally on Windows. Please note, this solution is an ugly kludge (the software is written to work in a UNIX web-service framework, not a Windows desktop!), but it seems to work

Visit github and download the ZIP file for phylomatic (click on Clone or Download on the right). Unzip it somewhere.
Get gawk (version 4.0 or greater) from here, and cURL from here (choose Win32 generic). Unzip the files and locate gawk.exe and curl.exe and copy them into the top directory of the phylomatic bundle, the same directory that has pmws in it.
Create a plain text file with your commands in it. Use a plain text editor (Notepad++, or even just Notepad). Call it, e.g., commands.txt. Here is an example:
```
        informat=newick&storedtree=R20120829&method=phylomatic
        &taxauri=http://phylodiversity.net/phylomatic/eg/taxa_sample
        &outformat=newick&local=1&clean=true
      
```
There should be no breaks in the string (unlike the example above). What this command does is pass the same arguments from the phylomatic web form to the program, so see that page if you are unsure of the meaning of the arguments.
Find the Command Prompt on you Windows system (e.g., see here). Try searching for CMD.EXE. Open it, and navigate to the phylomatic directory, using CD. To be sure you are there, type DIR, and you should see pmws, commands.txt, gawk.exe and curl.exe.
Now to run phylomatic. Use the above commands.txt example first, to be sure your setup is working. In the Command Prompt, type:
```
        TYPE command.txt | gawk -f pmws
      
```
You will see some errors (“Can’t recognize…”, etc.), but you should see a Newick tree appear at the bottom. Success!
Once you are sure all is working, use the URL of your online taxa list (taxauri=http://...) and the URL of your framework tree (treeuri=) if not using a builtin tree. You should redirect the output to a file:
```
        TYPE command.txt | gawk -f pmws > mytree.new
      
```
Hit Enter, and go have a cup of tea (or many!). Large taxa lists will take an hour or more to run. Hope this works for you.

Acknowledgments

Thanks to the Phylotastic working group at NESCent, and the sponsors of the meeting.

Previous phylomatic versions

PHYLOMATIC v2 IS NOW OFFLINE (2013-01-10) The phylomatic v2 web-app was just hacked. I could restore it, but in its current form, I would have to do some significant rewriting to make it fully secure. Since developing the (more secure, I hope) phylomatic version 3 web service, I am not inclined to spend time on v2, and so must depreciate it. I am aware that some users have built version 2 into scripts, and apologize in advance for any work required to re-write script to utilize version 3; please blame the hacker rather than me. If converting to version 3 will present a significant problem for you, please do contact me via email.

For reference only: version 2 form, background and description of API.
Version 1 background