Package 'icesFO'

Title: Functions to support the creation of ICES Fisheries Overviews
Description: Functions to support the creation of ICES Fisheries Overviews.
Authors: Adriana Villamor [aut, cre], Colin Millar [aut], Colm Lordan [aut], Youen Vermard [aut], Scott Large [aut], Sarah Millar [ctb]
Maintainer: Adriana Villamor <[email protected]>
License: GPL (>= 2)
Version: 1.0.0.9005
Built: 2024-12-09 04:45:25 UTC
Source: https://github.com/ices-tools-prod/icesFO

Help Index


Functions to support the creation of ICES Fisheries Overviews

Description

Functions to support the creation of ICES Fisheries Overviews, ....

Details

Loading data:

load_sid load data from SID
load_sag load data from SAG
load_catches load catch data from ICES

Formatting datas:

format_sid format raw output from load_sid
format_stecf format raw output from load_sid

Plots:

plot_CLD_bar plot
plot_GES_pies plot
plot_catch_trends plot
plot_discard_current plot
plot_discard_trends plot
plot_kobe plot
plot_status_prop_pies plot
plot_stecf plot
plot_stock_trends plot

Author(s)

Adriana Villamor, Scott Large, Sarah Louise Millar and Colin Millar.


Compute a matrix of technical interactions.

Description

Based on landings and catches by species and gear, compute a matrix of technical interaction values and main gear contributions.

Usage

compute_technical_interactions(x, threshByCatch = 5,
  thresholdMainGear = 0.8, thresholdCoCatches = 0.5,
  catchCoverage = 0.95)

Arguments

x

a dataframe in the same format as the STECF data.

threshByCatch

minimum tonnage for a species to be considered a by catch (default 5)

thresholdMainGear

a threshold for including gears contributing to co-catches, to retain only the gear with the greatest contribution set this to 1 (default is 0.8)

thresholdCoCatches

a proportion giving the threshold for when we decide that there is co-catches (default 0.5)

catchCoverage

the propotion of total catch to cover in the tables i.e. 0.95 gives a table convering 95% of the total catch (default 0.95)

Value

A list with four elements, technical interactions for landings (recapLand) and catch (recapCatch) and tables of main gears involved in the interactions based on landings (MainGearsLandings) and catches (MainGearsCatches)

Note

Technical interaction appears between stocks when they are caught by the same gear during a fishing operation. Ideally the technical interaction should then be studied at the scale of the fishing operation to prevent artificially creating technical interaction between stocks that might only be caught at day/night or in different areas/timing of the year. However, often, the finest available information is per stock/gear/area/season. Knowing these limitations, the methodology used here consists in computing the sum of landings per strata of one species given that a second species is also present in the landings of this strata and then dividing this number by the total landings of the first species:

Ti,j=sLs,jPs,jsLs,i100T_{i,j}=\frac{\sum_s L_{s,j}*P_{s,j}}{\sum_s L_{s,i}}*100

Where T is the value of the technical interaction, i and j are the two species for which the technical interaction is assessed. P is an indicator variable and equals 0 if the total landings of a species for a for a given strata is less than 5 total landings for that strata and 1 otherwise. L is the landings for a given species and strata.

Strata corresponds to the provided disaggregation of the landings.

See Also

plot_technical_interactions for plotting technical interactions.

icesFO-package gives an overview of the package.

Examples

## Not run: 
technical_interacton <- 
  compute_technical_interactions(STECF_landings, catchCoverage = 0.99)

plot_technical_interactions(technical_interacton$recapLand)

## End(Not run)

Format the SAG status data for its use as an annex table.

Description

It provides an excel file with color names per status, as well as other information that might be required for an annex table

Usage

format_annex_table(df, year)

Arguments

df

a dataframe output from format_sag_status.

year

the active year

Value

A data frame

Note

Can add some helpful information here

See Also

format_sag for formatting raw data from the ICES Stock Assessment database.

icesFO-package gives an overview of the package.

Examples

## Not run: 
sid_format <- format_sid(x, "Celtic Seas")

