potentialDurations: Identify Potential Contact Durations
In contact: Creating Contact and Social Networks

Description Usage Arguments Value Examples

This function uses the output from dist2... functions to determine the potential maximum number of direct-contact durations between individuals in a data set. The max number of durations potentially observed is the number of TSWs both individuals (or an individual and fixed area) were simulataneously observed at the same time over the study period/temporal block.

Please note that this function assumes the desired minimum contact duration (MCD), as defined by Dawson et al. (2019), is 1 (i.e., a "contact" occurs when individuals are within a specified distance threshold for a single timestep). In a future version of this function we will aim to increase flexability by allowing for variable MCD values. For further clarification on the MCD definition and various contact-determination assumptions, please see:

Dawson, D.E., Farthing, T.S., Sanderson, M.W., and Lanzas, C. 2019. Transmission on empirical dynamic contact networks is influenced by data processing decisions. Epidemics 26:32-42. https://doi.org/10.1016/j.epidem.2018.08.003/

potentialDurations(
  x,
  blocking = FALSE,
  blockLength = 1,
  blockUnit = "hours",
  blockingStartTime = NULL,
  distFunction = "dist2All_df"
)

`x`	Output from the dist2All or dist2Area function. Can be either a data frame or non-data-frame list.
`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.
`distFunction`	Character string taking the values: "dist2All_df", or "dist2Area_df." Describes the contact-package function used to generate x.

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

`id`	The unique ID of an individual observed in the data set.
`potenDegree`	The maximum degree possible for individual `id` based on the number of other individuals observed during the time period.
`potenTotalContactDurations`	The maximum number of contact durations individual `id` may experience during the time period.
`potenContactDurations_...`	The maximum number of contact durations individual `id` may experience with each specific individual/fixed area during the time period.

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 may occur.
`block.start`	The timepoint in `x` at which the `block` begins.
`block.end`	The timepoint in `x` at which the `block` ends.

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.potentialContacts<-potentialDurations(x = calves.dist, blocking = FALSE)