Skip to contents

Chop AirDAS data - equal length

Source: R/airdas_chop_equallength.R
airdas_chop_equallength.Rd

Chop AirDAS data into equal-length effort segments, averaging conditions by segment

Usage

airdas_chop_equallength(x, ...)

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

# S3 method for class 'airdas_df'
airdas_chop_equallength(
  x,
  conditions,
  seg.km,
  randpicks.load = NULL,
  distance.method = NULL,
  num.cores = NULL,
  ...
)

Arguments

x

airdas_df object, or a data frame that can be coerced to a airdas_df object. This data must be filtered for 'OnEffort' events; see the Details section below

...

ignored

conditions

see airdas_effort

seg.km

numeric; target segment length in kilometers

randpicks.load

character, data frame, or NULL. If character, must be filename of past randpicks output to load and use (passed to file argument of read.csv). If data frame, randpicks values will be extracted from the data frame. If NULL, new randpicks values will be generated by the function

distance.method

character; see airdas_effort. Default is NULL since these distances should have already been calculated in airdas_effort

num.cores

See airdas_effort

Value

List of three data frames:

  • x, with columns added for the corresponding unique segment code and number

  • segdata: data frame with one row for each segment, and columns with relevant data (see airdas_effort for specifics)

  • randpicks: data frame with record of length allocations (see Details section above)

Details

WARNING - do not call this function directly! It is exported for documentation purposes, but is intended for internal package use only.

This function is intended to only be called by airdas_effort when the "equallength" method is specified. Thus, x must be filtered for events (rows) where either the 'OnEffort' column is TRUE or the 'Event' column is either "E" or "O"; see airdas_effort for more details. This function chops each continuous effort section (henceforth 'effort sections') in x into modeling segments (henceforth 'segments') of equal length. Each effort section runs from a "T"/"R" event to its corresponding "E"/"O" event. After chopping, airdas_segdata is called to get relevant segdata information for each segment.

When chopping the effort sections in segments of length seg.km, there are several possible scenarios:

  • The extra length remaining after chopping is greater than or equal to half of the target segment length (i.e. >= 0.5*seg.km): the extra length is assigned to a random portion of the effort section as its own segment (see Fig. 1a)

  • The extra length remaining after chopping is less than half of the target segment length (i.e. < 0.5*seg.km): the extra length is added to one of the (randomly selected) equal-length segments (see Fig. 1b)

  • The length of the effort section is less than or equal to the target segment length: the entire segment becomes a segment (see Fig. 1c)

  • The length of the effort section is zero: a segment of length zero. If there are more than two events (the "T"/R" and "E"/"O" events), the function throws a warning

Therefore, the length of each segment is constrained to be between one half and one and one half of seg.km (i.e. 0.5*seg.km <= segment length >=1.5*seg.km), and the central tendency is approximately equal to the target segment length. The only exception is when a continuous effort section is less than one half of the target segment length (i.e. < 0.5*seg.km; see Fig. 1c).

Note the PDF with Figs. 1a - 1c is included in the package, and can be found at: system.file("AirDAS_chop_equallength_figures.pdf", package = "swfscAirDAS")

'Randpicks' is a record of the random assignments that were made when chopping the effort sections into segments, and can be saved to allow users to recreate the same random allocation of extra km when chopping. The randpicks returned by this function is a data frame with two columns: the number of the effort section and the randpick value. Users should save the randpicks output to a CSV file, which then can be specified using the randpicks.load argument to recreate the same effort segments from x (i.e., using the same AirDAS data) in the future. Note that when saving with write.csv, users must specify row.names = FALSE so that the CSV file only has two columns. For an example randpicks file, see system.file("airdas_sample_randpicks.csv", package = "swfscAirDAS")

If the column dist_from_prev does not exist, the distance between subsequent events is calculated as described in airdas_effort