fleet_whelk: fleet_whelk

View source: R/fleet_whelk.R

fleet_whelkR Documentation

fleet_whelk

Description

This is a wrapper function that facilitates extracting information for the whelk fleet. All of the information used to identify fleets is stored in the package's associated data files - LIC_CORE, LIC_AREAS, and LIC_GEAR_SPEC. The various wrappers can have different options (e.g. MOBILE vs FIXED, WESTERN vs EASTERN, 4XY vs 5ZJM, small mesh vs large mesh, diamond vs square mesh, etc), and depending on which options are selected, different fleets are identified, and their data is extracted.

Usage

fleet_whelk(useLocal = NULL, socks = FALSE, ...)

Arguments

useLocal

default is FALSE. This specifies whether to run the script against local data or against Oracle (requires network or VPN). Depending on your value for useLocal, different values become necessary.

  • useLocal=TRUE This implies that you have local data you want to use.

    • param data.dir required. This is the path to your local data

  • useLocal=FALSE This implies that you have will query Oracle for the necessary data. Include all of the following:

    • param oracle.username required

    • param oracle.password required

    • param oracle.dsn required

    • param usepkg required

socks

default is FALSE. Normally, un-QC'd wrappers generate a prompt forcing the user to acknowledge that they are aware that the script needs further testing. Setting this to TRUE will prevent the prompt from showing up. Why 'socks'? You had to be there.

...

Arguments passed on to set_defaults

year

default is NULL. year can be used if data should be extracted for an entire calendar year (i.e. Jan 1 –> Dec 31). The format is YYYY, e.g. year = 2018. dateStart takes priority over year if both are provided.

dateStart

default is NULL. This identifies the start date of the search window, in the format YYYY-MM-DD (e.g. dateStart = "2019-02-19"). If no dateEnd is provided, the window will be for 1 year (i.e, 365 days). ,

dateEnd

default is NULL format is YYYY-MM-DD, e.g. dateEnd = "2019-02-19". dateEnd must be associated with a valid entry of dateStart to identify a block of time for a data extraction (e.g. Jun18, 2018 –> August 27, 2019).

marfSpp

default is 'all'. The marfis species code, usually sent by the fleet wrapper.

marfGear

default is 'all', but all wrappers have (overwritable) fleet-specific values. This is a vector of MARFIS gear codes known to have caught this species.

isdbSpp

default is 'all'. The ISDB species code, usually sent by the fleet wrapper

tripcd_id

default is NULL. If a tripcd_id from ISDB is provided, all matting records will be examined for matches

returnMARFIS

default is TRUE. Do you want a list object containing marfis trip and set information as part of your results?

returnISDB

default is TRUE. Do you want a list object containing isdb trip and set information as part of your results? (requires returnMARFIS = T)

areaFile

default is 'NAFOSubunits_sf'. This is used to identify which areas to check the trips and sets against. By default, Mar.data::NAFOSubunits_sf is ued, but any objects in Mar.data could be used.

areaFileField

default is 'NAFO_1'. This is a field within the areas object which specifies exactly which field of the areas object data should be compared against.

nafoDet

default is 2, but values between 1 and 4 are acceptable. This specifies the level of detail that will be used in the summarized locations table. Using the default value of 2, trips and sets will be summarized by areas such as "4X", "4V" and "5Z" (i.e 2 characters). If set to "1", areas would be more general (e.g. "3", "4", "5"; i.e. 1 character), while a value like 4 would summarize the trips and sets into very specific NAFO subunits (e.g. "3PSA","4VSB" and "5ZEM")

keepSurveyTrips

default is TRUE. Within the ISDB database are non-commercial, survey trips. Setting this to FALSE ensures these trips are dropped.

keepMissingGear

default is TRUE. Some fleets have particular allowable gear sizes and types (see gearSpecs). Many cases exist where all of the gear details are not filled it. When this parameter is set to TRUE, these 'unknown' types and sizes are retained, and the values are set to -999. If it is set to FALSE, any gears with missing values are dropped - and they are not included in the results.

maxTripDiff_Hr

default is 48. Any MARFIS and ISDB trips that vary by more than the # of days specified here will NOT be considered matches (on the basis of common Vessel, licence and date). They may still match on confirmation codes and/or trip names.

maxSetDiff_Hr

