prepData: Preprocessing of the data streams and covariates

Description

Preprocessing of the data streams, including calculation of step length, turning angle, and covariates from location data to be suitable for analysis using fitHMM.

Usage

prepData(data, ...)
# S3 method for default
prepData(
  data,
  type = c("UTM", "LL"),
  coordNames = c("x", "y"),
  covNames = NULL,
  spatialCovs = NULL,
  centers = NULL,
  centroids = NULL,
  angleCovs = NULL,
  altCoordNames = NULL,
  ...
)
# S3 method for hierarchical
prepData(
  data,
  type = c("UTM", "LL"),
  coordNames = c("x", "y"),
  covNames = NULL,
  spatialCovs = NULL,
  centers = NULL,
  centroids = NULL,
  angleCovs = NULL,
  altCoordNames = NULL,
  hierLevels,
  coordLevel,
  ...
)

Value

An object momentuHMMData or momentuHierHMMData, i.e., a dataframe of:

ID: The ID(s) of the observed animal(s)
...: Data streams (e.g., 'step', 'angle', etc.)
x: Either easting or longitude (if coordNames is specified or data is a crwData object)
y: Either norting or latitude (if coordNames is specified or data is a crwData object)
...: Covariates (if any)

Arguments

data: Either a data frame of data streams or a crwData (or crwHierData) object (as returned by crawlWrap). If data is a data frame, it can optionally include a field ID (identifiers for the observed individuals), coordinates from which step length ('step') and turning angle ('angle') are calculated, and any covariates (with names matching covNames and/or angleCovs). If step length and turning angle are to be calculated from coordinates, the coordNames argument must identify the names for the x- (longitunal) and y- (latitudinal) coordinates, and, for hierarchical data, the coordLevel argument must identify the level of the hierarchy at which the location data are obtained. With the exception of ID, coordNames, and, for hierarchical data, level, all variables in data are treated as data streams unless identified as covariates in covNames and/or angleCovs.
...: further arguments passed to or from other methods
type: 'UTM' if easting/northing provided (the default), 'LL' if longitude/latitude. If type='LL' then step lengths are calculated in kilometers and turning angles are based on initial bearings (see turnAngle). Ignored if data is a crwData object.
coordNames: Names of the columns of coordinates in the data data frame. Default: c("x","y"). If coordNames=NULL then step lengths, turning angles, and location covariates (i.e., those specified by spatialCovs, centers, and angleCovs) are not calculated. Ignored if data is a crwData object.
covNames: Character vector indicating the names of any covariates in data dataframe. Any variables in data (other than ID) that are not identified in covNames and/or angleCovs are assumed to be data streams (i.e., missing values will not be accounted for).
spatialCovs: List of raster objects for spatio-temporally referenced covariates. Covariates specified by spatialCovs are extracted from the raster layer(s) based on the location data (and the z values for a raster stack or brick) for each time step. If an element of spatialCovs is a raster stack or brick, then z values must be set using raster::setZ and data must include column(s) of the corresponding z value(s) for each observation (e.g., 'time').
centers: 2-column matrix providing the x-coordinates (column 1) and y-coordinates (column 2) for any activity centers (e.g., potential centers of attraction or repulsion) from which distance and angle covariates will be calculated based on the location data. If no row names are provided, then generic names are generated for the distance and angle covariates (e.g., 'center1.dist', 'center1.angle', 'center2.dist', 'center2.angle'); otherwise the covariate names are derived from the row names of centers as paste0(rep(rownames(centers),each=2),c(".dist",".angle")). As with covariates identified in angleCovs, note that the angle covariates for each activity center are calculated relative to the previous movement direction (instead of standard direction relative to the x-axis); this is to allow the mean turning angle to be modelled as a function of these covariates using circular-circular regression in fitHMM or MIfitHMM.
centroids: List where each element is a data frame containing the x-coordinates ('x'), y-coordinates ('y'), and times (with user-specified name, e.g., `time') for centroids (i.e., dynamic activity centers where the coordinates can change over time) from which distance and angle covariates will be calculated based on the location data. If any centroids are specified, then data must include a column indicating the time of each observation, and this column name must match the corresponding user-specified name of the time column in centroids (e.g. `time'). Times can be numeric or POSIXt. If no list names are provided, then generic names are generated for the distance and angle covariates (e.g., 'centroid1.dist', 'centroid1.angle', 'centroid2.dist', 'centroid2.angle'); otherwise the covariate names are derived from the list names of centroids as paste0(rep(names(centroids),each=2),c(".dist",".angle")). As with covariates identified in angleCovs, note that the angle covariates for each centroid are calculated relative to the previous movement direction (instead of standard direction relative to the x-axis); this is to allow the mean turning angle to be modelled as a function of these covariates using circular-circular regression in fitHMM or MIfitHMM.
angleCovs: Character vector indicating the names of any circular-circular regression angular covariates in data or spatialCovs that need conversion from standard direction (in radians relative to the x-axis) to turning angle (relative to previous movement direction) using circAngles.
altCoordNames: Character string indicating an alternative name for the returned location data. If provided, then prepData will return easting (or longitude) coordinate names as paste0(altCoordNames,".x") and northing (or latitude) as paste0(altCoordNames,".y") instead of x and y, respectively. This can be useful for location data that are intended to be modeled using a bivariate normal distribution (see fitHMM). Ignored unless coordNames are provided.
hierLevels: Character vector indicating the levels of the hierarchy and their order, from top (coarsest scale) to bottom (finest scale), that are included in data$level. For example, for a 2-level hierarchy then hierLevels=c("1","2i","2") indicates data$level for each observation can be one of three factor levels: "1" (coarse scale), "2i" (initial fine scale), and "2" (fine scale). Ignored if data is a crwHierData object.
coordLevel: Character string indicating the level of the hierarchy for the location data. If specified, then data must include a 'level' field indicating the level of the hierarchy for each observation. Ignored if coordNames is NULL or data is a crwHierData object.

Details

If data is a crwData (or crwHierData) object, the momentuHMMData (or momentuHierHMMData) object created by prepData includes step lengths and turning angles calculated from the best predicted locations (i.e., crwData$crwPredict$mu.x and crwData$crwPredict$mu.y). Prior to using prepData, additional data streams or covariates unrelated to location (including z-values associated with spatialCovs raster stacks or bricks) can be merged with the crwData (or crwHierData) object using crawlMerge.
For hierarchical data, data must include a 'level' field indicating the level of the hierarchy for each observation, and, for location data identified by coordNames, the coordLevel argument must indicate the level of the hierarchy at which the location data are obtained.

Examples

Run this code

coord1 <- c(1,2,3,4,5,6,7,8,9,10)
coord2 <- c(1,1,1,2,2,2,1,1,1,2)
cov1 <- rnorm(10)

data <- data.frame(coord1=coord1,coord2=coord2,cov1=cov1)
d <- prepData(data,coordNames=c("coord1","coord2"),covNames="cov1")

# include additional data stream named 'omega'
omega <- rbeta(10,1,1)
data <- data.frame(coord1=coord1,coord2=coord2,omega=omega,cov1=cov1)
d <- prepData(data,coordNames=c("coord1","coord2"),covNames="cov1")

# include 'forest' example raster layer as covariate
data <- data.frame(coord1=coord1*1000,coord2=coord2*1000)
spatialCov <- list(forest=forest)
d <- prepData(data,coordNames=c("coord1","coord2"),spatialCovs=spatialCov)

# include 2 activity centers
data <- data.frame(coord1=coord1,coord2=coord2,cov1=cov1)
d <- prepData(data,coordNames=c("coord1","coord2"),covNames="cov1",
              centers=matrix(c(0,10,0,10),2,2,dimnames=list(c("c1","c2"),NULL)))
              
# include centroid
data <- data.frame(coord1=coord1,coord2=coord2,cov1=cov1,time=1:10)
d <- prepData(data,coordNames=c("coord1","coord2"),covNames="cov1",
              centroid=list(centroid=data.frame(x=coord1+rnorm(10),
                                                y=coord2+rnorm(10),
                                                time=1:10)))
              
# Include angle covariate that needs conversion to 
# turning angle relative to previous movement direction
u <- rnorm(10) # horizontal component
v <- rnorm(10) # vertical component
cov2 <- atan2(v,u)
data <- data.frame(coord1=coord1,coord2=coord2,cov1=cov1,cov2=cov2)
d <- prepData(data,coordNames=c("coord1","coord2"),covNames="cov1",
              angleCovs="cov2")