Package 'icesVMS'

Title: Link to the ICES Vessel Monitoring System and Logbook Database Web Services
Description: Links to the ICES Vessel Monitoring System (VMS) and logbook database web services <https://data.ices.dk/vms/webservices> to allow users to download summaries and data products.
Authors: Colin Millar [aut, cre], Carlos Pinto [ctb]
Maintainer: Colin Millar <[email protected]>
License: GPL (>= 2)
Version: 1.1.5
Built: 2024-10-31 05:35:40 UTC
Source: https://github.com/ices-tools-prod/icesVMS

Help Index

Functions to link to the ICES VMS and logbook database web services.

Description

Functions to link to the ICES VMS and logbook database web services to allow users to download summaries and data products from the ICES VMS and logbook database.

Details

Download data:

get_benthis_parameters download gear contact model parameters
get_metier_lookup download metier to gear category lookup table
get_vms download VMS data

Author(s)

Colin Millar.

References

ICES VMS and Logbook Database web services: https://data.ices.dk/vms/webservices.

Lists of Vocabularies

Description

Get a list of vocabularies such as country codes or ecoregions.

Usage

check_ecoregion(arg, stop.on.fail = TRUE)

check_stat_recs(arg, stop.on.fail = TRUE)

check_countries(arg, stop.on.fail = TRUE)

Arguments

arg

one of country code, ICES statistical rectangle or ICES ecoregion
stop.on.fail

logical, if TRUE function will call stop()

Value

logical

Examples

check_ecoregion("Celtic Seas")

check_stat_recs("40F1")

check_countries("DK")
check_countries(c("DK", "GB"))

Get gear characteristics for 'benthis' gear categories

Description

Download a data.frame of gear contact models for 'benthis' gear categories used in calculating the swept area of a fishing gear.

Usage

get_benthis_parameters()

Value

a data.frame of model parameters

Examples

benthis_pars <- get_benthis_parameters()

Download C-square information

Description

Download a data.frame of information on a set of C-squares.

Usage

get_csquare(c_square, stat_rec, ices_area, ecoregion, convert2sf = FALSE)

Arguments

c_square

character 0.05 degree c-square name
stat_rec

ICES statistical rectangle
ices_area

ICES area
ecoregion

ICES ecoregion
convert2sf

logical, default FALSE, should an simple features object be returned if the sf package is installed?

Details

If the sf package is installed then a simple features object will be returned, if convert2sf flag is set to TRUE.

Value

a data.frame of VMS data

Examples

sq40F3 <- get_csquare(stat_rec = "40F3")

# if the sf package is installed, an simple feature object will be returned
 NS <- get_csquare(ecoregion = "Greater North Sea", convert2sf = TRUE)
 plot(NS["ices_area"], border = "transparent")

Lists of Vocabularies

Description

Get a list of vocabularies such as country codes or ecoregions.

Usage

get_ecoregion_list()

get_stat_rec_list()

get_country_list()

Value

a character vector

Examples

ecoregions <- get_ecoregion_list()
"Celtic Seas" %in% ecoregions

stat_recs <- get_stat_rec_list()
"40F1" %in% stat_recs

countries <- get_country_list()
"DK" %in% countries

Download fishing effort map data

Description

Download a data.frame of kw fishing hours by c-square and gear category averaged over 4 years.

Usage

get_effort_map(ecoregion, year = NULL, convert2sf = FALSE)

Arguments

ecoregion

ICES ecoregion (see details)
year

which year to select (see details)
convert2sf

logical, default FALSE, should an simple features object be returned if the sf package is installed?

Details

The spatial data.frame contains average annual mega Watt fishing hours, averaged over 4 years.

Available ecoregions are given in the description field of the ICES ecoregion vocabulary <http://vocab.ices.dk/?ref=1414>

Value

a data.frame with a WKT column for the c-square polygons

Examples

## Not run: 
# requires authorization
ns_effort_map <- get_effort_map("Greater North Sea", convert2sf = TRUE)
plot(
  ns_effort_map[ns_effort_map$fishing_category_FO == "Otter","mw_fishinghours"], 
  border = FALSE, logz = TRUE
)

## End(Not run)

