Chapter 3 About the Functions

There is a sub-folder within this repo named “functions” which is full of, well, scripts that contain functions! You’ll notice they’re often called (via source()) at the top of the example scripts. This loads in the custom functions that I have written to handle CTT data. Ultimately, these will be rolled into an R package.

3.1 Data Manager

3.1.1 load_data

Description
Loads data

Usage

load_data(directory_name=NULL, starttime=NULL, endtime=NULL, tags=NULL)

Arguments

  • directory_name: the input folder can contain a miscellany of raw downloaded files from the sensor station (beep data, node health, GPS) all in the same folder or subfolders. Zipped folders need to be unzipped, but compressed files do not (i.e. csv.gz files are just fine as they are).
  • starttime: start time in POSIXct
  • endtime: end time in POSIXct
  • tags: a vector of tag IDs

Value
The function will return a nested list where each item corresponds to:
1. beep data
2. node health
3. GPS

Within each list item, there is a list for a data frame and the hardware version. Also, a column “v” has been added to each data frame indicating the hardware version.

3.2 Node Health

3.2.1 node_channel_plots

Description
This function is the “engine” behind the export function. You can run it standalone with the following parameters, but you don’t have to if your sole goal is to output image files.

Usage

node_channel_plots(health, freq, ids, lat=NULL, lon=NULL)

Arguments

  • health: the 2nd list item output by the load_data() function
  • freq: the time interval for which you want variables to be summarized
  • ids: a vector of IDs; the ID is of the format “_”
  • lat: latitude (optional to produce day/night shading)
  • lon: longitude (optional to produce day/night shading)

Value
The output is a nested list, where the top level is each combination of channel and node, and each item is a list of the following plots:

  1. battery
  2. RSSI
  3. number of check-ins
  4. scaled number of check-ins as line plot over scaled RSSI
  5. box plot of node RSSI
    THE FOLLOWING ONLY FOR V2
  6. latitude
  7. longitude
  8. scaled RSSI
  9. dispersion

3.2.2 node_plots

Description
A set of diagnostic plots per node

Usage

node_plots(health, nodes, freq, lat = NULL, lon = NULL)

Arguments

  • health: the 2nd data frame output by the load_data() function
  • nodes: list of nodes
  • freq: the time interval for which you want variables to be summarized
  • lat: latitude
  • lon: longitude

Value
The output is a nested list for each node, with the following plots for each:

  1. RSSI
  2. number of check-ins
  3. battery
    THE FOLLOWING ONLY FOR V2
  4. time mismatches
  5. small time mismatches

3.2.3 gps_plots

Description
Plots to visualize some GPS data. ONLY FOR V2 HARDWARE

Usage

gps_plots(gps, freq)

Arguments

  • gps: the 3rd data frame from the load_data() function
  • freq: the time interval of summary

Value
A list of the following plots:

  1. altitude
  2. number of fixes

3.2.4 export_node_channel_plots

Description
Export plots of node x channel data

Usage

export_node_channel_plots(plotlist=NULL,health,freq="1 hour",out_path=getwd(),whichplots = c(3,2,1))

Arguments

  • plotlist: allows you to pass the output of node_channel_plots() if you prefer
  • health: the 2nd data frame output by the load_data() function
  • freq: the time interval for which you want variables to be summarized
  • out_path: where you want your plots to go
  • whichplots: an index vector of of the available plots

Output
This outputs a png for each input combination of node and channel.

3.2.5 export_node_plots

Description
Same as above; index for the plots can be chosen from the list under the node_plots() description
Usage

export_node_plots(plotlist = NULL, health,freq,out_path=getwd(), x=2, y=3, z=1)

Arguments
To assign x, y and z, look at the description for node_channel_plots() and select those plot index in the order you want them on the page.

Output
This outputs a png for each input node