Package 'FishSET'

Description

Aggregating function

Usage

agg_helper(
  dataset,
  value,
  period = NULL,
  group = NULL,
  within_group = NULL,
  fun = "sum",
  count = FALSE,
  format_tab = "decimal"
)

Arguments

Examples

## Not run: 

# total catch by port
agg_helper(pollockMainDataTable, value = "OFFICIAL_TOTAL_CATCH_MT", 
           group = "PORT_CODE", fun = "sum")

# count permits
agg_helper(pollockMainDataTable, value = "PERMIT", count = TRUE, fun = NULL)

# count permits by gear type
agg_helper(pollockMainDataTable, value = "PERMIT", group = "GEAR_TYPE",
           count = TRUE, fun = NULL)

# percent of total by gear type
agg_helper(pollockMainDataTable, value = "PERMIT", group = "GEAR_TYPE",
           count = TRUE, fun = "percent")
 
# within group percentage          
agg_helper(pollockMainDataTable, value = "OFFICIAL_TOTAL_CATCH_MT", 
           fun = "percent", group = c("PORT_CODE", "GEAR_TYPE"), 
           within_group = "PORT_CODE")

## End(Not run)

Description

Returns the Alternative Choice list from the FishSET database.

Usage

alt_choice_list(project, name = NULL)

Arguments

Description

Set x-axis labels to 45 degrees

Usage

angled_theme()

Description

Assign each observation in the primary dataset to a fishery management or regulatory zone. This function is primarily called by other functions that require zone assignment but can also be used on its own.

Usage

assignment_column(
  dat,
  project,
  spat,
  lon_dat,
  lat_dat,
  zoneID_spat,
  name = "ZoneID",
  closest_pt = FALSE,
  bufferval = NULL,
  lon_spat = NULL,
  lat_spat = NULL,
  hull_polygon = FALSE,
  epsg = NULL,
  log_fun = TRUE
)

Arguments

Details

Function uses the specified latitude and longitude from the primary dataset to assign each row of the primary dataset to a zone. Zone polygons are defined by the spatial dataset. Set hull_polygon to TRUE if spatial data is sparse or irregular. Function is called by other functions if a zone identifier does not exist in the primary dataset.

Value

Returns primary dataset with new assignment column.

Examples

## Not run: 
pollockMainDataTable <- 
     assignment_column(pollockMainDataTable, "pollock", spat = pollockNMFSSpatTable,
                       lon_dat = "LonLat_START_LON", lat_dat = "LonLat_START_LAT")

## End(Not run)

Description

Creates numeric variables divided into equal sized groups

Usage

bin_var(dat, project, var, br, name = "bin", labs = NULL, ...)

Arguments

Details

Function adds a new factor variable, labeled by name, to the primary dataset. The numeric variable is divided into equal sized groups if the length of br is equal to one and into intervals if the length of br is greater than one.

Value

Returns the primary dataset with binned variable added.

Examples

## Not run: 
 pollockMainDataTable <- bin_var(pollockMainDataTable, 'pollock', 'HAUL', 10, 'HAULCAT')
 pollockMainDataTable <- bin_var(pollockMainDataTable, 'pollock', 'HAUL', c(5,10), 'HAULCAT')

## End(Not run)

Description

Compare bycatch CPUE and total catch/percent of total catch for one or more species

Usage

bycatch(
  dat,
  project,
  cpue,
  catch,
  date,
  period = "year",
  names = NULL,
  group = NULL,
  sub_date = NULL,
  filter_date = NULL,
  date_value = NULL,
  filter_by = NULL,
  filter_value = NULL,
  filter_expr = NULL,
  facet_by = NULL,
  conv = "none",
  tran = "identity",
  format_lab = "decimal",
  value = "stc",
  combine = FALSE,
  scale = "fixed",
  output = "tab_plot",
  format_tab = "wide"
)

Arguments

Details

Returns a plot and/or table of the mean CPUE and share of total catch or raw count for each species entered. For optimal plot size in an R Notebook/Markdown document, we recommend including no more than four species. The order of variables in the cpue and catch arguments must be in the same order as in the names argument. The names argument is used to join the catch and cpue variables together.

Value

bycatch() compares the average CPUE and catch total/share of total catch between one or more species. 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. Only one grouping variable will be displayed; however, any number of variables can be combined by using combine = TRUE, but no more than three is recommended. For faceting, any variable in the dataset can be used, but "year" and "month" are also available provided a date variable is added to sub_date. Generally, no more than four species should be compared, and even fewer when faceting due to limited plot space. A list containing a table and plot are printed to the console and viewer by default. For optimal plot size in an R Notebook/Markdown document, use the chunk option fig.asp = 1.

Examples

## Not run: 
cpue(pollockMainDataTable, "myproject", xWeight = "f1Weight",
  xTime = "Hour", "f1_cpue"
)

bycatch(pollockMainDataTable, "myproject", 
        cpue = c("f1_cpue", "f2_cpue", "f3_cpue", "f4_cpue"),
        catch = c("f1", "f2", "f3", "f4"), date = "FISHING_START_DATE",
        names = c("fish_1", "fish_2", "fish_3", "fish_4"), period = "month",
        date_filter = "year", date_value = 2011, value = "stc", 
        output = "table")

## End(Not run)

Description

Calculate latitude and longitude variables (columns) containing the geographic centroid of each trip

Usage

calc_trip_centroid(dat, project, lon, lat, trip_id, weight_var = NULL)

Arguments

Details

This function computes the average longitude and latitude for each unique trip, as defined by the trip_id column. If weight_var is specified, the function calculates the weighted centroid.

Value

Returns the original data frame (dataset) with two new columns added: cent_lon (centroid longitude) and cent_lat (centroid latitude).

Examples

## Not run: 
# Assuming 'pollockMainDataTable' is a data frame

pollockMainDataTable <- calc_trip_centroid(
  dat = pollockMainDataTable, 
  project = 'pollock', 
  lon = 'LonLat_START_LON',
  lat = 'LonLat_START_LAT',
  trip_id = "TRIP_ID",
  weight_var = NULL
)

## End(Not run)

Description

Calculates the total distance for a fishing trip and adds it as a new column to the dataset.

Usage

calc_trip_distance(
  name = "trip_distance",
  project,
  dat,
  port,
  trip_id,
  haul_order,
  starting_port,
  return_port,
  start_haul_lat,
  start_haul_lon,
  end_haul_lat,
  end_haul_lon,
  distance_unit = "miles",
  a = 6378137,
  f = 1/298.257223563
)

Arguments

Details

This function calculates the total distance traveled during a fishing trip by summing its four key segments: 1. Distance from the departure port to the start of the first haul. 2. The cumulative distance covered *within* each haul. 3. The cumulative distance traveled *between* consecutive hauls. 4. The final distance from the end of the last haul to the return port.

The function uses a vectorized approach with the 'dplyr' package for efficiency and relies on 'geosphere::distGeo' for accurate geodesic distance calculations based on the WGS84 ellipsoid model.

Value

Returns the main data table with a new variable for trip distance.

Examples

## Not run: 
main_data_with_distance <- calc_trip_distance(
  name = "total_trip_miles",
  project = "my_project",
  dat = main_data,
  port = port_data,
  trip_id = "TRIP_ID",
  haul_order = "HAUL_NUMBER",
  starting_port = "DEPARTURE_PORT_NAME",
  return_port = "LANDING_PORT_NAME",
  start_haul_lat = "START_LATITUDE",
  start_haul_lon = "START_LONGITUDE",
  end_haul_lat = "END_LATITUDE",
  end_haul_lon = "END_LONGITUDE",
  distance_unit = "miles"
)

## End(Not run)

Description

First stage regression model for catch.

Usage

catch_lm(
  dat,
  project,
  catch.formula,
  zoneID = NULL,
  exp.name = NULL,
  new.name = NULL,
  date,
  output = "matrix"
)

Arguments

Details

