Package 'LTabundR'

Description

This function is typically not called by the user (though it certainly can be); instead, it is called as a subroutine within lta(). This function estimates density/abundance for Wincruz data, as processed by LTabundR::process_surveys().

Usage

abundance(
  segments,
  sightings,
  das,
  strata,
  truncation_distance,
  use_g0 = TRUE,
  g0 = c(1, 1),
  g0_threshold = 20,
  region_pool = FALSE,
  region_pool_name = "Regions pooled",
  region_pool_area = NA,
  year_pool = FALSE,
  forced_effort = NULL,
  verbose = TRUE
)

Arguments

Value

A data.frame with a row for each density/abundance estimate. You may expect multiple rows if multiple regions or years are contained within the datasets provided. This data.frame contains the following fields:

1. Region: Name(s) of geostrata represented in this estimate.

2. Area: Area of geostratum / region, in square km.

3. year: Years represented in this estimate.

4. segments: The number of effort segments used to estimate density/abundance.

5. km: The km of trackline effort contained in these segments.

6. Area_covered: The Area surveyed, according to km and ESW_mean (see next column).

7. ESW_mean: Mean effective strip width, in kw, calculated as the truncation distance multiplied by the mean probability of detection for all detections.

8. n: The number of detections in the data.

9. g0_mean: The mean g(0) estimate.

10. ER_clusters: The encounter rate for detections (schools) (n / km)

11. D_clusters: The density of detections (schools).

12. N_clusters: The abundance of schools.

13. size_mean: Average school size.

14. size_sd: Standard deviation of school size.

15. ER: Animal encounter rate.

16. D: Animal density.

17. N: Animal abundance.

Description

Relative trackline detection probabilities from Barlow (2015).

Usage

barlow_2015

Format

An object of class data.frame with 168 rows and 9 columns.

Details

This dataset holds the results from Barlow (2015), "Inferring trackline detection probabilities, g(0), for cetaceans from apparent densities in different survey conditions" (Marine Mammal Science), which used NOAA/NMFS cruise data from 1986 to 2010.

Description

Replicated from the coxed package, which has been archived on CRAN. Moving code here so that LTabundR can still use this function.

Usage

bca(theta, conf.level = 0.95)

Arguments

Value

A two-element vector with the lower and upper confidence interval calculated using the BCA method.

Description

Cruise data processed for the CNP, 1986 - 2020 (150 km segment lengths)

Usage

cnp_150km_1986_2020

Format

An object of class list of length 3.

Details

This dataset was processed with the following code:

data(group_size_coefficients)

survey <- load_survey_settings(
out_handling = 'remove',
max_row_interval = Inf,
segment_method = "equallength",
segment_target_km = 150,
segment_max_interval = 24,
segment_remainder_handling = c("segment"),
ship_list = NULL, # use package list
species_codes = NULL, # use package codes
group_size_coefficients = group_size_coefficients, # use package coefficients
smear_angles = FALSE)

data(strata_cnp)
strata <- strata_cnp

all_species <- load_cohort_settings(
id = "all",
species = NULL, #spp_codes,
strata = c('MHI', 'WHICEAS', 'HI_EEZ', 'OtherCNP'),
probable_species = FALSE,
sighting_method = 0,
cue_range = 0:7,
school_size_range = c(0, 10000),
school_size_calibrate = TRUE,
calibration_floor = 0,
use_low_if_na = TRUE,
io_sightings = 0,
geometric_mean_group = TRUE,
truncation_km = 7.5,
beaufort_range = 0:6,
abeam_sightings = FALSE,
strata_overlap_handling = c("smallest"),
distance_types = c('S','F','N'),
distance_modes = c('P','C'),
distance_on_off = TRUE
)

bottlenose <- load_cohort_settings(
id = "bottlenose",
species = '018',
strata = c('MHI', 'WHICEAS', 'HI_EEZ', 'OtherCNP', 'Bottlenose_BI', 'Bottlenose_OUFI', 'Bottlenose_KaNi'),
probable_species = FALSE,
sighting_method = 0,
cue_range = 0:7,
school_size_range = c(0, 10000),
school_size_calibrate = TRUE,
calibration_floor = 0,
use_low_if_na = TRUE,
io_sightings = 0,
geometric_mean_group = TRUE,
truncation_km = 7.5,
beaufort_range = 0:6,
abeam_sightings = FALSE,
strata_overlap_handling = c("smallest"),
distance_types = c('S','F','N'),
distance_modes = c('P','C'),
distance_on_off = TRUE
)

spotted <- load_cohort_settings(
id = "spotted",
species = '002',
strata = c('MHI', 'WHICEAS', 'HI_EEZ', 'OtherCNP','Spotted_OU','Spotted_FI','Spotted_BI'),
probable_species = FALSE,
sighting_method = 0,
cue_range = 0:7,
school_size_range = c(0, 10000),
school_size_calibrate = TRUE,
calibration_floor = 0,
use_low_if_na = TRUE,
io_sightings = 0,
geometric_mean_group = TRUE,
truncation_km = 7.5,
beaufort_range = 0:6,
abeam_sightings = FALSE,
strata_overlap_handling = c("smallest"),
distance_types = c('S','F','N'),
distance_modes = c('P','C'),
distance_on_off = TRUE
)

fkw <- load_cohort_settings(
id = "pseudorca",
species = '033',
strata = c('MHI', 'WHICEAS', 'HI_EEZ', 'OtherCNP','NHWI'),
probable_species = FALSE,
sighting_method = 0,
cue_range = 0:7,
school_size_range = c(0, 10000),
school_size_calibrate = TRUE,
calibration_floor = 0,
use_low_if_na = TRUE,
io_sightings = 0,
geometric_mean_group = TRUE,
truncation_km = 7.5,
beaufort_range = 0:6,
abeam_sightings = FALSE,
strata_overlap_handling = c("smallest"),
distance_types = c('S','F','N'),
distance_modes = c('P','C'),
distance_on_off = TRUE
)

settings <- load_settings(strata = strata,
                          survey = survey,
                          cohorts = list(all_species,
                                         bottlenose,
                                         spotted,
                                         fkw))

das_file = '../test_code/CNP/CenPac1986-2020_Final_alb.das'

cnp_150km_1986_2020 <- process_surveys(das_file = das_file,
                     settings = settings)

Description

Example of coded edits to cruz object.

Usage

cnp_1986_2020_edits

Format

An object of class list of length 4.

Details

This is an example of the kind of object that can be passed to the edits input in process_surveys().

Description

Coastline

Usage

coastline

Format

An object of class sf (inherits from data.frame) with 4133 rows and 4 columns.

Details

World coastline, downloadeded from Natural Earth.

Description

This is an internal function typically not called by a user directly.

Usage

coordinates_in_strata(lon, lat, poli)

Arguments

Value

A logical vector, the same length as the lon, indicating whether or not the coordinate falls within the polygon. If the coordinate falls exactly on the polygon boundary, it will be counted as in.

Description

This function combines processed cruz objects (the outputs of LTabundR::process_surveys()), under the assumption that the survey settings in both objects are the exact same. If the same cohort name occurs in multiple cruz objects, the contents of the instances of the cohort are checked for redundancy (using Cruise number - date combinations), and only non-redundant content is combined. If different cohorts occur in the supplied cruz objects, the cohorts are added without modification.

Usage

cruz_combine(cruzes)

Arguments

Value

A single cruz object.

Description

Launch a data explorer app for WinCruz surveys

Usage

cruz_explorer(cruz, cohort = 1)

Arguments

Value

A Shiny app for interactive data exploration. This app allows you to filter the cruz object according to various fields, then explore summary tables of effort, sightings, and detection distances. There are also tabs for reviewing the data in tabular form and exploring an interactive leaflet map of survey tracks, geostrata, and sightings.

Description

This function prints an overview of the list structure and sample sizes within your cruz object, which is produced from LTabundR::process_surveys().

Usage

cruz_structure(cruz)

Arguments

Value

Nothing; messages are printed to the Console.

Description

...without modifying the original data. Edits are provided as a list, which the user can store as a RData object or simply prepare with an R script. This function loops through each edit and applies them to the respective DAS file. This allows survey data to be modified reproducibly before being processed with LTabundR::process_surveys(), without touching the original DAS data files or requiring analysts to duplicate files and make one-off modifications manually.

Usage

das_editor(edits)

Arguments

Value

A list with two named slots:

• das: A data.frame containing the modified DAS data (with one column: ⁠$das⁠).

• log: The edits input, with each sublist augmented with a results slot that shows the results of the edit.

Description

This function is basically a wrapper for the function das_editor(), but this function saves the edited DAS data to new files. It takes a set of DAS files and a set of editing instructions (provided as a list – see das_editor() documentation), applies the edits to each DAS file, and saves new versions of the DAS file. It does NOT replace the original DAS file.

Usage

das_editor_tofile(das_file, edits, suffix = "_edited", verbose = TRUE)

Arguments

Value

At the end of the process, the function returns a vector of DAS filenames that should be passed to processing functions such as process_surveys() or das_load().

Description

This function removes invalid rows of data (due to missing Cruise numbers, timestamps, location coordinates, etc.), calculates the distance, in kilometers, between each row of data, adds a ship column with the ship name associated with the cruise number, and initiates the cruz object structure, with a new cohorts slot.

This is an internal function typically not called by a user directly. It is the third subroutine called within process_surveys(); after process_strata() and before segmentize().

Usage

das_format(cruz, verbose = FALSE)

Arguments

Value

A list with nascent cruz object structure, with these slots:

1. settings holds your settings object;

2. strata holds a dataframe summarizing the name and area (square km) of each geo-stratum, if any are provided;

3. cohorts holds a list with slots for each cohort of species as specified in settings. Each cohort slot has a copy of the DAS data with a new stratum column, with a stratum assignment tailored to its cohort-specific settings (specifically, the setting stratum_overlap_handling). This list structure will be expanded upon in subsequent steps of process_surveys().

Description

Use a Shiny app to explore a DAS file and build up a list of edits. Those edits will be saved as a list of instructions, which can subsequently be provided as an argument to LTabundR::process_surveys(), which will apply your list of edits before processing the data. This framework allows you to record details of required edits reproducibly without ever modifying the original dataset or producing modified versions of the original.

Usage

das_inspector(das_file)

Arguments

Value

A Shiny app is launched, where the user explores and builds up a list of staged edits. Once the user closes that app, this function returns that list of edits. We recommend saving that return in an object for easy call back later. To understand the structure of the list of edits, see LTabundR::das_editor().

Description

This function is not typically called by the user directly; it is called during process_surveys(). The user can instruct LTabundR to interpolate DAS data in load_survey_settings().

Usage

das_interpolate(das, new_interval = 120, max_ignore = 3600, verbose = FALSE)

Arguments

Details

