read_data: Import dose-response data

In pjbouchet/espresso: Bayesian Inference For Multi-Species Behavioural Dose-response Functions

Import dose-response data

Description

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.

Usage

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 \insertCiteMoretti2014;textualespresso, \insertCiteJacobson2022;textualespresso, \insertCiteHouser2013a;textualespressoa or \insertCiteHouser2013b;textualespressob.
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.

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.

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.

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.

Author(s)

Phil J. Bouchet

References

\insertAllCited

See Also

simulate_data example_brs summary.brsdata

Examples

## Not run: 
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)

## End(Not run)

pjbouchet/espresso documentation built on July 27, 2024, 12:31 p.m.