catch_lm() can merge an expected catch matrix into the primary dataset before running the linear model. This is done using by passing exp.name and zoneID to merge_expected_catch() and is for convenience; users can do this separately using merge_expected_catch() if desired, just make sure to leave exp.name empty before running catch_lm(). Merging expected catch in a separate step is useful for creating tables and plots before running a first stage linear regression.

Value

catch_lm() has two output options: dataset and matrix. When output == 'dataset', the primary dataset will be returned with the fitted values from the model added as a new column. The new column is named using new.name.

When output == 'matrix' an expected catch matrix is created and saved to the FishSET DB expected catch list (it is not outputted to the console). There are two ways to create an expected catch matrix: by using an existing expected catch matrix in catch.formula, or by using a zone-identifier column (i.e. zoneID) in the catch.formula. For example, if you have created an expected catch matrix named 'user1' using create_expectations(), catch.formula could equal catch ~ vessel_length * user1. In this case exp.name would equal 'user1'. Alternatively, you could create an expected catch matrix by specifying catch.formula as catch ~ vessel_length * zone. In this case, exp.name = NULL and zoneID = 'zone'.

See Also

merge_expected_catch()

Description

Save the unique centroid values from the primary table to the FishSET Database. Use this function if zone ID and centroid longitude/latitude are included in the primary table.

Usage

centroid_to_fsdb(
  dat,
  spat.name = NULL,
  project,
  zoneID,
  cent.lon,
  cent.lat,
  type = "zone"
)

Arguments

Details

In certain cases, the user may have the necessary spatial variables to run a discrete choice model included in the primary table when uploaded to FishSET, and does not need a spatial table to assign observations to zones or find centroids (e.g. by using create_centroid()). However, a centroid table table must be saved to the FishSET Database if a centroid option is used to define alternative choice (see create_alternative_choice()). cent_to_fsdb() allows users to save a zonal or fishing centroid table provided they have the required variables: a zone ID (zoneID), a centroid longitude (cent.lon), and a centroid latitude (cent.lat) column.

Description

View data class for each variable and call appropriate functions to change data class as needed.

Usage

change_class(dat, project, x = NULL, new_class = NULL, save = FALSE)

Arguments

Details

Returns a table with data class for each variable in dat and changes variable classes. To view variable classes run the function with default settings, specifying only dat and project. If variable class should be changed, run the function again, specifying the variable(s) (x) to be changed and the new_class(es) (new_class). Set save to TRUE to save modified data table.

Value

Table with data class for each variable and the working data with modified data class as specified.

Examples

## Not run: 
#View table without changing class or saving
change_class(pollockMainDataTable, "myproject")

#Change class for a single variable and save data table to FishSET database
change_class(pollockMainDataTable, "myproject", x = "HAUL", new_class = 'numeric', save=TRUE)

#Change class for multiple variables and save data table to FishSET database
change_class(pollockMainDataTable, "myproject", x = c("HAUL","DISEMBARKED_PORT"),
 new_class = c('numeric', 'factor'), save=TRUE)

## End(Not run)

Description

Converts spatial data to a sf object

Usage

check_spatdat(spatdat, lon = NULL, lat = NULL, id = NULL)

Arguments

Details

This function checks whether spatdat is a sf object and attempts to convert it if not. It also applies clean_spat which fixes certain spatial issues such as invalid or empty polygons, whether a projected CRS is used (converts to WGS84 if detected), and if longitude should be shifted to Pacific view (0-360 format) to avoid splitting the Alaska region during plotting.

Description

A helper function used to display the names of currently saved closure scenarios.

Usage

close_names(project)

Arguments

Details

To retrieve the complete closure scenario file, use get_closure_scenario.

Description

Creates a new spatial dataset that merges regulatory zones with closure areas.

Usage

combine_zone(spat, closure, grid.nm, closure.nm, recast = TRUE)

Arguments

Details

To combine zones with closure areas, this function performs the following steps:

1. Create the union of the closure area

2. Take the difference between the closure union and the zone file

3. Take the intersection of zone and the closure union

4. Combine the difference and intersection objects into one spatial dataframe

5. Assign new zone IDs to intersecting polygons

The result is a single spatial dataset containing all polygons from both spat and closure with overlapping (intersecting) polygons receiving new IDs (see new_zone_id). This allows users to partially close regulatory zones during the model design stage.

See Also

recast_multipoly new_zone_id

Description

Returns TRUE if confidentiality cache file is found in the project output folder.

Usage

confid_cache_exists(project)

Arguments

Examples

## Not run: 
confid_cache_exists("pollock")

## End(Not run)

Description

Add catch per unit effort (CPUE) or revenue per unit effort variable to the primary dataset. Catch should be a weight variable but can be a count. Effort should be in a duration of time, such as days, hours, or minutes.

Usage

cpue(dat, project, xWeight = NULL, xTime, price = NULL, name = NULL)

Arguments

Details

Creates the catch or revenue per unit effort variable. Catch variable should be in weight (lbs, mts). Effort variable should be a measurement of duration in time. New variable is added to the primary dataset with the column name defined by the name argument. CPUE for individual species should be calculated separately.

Value

Returns primary dataset with CPUE variable added.

Examples

## Not run: 
pollockMainDataTable <- cpue(pollockMainDataTable, 'pollock', 
                             xWeight = 'OFFICIAL_TOTAL_CATCH_MT', 
                             xTime = 'DURATION_IN_MIN', name = 'cpue')

## End(Not run)

Description

Required step. Creates a list identifying how alternative fishing choices should be defined. Output is saved to the FishSET database. Run this function before running models. dat must have a zone assignment column (see assignment_column()). In certain cases a centroid table must be saved to the FishSET Database, see occasion_var for details.

Usage

create_alternative_choice(
  dat,
  project,
  alt_name = NULL,
  zoneID,
  occasion = "zonal centroid",
  occasion_var = NULL,
  alt_var = "zonal centroid",
  min_haul = 0,
  spatname = NULL,
  spatID = NULL,
  outsample = FALSE
)

Arguments

Details

Defines the alternative fishing choices. These choices are used to develop the matrix of distances between observed and alternative fishing choices (where they could have fished but did not). The distance matrix is calculated by the format_model_data() function. occasion defines the observed fishing location and alt_var the alternative fishing location. occasion_var identifies an ID column or set of lon-lat variables needed to create the distance matrix.

Parts of the alternative choice list are pulled by create_expectations(), format_model_data(), and the model run fishset_fit()) functions. These output include choices of which variable to use for catch and which zones to include in analyses based on a minimum number of hauls per trip within a zone. Note that if the alternative choice list is modified, the create_expectations() and format_model_data() functions should also be updated before rerunning models.

Value

Function saves a list of alternative choice matrices to the FishSET database as projectAlternativeChoice. The list includes the alternative choice list from the user-defined choices. Multiple alternative choice cases can be added to the list by specifying unique names. The list is automatically saved to the FishSET database and is called in format_model_data.

Description

Create a zonal or fishing centroid table. The centroid can be joined with the primary data if output = "dataset". The centroid table is automatically saved to the FishSET Database.

Usage

create_centroid(
  spat = NULL,
  dat = NULL,
  project,
  spatID = NULL,
  zoneID = NULL,
  lon.dat = NULL,
  lat.dat = NULL,
  weight.var = NULL,
  type = "zonal centroid",
  names = NULL,
  cent.name = NULL,
  output = "dataset"
)

Arguments

Description

Adds a variable for distance between two points to the primary dataset. There are two versions of this function. The difference between the two versions is how additional arguments specific to start and end locations are added. This version requires only five arguments to be specified before running. Additional arguments specific to identifying the lat/lon of start or end points are added through prompts. This function is designed for an interactive session. The create_dist_between_for_gui function requires all necessary arguments to be specified before running and is best used in a non-interactive session. Both versions of the distance between function require that the start and end points be different vectors. If the start or ending points are from a port then PortTable must be specified to obtain lat/lons. If the start or ending points are the center of a fishing zone or area then spat, lon.dat, lat.dat, cat, lon.spat, and lat.spat must be specified to obtain latitude and longitude.

