Skip to contents

cmsy_area(): 一次完成某个渔区主要物种的CMSY++评估

Source: vignettes/articles/zh/reference/cmsy_area.Rmd
cmsy_area.Rmd

英文原页：cmsy_area()

说明

本函数一次完成cmsy_input()、cmsy_run()、cmsy_plot()、cmsy_forecast()和cmsy_tables()分步完成的工作，对象是某个FAO渔区中渔获量最大的物种（或指定的物种）：准备仅基于渔获量的输入数据，对每个种群运行CMSY++，绘制图表，预测各种群在不同捕捞情景下的变化，并写出表格。每一步都有进度条显示进度。

English

This function does in one call what cmsy_input(), cmsy_run(), cmsy_plot(), cmsy_forecast() and cmsy_tables() do step by step, for the species with the largest catch in an FAO fishing area (or for chosen species): it prepares the catch-only input, runs CMSY++ on every stock, draws the charts, projects the stocks under fishing scenarios and writes the tables. Progress bars follow each step.

用法 

cmsy_area(
  area,
  top = 10,
  species = NULL,
  recent_years = 10,
  out_dir = "cmsy_areas",
  auto_start = TRUE,
  seed = 1,
  parallel = NULL,
  settings = list(),
  charts = c(cmsy_stock_charts, cmsy_summary_charts),
  classes = c("fao", "palomares"),
  forecast = TRUE,
  annotations = getOption("faofishingreport.cmsy_annotations", FALSE),
  lang = NULL,
  pptx = getOption("faofishingreport.pptx", FALSE),
  plot_show = fao_setting("plot_show"),
  silent = fao_setting("silent"),
  ...
)

参数