This function allows you to interpolate the DAS position data at the onset of processing if your position updates are separated by large time intervals, which would make spatial effort and stratum assignments less exact. LTabundR will interpolate the data using simple-linear methods (i.e., no great-circle calculations), such that position updates occur every new_interval seconds or less. If adjacent DAS rows are from different dates or cruises, or if the interval between rows exceeds the input max_ignore, the interpolation routine will skip to the next pair of related rows. Interpolation will only occur for On-Effort rows.

Value

An interpolated data.frame of the DAS data. No formatting has been changed.

Description

This is an internal function typically not called by a user directly. It is the first subroutine called within process_surveys(). This function is essentially a wrapper for swfscDAS::das_read(), which reads in a raw DAS file (or a URL to an DAS file in an online repository), and swfscDAS::das_process(), which formats each row into columns, with survey status, sighting conditions, and observer positions added to each row as new columns.

Usage

das_load(das_file, perform_checks = FALSE, print_glimpse = FALSE)

Arguments

Value

A data.frame of the DAS file, with fields parsed into columns and with new columns for survey status, sighting conditions, and observer positions.

Description

In contrast to swfscDAS::das_read(), this function reads the DAS text in, saving each line of data to a single row of a one-column data.frame (no column parsing). This is useful if you wish to edit and save an altered version of the data using LTabundR::das_inspector() and LTabundR::das_editor(). This function relies upon the readtext package.

Usage

das_readtext(das_file)

Arguments

Value

A one-column data.frame (column name is das).

Description

This function is typically called within LTabundR::das_inspector() as a way of staging an edit that adjusts the timestamps of certain rows. Not typically called directly by a user.

Usage

das_time(das, tz_adjust = "from utc")

Arguments

Value

A two-slot list: ⁠[[1]] dt⁠ returns the revised date-time characters. ⁠[[2]] das⁠ returns the revised row in full (if a full row was originally provided).

Description

This is an internal function, typically not called by the user. It returns a single detection function curve based on one or more detection function models. If multiple models are provided, their curves will be averaged together to provide a single curve, weighting the average based upon the model AIC.

Usage

df_curve(models, covariates = NULL, truncation_distance)

Arguments

Details

This function is adapted from code in mrds::plot.ds() and mrds::detfct().

Value

A data.frame of length 101, with two columns: km is distance from the trackline, and p is the average detection probability at that distance, based on the data's covariates.

Description

This function is not typically called by the user (though it can be); instead it is called as a subroutine from within the function lta(). This function is a wrapper for the detection function fitting routine in the package mrds (function mrds::ddf()). As a wrapper, this function conducts automated stepwise model-fitting, trying all candidate function keys and covariates, then selecting the best model(s) based upon AICc.

Usage

df_fit(
  sightings,
  truncation_distance = Inf,
  covariates = NULL,
  detection_function_base = "hn",
  base_model = "~1",
  delta_aic = 2,
  toplot = TRUE,
  verbose = TRUE
)

Arguments

Details

Model fitting is done in a forward stepwise procedure, starting fresh with each base key provided. In the first round, the base model (no covariates) is fit first. In the second round, each covariate is added one at a time; the covariate, if any, that produces the lowest AICc below the AIC from the previous round is added to the formula. This process is repeated in subsequent rounds until the AICc no longer improves. All models within delta_aic of the model with the lowest AICc qualify as best-fitting models.

Value

A named list:

1. best_models: A data.frame summary of the best-fitting models, based upon the table produced by Distance::summarize_ds_models(). See that function's documentation for details.

2. all_models: Similar to the preceding slot, a tabular summary of all models tested.

3. best_objects: A list containing the ds objects (produced by package Distance) for each of the best-fitting models.

4. sample_size: A data.frame with the detections for each species within the species pool used to fit the detection function. Ntot is total detections for each species; Ndet is total detections within the truncation distance and therefore used in the detection function fitting routine; TD is the truncation distance.

5. tables: A list of the data tables passed to Distance::ds() during model fitting.

6. sightings: The sightings data.frame provided, now with an esw columns provided estimated Effective Strip half-Width for each sighting.

Description

This function adapts mrds::plot.ds() to plot the detection functions fit and provided by the output of lta() and lta_multistock(). Arguments allow for stylizing the plot as well as displaying multiple best-fitting models on the same histogram.

Usage

df_plot(
  lta_result,
  model_colors = "black",
  model_pch = 1,
  hist_bars = 15,
  hist_col = "grey90",
  hist_border = "grey60",
  pt_show = 1,
  pt_cex = 0.8,
  pt_alpha = 0.3,
  line_col = "darkblue",
  line_lty = 1,
  line_lwd = 2.5,
  line_alpha = 0.7,
  bootstrap_show = TRUE,
  bootstrap_col = "steelblue4",
  bootstrap_alpha = 0.2,
  bootstrap_lwd = 0.5,
  main_show = TRUE,
  main = NULL,
  main_cex = 1.25,
  legend_show = FALSE,
  ymax = NULL,
  legend_x = 3.2,
  legend_y = 1.2,
  legend_cex = 0.8,
  xlab = "Distance (km) from trackline"
)

Arguments

Value

A plot is printed.

Description

EEZ (all US EEZ boundaries)

Usage

eez

Format

An object of class sf (inherits from data.frame) with 260 rows and 17 columns.

Details

World dataset of geopolitical Exclusive Economic Zones (EEZ), downloaded from Natural Earth.

Description

EEZ - California Current System (formatted for sf / tmap mapping)

Usage

eez_ccs

Format

An object of class sfc_MULTILINESTRING (inherits from sfc) of length 17.

Details

The EEZ relevant to the California Current System only, formatted for sf-compatibility.

Description

EEZ - Hawaii (formatted for sf / tmap mapping)

Usage

eez_hawaii

Format

An object of class sfc_MULTILINESTRING (inherits from sfc) of length 25.

Details

The EEZ relevant to the Hawai'ian area only, formatted for sf-compatibility.

Description

Test for the probability that year-to-year changes observed in a species' encounter rate are due to random sampling variation instead of an actual change in the encounter rate. This function uses bootstrap sampling of survey segments to see if random variation in sampling could possibly produce an apparent but immaterial change in encounter rate across years.

Usage

er_simulator(
  spp,
  cohort = 1,
  cruz,
  iterations = 1000,
  seed = NULL,
  verbose = FALSE
)

Arguments

Details

See the Appendix to Bradford et al. (2020) for analytical details, but briefly: in each bootstrap iteration, survey segments are resampled in a way that preserves the proportion of effort occurring within each geostratum in the data. The resampled data are used to calculate the overall encounter rate across all years, since the null hypothesis is that the encounter rate does not change across years. This overall encounter rate is used to predict the number of sightings in each year, based on the distance covered by the resampled segments in each year. This process is repeated (iterations times) to produce a distribution of predicted sighting counts in each year. This distribution is compared to the actual number of sightings observed in each year. The number of simulated sightings counts that exceed the observed count reflects the probability that the observed count is due to random sample variation alone.

Value

A dataframe with a row for each year. Columns provide the number of observations of the species of interest during systematic effort, and the p-value of the test. The p-value represents the fraction of simulated encounter rates that exceed the observed encounter rate.

Description

Example cruz object (WHICEAS 2020)

Usage

example_cruz

Format

An object of class list of length 3.

Details

This example cruz object was prepared with the following code:

data(example_settings)
example_cruz <- process_surveys('data-raw/data/HICEASwinter2020.das',
                          settings = example_settings)

Description

Example settings used in LTabundR vignette (WHICEAS 2020)

Usage

example_settings

Format

An object of class list of length 3.

Details

This example settings object was prepared with the following code:

data(strata_cnp)
data(study_cnp)
data(group_size_coefficients)
survey <- load_survey_settings()
cohort1 <- load_cohort_settings(strata = c('OtherCNP', 'HI_EEZ', 'WHICEAS'))
example_settings <- load_settings(strata = strata_cnp,
                               study_area = study_cnp,
                               survey = survey,
                               cohorts=list(cohort1))

Description

This is an internal function, usually not called directly by analysts, but it certainly can be. Rather than calling a cruz object, as filter_cruz does, this function just calls for the three relevant constituent tables: segments, sightings, and the full das dataset.

Usage

filter_cohort(
  segments,
  sightings,
  das,
  analysis_only = FALSE,
  spp = NULL,
  years = NULL,
  not_years = NULL,
  cruises = NULL,
  not_cruises = NULL,
  regions = NULL,
  not_regions = NULL,
  bft_range = NULL,
  eff_types = NULL,
  on_off = NULL,
  lat_range = NULL,
  lon_range = NULL,
  verbose = TRUE
)

Arguments

Details

This function works by using the filter arguments to determine which rows of DAS data meet all criteria; since that DAS dataframe is drawn from a processed cruz object, it has a seg_id column indicating the segment IDs pertaining to eligible rows of data. Those segment IDs are then used to filter segments and sightings.

Note that when arguments are NULL, they are ignored and no filtering by the associated variable occurs.

Value

A list with two objects: segments and sightings. These are filtered versions of the same objects contained within the cruz object. See process_surveys() documentation for details.

Description

Subsets a cruz object according to a variety of filters. The same filters apply to all cohorts within the cruz object.

Usage

filter_cruz(
  cruz,
  analysis_only = FALSE,
  spp = NULL,
  years = NULL,
  not_years = NULL,
  cruises = NULL,
  not_cruises = NULL,
  regions = NULL,
  not_regions = NULL,
  bft_range = NULL,
  eff_types = NULL,
  on_off = NULL,
  lat_range = NULL,
  lon_range = NULL,
  verbose = TRUE
)

Arguments

Details

This function works by using the filter arguments to determine which rows of DAS data meet all criteria; since that DAS dataframe comes from within the processed cruz object, it has a seg_id column indicating the segment IDs pertaining to eligible rows of data. Those segment IDs are then used to filter segments, sightings, and subgroups.

Note that the analysis_only filter is ignored for subgroups sightings/subgroups/events, since those are often case-by-case-specific.

Note that when arguments are NULL, they are ignored and no filtering by the associated variable occurs. Also note that subgroups are not filtered at this time.

Note that there is a similar function, filter_cohort(), that performs a similar task for only a single cohort, without requiring an in-tact cruz object. Instead it asks for the requisite datasets separately.

Value

A modified cruz object. See process_surveys() documentation for details.

Description

This function is typically not called by the user, but it certainly can be. It is called as a subroutine within LTabundR::lta().

Usage

g0_combine(g0s, g0cvs)

Arguments

Value

A list with two slots: ⁠$g0⁠ holds the combined g(0) estimate, and ⁠$CV⁠ holds the combined CV.

Description