Usage

create_dist_between(
  dat,
  project,
  start,
  end,
  units = c("miles", "meters", "km", "midpoint"),
  zoneid = NULL,
  name = "distBetween"
)

Arguments

Details

Additional arguments.
Further arguments are required to identify the latitude and longitude of the starting or ending location if start or end is defined as zonal centroid or a column from primary dataset containing port information, such as departing or embarking port. Prompts will appear asking for required arguments.

Port arguments required:

Centroids arguments required:

Value

Returns primary data set with distance between variable.

Examples

## Not run: 
pollockMainDataTable <- create_dist_between(pollockMainDataTable, 'pollock', 'centroid',
 'EMBARKED_PORT', units = 'miles', 'DistCentPort')

pollockMainDataTable <- create_dist_between(pollockMainDataTable, 'pollock', c('LonLat_START_LON',
 'LonLat_START_LAT'), c('LonLat_END_LON','LonLat_END_LAT'), units='midpoint', 'DistLocLock')
 
pollockMainDataTable <- create_dist_between(pollockMainDataTable, 'pollock', 'DISEMBARKED_PORT',
  'EMBARKED_PORT', units='meters', 'DistPortPort')

## End(Not run)

Description

Adds distance between two points to the primary data set. There are two versions of this function. The difference between the two versions is how additional arguments specific to start and end locations are added. This version requires all necessary arguments to be specified before running and is best used in a non-interactive session. The create_dist_between version requires only five arguments to be specified before running. Additional arguments specific to identifying the lat/long of start or end points are added through prompts. This function is designed for an interactive session. Both versions of the distance between function require that the start and end points be different vectors. If the start or ending points are from a port, then PortTable must be specified to obtain lat/lons. If the start or ending points are the center of a fishing zone or area then spat, lon.dat, lat.dat, cat, lon.spat, and lat.spat must be specified to obtain latitude and longitude.

Usage

create_dist_between_for_gui(
  dat,
  project,
  start = c("lat", "lon"),
  end = c("lat", "lon"),
  units,
  name = "DistBetwen",
  portTable = NULL,
  zoneid,
  spat = NULL,
  lon.dat = NULL,
  lat.dat = NULL,
  cat = NULL,
  lon.spat = NULL,
  lat.spat = NULL
)

Arguments

Value

Primary data set with distance between points variable added.

Description

Create duration of time variable based on start and ending dates in desired temporal units.

Usage

create_duration(
  dat,
  project,
  start,
  end,
  units = c("week", "day", "hour", "minute"),
  name = "create_duration"
)

Arguments

Details

Calculates the duration of time between two temporal variables based on defined time unit. The new variable is added to the dataset. A duration of time variable is required for other functions, such as cpue.

Value

Returns primary dataset with duration of time variable added.

Examples

## Not run: 
pollockMainDataTable <- create_duration(pollockMainDataTable, 'pollock', 'TRIP_START', 'TRIP_END',
  units = 'minute', name = 'TripDur')

## End(Not run)

Description

Create expected catch or expected revenue matrix. The matrix is required for the conditional logit model. Multiple matrices (with unique names) can be saved in a project.

Usage

create_expectations(
  dat,
  project,
  name,
  alt_name,
  catch,
  price = NULL,
  define_group = NULL,
  temp_var = NULL,
  temporal = "daily",
  calc_method = "standardAverage",
  temp_window = 7,
  day_lag = 1,
  year_lag = 0,
  empty_catch = NULL,
  empty_expectation = 1e-04,
  dummy_exp = FALSE,
  weight_avg = FALSE,
  outsample = FALSE
)

Arguments

Details

Function creates an expectation of catch or revenue for alternative fishing zones (zones where they could have fished but did not). The output is saved to the FishSET database and called by the format_model_data function. create_alternative_choice must be called first as observed catch and zone inclusion requirements are defined there.
The primary choices are whether to treat data as a fleet or to group the data (define_group) and the time frame of catch data for calculating expected catch. Catch is averaged along a daily or sequential timeline (temporal) using a rolling average. temp_window and day_lag determine the window size and temporal lag of the window for averaging. Use temp_obs_table before using this function to assess the availability of data for the desired temporal moving window size. Sparse data is not suited for shorter moving window sizes. For very sparse data, consider setting temp_var to NULL and excluding temporal patterns in catch.
Empty catch values are considered to be times of no fishing activity. Values of 0 in the catch variable are considered times when fishing activity occurred but with no catch. These points are included in the averaging and dummy creation as points in time when fishing occurred.

Value

Function saves a list of expected catch matrices to the FishSET database as projectExpectedCatch. The list includes the expected catch matrix from the user-defined choices. Multiple expected catch cases can be added to the list by specifying unique names. The list is automatically saved to the FishSET database and is called in format_model_data. The expected catch output does not need to be loaded when defining or running the model.

Examples

## Not run: 
create_expectations(pollockMainDataTable, "pollock", "exp1", "OFFICIAL_TOTAL_CATCH_MT",
  price = NULL, define_group = "fleet", temp_var = "DATE_FISHING_BEGAN",
  temporal = "daily", calc_method = "standardAverage", 
  empty_catch = "allCatch", empty_expectation = 0.0001, temp_window = 4,
  day_lag = 2, year_lag = 0, dummy_exp = FALSE, 
  weight_avg = FALSE, outsample = FALSE
)

## End(Not run)

Description

Calculates latitude and longitude of the haul midpoint and adds two variables to the primary data set: the midpoint latitude and the midpoint longitude.

Usage

create_mid_haul(
  dat,
  project,
  start = c("lon", "lat"),
  end = c("lon", "lat"),
  name = "mid_haul"
)

Arguments

Details

Each row of data must be a unique haul. Requires a start and end point for each observation.

Value

Returns primary dataset with two new variables added: latitude and longitude of haul midpoint.

Examples

## Not run: 
pollockMainDataTable <- create_mid_haul(pollockMainDataTable, 'pollock', 
    start = c('LonLat_START_LON', 'LonLat_START_LAT'), 
   end = c('LonLat_END_LON', 'LonLat_END_LAT'), name = 'mid_haul')

## End(Not run)

Description

Create fishery season identifier variable

Usage

create_seasonal_ID(
  dat,
  project,
  seasonal.dat,
  use.location = c(TRUE, FALSE),
  use.geartype = c(TRUE, FALSE),
  sp.col,
  target = NULL
)

Arguments

Details

Uses a table of fishery season dates to create fishery season identifier variables. Output is a SeasonID variable and/or multiple SeasonID*fishery variables. If fishery season dates vary by location or gear type, then use.location and use.geartype should be TRUE.

The function matches fishery season dates provided in seasonal.dat to the earliest date variable in dat. The 'seasonID' variable is a vector of fishery seasons whereas the 'SeasonID*fishery' variables are 1/0 depending on whether the fishery was open on the observed date.

If target is not defined, then each row of seasonID is defined as the earliest fishery listed in seasonal.dat for which the fishery season date encompasses the date variable in the primary dataset. If target fishery is defined, then 'SeasonID' is defined by whether the target fishery is open on the date in the primary dataset or a different fishery. The vector is filled with 'target' or 'other'.

'SeasonID*fishery' variables are a 1/0 seasonID vector for each fishery (labeled by seasonID and fishery) where 1 indicates the dates for a given row in the primary data table fall within the fishery dates for that fishery.

Value

Returns the primary dataset with the variable SeasonID, or a series of variables identifying by the individual fisheries included (seasonID*fishery).

Examples

## Not run: 
pcodMainDataTable <- create_seasonal_ID("pcodMainDataTable", seasonal_dat,
  use.location = TRUE, use.geartype = TRUE, sp.col = "SPECIES", target = "POLLOCK"
)

## End(Not run)

Description

Creates a new variable based on the arithmetic operation between two variables. Function is useful for creating rate variables or the summation of two related variables.