## End(Not run)

Format the data from the time-series of ICES historical, official and preliminary catches.

Description

Format the data from the ICES Stock Assessment Database for the downloaded year and the specific Ecoregion for which you are producing the Fisheries Overviews.

Usage

format_catches(year, ecoregion, historical, official, preliminary = NULL,
  species_list, sid)

Arguments

year

the year required

ecoregion

an identifier of the Ecoregion of interest

historical

a dataframe output from load_historical_catches() required.

official

a dataframe output from load_official_catches() required.

preliminary

a dataframe output from load_preliminary_catches() optional.

species_list

a list of species common names and scientific names from ASFIS

sid

the main table from ICES Stock Information DB (SD)

Value

A data frame..

Note

Can add some helpful information here

References

The ICES stock information Database web sevices: http://sid.ices.dk/services/

See Also

format_sid for formatting raw data from the ICES Stock Information database.

icesFO-package gives an overview of the package.

Examples

## Not run: 
  sid <- load_sid(2019)
  species_list <- load_asfis_species()
  historical <- load_historical_catches()
  official <- load_official_catches()
  preliminary <- load_preliminary_catches(2018)
  catches_format <- 
    format_catches(2019, "Celtic Seas", historical, official, preliminary,
                   species_list, sid)

## End(Not run)

Format the data from the ICES Stock Assessment Database.

Description

Format the data from the ICES Stock Assessment Database for the downloaded year and the specific Ecoregion for which you are producing the Fisheries Overviews.

Usage

format_sag(x, y, year, ecoregion)

Arguments

x

a dataframe output from load_sag_summary() required.

y

a dataframe output from load_sag_refpts() required.

year

the year for which data is required.

ecoregion

an identifier of the Ecoregion of interest

Value

A data frame..

Note

Can add some helpful information here

References

The ICES stock information Database web sevices: http://sid.ices.dk/services/

See Also

format_sid for formatting raw data from the ICES Stock Information database.

icesFO-package gives an overview of the package.

Examples

## Not run: 
sag_format <- format_sag(x,y, "Celtic Seas")

## End(Not run)

Format the stock status data as is in the ICES Stock Assessment Database.

Description

Format the data from the ICES Stock Assessment Database for the downloaded year and the specific Ecoregion for which you are producing the Fisheries Overviews.

Usage

format_sag_status(x, year, ecoregion)

Arguments

x

a dataframe output from load_sag_status() required.

year

the year required

ecoregion

an identifier of the Ecoregion of interest

Value

A data frame..

Note

Can add some helpful information here

References

The ICES stock information Database web sevices: http://sid.ices.dk/services/

See Also

format_sid for formatting raw data from the ICES Stock Information database.

icesFO-package gives an overview of the package.

Examples

## Not run: 
sag_status <- format_sag_status(x,"Celtic Seas")

## End(Not run)

Format the data from the ICES Stock Information Database.

Description

Format the data from the ICES Stock Information Database for the downloaded year and the specific Ecoregion for which you are producing the Fisheries Overviews.

Usage

format_sid(x, ecoregion)

Arguments

x

a dataframe output from load_sid() required.

ecoregion

an identifier of the Ecoregion of interest

Value

A data frame..

Note

Can add some helpful information here

References

The ICES stock information Database web sevices: http://sid.ices.dk/services/

See Also

format_sag for formatting raw data from the ICES Stock Assessment database.

icesFO-package gives an overview of the package.

Examples

## Not run: 
sid_format <- format_sid(x, "Celtic Seas")

## End(Not run)

Format the data from STECF effort and landings

Description

Format the data from STECF effort and landings for the specific Ecoregion for which you are producing the Fisheries Overviews.

Usage

format_stecf_effort(x)

format_stecf_landings(x)

Arguments

x

the name of the dataframe with effort data

Details

These two dataframes have to be downloaded by hand and put in the data folder. The proper Annexes have to decided by the user.

Value

a data frame of stock status relative to reference points and catch, discards, and landings by stock for the most recent assessment.

