rkori Tutorial

#Overview

The rkori package for R is my incipient collection of R functions for working with the WKP-HRDB data. At the moment, it only consists of three functions in total. All of these functions are high level convenience wrappers for retrieving, plotting, and manipulating data.

The idea behind sharing these functions with the wider world is to lower the barrier to entry for new researchers to work with this data, not software development. Yes, I know my code is fragile and ugly - I personally think that you, reading this right now, can do better, and should. And then you should follow up by forking the rkori repo, building better code than mine, and then merging your branch back in so that anyone can use your stuff.

In any event, the rkori package has a LOT of dependencies - ggplot2, RPostgreSQL, plyr, reshape2 - because these are the packages I use every day in working with this data. On a brighter note, all of the functions are fairly well documented with accompanying help files that can be accessed via ?.

These functions were written in R version 3.2.0 and the rkori package was built using roxygen. They have been tested and appear to work in RStudio build 0.99.447, but RStudio functionality is not guaranteed.

#Installing rkori from github

After installing R 3.2.0 from the CRAN website, start an R session. This is a two-step process: first you need to download and load the devtools package, and then you will download and load the rkori package directly from github.

#install and load devtools
install.packages("devtools")
library(devtools)

#install and load rkori
install_github("FloridaGeologicalSurvey/KORI/rkori")
library(rkori)

#Basic Package Functionality

At present (2015-06-26), I have only had time to write and document three functions for this package. To be fair, these are very convenient functions that trivialize tasks I find myself doing repeatedly. Below is an example R session that should get you up and running with what is there.

#first, load RPostgreSQL (it should have downloaded as a dependency of rkori) and rkori
library(RPostgreSQL)
library(rkori)

#this should always be run in your R session before establishing a connection to the database, 
#forces R to keep timestamps in GMT rather than converting the timestamps to the TZ of your local OS
Sys.setenv(TZ='GMT')

#establish a connection to your database server (substitute your connection parameters)
db <- dbConnect(PostgreSQL(), host="hostname", user="username", password="password", db="wkp_hrdb")

#the first convenience function is getfalmouth() 
?getfalmouth

#this function trivializes queries and reduces the necessary inputs to a
#start and ending timestamp
fal <- getfalmouth(db, "2008-01-01 00:00:00", "2008-06-01 00:00:00")
head(fal)
str(fal)

#also works with the hourly and daily averages
fal.hourly <- getfalmouth(db, "2008-01-01 00:00:00", "2008-06-01 00:00:00", "rfalmouth_hourly")
fal.daily <- getfalmouth(db, "2008-01-01 00:00:00", "2008-06-01 00:00:00", "rfalmouth_daily")

#matplotfalmouth() constructs a ggplot style plot based upon data frame returned by getfalmouth()
?matplotfalmouth

#this function is not very robust and can produce odd outputs depending on what data the database returns
matplotfalmouth(fal)
matplotfalmouth(fal.hourly)
matplotfalmouth(fal.daily)

#by default, scales are free_y
#this parameter can be passed to ggplot2, as can point size
matplotfalmouth(fal, scale_type="fixed", point_size=.5)

#transmutefalmouth() applies a little dcast magic to convert the falmouth data from "long" to "wide" format
?transmutefalmouth

#a variable name - "aspd", "cond" etc - is required
head(fal)
fal.aspd <- transmutefalmouth(fal, "aspd")
fal.aspd[1:50,]

#note the staggered values beginning at row 21
#this happens when one site is recording "on the hour" and another "on the fives"
#using the daily or hourly averages is a quick fix
fal.aspd.hourly <- transmutefalmouth(fal.hourly, "aspd")
fal.aspd.hourly[1:50,]    

#this is useful for running correlations, linear models, and other functions where the data needs to be in wide format by default
#note we slice the dataframe to exclude the first column, as this is a date_time column
cor(fal.aspd[,-1], use="pairwise.complete.obs", method="pearson")

#using the hourly averages gives a substantially better correlation because we have more matching values to correlate
cor(fal.aspd.hourly[,-1], use="pairwise.complete.obs", method="pearson")

#comparison
plot(fal.aspd[["B (Deep)"]], fal.aspd[["C (Deep)"]], pch=20, xlab="B Conduit ASPD", ylab="C Conduit ASPD")
points(fal.aspd.hourly[["B (Deep)"]], fal.aspd.hourly[["C (Deep)"]], pch=".", col="blue", xlab="Conduit B ASPD", ylab="Conduit C ASPD")

#simple linear models
mod = lm(fal.aspd[["C (Deep)"]] ~ fal.aspd[["B (Deep)"]])
mod.hourly = lm(fal.aspd.hourly[["C (Deep)"]] ~ fal.aspd.hourly[["B (Deep)"]])
summary(mod)
summary(mod.hourly)    

#add models to plot
abline(mod, col="red")
abline(mod.hourly, col="blue")

#cbind can be used to bind the outputs of transmutefalmouth together
fal.cond <- transmutefalmouth(fal, "cond")    
names(fal.aspd) <- c("date_time","ad_aspd","ak_aspd","b_aspd","c_aspd","d_aspd","k_aspd","vent_aspd")
names(fal.cond) <- c("date_time","ad_cond","ak_cond","b_cond","c_cond","d_cond","k_cond","vent_cond")

#note the slice
fal.bind <- cbind(fal.aspd, fal.cond[,-1])    
plot(fal.bind, pch=".")

#fin