Usage

create_var_num(dat, project, x, y, method, name = "create_var_num")

Arguments

Details

Creates a new numeric variable based on the defined arithmetic expression method. New variable is added to the primary dataset.

Value

Returns primary dataset with new variable added.

Examples

## Not run: 
pollockMainDataTable <- create_var_num(pollockMainDataTable, 'pollock', x = 'HAUL_CHINOOK',
    y = 'HAUL_CHUM', method = 'sum', name = 'tot_salmon')

## End(Not run)

Description

Used to convert spatial data with no spatial class to a sf object. This is useful if the spatial data was read from a non-spatial file type, e.g. a CSV file.

Usage

dat_to_sf(dat, lon, lat, id, cast = "POLYGON", multi = FALSE, crs = 4326)

Arguments

Description

Check primary data for common data quality issues, such as NaNs, NAs, outliers, unique rows, and empty variables.

Usage

data_check(dat, project, x)

Arguments

Details

Prints summary stats for all variables in dat. Prints column names that contain NaNs or NAs. Checks for outliers for specified variable x. Checks that all column names are unique, whether any columns in dat are empty, whether each row is a unique choice occurrence at the haul or trip level, that data for either lat/lon or fishing area are included. The function is also called by other functions.

Examples

## Not run: 
data_check(pcodMainDataTable, "OFFICIAL_TOTAL_CATCH_MT")

## End(Not run)

Description

Helper function that can read data from file, from FishSET DB, or a dataframe in the working environment. Used for data upload functions: load_maindata, load_port, load_aux, load_grid, load_spatial.

Usage

data_upload_helper(dat, type, ...)

Arguments

Examples

## Not run: 
dataset <- data_upload_helper(dat, type = "main")

## End(Not run)

Description

Check that latitude and longitude are in decimal degrees and the variable sign is correct. Correct lat/lon if required.

Usage

degree(
  dat,
  project,
  lat = NULL,
  lon = NULL,
  latsign = FALSE,
  lonsign = FALSE,
  replace = TRUE
)

Arguments

Details

