Chop DAS data into approximately equal-length effort segments, averaging conditions by segment
das_chop_equallength(x, ...)# S3 method for data.frame
das_chop_equallength(x, ...)
# S3 method for das_df
das_chop_equallength(
x,
conditions,
seg.km,
randpicks.load = NULL,
distance.method = NULL,
num.cores = NULL,
...
)
an object of class das_df,
or a data frame that can be coerced to class das_df.
This data must be filtered for 'continuous effort sections;
see the Details section below
ignored
see das_effort
numeric; target segment length in kilometers
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
character; see das_effort.
Default is NULL since these distances should have already been calculated
see das_effort
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 das_effort for specifics)
randpicks: data frame with record of length allocations (see Details section above)
This function is intended to be called by das_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 "E";
see das_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 an "R" event to its corresponding "E" event.
After chopping, das_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 "B"/R" and "E" 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("DAS_chop_equal_figures.pdf", package = "swfscDAS")
'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 DAS 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("das_sample_randpicks.csv", package = "swfscDAS")
If the column dist_from_prev does not exist, the distance between
subsequent events is calculated as described in das_effort