Link Search Menu Expand Document
PHRAPL documentation

INSTALLATION

  1. System requirements
  2. Installation with conda environment (Recommended)
    1. For macOS
      1. Create a conda environment and compile code.
      2. Activate and deactivate conda environment.
      3. Save conda environment in yml file.
      4. Create a new conda environment with your yml file.
    2. For Linux
      1. Create conda environment and compile code.
    3. Other options to export and share conda environments
      1. Spec List
      2. Clone
      3. Pack
  3. Info – installation requirements
    1. R
    2. PHRAPL dependencies in R
    3. ms
    4. Perl
  4. Known installation issues.
    1. P2C2M and rPython
    2. devtools and diagram
    3. rgl (for mac users)
  5. Quick install (not recommended)

System requirements

PHRAPL can only be used in macOS and Linux. PHRAPL requires R, ms, and perl to be installed in your computer. This tutorial assumes you are working in a Mac/Linux environment. We have yet to properly test the method using a PC, although we suspect a few (surmountable) issues will arise when the sufficiently adventurous try this out.

Because the PHRAPL source code has not been updated, you may encounter some compatibility issues with some R versions and some dependencies. Therefore, the easiest and long term solution for this issue that will ensure reproducibility of your code, is creating a conda environment exclusive for PHRAPL.

If you have not used conda before, please got to this page to download anaconda and then follow the instructions to install it your macOS or linux system.

You will need to activate (not create) this environment each time that you run `PHRAPL`.

For macOS

Create a conda environment and compile code.

Compiling source code within conda environments in macOS sometimes might be tricky. Here, we have tried to address the potential issues, just copy-paste the code below in your mac terminal (not in R terminal). But see this page if you are running into issues.

## create conda env and configure linker
conda create --name OX_env_phrapl
conda activate OX_env_phrapl
export PREFIX="${CONDA_PREFIX}"
export CONDA_BUILD="1"
conda activate OX_env_phrapl

## Installing the macOS SDK --> required for compilation
## requires admin permits
sudo mkdir -p /opt
cd /opt
wget https://github.com/phracker/MacOSX-SDKs/releases/download/10.13/MacOSX10.9.sdk.tar.xz
tar -xf MacOSX10.9.sdk.tar.xz

## set env variable
export CONDA_BUILD_SYSROOT="/opt/MacOSX10.9.sdk"


## Install R and PHRAPL dependencies in your conda environment
conda install r-ape r-devtools r-rgl r-gmp r-rjsonio -c r 
conda install -c conda-forge/label/gcc7 r-gmp

## update devtool dependecies (not installed by default in "r" channel) ¯\_(ツ)_/¯
conda update r-devtools -c conda-forge

## download dependencies that will be installed locally
## Due to compatibility issues with new R versions, these libraries have to be downloaded and installed from source code locally.
wget https://github.com/ariadnamorales/phrapl-manual/blob/master/dependencies/rPython_0.0-6.tar.gz
wget https://github.com/ariadnamorales/phrapl-manual/blob/master/dependencies/P2C2M_0.7.6.tar.gz

## install dependencies
R CMD INSTALL rPython_0.0-6.tar.gz
R CMD INSTALL P2C2M_0.7.6.tar.gz 

## (optional) ---> remove "##" if you want to remove the source code downloded for installation.
## rm rPython_0.0-5.tar.gz
## rm P2C2M_0.7.6.tar.gz 


## Load R, clean variables github variables (in case there is an issue), and install phrapl
## Run this still in your mac terminal.
R

## wait for R to be loaded
library(devtools)
install_github
github_pat(1)
github_pat
Sys.getenv("GITHUB_PAT")
Sys.unsetenv("GITHUB_PAT")
Sys.getenv("GITHUB_PAT")
Sys.setenv(RPYTHON_PYTHON_VERSION=3)

devtools::install_github("bomeara/phrapl")

quit()
n

At this point, you can close your terminal or deactivate your OX_env_phrapl conda environment, and then activate it each time you need to use `PHRAPL`.

Activate and deactivate conda environment.

## Load your conda environment
conda activate OX_env_phrapl

## Deactivate your current conda environment
conda deactivate

You know that the OX_env_phrapl environment has been loaded because your terminal looks like this:

(OX_env_phrapl) my-MacBook-Pro:

Save conda environment in yml file.

If you want to save this conda environment to install everything again in a new computer, save a yml file, and then use it to create a new environment.

## save conda env
conda env export > env_phrapl.$(sw_vers -productName)_$(sw_vers -productVersion)_$(date +%Y.%m.%d).yml

The output will be a file like env_phrapl.macOS.11.2.3_2021.08.13.yml (I created mine on a macOS Big Sur version 11.2.3 on August 13, 2021). But the OS version and/or date may differ in yours. Conda environments are not always transferable, so it is good to keep track of when and, most importantly, under what OS was created. Save this file with the rest of your `PHRAPL` scripts, your future self will thank you :)

Create a new conda environment with your yml file.

Then, to create a new environment in a new computer type:

conda env create -f env_phrapl.macOS.11.2.3_2021.08.13.yml
## Do not forget to change the name of your yml file.

For Linux

Create conda environment and compile code.

This should be “more straightforward” in linux than macOS. Make sure that your “.condarc” and/or “.bashrc” point to a local folder, if you do not have admin permits.

## create conda environemnt with PHRAPL dependencies ---> to be used in linux


### ----> These steps may change depending on your system. Ask your system admin if in doubt.
## module load gcc/4.9.2
## export PATH=$HOME/miniconda3/bin:$PATH

