Skip to contents

Changelog

Source: NEWS.md

faofishingreport 1.0.0

Changes that need attention

  • rank_range of fishing_area_species(), fishing_area_country(), species_country(), country_species() and country_analysis() lists the ranks to show: 1:10 (the new default) for the first ten, 11:20 for the next ten, c(5, 6) for the fifth and the sixth. Until 0.9.0 two numbers were the first and the last rank, so c(1, 10) now shows only ranks 1 and 10; a note says so once per session. Ranks beyond the data are left out, and an error is given when none is left. The report (fao_report()) uses the first top_n ranks as before.
  • The analysis functions return their results invisibly, after a summary in the console (below): assign them to keep them, e.g. species <- fishing_area_species(...). The list returned by species_country() with timeseries_analysis = TRUE has names (species_country_ranked, coefs_data); [[1]] and [[2]] still work.

Results in the console and charts on screen

  • When an analysis finishes, it shows a short summary in the console: what was analysed, the first rows of its main table (e.g. the species at the chosen ranks with their catch and share), the charts and tables it saved, and the parts of the result it returns. fao_settings(show_data = FALSE) turns the summaries off. The functions run by another one (e.g. by fao_report() or cmsy_area()) stay quiet, and the CMSY++ functions follow their silent argument.
  • New argument plot_show of every function that draws charts, and setting fao_settings(plot_show = TRUE) for all of them: each chart is also drawn in the plot window (e.g. the Plots pane of RStudio) as it is saved. plot = TRUE still saves the chart files, and plot_show is FALSE by default.

Website

  • Every article ends with links to the previous and the next article, in the order of the menu, and to the list of all articles.
  • The last section of the fishing area article shows the Northwest Atlantic (area 21), whose Atlantic cod collapsed in the early 1990s (Hutchings and Myers 1994), instead of the Northwest Pacific. The get-started article shows the summary in the console and plot_show.
  • The examples of the function reference use area 27 instead of area 34.

faofishingreport 0.9.0

Charts

  • fishing_area_map() saves each map with the shape of the area: the height follows the width and length of the map (between 4 and 14 inches for a width of 10), so wide maps such as the polar map of area 27 no longer have empty bands above and below.
  • The example charts of the home pages (README) are made at 300 dpi instead of 90, so the maps are sharp.
  • fao_report() has a dpi argument for the resolution of the charts of the report (300 by default, e.g. 600 for print); it was always 300. The other functions keep their resolution set with fao_settings(dpi = ) (600 by default).

Fixes

  • Reading the tables bundled with the package no longer gives a warning about translating the byte order mark of the files in some locales.

Example scripts

  • The example scripts in the Demo/ folder of the GitHub repository (not part of the installed package) now use the areas of the articles: Demo_FAO27.R, the whole workflow for the Northeast Atlantic (maps, species and countries, summaries, temperature, CMSY++ with its MCMC check and the report), and Demo_FAO67.R, the code of the Northeast Pacific tutorial. The area 34 script was removed.

faofishingreport 0.8.0

