das_effort: Summarize DAS effort
In swfscDAS: Southwest Fisheries Science Center Shipboard DAS Data Processing
das_effort R Documentation
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
)
swfscDAS documentation built on Aug. 10, 2023, 9:06 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| das_effort | R Documentation |
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 |
... |
arguments passed to the specified chopping function,
such as |
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 |
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 |
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 |
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 |
event.touse |
character vector of events to use to determine
segment lengths; overrides |
num.cores |
Number of CPUs to over which to distribute computations.
Defaults to |
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 indas_sightforreturn.formatis "default"randpicks: see
das_chop_equallength;NULLif 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
)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.