This function creates a matrix that, for each time step (matrix row) in a sequence of user-defined times, defines whether or not each individual (matrix column) was at liberty. To implement the function, a dataframe with individual IDs and deployment start and end times must be supplied (via ids). The times for which to express whether or not each individual was at liberty are provided by optionally defining a start and end date (these can be taken from the range of deployment times in ids if unspecified) and the interval (delta_t) between time steps.

make_matrix_ids(
  ids,
  start = NULL,
  end = NULL,
  delta_t = "120 mins",
  as_POSIXct = as.POSIXct,
  set_names = TRUE
)

Arguments

ids

A dataframe that defines individual IDs and deployment times. This must contain the following columns: an identifier for individuals (named `individual_id'), the start time of individuals' deployment periods (`tag_start_date') and the end time of individuals' deployment periods (`tag_end_date'). Deployment times can be recorded as Date or POSIXct objects but, if the former is provided, they need to be coerced to POSIXct objects. This can be done automatically (see as_POSIXct).

start, end

Date or POSIXct objects that define the start and end time. If unspecified, these are taken from the range of deployment times in ids.

delta_t

A number or character that defines the time interval between successive time steps. This is passed to the `by' argument of seq.POSIXt.

as_POSIXct

A function that coerces any supplied times (ids$tag_start_date, ids$tag_end_date, start and end) that are not POSIXct objects to POSIXct objects.

set_names

A logical variable that defines whether or not to set the row and column names of the matrix to the time steps and the individual IDs respectively.

Value

The function returns a matrix with one row for each time step and one column for each individual. Each cell defines whether (1) or not (0) each individual was at liberty during that time step.

Author

Edward Lavender

Examples

dat_ids$tag_end_date <- as.Date("2017-06-02")
mat_hours <- make_matrix_ids(dat_ids, delta_t = "hours")
mat_days <- make_matrix_ids(dat_ids, delta_t = "days")
utils::str(mat_hours)
#>  num [1:10849, 1:33] 1 1 1 1 1 1 1 1 1 1 ...
#>  - attr(*, "dimnames")=List of 2
#>   ..$ : chr [1:10849] "2016-03-07 01:00:00" "2016-03-07 02:00:00" "2016-03-07 03:00:00" "2016-03-07 04:00:00" ...
#>   ..$ : chr [1:33] "8" "9" "10" "13" ...
utils::str(mat_days)
#>  num [1:453, 1:33] 1 1 1 1 1 1 1 1 1 1 ...
#>  - attr(*, "dimnames")=List of 2
#>   ..$ : chr [1:453] "2016-03-07 01:00:00" "2016-03-08 01:00:00" "2016-03-09 01:00:00" "2016-03-10 01:00:00" ...
#>   ..$ : chr [1:33] "8" "9" "10" "13" ...