Note

Some considerable errors have been identified in the STECF data. Finland and Estonia effort data are not reliable, and Germany recorded an erroneous haul in 2013. These values have been removed.

Can add some helpful information here

References

STECF dissemination tool https://stecf.jrc.ec.europa.eu/web/stecf/dd/effort/graphs-annex

See Also

format_sag for formatting raw data from the ICES Stock Assessment database.

icesFO-package gives an overview of the package.

Examples

## Not run: 
stecf_formatted <- format_stecf("Celtic Seas")

## End(Not run)

Download ICES areas polygons

Description

Returns a simple features object with polygons for all subdivisions

Usage

load_areas(ecoregion, precision = 3)

Arguments

ecoregion

an ICES ecoregion to download ICES areas from (e.g "Baltic Sea")

precision

the numnber of decimal places required in the coordinates

Value

A simple features collection

See Also

icesFO-package gives an overview of the package.

Examples

## Not run: 
  ices_areas <- load_areas("Greater North Sea")

## End(Not run)

Download ASFIS Species list from FAO.

Description

Download

Usage

load_asfis_species()

Value

A data frame

See Also

load_sag for loading data from the ICES Stock Assessment database.

icesFO-package gives an overview of the package.

Examples

## Not run: 
catches_hist_raw <- load_historical_catches()
catches_official_raw <- load_official_catches()
catches_prelim_raw <- load_preliminary_catches()

## End(Not run)

Download catch data from ICES web services.

Description

Download historical and current catches data from the ICES web services also preliminary catches can be downloaded for the current year

Usage

load_historical_catches()

load_official_catches()

load_preliminary_catches(year)

Arguments

year

the year for which data is required.

Value

A data frame..

Note

Can add some helpful information here

References

The ICES stock information Database web sevices: http://sid.ices.dk/services/

See Also

load_sag for loading data from the ICES Stock Assessment database.

icesFO-package gives an overview of the package.

Examples

## Not run: 
catches_hist_raw <- load_historical_catches()
catches_official_raw <- load_official_catches()
catches_prelim_raw <- load_preliminary_catches()

## End(Not run)

Download ecoregion polygons

Description

Returns a simple features object with a polygon for each ecoregion

Usage

load_ecoregion(ecoregion, precision = 3)

Arguments

ecoregion

an ICES ecoregion to download (e.g "Baltic Sea")

precision

the numnber of decimal places required in the coordinates

Value

A simple features collection

See Also

icesFO-package gives an overview of the package.

Examples

## Not run: 
  ecoregion <- load_ecoregion("Baltic Sea")

## End(Not run)

Download data from the ICES Stock Assessment database.

Description

Download data from the ICES Stock Assessment database for the year in which you are producing the Fisheries Overviews. Form SAG

Usage

load_sag_summary(year)

load_sag_refpts(year)

load_sag_status(year)

Arguments

year

the year for which data is required.

Value

A data frame..

Note

Can add some helpful information here

References

The ICES stock assessment graphs Database web sevices: http://standardgraphs.ices.dk/stockList.aspx

See Also

load_sid for loading data from the ICES Stock Information database.

icesFO-package gives an overview of the package.

Examples

## Not run: 
sag_summary_raw <- load_sag_summary(2019)
sag_refpts_raw <- load_sag_refpts(2019)
sag_status_raw <- load_sag_status(2019)

## End(Not run)

Download data from the ICES Stock Information Database.

Description

Download data from the ICES Stock Information Database for the year in which you are producing the Fisheries Overviews.

Usage

load_sid(year)

Arguments

year

the year for which data is required.

Value

A data frame..

Note

Can add some helpful information here

References

The ICES stock information Database web sevices: http://sid.ices.dk/services/

See Also

load_sag for loading data from the ICES Stock Assessment database.

icesFO-package gives an overview of the package.

Examples

## Not run: 
sid_raw <- load_sid(2019)

## End(Not run)

Download a statistical rectangles mapped to ecoregion

Description