## Create conda env
conda create -n linux_env_phrapl r-essentials r-base
source activate linux_env_phrapl

conda update -n base conda
conda install -c r r-ape 
conda install -c r r-devtools
conda install -c r r-rgl 
conda install -c conda-forge/label/gcc7 r-gmp
conda install -c r r-rjsonio

## Get packages that may not be available
wget https://github.com/ariadnamorales/phrapl-manual/blob/master/dependencies/rPython_0.0-6.tar.gz
wget https://github.com/ariadnamorales/phrapl-manual/blob/master/dependencies/P2C2M_0.7.6.tar.gz

## Install dependencies locally
R CMD INSTALL rPython_0.0-6.tar.gz
R CMD INSTALL P2C2M_0.7.6.tar.gz 

## (optional) ---> remove "##" if you want to remove the source code downloded for installation.
## rm rPython_0.0-5.tar.gz
## rm P2C2M_0.7.6.tar.gz


R
Sys.setenv(RPYTHON_PYTHON_VERSION=3)
install.packages('devtools')
devtools::install_github("bomeara/phrapl")

quit()
n

To deactivate, activate, save conda environment in yml file, then and create a new environment from such a file, please see above for the macOS version instructions.

Other options to export and share conda environments

See more info here on how to manage conda environments.

Spec List

conda list --explicit > specList.env_phrapl.$(sw_vers -productName)_$(sw_vers -productVersion)_$(date +%Y.%m.%d).txt
conda create --name OX_env_phrapl --file specList.env_phrapl.macOS.11.2.3_2021.08.12.txt
## Do not forget to change the name of your txt file.

Clone

conda create --name snapshot.env_phrapl.$(sw_vers -productName)_$(sw_vers -productVersion)_$(date +%Y.%m.%d).txt --clone OX_env_phrapl
## Do not forget to change the name of your txt file.

Pack

With this option, you will save all the files need to recreate the conda environment without access to internet. ONLY works if the OS is EXACTLY the same.

conda pack -n OX_env_phrapl -o pack.env_phrapl.$(sw_vers -productName)_$(sw_vers -productVersion)_$(date +%Y.%m.%d).tar.gz

Info – installation requirements

PHRAPL requires R, ms, and perl to be installed in your computer.

R

Go to the following web page (http://www.r-project.org) and download the suitable version for your platform.

PHRAPL dependencies in R

## Install phrapl dependencies in R
install.packages(c("ape", "partitions", "lattice", "polynom", "gmp", "rgenoud","parallel", "optimx", "igraph", "numDeriv", "nloptr", "Matrix", "rgl", "RColorBrewer", "binom", "diagram", "P2C2M"))

ms

The most recent version of PHRAPL should install this dependency, If for some reason there is an issue, please intall int manually, and add it to your $PATH:. Go to the web page (http://home.uchicago.edu/~rhudson1/source/mksamples.html) and download ms.tar.gz. Or in your terminal window type:

wget https://webshare.uchicago.edu/users/rhudson1/Public/ms.folder/ms.tar.gz

The following commands will extract, compile the program and add it to your PATH:

tar -xvf ms.tar
cd msdir
gcc -o ms ms.c streec.c rand1.c -lm
sudo cp ms /usr/bin
sudo cp ms /usr/lib

It is not required to add ms to your PATH, you can specify its location in the GridSearch function.

Perl

If you are working on a Linux or Mac OS X platform, PERL will already be installed. Note that most of PHRAPL is written in R. However, the part of the code that matches observed trees to trees expected under a given model is currently written in Perl in order to speed up the method. If you are running PHRAPL on a Mac or Linux machine, Perl has most likely already been installed (to make sure, within R, you can type system("perl -v"), which will give you the version installed, if it exists).

Known installation issues.

The recipe to create a conda environment (see above) is meant to avoid any compatibility issues with other R packages, it should install all the required dependencies. But if you still have an issue, please make sure that the following packages are working properly.

P2C2M and rPython

The library and code of P2C2M is no longer maintained. Recent R versions have some compatibility issues with it and some of its dependencies (rPyhton and RJSONIO). The easiest way to solve it, is to dowload the source code, and install it locally.

## Get packages that may not be available
wget https://github.com/ariadnamorales/phrapl-manual/blob/master/dependencies/rPython_0.0-6.tar.gz
wget https://github.com/ariadnamorales/phrapl-manual/blob/master/dependencies/P2C2M_0.7.6.tar.gz

## Install dependencies locally
R CMD INSTALL rPython_0.0-6.tar.gz
R CMD INSTALL P2C2M_0.7.6.tar.gz 

## (optional) ---> remove "##" if you want to remove the source code downloded for installation.
## rm rPython_0.0-5.tar.gz
## rm P2C2M_0.7.6.tar.gz

devtools and diagram

It has come to our attention that one of the R packages that PHRAPL imports, diagram, includes an error in it’s DESCRPTION file such that devtools can’t install it. Thus, if you are thrown an error upon trying to install PHRAPL using devtools (something along the lines of Invalid comparison operator in dependency: >=, try installing diagram first without devtools, by typing install.packages("diagram"). Then, try installing PHRAPL again using the devtools command.

rgl (for mac users)

Also, for Mac users, if you experience issues with rgl properly installing, another PHRAPL dependency, you should try updating your version of XQuartz (https://www.xquartz.org/), then reinstalling rgl separately in R (install.packages("rgl")). Then install PHRAPL.

(Assuming you have installed all dependencies and there are no compatibility issues).

If you have installed R, ms, and perl in your computer, go ahead and install PHRAPL!. Launch R and type:

install.packages("devtools")
devtools::install_github("bomeara/phrapl")