area
FAO主要渔区名称（可以是多个），写法与fishing_area_data()中相同（例如”Atlantic, Northeast”），也可以是FAO渔获量数据，例如fishing_area_data()$area_data。
English FAO major fishing area name(s), as in fishing_area_data() (e.g. “Atlantic, Northeast”), or FAO catch data such as fishing_area_data()$area_data.
top
要评估的渔获量最大的物种数。默认为10。
English Number of species with the largest catch to assess. Default is 10.
species
可选，指定要评估的物种，以代替渔获量最大的top个物种；可以用英文名或中文名、学名或FAO三字母代码给出。
English Optional species to assess instead of the top ones, by English or Chinese name, scientific name or FAO 3-alpha code.
recent_years
按数据最后recent_years年的平均渔获量对物种排序。默认为10。
English Catch is ranked by its mean over the last recent_years years of the data. Default is 10.
out_dir
存放结果的文件夹，每个渔区在其中各建一个文件夹。默认为”cmsy_areas”。
English The folder in which a folder per area is made. Default is “cmsy_areas”.
auto_start
同cmsy_run()，但这里默认为TRUE：起始生物量难以判断的种群，按CMSY++的建议从渔获量首次达到最大值至少40%的年份开始。
English As in cmsy_run(), but TRUE by default here: a stock whose start biomass is ambiguous starts in the first year with at least 40% of the maximum catch, as suggested by CMSY++.
seed
运行所用的随机数种子，使结果可以重复。默认为1。
English The random seed of the runs, so that the results can be repeated. Default is 1.
parallel
同时运行的种群数。每个种群还要为其两条MCMC链另外使用两个进程。默认为处理器物理核心数的一半。
English The number of stocks run at the same time. Each uses two more processes for its two MCMC chains. Default is half the number of processor cores.
settings
可选，用于替换CMSY++默认值的CMSY++设置（命名列表），例如list(CV.C = 0.2, n.iter = 100000, n.burnin = 50000)。各项设置、默认值及其作用见cmsy_defaults()。默认不做更改：CMSY++使用自己的默认值运行。所用的设置保存在运行文件夹的settings_used.csv和result$settings中。
English Optional named list of CMSY++ settings that replace its defaults, e.g. list(CV.C = 0.2, n.iter = 100000, n.burnin = 50000). See cmsy_defaults() for the settings, their defaults and what they do. Default is no change: CMSY++ runs with its own defaults. The settings used are saved in settings_used.csv of the run folder and in result$settings.
charts
要绘制的图表（见cmsy_plot()）。默认为全部图表。
English The charts to draw (see cmsy_plot()). Default is all of them.
classes
资源状态分类：“fao”（默认，两类）或”palomares”（五类）。
English The status classes: “fao” (default, two classes) or “palomares” (five classes).
forecast
逻辑值。为TRUE（默认）时，还按cmsy_forecast()的默认捕捞情景对各种群进行预测。
English A logical value. If TRUE (default), the stocks are also projected under the default fishing scenarios of cmsy_forecast().
annotations
在坐标轴标题和坐标轴标签之外添加到图表中的文字：FALSE（默认）不添加，TRUE全部添加，或从”title”（标题）、“subtitle”（副标题）、“caption”（图注）、“legend”（图例）和”labels”（图表内的文字）中任选。可以用options(faofishingreport.cmsy_annotations = TRUE)在本次R会话中更改默认值。
English The text added to the axis titles and labels: FALSE (default) none, TRUE all, or any of “title”, “subtitle”, “caption”, “legend” and “labels” (text inside the chart). The default can be changed for the session with options(faofishingreport.cmsy_annotations = TRUE).
lang
图表文字和名称的语言：“en”（英文）、“zh”（中文）或”both”（中英双语）。默认为NULL，即使用fao_settings()设置的语言（未更改时为”en”）。
English The language of the chart text and names: “en” (English), “zh” (Chinese) or “both” (Chinese and English). Default is NULL, which uses the language set with fao_settings() (“en” unless changed).
pptx
逻辑值。为TRUE时，图表还另存为可编辑的PowerPoint文件，保存在<out_dir>/<area>/figures_pptx/中。默认为FALSE，可以用fao_settings(pptx = TRUE)为所有函数统一更改。
English A logical value. If TRUE, the charts are also saved as editable PowerPoint files in <out_dir>/<area>/figures_pptx/. Default is FALSE, which can be changed for all functions with fao_settings(pptx = TRUE).
plot_show
逻辑值。为TRUE时，每张图在保存的同时也画在绘图窗口中（例如RStudio的Plots窗格），便于立即查看。默认为FALSE，可以用fao_settings(plot_show = TRUE)为所有函数统一更改。无论是否显示，图表都会保存为文件（plot = TRUE）。
English A logical value. If TRUE, each chart is also drawn in the plot window (e.g. the Plots pane of RStudio) as it is saved, to look at it at once. Default is FALSE, which can be changed for all functions with fao_settings(plot_show = TRUE). The charts are saved as files (plot = TRUE) either way.
silent
逻辑值。为FALSE（默认）时，用进度条显示已完成的种群数以及已用时间和预计剩余时间，并输出运行信息。为TRUE时不输出任何内容。可以用fao_settings(silent = TRUE)在本次R会话中更改默认值。
English A logical value. If FALSE (default), a progress bar shows how many stocks have finished, with the elapsed and the estimated remaining time, and messages report the run. If TRUE, nothing is printed. The default can be changed for the session with fao_settings(silent = TRUE).
...
传递给cmsy_input()的其他参数（例如priors、default_resilience）。
English Further arguments passed to cmsy_input() (e.g. priors, default_resilience).

返回值

以不可见方式返回cmsy_run()的结果，并附加input、forecast、tables和dir（该渔区的文件夹）几个元素；有多个渔区时，返回由这些结果组成、以渔区命名的列表。

English

Invisibly, the result of cmsy_run() with the elements input, forecast, tables and dir (the folder of the area); a list of these, named by area, for several areas.

详细说明