Returns a data frame of giving the ecoregion for each ICES statistical rectangle

Usage

load_statrec2ecoregions()

Value

A data frame

See Also

icesFO-package gives an overview of the package.

Examples

## Not run: 
  statrec2ecoregion <- load_statrec2ecoregion()

## End(Not run)

Returns an ordered plot of catch bars colored according to F/F<sub>MSY</sub> and SSB/MSY B<sub>trigger</sub> by fish category and ecoregion

Description

Wrangling of format_sag output to obtain a dataframe with time-series of F, Fmsy, SSB and MSY B trigger for each stock in the Ecoregion, according to the last assessment (relative to the set year)

Usage

plot_CLD_bar(x, guild, caption = TRUE, cap_year, cap_month,
  return_data = FALSE)

Arguments

x

a dataframe output of stockstatus+catch_current.R

guild

an identifier of the Fisheries guild to plot

caption

logical flag

cap_year

the year to be shown in the figure caption

cap_month

the month to be shown in the figure caption, the accession date to SAG usually

return_data

a parameter indicating if the data behind the plot should be returned as a dataframe

Value

A plot

Note

Can add some helpful information here

References

The ICES stock information Database web sevices: http://sid.ices.dk/services/

See Also

plot_CLD_bar Stock status relative to reference points.

icesFO-package gives an overview of the package.

Examples

## Not run: 
plot1 <- plot_CLD_bar(CLDstatus, guild="Demersal", return_data = TRUE)

## End(Not run)

Returns a plot of discard rate by fish category for an ecoregion in the last assessment year.

Description

Wrangling of format_sag output to obtain a dataframe with time-series of F, Fmsy, SSB and MSY B trigger for each stock in the Ecoregion, according to the last assessment (relative to the set year)

Usage

plot_discard_current(x, year, position_letter = "b)", caption = TRUE,
  cap_year, cap_month, return_data = FALSE)

Arguments

x

a dataframe output of CLD_trends

year

the year required

position_letter

is this figure "a)", or "b)" etc.

caption

logical for whether there should be a caption

cap_year

the year to be shown in the figure caption

cap_month

the month to be shown in the figure caption, the accession date to SAG usually

return_data

a parameter indicating if the data behind the plot should be returned as a dataframe

Value

A plot

Note

Can add some helpful information here

References

The ICES stock information Database web sevices: http://sid.ices.dk/services/

See Also

plot_discard_current a plot of landings and discards by fish category in the last year for an ecoregion.

icesFO-package gives an overview of the package.

Examples

## Not run: 
plot1 <- plot_discard_trends(CLDtrends, caption = T,cap_year, cap_month, return_data = TRUE)

## End(Not run)

Returns an map of the ecoregion and the divisions included in it

Description

Returns an map of the ecoregion and the divisions included in it

Usage

plot_ecoregion_map(ecoregion, ices_areas)

Arguments

ecoregion

a simple features dataframe output of load_ecoregions( ... )

ices_areas

a simple features dataframe output of load_areas( ... )

Value

A ggplot plot

See Also

plot_CLD_bar Stock status relative to reference points.

icesFO-package gives an overview of the package.

Examples

## Not run: 
  ices_areas <- load_areas("Baltic Sea")
  ecoregion <- load_ecoregion("Baltic Sea")
  eco_map <- plot_ecoregion_map(ecoregion, ices_areas)

## End(Not run)

Returns an map of the ecoregion and the divisions included in it

Description

Returns an map of the ecoregion and the divisions included in it

Usage

plot_effort_map(effort, ecoregion)

Arguments

effort

a dataframe of effort data with a WKT columns (see notes)

ecoregion

a dataframe output of load_ecoregion( ... )

Value

A ggplot object

Note

The effort data.frame is conveted to an sf object for plotting and is expeted to have a Well Known Text column containing polygons of c-squares

See Also

plot_ecoregion_map plots ICES areas and ecoregion.

Examples

## Not run: 
ecoregion <- load_ecoregion("Baltic Sea")
effort <- icesVMS::get_effort_map("Baltic Sea")

