💾 FAO数据：下载与自定义 • faofishingreport

fao_settings(lang = "zh")   # 本文所有图表使用中文

📦 数据来源：FAO全球捕捞产量（Global Capture Production）2026.1.0版（FAO于2026-03-30发布，1950–2024年），下载地址Capture_2026.1.0.zip，许可证CC BY 4.0。用fao_data_info()查看你使用的版本和引用格式。

📚 数据简介

faofishingreport使用的是FAO全球捕捞产量（Global Capture Production）统计：1950年以来每个国家按物种条目和FAO主要渔区统计的年产量。数据只包括捕捞渔业（不含水产养殖），单位为活重吨。这些数据由FAO根据各国统计机构的报告汇编，对未上报的国家则由FAO估算（FAO 2026；Garibaldi 2012）。

data <- load_fao_data()
c(rows = nrow(data), first_year = min(data$Year), last_year = max(data$Year),
  countries = length(unique(data$Country..Name.)),
  species = length(unique(data$ASFIS.species..Name.)),
  areas = length(unique(data$FAO.major.fishing.area..Name.)))
#>       rows first_year  last_year  countries    species      areas 
#>    1024698       1950       2024        248       3797         26

FAO大约每年发布一次新版本，每次增加一年的数据，并修订往年的数据。本包自带一个较新的版本，也可以直接从FAO统计服务器下载更新的版本，每个版本是一个Capture_<version>.zip文件。

本文介绍的函数：

函数	用途
`check_fao_update()`	列出FAO服务器上的所有版本，并把最新版本与本机数据比较
`download_fao_data()`	下载某个版本并转换成本包的数据格式
`load_fao_data()`	读取已下载的版本或包自带数据
`fao_data_info()`	所用的版本、下载链接、许可证和引用格式
`fao_data_dir()`	下载数据的保存目录
`fao_translate()`	国家、物种和渔区的中文名或中英双语名

🔎 检查是否有新版本

check_fao_update()列出FAO服务器上的所有版本，并把其中最新的版本与包自带数据以及你已下载的数据进行比较：

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.

参数	含义	默认值
`data_dir`	已下载版本所在的文件夹	`fao_data_dir()`
`quiet`	设为`TRUE`时不显示任何信息，例如在脚本中使用	`FALSE`

它还会以不可见（invisible）的方式返回一个列表：

元素	内容
`latest`	FAO线上的最新版本
`bundled`	包自带数据的版本
`local`	已下载的最新版本（没有则为`NA`）
`update_available`	线上最新版本比包自带数据和已下载数据都新时为`TRUE`
`releases`	线上所有版本：版本号`version`、发布日期`date`、文件大小`size`和下载地址`url`

releases <- check_fao_update(quiet = TRUE)
releases$update_available
#> [1] FALSE
tail(releases$releases, 3)
#>     version       date size                                                          url
#> 9  2024.1.0 2024-04-04 4.5M https://www.fao.org/fishery/static/Data/Capture_2024.1.0.zip
#> 10 2025.1.0 2025-09-04 5.0M https://www.fao.org/fishery/static/Data/Capture_2025.1.0.zip
#> 11 2026.1.0 2026-03-30 5.5M https://www.fao.org/fishery/static/Data/Capture_2026.1.0.zip

⬇️ 下载某个版本

download_fao_data()下载一个版本（约5 MB），转换成本包的数据格式并保存到你的电脑上。之后无需重复下载：再次调用时会直接读取已保存的文件。

download_fao_data()                       # 最新版本
download_fao_data(version = "2023.1.1")   # 较早的版本，例如用于重现以前的报告
download_fao_data(overwrite = TRUE)       # 重新下载

参数	含义	默认值
`version`	要下载的版本，如`"2026.1.0"`；`"latest"`为线上最新版本。FAO服务器上没有的版本会报错，并列出可用的版本	`"latest"`
`data_dir`	保存该版本数据的文件夹	`fao_data_dir()`
`overwrite`	`FALSE`时直接读取已下载过的版本；`TRUE`时重新下载	`FALSE`
`quiet`	不显示进度信息	`FALSE`

