das_effort {swfscDAS}

Summarize DAS effort

Description

Chop DAS data into effort segments

Usage

das_effort(x, ...)

## S3 method for class 'data.frame'
das_effort(x, ...)

## S3 method for class 'das_df'
das_effort(
  x,
  method = c("condition", "equallength", "section"),
  conditions = NULL,
  strata.files = NULL,
  distance.method = c("greatcircle", "lawofcosines", "haversine", "vincenty"),
  seg0.drop = FALSE,
  comment.drop = FALSE,
  event.touse = NULL,
  num.cores = NULL,
  ...
)

Arguments

x

an object of class das_df, or a data frame that can be coerced to class das_df

...

arguments passed to the specified chopping function, such as seg.km or seg.min.km

method

character; method to use to chop DAS data into effort segments Can be "condition", "equallength", "section", or any partial match thereof (case sensitive)

conditions

character vector of names of conditions to include in segdata output. These values must be column names from the output of das_process, e.g. 'Bft', 'SwellHght', etc. If method == "condition", then these also are the conditions which trigger segment chopping when they change. Only the following conditions can be used for chopping: 'Bft', 'SwellHght', 'RainFog', 'HorizSun', 'VertSun', 'Glare', 'Vis', 'Course', 'SpdKt'

strata.files

list of path(s) of the CSV file(s) with points defining each stratum. The CSV files must contain headers and be a closed polygon. The list should be named; see the Details section. If NULL (the default), then no effort segments are not classified by strata.

distance.method

character; method to use to calculate distance between lat/lon coordinates. Can be "greatcircle", "lawofcosines", "haversine", "vincenty", or any partial match thereof (case sensitive). Default is "greatcircle"

seg0.drop

logical; flag indicating whether or not to drop segments of length 0 that contain no sighting (S, K, M, G, t) events. Default is FALSE

comment.drop

logical; flag indicating if comments ("C" events) should be ignored (i.e. position information should not be used) when segment chopping. Default is FALSE

event.touse

character vector of events to use to determine segment lengths; overrides comment.drop. If NULL (the default), then all on effort events are used. If used, this argument must include at least R, E, S, and A events, and cannot include ? or 1:8 events

num.cores

Number of CPUs to over which to distribute computations. Defaults to NULL, which uses one fewer than the number of cores reported by detectCores. Using 1 core likely will be faster for smaller datasets

Details

This is the top-level function for chopping processed DAS data into modeling segments (henceforth 'segments'), and assigning sightings and related information (e.g., weather conditions) to each segment. This function returns data frames with all relevant information for the effort segments and associated sightings ('segdata' and 'sightinfo', respectively). Before chopping, the DAS data is filtered for events (rows) where either the 'OnEffort' column is TRUE or the 'Event' column "E". In other words, the data is filtered for continuous effort sections (henceforth 'effort sections'), where effort sections run from "R" to "E" events (inclusive), and then passed to the chopping function specified using method. Note that while B events immediately preceding an R are on effort, they are ignored during effort chopping. In addition, all on effort events (other than ? and numeric events) with NA DateTime, Lat, or Lon values are verbosely removed.

If strata.files is not NULL, then the effort lines will be split by the user-provided stratum (strata). In this case, a column 'stratum' will be added to the end of the segdata data frame with the user-provided name of the stratum that the segment was in, or NA if the segment was not in any of the strata. If no name was provided for the stratum in strata.files, then the value will be "Stratum#", where "#" is the index of the applicable stratum in strata.files. While the user can provide as many strata as they want, these strata can share boundaries but they cannot overlap. See das_effort_strata for more details.

The following chopping methods are currently available: "condition", "equallength", and "section. When using the "condition" method, effort sections are chopped into segments every time a condition changes, thereby ensuring that the conditions are consistent across the entire segment. See das_chop_condition for more details about this method, including arguments that must be passed to it via the argument ...

The "equallength" method consists of chopping effort sections into equal-length segments of length seg.km, and doing a weighted average of the conditions for the length of that segment. See das_chop_equallength for more details about this method, including arguments that must be passed to it via the argument ...

The "section" method involves 'chopping' the effort into continuous effort sections, i.e. each continuous effort section is a single effort segment. See das_chop_section for more details about this method.

The distance between the lat/lon points of subsequent events is calculated using the method specified in distance.method. If "greatcircle", distance_greatcircle is used, while distance is used otherwise. See das_sight for how the sightings are processed.

The sightinfo data frame includes the column 'included', which is used in das_effort_sight when summarizing the number of sightings and animals for selected species. das_effort_sight is a separate function to allow users to personalize the included values as desired for their analysis. By default, i.e. in the output of this function, 'included' is TRUE if: the sighting was made when on effort, by a standard observer (see das_sight), and in a Beaufort sea state less than or equal to five.

Value

List of three data frames:

• segdata: one row for every segment, and columns for information including unique segment number (segnum), the corresponding effort section (section_id), the segment index within the corresponding effort section (section_sub_id), the starting and ending line of the segment in the DAS file (stlin, endlin), start/end/midpoint coordinates(lat1/lon1, lat2/lon2, and mlat/mlon, respectively), the start/end/midpoint date/time of the segment (DateTime1, DateTime2, and mDateTime, respectively; mDateTime is the average of DateTime1 and DateTime2), segment length (dist), conditions (e.g. Beaufort), and, if applicable, stratum (InStratumName).

• sightinfo: details for all sightings in x, including: the unique segment number it is associated with, segment mid points (lat/lon), the 'included' column described in the 'Details' section, and the output information described in das_sight for return.format is "default"

• randpicks: see das_chop_equallength; NULL if using "condition" method

See Also

Internal functions called by das_effort: das_chop_condition, das_chop_equallength, das_chop_section, das_segdata

Examples

y <- system.file("das_sample.das", package = "swfscDAS")
y.proc <- das_process(y)

# Using "condition" method
das_effort(
  y.proc, method = "condition", conditions = c("Bft", "SwellHght", "Vis"),
  seg.min.km = 0.05, num.cores = 1
)

# Using "section" method
das_effort(y.proc, method = "section", num.cores = 1)


# Using "equallength" method
y.rand <- system.file("das_sample_randpicks.csv", package = "swfscDAS")
das_effort(
  y.proc, method = "equallength", seg.km = 10, randpicks.load = y.rand,
  num.cores = 1
)

# Using "section" method and chop by strata
stratum.file <- system.file("das_sample_stratum.csv", package = "swfscDAS")
das_effort(
  y.proc, method = "section", strata.files = list(Poly1 = stratum.file),
  num.cores = 1
)