Skip to contents

Display trip duration and value per unit effort

Usage

trip_dur_out(
  dat,
  project,
  start,
  end,
  units = "days",
  vpue = NULL,
  group = NULL,
  combine = TRUE,
  haul_count = TRUE,
  sub_date = NULL,
  filter_date = NULL,
  date_value = NULL,
  filter_by = NULL,
  filter_value = NULL,
  filter_expr = NULL,
  facet_by = NULL,
  type = "hist",
  bins = 30,
  density = TRUE,
  scale = "fixed",
  tran = "identity",
  format_lab = "decimal",
  pages = "single",
  remove_neg = FALSE,
  output = "tab_plot",
  tripID = NULL,
  fun.time = NULL,
  fun.numeric = NULL
)

Arguments

dat

Primary data containing information on hauls or trips. Table in FishSET database should contain the string `MainDataTable`.

project

String, name of project.

start

Date variable containing the start of vessel trip.

end

Date variable containing the end of vessel trip.

units

Time unit, defaults to "days". Options include "secs", "mins", "hours", "days", or "weeks".

vpue

Optional, numeric variable in dat for calculating value per unit effort (VPUE).

group

Optional, string names of variables to group by. By default, grouping variables are combined unless combine = FALSE and type = "freq_poly" (frequency polygon). combine = TRUE will not work when type = "hist" (histogram). Frequency polygon plots can use up to two grouping variables if combine = FALSE: the first variable is assigned to the "color" aesthetic and second to the "linetype" aesthetic.

combine

Logical, whether to combine the variables listed in group for plot.

haul_count

Logical, whether to include hauls per trip in table and/or plot (this can only be used if collapsing data to trip level using tripID. If data is already at trip level, add your haul frequency variable to vpue).

sub_date

Date variable used for subsetting, grouping, or splitting by date.

filter_date

The type of filter to apply to `MainDataTable`. To filter by a range of dates, use filter_date = "date_range". To filter by a given period, use "year-day", "year-week", "year-month", "year", "month", "week", or "day". The argument date_value must be provided.

date_value

This argument is paired with filter_date. To filter by date range, set filter_date = "date_range" and enter a start- and end-date into date_value as a string: date_value = c("2011-01-01", "2011-03-15").

To filter by period (e.g. "year", "year-month"), use integers (4 digits if year, 1-2 digits if referencing a day, month, or week). Use a vector if filtering by a single period: date_filter = "month" and date_value = c(1, 3, 5). This would filter the data to January, March, and May.

Use a list if using a year-period type filter, e.g. "year-week", with the format: list(year, period). For example, filter_date = "year-month" and date_value = list(2011:2013, 5:7) will filter the data table from May through July for years 2011-2013.

filter_by

String, variable name to filter `MainDataTable` by. the argument filter_value must be provided.

filter_value

A vector of values to filter `MainDataTable` by using the variable in filter_by. For example, if filter_by = "GEAR_TYPE", filter_value = 1 will include only observations with a gear type of 1.

filter_expr

String, a valid R expression to filter `MainDataTable` by.

facet_by

Variable name to facet by. Facetting by "year", "month", or "week" provided a date variable is added to sub_date.

type

The type of plot. Options include histogram ("hist", the default) and frequency polygon ("freq_poly").

bins

The number of bins used in histogram/freqency polygon.

density

Logical, whether densities or frequencies are used for histogram. Defaults to TRUE.

scale

Scale argument passed to facet_grid. Defaults to "fixed". Other options include "free_y", "free_x", and "free_xy".

tran

Transformation to be applied to the x-axis. A few options include "log", "log10", and "sqrt". See scale_continuous for a complete list.

format_lab

Formatting option for x-axis labels. Options include "decimal" or "scientific".

pages

Whether to output plots on a single page ("single", the default) or multiple pages ("multi").

remove_neg

Logical, whether to remove negative trip durations from the plot and table.

output

Options include 'table', 'plot', or 'tab_plot' (both table and plot, the default).

tripID

Column(s) that identify the individual trip.

fun.time

How to collapse temporal data. For example, min, mean, max. Cannot be sum for temporal variables.

fun.numeric

How to collapse numeric or temporal data. For example, min, mean, max, sum. Defaults to mean.

Value

trip_dur_out() calculates vessel trip duration given a start and end date, converts trip duration to the desired unit of time (e.g. weeks, days, or hours), and returns a table and/or plot. There is an option for calculating vpue (value per unit of effort) as well. The data can be filtered by date and/or by a variable.

filter_date specifies the type of date filter to apply--by date-range or by period. date_value should contain the values to filter the data by. To filter by a variable, enter its name as a string in filter_by and include the values to filter by in filter_value. If multiple grouping variables are given then they are combined into one variable unless combine = FALSE and

type = "freq_poly". No more than three grouping variables is recommended if pages = "single". Any variable in the dataset can be used for faceting, but "year", "month", and "week" are also available. Distribution plots can be combined on a single page or printed individually with pages.

See also

Examples

if (FALSE) {
trip_dur_out(pollockMainDataTable,
  start = "FISHING_START_DATE", end = "HAUL_DATE",
  units = "days", vpue = "OFFICIAL_TOTAL_CATCH", output = "plot",
  tripID = c("PERMIT", "TRIP_SEQ"), fun.numeric = sum, fun.time = min
)

}