函数以不可见的方式返回数据。转换时只保留以活重吨计的产量，通过FAO代码把国家和物种匹配到本包使用的名称，并记录版本号、发布日期、下载地址和下载日期（attr(data, "fao_version")、attr(data, "release_date")、attr(data, "source_url")、attr(data, "download_date")）。每个版本保存为三个文件：

文件	内容
`Global_Production_long_<version>.rds`	产量数据
`fao_names_<version>.rds`	国家、物种和渔区的官方中文名称
`fao_groups_<version>.rds`	物种类群（ISSCAAP、分类阶元）、国家分组和渔区分组

📂 选择数据文件夹

fao_data_dir()没有参数，它返回download_fao_data()（以及download_fishbase_data()）保存数据、所有函数读取数据的文件夹，按以下顺序确定：

顺序	来源	设置方法
1	`data_dir`设置	`fao_settings(data_dir = "D:/shared/fao_data")`（本次R会话有效）
2	环境变量`FAOFISHINGREPORT_DATA_DIR`	在用户主目录的`.Renviron`文件中加一行`FAOFISHINGREPORT_DATA_DIR=<文件夹>`（每次R会话都有效）
3	R的用户数据文件夹`tools::R_user_dir("faofishingreport", "data")`	默认

fao_data_dir()
#> [1] "C:/Users/<you>/AppData/Roaming/R/data/R/faofishingreport"          # Windows
#> [1] "~/Library/Application Support/org.R-project.R/R/faofishingreport"  # macOS
#> [1] "~/.local/share/R/faofishingreport"                                 # Linux

如果想把数据放在别处，例如团队共享的文件夹，只需设置一次data_dir。此后下载的数据都会保存到那里，所有函数也都从那里读取数据：

fao_settings(data_dir = "D:/shared/fao_data")
download_fao_data()

🧭 使用哪个版本

所有函数都使用可用的最新数据：即已下载的最新版本；如果包自带数据更新，则使用包自带数据。fishing_area_data()、country_analysis()和fao_report()可以用data_version指定使用哪个版本：

FAO27 <- fishing_area_data("Atlantic, Northeast")                            # 最新数据
FAO27 <- fishing_area_data("Atlantic, Northeast", data_version = "bundled")  # 包自带数据
FAO27 <- fishing_area_data("Atlantic, Northeast", data_version = "2023.1.1") # 已下载的某个版本

load_fao_data()返回完整的数据集，取值方式相同：

data <- load_fao_data()                  # 最新数据
data <- load_fao_data("2023.1.1")        # 已下载的某个版本

参数	含义	默认值
`version`	`"latest"`：已下载版本和包自带数据中最新的一个；`"bundled"`：包自带数据；或已下载的版本、包自带数据的版本号，如`"2025.1.0"`（其他版本会报错，并列出已下载的版本）	`"latest"`
`data_dir`	已下载版本所在的文件夹	`fao_data_dir()`

它返回包含下文所述八列的数据框，并显示读取的是哪个版本。

📝 版本信息与引用

fao_data_info()显示分析使用的是哪个版本、FAO的发布日期、包含的年份、下载的文件、许可证，以及写报告用的引用格式。它的参数与load_fao_data()相同（version，默认"latest"；data_dir，默认fao_data_dir()）：

fao_data_info()
#> FAO Global Capture Production
#>   Release:   2026.1.0 (published by FAO on 2026-03-30)
#>   Years:     1950-2024
#>   File:      https://www.fao.org/fishery/static/Data/Capture_2026.1.0.zip
#>   Obtained:  bundled with faofishingreport, downloaded from FAO on 2026-10-10
#>   Licence:   CC BY 4.0 (https://www.fao.org/contact-us/terms/db-terms-of-use/en)
#>   Citation:  FAO. 2026. Global Capture Production 1950-2024, release 2026.1.0. In: Fisheries and Aquaculture [online]. Rome. [Cited 10 October 2026]. https://www.fao.org/fishery/collection/capture/en. Licence: CC BY 4.0.

fao_data_info()$citation           # 只看引用格式
fao_data_info("2025.1.0")          # 某个已下载的版本

它返回一个列表：