# convert to sf
effort <- sf::st_as_sf(effort, wkt = "wkt", crs = 4326)

# select gears to plot
gears <- c("Static", "Midwater", "Otter", "Demersal seine")
effort <- effort[effort$fishing_category_FO %in% gears,]

plot1 <- plot_effort_map(effort, ecoregion)

## End(Not run)

Returns an ordered plot of catch bars colored according to F/F<sub>MSY</sub> and SSB/MSY B<sub>trigger</sub> by fish category and ecoregion

Description

Wrangling of format_sag output to obtain a dataframe with time-series of F, Fmsy, SSB and MSY B trigger for each stock in the Ecoregion, according to the last assessment (relative to the set year)

Usage

plot_GES_pies(x, y, cap_month = "August", cap_year = "2019",
  return_data = FALSE)

Arguments

x

a dataframe output of format_sag_status.R

y

a dataframe output of stockstatus_CLD_current.R

cap_month

the month to be shown in the figure caption, the accession date to SAG usually

cap_year

the year to be shown in the figure caption

return_data

a parameter indicating if the data behind the plot should be returned as a dataframe

Value

A plot

Note

Can add some helpful information here

References

The ICES stock information Database web sevices: http://sid.ices.dk/services/

See Also

plot_CLD_bar Stock status relative to reference points.

icesFO-package gives an overview of the package.

Examples

## Not run: 
plot1 <- plot_CLD_bar(CLDstatus, guild="Demersal", return_data = TRUE)

## End(Not run)

Returns a scatterplot of F/F<sub>MSY</sub> and SSB/MSY B<sub>trigger</sub> by fish category and ecoregion

Description

Wrangling of format_sag output to obtain a dataframe with time-series of F, Fmsy, SSB and MSY B trigger for each stock in the Ecoregion, according to the last assessment (relative to the set year)

Usage

plot_kobe(x, guild, caption = FALSE, cap_year, cap_month,
  return_data = FALSE)

Arguments

x

a dataframe output of stockstatus+catch_current.R

guild

an identifier of the Fisheries guild to plot

caption

logical flag

cap_year

the year to be shown in the figure caption

cap_month

the month to be shown in the figure caption, the accession date to SAG usually

return_data

a parameter indicating if the data behind the plot should be returned as a dataframe

Value

A plot

Note

Can add some helpful information here

References

The ICES stock information Database web sevices: http://sid.ices.dk/services/

See Also

plot_kobe Stock status relative to reference points.

icesFO-package gives an overview of the package.

Examples

## Not run: 
plot1 <- plot_kobe(CLDstatus, guild="Demersal", return_data = TRUE)

## End(Not run)

Returns an map of the ecoregion and the divisions included in it

Description

Returns an map of the ecoregion and the divisions included in it

Usage

plot_sar_map(sar, ecoregion, what)

Arguments

sar

a dataframe of swept area ratio data with a WKT columns (see notes)

ecoregion

a dataframe output of load_ecoregion( ... )

what

a flag which SAR value to plot - either "surface" or "subsurface"

Value

A ggplot object

Note

The effort data.frame is conveted to an sf object for plotting and is expeted to have a Well Known Text column containing polygons of c-squares

See Also

plot_ecoregion_map plots ICES areas and ecoregion.

Examples

## Not run: 
ecoregion <- load_ecoregion("Baltic Sea")
sar <- icesVMS::get_sar_map("Baltic Sea")

# convert to sf
sar <- sf::st_as_sf(sar, wkt = "wkt", crs = 4326)

plot1 <- plot_sar_map(sar, ecoregion, what = "surface")

## End(Not run)

Returns an ordered plot of catch bars colored according to F/F<sub>MSY</sub> and SSB/MSY B<sub>trigger</sub> by fish category and ecoregion

Description

Wrangling of format_sag output to obtain a dataframe with time-series of F, Fmsy, SSB and MSY B trigger for each stock in the Ecoregion, according to the last assessment (relative to the set year)