First checks whether any variables containing 'lat' or 'lon' in their names are numeric. Returns a message on results. To convert a variable to decimal degrees, identify the lat or lon variable(s) and set replace = TRUE. To change the sign, set latsign (for lat) or lonsign (for lon = TRUE. FishSET requires that latitude and longitude be in decimal degrees.

Value

Returns the primary dataset with the latitudes and longitudes converted to decimal degrees if replace = TRUE or if Changing the sign. Otherwise, a message indicating whether selected longitude and latitude variables are in the correct format.

Examples

## Not run: 
# check format
degree(pollockMainDataTable, 'pollock', lat = 'LatLon_START_LAT',
       lon = 'LatLon_START_LON')

# change signs and convert to decimal degrees
pollockMainDataTable <- degree(pollockMainDataTable, 'pollock', 
                               lat = 'LatLon_START_LAT', 
                               lon = 'LatLon_START_LON', latsign = FALSE, 
                               lonsign = FALSE, replace = TRUE)

## End(Not run)

Description

Delete table meta data or project meta file

Usage

delete_meta(project, tab.name = NULL, delete_file = FALSE)

Arguments

Description

Creates a kernel density estimate, empirical cumulative distribution function, or cumulative distribution function plot of selected variable. Grouping, filtering, and several plot options are available.

Usage

density_plot(
  dat,
  project,
  var,
  type = "kde",
  group = NULL,
  combine = TRUE,
  date = NULL,
  filter_date = NULL,
  date_value = NULL,
  filter_by = NULL,
  filter_value = NULL,
  filter_expr = NULL,
  facet_by = NULL,
  conv = "none",
  tran = "identity",
  format_lab = "decimal",
  scale = "fixed",
  bw = 1,
  position = "identity",
  pages = "single"
)

Arguments

Details

The data can be filtered by date or by variable (see filter_date and filter_by). If type contains "kde" or "all" then grouping variables are automatically combined. Any variable in dat can be used for faceting, but "year", "month", or "week" are also available if date is provided.

Value

denstiy_plot() can return up to three plots in a single call. When pages = "single" all plots are combined and stacked vertically. pages = "multi" will return separate plots.

Examples

## Not run: 

density_plot(pollockMainDataTable, "pollock", var = "OFFICIAL_TOTAL_CATCH_MT",
             type = c("kde", "ecdf"))

# facet 
density_plot(pollockMainDataTable, "pollock", var = "OFFICIAL_TOTAL_CATCH_MT",
             type = c("kde", "ecdf"), facet_by = "GEAR_TYPE")

# filter by period
density_plot(pollockMainDataTable, "pollock", var = "OFFICIAL_TOTAL_CATCH_MT", 
             type = "kde", date = "FISHING_START_DATE", filter_date = "year-month", 
             filter_value = list(2011, 9:11))

## End(Not run)

Description

Create dummy matrix from a coded ID variable

Usage

dummy_matrix(dat, project, x)

Arguments

Details

Creates a dummy matrix of 1/0 with dimensions [(number of observations in dataset) x (number of factors in x)] where each column is a unique factor level. Values are 1 if the value in the column matches the column factor level and 0 otherwise.

Examples

## Not run: 
PortMatrix <- dummy_matrix(pollockMainDataTable, 'pollock', 'PORT_CODE')

## End(Not run)

Description

Create a binary vector from numeric, date, and character or factor vectors.

Usage

dummy_num(dat, project, var, value, opts = "more_less", name = "dummy_num")

Arguments

Details

For date variables, the dummy variable is defined by a date (year) and may be either year x versus all other years ("x_y") or before vs after year x ("more_less"). Use this function to create a variable defining whether or not a policy action had been implemented.
Example: before vs. after a 2008 amendment:
dummy_num('pollockMainDataTable', 'Haul_date', 2008, 'more_less', 'amend08')

For factor variables, both choices in opts compare selected factor level(s) against all other factor levels.
Example: Fishers targeting pollock vs. another species:
dummy_num('pollockMainDataTable', 'GF_TARGET_FT', c('Pollock - bottom', 'Pollock - midwater'), 'x_y', 'pollock_target')

For numeric variables, value can be a single number or a range of numbers. The dummy variable is the selected value(s) against all others (x_y) or less than the selected value versus more than the selected value (more_less). For more_less, the mean is used as the critical value if a range of values is provided.

Value

Returns primary dataset with dummy variable added.

Examples

## Not run: 
pollockMainDataTable <- dummy_num(pollockMainDataTable, 'pollock', 'Haul_date', 2008, 
  'more_less', 'amend80')

## End(Not run)

Description

Check for and remove empty variables from dataset. Empty variables are columns in the data that contain all NAs and/or empty strings.

Usage

empty_vars_filter(dat, project, remove = FALSE)

Arguments

Details

Function checks for empty variables and prints an outcome message to the console. If empty variables are present and remove = TRUE, then empty variables will be removed from the dataset. Empty variables are columns in the dataset that contain all NAs or empty strings.

Value

Returns the dataset with empty variables removed if remove = TRUE.

Examples

## Not run: 
# check for empty vars
empty_vars_filter(pollockMainDataTable)

# remove empty vars from data
mod.dat <- empty_vars_filter(pollockMainDataTable, 'pollock', remove = TRUE)

## End(Not run)

Description

Return the names of expected catch matrices saved to the FishSET database.

Usage

exp_catch_names(project)

Arguments

Description

Returns the Expected Catch list from the FishSET database.

Usage

expected_catch_list(project, name = NULL)

Arguments

Description

Remove rows based on filter expressions defined in 'filterTable'

Usage

filter_dat(dat, project, exp, filterTable = NULL)

Arguments

Details

Filter data frame based on a predefined filter expression from filter_table or a filter expression. We recommend creating a filter table using filter_table so that filter expressions are stored and easily accessed in the future.

Value

Filtered data frame

Examples

## Not run: 
newdat <- filter_dat(pcodMainDataTable, 'pcod', exp = 3, 
                     filterTable = 'pcodfilterTable01012011')
                     
newdat <- filter_dat(pcodMainDataTable, 'pcod', 
                     exp = 'PERFORMANCE_Code == 1', filteTable = NULL)
                     
newdat <- filter_dat(pcodMainDataTable, "pcod", exp = "SEASON == 'A'",
                     filterTable = NULL)

## End(Not run)

Description

Define and store filter expressions

Usage

filter_table(dat, project, x, exp)

Arguments

Details

This function allows users to define and store data filter expressions which can then be applied to the data. The filter table will be saved in the FishSET database under the project name and 'filterTable'. The new filter functions are added each time the function is run and the table is automatically updated in the FishSET database. The function call will be logged in the log file.

Value

Filter expressions saved as a table to the FishSET database.

Examples

## Not run: 
filter_table(pcodMainDataTable, 'pcod', x = 'PERFORMANCE_Code',
             exp = 'PERFORMANCE_Code == 1')

## End(Not run)

Description

Identify geographic centroid of fishery management or regulatory zone

Usage

find_centroid(
  spat,
  project,
  spatID,
  lon.spat = NULL,
  lat.spat = NULL,
  cent.name = NULL,
  log.fun = TRUE
)

Arguments

Details

Returns the geographic centroid of each area/zone in spat. The centroid table is saved to the FishSET database. Function is called by the create_alternative_choice and create_dist_between functions.

Value

Returns a data frame where each row is a unique zone and columns are the zone ID and the latitude and longitude defining the centroid of each zone.

Description

Create fishing or weighted fishing centroid

Usage

find_fishing_centroid(
  dat,
  project,
  zoneID,
  weight.var = NULL,
  lon.dat,
  lat.dat,
  names = NULL,
  cent.name = NULL,
  log.fun = TRUE
)

Arguments

Details

Fishing centroid defines the centroid by mean latitude and longitude of fishing locations in each zone. Weighted centroid defines the centroid by the mean latitude and longitude of fishing locations in each zone weighted by the weight.var. The fishing and weighted centroid variables can be used anywhere latitude/longitude variables appear. Each observation in dat must be assigned to a fishery or regulatory area/zone. If the zone identifier exists in dat and is not called 'ZoneID', then zoneID should be the variable name containing the zone identifier. If a zone identifier variable does not exist in dat, spat must be be specified and zoneID must be zone identifier in spat. The assignment_column function will be run and a zone identifier variable added to dat.

Value

Returns primary dataset with fishing centroid and, if weight.var is specified, the weighted fishing centroid.

Description

Compare imported data table to the previously saved version of the data table

Usage

fishset_compare(x, y, compare = c(TRUE, FALSE), project)

Arguments

Details

Function is optional. It is designed to check for consistency between versions of the same data frame so that the logged functions can be used to rerun the previous analysis on the updated data. The column names, including spelling and capitalization, must match the previous version to use the logged functions to rerun code after data has been updated (i.e., new year of data). The function is called by the data import functions (load_maindata, load_port, load_aux, load_grid). Set the compare argument to TRUE to compare column names of the new and previously saved data tables. The new data tables will be saved to the FishSET database if column names match. Set the compare argument to FALSE if no previous versions of the data table exist in the FishSET database. No comparison will be made and the new file will be saved to the database.

Description

Performs k-fold cross-validation on a fitted FishSET model to evaluate out-of-sample predictive performance. Bypasses formula parsing by directly subsetting the design matrix.

Usage

fishset_cv(
  project,
  base_model_name,
  k = 5,
  seed = 42,
  distribution = NULL,
  ...
)

Arguments

Value

A list containing the average out-of-sample accuracy, log-likelihood, PAPE, AIC, fold details, and estimated coefficients across folds.

Examples

## Not run: 
# Standard logit
cv_results <- fishset_cv(
  project = "MyProject",
  base_model_name = "clogit_design"
)

# EPM - normal catch function
cv_epm_results <- fishset_cv(
  project = "MyProject",
  base_model_name = "epm_design",
  distribution = "normal"
)

## End(Not run)

Description

Constructs the design object required for discrete choice model fitting within the FishSET framework. This function parses the model formula, validates the formatted data, and generates the design matrix (X) and choice vector (y). It handles both alternative-specific variables and trip- or haul-specific variables (automatically creating interactions with zone constants). The resulting design object is the primary input for the fishset_fit function, which performs the parameter estimation.

Usage

fishset_design(
  formula,
  project,
  model_name,
  formatted_data_name,
  unique_obs_id,
  zone_id,
  catch_formula = NULL,
  price_var = NULL,
  scale = FALSE,
  overwrite = FALSE
)

Arguments

Details

The resulting design object is saved as a compressed file in the 'Models/ModelDesigns' folder, which is located inside the project folder.

Value

A list object of class 'fishset_design' containing the design matrices, choice vector, and metadata. The list is saved as a compressed file in the project folder.

Examples

## Not run: 
# 1. Standard Conditional Logit
# "chosen" is ALWAYS the response, "expected_catch" and "distance" are site attributes.
fishset_design(
  formula = chosen ~ expected_catch + distance,
  project = "MyProject",
  model_name = "clogit_model1",
  formatted_data_name = "my_formatted_data",
  unique_obs_id = "haul_id",
  zone_id = "zone_id"
)

# 2. Zonal Logit with Alternative-Specific Constants (ASCs)
# Add the zone_id variable ("zone_id") to the formula to generate fixed effects.
fishset_design(
  formula = chosen ~ expected_catch + distance + zone_id,
  project = "MyProject",
  model_name = "zonal_logit_model1",
  formatted_data_name = "my_formatted_data",
  unique_obs_id = "haul_id",
  zone_id = "zone_id",
  scale = TRUE
) 

# 3. Zonal Logit with trip- or haul-specific variables
# Add the variable that does not vary across zones (e.g., vessel length) after the pipe ("|").
fishset_design(
  formula = chosen ~ expected_catch + distance | vessel_length,
  project = "MyProject",
  model_name = "zonal_logit_model2",
  formatted_data_name = "my_formatted_data",
  unique_obs_id = "haul_id",
  zone_id = "zone_id",
  scale = TRUE
)

# 4. Expected profit model - normal distribution
# The expected catch (catch_var in this example) does not vary across zones in this 
# example (e.g., vessel length).
fishset_design(
  formula = chosen ~ distance | catch_var,
  project = "MyProject",
  model_name = "epm1",
  formatted_data_name = "my_formatted_data",
  unique_obs_id = "haul_id",
  zone_id = "ZoneID",
  catch_formula = actual_catch ~ catch_var:ZoneID,
  price_var = "price_var",
  scale = TRUE
) 

## End(Not run)

Description

Estimates parameters for logit models using the RTMB (R Template Model Builder) framework. This function takes a design object created by fishset_design, optimizes the negative log-likelihood, and returns a comprehensive list of model results, fit statistics, and diagnostics.

Usage

fishset_fit(
  project,
  model_name,
  fit_name = NULL,
  distribution = NULL,
  robust = FALSE,
  return_full_prob_mat = FALSE,
  se_calc = TRUE,
  overwrite = FALSE,
  ...
)

Arguments

Value

A list object of class "fishset_fit" containing, this list is also saved in the project database:

coefficients

Named vector of estimated parameters.

coef_table

Data frame with Estimates, Std. Errors, Z-values, and P-values.

vcov

Variance-covariance matrix of the parameters.

opt

Raw optimization output from nlminb.

logLik

The maximum log-likelihood value of the fitted model.

null_logLik

The log-likelihood of a null model (random guessing).

pseudo_R2

McFadden's Pseudo-R-squared.

AIC, AICc, BIC

Information criteria for model comparison.

accuracy

The proportion of observations where the model assigned the highest probability to the actual choice.

fitted_values

Vector of predicted probabilities for the chosen alternatives.

prob_matrix

Matrix of predicted probabilities for all alternatives (N_obs x J_alts).

diagnostics

A list containing the Hessian, gradients, eigenvalues, and condition number.

See Also

fishset_design for creating the input design object.

Examples

## Not run: 
# 1. Standard fit using default settings
# This uses the design object named "clogit_design" saved in "MyProject"
fit_result <- fishset_fit(
  project = "MyProject",
  model_name = "clogit_design"
)
  
# 2. Advanced fit with custom optimization settings and start values
# 'control' and 'start_values' are passed via the '...' argument
fit_custom <- fishset_fit(
  project = "MyProject",
  model_name = "clogit_design",
  fit_name = "clogit_custom_fit",
    
  # Pass control list to nlminb (e.g., increase max iterations, turn on tracing)
  control = list(eval.max = 5000, iter.max = 5000, trace = 1),
    
  # Pass initial start values for the parameters (e.g., for 2 predictors)
  start_values = c(0.5, -0.2)
)
  
# 3. EPM - normal catch function
epm_fit <- fishset_fit(project = project,
  model_name = "epm1",
  fit_name = "epm_fit1",
  distribution = "normal"
)

## End(Not run)

Description

Performs the Hausman-McFadden specification test to check the Independence of Irrelevant Alternatives (IIA) assumption for logit models.

Usage

fishset_iia_test(
  project,
  model_name,
  fit_name = NULL,
  omitted_zones = NULL,
  robust = FALSE,
  ...
)

Arguments

Details

The test compares the estimates from a full model (fitted on all alternatives) against a restricted model (fitted on a subset of alternatives). If the IIA assumption holds, the coefficients common to both models should not be systematically different.

A significant p-value (typically < 0.05) indicates that the IIA assumption has been violated, suggesting that the logit model may be misspecified (e.g., unobserved correlation between alternatives). Note: Alternative-Specific Constants (ASCs) are excluded from the statistical comparison to prevent reference-level shift bias.

Value

A list object of class "fishset_iia" containing:

statistic

The Hausman chi-squared test statistic.

p_value

The p-value of the test.

df

Degrees of freedom (number of coefficients compared).

full_coefs

Coefficients from the full model (subsetted for comparison).

restricted_coefs

Coefficients from the restricted model.

description

Text interpretation of the result.

Description

Returns a data frame containing all tables from each project by project name and table type.

Usage

fishset_tables(project = NULL)

Arguments

Examples

## Not run: 
# return all tables for all projects
fishset_tables()

# return all tables for a specific project
fishset_tables("pollock")

## End(Not run)

Description

Add a fleet ID column to the primary data using a fleet table (see fleet_table for details).

Usage

fleet_assign(
  dat,
  project,
  fleet_tab,
  assign = NULL,
  overlap = FALSE,
  format_var = "string"
)

Arguments

Value

Returns the primary dataset with added fleet variable(s).

See Also

fleet_table

Examples

## Not run: 
fleet_assign(pollockMainDataTable, 'pollock', fleet_tab = 'pollockFleetTable', 
             overlap = TRUE)

## End(Not run)

Description

fleet_table saves a table of fleet expression to the FishSET database which can then be applied to a dataset with fleet_assign. The table must contain a 'condition' and 'fleet' column with each row corresponding to a set of expressions that will be used to assign observations to fleets. A table can be created with the cond and fleet_val arguments or by uploading an existing table that matches the format requirements. See 'Details' below for examples of how tables can be formatted.

Usage

fleet_table(
  dat,
  project,
  cond = NULL,
  fleet_val = NULL,
  table = NULL,
  save = TRUE
)

Arguments

Details

Below is a simple example of a fleet table. For a fleet table to be created, it must contain one "condition" column and one "fleet" column. Each fleet definition can be as long as necessary. For example, the first expression in the condition column example could also be "GEAR == 8 & species == 'pollock'". Use the '&' operator when combining expressions.

Value

Returns a table of fleet conditions that is saved to the FishSET database with the name 'projectFleetTable'.

Examples

## Not run:  
fleet_table("MainDataTable", "myProject", 
            cond = c("GEAR == 8", "species == 'cod'", "area %in% c(640, 620)"),
            fleet_val = c("A", "B", "C"), save = TRUE
            ) 

## End(Not run)

Description

Change the format of a gridded dataset from wide to long (or vice versa) and remove any unmatched area/zones from grid. This is a necessary step for including gridded variables in the conditional logit model.

Usage

format_grid(
  grid,
  dat,
  project,
  dat.key,
  area.dat,
  area.grid = NULL,
  id.cols,
  from.format = "wide",
  to.format = "wide",
  val.name = NULL,
  save = FALSE
)

Arguments

See Also

merge_dat()

Description

Reshapes the project datasets into a single long format suitable for discrete choice modeling using RTMB. This function integrates various data sources-including distance matrices, expectation (catch and/or revenue) matrices, auxiliary data, and gridded environmental data- and performs optional missing data imputation.

Usage

format_model_data(
  project,
  name,
  alt_name,
  zone_id,
  unique_obs_id,
  select_vars = NULL,
  aux_data = NULL,
  aux_key = NULL,
  gridded_data = NULL,
  expectations = NULL,
  distance = TRUE,
  distance_units = NULL,
  impute = NULL,
  crs = NULL,
  overwrite = FALSE
)

Arguments

Details

The resulting formatted data is serialized and stored in the FishSET project database within a table named '[project_name]LongFormatData'.

Value

A list containing the formatted data frame and the input settings. The list is saved to the project database.

Examples

## Not run: 
  # Basic usage: Formatting data with simple mean imputation for missing values
  format_model_data(
    project = "NewEnglandCod",
    name = "ModelData_Run1",
    alt_name = "altname_1",
    zone_id = "zone_code",
    unique_obs_id = "trip_id",
    select_vars = c("vessel_length", "month", "permit_type"),
    impute = "mean"
  )

  # Advanced usage: Including distance calculations, auxiliary economic data, 
  # and revenue expectations
  format_model_data(
    project = "WestCoastGroundfish",
    name = "ModelData_Spatial",
    alt_name = "altname_1",
    zone_id = "grid_id",
    unique_obs_id = "haul_id",
    select_vars = c("vessel_len", "month", "fuel_price"),
    aux_data = "FuelCostIndex",
    aux_key = "year",
    expectations = c("ExpectedRevenue_2023"),
    distance = TRUE,
    crs = 4326,
    impute = "remove"
  )

## End(Not run)

Description

Display summary of function calls

Usage

function_summary(project, date = NULL, type = "dat_load", show = "all")

Arguments

Details

Displays a list of functions by type and their arguments from a log file. If no date is entered the most recent log file is pulled.

See Also

filter_summary

Examples

## Not run: 
function_summary("pollock")

## End(Not run)

Description

Retrieve closure scenario by project

Usage

get_closure_scenario(project)

Arguments

Examples

## Not run: 
get_closure_scenario("pollock")

## End(Not run)

Description

This function lists the confidentiality "check" tables used to suppress values.

Usage

get_confid_cache(project, show = "all")

Arguments

Value

A list of tables containing suppression conditions.

See Also

reset_confid_cache

Description

This function returns the confidentiality settings from project settings file.

Usage

get_confid_check(project)

Arguments

Value

A list containing the confidentiality parameters: check, v_id, rule, and value.

See Also

set_confid_check get_proj_settings

Description

Retrieves the grid log file for a project. The grid log shows which grid files are currently saved to the project data folder.

Usage

get_grid_log(project)

Arguments

Details

The grid log is a list containing information about the grid files currently saved to the project data folder. Each grid entry contains three fields: grid_name, closure_name, and combined_areas. grid_name is the name of the original grid object. If the other two fields are empty, this means that the grid file has not been altered and is the same as the original. closure_name is the name of a second grid file containing closure areas that were combined with grid_name. combined_areas are the names/IDs of the closures areas from the closure grid file that were combined with grid_name.

Examples

## Not run: 
get_grid_log("pollock")

## End(Not run)

Description

Pull data from latest project file

Usage

get_latest_projectfile(project, mod.name)

Arguments

Examples

## Not run: 
get_latest_projectfile("pollock", "logit_mod1")

## End(Not run)

Description

Retrieve project settings

Usage

get_proj_settings(project, format = FALSE)

Arguments

Details

The project settings file includes confidentiality settings, the user output folder directory, and the default plot saving size.

Description

Wrapper function to calculate global and local Getis-Ord by discrete area

Usage

getis_ord_stats(
  dat,
  project,
  varofint,
  zoneid,
  spat,
  cat,
  lon.dat = NULL,
  lat.dat = NULL,
  lon.spat = NULL,
  lat.spat = NULL
)

Arguments

Details

Calculates the degree, within each zone, that high or low values of the varofint cluster in space. Function utilizes the localG and knearneigh functions from the spdep package. The spatial input is a row-standardized spatial weights matrix for computed nearest neighbor matrix, which is the null setting for the nb2listw function. Requires a data frame with area as a factor, the lon/lat centroid for each area, the lat/lon outlining each area, and the variable of interest (varofint) or a map file with lat/lon defining boundaries of area/zones and variable of interest for weighting. Also required is the lat/lon defining the center of a zone/area. If the centroid is not included in the map file, then find_centroid can be called to calculate the centroid of each zone. If the variable of interest is not associated with an area/zone then the assignment_column function can be used to assign each observation to a zone. Arguments to identify centroid and assign variable of interest to area/zone are optional and default to NULL.

Value

Returns a plot and table. Both are saved to the output folder.

Examples

## Not run: 
getis_ord_stats(pcodMainDataTable, project = 'pcod', varofint = 'OFFICIAL_MT_TONS',
  spat = spatdat, lon.dat = 'LonLat_START_LON', lat.dat = 'LonLat_START_LAT', cat = 'NMFS_AREA')

## End(Not run)

Description

Create a within-group running sum variable

Usage

group_cumsum(
  dat,
  project,
  group,
  sort_by,
  value,
  name = "group_cumsum",
  include_total_col = FALSE
)

Arguments

Details

group_cumsum sums value by group, then cumulatively sums within groups. For example, a running sum by trip variable can be made by entering variables that identify unique vessels and trips into group and a numeric variable (such as catch or # of hauls) into value. Each vessel's trip total is calculated then cumulatively summed. The "group_total" variable gives the total value by group and can be dropped by setting include_total_col = TRUE.

Examples

## Not run: 
group_cumsum(pollockMainDataTable, "pollock", group = c("PERMIT", "TRIP_ID"),
             sort_by = "HAUL_DATE", value = "OFFICIAL_TOTAL_CATCH")

## End(Not run)

Description

Create a within-group lagged difference variable

Usage

group_diff(
  dat,
  project,
  group,
  sort_by,
  value,
  name = "group_diff",
  lag = 1,
  include_total_col = FALSE
)

Arguments

Details

group_diff creates a grouped lagged difference variable. value is first summed by the variable(s) in group, then the difference within-group is calculated. The "group_total" variable gives the total value by group and can be dropped by setting include_total_col = FALSE.

Examples

## Not run: 
group_diff(pollockMainDataTable, "pollock", group = c("PERMIT", "TRIP_ID"),
           sort_by = "HAUL_DATE", value = "HAUL")

## End(Not run)

Description

Create a within-group percentage variable

Usage

group_perc(
  dat,
  project,
  group = NULL,
  value,
  name = "group_perc",
  include_total_col = FALSE
)

Arguments

Details

group_perc creates a within-group percentage variable using a primary group (group). The total value of group is stored in the "total_value" variable, and the within-group total stored in "group_total". The group percentage is calculated using these two function-created variables. "total_value" can be dropped by setting include_total_col = TRUE.

Examples

## Not run: 
group_perc(pollockMainDataTable, "pollock", group = "PERMIT",
           value = "OFFICIAL_TOTAL_CATCH_MT")
           
group_perc(pollockMainDataTable, "pollock", group = "DISEMBARKED_PORT", value = "HAUL")

## End(Not run)

Description

Aggregates a data frame from individual observations (hauls) to a summary level (trips). It provides flexible methods for collapsing numeric, character, and temporal data.

Usage

haul_to_trip(
  dat,
  project,
  trip_id,
  zoneID_dat,
  zone_fun = "mode",
  date_fun = "min",
  num_fun = "mean",
  char_fun = "mode",
  haul_count = TRUE,
  log_fun = TRUE
)

Arguments

Details

The function aggregates columns based on their data type per unique trip ID. For columns that are not numeric, date, or character, the function defaults to taking the first observation for each trip.

Value

A data frame where each row represents a single trip, aggregated according to the specified methods.

Examples

## Not run: 
# Collapse the data from haul to trip level
trip_data <- haul_to_trip(
  dat = "pollockMainDataTable",
  project = "pollock",
  trip_id = "tripID",
  zone_col = "ZONE",
  zone_fun = "mode", # Use the most common zone for the trip
  date_fun = "min",   # Use the earliest haul date as the trip date
  num_fun = "sum",    # Sum the fish weight for the trip
  char_fun = "first", # Use the first vessel name recorded
  haul_count = TRUE
)

## End(Not run)

Description

Create ID variable from one or more variables

Usage

ID_var(
  dat,
  project,
  vars,
  name = NULL,
  type = "string",
  drop = FALSE,
  sep = "_",
  log_fun = TRUE
)

Arguments

Details

ID variable can be based on a single or multiple variables. Use sep = TRUE if dropping variables that create the ID variable.

Value

Returns the 'MainDataTable' with the ID variable included.

Examples

## Not run: 
pcodMainDataTable <- ID_var(pcodMainDataTable, "pcod", name = "PermitID", 
        vars = c("GEAR_TYPE", "TRIP_SEQ"), type = 'integar')
pcodMainDataTable <- ID_var(pcodMainDataTable, "pcod", name = "PermitID", 
        vars = c("GEAR_TYPE", "TRIP_SEQ"), type = 'string', sep="_")

## End(Not run)

Description

Insert plot from user folder

Usage

insert_plot(out, project)

Arguments

Examples

## Not run: 
insert_plot("pollock_plot.png")

## End(Not run)

Description

Insert table from user folder

Usage

insert_table(out, project)

Arguments

Examples

## Not run: 
insert_table("pollock_table.csv")

## End(Not run)

Description

Jitter longitude and latitude variables

Usage

jitter_lonlat(dat, project, lon, lat, factor = 1, amount = NULL)

Arguments

Details

This is one of the FishSET confidentiality functions. It "jitters" longitude and latitude using the base R function jitter.

Examples

## Not run: 
jitter_lonlat(pollockMainDataTable, "pollock",
              lon = "LonLat_START_LON", lat = "LonLat_START_LAT")

## End(Not run)

Description

Creates a lagged zone ID variable for haul data, where the lagged location of the first haul is filled in with the port of departure. This variable is required for data with multiple sets or hauls in a single trip and for the full information model with Dahl's correction (logit_correction).

Usage

lag_zone(
  dat,
  project,
  spat = NULL,
  port,
  port_name,
  port_lon,
  port_lat,
  trip_id,
  haul_order,
  starting_port,
  zoneID_dat,
  zoneID_spat = NULL,
  name = "startingloc",
  bufferval = 100,
  db_save = FALSE
)

Arguments

Details

Function creates the startloc vector that is required for multihaul data and the full information model with Dahl's correction logit_correction. The vector is the lagged zone ID - zone when the decision of where to fish next was made. Generally, the first zone of a trip is the port of departure. The assignment_column function is called to assign starting port locations and haul locations to zones. If ZoneID exists in dat, assignment_column is not called and the following arguments are not required: spat, zoneID_spat.

Value

Primary data set with starting location variable added.

Examples

## Not run: 
pcodMainDataTable <- lag_zone(pcodMainDataTable, 'pcod',
    map2, "pcodPortTable", "TRIP_SEQ", "HAUL_SEQ", "DISEMBARKED_PORT", 
 "START_LON", "START_LAT", "NMFS_AREA", "STARTING_LOC"
)

## End(Not run)

Description

View list of all log files

Usage

list_logs(project = NULL, chron = FALSE, modified = FALSE)

Arguments

Description

Show project table names by table type. To see all tables for all projects in the FishSETFolder, use fishset_tables.

Usage

list_tables(project, type = "main")

Arguments

Examples

## Not run: 
list_tables("pollock", type = "main")
list_tables("pollock", "ec")

## End(Not run)

Description

Auxiliary data is additional data that connects the primary dataset. Function pulls the data, parses it, and then and saves the data to the FishSET database. A project must exist before running load_aux(). See load_maindata to create a new project.

Usage

load_aux(dat, aux, name, over_write = TRUE, project = NULL)

Arguments

Details

Auxiliary data is any additional data beyond the primary data and the port data. Auxiliary data can be any data that can be merged with the primary dataset (ex. prices by date, vessel characteristics, or fishery season). The auxiliary data does not have to be at a haul or trip level but must contain a variable to connect the auxiliary data to the primary dataset. The function checks that at least one column name of the auxiliary data matches a column name in the primary dataset. The function checks that each row is unique, that no variables are empty, and that column names are case-insensitive unique. There data issues are resolved before the data is saved to the database. The data is saved in the FishSET database as the raw data and the working data. The naming convention for auxiliary tables is "projectNameAuxTable". Date is also added to the name for the raw data. See table_view to view/load auxiliary tables into the working environment.

See Also

table_view, load_maindata, write_dat

Examples

## Not run: 
load_aux(pcodMainDataTable, name = 'FisherySeason', over_write = TRUE, 
         project = 'pcod')

## End(Not run)

Description

Load data from FishSET database into the R environment

Usage

load_data(project, name = NULL)

Arguments

Details

Pulls the primary data table from the FishSET database and loads it into the working environment as the project and MainDataTable. For example, if the project was pollock, then data would be saved to the working environment as 'pollockMainDataTable'.

Value

Data loaded to working environment as the project and ‘MainDataTable’.

Examples

## Not run: 
load_data('pollock')

load_data('pollock', 'pollockMainDataTable20190101')

## End(Not run)

Description

Gridded data is data that varies by two dimensions. Column names must be zone names. Load, parse, and save gridded data to FishSET database. A project must exist before running load_grid(). See load_maindata to create a new project.

Usage

load_grid(grid, name, project, over_write = TRUE)

Arguments

Details

Grid data is an optional data frame that contains a variable that varies by the map grid (ex. sea surface temperature, wind speed). Data can also vary by a second dimension (e.g., date/time). Both dimensions in the gridded data file need to be variables included in the primary data set. The grid locations (zones) must define the columns and the optional second dimension defines the rows. The row variable must have the exact name as the variable in the primary data frame that it will be linked to. The function DOES NOT check that column and row variables match a variable in the primary data set. The function checks that each row is unique, that no variables are empty, and that column names are case-insensitive unique. These data issues are resolved before the data is saved to the database. The data is saved in the FishSET database as the raw data and the working data. In both cases, the table name is the project and the file name x. Date is attached to the name for the raw data. The naming convention for gridded tables is "projectNameGridTable". See table_view to view/load gridded tables into the working environment.

See Also

table_view, load_maindata, write_dat

Examples

## Not run: 
load_grid(dat = 'pcodMainDataTable', name = 'SeaSurfaceTemp', 
          over_write = TRUE, project = 'pcod')

## End(Not run)

Description

A helper function to load selected variables from an RDS file in the FishSET GUI.

Usage

load_gui_variables(project_name, folderpath)

Arguments

Value

A list of saved variables if the file exists, otherwise returns NULL.

Description

load_maindata() saves the primary dataset to the FishSET Database (located in the FishSETFolder) and is a required step. The primary data will also be loaded into the working environment as a dataframe named "projectMainDataTable". Running load_maindata() creates a new project directory in the FishSETFolder. To see a list of existing projects run projects() or open the FishSETFolder.

Usage

load_maindata(dat, project, over_write = FALSE, compare = FALSE, y = NULL)

Arguments

Details

The dataset is saved in the FishSET database as raw and working tables. The table name is the project and the table type, 'MainDataTable'. The raw table is the original, unedited table. The working table contains any changes made to the table after uploading. An eight digit date string is included in the name of the raw table (e.g. "pollockMainDataTable20220210"). The primary data is loaded into the working environment as ‘projectMainDataTable’. The fishset_compare argument compares dat to an existing FishSET table in y and returns a message noting basic differences between the two. The column names are checked for case-insensitivity and uniqueness.

See Also

save_dat, write_dat, load_data, fishset_tables

Examples

## Not run: 
# upload data from filepath
load_maindata(dat = "PATH/TO/DATA", project = "pollock")

# upload from dataframe in working environment
load_maindata(dat = Mydata, project = 'pollock', over_write = TRUE, 
              compare = TRUE, y = 'MainDataTable01012011')
              
# upload from an exisitng FishSET primary data table
looad_maindata(dat = "pollockMainDataTable", project = "pollock2020")

## End(Not run)

Description

load_outsample() saves out-of-sample dataset to the FishSET Database (located in the FishSETFolder) and the structure must match the primary dataset. A project must exist before running load_outsample(). See load_maindata to create a new project. Note: if the data are out-of-sample temporally then upload a new datafile, if the data are only out-of-sample spatially then upload the primary data file in this function.

Usage

load_outsample(dat, project, over_write = FALSE, compare = FALSE, y = NULL)

Arguments

Details

The out-of-sample dataset is saved in the FishSET database as raw and working tables. The table name is the project and the table type, 'OutSampleDataTable'. The raw table is the original, unedited table. The working table contains any changes made to the table after uploading. An eight digit date string is included in the name of the raw table (e.g. "pollockOutSampleDataTable20220210"). The out-of-sample data is loaded into the working environment as ‘projectOutSampleDataTable’. The fishset_compare argument compares dat to an existing FishSET table in y and returns a message noting basic differences between the two. The column names are checked for case-insensitivity and uniqueness.

See Also

load_maindata, save_dat, write_dat, load_data, fishset_tables

Examples

## Not run: 
# upload data from filepath
load_outsample(dat = "PATH/TO/DATA", project = "pollock")

# upload from dataframe in working environment
load_outsample(dat = MyData, project = 'pollock', over_write = TRUE, 
              compare = TRUE, y = 'OutSampleDataTable01012011')
              
# upload from an exisitng FishSET out-of-sample data table
load_outsample(dat = "pollockOutSampleDataTable", project = "pollock")

## End(Not run)

Description

A project must exist before running load_port(). See load_maindata to create a new project.

Usage

load_port(
  dat,
  port_name,
  project,
  over_write = TRUE,
  compare = FALSE,
  y = NULL
)

Arguments

Details

Runs a series of checks on the port data. The function checks that each row is unique, that no variables are empty, and that column names are case-insensitive unique. There data issues are resolved before the data is saved to the database. If checks pass, runs the fishset_compare function and saves the new data frame to the FishSET database. The data is saved in the FishSET database as the raw data and the working data. The naming convention for port tables is "projectPortTable". Date is also attached to the name for the raw data. See table_view to view/load port tables into the working environment.

See Also

table_view, load_maindata, write_dat

Examples

## Not run: 
load_port(PortTable, over_write = TRUE, project  ='pollock',
          compare = TRUE, y = 'pollockPortTable01012011')

## End(Not run)

Description

Saves a spatial table to the FishSETFolder as a geojson file. A project must exist before running load_spatial(). See load_maindata to create a new project.

Usage

load_spatial(
  spat,
  name = NULL,
  over_write = TRUE,
  project,
  data.type = NULL,
  lon = NULL,
  lat = NULL,
  id = NULL,
  ...
)

Arguments