Download fishing effort summaries

Description

Download a data.frame of kw fishing hours by country and year for a given ICES ecoregion.

Usage

get_fo_effort(ecoregion)

Arguments

ecoregion

ICES ecoregion

Value

a data.frame

Examples

## Not run: 
# requires authorization
ns_effort_data <- get_fo_effort("Greater North Sea")

## End(Not run)

Download fishing landings summaries

Description

Download a data.frame of total weight by country and year for a given ICES ecoregion.

Usage

get_fo_landings(ecoregion)

Arguments

ecoregion

ICES ecoregion

Value

a data.frame

Examples

## Not run: 
# requires authorization
ns_landings_data <- get_fo_landings("Greater North Sea")

## End(Not run)

Download Logbook data

Description

RESTRICTED. Only core members of the ICES VMS data call can access this data. Download a data.frame of VMS data from the ICES VMS and logbook database.

Usage

get_logbook(
  country,
  year,
  month,
  gear_code,
  metier,
  stat_rec,
  ices_area,
  ecoregion
)

Arguments

country

country code
year

integer year
month

integer month
gear_code

benthis gear code
metier

level 6 metier code
stat_rec

ICES statistical rectangle
ices_area

ICES area
ecoregion

ICES ecoregion

Value

a data.frame of VMS data

Examples

## Not run: 
# requires authorization
logbook <- get_logbook(country = "DK", year = 2021, month = 1)

## End(Not run)

Link Metier level 6 to Benthis categories

Description

Download a data.frame of Metier codes to link level 6 metier codes with different gear categories

Usage

get_metier_lookup()

Value

a data.frame

Examples

metier_lookup <- get_metier_lookup()

Download passive fishing gear footprint

Description

Download a data.frame of presence of fishing by c-square and year for passive fishing gears (see details).

Usage

get_passive_footprint(
  ecoregion,
  year,
  metier_level4 = NULL,
  datacall = NULL,
  convert2sf = FALSE
)

Arguments

ecoregion

ICES ecoregion
year

which year to select
metier_level4

optional gear code (metier level 4) ("FPO")
datacall

integer year giving which data call year to inquire about. If NULL returns the a summary of the most recent approved data.
convert2sf

logical, default FALSE, should an simple features object be returned if the sf package is installed?

Details

Passive gears defined as all gears registered under the metier level 4 codes, FPO (fishing pots), LLS (long lines) and GNS (set gill nets), with the exclusion of metier level 5 codes within the GNS category: GNS_SPF and GNS_LPF (set gill nets targeting small and large pelagic fish).

Value

a data.frame with a WKT column for the c-square polygons

Examples

## Not run: 
# requires authorization
footprint_map <- get_passive_footprint("Celtic Seas", 2021, convert2sf = TRUE)
plot(footprint_map["ecoregion"], border = FALSE)

## End(Not run)

Download VMS data

Description

RESTRICTED. Only core members of the ICES VMS data call can access this data. Download a data.frame of VMS swept area ratio values from the ICES VMS and logbook database.

Usage

get_sar(
  year,
  c_square,
  gear_code,
  stat_rec,
  ices_area,
  ecoregion,
  datacall = NULL
)

Arguments

year

integer year
c_square

character 0.05 degree c-square name
gear_code

benthis gear code
stat_rec

ICES statistical rectangle
ices_area

ICES area
ecoregion

ICES ecoregion
datacall

integer year giving which data call year to inquire about. If NULL returns the a summary of the most recent approved data.

Value

a data.frame of VMS data

Examples

## Not run: 
# requires authorization
sar <- get_sar(2021, stat_rec = "40F1")

## End(Not run)

Download swept area ratio map data

Description

Download a data.frame of surface and subsurface swept area ratio by c-square for a given ICES ecoregion.

Usage

get_sar_map(ecoregion, year = NULL, nyears = NULL, convert2sf = FALSE)

Arguments

ecoregion

ICES ecoregion
year

which year to select (see details)
nyears

the number of years to take an average over
convert2sf

logical, default FALSE, should an simple features object be returned if the sf package is installed?

Details

