mps: Identify and Remove Data Points Based on Observed Movement...

Description Usage Arguments Details Value Examples

View source: R/mps.R

Description

mps (a.k.a. Meters-per-Second Filter) identifies and removes timepoints when tracked individuals were observed moving faster than a set distance threshold (representing either the great-circle distance between two points a planar distance metric, depending on whether or not lonlat == TRUE or FALSE, respectively) per second. (i.e., if it is impossible/highly unlikely that individuals moved faster than a given speed (mps), we can assume that any instances when they were observed doing so were the result of erroneous reporting, and should be removed). When running the mps filter, users have the option of setting lonlat == TRUE (by default lonlat == FALSE). lonlat is a logical argument that tells the function to calculate the distance between points on the WGS ellipsoid (if lonlat == TRUE), or on a plane (lonlat == FALSE) (see raster::pointDistance). If lonlat == TRUE, coordinates should be in degrees. Otherwise, coordinates should represent planar ('Euclidean') space (e.g. units of meters).

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
mps(
  x,
  id = NULL,
  point.x = NULL,
  point.y = NULL,
  dateTime = NULL,
  mpsThreshold = 10,
  lonlat = FALSE,
  parallel = FALSE,
  nCores = (parallel::detectCores()/2),
  filterOutput = TRUE
)

Arguments

x

List or data frame containing real-time location data that will be filtered.

id

Vector of length nrow(data.frame(x)) or singular character data, detailing the relevant colname in x, that denotes what unique ids for tracked individuals will be used. If argument == NULL, the function assumes a column with the colname "id" exists in x. Defaults to NULL.

point.x

Vector of length nrow(data.frame(x)) or singular character data, detailing the relevant colname in x, that denotes what planar-x or longitude coordinate information will be used. If argument == NULL, the function assumes a column with the colname "x" exists in x. Defaults to NULL.

point.y

Vector of length nrow(data.frame(x)) or singular character data, detailing the relevant colname in x, that denotes what planar-y or lattitude coordinate information will be used. If argument == NULL, the function assumes a column with the colname "y" exists in x. Defaults to NULL.

dateTime

Vector of length nrow(data.frame(x)) or singular character data, detailing the relevant colname in x, that denotes what dateTime information will be used. If argument == NULL, the function assumes a column with the colname "dateTime" exists in x. Defaults to NULL.

mpsThreshold

Numerical. Distance (in meters) representing the maximum distance individuals can realistically travel over a single second.

lonlat

Logical. If TRUE, point.x and point.y contain geographic coordinates (i.e., longitude and lattitude). If FALSE, point.x and point.y contain planar coordinates. Defaults to FALSE.

parallel

Logical. If TRUE, sub-functions within the mps wrapper will be parallelized. Defaults to FALSE.

nCores

Integer. Describes the number of cores to be dedicated to parallel processes. Defaults to half of the maximum number of cores available (i.e., (parallel::detectCores()/2)).

filterOutput

Logical. If TRUE, output will be a data frame or list of data frames (depending on whether or not x is a data frame or not) containing only points that adhere to the mpsThreshold rule. If FALSE, no observartions are removed and an "mps" column is appended to x,which reports the avg distance per second individuals moved to get from observation i-1 to observation i. Defaults to TRUE.

Details

If users are not actually interested in filtering datasets, but rather determining what observations should be filtered, they may set filterOutput == FALSE. By doing so, this function will append up an "mps" column to the dataset, which reports the avg distance per second individuals moved to get from observation i-1 to observation i.

Value

If filterOutput == TRUE, returns x less observations representing impossible/unlikely movements.

If filterOutput == FALSE, returns x appended with an "mps" column which reports the avg distance per second individuals moved to get from observation i-1 to observation i.

Examples

1
2
3
4
5
6
7
8
9
data(calves) #load calves data

calves.dateTime<-datetime.append(calves, date = calves$date,
   time = calves$time) #create a dataframe with dateTime identifiers for location fixes.

calves_filter1 <- mps(x = calves.dateTime, id = calves.dateTime$calftag,
   point.x = calves.dateTime$x, point.y = calves.dateTime$y, 
   dateTime = calves.dateTime$dateTime, mpsThreshold = 10, lonlat = FALSE, parallel = FALSE, 
   filterOutput = TRUE) 

contact documentation built on May 17, 2021, 5:07 p.m.