default is 48. Any MARFIS and ISDB sets that vary by more than the # of hours specified here will NOT be considered matches.

maxSetDiff_Km

default is 100. Any MARFIS and ISDB sets with positions more than the # of kilometers specified here will NOT be considered matches.

dropUnmatchedISDB

default is TRUE.

manualMatch

default is FALSE. This parameter is only used when calling functions from manual_matcher(). It ensures that the functions work properly with its reduced input format.

data.dir

default is 'file.path(getwd(), "data")'. Necessary for useLocal == T. This is the path to a folder where your *.rdata files are stored.

oracle.username

default is '_none_'. This is your username for accessing oracle objects.

oracle.password

default is '_none_'. This is your password for accessing oracle objects.

oracle.dsn

default is '_none_'. This is your dsn/ODBC identifier for accessing oracle objects. Normally, the value should be "PTRAN"

usepkg

default is 'roracle'. This indicates whether the connection to Oracle should use 'rodbc' or 'roracle' to connect. rodbc can be slightly easier to setup, but roracle will extract data faster.

debug

default is FALSE. If TRUE, this parameter causes the package to run in debug mode, providing much extraneous information.

debugLics

default is NULL. If a vector of LICENCE_IDs is provided, the script will provide information about when the script drops them from consideration.

debugVRs

default is NULL. If a vector of VR numbers is provided, the script will provide information about when the script drops them from consideration.

debugMARFTripIDs

default is NULL. If a vector of MARFIS trip IDs is provided, the script will provide information about when the script drops them from consideration.

debugISDBTripIDs

default is NULL. If a vector of ISDB trip IDs is provided, the script will provide information about when the script drops them from consideration.

debugISDBTripNames

default is NULL. If a vector of ISDB trip names is provided, the script will provide information about when the script drops them from consideration. Trip "names" are typically in a format like "J18-1234" or "A18-1234A".

Details

Licence Information for any fleet is accessible via the following calls. Please replace "<fleet>", with this fleet's actual fleet value identified in the NOTE, below:

  • Licence Type, Subtype, Gear and Species Information (if applicable) Mar.fleets::LIC_CORE[Mar.fleets::LIC_CORE$FLEET=="<fleet>",]

  • Licence Areas (if applicable) Mar.fleets::LIC_AREAS[Mar.fleets::LIC_AREAS$FLEET=="<fleet>",]

    If different areas/components/units are available for this fleet, the areas associated with each can be differentiated by the differing values of FLEET_AREA_ID . For example, the Redfish fleet is divided into Units 2 and 3. All of the NAFO areas associated with either of these units these can be found in via Mar.fleets::LIC_AREAS[Mar.fleets::LIC_AREAS$FLEET=="REDFISH",], but the NAFO areas associated with the Unit 2 fleet are those with FLEET_AREA_ID == UNIT2.

  • Licence Gear Specifications (if applicable) Mar.fleets::LIC_GEAR_SPEC[Mar.fleets::LIC_GEAR_SPEC$FLEET=="<fleet>",]

    If particular gear size/types are allowed, the range of sizes for each are specified by the MIN and MAX fields. If aspects of the fleet are defined by the gear size, multiple records may be present. For example, the SMALL mesh fleet will have different max and min values than the LARGE MESH fleet. These records can correspond with fleet areas, but do not have to. In this case, the gear associated with catching redfish in UNIT 2 is different than what's allowed in UNIT 3, so the LIC_GEAR_SPEC table differentiates the gear by having different entries in FLEET_GEARSPECS_ID (i.e. UNIT2 vs UNIT3). The mobile POLLOCK fleet also has multiple categories of gear sizes, but they are not related to different areas - the entries in FLEET_GEARSPECS_ID are just SMALL and LARGE. Differing values of Type have not been implemented, but the field exist such that gear can be filtered by Diamond vs Square mesh.

Value

