rNDOW package22 Mar 2016
Over the last few months I’ve been writing tons of R functions. They all go to GitHub, but they aren’t easily used in R. Each time I want to use one I have to use
source('url.to.repo'). I finally decided it was time to write an R package to more easily access these functions, and make them more user friendly for my colleagues.
Writing R packages
The best sources to help write R packages are Hilary Parker’s quick post about writing a personal R package, and Hadley Wickham’s R Packages book. I won’t go into detail about how to write a package as these are two great source. I will say that the easiest way to write a package is to use RStudio and distribute on GitHub.
Push to GitHub
.R files are saved and
.Rd files are generated with
devtools::document() push to a GitHub repo. Now all you have to do in order to install you package is
devtools::install_github('username/repo'). Now your package is installed and usable by you and your colleagues.
rNDOW package is very early in development. I’ve added three functions that I use very frequently for exploratory analysis and visualization of animal movement data (post on that soon!). The package will be used by my colleagues to interface with our data management systems. Due to this, many functions will have hard-coded or default values that make data analysis easier for us. Most of the functions will encapsulate common data munging, exploration, and visualization procedures.
There are 4 functions in the package,
plot3DTraj. I’ve included a randomly sampled animal trajectory for examples
muldDat. The packages can be found at the NDOW-ARG/rNDOW repository. The functions solve a common workflow I have in R, converting latlong coordinates to UTM, adding parameters for animal movement models, and plotting the animal trajectory for exploratory visualization. More information on the input and specifics of the functions can be found at the bottom of the post.
Here is an example of how I use the functions.
Line 1 calls the data from the package. Line 2 converts the coordinates to UTM Zone 11, the default options work for me. Line 3 adds the movement parameters to the dataframe. The timestamp isn’t class
POSIXct so I convert it using the
fasttime library. Line 4 and 5 plot the trajectory. Line 5 creates a “space time cube”, a visualization of the spatial and temporal distribution of the animals GPS locations.
About the functions
Convert geographic coordinates from one coordinate system to another. The input is:
data.framewith the geographic coordinates.
xy- the names of the x and y coordinates.
proj4stringof the input coordinates.
proj4stringfor the coordinates to be converted to.
outclass- the class for the output object. There are three options
data.frame- output as a
data.framewith converted coordinates.
data.table- output as a
data.tablewith the converted coordinates.
spdf- output as a
SpatialPointsDataFramewith the converted coordinates as the
Each output class has its pros and cons. I like working with the
data.table package. Converting to
SpatialPointsDataFrame makes writing shapefiles and plotting easier.
Estimate a number of different movement parameters based on timestamped XY data. These parameters are used in many different models of animal movement. For meaningful estimates it is best to convert to a UTM or other metric projection. The input is:
x- the x coordinate.
y- the y coordinate.
timestamped- the timestamp associated with the XY coordinates.
dat- specify the
data.tableto add the movement parameters to, this is optional.
isPOSIXct- whether or not the timestamp is of class
POSIXct, if not it’ll be converted. For best results the text format should be a character string as “YYYY-MM-DD HH:MM:SS”.
A simple function to plot an animal trajectory. Takes X and Y coordinates as input and uses base graphics to plot the trajectory. The green and red circle indicate the beginning and end of the trajectory.
Another simple function to plot the animal trajectory in 3D. Specify a Z value and value for the color. When plotted the figure will spin, and is interactive.
A randomly sampled animal trajectory. There are 500 rows and 3 fields:
- long_x - longitude coordinate
- lat_y - latitude coordinate
- timestamp - character of the date/time the coordinates were taken (YYYY-MM-DD HH:MM:SS)
The immediate goal is to provide a framework for more complex movement analysis, including the estimation of home ranges and segmenting trajectories based on behavior.
I’ve stopped using
data.table package as it is a new syntax that needs to be learned.