referencePoint2Polygon: Create a Rectangular Polygon Using Planar XY Coordinates
In contact: Creating Contact and Social Networks

Description Usage Arguments Details Value References Examples

This function creates a square/rectangular polygon from a single reference point by translating its location multiple times using the same method used in repositionReferencePoint. For example, even though calves in our study (see data(calves2018)) were only equiped with RFID tags on their left ear. With this function, we can create polygons that account for the total space used by each individual at each time step.This function is different from similar point-to-polygon functions for two reasons: 1.) It does not assume points lie within the center of the polygon. Rather, the reference point must be a corner of the polygon (Note: "UL" denotes that the reference point lies on the upper-left corner of the polygon, "UR" denotes that reference point lies on the upper-right corner of the polygon,"DL" denotes that reference point lies on the down-left corner of the polygon, "DR" denotes that reference point lies on the down-left corner of the polygon). Note that if you want the reference point to be at the center of the polygon, you can first translate the reference point to a central location on tracked individuals using repositionReferencePoint. 2.) Polygon angles/directionality are based on observed movements of tracked individuals or gyroscope data.

referencePoint2Polygon(
  x = NULL,
  id = NULL,
  dateTime = NULL,
  point.x = NULL,
  point.y = NULL,
  direction = NULL,
  StartLocation = "UL",
  UpDownRepositionLen = 1,
  LeftRightRepositionLen = 1,
  CenterPoint = FALSE,
  MidPoints = FALSE,
  immobThreshold = 0,
  parallel = FALSE,
  nCores = (parallel::detectCores()/2),
  modelOrientation = 90
)