specific returned objects can be specified by the user, but the default result is a list of objects. The list includes marfis data, isdb data, information related to the matching, and a breakdown of where the various trips and sets occurred, specifically:

  • params - this is a list containing information about the extraction

    • user - this contain all of the parameters sent to the function (including defaults, user-provided and hardcoded)

    • fleet - this is a list object containing 3 dataframes that contain the information used to identify the fleet. These will include licencesCore, licecesAreas, and licencesGearSpecs. Depending on how the fleet is defined, one or more of these may be empty.

  • fleet - This is a dataframe of the unique combinations of (MARFIS) LICENCE_ID, VR_NUMBER and GEAR_CODE that was found for this fleet during the specified period

  • FLEET_ACTIVITY - This is a dataframe of identifiers for all of the (MARFIS) fishing activity undertaken by vessels of this fleet during the specified period (i.e. LICENCE_ID, PRO_SPC_INFO_ID, LOG_EFRT_STD_INFO_ID, GEAR_CODE, MON_DOC_ID, VR_NUMBER, and several dates associated with the trip)

  • marf - This is a list of 3 sets of information for the commercial catch data (i.e. marfis):

    • MARF_TRIPS

    • MARF_SETS

    • MARF_MATCH This is a special dataframe containing information that can be used to link the commercial data to the ISDB data

  • isdb - This is a list of data objects from the ISDB db:

    • ISDB_TRIPS These are ISDB trips that are associated with MARFIS trips from the marf$MARF_TRIPS object above

    • ISDB_SETS These are all of the ISDB sets associated with the ISDB_TRIPS (matched and unmatched)

    • ISDB_CATCHES This is the data associated with the records in ISDB_TRIPS

      • ALL This is the raw data from ISCATCHES for the trips found in ISDB_TRIPS

      • SUMMARY This is the data from ISCATCHES for all of the trips found in ISDB_TRIPS, summarized by species. Each species has calculated aggregate values for "EST_NUM_CAUGHT", EST_KEPT_WT", "EST_DISCARD_WT" and "EST_COMBINED_WT"

  • matches This is a list item that contains all of the information used to assigne matches between MARFIS and ISDB

    • MATCH_SUMMARY_TRIPS This is a simple breakdown of the various approaches used for matching, and the relative success of each. Matches can occur using multiple approaches, so these can not be added up. This list also includes "Likely_Swapped_VR_Lic" which indicates how may matches seem to have the values for LICENCE_ID and VR_NUMBER reversed, and includes the count of how many rows are present in both Multimatches and Umatchables

    • MATCH_DETAILS This is a dataframe of all of the MARFIS and ISDB trips that have been associated with each other, and whether or not they were matched on each of the possible approaches

    • ISDB_UNMATCHABLES These are the trips from MARFIS that included ISDB-type information (e.g. Observer ID, ISDB Trip name, etc), but for which no ISDB match could be found.

    • ISDB_MULTIMATCHES These are ISDB trips that were found to be match multiple MARFIS trips equally well.

  • location_summary - This is a list of 1 or more dataframes that breaks down the various trips and sets by the areas in which they occurred. NAFO locations are reported for MARFIS trips, MARFIS sets and ISDB sets (not ISDB trips). These reported locations are shown, as are the "calculated" locations, which are based on the reported latitudes and longitudes. No "calculated" locations are shown for MARFIS trips, as there are no coordinates for the trip level. If a custom value for areaFile was sent (i.e. not "NAFOSubunits_sf"), a second dataframe breaking down the sets by the custom area will also be provided.

Note

Hardcoded parameters for this fleet are as follows:

  • marfGear = 62

  • marfSpp = 615

  • isdbSpp = c(4210,4211)

  • tripcd_id = 4211

  • fleet = "WHELK"

Author(s)

Mike McMahon, Mike.McMahon@dfo-mpo.gc.ca

See Also

Other fleets: fishin_CHPs(), fleet_bluefin(), fleet_cucumber(), fleet_flatfish(), fleet_gaspereau(), fleet_hagfish(), fleet_halibut(), fleet_herring(), fleet_jonah(), fleet_redCrab(), fleet_redfish(), fleet_rockCrab(), fleet_scallop(), fleet_sculpin(), fleet_shrimp(), fleet_silverhake(), fleet_snowcrab(), fleet_surfclam(), fleet_swordfishTunaShark(), fleet_urchin()

Examples

## Not run: 
db <- fleet_whelk(useLocal = F,
                    year = 2018,
                    oracle.username = "<name>",
                    oracle.password="<password>",
                    oracle.dsn="PTRAN",
                    usepkg = "roracle"
                    )
local <- fleet_whelk(year = 2018,
                       useLocal = T,
                       data.dir = "c:/data_folder"
                      )
                       
## End(Not run)

Maritimes/Mar.bycatch documentation built on Feb. 6, 2024, 3:27 p.m.