The spatial data.frame contains average annual surface-swept-area-ratio and subsurface-swept-area-ratio averaged over 4 years by default. If year is not specified (NULL) then the present year - 1 is assumed.

Value

a data.frame with a WKT column for the c-square polygons

Examples

## Not run: 
# requires authorization
sar_map <- get_sar_map("Celtic Seas", 2021, convert2sf = TRUE)
plot(sar_map["surface_sar"], border = FALSE, logz = TRUE)

## End(Not run)

Get the details of a file screening session

Description

Download a list of information on a file upload screening session.

Usage

get_screening_details(sessionId)

Arguments

sessionId

file screening session ID

Value

a list

Examples

screening_info <- get_screening_details(530)

Get all messages of a file screening session

Description

Download a list of error and warning messages on a file upload screening session.

Usage

get_screening_messages(sessionId)

Arguments

sessionId

file screening session ID

Value

a list

Examples

tofix <- get_screening_messages(528)

Download a summary of submitted data

Description

Download a summary of submitted data

Usage

get_upload_summary(datacall = NULL)

Arguments

datacall

integer year giving which data call year to inquire about. If NULL returns the a summary of the most recent approved data.

Value

a data.frame of VMS summary data

Examples

## Not run: 
upload_summary <- get_upload_summary()

## End(Not run)

Download VMS data

Description

RESTRICTED. Only core members of the ICES VMS data call can access this data. Download a data.frame of VMS data from the ICES VMS and logbook database.

Usage

get_vms(
  country,
  year,
  month,
  c_square,
  gear_code,
  metier,
  stat_rec,
  ices_area,
  ecoregion,
  datacall = NULL
)

Arguments

country

country code
year

integer year
month

integer month
c_square

character 0.05 degree c-square name
gear_code

benthis gear code
metier

level 6 metier code
stat_rec

ICES statistical rectangle
ices_area

ICES area
ecoregion

ICES ecoregion
datacall

integer year giving which data call year to inquire about. If NULL returns the a summary of the most recent approved data.

Value

a data.frame of VMS data

Examples

## Not run: 
# requires authorization
vms <- get_vms(country = "DK", year = 2021, month = 1)

## End(Not run)

Download swept area ratio, landings and value map data

Description

Download a data.frame of surface and subsurface swept area ratio by c-square for a given ICES ecoregion, year and gear code.

Usage

get_wgfbit_data1(
  ecoregion,
  year,
  fishing_category = NULL,
  benthis_metier = NULL,
  datacall = NULL,
  convert2sf = FALSE
)

Arguments

ecoregion

ICES ecoregion
year

which year to select
fishing_category

optional gear category ("Otter", "Dredge")
benthis_metier

optional benthis metier ("SDN_DMF")
datacall

integer year giving which data call year to inquire about. If NULL returns the a summary of the most recent approved data.
convert2sf

logical, default FALSE, should an simple features object be returned if the sf package is installed?

Details

fishing_category and benthis_metier may not both be supplied, if neither are supplied the total is calculated.

Value

a data.frame with a WKT column for the c-square polygons

Examples

## Not run: 
# requires authorization
data1 <- get_wgfbit_data1("Celtic Seas", 2021, benthis_metier = "OT_DMF", convert2sf = TRUE)
plot(data1["total_weight"], border = NA, logz = TRUE)

## End(Not run)

Download swept area ratio, landings and value map data

Description

Download a data.frame of surface and subsurface swept area ratio by c-square for a given ICES ecoregion, year and gear code.

Usage

get_wgfbit_data2(ecoregion, year, convert2sf = FALSE)

Arguments

ecoregion

ICES ecoregion
year

which year to select
convert2sf

logical, default FALSE, should an simple features object be returned if the sf package is installed?

Value

a data.frame with a WKT column for the c-square polygons

Examples

## Not run: 
# requires authorization
data2 <- get_wgfbit_data2("Celtic Seas", 2021, convert2sf = TRUE)
plot(data2[data2$lE_MET_level6 == "OTB_DEF_70-99_0_0", "total_weight"], border = NA, logz = TRUE)

## End(Not run)

Download swept area ratio, landings and value map data

Description

