contactDur.all: Identify Inter-animal Contacts
In contact: Creating Contact and Social Networks

Description Usage Arguments Value Examples

This function uses the output from dist2All to determine when and for how long tracked individuals are in "contact" with one another. Individuals are said to be in a "contact" event if they are observed within a given distance (<= dist.threshold) at a given timestep. Contacts are broken when individuals are observed outside the specified distance threshold from one another for > sec.threshold seconds. Sec.threshold dictates the maximum amount of time between concurrent observations during which potential "contact" events remain unbroken. For example, if sec.threshold == 10, only "contacts" occurring within 10secs of one another will be regarded as a single "contact" event of duration sum(h). If in this case, a time difference between contacts was 11 seconds, the function will report two separate contact events.

The output of this function is a data frame containing a time-ordered contact edge set detailing inter-animal contacts.

contactDur.all(
  x,
  dist.threshold = 1,
  sec.threshold = 10,
  blocking = FALSE,
  blockLength = 1,
  blockUnit = "hours",
  blockingStartTime = NULL,
  equidistant.time = FALSE,
  parallel = FALSE,
  nCores = (parallel::detectCores()/2),
  reportParameters = TRUE
)

`x`	Output from the dist2All function. Can be either a data frame or non-data-frame list.
`dist.threshold`	Numeric. Radial distance (in meters) within which "contact" can be said to occur. Defaults to 1. Note: If you are defining conttacts as occurring when polygons intersect, set dist.threshold to 0.
`sec.threshold`	Numeric. Dictates the maximum amount of time between concurrent observations during which potential "contact" events remain unbroken. Defaults to 10.
`blocking`	Logical. If TRUE, contacts will be evaluated for temporal blocks spanning blockLength blockUnit (e.g., 6 hours) within the data set. Defaults to FALSE.
`blockLength`	Integer. Describes the number blockUnits within each temporal block. Defaults to 1.
`blockUnit`	Character string taking the values, "secs," "mins," "hours," "days," or "weeks." Describes the temporal unit associated with each block. Defaults to "hours."
`blockingStartTime`	Character string or date object describing the date OR dateTime starting point of the first time block. For example, if blockingStartTime = "2016-05-01" OR "2016-05-01 00:00:00", the first timeblock would begin at "2016-05-01 00:00:00." If NULL, the blockingStartTime defaults to the minimum dateTime point in x. Note: any blockingStartTime MUST precede or be equivalent to the minimum timepoint in x. Additional note: If blockingStartTime is a character string, it must be in the format ymd OR ymd hms.
`equidistant.time`	Logical. If TRUE, location fixes in individuals' movement paths are temporally equidistant (e.g., all fix intervals are 30 seconds). Defaults to FALSE. Note: This is a time-saving argument. A sub-function here calculates the time difference (dt) between each location fix. If all fix intervals in an individuals' path are identical, it saves a lot of time.
`parallel`	Logical. If TRUE, sub-functions within the contactDur.all 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)).
`reportParameters`	Logical. If TRUE, function argument values will be appended to output data frame(s). Defaults to TRUE.

Returns a data frame (or list of data frames if x is a list of data frames) with the following columns:

`dyadMember1`	The unique ID of an individual observed in contact with a specified second individual.
`dyadMember2`	The unique ID of an individual observed in contact with `dyadMember1`.
`dyadID`	The unique dyad ID used to identify the pair of individuals `dyadMember1` and `dyadMember2`.
`contactDuration`	The number of sequential timepoints in `x` that `dyadMember1` and `dyadMember2` were observed to be in contact with one another.
`contactStartTime`	The timepoint in `x` at which contact between `dyadMember1` and `dyadMember2` begins.
`contactEndTime`	The timepoint in `x` at which contact between `dyadMember1` and `dyadMember2` ends.

If blocking == TRUE, the following columns are appended to the output data frame described above:

`block`	Integer ID describing unique blocks of time during which contacts occur.
`block.start`	The timepoint in `x` at which the `block` begins.
`block.end`	The timepoint in `x` at which the `block` ends.
`numBlocks`	Integer describing the total number of time blocks observed within `x` at which the `block`

Finally, if reportParameters == TRUE function arguments distThreshold, secThreshold, equidistant.time, and blockLength (if applicable) will be appended to the output data frame.

data(calves)

calves.dateTime<-datetime.append(calves, date = calves$date, time =
    calves$time) #create a dataframe with dateTime identifiers for location foxes
    
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 locations to 5-min fix intervals.

calves.dist<-dist2All_df(x = calves.agg, parallel = FALSE, dataType = "Point",
    lonlat = FALSE) #calculate distance between all individuals at each timepoint
    
calves.contact.block<-contactDur.all(x = calves.dist, dist.threshold=1,
    sec.threshold=10, blocking = TRUE, blockUnit = "hours", blockLength = 1,
    equidistant.time = FALSE, parallel = FALSE, reportParameters = TRUE)
    
calves.contact.NOblock<-contactDur.all(x = calves.dist, dist.threshold=1,
    sec.threshold=10, blocking = FALSE, blockUnit = "hours", blockLength = 1,
    equidistant.time = FALSE, parallel = FALSE, reportParameters = TRUE)