fao_data_info() shows the release you use and how
to cite it.
faofishingreport turns the FAO Global Capture Production statistics into charts, maps and tables for reports. This page walks through a complete first analysis of the Northeast Atlantic (FAO major fishing area 27); every chart below was produced by the code shown above it.
A typical workflow:
| Step | What you do | Functions |
|---|---|---|
| 1. Data | Check for and download the latest FAO release; see which release you use |
check_fao_update(), download_fao_data(),
fao_data_info()
|
| 2. Fishing area | Total catch, main species and main countries of an area |
fishing_area_data(),
fishing_area_species(),
fishing_area_country()
|
| 3. Species and countries | Who catches a species, what a country catches |
species_country(), country_species(),
country_analysis()
|
| 4. Summaries | Composition, stock status, trends, data quality, diversity, fleets |
species_group_composition(),
stock_status(), peak_trend(),
data_quality(), coastal_distant(), โฆ |
| 5. Methods from the literature | Catch shocks, collapses, synchrony, pelagic/demersal ratio, mean temperature of the catch |
catch_shocks(), collapse_analysis(),
catch_synchrony(), pelagic_demersal(),
mean_temperature_catch()
|
| 6. Stock assessment | CMSY++ for the main species |
cmsy_setup(), cmsy_area()
|
| 7. Report | A Word report of an area in one call | fao_report() |
| 8. Style | Language, theme, colours, map projection | fao_settings() |
๐ฆ Installation
faofishingreport needs R 4.2 or later. Install it from GitHub:
install.packages("remotes")
remotes::install_github("Linbojun99/faofishingreport", dependencies = TRUE)With dependencies = TRUE every package that the analyses
use is installed with it: dplyr, ggplot2 and sf for the charts and maps,
rnaturalearth for the world maps, officer and xml2 for Word reports,
eoffice for editable PowerPoint charts, nanoparquet for the FishBase and
SeaLifeBase tables, ncdf4 for sea surface temperature files, and the R
packages of CMSY++ (coda, conicfit, gplots, MASS, mvtnorm, neuralnet,
โฆ). The only exceptions are rjags and R2jags, which need the separate
JAGS program: cmsy_setup() installs JAGS and both packages
the first time you use CMSY++ (see ๐ CMSY++ stock
assessment).
Windows and macOS use binary packages, so no compiler (Rtools) is needed. On macOS, editable PowerPoint charts also need XQuartz. Linux needs the system libraries of the sf package and, for Chinese charts, a Chinese font:
Load the package. The start-up message shows the operating system and the font chosen for charts (SimSun on Windows, Songti SC on macOS, Noto Serif CJK SC on Linux):
library(faofishingreport)
#> faofishingreport: Windows, chart font "SimSun" (change it with fao_font())๐พ Get the latest FAO data
The package comes with FAO release 2026.1.0. FAO publishes a new release about once a year. Check whether a newer one exists and download it (about 5 MB, a few seconds):
check_fao_update()
#> FAO Global Capture Production
#> Latest online release: 2026.1.0 (published 2026-03-30)
#> Bundled with package: 2026.1.0
#> Downloaded locally: none
#> Your data is up to date.
download_fao_data() # only needed when a newer release is availableAll functions automatically use the newest data available.
fao_data_info() tells which release that is, where it comes
from and how to cite it. See ๐พ FAO data for all
the arguments of these functions, choosing releases, the data format and
working with your own subsets.
๐ Where the results go
Each analysis saves its charts and tables in the current working folder:
| Folder | Content |
|---|---|
figures/png/ |
Charts as PNG (always); the summary analyses use
figures/png/summary/
|
figures/pptx/ |
Charts as editable PowerPoint files (with pptx = TRUE;
uses the eoffice package) |
tables/ |
Tables as CSV, readable by Excel including Chinese names |
reports/ |
Word reports of fao_report()
|
So start by choosing a folder for the report:
setwd("D:/reports/FAO27") # any folder๐ First analysis: FAO area 27
fishing_area_data() extracts the catch of one FAO major
fishing area and draws its total catch with the breakpoints of the mean
catch, its share of the world catch of all marine areas, and a world map
of the countries fishing there.
FAO27 <- fishing_area_data("Atlantic, Northeast")
The result is a list with the catch records of the area
(area_data), the periods between breakpoints
(coefs_data) and the map data (act_world_map).
FAO27$area_data is the input of most other functions:
show_table(FAO27$area_data, n = 5)| Country..Name. | ASFIS.species..Name. | FAO.major.fishing.area..Name. | Unit..Name. | Unit | Year | Production | Production.Type | |
|---|---|---|---|---|---|---|---|---|
| 51634 | Belgium | European eel | Atlantic, Northeast | Tonnes - live weight | TLW, Number | 2018 | 1.0 | actual |
| 51635 | Belgium | European eel | Atlantic, Northeast | Tonnes - live weight | TLW, Number | 2019 | 1.0 | actual |
| 51636 | Belgium | European eel | Atlantic, Northeast | Tonnes - live weight | TLW, Number | 2020 | 0.7 | actual |
| 51637 | Belgium | European eel | Atlantic, Northeast | Tonnes - live weight | TLW, Number | 2021 | 1.0 | actual |
| 51638 | Belgium | European eel | Atlantic, Northeast | Tonnes - live weight | TLW, Number | 2022 | 0.0 | actual |
Any other area works the same way. The names of the FAO major fishing areas are:
data <- load_fao_data()
sort(unique(data$FAO.major.fishing.area..Name.))
#> [1] "Africa - Inland waters" "America, North - Inland waters"
#> [3] "America, South - Inland waters" "Arctic Sea"
#> [5] "Asia - Inland waters" "Atlantic, Antarctic"
#> [7] "Atlantic, Eastern Central" "Atlantic, Northeast"
#> [9] "Atlantic, Northwest" "Atlantic, Southeast"
#> [11] "Atlantic, Southwest" "Atlantic, Western Central"
#> [13] "Europe - Inland waters" "Former USSR area - Inland waters"
#> [15] "Indian Ocean, Antarctic" "Indian Ocean, Eastern"
#> [17] "Indian Ocean, Western" "Mediterranean and Black Sea"
#> [19] "Oceania - Inland waters" "Pacific, Antarctic"
#> [21] "Pacific, Eastern Central" "Pacific, Northeast"
#> [23] "Pacific, Northwest" "Pacific, Southeast"
#> [25] "Pacific, Southwest" "Pacific, Western Central"๐ Main species and countries
The ten species with the largest catch in area 27, their catch over time and the breakpoints of their mean catch:
species <- fishing_area_species(FAO27$area_data, rank_range = 1:10)
The same for the countries:
countries <- fishing_area_country(FAO27$area_data, rank_range = 1:10)
rank_range lists the ranks shown: 1:10 the
first ten, 11:20 the next ten, c(5, 6) the
fifth and the sixth.
๐ฅ๏ธ What you see in the console
When a function finishes, it shows a short summary of its results in
the console: what was analysed, the first rows of its main table, the
charts and tables it saved, and the parts of the result it returns. The
result itself is returned invisibly: assign it
(species <- ...) to keep it. Here the fifth and the
sixth species:
fao_settings(show_data = TRUE) # the default (the articles of this site turn it off)
species56 <- fishing_area_species(FAO27$area_data, rank_range = c(5, 6))
#>
#> โโ fishing_area_species(): Atlantic, Northeast โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
#> Ranks 5 to 6 of 1029 species items, by catch over all years (catch_t and share_pct: all years):
#> rank species catch_t share_pct
#> 5 Atlantic mackerel 44,615,940 6.19
#> 6 Sandeels(=Sandlances) nei 33,532,765 4.65
#> Charts saved in figures/png/area/: area_species.png, area_species_wrap.png
#> Tables saved in tables/: species_ranked_table.csv, species_coefs_data.csv
#> Results returned: $area_species, $area_species_ranked, $area_species_ranked_total, $coefs_data
fao_settings(show_data = FALSE)plot_show = TRUE also draws each chart in the plot
window (the Plots pane of RStudio) as it is saved;
plot = TRUE keeps saving the chart files either way:
species <- fishing_area_species(FAO27$area_data, rank_range = 1:10, plot_show = TRUE)
fao_settings(plot_show = TRUE) # every function of the session draws its charts
fao_settings(show_data = FALSE) # no summaries in the console๐ Chinese and bilingual charts
Every analysis has a lang argument: "en"
(English), "zh" (Chinese) or "both". Country,
species and area names use the official FAO Chinese names.
species_country(FAO27$area_data, species_name = "Atlantic cod", lang = "both")
To use Chinese everywhere, set it once with
fao_settings(lang = "zh").
๐ A first summary: stock status
stock_status() classifies each species by its catch
relative to its peak catch (stock status plots, Kleisner et
al.ย 2013):
status <- stock_status(FAO27$area_data)
๐ A Word report in one call
fao_report() runs the analyses of an area and writes a
Word report with cover, abstract, data sources and methods, results with
charts and tables, conclusions, references and appendix tables. The area
can be given by its name or its code:
fao_report(27, lang = "en") # writes reports/FAO27_report_en.docx in the working folderBy default the report has the total catch and its stages, the main species and countries, the ISSCAAP groups, the stock status plots, the data quality, the diversity of the catch and the coastal and distant-water fleets. Catch shocks, collapses, synchrony, the pelagic/demersal ratio, the mean temperature of the catch, distant-water fleet profiles and CMSY++ can be switched on. See ๐ Assessment report: Word, LaTeX and PDF for all its settings.
โ๏ธ Settings of the functions on this page
The arguments shared by the analyses:
| Argument | Meaning | Default |
|---|---|---|
lang |
Language of the chart text and names: "en",
"zh" or "both"
|
NULL: the language of fao_settings()
("en" unless changed) |
plot |
Save the charts | TRUE |
table |
Save the tables in tables/ (not in
fishing_area_data()) |
TRUE |
pptx |
Also save the charts as editable PowerPoint files |
FALSE, or pptx of
fao_settings()
|
plot_show |
Also draw each chart in the plot window (e.g.ย the Plots pane of RStudio) as it is saved |
FALSE, or plot_show of
fao_settings()
|
ZH |
Older way of asking for Chinese: ZH = TRUE is
lang = "zh" (only in the fishing area, species and country
functions) |
FALSE |
label |
Name used in the output files of the summary analyses,
e.g.ย stock_status()
|
NULL: the fishing area (or country) of the data |
Every function has its own arguments as well; each article has a table of all of them:
| Functions | Main arguments | All arguments |
|---|---|---|
check_fao_update(), download_fao_data(),
load_fao_data(), fao_data_info()
|
version, data_dir, overwrite,
quiet
|
๐พ FAO data |
fishing_area_data() |
area_name, timeseries_analysis,
data_version, colours and text sizes |
๐ Fishing area analysis |
fishing_area_species(),
fishing_area_country()
|
rank_range, timeseries_analysis,
h_value, line and text styles |
๐ Fishing area analysis |
species_country() |
species_name, rank_range,
h_value, map style |
๐ Species and countries |
stock_status() |
taxon_levels, min_years,
min_consecutive, min_catch,
smooth
|
๐ Composition, stock status and trends |
fao_report() |
area, lang, file, sections
switched on or off, settings of each analysis |
๐ Assessment report: Word, LaTeX and PDF |
fao_settings(), fao_font()
|
lang, theme, palette,
map_projection, dpi, โฆ |
๐จ Customise charts and maps |
๐งญ Next steps
- ๐ Tutorial: FAO area 67 from zero to a report: a complete worked example, with every analysis of the package and how to read each chart
- ๐พ FAO data: download and customise: releases, data format, subsets, Chinese names
- ๐ Fishing area analysis: all options of the fishing area functions
-
๐ Species and countries:
species_country(),country_species(),country_analysis() - ๐ Composition, stock status and trends and ๐ Data quality, diversity and fleets: the summary analyses
- ๐ฌ Shocks, collapses, synchrony and fleets: methods from the literature (catch shocks, fishery collapses, synchrony and the portfolio effect, distant-water fleets, revisions between FAO releases)
- ๐ก๏ธ Sea temperature and catch temperature: SST of the fishing areas (built in or from your own NetCDF files) and the mean temperature of the catch
- ๐ FishBase and SeaLifeBase traits: match FAO species items to FishBase and SeaLifeBase and use their traits
- ๐ CMSY++ stock assessment: catch-only stock assessment of the main species
- ๐ Assessment report: Word, LaTeX and PDF: the whole analysis of an area as a Word report
- ๐งฉ Extension, not part of the Word report: ๐ข Trade and employment: exports and imports compared with the catch, people in fisheries and aquaculture, and catch per fisher
- ๐จ Customise charts and maps: themes, palettes, map projections, fonts and output
๐ References
Bai, J. and Perron, P. (2003). Computation and analysis of multiple structural change models. Journal of Applied Econometrics 18(1): 1โ22. doi:10.1002/jae.659
CWP (Coordinating Working Party on Fishery Statistics). CWP Handbook of Fishery Statistics: Main water areas (FAO major fishing areas). Rome: FAO. https://www.fao.org/cwp-on-fishery-statistics/handbook/general-concepts/main-water-areas/en/
FAO (2026). FishStat: Global capture production 1950โ2024 (release 2026.1.0). In: FishStatJ. https://www.fao.org/fishery/statistics/software/fishstatj/en. Licence: CC-BY-4.0. Release file: https://www.fao.org/fishery/static/Data/Capture_2026.1.0.zip
FAO (2026). Fishery and Aquaculture Statistics โ Yearbook 2024. FAO Yearbook of Fishery and Aquaculture Statistics. Rome: FAO. doi:10.4060/ce1217en
Kleisner, K., Zeller, D., Froese, R. and Pauly, D. (2013). Using global catch data for inferences on the worldโs marine fisheries. Fish and Fisheries 14(3): 293โ311. doi:10.1111/j.1467-2979.2012.00469.x
Natural Earth. Free vector and raster map data at 1:10m, 1:50m and 1:110m scales. https://www.naturalearthdata.com/
Zeileis, A., Kleiber, C., Krรคmer, W. and Hornik, K. (2003). Testing and dating of structural changes in practice. Computational Statistics & Data Analysis 44(1โ2): 109โ123. doi:10.1016/S0167-9473(03)00030-6
Zeileis, A., Leisch, F., Hornik, K. and Kleiber, C. (2002). strucchange: an R package for testing for structural change in linear regression models. Journal of Statistical Software 7(2): 1โ38. doi:10.18637/jss.v007.i02