Download a data.frame of surface and subsurface swept area ratio by c-square for a given ICES ecoregion, month, year and gear code.

Usage

get_wgfbit_data3(
  year,
  fishing_category = NULL,
  benthis_metier = NULL,
  datacall = NULL,
  convert2sf = FALSE
)

Arguments

year

which year to select
fishing_category

optional gear category ("Otter", "Dredge")
benthis_metier

optional benthis metier ("SDN_DMF")
datacall

integer year giving which data call year to inquire about. If NULL returns the a summary of the most recent approved data.
convert2sf

logical, default FALSE, should an simple features object be returned if the sf package is installed?

Details

gear_group and benthis_metier may not both be supplied, if neither are supplied the total is calculated.

Value

a data.frame with a WKT column for the c-square polygons

Examples

## Not run: 
# requires authorization
data3 <- get_wgfbit_data3(2021, benthis_metier = "OT_DMF", convert2sf = TRUE)
plot(data3["surface_sar"], border = NA, logz = TRUE)

## End(Not run)

Screen a VMS file and submit for QC checks

Description

In this web service the user can upload a file to be screen and validated by the VMS database. The service can be called using post and the file will have to be part of the body of the call. The user needs to be authenticated in order to call this service. This file can be later pushed to the database by the same user.

Usage

screen_vms_file(filename, verbose = FALSE, force = FALSE)

Arguments

filename

file name of the file containing the data to screen
verbose

return verbose information about the POST request
force

force submission even if checks to do not pass

Value

text message from the screening process

Examples

## Not run: 
# requires authorization
filename <- system.file("test_files/vms_test.csv", package = "icesVMS")
screen_vms_file(filename)

filename <- system.file("test_files/vms_test_ok.csv", package = "icesVMS")
screen_vms_file(filename)

## End(Not run)

Add together anonymous ID entries

Description

Anonymous vessel IDs are supplied when there are less than 2 vessels. Therefore when adding these values, if there is one or more values containing an empty string (? 2 vessels) then the results is an empty string also. Otherwise, a unique vector of vessel IDs is computed and if there are 2 or less unique entries they are returned, otherwise an empty string is returned.

Usage

sum_distinct_vessels(id, n)

sum_vessel_ids(id, n)

Arguments

id

a vector vessel Ids entries: string vector of semi-colon separated IDs
n

a vector corresponding to the number of unique vessel ids in the vector supplied in id where 3 codes for anything greater than 2.

Value

a single character

Note

the format of the vessel IDs is a semi-colon separated list of IDs contained in a character vector of length one.

Examples

sum_vessel_ids(c("id1;id2", "id1", "id2", "id1;id3", ""), c(2, 1, 1, 2, 3))
sum_vessel_ids(c("id1;id2", "id1", "id2", "id1;id3"), c(2, 1, 1, 2))


sum_distinct_vessels(c("id1;id2", "id1", "id2", "id1;id3", ""), c(2, 1, 1, 2, 3))
sum_distinct_vessels(c("id1;id2", "id1", "id2", "id1;id3"), c(2, 1, 1, 2))

## Not run: 
require(dplyr)

data(vms)
vms <-
  vms %>%
  group_by(year, cSquare) %>%
  summarise(
    fishingHours = sum(fishingHours, na.rm = TRUE),
    totweight = sum(totweight, na.rm = TRUE),
    noDistinctVessels = sum_distinct_vessels(anonymizedVesselID, noDistinctVessels),
    anonymizedVesselID = sum_vessel_ids(anonymizedVesselID, noDistinctVessels),
    .groups = "drop"
  )

## End(Not run)

Build a VMS web service url

Description

utility to build a url with optional query arguments

Usage

vms_api(service, ...)

Arguments

service

the name of the service
...

named arguments will be added as queries

Value

a complete url as a character string

Examples

vms_api("hi", bye = 21)
vms_api("csquares", argument1 = 2021, argument2 = NULL)

Build a WKT string from latitude and longitude

Description

utility to build a WKT (Well Known Text) polygon string for a c-square

Usage

wkt_csquare(lat, lon)

Arguments

lat

latitude
lon

longitude

Value

a string in WKT format

Examples

wkt_csquare(55, 0.1)