Usage

plot_status_prop_pies(x, cap_month = "November", cap_year = "2018",
  return_data = FALSE)

Arguments

x

a dataframe output of format_sag_status.R

cap_month

the month to be shown in the figure caption, the accession date to SAG usually

cap_year

the year to be shown in the figure caption

return_data

a parameter indicating if the data behind the plot should be returned as a dataframe

Value

A plot

Note

Can add some helpful information here

References

The ICES stock information Database web sevices: http://sid.ices.dk/services/

See Also

plot_CLD_bar Stock status relative to reference points.

icesFO-package gives an overview of the package.

Examples

## Not run: 
plot1 <- plot_CLD_bar(CLDstatus, guild="Demersal", return_data = TRUE)

## End(Not run)

STECF Landings over time by country, guild, or species

Description

The stecf_plot function returns an area or line plot of landings (historic and official catch) for an ecoregion by country guild, or species.

Usage

plot_stecf(x, type, variable = NULL, cap_year, cap_month, line_count,
  stecf_report, return_data = FALSE)

Arguments

x

a dataframe resulting from format_stecf_effort function

type

need description

variable

need description

cap_year

the year to be shown in the figure caption

cap_month

the month to be shown in the figure caption, the accession date to SAG usually

line_count

indicates the number of lines to be shown in the graph

stecf_report

need description

return_data

a parameter indicating if the data behind the plot should be returned as a dataframe

Value

A ggplot2 object

Examples

## Not run: 
stecf_plot("Greater North Sea Ecoregion", 
           metric = "EFFORT", 
           type = "GEAR", 
           return_plot = TRUE, 
           line_count = 4)

## End(Not run)

Visualise a matrix of technical interactions.

Description

Based on a matrix of technical interactions produce an image plot with a legend.

Usage

plot_technical_interactions(x, col = heat.colors(5, rev = TRUE))

Arguments

x

a square matrix with identical row and column names containing values of tecnical interaction between species

col

a vector of colours to use on the image plot

Value

A list with four elements, technical interactions for landings (recapLand) and catch (recapCatch) and tables of main gears involved in the interactions based on landings (MainGearsLandings) and catches (MainGearsCatches)

See Also

compute_technical_interactions for computing technical interactions.

icesFO-package gives an overview of the package.

Examples

## Not run: 
technical_interacton <- 
  compute_technical_interactions(STECF_landings, catchCoverage = 0.99)

plot_technical_interactions(technical_interacton$recapLand)

## End(Not run)

VMS Effort and landings over time by country or gear

Description

The stecf_plot function returns an area or line plot of landings (historic and official catch) for an ecoregion by country guild, or species.

Usage

plot_vms(x, metric = NULL, type = NULL, cap_year, cap_month,
  line_count, return_data = FALSE)

Arguments

x

a dataframe resulting from icesVMS::get_fo_effort() or icesVMS::get_fo_landings()

metric

either "effort" or "landings"

type

either "country" or "gear_category"

cap_year

the year to be shown in the figure caption

cap_month

the month to be shown in the figure caption, the accession date to SAG usually

line_count

indicates the number of lines to be shown in the graph

return_data

a parameter indicating if the data behind the plot should be returned as a dataframe

Value

A ggplot2 object

Examples

## Not run: 
vms_plot("Greater North Sea Ecoregion", 
           metric = "effort", 
           type = "gear_category",
           line_count = 4)

## End(Not run)

Stock status relative to reference points

Description

returns a data frame of stock status relative to reference points and catch, discards, and landings by stock for the most recent assessment.

Usage

stockstatus_CLD_current(x)

Arguments

x

a dataframe output of format_sag function

Value

A data frame..

Note

Can add some helpful information here

References

The ICES stock information Database web sevices: http://sid.ices.dk/services/

See Also

stock_trends for formatting data from the ICES Stock Assessment database.

icesFO-package gives an overview of the package.

Examples

## Not run: 
CLD_2018 <- catch_landings_discards(sag_formatted)

## End(Not run)