New functions

  • fao_areas() lists the FAO major fishing areas (the 19 marine areas and the inland waters of each continent) with their code, name, ocean, catch in the last year of the data and the link to the official FAO map of each area (https://www.fao.org/fishery/docs/maps/Default.htm), and saves a world map of the marine areas labelled with their codes.

  • fishing_area_map() maps one marine area with its subareas, divisions or subdivisions, labelled with their codes, from the boundaries bundled with the package. When the ggOceanMaps package (Vihtakari 2026, https://github.com/MikkoVihtakari/ggOceanMaps, now in Suggests) is installed, the map is drawn on its bathymetric base map, with the depth of the ETOPO 2022 relief model bundled with ggOceanMaps (polar stereographic for areas reaching beyond 60° of latitude); without it, the land of Natural Earth is drawn in a Lambert azimuthal equal-area projection centred on the area. The result lists the boundaries, base map and depth data used, to cite with the map.

  • cmsy_mcmc() shows the MCMC settings of each CMSY++ run (chains, iterations, burn-in, thinning) and whether it converged: for r, k, MSY, B/k, B/Bmsy and F/Fmsy, the posterior summary, Rhat (Gelman and Rubin 1992) and the effective sample size (coda), with the stocks that did not converge (Rhat above 1.1) or have too few effective draws (below 400) reported apart, and a chart of the trace and density of each chain (also the new “mcmc” chart of cmsy_plot()). The colours of the chains can be chosen (colors, mcmc_colors). cmsy_run() keeps the draws of each chain for it; the CMSY++ model is not changed. With the settings of CMSY++16.R (2 chains of 60,000 iterations, thinned by 10), the effective sample size of r and k is often only a few hundred; longer and more chains raise it.

  • The Word report gives the MCMC settings, the largest Rhat and the smallest effective sample size of the CMSY++ runs, and names the stocks that did not converge or have too few effective draws.

Bug fixes

  • The tables bundled with the package (chart labels, Chinese names, ISSCAAP groups, SST) and the CSV files written by the package are read as UTF-8 in any locale. In a locale that is not UTF-8 (e.g. “C” on some Linux servers) the Chinese text could not be read, so every chart stopped with “Unknown chart label”.

Documentation

  • The home pages start with an introduction to the FAO major fishing areas: the 19 marine areas with their code, name, extent and official FAO map, and the inland areas.
  • The examples of the home pages and of all articles use the Northeast Atlantic (FAO area 27) instead of the Eastern Central Atlantic (area 34): Atlantic cod and Norway are the example species and country, and the CMSY++ article shows the 30 main stocks of area 27 with a healthy and an overfished stock in detail. Facts about area 34 used to explain a rule (the coastal countries through overseas territories, the share of estimated catch) are kept and say so.
  • The fishing area article describes fao_areas() and fishing_area_map(), with the references of ggOceanMaps, ETOPO 2022 and the FAO fishing area maps.

Website

  • Headings are in the deep blue of the logo and the body text near-black, so that headings stand apart from the content.

faofishingreport 0.7.0

This version corrects errors found in a review of the code and of the statistics. Some results change: see “Changed results”.

Changed results

  • cmsy_forecast() follows the timing of CMSY++: the biomass of a year is the biomass before that year’s catch, the last year of the data keeps its catch, and the catch of an F scenario is the scenario F times the biomass of the same year. F/Fmsy uses an Fmsy reduced below half of Bmsy, as in CMSY++, so it equals the scenario value (before, 0.5 Fmsy gave 0.45). Projections differ from those of earlier versions.
  • Trends in peak_trend(), mean_temperature_catch() and the report are tested with a Mann-Kendall test whose variance is corrected for autocorrelation (Yue and Wang 2004); p_value_iid keeps the p value of the usual test and lag1_autocorrelation the autocorrelation used. peak_trend() adds q_value, the p values adjusted for the number of series (Benjamini and Hochberg 1995), and the report calls a trend of a main species or country significant only when its q value is below 0.05. Fewer trends are significant than before.
  • catch_synchrony(): share_of_variability_pct, the share of each standard deviation in their sum, is renamed sd_share_pct, and the new variance_contribution_pct gives the contribution of each series to the variance of the total catch (its covariance with the total). The report names the series that contribute most to the variance.
  • catch_shocks(): the yearly shock frequency divides by the series analysed in that year, including series whose catch fell to zero, so it can no longer exceed 100%.
  • Decade means (tables of fishing_area_species(), fishing_area_country(), species_country(), country_species(), country_analysis() and the appendix of the report) divide the catch of a decade by the years of the data in that decade, the same for every item; before, they depended on the years an item or the items chosen had records, and country_analysis() averaged the rows of several areas.
  • Employment, catch per fisher and trade: years that a country did not report are missing (NA), not zero, and missing trade quantities stay missing; a group or flow not reported in a year that the country did report is zero. The employment chart shows stacked bars by year, with gaps for years not reported.
  • SST from NetCDF files: the weights of the grid cells are saved by grid and cover every cell with values, also cells without values in the first year; dates follow the calendar of the file (360-day, 365-day and 366-day calendars) and the time of the origin. Tables computed from your own files with earlier versions are computed again the next time they are used.
  • catch_synchrony() computes moving windows as soon as the series are as long as the window (20 years give one window).

CMSY++ integration

These changes concern how the package runs CMSY++. The model of CMSY++16.R is unchanged, and no change was added to its code (the changes the package makes to run it, for file names, graphics devices and saving results, are listed in code_changes.csv of each run and in result$changes).

  • sigmaR and ni are set in CMSY++16.R but not used by its code (the process error of the model is estimated with the prior itau2 ~ dgamma(4, 0.01)): cmsy_defaults() lists them as “not used”, and cmsy_run(settings = ) refuses to change them, so that a run is not taken for a sensitivity analysis of the process error. Examples use CV.C instead.
  • B/k and r priors must be given as pairs of lower and upper bounds (CMSY++ uses a prior only when both are given), with lower < upper, B/k between 0 and 1, and an intermediate prior with a year between the start and end years; cmsy_input() and cmsy_run() stop with the stocks concerned. A prior is recorded as the user’s only when both bounds are given.
  • Stocks by country of countries without an ISO3 code (e.g. “Germany, Fed. Rep. of” and “Germany,New Länder”) get the numeric code of the FAO country list (“COD_27_UN280”) instead of sharing “XXX”; cmsy_input() and cmsy_run() check that stock identifiers, folders and stock-year catches are unique.
  • cmsy_run() reports how each run ended: run_status is “ok” (finished), “partial” (the main analysis saved its results but a later step, such as the retrospective analysis, failed or ran out of time), “failed” or “timeout”, and exit keeps the original message; a stock that runs out of time is stopped. Results of “ok” and “partial” stocks are used by the other functions.
  • auto_start = TRUE smooths the catch with the bandwidth bw of the run, as CMSY++ does, instead of always 3.
  • The report says that the CMSY++ results are completed model runs and, when the B/k priors came from the neural network, that these were not checked stock by stock (the CMSY++ user guide notes they “may not be appropriate for your stock”), so the results are not validated assessments.

Bug fixes

  • fao_report(): the charts of the main species and countries show the items of the tables, ranked by the last five years (new argument rank_years of fishing_area_species() and fishing_area_country()); a CMSY++ result given with cmsy = must be of the area and FAO release of the report; collapse_null_model = FALSE, groups_group = "major" and own pelagic and demersal groups (pelagic_pelagic, pelagic_demersal) are described in the text as used; the portfolio effect is described as positive, absent or negative; a slope of the mean temperature of the catch without a significant trend keeps its sign.
  • cmsy_input(): a prior row with a Stock applies to that stock only, rows for a species are applied before rows for one stock, and a Resilience given without r.low and r.hi replaces the FishBase r range; when no stock is ready, the excluded stocks are returned instead of an error.
  • cmsy_area() keeps the results of an earlier run until the new run has finished, and stops before deleting anything when the input is wrong.
  • cmsy_forecast() projects stocks whose data end in different years to the same final year, and the share of stocks at or above Bmsy gives the number of stocks.
  • fishing_area_data() keeps the FAO release of the data, so cmsy_input() records the release actually used; when data do not record it, cmsy_input() says which release is assumed.
  • regime_shift() leaves out species without catch instead of stopping.
  • The tables of species_country() keep “Other nei” when it is among the ranked countries.
  • fao_report(): the stock status paragraph gave the shares of collapsed and rebuilding stocks in the wrong order, and its total of over-exploited and collapsed stocks added rebuilding stocks instead of collapsed ones.
  • fao_report(): the Word file gives the author of the report as “last modified by”, not the login name of the computer that wrote it.
  • Report text: the abstract no longer opens with a general sentence on the area or ends with a recommendation; the sentence on under-reporting cites Garibaldi (2012); the conclusion on diversity gives the HHI, and equal concentration by species and by country is said once; the P/D paragraph and conclusion do not name the most recent period twice; counts of CMSY++ stocks agree with their verbs and say “no stock” (“没有种群”) instead of 0; English sentences no longer start with a number; lists whose items contain commas are separated by semicolons; Chinese notes no longer open with “需要指出的是”.
  • cmsy_input() and cmsy_area() messages say “1 stock” instead of “1 stocks”.

Website

  • Pages are less crowded: wider line spacing (above all in Chinese), main sections separated by a thin line, subsections marked with a bar, and more space between paragraphs, list items, code, tables and figures.
  • In the tutorial, the explanation under each chart (“How to read it” and the result for area 67) is in its own box, with a dashed line before the result, so that each chart and its text stand apart from the next chart.
  • The documentation links on the home pages are grouped (start here, data and analyses, assessment and report, more) instead of one run of links.
  • Charts in the articles no longer show the path of their file below them.
  • The home page (the README) always opens in English, also after Chinese pages were visited (other pages keep the chosen language); the Chinese home page links to it at its top.

faofishingreport 0.6.0

Documentation

  • The tutorial now takes the Northeast Pacific (FAO area 67: the eastern Bering Sea, the Gulf of Alaska and the coasts of Canada and the United States) from an empty R session to a finished report, in English and Chinese. It replaces the tutorial on area 61, and the old pages redirect to it. Area 67 shows clearly how fleets and management shape catch statistics: the distant-water fleets of Japan and the USSR, the 200-mile fishery zones of 1977 and the growth of the US fleets. Its CMSY++ charts are made by data-raw/tutorial67_figures.R.
  • How to install TinyTeX, which compiles the PDF report, is explained in the report article (new section “Install TinyTeX (once)”), in the tutorial and in the help of fao_report(), with what to do when TinyTeX is old or another LaTeX distribution is used.

Changes

faofishingreport 0.5.0

Documentation

  • A new tutorial, in English and Chinese, takes a complete assessment of the Northwest Pacific (FAO area 61) from an empty R session to a finished report (replaced by the tutorial on area 67 in 0.6.0): getting the data and knowing its release, every analysis of the package step by step, how to read each chart and what it shows for the area (with the numbers computed when the page is built), the files the package saves and how to read them back, and the report as Word, LaTeX and PDF. Its CMSY++ charts are made by data-raw/tutorial61_figures.R.

Changes

  • fishing_area_data(), fishing_area_species(), fishing_area_country(), species_country(), country_species() and country_analysis() no longer print their intermediate tables in the console (they are returned and saved in tables/); options(faofishingreport.verbose = TRUE) prints them again.
  • The colour bars of the maps are wider, so their labels no longer overlap.
  • The trend segments of the older charts use linewidth, so ggplot2 no longer warns that size is deprecated for lines.
  • The Chinese data-source box at the top of the website articles has no spaces between Chinese and Latin text.

faofishingreport 0.4.0

New features

  • fao_report(format = ) writes the report as Word ("docx", default), LaTeX ("latex") and PDF ("pdf"), one or more. The analyses run once and all formats have the same text, figures, tables, captions and references. The LaTeX file (with its figures in a folder next to it) follows the format of the Word report: the ctexart class with FangSong, SimHei and KaiTi (or the fonts of macOS, or the Fandol fonts of TeX Live) for Chinese reports, the article class for English reports, three-line tables that run over pages, numbered captions, page numbers from the title page and PDF bookmarks. PDFs are compiled with XeLaTeX through tinytex when it is installed (which installs missing LaTeX packages), else with the xelatex of the system.
  • The website links to the FAO sources (FAO, FAOSTAT, Global Capture Production and the FAO fishery data files) in the sidebar of the home page and in the footer of every page, with the note “This package is not affiliated with FAO; the data come from FAO” (“本包与FAO无关联，数据来源为FAO”); the README and the Chinese home page give the same links and note.
  • The Chinese function reference covers the new functions (62 pages).

Extensions: other FAO datasets

These functions use FAO fishery statistics other than global capture production. They are an extension of the package and not part of the Word report (fao_report()).

  • Catch by division: load_fao_divisions() downloads and loads the FAO capture data by division of four regional fishery bodies (GFCM in area 37, CECAF in area 34, the Southeast Atlantic in area 47 and RECOFI in part of area 51), in the package format with the columns Division, Division..Name. and Region. pelagic_demersal() and mean_temperature_catch() gain by = "division", and fao_area_sst(level = "division") gives the SST of the FAO subareas and divisions (built in for areas 34, 37, 47 and 51 from NOAA ERSST v5; all of them from downloaded products or the user’s own NetCDF files). Divisions without a boundary on the FAO map use the SST of their subarea, and the functions say when the SST of a division rests on fewer than 5 grid cells.
  • Trade: load_fao_trade() downloads and loads the FAO statistics of the trade of aquatic products (FI_Trade: exports, imports and re-exports of each country by ISSCFC commodity and year from 1976, quantity in tonnes product weight and value in thousand USD, each commodity with its ISSCAAP group). catch_trade() compares a country’s catch with its exports and imports of the same ISSCAAP groups, by year and by group: exports as a share of the catch, net trade, unit values, the share of the export value estimated or taken from partner reports, and, with conversion factors given by the user, trade in live weight equivalent and the apparent supply (catch + imports - exports - re-exports). Because trade statistics do not tell whether a product was caught or farmed, only the groups mostly caught are compared (capture at least 90% of world production in every year; fao_capture_groups(), from FAO global production data built into the package); fishmeal and fish oil not assigned to a species group are reported separately.
  • Employment: load_fao_employment() downloads and loads the FAO statistics of the people employed in fisheries and aquaculture (FI_Employment, first disseminated in 2026: by country, work area, working time and sex from 1995), with FAO’s notes on individual countries. employment_summary() gives the people in aquaculture, marine and inland fishing and unspecified work areas by year, for countries or the world, with the shares of women and full-time workers among those known and the shares unknown (as FAO does in The State of World Fisheries and Aquaculture). catch_per_fisher() divides marine and inland catch by marine and inland fishers (FAO 2012, table 9), as people or as full-time equivalents with the weights of Scherrer et al. (2024), and flags workers of unspecified work area, estimated values and numbers carried forward unchanged. The article “Trade and employment” shows both datasets and what others did with them.

Bug fixes

  • fao_area_sst(sst = "ersst5") and mean_temperature_catch() use the downloaded ERSST v5 tables together with the built-in ones: the subareas and divisions the built-in table lacks were left out unless the download reached a later year.
  • mean_temperature_catch(by = "division", sst = <table>) matches an SST table keyed by area_en to the divisions (it found no SST before), and says when no SST matches; the check for the division columns now comes before the FishBase matching.
  • fao_capture_groups(years = ) gives the years covered by its table when none of years is in it.
  • The SST area weights computed before are found again (their cache name had changed).
  • fao_report(pelagic_by = , mtc_by = ) explains that the analyses by division are an extension outside the report.
  • Help pages of the new functions: defaults of label, the columns of catch_trade()$groups, meal_oil_export_value, the file names with by = "division", and the shares of fao_capture_groups().

Other changes

  • The CMSY++ tests of the three-system check run on the installed package, so they also run on macOS without XQuartz.

faofishingreport 0.3.0

New features

  • fao_report() writes a Word report of an FAO fishing area in Chinese or English, in one call: cover, title, abstract, data and methods, results and conclusions with charts and tables, references and appendix. The text is written from templates filled in with the results (inst/extdata/report_text.csv), as a first draft to complete by hand. Chinese reports follow the format of project reports (FangSong and Times New Roman, 1.5 line spacing, three-line tables, numbered GB/T 7714 references); English reports use Arial by default and APA or FAO citations. With cmsy = TRUE, the main species (by default as many as top_n, or cmsy_top) are also assessed with CMSY++ (cmsy_area()), and the report ends with a section on the assessment: an overview with the results table and Kobe plot, and the results of every species. Scientific names are in italics (species and genera) in the text and the tables. Every analysis is a section switched on or off (total, species, countries, groups, status, quality, diversity and fleets by default; shocks, collapse, synchrony, pelagic, mtc, distant and cmsy when asked), and the settings of its function are given with the section as prefix (e.g. species_h_value = 0.2, collapse_method = "worm2006", cmsy_top = 5). The abstract, methods, conclusions and references follow the sections of the report. It returns the tables of the report and the results of all analyses as data frames, including the CMSY++ reference points, priors and the links to their sources.
  • The website has a guide for every part of the package, illustrated with FAO area 34, in English and Chinese, with tables of all arguments of every function, examples and a reference list with the DOI or link of every method and data source: getting started, FAO data, fishing areas, species and countries, composition and stock status, data quality and fleets, shocks, collapses and synchrony, sea temperature and the mean temperature of the catch, FishBase traits, CMSY++, the Word report and customisation. Every function reference page has a Chinese version with the English original of each part beside it (data-raw/make_zh_reference.R), and the language button switches between them.
  • New version of the logo.
  • CMSY++ disclaimer and source: the CMSY++ article, cmsy_sources(), the bundled inst/cmsy/README.md and the README state that the bundled code is that of the CMSY++ authors (March 2021 release, also on GitHub at https://github.com/SISTA16/cmsyPlusPlus), run without changes to the method, and that faofishingreport is not affiliated with or endorsed by them. The runs test of the archived snpar package, which CMSY++ uses and cmsy_run() reproduces, is credited with its source (snpar 1.0, Debin Qiu; CRAN archive and https://github.com/cran/snpar) in cmsy_sources(), cmsy_system(), the code of each run and the CMSY++ article.
  • Sources of the FishBase data: fishbase_sources(), the help pages and the FishBase and CMSY++ articles cite the rfishbase project that publishes the data snapshots (Boettiger et al. 2012; https://github.com/ropensci/rfishbase).
  • The packages used by the analyses (officer and xml2 for Word reports, eoffice for PowerPoint, nanoparquet for FishBase, ncdf4 for sea surface temperature, and the R packages of CMSY++ except rjags and R2jags, which need JAGS: see cmsy_setup()) are installed with the package. They are loaded only when needed, so the package also loads on macOS without XQuartz (needed by eoffice).
  • Analyses that follow published methods, each citing its sources:
    • catch_shocks() finds abrupt falls in catch with the method of Cottrell et al. (2019; LOESS span 0.6, Cook’s distance > 0.3 in a lag-1 residual regression, loss against the 7-year median) or Gephart et al. (2017; lowess span 2/3, Cook’s distance > 0.35, 5-year mean), and gives the shock frequency by year and the shock rate by area, country, species group or continent, with the loss and the years to recovery of each shock.
    • collapse_analysis() finds collapsed catch series with the definition of Mullon et al. (2005; catch below 1/10 of the maximum for 4 years after the maximum, for species x country x area series) and classifies the decline before each collapse as plateau, smooth or erratic, or with the definition of Worm et al. (2006; catch below 10% of the maximum, the share of fisheries collapsed in each year and collapsed at least once). It repeats the analysis on random series with no trend (Wilberg and Miller 2007) for comparison. On the world marine data for 1950-2000 it finds 24.9% of series collapsed, as Mullon et al. (24%).
    • catch_synchrony() measures how synchronously the catches of species (or countries) fluctuate and how much this stabilises the total: the synchrony index phi of Loreau and de Mazancourt (2008), the decomposition CV of the total = sqrt(phi) x weighted mean CV of Thibaut and Connolly (2013), the portfolio effect and series selection of Ong et al. (2021), and pairwise correlations, on series detrended with a linear trend (Lepš et al. 2019), for the whole period and in moving windows.
    • distant_water_profile() follows a country’s catch in the FAO areas it borders and in distant-water areas, its distant-water share, the number of FAO areas it fishes each year and when it entered each area (spatial expansion; Swartz et al. 2010), with a note on China’s distant-water catch entered in area 61 since 2022 (FAO 2024).
    • compare_releases() compares two FAO releases record by record and lists revised, added, removed and reclassified records, with the revision of each year and country (the “presentist bias” of Zeller and Pauly 2018).
    • pelagic_demersal() computes the ratio of pelagic to demersal catch (P/D; Caddy 1993) of each FAO marine area by year and by decade (mean, lowest and highest yearly ratio). ISSCAAP groups are counted as in de Leiva Moreno et al. (2000; small pelagics against demersal fishes and crustaceans, the default) or Grainger and Garcia (1996; all pelagic against all demersal fishes), or as chosen; fao_pd_groups() lists how each group is counted. It reports the share of the catch counted and of unidentified marine fishes, and its help page states what besides nutrients changes the ratio (fishing and markets, hypoxia, natural variability of small pelagics, reporting).
  • mean_temperature_catch(): the mean temperature of the catch (MTC; Cheung et al. 2013) of each FAO fishing area, the catch-weighted mean of the species’ preferred temperatures in FishBase and SeaLifeBase, compared with the sea surface temperature of the area. It gives the coverage of the catch, slopes and Mann-Kendall trends over all years and since 1970, the correlation with SST (also of year-to-year differences), and a species table with each item’s weight, contribution and links to FishBase, SeaLifeBase and WoRMS. Only species-level items matched by name, by an official synonym, through WoRMS or by a manual correction are used. The preferred temperatures are automatic first matches: users check them with the links, mark them in the checked column and run the function again with the checked table; charts say when not all have been checked.
  • fao_area_sst(): yearly sea surface temperature (SST) of the 19 FAO major marine fishing areas: the area mean, the range within the area (10th-90th percentile of the grid cells) and the seasonal range (coldest and warmest month). The package comes with one SST product, NOAA ERSST v5 (2°, 1950-2025, in situ observations only), the smallest to keep the package small. Any other gridded SST can be used by giving the path of its NetCDF file or folder, as sst = "path" or once with fao_settings(sst = "path"): the area means are computed on the user’s computer the first time and saved. download_sst_data() downloads HadISST1, COBE-SST2 or OISST v2.1 for this, and fao_sst_products() describes them. Every function says which SST data it uses.
  • download_fishbase_data(), check_fishbase_update() and fishbase_table() keep a copy of the FishBase and SeaLifeBase snapshots (the parquet files used by rfishbase; CC BY-NC 4.0, FishBase.org team) for offline use. Downloading is optional: functions download the tables they need when online; download_fishbase_data() downloads the tables the package uses (about 30 MB) or every table (tables = "all", about 250 MB), and first says what is downloaded, from where, under which licence and by which rules it is used. When offline, or with fao_settings(online = FALSE), the newest downloaded release is used, and when nothing has been downloaded, fishbase_match() uses a table built into the package (FishBase and SeaLifeBase 26.06, made by data-raw/build_fishbase_traits.R).
  • fishbase_sources() lists the data sources, licences and citations, the tables downloaded and what they hold, and every matching rule with its published source.
  • The data folder can also be set with the environment variable FAOFISHINGREPORT_DATA_DIR (e.g. in .Renviron), so several computers or a team can share one folder.
  • fishbase_match() matches the FAO species items of the data one by one to FishBase and SeaLifeBase, only by published rules: an exact valid name, an official synonym, the valid name in WoRMS (looked up online and saved for offline use), the mean trophic level of the species of a genus, family or higher taxon (Branch et al. 2010), or trophic level 1 for plants. Each row gives the rule and its source and links to the FishBase, SeaLifeBase or WoRMS pages; items no rule covers are marked as failed with search links, and can be corrected in a shared corrections.csv.
  • CMSY++ catch-only stock assessment (Froese et al. 2023), with the official CMSY++ code, neural network and user guide (March 2021, CC BY 4.0) bundled in inst/cmsy/:
    • cmsy_system() detects the operating system, R version, JAGS and R packages, and shows the settings used on it: the changes the user guide asks Mac users to make (windows() to quartz(), antialias = "cleartype" to "default") are made automatically in a copy of the code, the system can be set by hand, and charts are saved through an off-screen device on every system. The archived snpar package, RStudio and the automatic package installation are no longer needed.
    • cmsy_setup() and cmsy_install_jags() install the R packages and download and open the JAGS installer for the system (JAGS 4.3.2 by default, 5.0.0 with jags = "latest"), checking its size and checksum; cmsy_sources() lists the version, link, checksums, licence and reference of every component.
    • cmsy_priors() searches a built-in table (offline) of the resilience and prior r of 3,155 FAO species in FishBase and SeaLifeBase 26.06, with a link to the page of each species; r ranges follow the CMSY++ user guide.
    • cmsy_input() turns FAO catch data into the CMSY++ catch and ID files (catch only: FAO data have no abundance index), cmsy_run() runs CMSY++ on each stock in its own folder and R process and returns MSY, B/Bmsy, F/Fmsy, Kobe probabilities and the status in FAO’s two classes for catch-only results, and cmsy_plot() draws the results in English, Chinese or both.
    • cmsy_area() runs CMSY++ in one call for the species with the largest catch in one or more fishing areas (or chosen species), with charts, projections and tables, and saves each area in its own folder (input/, runs/, figures/, tables/).
    • cmsy_plot() draws every chart of the CMSY++ user guide (analysis and management panels, r-k pairs, B/k with its priors, Kobe plot with 50/80/95% regions and quadrant probabilities, prior-posterior densities with PPVR, retrospective analysis with Mohn’s rho) and the summaries common in CMSY papers (overview, Kobe plot of all stocks, status shares by number and catch and over time, B/Bmsy histogram and small multiples, trends, totals relative to MSY and Bmsy, map), with FAO or Palomares et al. (2018) status classes. Charts show only axis text by default; annotations adds titles, captions with sources, legends and labels.
    • cmsy_forecast() projects stocks under Fmsy fractions, status quo F or constant catch with the CMSY++ model; cmsy_compare() compares runs or other assessments; cmsy_tables() makes the priors and results tables of reports.
    • Species can be given by English or Chinese name, scientific name or FAO 3-alpha code everywhere, and every result links to its sources (FishBase page and table, CMSY++ user guide, FAO release).
    • Progress bars with elapsed and remaining time; silent = TRUE, or fao_settings(silent = TRUE), turns them and the messages off.
    • cmsy_run(settings = ) changes the general settings of CMSY++ (process error, catch CV, MCMC chains and iterations, …), which otherwise keep their CMSY++ defaults; cmsy_defaults() lists them with their defaults and meaning, checks changed values, and the values used are saved with each run.
    • cmsy_jags_versions() tells which JAGS installer (and rjags version) goes with each R version on Windows, macOS and Linux, with the evidence for each rule, and cmsy_download_jags() downloads the matching installer automatically (checksums checked), also for other systems or R versions; cmsy_setup() and cmsy_install_jags() use it.
    • The output of the CMSY++ processes is written to log.txt from within R, the same way on every system. A GitHub Actions workflow runs CMSY++ for real on Windows, macOS and Linux (JAGS downloaded with cmsy_install_jags()).

Bug fixes

  • The share chart of fishing_area_data() now gives the share of the area in the world catch of marine areas (or of inland waters, for an inland area); inland waters were counted in the world catch before.
  • peak_trend(top_n = Inf) no longer fails on series without catch or with fewer than three recent years.
  • The periods between breakpoints of fishing_area_data(), fishing_area_species(), fishing_area_country(), species_country(), country_species() and country_analysis() started or ended one year too early, and the years were wrong for series with a missing year; they now come from the years of the series.
  • species_country(), country_species() and country_analysis() no longer change options(digits, scipen) for the rest of the R session.
  • fishing_area_data(): the axis titles of the total catch chart use axis_title_size and axis_title_face (they used the axis text settings), and axis_text_face now sets its axis text.
  • collapse_analysis(method = "mullon2005"): collapses less than 10 years after the first year with catch of a series are not classified, as documented (the years before the series counted before).
  • catch_shocks(): countries without a continent (the USSR, “Other nei”) are counted as “Other” instead of NA.
  • download_sst_data("ersst5", years = ) adds the downloaded years to the built-in ERSST v5 table instead of replacing it.
  • check_fishbase_update() no longer reports an update after the default download of the tables the package needs.
  • A FishBase correction with only a SpecCode, when FishBase cannot be reached, is skipped instead of marking the item as matched without values.
  • download_fao_data() reads a release that is already downloaded without going online.
  • fao_report(): the cover shows the report number once (“Report no.: 1”); author-date citations after the authors’ names give only the year (“Caddy (1993)”); APA reference lists are ordered by all authors’ names; conference papers follow GB/T 7714 (“[C]//”); the methods give the breakpoint segment length and stock-status criteria actually used, and say when catches were smoothed.
  • Help pages: corrected defaults and return values (fishing_area_species(), fishing_area_country(), fishing_area_data(), cmsy_area()), percent signs that cut lines short, and the descriptions of arguments that were copied from other functions (cmsy_plot(), cmsy_forecast(), cmsy_compare(), cmsy_tables()).

faofishingreport 0.2.0

New features

  • A package website (https://linbojun99.github.io/faofishingreport/) with a guide for every part of the package, illustrated with FAO area 34, in English with a Chinese version (switch with the button at the top right).
  • New logo.
  • fao_data_info() shows which FAO release the analyses use, when FAO published it, the years it covers, the file it was downloaded from, its licence and a citation for reports. Every page of the website shows the release used and its download link.
  • Function reference pages of the website link to the previous and next function and list the other functions of their group; help pages link to related functions (“See also”).
  • fao_settings(data_dir = ...) keeps downloaded FAO data in a chosen folder, e.g. one shared by a team; fao_data_dir() returns it.
  • fao_settings() sets, for the session, the default language, chart theme, font size, category palette, map palette, map centre (longitudes -180 to 180 or 0 to 360), map projection (longitude-latitude, Robinson, Mollweide, Equal Earth, Winkel Tripel, Mercator, or any PROJ string or EPSG code), map colours, grid lines, PNG resolution and PowerPoint output.
  • Maps are drawn with sf: countries come from Natural Earth and are matched on ISO3 codes instead of a hand-made name list, FAO area boundaries are simplified for world maps, and maps centred on the Pacific join the parts that the data split at the dateline. Fishing area maps show land without country borders.
  • New summary analyses, each saving charts in figures/png/summary/ and tables in tables/:
    • species_group_composition(): catch by ISSCAAP species group or major group.
    • stock_status(): stock status plots (developing, exploited, over-exploited, collapsed, rebuilding) from catch relative to peak, following Kleisner et al. (2013).
    • peak_trend() and area_overview(): peak year, last year as a percentage of the peak, growth rate and Mann-Kendall trend, for species, countries or all FAO marine areas.
    • data_quality(): share of officially reported and estimated catch, and share identified to species, genus, family or higher.
    • diversity_concentration(): number of species and countries, Shannon diversity, HHI and top-N shares.
    • country_group_summary(): catch by World Bank income group, continent or region.
    • regime_shift(): breakpoints of the main species and the number of species changing in each year.
    • coastal_distant(): catch by coastal countries and distant-water fleets, from the FAO area boundaries and Natural Earth country outlines.
  • Species, country and area groups (ISSCAAP group, taxonomic level, income group, continent, region, …) are saved with each FAO release. Chart labels and the unofficial Chinese names of ISSCAAP groups, major groups and income groups are kept in editable CSV files in inst/extdata/.
  • check_fao_update(), download_fao_data() and load_fao_data() check the FAO website for the latest Global Capture Production release, download it and convert it to the package’s data format. fishing_area_data() and country_analysis() use the newest data available and gain a data_version argument.
  • All analysis functions gain a lang argument: "en", "zh" or "both" (Chinese and English on the same chart). ZH = TRUE still works and means lang = "zh".
  • Chinese names of countries, species and fishing areas now come from the FAO official code lists and the ASFIS species list (fao_translate()), with the package’s earlier tables filling the gaps.
  • The chart font is chosen for the operating system (SimSun on Windows, Songti SC on macOS, Noto Serif CJK SC on Linux) and can be changed with fao_font(). Previously “Songti SC” was hard-coded, so Chinese text did not display on Windows.
  • CSV tables are written as UTF-8 with a byte order mark, so Excel shows Chinese names correctly.
  • Charts are saved as PNG by default. Editable PowerPoint files are optional: add pptx = TRUE to a function, or set fao_settings(pptx = TRUE) for all functions. Previously every chart was saved in both formats.
  • eoffice, used only for PowerPoint files, is now suggested instead of required, so the package loads on macOS without XQuartz. Install it with install.packages("eoffice") to save PowerPoint files.
  • fishing_area_species() now saves PNG charts too, in figures/png/area/ (PowerPoint in figures/pptx/area/, previously figures/), like fishing_area_country().
  • Charts have no background grid lines by default; options(faofishingreport.grid = TRUE) brings them back. Year axes are labelled up to the last year of the data.
  • The PowerPoint charts of fishing_area_data() have the same size as the PNG (12 x 6 inches) instead of the size of the current graphics window.

Data

  • The bundled data is updated to FAO release 2026.1.0 (1950-2024). The previous bundled data (1950-2021) can be downloaded with download_fao_data("2023.1.1").
  • The previous bundled data lost the country name of about 24.5 million tonnes of catch (e.g. Türkiye, Réunion); the new data has no missing names.

Bug fixes

  • species_country() now uses its h_value argument; it was always 0.15 before, so breakpoint results differ from earlier charts.
  • Years are no longer fixed at 2021: axis breaks, “last five years” tables, last-year shares and pie chart periods follow the data.
  • Every function creates the output folders it needs, so functions can be run in any order.
  • country_analysis() uses the fishing area map bundled with the package instead of a path on one computer, and its fishing area map no longer fails with current ggplot2.
  • country_species() and country_analysis() no longer fail with timeseries_analysis = FALSE, and country_analysis() no longer overwrites a chart of country_species().
  • fishing_area_data(plot = FALSE) no longer fails.
  • The fishing area map of country_analysis() shows the country’s total catch in each area; before, the polygons of each species were drawn on top of each other and the colour showed one species only.
  • A species or country whose catch series is too short for the breakpoint analysis is skipped with a message, instead of stopping country_species(), country_analysis(), fishing_area_species() or fishing_area_country().
  • Curaçao and Côte d’Ivoire are now coloured on the world maps.
  • The species bar charts of country_species() and country_analysis() label their axis “Species” instead of “Country”.

Other changes

  • Requires R 4.2 or later.
  • Functions no longer place Global_Production_long, ASFIS_sp or name_mapping in the global environment.
  • The package works without library() (e.g. faofishingreport::country_analysis()), and all required packages are declared, including sf, maps and rnaturalearth.
  • Help pages for every function, generated with roxygen2.
  • Unit tests (testthat), and GitHub Actions for R CMD check on Windows, macOS and Linux, test coverage and the website.