Import dose-response data

Read in and format data from behavioural response studies (BRSs). The function provides options for filtering the data based on species and/or sample sizes. See Details for formatting requirements.

read_data(
  file = NULL,
  risk.functions = c(FALSE, FALSE, FALSE, FALSE),
  n.risk = c(10, 10, 10, 10),
  include.species = NULL,
  exclude.species = NULL,
  min.N = NULL,
  covariates = NULL,
  sonar.groups = list(MFAS = c("MFAS", "MFA", "REAL MFA", "MFAS_DS", "MFA HELO",
    "REAL MFA HELO", "SOCAL_d", "REAL MFAS", "REAL MFA (USS Dewey)"), LFAS = c("LFAS",
    "LFA", "LFAS_DS", "LFAS_LO", "LFAS_122", "LFAS_185", "HPAS-C", "HPAC-C", "HPAS-D",
    "HPASF-C", "MPAS-C", "MPAS-D", "HPAC-C", "XHPAS-D", "XHPAS-C")),
  min.spl = NULL,
  max.spl = NULL,
  dose.range = c(60, 215),
  obs.sd = 2.5,
  verbose = TRUE
)

Arguments

file	Path to the input CSV file. If set to `NULL`, imports the `example_brs` data.
risk.functions	Logical vector of length 4. If `TRUE`, indicates whether to include the risk functions derived in Moretti et al. (2014) , Jacobson et al. (2022) , Houser et al. (2013) a or Houser et al. (2013) b.
n.risk	Vector of length 4. Number of samples to draw for simulating exposures from the dose-response curves selected using `risk.functions`. Defaults to `c(10, 10, 10, 10)`.
include.species	Character vector specifying which species should be retained. These can be selected by any combination of scientific name, common name, or unique identifier, as listed in `species_brs`. All species are included when this argument is set to the default of `NULL`.
exclude.species	Character vector specifying which species should be discarded. These can be selected by any combination of scientific name, common name, or unique identifier, as listed in `species_brs`. No species are excluded when this argument is set to the default of `NULL`.
min.N	Minimum number of observations per species. Species with sample sizes smaller than `min.N` will be removed.
covariates	Contextual covariates. Must be a character string containing one or more of the following: `exposed`, `sonar`, `behaviour` or `range`. No covariates are considered when this argument is set to `NULL`.
sonar.groups	Named list detailing which sonar signals should be grouped a priori.
min.spl	Minimum SPL value to be considered. Data below this value will be discarded.
max.spl	Maximum SPL value to be considered. Data above this value will be discarded.
dose.range	Bounds for the dose-response function. Must be a vector of length 2. Defaults to: (1) a lower bound of 60 dB re 1μPa, taken as a conservative lower limit of detectability given hearing sensitivity and the lowest average sea noise conditions; and (2) an upper bound of 215 dB re 1μPa at/above which all animals are expected to respond. This upper bound is consistent with the maximum source levels employed in behavioural response studies (BRSs) to date.
obs.sd	Measurement uncertainty (expressed as a standard deviation in received levels), in dB re 1μPa.
verbose	Logical. Whether to print or suppress warning messages.

Value

A list object of class brsdata, with the following elements:

`dat`	Output dataset, after processing.
`species`	Species data, including species names, groups, sample sizes etc.
`whales`	Individual data, including animal IDs.
`trials`	Exposure data, including exposure IDs.
`covariates`	Covariate data, including dummy coding, sonar groupings, factor levels etc.
`obs`	Observations, including left- and right-censoring cutoffs.
`param`	General parameters.

Details

The input data file must contain the following fields:

`species`	Species code, as listed in `species_brs`
`tag_id`	Unique tag identifier
`resp_SPL`	Sound pressure level at time of response (in dB re 1μPa)
`max_SPL`	Maximum sound pressure level reached during the exposure
`censored`	Integer variable indicating whether an observation is left-censored (-1), right-censored (1), or not censored (0)

When covariates are specified, the below fields must also be included, as relevant:

`exp_order`	History of exposure (1 = 1st exposure, 2 = 2nd exposure, etc.)
`exp_signal`	Type of sonar signal (e.g., MFAS, REAL MFA, PRN, CAS)
`pre_feeding`	Behavioural mode (TRUE = feeding, FALSE = non-feeding)
`min_range`	Minimum whale-source range during the exposure
`resp_range`	Whale-source range at the time of response
`inferred_resp_range`	Best estimate of whale-source range at the time of response
`inferred_min_range`	Best estimate of minimum whale-source range during the exposure

An example data file is included in the package. See example_brs for details.

Note

Data simulated using risk.functions are assumed to represent measured responses and do not include left or right-censored observations. Note also that include.species and exclude.species override risk.functions, such that simulated data cannot be produced if the associated species is excluded.

References

Houser DS, Martin SW, Finneran JJ (2013). “Behavioral responses of California sea lions to mid-frequency (3250–3450 Hz) sonar signals.” Mar. Environ. Res., 92, 268--278. doi: 10.1016/j.marenvres.2013.10.007 .

Houser DS, Martin SW, Finneran JJ (2013). “Exposure amplitude and repetition affect bottlenose dolphin behavioral responses to simulated mid-frequency sonar signals.” J. Exp. Mar. Biol. Ecol., 443, 123--133. doi: 10.1016/j.jembe.2013.02.043 .

Jacobson EK, Henderson EE, Miller DL, Oedekoven CS, Moretti DJ, Thomas L (2022). “Quantifying the response of Blainville's beaked whales to U.S. naval sonar exercises in Hawaii.” Marine Mammal Science, n/a(n/a). doi: 10.1111/mms.12944 .

Moretti D, Thomas L, Marques T, Harwood J, Dilley A, Neales B, Shaffer J, McCarthy E, New L, Jarvis S, Morrissey R (2014). “A risk function for behavioral disruption of Blainville's beaked whales (Mesoplodon densirostris) from mid-frequency active sonar.” PLoS One, 9(1), e85064. doi: 10.1371/journal.pone.0085064 .

Author

Phil J. Bouchet

Examples

if (FALSE) {
library(espresso)

# Import the example data
mydat <- read_data(file = NULL) 

# Import a real dataset with the sonar and range covariates, 
# whilst excluding sperm whales and any other species with a sample size
# smaller than two observations.
mydat <- read_data(file = "path/to/my/data.csv", 
                  risk.functions = c(FALSE, FALSE, FALSE, FALSE),
                  exclude.species = "Sperm whale",
                  min.N = 2)
}