View source: R/make_matrices.R
make_matrix_cooccurence | R Documentation |
The function computes a detection history similarity matrix. For all combinations of individuals, this shows the total number (or percentage) of detections ‘nearby’ in space and time, which can help to elucidate possible interactions among individuals that affect space use (see Details). To compute this matrix, the function pairs detections for each individual with the detections nearest in time for each other individual. The function computes the time (minutes) between paired detection time series, and the distance (m) between the receiver(s) at which paired detections occurred, dropping any detection pairs that are further apart in time or space than user-defined thresholds (which depend on the mobility of the species under investigation). For each combination of individuals, the function returns total number (or percentage) of detections that are closely associated in time and space. For very large combinations of individuals, especially those with long, overlapping time series, the function may take some time to run; therefore, testing the function on a small subset of individuals first is advisable. Parallelisation can be used to improve computation time. Similarity matrices can be visualised with pretty_mat
.
make_matrix_cooccurence(
acoustics_ls,
thresh_time,
thresh_dist,
cl = NULL,
varlist = NULL,
output = 1,
verbose = TRUE
)
acoustics_ls |
A list of dataframes, with one element for each individual, which contains each individual's detection time series. Each dataframe must include the following columns: ‘individual_id’, a factor which specifies unique individuals; ‘timestamp’, a POSIXct object which specifies the time of each detection; ‘receiver_long’, the longitude (decimal degrees) of the receiver(s) at the individual was detected; and ‘receiver_lat’, the latitude (decimal degrees) of the receiver(s) at which individual was detected. Each dataframe should be ordered by ‘individual_id’ and then by ‘timestamp’. Careful ordering of ‘individual_id’ factor levels (e.g. perhaps by population group, then by the number of detections of each individual) can aid visualisation of similarity matrices, in which the order or rows/columns corresponds directly to the order of individuals in |
thresh_time |
A number which specifies the time, in minutes, after which detections at nearby receivers are excluded. |
thresh_dist |
A number which specifies the (Euclidean) distance between receivers, in metres, beyond which detections are excluded (see Details). |
cl , varlist |
(optional) |
output |
A number which specifies the output type. If |
verbose |
A logical input which specifies whether or not to print messages to the console which relay function progress. |
Passive acoustic telemetry is widely used to study animal space use, and the possible drivers of spatiotemporal patterns in space use, in aquatic environments. Patterns in space use are widely related to environmental conditions, such as temperature, but the role of interactions among individuals is often more challenging to investigate due to a paucity of data, despite their likely importance. However, discrete detections also contain information on interactions among individuals that may influence space use through their similarities and differences among individuals over time and space.
Similarities and differences can take different forms with differing ecological implications. For example, for individuals that are frequently detected in similar areas, detections may indicate (a) prolonged associations among individuals, if detections are usually closely associated in time and space (for example, due to parent-offspring relationships, group-living and/or mating); or (b) avoidance and/or territorial-like behaviour if detections, while close in space, are usually at different receivers and/or disjointed in time. Likewise, detection similarities among individuals that are rarely detected, or usually detected at disparate receivers, may reflect important interactions among those individuals at particular times (e.g. mating).
To explore similarities and differences in patterns of space use, visualisation of detection histories with abacus plots and maps is beneficial. However, with many individuals and large receiver arrays, quantification of the similarities in detections over time and space is challenging. To this end, make_matrix_cooccurence
computes a similarity matrix across all individuals, defining the number (or percentage) of detections for each individual that are nearby in time, or space, to detections for each other individual.
The distances beyond which detections of different individuals nearby in time are considered to demonstrate that those individuals are not closely associated are Euclidean. This may be problematic (e.g. when receivers hug complex coastlines).
The function returns a matrix or a list, depending on the input to output
(see above).
Edward Lavender
#### Prepare data
# acoustics_ls requires a dataframe with certain columns
# individual_id should be a factor
dat_acoustics$individual_id <- factor(dat_acoustics$individual_id)
# ensure dataframe ordered by individual, then time stamp
dat_acoustics <- dat_acoustics[order(dat_acoustics$individual_id, dat_acoustics$timestamp), ]
# define list of dataframes
acoustics_ls <- split(dat_acoustics, factor(dat_acoustics$individual_id))
#### Example (1): Compute detection similarity matrix using default options
# mat_sim contains the number of observations shared among individuals
mat_sim <- make_matrix_cooccurence(
acoustics_ls = acoustics_ls,
thresh_time = 90,
thresh_dist = 0
)
prettyGraphics::pretty_mat(mat_sim, col_diag = "dimgrey")
#### Example (2): Return list of outputs
out_ls <- make_matrix_cooccurence(
acoustics_ls = acoustics_ls,
thresh_time = 90,
thresh_dist = 0,
output = 2
)
names(out_ls)
# Examine number of observations for each individual
prettyGraphics::pretty_mat(out_ls$mat_nobs)
# Examine % shared detections between individuals
prettyGraphics::pretty_mat(out_ls$mat_pc, col_diag = "dimgrey")
#### Example (3): Turn off messages with verbose = FALSE
out_ls_non_verb <- make_matrix_cooccurence(
acoustics_ls = acoustics_ls,
thresh_time = 90,
thresh_dist = 0,
verbose = FALSE
)
#### Example (4): Implement algorithm in parallel
out_ls_pl <- make_matrix_cooccurence(
acoustics_ls = acoustics_ls,
thresh_time = 90,
thresh_dist = 0,
cl = parallel::makeCluster(2L),
output = 2
)
names(out_ls_pl)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.