Simulate acoustic arrays (i.e., networks of acoustic receiver(s)) on a grid.
sim_array(
.map,
.timeline,
.arrangement = "random",
.n_receiver = 10L,
...,
.receiver_alpha = 4,
.receiver_beta = -0.01,
.receiver_gamma = 750,
.n_array = 1L,
.plot = TRUE,
.one_page = FALSE
)Arguments
- .map
A
SpatRasterthat defines the region of interest (seeglossary). Here,mapis used to:Sample receiver locations in appropriate (non
NA) regions, viaterra::spatSample();
- .timeline
A
POSIXctvector of regularly spaced time stamps that defines the timeline for the simulation. Here,.timelineis used to:Define receiver deployment periods (that is,
receiver_startandreceiver_endcolumns in the outputdata.table). Receiver deployment periods are defined bymin(.timeline)andmax(.timeline)and constant for all receivers. (These columns are added solely for use in downstream functions.)
- .arrangement, .n_receiver, ...
Arguments passed to
terra::spatSample(), used to sample receiver locations..arrangementis acharacterthat defines the receiver arrangement (passed to themethodargument)..n_receiveris anintegerthat defines the number of receivers to simulate (passed to thesizeargument)....Additional arguments, passed toterra::spatSample(), excludingx,size,method,replace,na.rm,xy,cellsandvalues.
- .receiver_alpha, .receiver_beta, .receiver_gamma
(optional)
Numericconstants for the default detection probability parameters for inclusion in the outputdata.table. (These columns are added solely for use in downstream functions, such assim_observations().)Single inputs are expected to these arguments, which are constant across all receivers.
- .n_array
An
integerthat defines the number of array designs to simulate with the aforementioned parameters.- .plot
A
logicalvariable that defines whether or not to plot simulated arrays.- .one_page
If
.plot = TRUE,.one_pageis alogicalvariable that defines whether or not to produce plots on a single page.
Value
The function returns a data.table with the following columns:
array_id---anintegervector of array IDs,receiver_id---anintegervector of receiver IDs;receiver_start,receiver_end---POSIXctvectors that define receiver deployment periods;receiver_xandreceiver_y---numericvectors that defines receiver coordinates;receiver_alpha,receiver_beta,receiver_gamma---numericvectors of detection probability parameters, if defined;
Details
See also
sim_*functions implement de novo simulation of movements and observations:sim_path_walk()simulates movement path(s) (viaModelMove);sim_array()simulates acoustic array(s);sim_observations()simulates observations (viaModelObs);
Examples
#### Define simulation arguments
map <- dat_gebco()
timeline <- seq(as.POSIXct("2016-01-01", tz = "UTC"),
length.out = 1000L, by = "2 mins")
#### Example (1): The default implementation
array <- sim_array(.map = map, .timeline = timeline)
head(array)
#> array_id receiver_id receiver_start receiver_end receiver_x
#> <int> <int> <POSc> <POSc> <num>
#> 1: 1 1 2016-01-01 2016-01-02 09:18:00 708642.1
#> 2: 1 2 2016-01-01 2016-01-02 09:18:00 706642.1
#> 3: 1 3 2016-01-01 2016-01-02 09:18:00 708942.1
#> 4: 1 4 2016-01-01 2016-01-02 09:18:00 704142.1
#> 5: 1 5 2016-01-01 2016-01-02 09:18:00 707542.1
#> 6: 1 6 2016-01-01 2016-01-02 09:18:00 709042.1
#> receiver_y receiver_alpha receiver_beta receiver_gamma
#> <num> <num> <num> <num>
#> 1: 6268807 4 -0.01 750
#> 2: 6250907 4 -0.01 750
#> 3: 6261607 4 -0.01 750
#> 4: 6265407 4 -0.01 750
#> 5: 6251107 4 -0.01 750
#> 6: 6254207 4 -0.01 750
#### Example (2): Customise receiver placement/number
array <- sim_array(.map = map, .timeline = timeline,
.arrangement = "regular", .n_receiver = 100L)
#### Example (3): Customise detection probability parameters
# (This information is used by the default downstream functions)
array <- sim_array(.map = map, .timeline = timeline,
.receiver_alpha = 4.5,
.receiver_beta = -0.02,
.receiver_gamma = 500)
#### Example (4): Control the plot(s)
sim_array(.map = map, .timeline = timeline,
.plot = FALSE)
#> array_id receiver_id receiver_start receiver_end receiver_x
#> <int> <int> <POSc> <POSc> <num>
#> 1: 1 1 2016-01-01 2016-01-02 09:18:00 705642.1
#> 2: 1 2 2016-01-01 2016-01-02 09:18:00 709342.1
#> 3: 1 3 2016-01-01 2016-01-02 09:18:00 711342.1
#> 4: 1 4 2016-01-01 2016-01-02 09:18:00 701942.1
#> 5: 1 5 2016-01-01 2016-01-02 09:18:00 710142.1
#> 6: 1 6 2016-01-01 2016-01-02 09:18:00 706242.1
#> 7: 1 7 2016-01-01 2016-01-02 09:18:00 697742.1
#> 8: 1 8 2016-01-01 2016-01-02 09:18:00 699842.1
#> 9: 1 9 2016-01-01 2016-01-02 09:18:00 710542.1
#> 10: 1 10 2016-01-01 2016-01-02 09:18:00 709342.1
#> receiver_y receiver_alpha receiver_beta receiver_gamma
#> <num> <num> <num> <num>
#> 1: 6261407 4 -0.01 750
#> 2: 6253607 4 -0.01 750
#> 3: 6252207 4 -0.01 750
#> 4: 6266007 4 -0.01 750
#> 5: 6262407 4 -0.01 750
#> 6: 6254807 4 -0.01 750
#> 7: 6268207 4 -0.01 750
#> 8: 6266607 4 -0.01 750
#> 9: 6269407 4 -0.01 750
#> 10: 6254307 4 -0.01 750
sim_array(.map = map, .timeline = timeline,
.n_array = 5L, .plot = TRUE, .one_page = TRUE)
#> array_id receiver_id receiver_start receiver_end receiver_x
#> <int> <int> <POSc> <POSc> <num>
#> 1: 1 1 2016-01-01 2016-01-02 09:18:00 706242.1
#> 2: 1 2 2016-01-01 2016-01-02 09:18:00 701642.1
#> 3: 1 3 2016-01-01 2016-01-02 09:18:00 710842.1
#> 4: 1 4 2016-01-01 2016-01-02 09:18:00 710542.1
#> 5: 1 5 2016-01-01 2016-01-02 09:18:00 708242.1
#> 6: 1 6 2016-01-01 2016-01-02 09:18:00 703142.1
#> 7: 1 7 2016-01-01 2016-01-02 09:18:00 706942.1
#> 8: 1 8 2016-01-01 2016-01-02 09:18:00 710542.1
#> 9: 1 9 2016-01-01 2016-01-02 09:18:00 702042.1
#> 10: 1 10 2016-01-01 2016-01-02 09:18:00 707342.1
#> 11: 2 1 2016-01-01 2016-01-02 09:18:00 711042.1
#> 12: 2 2 2016-01-01 2016-01-02 09:18:00 701742.1
#> 13: 2 3 2016-01-01 2016-01-02 09:18:00 708542.1
#> 14: 2 4 2016-01-01 2016-01-02 09:18:00 702442.1
#> 15: 2 5 2016-01-01 2016-01-02 09:18:00 703242.1
#> 16: 2 6 2016-01-01 2016-01-02 09:18:00 709642.1
#> 17: 2 7 2016-01-01 2016-01-02 09:18:00 710542.1
#> 18: 2 8 2016-01-01 2016-01-02 09:18:00 709642.1
#> 19: 2 9 2016-01-01 2016-01-02 09:18:00 705142.1
#> 20: 2 10 2016-01-01 2016-01-02 09:18:00 711842.1
#> 21: 3 1 2016-01-01 2016-01-02 09:18:00 709842.1
#> 22: 3 2 2016-01-01 2016-01-02 09:18:00 698342.1
#> 23: 3 3 2016-01-01 2016-01-02 09:18:00 697942.1
#> 24: 3 4 2016-01-01 2016-01-02 09:18:00 699642.1
#> 25: 3 5 2016-01-01 2016-01-02 09:18:00 706042.1
#> 26: 3 6 2016-01-01 2016-01-02 09:18:00 708742.1
#> 27: 3 7 2016-01-01 2016-01-02 09:18:00 712042.1
#> 28: 3 8 2016-01-01 2016-01-02 09:18:00 708642.1
#> 29: 3 9 2016-01-01 2016-01-02 09:18:00 710742.1
#> 30: 3 10 2016-01-01 2016-01-02 09:18:00 706442.1
#> 31: 4 1 2016-01-01 2016-01-02 09:18:00 710042.1
#> 32: 4 2 2016-01-01 2016-01-02 09:18:00 710542.1
#> 33: 4 3 2016-01-01 2016-01-02 09:18:00 702442.1
#> 34: 4 4 2016-01-01 2016-01-02 09:18:00 703642.1
#> 35: 4 5 2016-01-01 2016-01-02 09:18:00 709242.1
#> 36: 4 6 2016-01-01 2016-01-02 09:18:00 703442.1
#> 37: 4 7 2016-01-01 2016-01-02 09:18:00 699542.1
#> 38: 4 8 2016-01-01 2016-01-02 09:18:00 701442.1
#> 39: 4 9 2016-01-01 2016-01-02 09:18:00 704042.1
#> 40: 4 10 2016-01-01 2016-01-02 09:18:00 707142.1
#> 41: 5 1 2016-01-01 2016-01-02 09:18:00 705042.1
#> 42: 5 2 2016-01-01 2016-01-02 09:18:00 707642.1
#> 43: 5 3 2016-01-01 2016-01-02 09:18:00 702842.1
#> 44: 5 4 2016-01-01 2016-01-02 09:18:00 708542.1
#> 45: 5 5 2016-01-01 2016-01-02 09:18:00 704842.1
#> 46: 5 6 2016-01-01 2016-01-02 09:18:00 697742.1
#> 47: 5 7 2016-01-01 2016-01-02 09:18:00 698542.1
#> 48: 5 8 2016-01-01 2016-01-02 09:18:00 709942.1
#> 49: 5 9 2016-01-01 2016-01-02 09:18:00 711342.1
#> 50: 5 10 2016-01-01 2016-01-02 09:18:00 710942.1
#> array_id receiver_id receiver_start receiver_end receiver_x
#> receiver_y receiver_alpha receiver_beta receiver_gamma
#> <num> <num> <num> <num>
#> 1: 6264407 4 -0.01 750
#> 2: 6267607 4 -0.01 750
#> 3: 6270107 4 -0.01 750
#> 4: 6269607 4 -0.01 750
#> 5: 6260107 4 -0.01 750
#> 6: 6249707 4 -0.01 750
#> 7: 6261507 4 -0.01 750
#> 8: 6263207 4 -0.01 750
#> 9: 6264507 4 -0.01 750
#> 10: 6266007 4 -0.01 750
#> 11: 6270207 4 -0.01 750
#> 12: 6266007 4 -0.01 750
#> 13: 6251507 4 -0.01 750
#> 14: 6265707 4 -0.01 750
#> 15: 6264207 4 -0.01 750
#> 16: 6253307 4 -0.01 750
#> 17: 6250407 4 -0.01 750
#> 18: 6249607 4 -0.01 750
#> 19: 6259607 4 -0.01 750
#> 20: 6253507 4 -0.01 750
#> 21: 6269607 4 -0.01 750
#> 22: 6269707 4 -0.01 750
#> 23: 6268907 4 -0.01 750
#> 24: 6265807 4 -0.01 750
#> 25: 6265307 4 -0.01 750
#> 26: 6266207 4 -0.01 750
#> 27: 6250207 4 -0.01 750
#> 28: 6268207 4 -0.01 750
#> 29: 6260607 4 -0.01 750
#> 30: 6250107 4 -0.01 750
#> 31: 6249707 4 -0.01 750
#> 32: 6266107 4 -0.01 750
#> 33: 6256207 4 -0.01 750
#> 34: 6250307 4 -0.01 750
#> 35: 6254507 4 -0.01 750
#> 36: 6265407 4 -0.01 750
#> 37: 6268407 4 -0.01 750
#> 38: 6256407 4 -0.01 750
#> 39: 6252107 4 -0.01 750
#> 40: 6266207 4 -0.01 750
#> 41: 6249807 4 -0.01 750
#> 42: 6249407 4 -0.01 750
#> 43: 6264207 4 -0.01 750
#> 44: 6257207 4 -0.01 750
#> 45: 6262907 4 -0.01 750
#> 46: 6270207 4 -0.01 750
#> 47: 6266307 4 -0.01 750
#> 48: 6257707 4 -0.01 750
#> 49: 6256607 4 -0.01 750
#> 50: 6251807 4 -0.01 750
#> receiver_y receiver_alpha receiver_beta receiver_gamma
sim_array(.map = map, .timeline = timeline,
.n_array = 5L, .plot = TRUE, .one_page = FALSE)
#> array_id receiver_id receiver_start receiver_end receiver_x
#> <int> <int> <POSc> <POSc> <num>
#> 1: 1 1 2016-01-01 2016-01-02 09:18:00 709542.1
#> 2: 1 2 2016-01-01 2016-01-02 09:18:00 709542.1
#> 3: 1 3 2016-01-01 2016-01-02 09:18:00 704442.1
#> 4: 1 4 2016-01-01 2016-01-02 09:18:00 707342.1
#> 5: 1 5 2016-01-01 2016-01-02 09:18:00 702742.1
#> 6: 1 6 2016-01-01 2016-01-02 09:18:00 708542.1
#> 7: 1 7 2016-01-01 2016-01-02 09:18:00 709742.1
#> 8: 1 8 2016-01-01 2016-01-02 09:18:00 711042.1
#> 9: 1 9 2016-01-01 2016-01-02 09:18:00 707842.1
#> 10: 1 10 2016-01-01 2016-01-02 09:18:00 706942.1
#> 11: 2 1 2016-01-01 2016-01-02 09:18:00 709042.1
#> 12: 2 2 2016-01-01 2016-01-02 09:18:00 702542.1
#> 13: 2 3 2016-01-01 2016-01-02 09:18:00 702042.1
#> 14: 2 4 2016-01-01 2016-01-02 09:18:00 709042.1
#> 15: 2 5 2016-01-01 2016-01-02 09:18:00 710842.1
#> 16: 2 6 2016-01-01 2016-01-02 09:18:00 703442.1
#> 17: 2 7 2016-01-01 2016-01-02 09:18:00 711842.1
#> 18: 2 8 2016-01-01 2016-01-02 09:18:00 706142.1
#> 19: 2 9 2016-01-01 2016-01-02 09:18:00 707142.1
#> 20: 2 10 2016-01-01 2016-01-02 09:18:00 707142.1
#> 21: 3 1 2016-01-01 2016-01-02 09:18:00 710642.1
#> 22: 3 2 2016-01-01 2016-01-02 09:18:00 705242.1
#> 23: 3 3 2016-01-01 2016-01-02 09:18:00 703642.1
#> 24: 3 4 2016-01-01 2016-01-02 09:18:00 711342.1
#> 25: 3 5 2016-01-01 2016-01-02 09:18:00 706142.1
#> 26: 3 6 2016-01-01 2016-01-02 09:18:00 707842.1
#> 27: 3 7 2016-01-01 2016-01-02 09:18:00 704442.1
#> 28: 3 8 2016-01-01 2016-01-02 09:18:00 704942.1
#> 29: 3 9 2016-01-01 2016-01-02 09:18:00 703842.1
#> 30: 3 10 2016-01-01 2016-01-02 09:18:00 710442.1
#> 31: 4 1 2016-01-01 2016-01-02 09:18:00 711542.1
#> 32: 4 2 2016-01-01 2016-01-02 09:18:00 705642.1
#> 33: 4 3 2016-01-01 2016-01-02 09:18:00 708842.1
#> 34: 4 4 2016-01-01 2016-01-02 09:18:00 709042.1
#> 35: 4 5 2016-01-01 2016-01-02 09:18:00 710542.1
#> 36: 4 6 2016-01-01 2016-01-02 09:18:00 708442.1
#> 37: 4 7 2016-01-01 2016-01-02 09:18:00 700942.1
#> 38: 4 8 2016-01-01 2016-01-02 09:18:00 705042.1
#> 39: 4 9 2016-01-01 2016-01-02 09:18:00 704942.1
#> 40: 4 10 2016-01-01 2016-01-02 09:18:00 705542.1
#> 41: 5 1 2016-01-01 2016-01-02 09:18:00 702542.1
#> 42: 5 2 2016-01-01 2016-01-02 09:18:00 708042.1
#> 43: 5 3 2016-01-01 2016-01-02 09:18:00 710842.1
#> 44: 5 4 2016-01-01 2016-01-02 09:18:00 708742.1
#> 45: 5 5 2016-01-01 2016-01-02 09:18:00 710242.1
#> 46: 5 6 2016-01-01 2016-01-02 09:18:00 702342.1
#> 47: 5 7 2016-01-01 2016-01-02 09:18:00 703342.1
#> 48: 5 8 2016-01-01 2016-01-02 09:18:00 711342.1
#> 49: 5 9 2016-01-01 2016-01-02 09:18:00 710742.1
#> 50: 5 10 2016-01-01 2016-01-02 09:18:00 704942.1
#> array_id receiver_id receiver_start receiver_end receiver_x
#> receiver_y receiver_alpha receiver_beta receiver_gamma
#> <num> <num> <num> <num>
#> 1: 6260207 4 -0.01 750
#> 2: 6253907 4 -0.01 750
#> 3: 6250107 4 -0.01 750
#> 4: 6252007 4 -0.01 750
#> 5: 6266807 4 -0.01 750
#> 6: 6253507 4 -0.01 750
#> 7: 6264307 4 -0.01 750
#> 8: 6253107 4 -0.01 750
#> 9: 6251507 4 -0.01 750
#> 10: 6264107 4 -0.01 750
#> 11: 6254807 4 -0.01 750
#> 12: 6250107 4 -0.01 750
#> 13: 6254007 4 -0.01 750
#> 14: 6265807 4 -0.01 750
#> 15: 6252507 4 -0.01 750
#> 16: 6265807 4 -0.01 750
#> 17: 6257707 4 -0.01 750
#> 18: 6255107 4 -0.01 750
#> 19: 6266107 4 -0.01 750
#> 20: 6262207 4 -0.01 750
#> 21: 6250807 4 -0.01 750
#> 22: 6251507 4 -0.01 750
#> 23: 6249707 4 -0.01 750
#> 24: 6261507 4 -0.01 750
#> 25: 6250907 4 -0.01 750
#> 26: 6262207 4 -0.01 750
#> 27: 6252307 4 -0.01 750
#> 28: 6258907 4 -0.01 750
#> 29: 6263907 4 -0.01 750
#> 30: 6253507 4 -0.01 750
#> 31: 6258907 4 -0.01 750
#> 32: 6251807 4 -0.01 750
#> 33: 6263607 4 -0.01 750
#> 34: 6256207 4 -0.01 750
#> 35: 6268307 4 -0.01 750
#> 36: 6259807 4 -0.01 750
#> 37: 6266007 4 -0.01 750
#> 38: 6252907 4 -0.01 750
#> 39: 6249807 4 -0.01 750
#> 40: 6250007 4 -0.01 750
#> 41: 6254507 4 -0.01 750
#> 42: 6269007 4 -0.01 750
#> 43: 6250607 4 -0.01 750
#> 44: 6254507 4 -0.01 750
#> 45: 6261607 4 -0.01 750
#> 46: 6255307 4 -0.01 750
#> 47: 6264607 4 -0.01 750
#> 48: 6255307 4 -0.01 750
#> 49: 6256107 4 -0.01 750
#> 50: 6251007 4 -0.01 750
#> receiver_y receiver_alpha receiver_beta receiver_gamma