fetch_vectronics: Download data from Vectronics' web service

In Huh/collar: Utilities for Accessing and Manipulating GPS Data

Download data from Vectronics' web service

Description

A function to download data from the Vectronics' web service. The function relies on a directory containing collar keys key_dir. The function will then attempt to download the relevant data using the keys in the key_dir directory. The user may alter the data downloaded by, for example, downloading data after some arbitrary date, downloading different types of data or after a data id.

Usage

fetch_vectronics(
  key_paths,
  base_url = NULL,
  after_data_id = NULL,
  type = "gps",
  count = FALSE,
  start_date = NULL,
  which_date = NULL,
  rename_fun = adj_col_nms
)

Arguments

key_paths	The full path to one or more key files
base_url	NULL or the url to build from, the default NULL should suffice in almost all cases
after_data_id	All data types have a unique ID maintained by the manufacturer. Use this parameter to download data after the supplied data ID. Must be equal in length to collar_id and collar_key. Only one of start_date and after_data_id may be supplied.
type	The data type, options include "gps", "act", "mit", "mor", "prx", "sep", "trap" and "vit". See details.
count	logical indicating whether you want a count of the data type
start_date	A character vector specifying date and time as DD-MM-YYYYTHH:MM:SS (the T is required, for example 01-01-2018T00:00:00). Supplying this parameter will cause the API to only return data collected after the supplied date. Must be equal in length to collar_id and collar_key. Only one of start_date and after_data_id may be supplied.
which_date	either scts or acquisition, indicates date column to use for subsetting
rename_fun	Column renaming function

Details

This function assumes that the user stores key files for each collar deployed in a single directory and that directory only contains key files. The function will extract all of the keys contained in this directory and attempt to download data for each collar.

If desired, the user may limit the amount of data downloaded by supplying a data id or start date. In both cases only data after the data id or date will be downloaded. One value of data_id is required for each collar. For start_date, the user has the option of supplying a single value or one for each collar.

The type argument allows the user to download different types of information collected by Vectronics collars. The possible options are

• "count" returns count of data records, used with values below

• "gps" returns location data

• "act" returns activity data

• "mit" returns implant mortality data

• "mor" returns mortality data

• "prx" returns proximity data

• "sep" returns separation data

• "trap" returns trap event data

• "vit" returns vaginal implant data

Column names are adjusted using a custom function, but the user can pass any function they want to manipulate column names (e.g. make.names). The default removes non-ASCII characters, coerces all characters to lower case and replaces "." with "_".

Value

Tibble

Examples

## Not run: 
# Use get_paths function to extract full path to each key file in directory
path <- get_paths(
  system.file(
    "extdata",
    package = "collar"
  )
)

# Download count of GPS data
fetch_vectronics(path, type = "gps", count = TRUE)

# Download count of activity data
fetch_vectronics(path, type = "act", count = TRUE)

# Download all data
all_dat <- fetch_vectronics(path, type = "gps")

# Fake multiple key_paths
too_much <- fetch_vectronics(c(path, path), type = "gps")

# Download data after some data id
id_pos <- all_dat$idposition
data_id <- id_pos[which(id_pos == (max(id_pos) - 10))]
new_dat <- fetch_vectronics(path, type = "gps", after_data_id = data_id)

(nrow(new_dat) == 10)

# Download all data after some acquisition date
after <- "2018-06-30T00:00:00"
after_dat <- fetch_vectronics(
  path,
  type = "gps",
  start_date = after,
  which_date = "acquisition"
)

## End(Not run)

Huh/collar documentation built on Aug. 5, 2022, 11:02 p.m.