`x`	Data frame or list of data frames containing real-time-location point data.
`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.
`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.
`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.
`direction`	Numerical vector of length nrow(data.frame(x)) or singular character data detailing the relevant colname in x, that denotes what movement-direction information will be used. Observations in this vector represent the direction (in degrees) that tracked individuals moved to reach their position at each time point, NOT the direction that they will move to reach their subsequent position (i.e., values represent known orientations at each time point). Note that for the purposes of this function, observations of 0, 90, 180, and 270 degrees indicates that an individual moved straight Eastward, Northward, Westward, and Southward, respectively. If NULL, direction will be calculated using observed point-locations. Defaults to NULL.
`StartLocation`	Character string taking the values "UL," "UR," "DL," or "DR" describing where the reference point (i.e., point corresponding to xy-coordinates in the data set) lies on the rectangle that this function will delineate. Defaults to "UL."
`UpDownRepositionLen`	Numerical. Describes the height, in planar units (e.g., meters) of the output polygon. Planar units are inherent to the real-time-location input. Defaults to 1.
`LeftRightRepositionLen`	Numerical. Describes the width, in planar units (e.g., meters) of the output polygon. Planar units are inherent to the real-time-location input. Defaults to 1.
`CenterPoint`	Logical. If TRUE, in addition to the xy-coordinates for each polygon vertex, xy-coordinates for centroid of each polygon will be reported in the output. Defaults to FALSE.
`MidPoints`	Logical. If TRUE, in addition to the xy-coordinates for each polygon vertex, xy-coordinates for mid-point of each polygon edge will be reported in the output. Defaults to FALSE.
`immobThreshold`	Numerical. Describes what we call, the immobility threshold, which is a movement distance (in planar units) within which we assume individuals’ physical locations and orientations remain unchanged. This immobility threshold allows us to discount observed movements so miniscule that the majority of animals’ physical-space usage is likely unaffected (e.g., head shaking). Defaults to 0.
`parallel`	Logical. If TRUE, sub-functions within the referencePoint2Polygon 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)).
`modelOrientation`	Numerical. Describes the relative orientation (in degrees) of a planar model (see vignette or Farthing et al. in Press (note: when this manuscript is officially published, we will update this citation/reference information)) describing vertex locations relative to tracking-device point-locations. Defaults to 90.

Currently, this function only supports input data with coordinates representing planar ('Euclidean') space (e.g. units of meters).

In the output, point1.x and point1.y represent the xy coordinates from the input file. Point2-n coordinates move in a clockwise direction from point1. For example: if point1 is located on the upper left ("UL") corner of the polygon, point2 would be on the upper right corner, point3 on the bottom right, and point 4 on the bottom left.

If distance == NULL, then function will require information (dist, dx, dy) from 2 points on an individual's path to work properly. Because of this, when no gyroscopic data are provided, at least the first point in each individual's path will be removed (the function will report NAs for adjusted locations). Also note that if the distance between an individual's first point in their path and the second one is 0, the function will also report NAs for the second point's adjusted coordinates. The first non-NA values will only be reported for the instance where dist > 0.

Note that populating the direction argument with gyroscopic accelerometer data (or data collected using similar devices) collected concurrently with point-locations allows us to overcome a couple of assumptions associated with using point-locations alone.

First, unless the direction argument is specifically given (i.e., direction != NULL), vertex locations in output are subject to the assumption that dt values are sufficiently small to capture individuals' orientations (i.e., individuals do not face unknown directions inbetween observed relocations). If input was previously processed using tempAggregate with resolutionLevel == "reduced," dt > secondAgg indicates that tracked individuals were missing in the original dataset for a period of time. In this case, the assumption that individuals are facing a given direction because they moved from the previous timepoint may not be accurate. Consider removing these rows (rows following one with dt > secondAgg; remember that dt indicates the time between reported xy coordinates in row i to row i + 1) from your data set.

Second, unless the direction argument is specifically given (i.e., direction != NULL), this function assumes tracked individuals are always forward-facing. This is because by observing only a single point on each individual, we cannot ascertain the true positioning of individuals' bodies. For example, even if we know a point-location moved x distance in a 90-degree direction, from this information alone we cannot determine what direction said individual was facing at the time (e.g., this could be an example of forward, bawckward, or sideward movement). However, gyroscopic data (or data collected using similar devices) can tell us absolute movement directions, as opposed to relative ones.

Output is a data frame with the following columns:

`id`	Unique ID of tracked individuals.
`cornerPoint...x`	Planar x coordinates of polygon-corner vertices.
`cornerPoint...y`	Planar y coordinates of polygon-corner vertices.
`startLocation`	Describes the location of input point-locations in the vertex outputs. see `StartLocation` argument.
`upDownRepositionLength`	Describes the vertical movement of point-locations on planar models. see `UpDownRepositionLen` argument.
`leftRightRepositionLength`	Describes the horizontal movement of point-locations on planar models. see `leftRightRepositionLen` argument.
`immob`	If "0", distance between observed movements is < `immobThreshold`.
`immobThreshold`	Returns the value from the `immobThreshold` argument.
`dateTime`	Timepoint at which polygons were observed.
`dt`	The time between reported xy coordinates in row i to row i + 1 in each individuals' movement path.

If MidPoints or CenterPoints == TRUE, additional columns will be appended to output data frame.

Farthing, T.S., Dawson, D.E., Sanderson, M.W., and Lanzas, C. 2020. Accounting for space and uncertainty in real-time-location- system-derived contact networks. Ecology and Evolution 10(11):4702-4715.

data("calves")
calves.dateTime<-datetime.append(calves, date = calves$date,
   time = calves$time) #add dateTime identifiers for location fixes.

calves.agg<-tempAggregate(calves.dateTime, id = calves.dateTime$calftag, 
   dateTime = calves.dateTime$dateTime, point.x = calves.dateTime$x, 
   point.y = calves.dateTime$y, secondAgg = 300, extrapolate.left = FALSE, 
   extrapolate.right = FALSE, resolutionLevel = "reduced", parallel = FALSE, 
   na.rm = TRUE, smooth.type = 1) #smooth to 5-min fix intervals.

calf_heads <- referencePoint2Polygon(x = calves.agg,
   id = calves.agg$id, dateTime = calves.agg$dateTime,
   point.x = calves.agg$x, point.y = calves.agg$y, direction = NULL,
   StartLocation = "DL", UpDownRepositionLen = 0.333, LeftRightRepositionLen = 0.333,
   CenterPoint = FALSE, MidPoints = FALSE, immobThreshold = 0.1, parallel = FALSE,
   modelOrientation = 90)