This function is an implementation of Barlow (2015), "Inferring trackline detection probabilities, g(0), for cetaceans from apparent densities in different survey conditions" (Marine Mammal Science), for processed Wincruz survey data. This function predicts the relative g(0) (compared to Beaufort sea state 0) for all Beaufort sea states 0 - 6.

Usage

g0_model(
  spp,
  truncation_distance = 5.5,
  cruz,
  cohort = 1,
  eff_types = "S",
  jackknife_fraction = 0.1,
  seed = NULL,
  constrain_shape = FALSE,
  k = 4,
  toplot = TRUE,
  verbose = TRUE
)

Arguments

Details

After Barlow (2015), this function implements the following procedure:

1. Filter sightings to the specified species code(s), and associate those sightings with their respective 10-km segment ID.

2. Determine the presence or absence of the species of interest for each segment.

3. Estimate the Effective Search Area (ESA) for each Beaufort sea state represented in the data. This is done by fitting a detection function to the sightings data (half-normal key; using function Distance::ds()), using Beaufort as the only covariate. With this detection function model, the probability of detection (p(det)) for sightings in each Beaufort state is determined (Distance::predict.ds()$fitted). The effective strip width (ESW) for each Beaufort state is determined by multiplying p(det) by the supplied truncation_distance. The ESW is used to calculate the ESA in each segment (ESA = 2 x L x ESW). Note that Beaufort states 0 and 1 are combined (after Barlow 2015), since they are typically under-represented in open-ocean fieldwork.

4. A binomial Generalized Additive Model (GAM) ("logit" link function) is fit to the segments (using mgcv::gam), based upon Equation 3 from Barlow (2015), which includes Beaufort sea state, Latitude x Longitude, and Year as predictors (using the mgcv::s() spline function) and the log of ESA as an offset (stats::offset()) to predict the probability of apparent presence in each segment. To prevent over-fitting, the spline functions for Beaufort and Year are constrained with k=4, and model complexity penalty is inflated (gamma = 1.4 in mgcv::gam()).

5. The GAM model is used to predict the probability of apparent species presence (mgcv::predict.gam()) in fake segements of equal length, year, and Latitude/Longitude but with different Beaufort sea states, 0 - 6.

6. By comparing the probability for Beaufort 0 (in which rates of apparent presence would be highest) to that for other Beaufort states, the Relative g(0) (Rg(0))is estimated (Equation 4 in Barlow 2015).

7. The Coefficient of Variation (CV) for Rg(0) is then estimated using a jackknife procedure, in which a fraction of the data are sequentially removed (input jackknife_fraction, with default 10%), Rg(0) is re-estimated by implementing steps 4 - 6 above, and this process is repeated for all sequential fractions of the data. The CV is derived from these pseudo-estimates (let's call them jacks) with the equation ⁠n*CV(jacks) - (n-1)*CV(jacks))⁠, in which n is the number of jackknife estimates (1 / jackknife_fraction) and CV is the standard deviation of jacks divided by their mean.

Value

A list:

• Rg0 a data.frame of estimates of Relative g(0) at each Beaufort.

• gam the mgcv::gam() model output.

• jackknife A list of jackknife results: ⁠$g0⁠ contains the g(0) estimates from each jacknife iteration; ⁠$ESW⁠ contains the effective half-strip-width estimates; ⁠$gams⁠ contains the gam model objects.

• summary: A dataframe summarizing results; this is the primary output you are likely to use..

• cruz10: A modified nascent cruz object that has been re-segmentized to have segments of 10km-length. This usually takes a while to create, so this output gives you the option of passing this object on to your next call of g0_bft_model() (see cruz10 argument above) to save time.

Description

This is an internal function used in LTabundR::lta() for finding the values (through optim()) for the parameters needed to conduct parametric bootstrapping of g0 values for each non-parametric bootstrap of the LTA routine.

Usage

g0_optimize(g0, g0_cv, try_count = 20, seed = NULL, verbose = TRUE)

Arguments

Value

A list with three named slots: ⁠[[1]] g0_mean⁠, the exact mean, according to the optimization results; ⁠[[2]] g0_cv⁠, the CV according to optimization; and ⁠[[3]] bestFit⁠, a numeric vector of length 2 containing parameters to pass to the parameteric g(0) bootstrap routine in LTabundR::lta(). If the initial g(0) estimate is 1.0, or the initial g(0) CV estimate is 0.0, then these parameters will be returned as NA.

Description

This function produces a multi-pane plot of changes in relative trackline detection probabilities, Rg(0), across Beaufort sea states for a set of species.

Usage

g0_plot(Rg0, panes = 3, legend_key = 0.4, legend_font = 7)

Arguments

Value

A ggplot object with faceted panes arranged vertically.

Description

Relative trackline detection probabilities – Rg(0)

Usage

g0_results

Format

An object of class data.frame with 175 rows and 13 columns.

Details

Rg(0) estimates for 25 species groups, based on survey data from 1986-2020 (see noaa_10km_1986_2020 dataset).

Description

This function estimates relative trackline probabilities, Rg(0), for a set of species and returns a single table (a data.frame) with the results for each species. This function is a wrapper for LTabundR::g0_model(). See its documentation for details on the procedure.

Usage

g0_table(
  cruz,
  species,
  eff_types = "S",
  jackknife_fraction = NULL,
  seed = NULL,
  toplot = TRUE,
  verbose = TRUE
)

Arguments

Value

A data.frame, in which every row details the Rg0 estimate for a single species group in a single Beaufort sea state, with the following columns:

1. title: The title given to the species group.

2. spp: Species codes, concatenated by a hyphen if there are multiple in the species group.

3. bft: Beaufort sea state.

4. Rg0: Estimate of the relative g(0) for this sea state.

5. ESW: Estimate of the effective strip half-width (ESW) for this sea state.

6. Rg0_SE: The standard error of the Rg(0) estimate, non-zero only if jackknife_fraction was used.

7. Rg0_CV: The CV of the Rg(0) estimate, non-zero only if jackknife_fraction was used.

8. ESW_SE: The standard error of the ESW estimate, non-zero only if jackknife_fraction was used.

9. sits: The number of sightings within this sea state used to model Rg(0).

10. sits_p: The proportion of sightings within this sea state.

11. segs: The number of segments within this sea state used to model Rg(0).

12. segs_p: The proportion of segments within this sea state.

See the built-in dataset, data(g0_results), for an example of the output.

Description

Use this function to summarize the Beaufort-specific model of relative trackline probabilities (from LTabundR::g0_bft_model()) as a single relative g(0) estimate, weighted by the prevalence of each Beaufort sea state within the survey data. This function automatically estimates the CV of this weighted value using an iterative loop with an MCMC core, adapted from Jeff Moore's code.

Usage

g0_weighted(
  Rg0,
  Rg0_cv,
  cruz,
  cohort = 1,
  iterations = 10000,
  seed = NULL,
  beta_range = c(-1.5, 0),
  beta_step = 0.001,
  beta_sd_range = c(0, 0.3),
  beta_sd_step = 1e-04,
  ymax = 0.2,
  calculate_pars = TRUE,
  toplot = TRUE,
  verbose = TRUE
)

Arguments

Details

This code is an adaptation and expansion of Jeff Moore's code (February 2020). This function automatically estimates the CV of this weighted value using an iterative loop with an MCMC core. The MCMC routine is described in Bradford et al. (2021). The iterative loop tries various candidate values for the distribution parameters and calculates the cumulative error of the resulting distribution at each Beaufort state. It then determines the candidate value with the lowest error, weighting each error according to the proportion of effort occurring in the respective Beaufort state.

Value

The output is provided in the form of a list with two slots: g0 and bft. The g0 slot holds a data.frame in which ⁠$wt.mean⁠ is the weighted mean g(0) value across all Beaufort states for the survey data provided, and ⁠$wt.cv⁠ is the CV of that estimate. Other values are reported to facilitate QA/QC, but ⁠$wt.mean⁠ and ⁠$wt.cv⁠ is what you would pass to an abundance estimation routine, such as LTabundR::lta()). The bft slot holds a dataframe with the proportion of effort in each Beaufort sea state.

Description

Add cruz effort to a base ggplot2 map.

Usage

gg_effort(
  p,
  cruz,
  cohort = 1,
  color_by_bft = FALSE,
  color = "black",
  lwd = 0.1,
  alpha = 0.5
)

Arguments

Value

An updated ggplot2 object.

Description

Add cruz geostrata to a base ggplot2 map.

Usage

gg_geostratum(
  p,
  cruz,
  strata,
  color = "orchid4",
  lwd = 0.5,
  lty = 1,
  crs = 4326
)

Arguments

Value

An updated ggplot2 object.

Description

Add cruz sightings to a base ggplot2 map.

Usage

gg_sightings(
  p,
  cruz,
  cohort = 1,
  spp = NULL,
  spp_translate = NULL,
  color_by_spp = FALSE,
  color = "black",
  pch = 16,
  cex = 0.5,
  alpha = 0.5
)

Arguments

Value

An updated ggplot2 object.

Description

Modify a ggplot object to handle the International Date Line (IDL)

Usage

ggplot_idl(
  p_base,
  lon_range = c(100, -100),
  lat_range = NULL,
  idl_padding = 0.02,
  axes = TRUE,
  bypass = FALSE
)

Arguments

Value

A ggplot2 object that is actually two plots side by side, with a small space in between indicating the IDL.

Description

This is an internal function typically not called by a user directly. This function is used as a subroutine in process_sightings(). It produces school size estimates for each species within a sighting, based upon all estimates of school size and species composition provided by observers.

Usage

group_size(
  grp,
  gs_coefficients = NULL,
  calibrate_floor = 0,
  geometric_mean = FALSE,
  use_low_if_na = TRUE,
  debug_mode = FALSE,
  verbose = TRUE
)

Arguments

Value

A dataframe in which each row is a species within the sighting, with final estimates of best / high / low and metadata regarding calibration. When this function is used internally by LTabundR, the results are passed back to process_sightings().

Description

This is an internal function typically not called by a user directly. It is called by the subroutine group_size(), which is itself a subroutine of process_sightings().

This function performs school size calibration for a single observer's estimates.

Usage

group_size_calibration(
  obs,
  bft,
  yr,
  gbest,
  glow,
  ghigh,
  gs_coefficients = NULL,
  calibrate_floor = 0
)

Arguments

Value

A one-row dataframe with the best school size estimate, the variance of the estimate, a boolean indicating whether calibration was possible, and the slope and intercept used for calibration. Passed back to group_size().

Description

Group size coefficients

Usage

group_size_coefficients

Format

An object of class data.frame with 162 rows and 21 columns.

Details

A table of group size calibration coefficient values for a variety of species for a variety of observer codes. This table was provided by Jay Barlow (NOAA NMFS Bioligist), was created prior to 2016, and has been used for published analyses through 2021.

Description