元素	内容
`release`	版本号，如`"2026.1.0"`
`release_date`	在FAO服务器上的发布日期
`years`	数据的起止年份
`source`	`"bundled"`（包自带）或`"downloaded"`（已下载）
`url`	FAO服务器上的版本文件
`download_date`	从FAO下载数据的日期
`licence`、`terms`	`"CC BY 4.0"`和FAO统计数据库使用条款
`citation`	写报告用的引用格式

📋 数据格式

每个版本都会转换成相同的八列，因此所有分析都适用于任何版本：

show_table(data, n = 6)

Country..Name.	ASFIS.species..Name.	FAO.major.fishing.area..Name.	Unit..Name.	Unit	Year	Production	Production.Type
Afghanistan	Freshwater fishes nei	Asia - Inland waters	Tonnes - live weight	TLW, Number	1950	100	actual
Afghanistan	Freshwater fishes nei	Asia - Inland waters	Tonnes - live weight	TLW, Number	1951	100	actual
Afghanistan	Freshwater fishes nei	Asia - Inland waters	Tonnes - live weight	TLW, Number	1952	100	actual
Afghanistan	Freshwater fishes nei	Asia - Inland waters	Tonnes - live weight	TLW, Number	1953	100	actual
Afghanistan	Freshwater fishes nei	Asia - Inland waters	Tonnes - live weight	TLW, Number	1954	100	actual
Afghanistan	Freshwater fishes nei	Asia - Inland waters	Tonnes - live weight	TLW, Number	1955	200	actual

列	内容
`Country..Name.`	国家（FAO简称，如”Korea, Republic of”）
`ASFIS.species..Name.`	物种条目（ASFIS英文名；未鉴定到种的条目以”nei”结尾）
`FAO.major.fishing.area..Name.`	FAO主要渔区
`Unit..Name.`、`Unit`	均为活重吨
`Year`	年份
`Production`	产量（吨）
`Production.Type`	数值的状态，来自FAO的状态标记：`actual`（官方数据）、`estimate`（由该国或FAO估算）、`neligible`（低于0.5吨）、`provisional`（临时数据）、`suppressed`、`international organization`

✂️ 分析自己的数据子集

各分析函数的输入都是包含上述各列的数据框，因此任何数据子集都可以拿来分析。fishing_area_data()是提取单个渔区最简便的方法，但你也可以自己构建子集：

# 多个渔区合并的产量，例如整个大西洋
atlantic <- subset(data, grepl("^Atlantic", FAO.major.fishing.area..Name.))
unique(atlantic$FAO.major.fishing.area..Name.)
#> [1] "Atlantic, Southeast"       "Atlantic, Eastern Central"
#> [3] "Atlantic, Western Central" "Atlantic, Southwest"      
#> [5] "Atlantic, Antarctic"       "Atlantic, Northeast"      
#> [7] "Atlantic, Northwest"

# 2000年以来整个大西洋的物种类群结构
species_group_composition(subset(atlantic, Year >= 2000), label = "Atlantic since 2000")

species_group_composition()、peak_trend()等汇总分析共有以下参数（各自特有的参数见📈 类群结构、资源状态与趋势）：

参数	含义	默认值
`area_data`	产量数据：`fishing_area_data()$area_data`或`load_fao_data()`的任意子集
`plot`	在`figures/png/summary/`中保存图表	`TRUE`
`table`	在`tables/`中保存表格	`TRUE`
`lang`	`"en"`、`"zh"`或`"both"`	`NULL`：使用`fao_settings()`中的语言
`pptx`	同时在`figures/pptx/summary/`中保存可编辑的PowerPoint文件	`FALSE`，或`fao_settings()`中的`pptx`
`plot_show`	保存图表的同时把图画在绘图窗口中（例如RStudio的Plots窗格）	`FALSE`，或`fao_settings()`中的`plot_show`
`label`	输出文件名中使用的名称	`NULL`：数据所属的渔区（或国家）

更多示例：

# 某个国家在所有渔区的产量
china <- subset(data, Country..Name. == "China")
peak_trend(china, by = "area", label = "China")

