---
title: 'Potential Path Volume (PPV): A Simple Example'
author: "Urska Demsar and Jed Long"
date: "29 November 2018"
output: html_document
---

```{r setup, include=FALSE}
chooseCRANmirror(graphics=FALSE, ind=1)
knitr::opts_chunk$set(echo = TRUE)
```

# Potential Path Volumes

This is a simple example of the potential path volume (PPV) method for quantifying 3D home ranges from animal tracking data. 
The code is meant to be used as a demonstration of the potential of the method. A simple synthetic dataset of a movement path going up and then downwards is used.

## Installing the package

The PPV method is available as the function \texttt{ppv} in the package *wildlifeTG* which is available on GitHub.

It can be easily installed in R using the *devtools* package:

```{r}
#install.packages('devtools')
library(devtools)
#install_github('jedalong/wildlifeTG')
library(wildlifeTG)
```


The function \texttt{ppv} is used to create a potential path volume. The input is an *ltraj* object from the *adehabitat* package, where an additional column in the *infolocs* slot provides the elevation/altitude information. The column name is passed into the function \texttt{ppv}. We need to specificy the a parameter *vmax* which describes the maximum movement speed (in 3D) often it is useful to derive this from the tracking data in some way. Finally, we must specify a voxel resolution, in the same units in which x, y, z are provided. It is typical that x, y, z are in the same units, but there may be reasons to specify z in different units to exaggerate vertical effects for example. The voxel resolution is the greatest factor in how long the algorithm takes, consider the range of the values in x, y, and z when choosing the parameter *vox* and I have found that a good rule of thumb is to try to not have more than 1 million voxels in the map.

We will create some simulated data to test the PPV method, showing a simple up and down movement.
```{r}
x <- 1:7 + rnorm(7,0,0.2)               # x-coordinates
y <- 1:7 + rnorm(7,0,0.2)               # y-coordinates
z <- c(0,1,2,3,2,1,0) + rnorm(7,0,0.2)  # z-coordinates
t <- as.POSIXct(Sys.time()+1:7)         # time steps 
d <- data.frame(x,y,z,t)

library(adehabitatLT)
traj <- as.ltraj(d,date=t,id='Jed',infolocs=d)
plot(traj)
```

Next we can create the PPV. We need to carefully select values for vmax and vox. Here given the simplified nature of the movement, we know a vmax of 2.5 is suitable. In practical situations a more careful consideration of vmax is required. If we consider that the spatial range of movement in 3D is approximately 7 x 7 x 3 units a voxel size of 0.2 divides the region into approximately 35 x 35 x 15 = 18k voxels.

```{r}
# ?ppv
ppv1 <- ppv(traj,zcol='z',vmax=2.5,vox=0.2)
head(ppv1)  # look at structure of output
```

The output from the \texttt{ppv} function is a dataframe with four columns {x,y,z} are the coordinates of the voxels, and p is binary indicator of whether or not a voxel is in the PPV. This format is also easy to export for use in other software.

Plotting the PPV requires the use of a 3D plotting system. Here for demonstration we will plot the PPV with the \texttt{scatter3D} function from the *plot3D* package.

```{r}
#install.packages('plot3D')
library(plot3D)

m <- ppv1[which(ppv1$p == 1),]        # get only pixels in the PPV

par(mfcol=c(1,2))
# Plot 1 - horizontal view
scatter3D(m$x,m$y,m$z,colvar=NULL,phi=0,theta=45,ticktype='detailed',bty='g',pch=0,col='grey',alpha=0.1)
scatter3D(x,y,z,colvar=NULL,col='red',pch=20,add=T)

#Plot 2 - Top angled view
scatter3D(m$x,m$y,m$z,colvar=NULL,phi=60,theta=45,ticktype='detailed',bty='g',pch=0,col='grey',alpha=0.1)
scatter3D(x,y,z,colvar=NULL,col='red',pch=20,add=T)
```

The graphics in the paper were generated using the computer visualization software Voxler (https://www.goldensoftware.com/products/voxler), but similar visualizations can be constructed using the free and open source software ParaView (https://www.paraview.org/).