This function creates a matrix that, for each time step (matrix row) in a sequence of user-defined times, defines whether or not each receiver (matrix column) was active. To implement the function, a dataframe with receiver IDs and deployment start and end times must be supplied (via moorings). Servicing dates can also be accounted for via a dataframe with receiver IDs and servicing times (services). The times for which to express whether or not each receiver was active are provided by optionally defining a start and end date (these can be taken from the range of deployment times in moorings if unspecified) and the interval (delta_t) between time steps.
make_matrix_receivers(
moorings,
services = NULL,
start = NULL,
end = NULL,
delta_t = "120 mins",
as_POSIXct = as.POSIXct,
set_names = TRUE
)A dataframe that defines receiver IDs and deployment times. This must contain the following columns: an identifier for receivers (named `receiver_id'), the start time of receiver' deployment periods (`receiver_start_date') and the end time of receivers' deployment periods (`receiver_end_date') (see dat_moorings for an example). Deployment times can be recorded as Date or POSIXct objects.
(optional) A dataframe that defines receiver IDs and servicing dates (times during the deployment period of a receiver when it was not active due to servicing). If provided, this must contain the following columns: an identifier for serviced receivers (named `receiver_id') and two columns that define the time of the service(s) (`service_start_date' and `service_end_date'). Times can be recorded as Date or POSIXct objects. Before/after service events, receivers are assumed to have been deployed in the same locations; receiver deployments in different locations before/after servicing should be treated as distinct deployments in moorings.
Date or POSIXct objects that define the start and end time. If unspecified, these are taken from the range of deployment times in moorings.
A number or character that defines the time interval between successive time steps. This is passed to the `by' argument of seq.POSIXt or seq.Date (depending on as_POSIXct, below).
(optional) A function that coerces supplied any supplied times (moorings$receiver_start_date, moorings$receiver_end_date, services$service_start_date, services$service_end_date, start and end) that are not POSIXct objects to POSIXct objects. This can be suppressed via as_POSIXct = NULL if supplied times are Date objects and delta_t is not less than one day.
A logical variable that defines whether or not to set the row and column names of the matrix to the time steps and the receiver IDs respectively.
The function returns a matrix with one row for each time step and one column for each receiver. Each cell defines whether (1) or not (0) each receiver was at active during that time step. A `bins' attribute is included, which defines the time steps as a Date or POSIXct vector.
#### Example (1): Illustration using fake data
## Define some example 'moorings' data
# ... with receiver IDs and deployment times
moorings <- data.frame(
receiver_id = c(1, 2, 3, 4, 5),
receiver_start_date = as.Date(c(
"2016-01-01",
"2016-01-02",
"2016-01-03",
"2016-01-04",
"2016-01-05"
)),
receiver_end_date = as.Date(c(
"2016-01-06",
"2016-01-07",
"2016-01-08",
"2016-01-09",
"2016-01-09"
))
)
## Define some example 'servicing' data
# ... with receiver IDs and servicing times
# ... Here, receiver 1 was serviced twice
# ... ... from 2016-01-02--3 and 2016-01-04--5
# ... and receiver 5 was serviced
# ... ... on 2016-01-08.
services <- data.frame(
receiver_id = c(1, 1, 5),
service_start_date = as.Date(c(
"2016-01-02",
"2016-01-04",
"2016-01-08"
)),
service_end_date = as.Date(c(
"2016-01-03",
"2016-01-05",
"2016-01-08"
))
)
## Get daily receiver status (0, 1) matrix
make_matrix_receivers(moorings, delta_t = "days", as_POSIXct = NULL)
#> 1 2 3 4 5
#> 2016-01-01 1 0 0 0 0
#> 2016-01-02 1 1 0 0 0
#> 2016-01-03 1 1 1 0 0
#> 2016-01-04 1 1 1 1 0
#> 2016-01-05 1 1 1 1 1
#> 2016-01-06 1 1 1 1 1
#> 2016-01-07 0 1 1 1 1
#> 2016-01-08 0 0 1 1 1
#> 2016-01-09 0 0 0 1 1
#> attr(,"bins")
#> [1] "2016-01-01" "2016-01-02" "2016-01-03" "2016-01-04" "2016-01-05"
#> [6] "2016-01-06" "2016-01-07" "2016-01-08" "2016-01-09"
## Get daily receiver status (0, 1) matrix
# ... accounting for servicing dates
make_matrix_receivers(moorings, services, delta_t = "days", as_POSIXct = NULL)
#> 1 2 3 4 5
#> 2016-01-01 1 0 0 0 0
#> 2016-01-02 0 1 0 0 0
#> 2016-01-03 0 1 1 0 0
#> 2016-01-04 0 1 1 1 0
#> 2016-01-05 0 1 1 1 1
#> 2016-01-06 1 1 1 1 1
#> 2016-01-07 0 1 1 1 1
#> 2016-01-08 0 0 1 1 0
#> 2016-01-09 0 0 0 1 1
#> attr(,"bins")
#> [1] "2016-01-01" "2016-01-02" "2016-01-03" "2016-01-04" "2016-01-05"
#> [6] "2016-01-06" "2016-01-07" "2016-01-08" "2016-01-09"
#### Example (2): Illustration using actual data
# ... for different time windows
mat_days <- make_matrix_receivers(dat_moorings, delta_t = "days", as_POSIXct = NULL)
mat_hours <- make_matrix_receivers(dat_moorings, delta_t = "hours")
utils::str(mat_days)
#> num [1:508, 1:40] 1 1 1 1 1 1 1 1 1 1 ...
#> - attr(*, "bins")= Date[1:508], format: "2016-03-03" "2016-03-04" ...
#> - attr(*, "dimnames")=List of 2
#> ..$ : chr [1:508] "2016-03-03" "2016-03-04" "2016-03-05" "2016-03-06" ...
#> ..$ : chr [1:40] "3" "4" "7" "9" ...
utils::str(mat_hours)
#> num [1:12169, 1:40] 1 1 1 1 1 1 1 1 1 1 ...
#> - attr(*, "bins")= POSIXct[1:12169], format: "2016-03-03 01:00:00" "2016-03-03 02:00:00" ...
#> - attr(*, "dimnames")=List of 2
#> ..$ : chr [1:12169] "2016-03-03 01:00:00" "2016-03-03 02:00:00" "2016-03-03 03:00:00" "2016-03-03 04:00:00" ...
#> ..$ : chr [1:40] "3" "4" "7" "9" ...