# 某个物种在所有渔区的产量
skipjack <- subset(data, ASFIS.species..Name. == "Skipjack tuna")
peak_trend(skipjack, by = "area", label = "Skipjack tuna")

# 只取27渔区最近30年的数据
FAO27_recent <- subset(FAO27$area_data, Year >= 1995)
fishing_area_species(FAO27_recent)

查找国家、物种和渔区的准确名称：

head(sort(unique(data$Country..Name.)), 10)
#>  [1] "Afghanistan"         "Albania"             "Algeria"            
#>  [4] "American Samoa"      "Andorra"             "Angola"             
#>  [7] "Anguilla"            "Antigua and Barbuda" "Argentina"          
#> [10] "Armenia"
grep("tuna", unique(data$ASFIS.species..Name.), value = TRUE)
#>  [1] "Atlantic bluefin tuna"    "Frigate and bullet tunas"
#>  [3] "Bullet tuna"              "Skipjack tuna"           
#>  [5] "Yellowfin tuna"           "Dogtooth tuna"           
#>  [7] "Bigeye tuna"              "Pacific bluefin tuna"    
#>  [9] "Southern bluefin tuna"    "Longtail tuna"           
#> [11] "Frigate tuna"             "True tunas nei"          
#> [13] "Blackfin tuna"            "Slender tuna"

🌐 中文名称

中文名称来自FAO随每个版本发布的代码表和FAO ASFIS物种名录；没有官方中文名的条目由本包自带的对照表补充，仍然没有的则保留英文。用fao_translate()可以查看这些名称：

fao_translate(c("Norway", "Spain", "Korea, Republic of"), "country", "zh")
#> [1] "挪威"     "西班牙"   "大韩民国"
fao_translate(c("Atlantic cod", "Skipjack tuna"), "species", "both")
#> [1] "大西洋鳕 Atlantic cod" "鲣 Skipjack tuna"
fao_translate("Atlantic, Northeast", "area", "zh")
#> [1] "东北大西洋"

参数	含义	默认值
`x`	FAO数据中的英文名称
`type`	名称类型：`"country"`、`"species"`或`"area"`	`"country"`
`lang`	`"zh"`（中文）、`"both"`（中英双语）或`"en"`（不变）	`"zh"`

函数按原顺序返回名称。几个英文名对应同一个中文名时（例如两个物种条目的中文名相同），会同时保留英文名，以便在图表和表格中区分。

FAO名录中有许多物种条目没有中文名。对于只对应一个物种的条目，本包使用该物种在FishBase或SeaLifeBase中的中文俗名：即其中给中国、用简体字书写的名称，优先使用FishBase标为首选的名称（Froese和Pauly，2026；Palomares和Pauly，2026）。FAO的名称始终优先。这张名称表连同每个物种的其他名称和来源，保存在inst/extdata/species_names_zh_fishbase.csv中，由data-raw/build_species_names_zh.R根据rfishbase包读取的FishBase数据表生成：

fao_translate(c("Pacific cod", "Yellowfin sole", "Pacific ocean perch"), "species", "zh")
#> [1] "太平洋鳕"            "糙鲽"                "Pacific ocean perch"

Pacific ocean perch保留英文名：FishBase中没有给中国的简体中文名。

FAO没有为ISSCAAP物种类群、大类和收入分组提供中文名称；本包的译名保存在inst/extdata/group_names_zh.csv，所有图表标签保存在inst/extdata/chart_labels.csv。如需修改措辞，可在包的源代码中编辑这些文件，然后重新安装。

🧩 扩展：按分区的渔获

本节和下一节使用全球捕捞产量以外的FAO数据集，属于本包的扩展功能，不纳入Word报告。

FAO还为四个区域发布了按分区（区域渔业组织使用的FAO渔区下一级单元）统计的渔获：GFCM（37区，如37.1.1巴利阿里、37.2.1亚得里亚海、37.4.2黑海）、CECAF（34区）、东南大西洋（47区）和RECOFI（海湾、阿曼海和阿拉伯海西南部，属于51区的一部分）。load_fao_divisions()第一次使用时下载最新版本（约5 MB），保存在数据文件夹中，并按上面的格式返回，另外多三列：Division、Division..Name.和Region。