每个渔区的结果保存在各自的文件夹out_dir/<area>/中：

  • input/：CMSY++的渔获量文件和ID文件、所用的种群，以及未纳入评估的主要物种及其原因（例如没有r先验：见cmsy_input()的priors和default_resilience）；
  • runs/：每个种群的CMSY++运行结果（其文件夹中有CMSY++的原始图表、输出和日志）、修改后的CMSY++代码和修改清单；
  • figures/：每个种群一个图表文件夹，另有一个包含全部种群的summary/文件夹（PNG格式；pptx为TRUE时，PowerPoint文件保存在figures_pptx/中）；
  • tables/：结果、逐年序列、报告用的先验参数表和结果表、预测结果、所用的CMSY++设置（settings_used.csv）以及所用全部内容的来源（sources.csv）。

与cmsy_input()中一样，FAO数据只有渔获量（没有资源丰度指数），所以所有种群都只用CMSY++中仅基于渔获量的部分进行评估，结果仅具指示意义。

English

The results of each area are saved in their own folder, out_dir/<area>/:

  • input/: the CMSY++ catch and ID files, the stocks used, and the main species left out with the reason (e.g. no r prior: see priors and default_resilience of cmsy_input());
  • runs/: the CMSY++ run of each stock (its folder has the original CMSY++ charts, output and log), the changed CMSY++ code and the list of changes;
  • figures/: one folder of charts per stock and a summary/ folder for all stocks (PNG, and PowerPoint in figures_pptx/ when pptx is TRUE);
  • tables/: results, yearly series, the priors and results tables for reports, projections, the CMSY++ settings used (settings_used.csv) and the sources of everything used (sources.csv).

As in cmsy_input(), FAO data have catches only (no abundance index), so all stocks are assessed with the catch-only part of CMSY++ and the results are indicative.

参考文献

Froese, R., Winker, H., Coro, G., Palomares, M.L.D., Tsikliras, A.C., Dimarchopoulou, D., Touloumis, K., Demirel, N., Vianna, G.M.S., Scarcella, G., Schijns, R., Liang, C. and Pauly, D. (2023). New developments in the analysis of catch time series as the basis for fish stock assessments: the CMSY++ method. Acta Ichthyologica et Piscatoria 53: 173-189. doi:10.3897/aiep.53.105910

Froese, R., Demirel, N., Coro, G. and Winker, H. (2021). User Guide for CMSY++. GEOMAR, Germany, 17 pp. https://oceanrep.geomar.de/id/eprint/52147/

FAO (2026). The State of World Fisheries and Aquaculture 2026. Rome, FAO. Section “The status of fishery resources”, Box 1.3 (assessment tiers and status classes). https://openknowledge.fao.org/server/api/core/bitstreams/09d03e2f-7097-4d59-bf94-db65e95f44fd/content/sofia-2026/the-status-fishery-resources.html

示例 

cmsy_setup()                     # once: JAGS and the R packages CMSY++ needs

# The ten species with the largest catch of the last ten years in FAO area 27, in Chinese
area27 <- cmsy_area("Atlantic, Northeast", top = 10, lang = "zh")
area27$summary[, c("Stock", "species_name", "B_Bmsy", "F_Fmsy", "status")]
area27$dir                       # folder with input/, runs/, figures/ and tables/

# Chosen species (scientific name, FAO code, ...), all annotations, five status classes
cmsy_area("Atlantic, Northeast", species = c("Mallotus villosus", "PRA"),
          annotations = TRUE, classes = "palomares")

# Species without a FishBase prior get a resilience (passed on to cmsy_input())
cmsy_area("Atlantic, Northeast", top = 20, default_resilience = "Medium")

# Several areas, quietly, with longer MCMC chains (see cmsy_defaults())
cmsy_area(c("Atlantic, Northeast", "Atlantic, Northwest"), top = 5, silent = TRUE,
          settings = list(n.iter = 100000, n.burnin = 50000))