Getting, installing, and working with peyotl

Peyotl is a python library that can interact with many of the services and files available through the Open Tree of Life. Here are some simple instructions on how to get a working copy of this library on your system so that you can start playing with the API, studies, and trees. For more details than what is presented here check the peyotl github page.

##Getting peyotl## To get peyotl, you will need git, which you can get in a number of different ways, each depending on your system. Check this website. Then, go to where you would like it installed and run git clone https://github.com/OpenTreeOfLife/peyotl.git. That's it!

##Installing peyotl## Because of the requirements that peyotl has, it is recommended that you use virtual-env. This simply lets you make something of a sandbox where you can install the requirements and peyotl in a safe place away from the rest of your system. Here are some instructions to get virtualenv or the right python for Linux and Mac.

###Linux### For Ubuntu and Debian linux based systems, you can just run sudo apt-get install python-virtualenv and that is it!

###Mac### Even if you don't want to use virtualenv, you probably want to use a different python than the one that is installed with the system. The python that comes with the Mac is not complete and often not up to date. There is a simple solution to this which is to install homebrew. You can follow the instructions there (which consist of running this ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" ) and then you have homebrew installed! Homebrew lets you install a bunch of unix tools in a safe place (/usr/local). Now you can install python like brew install python. Then make sure that you are using the new python and so you should run which python and it should say /usr/local/bin/python. If so, then you are good. Now, you can install virtualenv like pip install virtualenv.

###Working with virtualenv### All you have to do to create a new virtual environment with virtualenv is go to where you want to make this environment (doesn't really matter where) and type virtualenv new-env. This will make a directory called new-env. To work within that environment, you just need to then run source new-env/bin/activate. Now you are working within a safe environment. You can go to other directories and do what you like, including installing other python packages. They will only install in this virtual environment. So if you mess up, you can just delete that new-env directory and start over. To exit, you just type deactivate. In the future, you will just type source new-env/bin/activate.

###Actually, installing peyotl### So, if you have a new virtual environment, let's activate it. (If not, still follow the following instructions, you just won't be in the virtual environment). Now run the command cd peyotl to change directories to inside the peyotl package that you downloaded with git above. Run pip install -r requirements.txt, which will install all the required python packages for peyotl (inside your virtual env). Now you can run python setup.py develop and you should be good to go! Peyotl expects to find some information about where certain files or servers are. To get that in the right place, run mkdir ~/.peyotl && cp extras/dot_peyotl/config ~/.peyotl/config. Then you can edit ~/.peyotl/config to the location of things (such as if you have a local copy of phylesystem -- which isn't required). More details on this configuration can be found here.

##First steps with peyotl## To make sure that you have peyotl correctly installed (in your virtual environment), just type python. From inside your python, type import peyotl. If there are no errors, you are good to go! Try this then

from peyotl.api import APIWrapper
a = APIWrapper()
oti = a.oti
b = oti.find_trees(ottTaxonName='Lonicera')
print b

You will get something like this

[{u'ot:studyId': u'pg_424', u'matched_trees': [{u'nexson_id': u'tree532', u'oti_tree_id': u'pg_424_tree532'}]}, {u'ot:studyId': u'pg_422', u'matched_trees': [{u'nexson_id': u'tree531', u'oti_tree_id': u'pg_422_tree531'}]}]

which is a list of dictionaries containing the studies and trees that contain Lonicera.

back to the Tutorials