Define alternative fishing choice — create_alternative

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,
  occasion = "zonal centroid",
  occasion_var = NULL,
  alt_var = "zonal centroid",
  dist.unit = "miles",
  min.haul = 0,
  zoneID,
  zone.cent.name = NULL,
  fish.cent.name = NULL,
  spatname = NULL,
  spatID = NULL,
  outsample = FALSE
)

Arguments

dat

Required, main data frame containing data on hauls or trips. Table in FishSET database should contain the string MainDataTable.

project

Required, name of project.

occasion

String, determines the starting point when calculating the distance matrix. Options are "zonal centroid", "fishing centroid", "port", or "lon-lat". See occasion_var for requirements.

occasion_var

Identifies an ID column or set of lon-lat variables needed to create the distance matrix. Possible options depend on the value of occasion:

Centroid

When occasion = zonal/fishing centroid the possible options are NULL, the name of a zone ID variable, or a set coordinate variables (in Lon-Lat order).

NULL: This will merge centroid lon-lat data to the primary table using the column enter in zoneID. A centroid table must be saved to the FishSET Database.
Zone ID: This option specifies the zone ID variable to merge the centroid table to. For example, a column containing the previous zonal area. A centroid table must be saved to the FishSET Database.
Lon-Lat: A string vector of length two containing the longitude and latitude of an existing set centroid variables in dat.

Port

When occasion = port the possible options include the name of a port ID variable or a set of lon-lat variables describing the location of the port. A value of NULL will return an error.

Port ID: The name of a port ID variable in dat that will be used to join the port table to the primary table. A port table is required (see load_port()) which contains the port name and the longitude and latitude of each port.
Lon-Lat: A string vector of length two containing a port's longitude and latitude in dat.

Lon-Lat

When occasion = lon-lat, occasion_var must contain a string vector of length two containing the longitude and latitude of a vessel's location in the dat. For example, the current or previous haul location.

alt_var

Determines the alternative choices used to calculate the distance matrix. alt_var may be the centroid of zonal assignment ("zonal centroid"), "fishing centroid", or the closest point in fishing zone ("nearest point"). The centroid options require that the appropriate centroid table has been saved to the project's FishSET Database. See create_centroid() to create and save centroids. List existing centroid tables by running list_tables("project", type = "centroid").

dist.unit

String, how distance measure should be returned. Choices are "meters" or "m", "kilometers" or "km", "miles", or "nmiles" (nautical miles). Defaults to "miles".

min.haul

Required, numeric, minimum number of hauls. Zones with fewer hauls than the min.haul value will not be included in model data.

zoneID

Variable in dat that identifies the individual zones or areas.

zone.cent.name

The name of the zonal centroid table to use when occasion or alt_var is set to zonal centroid. Use list_tables("project", type = "centroid") to view existing centroid tables. See create_centroid() to create centroid tables or centroid_to_fsdb() to create a centroid table from columns found in dat.

fish.cent.name

The name of the fishing centroid table to use when occasion or alt_var is set to fishing centroid. Use list_tables("project", type = "centroid") to view existing centroid tables. See create_centroid() to create centroid tables or centroid_to_fsdb() to create a centroid table from columns found in dat.

spatname

Required when alt_var = 'nearest point'. spat is a spatial data file containing information on fishery management or regulatory zones boundaries. sf objects are recommended, but sp objects can be used as well. See dat_to_sf() to convert a spatial table read from a csv file to an sf object. To upload your spatial data to the FishSETFolder see load_spatial().If spat should come from the FishSET database, it should be the name of the original file name, in quotes. For example, "pollockNMFSZonesSpatTable". Use tables_database() or list_tables("project", type = "spat") to view the names of spatial tables in the FishSET database.

spatID

Required when alt_var = 'nearest point'. Variable in spat that identifies the individual zones or areas.

outsample

Logical, indicating whether this is for main data or out-of sample data.

Value

Saves the alternative choice list to the FishSET database as a list. Output includes:

dataZoneTrue:	Vector of 0/1 indicating whether the data from that zone is to be included in the model	greaterNZ:	Zones which pass numofNecessary test
numOfNecessary:	Minimum number of hauls for zone to be included	altChoiceUnits:	Set to miles
altChoiceType:	Set to distance	occasion:	Identifies how to find latitude and longitude for starting point
occasion_var:	Identifies how to find latitude and longitude for starting point	alt_var:	Identifies how to find latitude and longitude for alternative choice
zoneRow:	Zones and choices array	zone_cent:	Geographic centroid for each zone. Generated from `find_centroid()`
fish_cent:	Fishing centroid for each zone. Generated from `find_fishing_centroid()`	zone_cent_name:	Name of the zonal centroid table
fish_cent_name:	Name of the fishing centroid table	spat:	Spatial data object

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 make_model_design() 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(), make_model_design(), and the model run discretefish_subroutine()) 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 make_model_design() functions should also be updated before rerunning models.