This can be useful for plotting datasets that cross the international date line (IDL). (Designed as a behind-the-scences function that most users wont' use, but making it available just in case.)

Usage

idl_coerce(df)

Arguments

Value

Corrected dataframe (all coordinates between 0 and less than -180).

Description

Land

Usage

land

Format

An object of class sf (inherits from data.frame) with 10 rows and 4 columns.

Details

World dataset of land polygons, downloaded from Natural Earth.

Description

This function builds a list of cohort-specific settings – applying only to the analyses for a certain group of species – which you will pass to load_settings().

Usage

load_cohort_settings(
  id = "default",
  species = NULL,
  strata = NULL,
  probable_species = FALSE,
  sighting_method = 0,
  cue_range = 0:7,
  school_size_range = c(0, 10000),
  school_size_calibrate = TRUE,
  calibration_floor = 0,
  use_low_if_na = FALSE,
  io_sightings = 0,
  geometric_mean_group = TRUE,
  truncation_km = 5.5,
  beaufort_range = 0:6,
  abeam_sightings = FALSE,
  strata_overlap_handling = "smallest",
  distance_types = c("S", "F", "N"),
  distance_modes = c("P", "C"),
  distance_on_off = TRUE
)

Arguments

Value

A list with named slots, equivalent to your input arguments. Save this output to an object, e.g., using the same name you provided in the id argument, and pass it to load_settings().

Description

You need the output of this function to pass to process_surveys(), the primary function for processing WinCruz data.

Usage

load_settings(strata = NULL, survey = NULL, cohorts = NULL)

Arguments

Value

A list with three named slots, equivalent to your three input arguments. Save this output to an object, e.g., "settings", and pass it to process_surveys().

Description

This function builds a list of survey-wide settings (applying to all segments and all sightings of all species, regardless of their cohort designation), which you will pass to load_settings().

Usage

load_survey_settings(
  out_handling = "remove",
  interpolate = NULL,
  min_row_interval = 2,
  max_row_interval = 3600,
  max_row_km = 100,
  km_filler = 1,
  speed_filler = 10 * 1.852,
  segment_method = "day",
  segment_target_km = 150,
  segment_max_interval = 48,
  segment_remainder_handling = "segment",
  seed = NULL,
  ship_list = NULL,
  species_codes = NULL,
  group_size_coefficients = NULL,
  smear_angles = FALSE
)

Arguments

Value

A list with named slots, equivalent to your input arguments. Save this output to an object, e.g., "survey_settings", and pass it to load_settings().

Description

For a single species or species pool, fit a detection function and estimate density / abundance, with an option to conduct parametric / non-parametric bootstrap sampling for variance estimation.

Usage

lta(
  cruz,
  Rg0,
  fit_filters,
  df_settings,
  estimates,
  use_g0 = TRUE,
  abund_eff_types = c("S"),
  abund_bft_range = 0:6,
  bootstraps = 0,
  seed = NULL,
  max_attempts = 5,
  results_file = NULL,
  toplot = TRUE,
  verbose = TRUE
)

Arguments

Details

See the vignette online for detailed examples & case studies.

Survey area calculations: The area for which abundance is to be estimated is calculated separately for each sublist within estimates according to the inpunts regions and regions_remove. This calculation is performed by a call to the LTabundR function strata_area(), which handles complex combinations and subtractions of geostrata, accounting for overlapping strata and the (optional) removal of any land area (see its documentation for details). The polygon for each resulting study area is added to the respective estimates sublist. Those polygons can be retrieved from the output's ⁠$inputs⁠ slot.

Weighted g(0) estimates: If g(0) values are not supplied manually for an estimates sublist, a weighted g(0) will be estimated as part of this function's operations through a call to the LTabundR function g0_weighted(), which automatically optimizes a model that estimates the g(0) and its CV based on the distribution of effort in different Beaufort sea states within the specific year, region, and cruise in question. This is only done if the input Rg0 is supplied.

Covariates in detection function estimation: Before detection functions are modelled, any covariates supplied by the user and specified as a factor are first tested for eligibility. Only factors with at least two levels (or whatever you specified with df_settings$covariates_levels) and 10 observations in each level (or whatever you specified with df_settings$covariates_n_per_level) are eligible for inclusion.

Fitting a detection function: The detection function is estimated using functions in the package mrds, primarily the main function mrds::ddf(), which uses a Horvitz-Thompson-like estimator to predict the probability of detection for each sighting. If multiple base key functions (e.g., half-normal or hazard-rate) are provided, and/or if covariates are specified, model fitting is done in a forward stepwise procedure: In the first round, the base model (no covariates, i.e., "~1") is fit first. In the second round, each covariate is added one at a time; at the end of the round, the covariate, if any, that produces the lowest AICc below the AICc from the previous round is added to the formula. This process is repeated in subsequent rounds, adding a new covariate term in each round, until the AICc no longer improves. If a second base key is provided, the process is repeated for that second key. All models within delta_aic of the model with the lowest AICc qualify as best-fitting models.

The best-fitting model(s) is(are) then used to estimate the Effective Strip half-Width (ESW) based on the covariates associated with each sighting. If multiple best-fitting models occur, we will find the average ESW for each sighting across all models, using a weighted mean approach in which we weight according to model AICc. To turn off this model averaging step, set delta_aic to 0 to avoid passing multiple models to the abundance estimation stage.

This stage of the lta() command is executed within a backend function, LTabundR::df_fit(), which has its own documentation for your reference.

Note that if LnSsTot and/or Bft (or any other numeric covariate) are included as candidate covariates, missing data (in the case of LnSsTot, rows where ss_valid == FALSE), will be removed before detection function fitting, but those sightings will not be removed from the sightings data used for abundance estimation (see below). (Note that the code to handle these exceptions are contained within lta(), not df_fit()).

Estimating density & abundance: Estimates are produced for various combinations of species, regions, and years, according to the arguments specified in your estimates list(s). Before these estimates are produced, we filter the data used to fit the detection function to strictly systematic (design-based) effort (as specified in the abund_eff_types and abund_bft_range inputs). Note that if NA's occur in the esw column (due, for instance, to a covariate with missing data for a sighting), they will be replaced with the mean esw value for the remainder of the dataset in that region-year. Similarly, if sightings has a column named ss_valid (all standard cruz objects do) and any of the rows in that column are FALSE, those rows will have their best school size estimate (which will be NA or 1, since they are invalid) replaced by the mean best estimate for their respective species in the year for which abundance is being estimated. Currently the data used for that mean estimate are not specific to a given region, just the year of the abundance estimate.

This stage of the lta() command is executed within a back-end function, LTabundR::abundance(), which has its own documentation for your reference.

Bootstrap variance estimation: If the bootstraps input value is greater than 1, bootstrap variance estimation will be attempted. In each bootstrap iteration, survey segments are re-sampled with replacement before fitting the detection function and estimating density/abundance.

Note that the entire process is repeated in each bootstrap: step-wise fitting of the detection function, averaging of the best-fitting models, and density/abundance estimation for all species/region/year combinations specified in your estimates input. At the end of the bootstrap process, results are summarized for each species/region/year combination. 95% confidence intervals are calculated using the BCA method (adapted from package coxed, function bca()).

g(0) values during bootstrapping: When conducting the non-parametric bootstrap routine to estimate the CV of density and abundance, uncertainty is incorporated into the g(0) value in each iteration using a parametric bootstrapping subroutine: First, a logit-transformed distribution is modeled based upon the mean and CV of g(0) provided by the user in the estimates input (see documentation for LTabundR::g0_optimize() for details on this step). This modeled distribution is used to randomly draw a g(0) value for each iteration of the density/abundance bootstrap routine. In this way, the uncertainty in g(0) is propagated into uncertainty in density/abundance.

Workflow recommendations: This function was designed to optimize workflow where possible. Some considerations:

• Expect a single lta() call for each species pool. You can use a single call to estimate the detection function once, then predict density/abundance separately for each species within the pool.

• Some inputs will be common across all species pools (e.g., df_settings and bootstraps). It may be most efficient – and easiest to keep consistent and to update – if you define these common inputs at the top of your script, then call them with a simple variable in each of your lta() calls.

• We recommend setting up each lta() call starting with bootstraps = 0, so that you can first test that the simple estimation step is successful for all species pools. Then test the bootstrapping functionality by setting bootstraps to 10 in each lta() call. Track how long it takes for your code to run, which you can use to predict processing time for a larger number of iterations, e.g., bootstraps = 1000.

• The most complicated argument to prepare is estimates. To help with this, LTabundR includes a function, lta_estimates(). See its documentation for details.

Value

A named list:

1. pool: The species pool this estimate pertains to.

2. ⁠inputs:⁠ A record of the inputs you provided, stored as a list.

3. estimate: A table of density/abundance estimates for each species/region/year combination specified in the estimates input. This data.frame contains the following fields:

   1. Region: Name(s) of geostrata represented in this estimate.

   2. Area: Area of geostratum / region, in square km.

   3. year: Years represented in this estimate.

   4. segments: The number of effort segments used to estimate density/abundance.

   5. km: The km of trackline effort contained in these segments.

   6. Area_covered: The Area surveyed, according to km and ESW_mean (see next column).

   7. ESW_mean: Mean effective strip width, in kw, calculated as the mean probability of detection for all detections.

   8. n: The number of detections in the data.

   9. g0_est: The mean g(0) estimate of detections, which may differ by group due to group size.

   10. ER_clusters: The encounter rate for detections (schools) (n / km)

   11. D_clusters: The density of detections (schools).

   12. N_clusters: The abundance of schools.

   13. size_mean: Average school size.

   14. size_sd: Standard deviation of school size.

   15. ER: Animal encounter rate.

   16. D: Animal density.

   17. N: Animal abundance.

   18. g0_small: the weighted g(0) for small group sizes in this estimate.

   19. g0_large: the weighted g(0) for large group sizes in this estimate.

   20. g0_cv_small: the CV of weighted g(0) for small group sizes in this estimate.

   21. g0_cv_large: the CV of weighted g(0) for large group sizes in this estimate.

4. df: A named list with details for the detection function.

   1. best_models: A data.frame summary of the best-fitting models, based upon the table produced by Distance::summarize_ds_models(). See that function's documentation for details.

   2. all_models: Similar to the preceding slot, a tabular summary of all models tested.

   3. best_objects: A list containing the ds objects (produced by package Distance) for each of the best-fitting models.

   4. sample_size: A data.frame with the detections for each species within the species pool used to fit the detection function (as well as Other species; see the other_species input). Ntot is total detections for each species; Ndet is total detections within the truncation distance and therefore used in the detection function fitting routine; TD is the truncation distance.

   5. curve: A data.frame of the best-fitting detection function curve (best-fitting models averaged together, weighted by AICc), for 100 distances between 0 and the truncation_distance (two columns: km and p, the probability of detection at that distance).

5. g0_tables: A list with g(0) estimation parameters for each sublist in estimates.

6. bootstrap: A named list with results from the bootstrap process, only returned if the bootstraps input is greater than 1.

   1. summary: a data.frame with a row for each species/region/year combination for which density/abundance was estimated. Notable columns include g0_mean and g0_cv (the mean and CV of g(0) values across parametric bootstrap iterations, which may differ slightly from the non-bootstrapped g0_ estimates provided in the estimate slot above.); Nmean (the mean abundance, based on bootstrap re-sampling); Nmedian (median abundance); Nsd (standard-deviation of abundance); CV (coefficient of variation, which applies to both density and abundance); L95 (the lower BCA 95% confidence interval), and U95 (the upper BCA 95% confidence interval).

   2. details: a data.frame with details for every iteration of the bootstrap routine.

   3. df: a data.frame with the detection function curve for each bootstrap iteration.

Description

This function is designed for a QA/QC step before running the lta() function (line transect analysis). It checks for missing data in covariate columns, group size columns (if lnsstot is a desired covariate), and the perpendicular distance column (PerpDistKm). The function runs these checks twice: first for all sightings to be used in fitting the detection function (where missing data are not preferred but would not be fatal; sightings with incomplete data would simply be removed, lowering your sample size for the model fit), and second for detections that contribute to each point estimate (here missing data is disastrous; unless the missing data are filled in, the detection would be removed and the density estimate would be affected.) This function can be used to pinpoint and address holes in the data as the user sees fit.

Usage

lta_checks(cruz, df_settings, fit_filters, estimates)

Arguments

Value

The function prints messages to the Console as it performs its checks, and it also returns a list with all details needed to find & edit rows in the sightings data that have missing data.

Description

Compute confidence intervals of a bootstrapped LTA estimate

Usage

lta_ci(estimate, bootstraps, ci = 0.95)

Arguments

Value

A list with three versions of the 95% confidence interval, in each case returned as a two-element vector: ⁠$quantile⁠ is the simple quantile-based CI of the bootstraps; ⁠$bca⁠ is the bias-correction with acceleration; and ⁠$bca_lognormal⁠ is the log-normal version of the bca CI. Adapted from Karin Forney's Excel magic.

Description

Combine the results of LTabundR::lta() from separate regions, weighting density by respective area and handling the combination of CV and 95% confidence interval estimates.

Usage

lta_combine(d1, n1, cv1, lci1, uci1, area1, d2, n2, cv2, lci2, uci2, area2)

Arguments

Value

A one-row data.frame with these columns:

1. D: the combined density (animals per square km), weighted by the areas of constituent regions.

2. N: the combined abundance.

3. CV: the combined CV of density and abundance.

4. LCI: the lower 95% confidence interval of abundance.

5. UCI: the upper 95% confidence interval of abundance.

6. area: combined area.

Description

This function loops through a list of results from LTabundR::lta() and updates their CV and 95% CI estimates, which were produced using a bootstrap method, using new estimates based on the delta method.

Usage

lta_delta_method(ltas, verbose = TRUE)

Arguments

Value

An updated version of the ltas input with new values for CV, L95, and U95 in the ⁠$bootstrap$summary⁠ slot.

Description

Loop through a list of stratified line-transect-analysis results and "destratify" – i.e., pool – them into a single estimate.

Usage

lta_destratify(
  lta_list,
  years,
  combine_method = "arithmetic",
  new_region = NULL,
  verbose = TRUE
)

Arguments

Details

Stratified estimates of parameter means are pooled using a weighted mean in which the area of each geostratum is used as the weight. Stratified estimates of abundance variance terms (SD, CV, and 95% confidence interval) are pooled either arithmetically – using standard equations to pool estimates one at a time – or iteratively – using the bootstrap results contained within the lta_list. The iterative technique resamples the abundance bootstrap estimates from each geostratum 10,000 times then calculates SD, CV, and 95% confidence interval from the resulting distribution. Some variance terms, e.g., the SD of school size and the CV of g(0), are not destratified in the current version and are instead replaced with NA.

Value

A modified lta_list, in which stratified estimates have been pooled into single annual estimates for relevant years.

Description

Run diagnostics on a LTA result

Usage

lta_diagnostics(
  lta_result,
  options = 1:8,
  describe_options = FALSE,
  wait = TRUE
)

Arguments

Value

A series of printed tables and plots, which the user can step through using the Enter key.

Description

This function reads in the line-transect-analysis results (from LTabundR::lta()) within a directory and concatenates them into a list.

Usage

lta_enlist(lta_path)

Arguments

Value

A list of LTA results.

Description

This function can be used to efficiently build up sub-lists for the estimates input that you must pass to the lta() function for line-transect analysis. Most studies of multiple species endeavor to estimate density/abundance for each species in the same set of year-region scenarios. Doing so typically requires multiple estimates sub-lists for each species of interest. Writing those sub-lists manually can be redundant, tedious, and prone to inconsistencies or error. To ensure the exact same scenarios are applied to each species of interest, you can use this function to return a custom function that you can then use to creates a standard set of sub-lists for each of you species.

Usage

lta_estimates(scenarios)

Arguments

Value

This function returns a custom function named estimator(), which accepts the following inputs:

• spp (required)

• title (required)

• g0 (the remainder are optional)

• g0_cv

• g0_threshold

• alt_g0_spp

• combine_g0

These arguments are explained under the estimates input for the lta() function. The estimator() function will return a list of sub-lists, in which the species-specific inputs it accepts are added to each sub-list in the scenarios argument you provided above. The result of the estimator() function is what you can pass as the estimates argument in lta(). See the vignette case studies for examples.

Description

This function returns abundance estimate plots (i.e., with year on the x axis, abundance on the y axis, the best estimate represented by a point, and the confidence interval represented by a vertical line). This function is capable of producing multi-panel plots for multiple species, and it is designed to produce a dynamic layout according to the number of species pools provided.

Usage

lta_plot(lta_result, species = NULL, years = NULL, nrows = NULL, ncols = NULL)

Arguments

Value

A ggplot2 plot, or many ggplot2 plots arranged by gridExtra::grid.arrange().

Description

This function allows you to pool, or concatenate, the results of two separate lta() runs in order to achieve the desired number of bootstrap iterations. An example use case: you are running a 1,000-iteration lta() call overnight, but the power goes out at iteration 900. In the morning you can run a 100-iteration version of the same lta() call, then use this function to pool the two results together.

Usage

lta_pool(ltas, bootstraps = NULL)

Arguments

Value

An lta() output object. The ⁠$estimate⁠ slot will be the exact same as the first slot in the ltas input; The ⁠$details⁠ slot will have the pooled bootstrap samples. The ⁠$df⁠ slot will have the pooled detection function curves. The ⁠$summary⁠ slot will have updated summary statistics based on the pooled set of bootstraps.

Description

This function formats the results from an LTA analysis (LTabundR::lta()) into that expected for standard tables in NOAA stock assessment reports (Tables 1, 2, 3, and 4, as well as appendix tables).

Usage

lta_report(lta_result, cruz = NULL, verbose = TRUE)

Arguments

Value

A list with five slots:

1. table1a: Sighting counts for all species in the cruz dataset for the years in which estimates were prepared. If the cruz argument was NULL, this slot is also NULL. If not, a count of all sightings and systematic-only sightings (i.e., EffType = "S" and Bft <= 6) are given for each species-year-region in the cruz data. These counts are provided separately from the ⁠$table1b⁠ slot below, since those counts are based on the lta_result object, and will not include sightings for species that did not have a specific LTA estimate specified when it was made. We also include this separately so as to give the user full flexibility in how they summarize sighting counts by region/population/stock.

2. table1b: Sighting counts used in estimates of density/abundance. Columns are prepared for total sightings (Ntot) and systematic sightings (Nsys), but they are left blank, since it is not clear how sightings from multiple regions in ⁠$table1a⁠ would be concatenated for this table, since that involves stock-level designations. The user can fill in those gaps accordingly.

3. table2: Sample sizes and truncation distances for detection functions modeled by using pooled species/sightings

4. table3: Line-transect parameter estimates (mean Effective Strip half-Width, ESW; mean school size; trackline detection probability, g(0); and its CV).

5. table4: Density and abundance estimates.

6. tableA1 : Appendix table with study areas for each geostratum/cohort/year.

7. tableA2: A list in which each slot is a data.frame with Effort & Beaufort allocation, parsed by geostratum, for each year. If the cruz argument was NULL, this slot is also NULL.

Description

Example of LTA results for three delphinids in 2010 and 2017

Usage

lta_result

Format

An object of class list of length 6.

Details

This dataset was processed using the following code:

data("cnp_150km_1986_2020")
cruz <- cnp_150km_1986_2020
cruz$strata

data('g0_results')
Rg0 <- g0_results

fit_filters = list(spp = c('013', '026', '031'), # striped, frasers, melon-headed
                   pool = 'Multi-species pool 1',
                   cohort = 'all',
                   truncation_distance = 5,
                   other_species = 'remove',
                   years = 1986:2017,
                   regions = NULL,
                   not_regions = NULL)

df_settings = list(covariates = c('bft','lnsstot','cruise','year','ship','species'),
                   covariates_factor = c(FALSE, FALSE, TRUE, TRUE, TRUE, TRUE),
                   covariates_levels = 2,
                   covariates_n_per_level = 10,
                   detection_function_base = 'hn',
                   base_model = '~1',
                   delta_aic = 2)

estimates <-
  list(
    list(spp = '013',
         title = 'Striped dolphin',
         years = 2010,
         regions = 'HI_EEZ',
         g0 = 0.33, g0_cv = 0.20),
    list(spp = '013',
         title = 'Striped dolphin',
         years = 2017,
         regions = 'HI_EEZ',
         g0 = 0.32, g0_cv = 0.21),
    list(spp = '026',
         title = "Fraser's dolphin",
         years = 2010,
         regions = 'HI_EEZ',
         g0 = 0.33, g0_cv = 0.20),
    list(spp = '026',
         title = "Fraser's dolphin",
         years = 2017,
         regions = 'HI_EEZ',
         g0 = 0.32, g0_cv = 0.21),
    list(spp = '031',
         title = 'Melon-headed whale',
         years = 2010,
         regions = 'HI_EEZ',
         g0 = 0.33, g0_cv = 0.20),
    list(spp = '031',
         title = 'Melon-headed whale',
         years = 2017,
         regions = 'HI_EEZ',
         g0 = 0.32, g0_cv = 0.21))

result <- lta(cruz,
              Rg0,
              fit_filters,
              df_settings,
              estimates,
              use_g0 = TRUE,
              bootstraps = 100,
              toplot=TRUE,
              verbose=TRUE)

Description

A flexible routine for carrying out subgroup-based line-transect analysis using the methodologies described for Hawai'ian false killer whales, Pseudorca crassidens, in Bradford et al. (2020). The function returns an estimate of density and abundance – along with estimates of intermediate parameters – with a CV derived from a bootstrapping routine. As part of this process, relative trackline detection probability (g(0)) is modeled as a function of Beaufort sea state (using LTabndR function g0_model()), then a weighted g(0) and its CV are estimated using LTabundR function g0_weighted().

Usage

lta_subgroup(
  df_sits,
  truncation_distance,
  ss,
  density_segments,
  density_das,
  density_sightings,
  df_settings = list(covariates = NULL, covariates_factor = NULL, covariates_levels = 2,
    covariates_n_per_level = 10, simplify_cue = TRUE, simplify_bino = TRUE,
    detection_function_base = "hn", base_model = "~1", delta_aic = 2),
  Rg0 = NULL,
  cruz10 = NULL,
  g0_spp = NULL,
  g0_truncation = NULL,
  g0_constrain_shape = FALSE,
  g0_jackknife_fraction = 0.1,
  abundance_area = NULL,
  iterations = 5000,
  seed = NULL,
  output_dir = NULL,
  toplot = FALSE,
  verbose = TRUE
)

Arguments

Details

This function performs the following operations:

1. Fits a detection function to df_sits, using the LTabundR function df_fit(). That function will be used to estimate the effective strip half-width (ESW) of each sighting in detection_sightings (and bootstrapped versions thereof).

2. Conducts bootstrap re-sampling of the detection function fitting routine in order to estimate the CV of ESW.

3. Estimates the arithmetic mean of subgroup school size based on the ss input.

4. Creates a bootstrap-resampled distribution of subgroup school sizes, with which CV is estimated.

5. Models the relative g(0) in different survey conditions using the LTabundR function g0_model(). This function also estimates the CV of the Rg(0) estimate in each Beaufort sea state using jackknife resampling.

6. Estimates the ESW and encounter rate (subgroup detections / trackline surveyed).

7. Creates a bootstrap-resampled distribution of encounter rate and ESW estimates.

8. Calculates a weighted g(0) estimate according to the proportion of effort occurring in each Beaufort sea state, then uses an automated parameter optimization routine (see details in LTabundR function g0_weighted()) to estimate the CV of the weighted g(0) estimate.

9. Creates a bootstrap-resampled distribution of the weighted g(0) estimate.

10. Estimates density using the best estimates of effective strip half-width, school size, g(0), and the encounter rate.

11. Estimates abundance by scaling the density estimate by the provided abundance_area, if provided.

12. Creates a bootstrap-resampled distribution of the density estimate by iteratively drawing values (without replacement, since the constituent distributions were already built with replacement) from the resampled distributions of the constituent parameters of the density equation.

13. Creates a bootstrap-resampled distribtion of the abundance estimate by scaling the density distribution by abundance_area.

Value

A list with these slots: ⁠$estimate⁠ (point estimates of parameters, detailed below), ⁠$bft⁠ (proportion of survey effort in each sea state), ⁠$g0_details⁠ (details on g0 fitting), ⁠$df⁠ (details on detection function fitting), ⁠$bootstraps⁠ (parameter values for each bootstrap iteration), ⁠$iterations⁠ (the number of iterations). Columns in ⁠$estimate⁠ slot are as follows:

1. D: The estimate of density for the population.

2. D_CV: The CV of the density estimate.

3. D_L95: The lower 95% confidence interval of density using the BCA method.

4. D_U95: The upper 95% confidence interval of density using the BCA method.

5. N: The estimate of abundance.

6. N_CV: The CV of the abundance estimate.

7. N_L95: The lower 95% confidence interval of abundance using the BCA method.

8. N_U95: The upper 95% confidence interval of abundance using the BCA method.

9. ER: The estimate of the encounter rate.

10. ESW = The estimate of the Effective Strip Width (km) for the population.

11. ESW_CV = Estimate of ESW CV, based on standard deviation of bootstrap estimates of ESW.

12. ss = Mean subgroup size estimate.

13. n: Number of sightings used in density estimation.

14. L: Survey effort, in km, used in density estimation.

15. n_segments: Number of effort segments used in density estimation.

16. g0: The empirical weighted mean of g(0) for the point estimate, based on sightings conditions in density_segments.

17. g0_cv: The CV of this estimate of the point estimate of the weighted mean of g(0), as estimated by an MCMC routine.

18. g0_details: A list with detailed results from Rg(0) estimation (see output details in ?g0_model).

19. df: A list with detailed results from detection function estimation (see output details in ?df_fit).

20. bootstraps: A named list with the bootstrapped values for esw (effective strip half-width), ss (subgroup size), g0 (relative g(0)), er (encounter rate), D (density), and N (abundance).

21. iterations: number of bootstrap iterations used for CV estimation.

See the online vignette for more details

Description

Produced an interactive leaflet map of your Wincruz survey data.

Usage

map_cruz(
  cruz,
  cohort = 1,
  eez_show = TRUE,
  eez_color = "black",
  eez_weight = 0.6,
  eez_opacity = 0.5,
  strata_show = TRUE,
  strata_color = "forestgreen",
  strata_weight = 1,
  strata_opacity = 0.5,
  effort_show = FALSE,
  effort_color = "darkblue",
  effort_weight = 0.6,
  effort_opacity = 0.85,
  sightings_show = TRUE,
  sightings_color = "color code",
  sightings_radius = 1,
  sightings_opacity = 0.5,
  initial_zoom = 4,
  verbose = TRUE
)

Arguments

Value

An interactive leaflet map.

Description

Cruise data processed for all NOAA SWFSC and PIFSC surveys, 1986 - 2020 (10 km segment lengths)

Usage

noaa_10km_1986_2020

Format

An object of class list of length 3.

Details

This dataset was processed using the following code:

data(group_size_coefficients)

survey <- load_survey_settings(
out_handling = 'stratum',
max_row_interval = Inf,
segment_method = "equallength",
segment_target_km = 10,
segment_max_interval = 6,
segment_remainder_handling = c("segment"),
group_size_coefficients = group_size_coefficients)

data(strata_ccs)
data(strata_cnp)
strata <- c(strata_ccs, strata_cnp)
strata$NEPAC <- data.frame(Lat = c(-20, -20, 65, 65), Lon = c(-230, -70, -70, -200))

all_species <- load_cohort_settings(
id = "all",
species = NULL,
probable_species = FALSE,
sighting_method = 0,
cue_range = 0:7,
school_size_range = c(0, 10000),
school_size_calibrate = TRUE,
calibration_floor = 0,
use_low_if_na = TRUE,
io_sightings = 0,
geometric_mean_group = TRUE,
truncation_km = 7.5,
beaufort_range = 0:6,
abeam_sightings = FALSE,
strata_overlap_handling = c("smallest"),
distance_types = c('S','F','N'),
distance_modes = c('P','C'),
distance_on_off = TRUE
)

settings <- load_settings(strata = strata,
                       study_area = NULL,
                       survey = survey,
                       cohorts = list(all_species))

das_file = c('../test_code/data/swfsc_1986_2020.das')
swfsc <- process_surveys(das_file,
                      settings = settings)

das_file = '../test_code/CNP/CenPac1986-2020_Final_alb.das'
pifsc <- process_surveys(das_file,
                      settings = settings)

cruzes <- list(swfsc, pifsc)
noaa_10km_1986_2020 <- cruz_combine(cruzes)

Description

This is an internal function typically not called by a user directly.

Usage

points_to_line(data, long, lat, id_field = NULL, sort_field = NULL)

Arguments

Value

A sp::SpatialLines object created from sp::spRbind().

Description

An interior function, typically not called by analysts. This function returns segment and sighting data according to resampled segment IDs, which serve as part of the bootstrap variance estimation process. The function includes an option to specify a selection of segment IDs, which allows the same bootstrap segments to be selected for the abundance estimation stage as was used in the detection function model fitting stage.

Usage

prep_bootstrap_datasets(segments, sightings, segment_picks = NULL, seed = NULL)

Arguments

Value

A list with resampled data: segments, sightings, and segment_picks (a numeric vector of segment IDs that have been re-sampled).

Description

This function is the near-equivalent of the DISTRAV subroutine in ABUND9. This is an internal function typically not called by a user directly. It is called in format_das().

Usage

process_km(
  das,
  min_interval = 5,
  max_interval = 3600,
  replacement_interval = 3600,
  max_km_gap = 100,
  km_filler = 1,
  speed_filler = 10 * 1.852,
  debug_mode = TRUE
)

Arguments

Value

A numeric vector, the same length as the number of rows in das, of distances (in km). The final element of this vector will be 0.

Description

This is an internal function typically not called by a user directly. It takes a dataframe of polygon coordinates and returns a list with the polygon formatted in various ways, as well as a calculation of the area of the polygon with land area removed (optionally).

Usage

process_polygon(polygon_dataframe, remove_land = TRUE, toplot = FALSE)

Arguments

Value

A list with four named slots:

1. coords The input dataframe, with longitudes corrected to proper negative decimal degrees, e.g., longitudes supplied as -185 will become 175.

2. polygon The polygon created by sf::st_polygon()

3. sf The sf version of the polygon that will be passed to mapping functions.

4. sf_land The sf version of the land polygons included within the polygon, if any.

5. km2 The area of the polygon, in square kilometers.

6. idl A Boolean indicating whether or not this polygon crosses the International Date Line.

7. lat_range Latitude range of polygon, in decimal degrees (N positive, S negative).

8. lon_range Longitude range of polygon, in decimal degrees (E positive, W negative).

9. plot A ggplot object; NULL if the input toplot is FALSE.

Description

This is an internal function typically not called by a user directly. It is the fifth subroutine called within process_surveys(), after segmentize() and before process_subgroups().

Usage

process_sightings(
  cruz,
  calibrate = NULL,
  calibrate_floor = NULL,
  geometric_mean = NULL,
  verbose = TRUE
)

Arguments

Value

A modified cruz object, in which a sightings dataframe (one row for each species in each sighting, with school size estimates averaged and calibrated according to cohort-specific settings) has been added to each ⁠<cohort>⁠ list. The sightings dataframe has a new column, included, indicating whether or not a sighting will be included in an analysis according to the inclusion criteria specified in cohort-specific settings, as well as a new column, ss_valid, indicating whether or not the school size estimate for this sighting is valid and appropriate for use in abundance estimation and/or detection function fitting with a school-size covariate. All columns are described in detail within the documentation for the LTabundR function, process_surveys().

Description

Determine in/out status of DAS events for each geo-strata provided by settings. This function loops through each stratum dataframe you have provided it in settings$strata, formats the stratum, and asks whether each DAS row occurs within it.

This is an internal function typically not called by a user directly. It is the second subroutine called within process_surveys(), after load_das() and before format_das().

Usage

process_strata(das, settings, verbose = TRUE)

Arguments

Value

A list with two named slots: settings and das. The das slot has the dataframe of your survey data. For each stratum, a column named ⁠stratum_<StratumName>⁠ is added to the das dataframe; each row in this column is TRUE (included) or FALSE.

Description

Subgroups are found based on DAS event code "G" and associated events. Subgroup sizes are estimated for each phase (based upon the false killer whale protocol), and both arithmetic and geometric means are provided.

This is an internal function typically not called by a user directly. It is the final processing subroutine called within process_surveys(), after the subroutine process_sightings().

Usage

process_subgroups(cruz, edits = NULL, verbose = TRUE)

Arguments

Value

A finalized cruz object. If subgroups are found, a subgroups slot is added to the analysis list for a cohort. This subgroups slot holds a list with three dataframes:

1. events, in which each row is a school size estimate for a single subgroup during a single phase – 1 or 2 – within a single sighting;

2. subgroups, in which each row is a single phase for a single subgroup, with all school size estimates averaged together (both arithmetically and geometrically);

3. sightings, in which each row is a school size estimate for a single phase for a single sighting, with all subgroup school sizes summed together.

Phase is determined simply according to the OnEffort column. If it is TRUE, Phase is 1; if not, Phase is 2.

Description

This function is the main command you will use to begin working with your survey data in R. It takes Wincruz survey data – .DAS file(s) – and user-specified settings to prepare the data for density estimation and/or habitat modeling analyses.

This function was designed to be similar to ABUND9, the Fortran program written by Jay Barlow (NOAA SWFSC) for the same purpose.

Usage

process_surveys(
  das_file,
  settings,
  edits = NULL,
  process_sightings = TRUE,
  process_subgroups = TRUE,
  save_local = FALSE
)

Arguments

Details

This function is a wrapper for several subroutines, which are executed in the following order:

1. Read and format the survey data contained in your DAS file using functions developed in the package swfscDAS (this step is carried out using the internal LTabundR function load_das()).

2. Interpolate the DAS data, if instructed by settings. See load_survey_settings() for details.

3. Determine which DAS events occur within the geo-strata provided by the user (using the internal LTabundR function process_strata()).

4. Remove invalid entries, determine the ship used in each cruise, calculate the distance transited between each DAS row, and initiate the data structure for the eventual cruz object output. (using the internal LTabundR function format_das()).

5. Parse survey effort into "segments", which are used in variance estimation, and determine which segments should be included in the analysis based upon user-specified settings (using the internal LTabundR function segmentize()).

6. Process sightings (optional) by determining which should be included in the analysis based upon user-specified settings, and refine school size estimates by calibrating observer estimates and averaging estimates from multiple observers. (using the internal LTabundR function process_sightings()).

7. Process subgroup size estimates (optional) for false killer whales (using the internal LTabundR function process_subgroups()).

8. The above process is repeated for each DAS file; if there are multiple DAS files, the results are combined using LTabundR::cruz_combine().

9. Optionally save the result as an RData object to easily pass the processed data to other R scripts.

Value

A cruz object, which is a nested list with the following primary slots:

1. settings, containing the settings list you provided as an argument.

2. strata, containing a dataframe summarizing the geostrata provided (their name and area, in square km).

3. cohorts, containing a named list for each cohort you specified within the settings argument.

Each cohort slot has a similar structure:

⁠cruz$cohorts$<cohort>$<details>⁠

• The name of each ⁠<cohort>⁠ slot is drawn from the id slot within that cohort's settings (e.g., settings$cohorts[[1]]$id).

• All cohorts have the same three slots for ⁠<details>⁠:

  1. segments, a data.frame with metadata for each effort segment (see below).

  2. das, a data.frame of the survey data (see below).

  3. sightings, a data.frame with details for each sighting (see below).

• Some cohorts may also have a fourth ⁠<details>⁠ slot, subgroups, if subgroups were found in the data for the species specified in the cohort. This slot will contain a list (see below).

segments data structure
A data.frame with metadata for each segment; each row is a segment.

1. Cruise: Cruise number

2. ship: Ship name initials

3. stratum: Stratum designation for this segment

4. seg_id: Unique segment identifier

5. yday: Numeric day of year

6. dist: Distance surveyed in this segment

7. lat1: Start latitude of segment, decimal degrees

8. lon1: Start longitude of segment, decimal degrees

9. DateTime1: Date and time for start of segment, formatted as a lubridate::datetime object

10. timestamp1: Numeric timestamp for start of segment (seconds since 00:00:00 UTC on 1 January 1970)

11. lat2: Ending latitude

12. lon2: Ending longitude

13. DateTime2: Date and time of end of segment

14. timestamp2: Numeric timestamp for end of segment

15. mlat: Latitude of middle of segment (i.e., the coordinate for the row of DAS data that is at ⁠nrow(<segment data>) / 2⁠)

16. mlon: Longitude of middle of segment

17. mDateTime: Date and time of middle of segment

18. mtimestamp: Numeric timestamp of middle of segment

19. use: A decision as to whether or not this segment will be included in the analysis, based upon user-specified criteria in settings.

20. Mode: Effort mode (P for passing or C for closing)

21. EffType: Effort type (S for systematic, N for non-systematic – i.e., off design-based trackline – and F for fine-scale)

22. OnEffort: If TRUE, standard search protocols are in practice

23. ESWsides: Number of sides for which the effective strip width (ESW) will apply. When traveling nearshore, this may be only 1

24. year: Year

25. month: Numeric month

26. day: Numeric day of month

27. min_line: The line number of DAS data at the start of this segment

28. max_line: The final line number

29. n_rows: Number of rows of DAS data in this segment

30. avgBft: Weighted average Beaufort sea state during this segment

31. avgSwellHght: Weighted average Swell Height, in feet, during this segment

32. avgHorizSun: Weighted average horizontal sun angle, corresponding to a clock face, during this segment

33. avgVertSun: Weighted average vertical sun angle (12 = overhead, 1-3 = at the horizon) during this segment

34. avgGlare: Weighted average Glare status during this segment

35. avgVis: Weighted average visibility (defines as the distance, in nautical miles, at which a dolphin could be seen surfacing with the water, not the sky, as the background) during this segment

36. avgCourse: Weighted average ship heading during this segment

37. avgSpdKt: Weighted average speed, in knots, during this segment

das data structure
The data.frame of DAS survey data, as read and formatted by swfscDAS::das_read() and swfscDAS::das_process() See the latter function documentation for details on columns. We have added the following columns during the preparation of the cruz object:

• ⁠stratum_<stratum name>⁠ A Boolean indicating whether or not this row of data occurs within this geostratum polygon. There will be a column like this for each geostratum provided in your settings object.

• year Year

• month Numeric month

• day Numeric day of month

• yday Numeric day of year

• km_int Distance, in kilometers, between this row of data and the next. See documentation for process_km() for details.

• km_cum Cumulative distance traveled up to this point in the DAS data.

• ship Ship name initials

• stratum Final stratum designation, decided based upon user-specific settings.

• seg_id Identifier for the segment containing this row of data.

• use: A Boolean decision as to whether or not this segment will be included in the analysis, based upon user-specified criteria in settings.

sightings data structure
The data.frame of processed sightings, as prepared by swfscDAS::das_sight(return.format = 'complete'). See that function's documentation for details on columns. Note that the unique sighting identifier can be found in column SightNodaily, not SightNo. That function returns up to several rows for each sighting (DAS event codes S, s, A, 1, 2, ..., etc.). We have processed the result further such that each row represents the school size estimate for a single species within a single sighting. For example, single-species sightings will always have just one row. We have also added the following columns during the preparation of the cruz object:

• See the columns added to the das slot above; those have all been propagated to this sightings table.

• species: species code (character string) for the species represented by this row.

• best: Best estimate of school size (calibrated and averaged across observer estimates according to settings)

• low: Low estimate of school size (ditto)

• high: High estimate of school size (ditto)

• prob: If TRUE, this species code is a probable identification (DAS event code ⁠?⁠).

• mixed: If TRUE, this species occurred in a mixed-species school.

• ss_tot: Total school size (calibrated and averaged across observer estimates according to settings)

• ss_percent: Percent of the school comprised by this species (averaged across observer estimates).

• n_sp: Number of species in this sighting.

• n_obs: Number of observers who contributed a school size estimate for this species.

• n_best: Number of valid best estimates of school size.

• n_low: Number of valid low estimates.

• n_high: Number of valid high estimates.

• calibr: Boolean indicating whether school size calibration was applied.

• ss_valid: Boolean indicating whether or not the school size estimate for this sighting is valid and appropriate for use in abundance estimation and/or detection function fitting with a school-size covariate.

• included: Boolean indicating whether the sightings should be included in the analysis based on the specified settings. Any sighting with use == FALSE will also have included == FALSE, but it is possible for sightings to have use == TRUE with included == FALSE. For example, if the setting abeam_sightings is set to FALSE, a sighting with a bearing angle beyond the ship's beam can be excluded from the analysis (included == FALSE) even though the effort segment it occurs within will still be used (use == TRUE).

subgroups data structure
If subgroup events (DAS event code G) are found pertaining to the species in your cohort, this slot will have a list with three slots:

1. sightings: A data.frame in which each row is a school size estimate for a single phase for a single sighting, with all subgroup school sizes summed together. Columns:

   1. Cruise

   2. Date

   3. SightNo

   4. Phase

   5. DateTime Mean date and time of estimates of this sighting

   6. Lat (same – mean)

   7. Lon (same – mean)

   8. Species

   9. Angle (same – mean)

   10. RadDist (same – mean)

   11. seg_id Identifier for the segment containing this row of data.

   12. PerpDist (same – mean)

   13. GSBest Sum of arithmetic means of best estimates of subgroups

   14. GSBest_geom Sum of geometric means

   15. EffType Type of effort (systematic, nonsystematic, or fine-scale)

   16. OnEffort Whether or not standard search protocols are in use (TRUE or FALSE).

   17. use Whether the segment on which this sighting occurred meets analysis inclusion criteria.

   18. ⁠stratum_[stratum name]⁠ A set of columns, one for each geostratum in the cruz object settings file, indicating whether or not this location occurs within each geostratum.

   19. stratum The geostratum to which this location was assigned, based upon cohort settings.

2. subgroups: A data.frame in which each row is a single phase for a single subgroup, with all school size estimates averaged together (both arithmetically and geometrically). Columns:

   1. Cruise

   2. Date

   3. DateTime First date and time of estimates of this subgroup

   4. Lat (same – first data point for estimates of this subgroup)

   5. Lon (same)

   6. OnEffort (same)

   7. EffType (same)

   8. SightNo (same)

   9. Species (same)

   10. SubGrp (same)

   11. Angle Mean angle to this subgroup

   12. RadDist Mean radial distance to this subgroup

   13. seg_id Identifier for the segment containing this row of data.

   14. PerpDist Mean perpendicular distance to this subgroup

   15. GSBest Arithmetic mean of best estimates of this subgroup. If no best estimates are given, the GSL value will be used here.

   16. GSH Arithmetic mean of high estimates of this subgroup

   17. GSL Arithmetic mean of low estimates of this subgroup

   18. GSBest_geom Geometric mean of best

   19. GSH_geom Geometric mean of high

   20. GSL_geom Geometric mean of low

   21. Phase Phase (1 or 2)

   22. use Whether the segment on which this sighting occurred meets analysis inclusion criteria.

   23. ⁠stratum_[stratum name]⁠ A set of columns, one for each geostratum in the cruz object settings file, indicating whether or not this location occurs within each geostratum.

   24. stratum The geostratum to which this location was assigned, based upon cohort settings.

3. events: A data.frame in which each row is single subgroup size estimate from a single observer for a single phase (Phase 1 – on effort / passing mode – or Phase 2 – off effort / closing mode). This is effectively the "raw" subgroup data. Columns:

   1. Cruise Cruise number

   2. Date Date, in format YYYY-MM-DD

   3. DateTime Date and time, in format YYYY-MM-DD HH:MM:SS

   4. Lat Latitude, in decimal degrees

   5. Lon Longitude, in decimal degrees

   6. OnEffort If TRUE, standard search protocols are in use. If FALSE, non-standard protocols (or no searching at all).

   7. EffType Effort type (S for systematic, N for non-systematic, and F for fine-scale)

   8. SightNo Sighting number of the day (the count resets every day)

   9. Species Species code (character string)

   10. Line Line number in DAS data

   11. SubGrp Subgroup identifier code

   12. Event Count of estimates for this subgroup-phase

   13. Obs Observer code

   14. GSBest Best estimate of subgroup size

   15. GSH High estimate of subgroup size

   16. GSL Low estimate of subgroup size

   17. Angle Angle between bow and subgroup

   18. RadDist Radial distance to subgroup, in km

   19. use Whether the segment on which this sighting occurred meets analysis inclusion criteria.

   20. ⁠stratum_[stratum name]⁠ A set of columns, one for each geostratum in the cruz object settings file, indicating whether or not this location occurs within each geostratum.

   21. stratum The geostratum to which this location was assigned, based upon cohort settings.

   22. PerpDist Perpendicular distance to subgroup from the trackline represented by the ship heading, in km

   23. sgid Unique subgroup identifier

   24. sitid Unique sighting identifier

   25. phase Phase in protocol; all OnEffort == TRUE estimates are Phase 1; all OnEffort == FALSE estimates are Phase 2.

This cruz object can be carried forward into data exploration (e.g., see the LTabundR function cruz_explorer()), analyses (e.g., see the LTabundR function lta()), or passed to mapping functions (see the LTabundR functions that begin with map_...) or summary functions (see the LTabundR functions that begin with summarize_...).

Description

This is an internal function typically not called by a user directly. This function reads in a .DAT file with coordinates for one or more polygons, returning a list.

Usage

read_polygon(dat_file)

Arguments

Value

A named list:

1. polygons A dataframe summarizing the polygons contained in the .DAT file. It has four columns: name (polygon name), area (polygon area, if provided), name_i (the index of the polygon in the file), and area_i (the index of the area provided in the file).

2. coordinates A list with a slot for each polygon contained within the .DAT file. Each polygon is a dataframe with two columns: Lon and Lat, with coordinates formatted as provided by the .DAT file.

3. dat The raw DAT file, as it was read by R, returned as a dataframe.

Description

This is an internal function, typically not called by the user.

Usage

region_das(das, regions)

Arguments

Value

A vector of line_num values whose data occur within any of regions, which can be used to filter segments and sightings.

Description

This is an internal function, typically not called by the user.

Usage

region_segments(das, regions)

Arguments

Value

A vector of segment IDs whose data occur within regions, which can be used to filter segments and sightings by the seg_id column.

Description

This function chops DAS effort into discrete sections for the purposes of estimating the variance of the abundance estimate.

This is an internal function typically not called by a user directly. It is the fourth subroutine called within process_surveys(), after format_das() and before process_sightings(). However, arguments are provided that allow you to call this function directly and override settings so that you can explore how segmentizing works.

Usage

segmentize(
  cruz,
  segment_method = NULL,
  segment_target_km = NULL,
  segment_max_interval = NULL,
  segment_remainder_handling = NULL,
  beaufort_range = NULL,
  distance_types = NULL,
  distance_modes = NULL,
  distance_on_off = NULL,
  seed = NULL,
  to_plot = TRUE,
  debug_mode = FALSE,
  verbose = FALSE
)

Arguments

Value

A modified cruz object, in which each cohort slot contains a list with the following slots: das (with two new columns, seg_id, indicating the segment corresponding to each DAS row; and use, indicating whether or not (TRUE or FALSE) the segment is to be included in the analysis.) and segments (a dataframe summarizing each segment).

Description

Ship codes

Usage

ships

Format

An object of class data.frame with 66 rows and 3 columns.

Details

A data.frame matching the ship name initials to the NOAA-NFMS cruise number.

Description

Species codes used in WinCRUZ

Usage

species_codes

Format

A data.frame with 164 rows and 5 variables:

code

Code used in WinCRUZ

short_name

Abbreviated name, in all CAPS

scientific_name

Latin Genus species

common

Most common name

description

Alternative common names

Details

A data.frame containing species codes and associated identifiers.

Description

Retrieve common and scientific names for a species based on their code number or short name, or vice versa: retrieve the species code based on common or scientific name.

Usage

species_translator(
  id,
  codes = NULL,
  match_by_code = TRUE,
  match_by_short_name = TRUE,
  match_by_latin = TRUE,
  match_by_common = TRUE
)

Arguments

Value

A data.frame with all viable patches to your search query.

Examples

species_translator('046') # match by species code
species_translator('46') # partial matches work
species_translator(46) # numeric codes work
species_translator('RM_WHA') # partial short names work
species_translator('Physeter') # latin names work
species_translator('orca') # common names work + partial matches + case insensitive
species_translator('orca', match_by_latin=FALSE) # toggle match modes

Description

This function allows for complex combinations / subtractions of geostratum polygons and calculates the resulting area before and after the removal of dry land. Diagnostic plots are provided that ensure the result is correct.

Usage

strata_area(
  strata_all,
  strata_keep,
  strata_remove = NULL,
  remove_land = TRUE,
  toplot = TRUE,
  verbose = TRUE
)

Arguments

Value

A list with the following slots:

1. km2 The area of the resulting survey area polygon, in square km.

2. km2_keep The area of the strata_keep polygons, after combining them to account for any overlapping portions of the polygons, but before removing land.

3. km2_remove The area of the strata_remove polygons, if any were provided, after combining them to account for any overlapping portions of the polygons, but before removing land.

4. km2_with_land The area of the resulting survey area polygon before removing land.

5. sf The sf object of the resulting polygon.

Note that if toplot is TRUE (the default), a diagnostic plot will also be produced.

Description

Strata CCS

Usage

strata_ccs

Format

An object of class list of length 5.

Details

Typical geostrata used in the California Current System region.

Description

Strata CNP

Usage

strata_cnp

Format

An object of class list of length 12.

Details

Typical geostrata used in the Central North Pacific region.

Description

Strata ETP

Usage

strata_etp

Format

An object of class list of length 70.

Details

Typical geostrata used in the Eastern Tropical Pacific region.

Description

The LTabundR package comes with several built-in datasets of geographic strata that are commonly used in NOAA/NMFS surveys. The functions strata_explore() and strata_select() were developed to help you explore those built-in options.

strata_explore() launches a leaflet map displaying the built-in geostrata datasets available for your use in the common NOAA/NMFS survey regions. Each stratum displayed as a separate layer that can be hidden or hovered over to get details.

Usage

strata_explore(
  region,
  start_at = 1,
  strata_color = "darkblue",
  begin_hidden = FALSE
)

Arguments

Value

An interactive leaflet map. The name of the geostratum, and the numeric identifier for it, are printed in a legend as well as in a pop-up box that appears when you hover over a stratum. Use this identifier as an argument in the companion function, strata_select(), to access the datasets of coordinates underlying the polygons displayed.

Description

A simple diagnostic function, usually not used by most analysts.

Usage

strata_segments(cruz, cohort = 1, plot_title = "Stratum assignments")

Arguments

Value

A ggplot2 object.

Description

The LTabundR package comes with several built-in datasets of geographic strata that are commonly used in NOAA/NMFS surveys. The functions strata_explore() and strata_select() were developed to help you explore those built-in options.

Those built-in datasets come in the form of a list, in which each slot is a separate geostratum. strata_select() allows you to "grab" the underlying data (i.e., the data.frame of Lat/Long coordinates) for one of the geostrata displayed by strata_explore().

Usage

strata_select(selections, region)

Arguments

Value

A data.frame of coordinates for the boundary of a geostratum. You can pass this object to the strata argument for load_settings().

Description

Stage edits to subgroups (e.g., phase and population assignments)

Usage

subgroup_edits(
  cohort,
  sgid,
  exclude = NULL,
  ObsStd = NULL,
  phase = NULL,
  population = NULL,
  pop_prob = NULL
)

Arguments

Value

A list of staged edits that will be accepted by the edits input in process_subgroups().

Description

This is an internal function typically not called by a user directly. It is called in process_subgroups(), which is an internal function called in process_surveys().

Usage

subgroup_events(das, species_filter = "033")

Arguments

Value

A data.frame in which each row is a single school size estimate for a single subgroup within a single phase of a single sighting (effectively, the 'raw' data for subgroups within the das data).

Description

Simple explorer for subgroups data

Usage

subgroup_explorer(cruz, cohort = "pseudorca")

Arguments

Value

A Shiny app to explore subgroup event data for a cohort within a cruz object.

Description

Review & stage edits to subgroup phase assignments

Usage

subgroup_phases(cruz, cohort)

Arguments

Value

A Shiny app that allows you to make manually stage revisions to the phase assigned to each subgroup (this is in reference to the protocol developed for false killer whales by NOAA PIFSC). Those phases were assigned automatically during the process_surveys() routine; this is a way for you to review those assignments and prepare a set of revisions. When you close the app, those revisions are returned as a list(), which you can then save to file and/or pass to LTabundR::subgroup_edit(), which will implement the revisions by modifying the data in your cruz object. This function, subgroup_phases(), does not edit the cruz object in any form.

Description

Assign subgroups to populations based on polygons

Usage

subgroup_populations(
  populations,
  cruz,
  cohort = "pseudorca",
  default_pop = "pelagic",
  verbose = TRUE
)

Arguments