med <- load_fao_divisions("GFCM")
pelagic_demersal(med, by = "division")          # 每个分区一条 P/D 序列
mean_temperature_catch(med, by = "division")    # 每个分区的渔获平均温度和海表温度

对GFCM、CECAF和东南大西洋，各分区渔获之和与FAO渔区的渔获几乎完全一致。有些代码不是具体海域：“37.0.0 Tunas” 是按整个渔区报告的金枪鱼，“37.9.0 Not known” 是分区不明的渔获。

🧩 扩展：贸易与就业数据

FAO还发布水产品贸易和渔业与养殖就业数据：

load_fao_trade()：各国按商品和年份的出口、进口、转口，从1976年起，约16 MB；
load_fao_employment()：各国按工作领域、工作时间、性别的从业人数，从1995年起，不到1 MB。

两个函数和load_fao_divisions()一样，第一次运行时下载数据并保存在数据文件夹。贸易数量是产品重量，不是活重；就业是人数，不是全时当量。把它们和渔获数据对接的分析（catch_trade()、employment_summary()、catch_per_fisher()）见🚢 贸易与就业。

trade <- load_fao_trade()
employment <- load_fao_employment()

⚠️ 数据注意事项

近几年的数据常为估算值。某个国家尚未上报时，FAO会估算其产量。在34渔区（中东大西洋），2024年约三分之一的产量是估算值，而27渔区不到1%；这些数值通常会在下一个版本中修订。data_quality()可以显示任一渔区的这一情况。
未分类（nei）类别（“not elsewhere included”，即”未另列明”）是未鉴定到种的产量，例如”Marine fishes nei”。在某些渔区，这部分产量占比很大。
已不存在的国家，如苏联（数据截至1991年），作为单独的国家列出。
不同版本之间存在差异：各国提交更正或更完整的数据后，FAO会修订往年数据（Garibaldi 2012；Zeller和Pauly 2018），因此用不同版本得到的结果可能不同。请在报告中注明所用的版本（fao_data_info()）。compare_releases()可以列出两个版本之间修订过的记录（见🔬 渔获骤变、渔业崩溃、同步性与远洋捕捞）。
数据的使用：FAO统计数据以CC BY 4.0许可证和FAO统计数据库使用条款发布；请引用所用的版本。

🔄 维护者须知：更新包自带数据

包自带数据、中文名称和分组可以用以下命令根据FAO最新版本重新生成：

Rscript data-raw/update_bundled_data.R

📖 参考文献

CWP (Coordinating Working Party on Fishery Statistics). CWP Handbook of Fishery Statistics. Rome: FAO. https://www.fao.org/cwp-on-fishery-statistics/handbook/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; all releases: https://www.fao.org/fishery/static/Data/

FAO (2026). Fishery and Aquaculture Statistics – Yearbook 2024. FAO Yearbook of Fishery and Aquaculture Statistics. Rome: FAO. doi:10.4060/ce1217en

FAO. ASFIS List of Species for Fishery Statistics Purposes. Rome: FAO. https://www.fao.org/fishery/collection/asfis/en

FAO. Global Capture Production. Fisheries and Aquaculture Division, Rome. https://www.fao.org/fishery/collection/capture/en

FAO. Terms of use of FAO statistical databases. https://www.fao.org/contact-us/terms/db-terms-of-use/en

Froese, R. and Pauly, D. (Eds.) (2026). FishBase. World Wide Web electronic publication, version 06/2026. https://www.fishbase.se

Garibaldi, L. (2012). The FAO global capture production database: a six-decade effort to catch the trend. Marine Policy 36(3): 760–768. doi:10.1016/j.marpol.2011.10.024

Palomares, M. L. D. and Pauly, D. (Eds.) (2026). SeaLifeBase. World Wide Web electronic publication, version 06/2026. https://www.sealifebase.se

Zeller, D. and Pauly, D. (2018). The ‘presentist bias’ in time-series data: implications for fisheries science and policy. Marine Policy 90: 14–19. doi:10.1016/j.marpol.2018.01.015