农业气象数据提取软件包：ag5Tools

××软件X 21（2023）101267原始软件出版物ag5Tools：用于从AgERA5数据库下载和提取农业气象数据的R软件包David Browna，b，Kauê de Sousac，d，Jacob van Ettenc荷兰瓦赫宁根大学地球信息科学与遥感研究实验室，Droevendaalsesteeg 3，6708 PBbDigital Inclusion，Bioversity International，30501，Turrialba，Costa RicacDigital Inclusion，Bioversity International，Parc Scientific Agropolis II，34397，Montpellier Cedex 5，Franced挪威内陆应用科学大学应用生态学、农业科学和生物技术学院农业科学系，2318 Hamar，挪威ar t i cl e i nf o文章历史记录：接收日期：2022年收到修订版2022年11月6日接受2022年关键词：农业气候作物品种评价田间试验a b st ra ct农业气象资料在农业研究中，特别是在农学和作物科学中，对于研究基因型与环境的相互作用是重要的哥白尼气候数据库的AgERA5数据集提供免费和公开访问1979年至今的全球网格每日农业气象数据，并提供为农业和农业生态研究量身定制的变量。我们开发了R软件包ag5Tools，它提供了一个简化的接口，用于下载和提取AgERA5数据。该软件包便于提取地理点的时间序列数据，其格式可方便地用于农业研究中应用的该软件包的使用证明了在坦桑尼亚阿鲁沙的多地点审判的合成数据集©2022作者（S）。由爱思唯尔公司出版这是CC BY许可下的开放获取文章（http://creativecommons.org/licenses/by/4.0/）中找到。代码元数据当前代码版本0.0.1用于此代码版本的代码/存储库的永久链接https://github.com/ElsevierSoftwareX/SOFTX-D-22-00257可复制胶囊的永久链接法律代码许可证MIT使用git的代码版本控制系统使用的软件代码语言、工具和服务R编译要求、操作环境和依赖关系R如果可用，请链接到开发人员文档/手册https://github.com/AgrDataSci/ag5Tools问题支持电子邮件david. wur.nl1. 动机和意义在多地点试验分析中使用气候数据作为模型协变量，可以提取特定地点的见解，例如有针对性的作物品种推荐[1，2]。几个统计和机器学习模型允许将气候数据作为模型协变量。缺乏从当地气象站获得所需时间和空间分辨率的气候数据一直是其应用的障碍[3]。*通讯作者：瓦赫宁根大学地球信息科学和遥感实验室&，Droevendaalsesteeg3，6708 PB，瓦赫宁根，荷兰。电子邮件地址：david. wur.nl（David Brown）.https://doi.org/10.1016/j.softx.2022.101267最近，一些覆盖全球的气候数据集已免费向公众提供，使农业研究人员能够将此类数据纳入其分析。AgERA5数据集为农业和农业生态研究提供了从1979年至今的可 用 农 业 气 象 指 标 [4] 。 它 来 自 于 欧 洲 中 期 天 气 预 报 中 心（ECMWF）对全球气候（ERA5）数据的大气再分析[5，6]。它是一个网格化的再分析数据产品，具有全球覆盖范围，从1979年到现在的时间覆盖范围，每天的时间分辨率，空间分辨率为0.1毫米。1公里（赤道约11公里）。AgERA5数据集提供了22个变量（表1），为农艺学研究量身定制[5]。它允许用户获得所有需要的2352-7110/©2022作者。 由Elsevier B.V.出版。这是一篇开放获取的文章，使用CC BY许可证（http://creativecommons.org/licenses/by/4.0/）。可在ScienceDirect上获得目录列表SoftwareX期刊主页：www.elsevier.com/locate/softxDavid Brown、Kaué de Sousa和Jacob van Etten软件X 21（2023）1012672表1可从AgERA5数据集下载的变量和统计数据资料来源：资料取自：https://doi.org/10.24381/cds.6c68c9bb。变量统计时间单位10米风速24小时平均值m s−12 m露点温度24 h平均K2 m相对湿度06：00%上午9时00分12点整15点整18点整2 m温度24 h最大K24 h平均至少24小时白天最大值白天平均值夜间平均值夜间最小值24小时平均云量液态降水持续时间分数降水通量（毫米）24小时平均积雪厚度积雪厚度LWE 24小时平均厘米太阳辐射通量J m−2 day−1固体沉淀持续时间分数24小时平均蒸汽压hPa具有均匀空间分辨率的单个气候数据集的变量。在使用来自不同来源的不同气候产品时，常常出现的情况是，这些产品具有不同的空间分辨率和坐标参考系。由于AgERA5数据集为农业研究提供了大量量身定制的变量，因此，将不同来源的数据集混合在一起的需求以及它们之间的潜在分歧大大减少。AgERA5数据集可从哥白尼气候数据存储（CDS）免费在线下载可以使用CDS网络接口下载数据，但取决于所需的数据量，该接口可能变得不实用。例如，有100个项目的限制，这意味着每次请求只能下载大约3个月的日常数据。CDS应用编程接口（API）（https://cds.climate.copernicus.eu/api-how-to）提供了从CDS编程下载数据的功能。CDS API由ECMWF开发和支持目前，官方支持的API客户端仅作为Python库（https://pypi.org/project/cdsapi/）提供。CDS API也可以与在线CDS API一起使用然而，即使使用官方的Python CDS API，前面提到的下载数据的限制仍然适用。R [7]用户可以通过ecmwfr [8]包访问广泛ecmwfr软件包提供的ECMWF产品的广泛可访问性确实方便了在建模工作流程中需要多个数据集的用户。为了提供这种跨数据集的兼容性，ecmwfr包中提供了几个然而，对于那些只对一个气候数据集感兴趣的用户来说例如，新用户可能会因为发现AgERA5数据集的下载请求是否确实需要一个参数而感到不知所措。因此，当建模工作流程主要依赖一种气候数据产品时此外，100个项目的数据限制也适用于使用ecmwfr包的下载请求。CDS以网络通用数据表（NetCDF-4）文件的形式提供AgERA 5数据。这种类型的文件可以很容易地读取 在R中由诸如terra [9]之类的软件包处理，特别是如果数据将以栅格格式使用，无论是作为单层还是多层SpatRaster对象。然而，当需要数据作为感兴趣的位置的基于点的时间序列时，应该通过日期和气候变量来搜索对应的文件，这可能是一项繁琐的任务，特别是当所需的工作流程包括不同气象变量和统计数据的若干时间序列时。2. 软件描述我们开发了R软件包ag5Tools，以方便农业研究人员下载和提取AgERA5数据。包装旨在支持数据分析和综合工作流程，例如对农场作物品种试验数据的分析和建模，以评估气候因素对感兴趣性状的影响（例如，产量或抗病性）。在许多这样的工作流中，数据通常需要采用基于点的格式，例如R数值向量或数据.frame对象。2.1. 软件构架ag 5 tools包是在R add之后开发的- 关于软件包指南和应用S3方法风格[10]。图1展示了ag5Tools包的架构图。包文件结构由七个主要子目录组成根目录包含文件DESCRIPTION、LICENSE、NAMESPACE和NEWS。为了开发ag 5 Tools包，我们使用了几个开放和免费的软件，例如R和devtools，fs，terra，reticulate和sf[7，9，11下载功能-ag5Tools软件包使用Python库cdsapi [15]。由于该包发布在The Comprehensive R Archive Network（CRAN）中，因此可以通过执行install.packages（“ag5Tools”）从R安装它。源代码可以在GitHub存储库https://github.com/AgrDataSci/ag5Tools中找到，开发版本可以通过执行devtools：：install_github（“agrtools ci/ag 5Tools”，build_vignettes= TRUE）。安装后，可以通过执行库（ag5Tools）将其加载到典型的R会话中。该软件包自动检查和配置本地环境，以满足从CDS服务下载数据的要求。唯一的先决条件是，用户应注册的CDS，并已David Brown、Kaué de Sousa和Jacob van Etten软件X 21（2023）1012673表2函数ag5_extract的方法、输入参数和输出的描述。方法参数输出ag5_extract.numericcoords：长度= 2的数值向量，形式为（lon，lat），或具有必需列path：指示包含AgERA5文件dates：字符用于提取指定变量的日期，长度为1的向量提取单个日期，而长度为2的向量表示开始和结束日期。variable：表示要提取的AgERA5变量的字符，有关可用选项statistic：字符，仅某些变量需要时间：仅适用于可变相对湿度-2 m：逻辑，如果为TRUE，则将温度值从开尔文转换为摄氏度。仅适用于变量ag5_extract.data.frameacoords：具有必需列的data.framestart_date：表示开始的列名的字符一段时间后，将被提取。end_date：表示要提取的时间段结束时的列名的lon：字符，指示包含输入数据中经度值lat：表示输入数据中包含纬度值的列的名称的a参数路径、变量、统计量、时间和时间也是必需的，但为了简洁起见省略了一个数值向量，其长度等于输入参数日期的第一个和第二个日期之间的日期数。矢量名称对应于请求的日期。如果只提供一个日期，则函数返回长度为1的数字向量一个命名的数字向量列表，每个向量对应于输入数据帧中的行。Fig. 1. ag5Tools软件包的架构图。找回他或她的用户密钥之后，用户应该将密钥存储在本地硬盘驱动器的文件中，该文件将由ag5Tools包自动检索。检索CDSAPI密钥的说明可以在C3Shttps的官方网站上找到//cds.climate.copernicus.eu/api-how-to网站。2.2. 软件功能下载数据ag5Tools软件包提供了从AgERA5数据集下载全套变量和统计数据的功能（表1）。用户可以通过函数ag5_download发出下载请求，该函数由R包reticulate内部解析为Python库cdsapi。这些依赖项由ag5Tools包内部管理，不需要用户干预。ag5Tools包的一个优点是它还避开了CDS平台当前的下载请求限制，该限制不允许请求超过100个元素。因此，ag5Tools用户可以请 求一年或 多年的数据 ，而不 必担心这 种限制。 由于ag5_download特定于AgERA5数据集，因此与其他工具相比，它需要较少的用户输入参数例如，数据集名称、数据集类型和文件格式等参数由函数ag5_download内部处理，提供了一个简化的编程接口。萃取数据从哥白尼气候变化服务下载的每个NetCDF文件（文件扩展名.nc）都包含特定日期的AgERA5数据。这些文件可以通过R软件包terra[9]轻松读取。当数据需要作为数字矢量或数据帧时，对于多个点位置和不同的时间帧，提取数据对于非专家用户来说可能是一项复杂的任务。ag5_extract函数提供了一个简单的界面，便于AgERA5数据的提取，自动搜索本地硬盘驱动器中的每个所需文件。ag5_extract是一个通用函数，它封装了依赖于输入参数和相应输出的不同方法（表2）。4=36.292−3.603 1991年6月3日1991年4月7日35.488−3.645 1990年6月3日1990年4月7日35.401−3.616 1990年1月22日1990年5月22日35.601−3.356 1990年3月22日1990年7月20日arusha_maxDT<- ag5_extract（coords= arusha_data，path=“D：/agera5_data/“，variable=“Temperature-Air-2m“，statistic=“Max-Day-Time“，start_date=“planting_date”，end_date=“harvest_date”，David Brown、Kaué de Sousa和Jacob van Etten表3软件X 21（2023）1012673. 说明性实例3.1. 下载数据‘‘Example code 1’’ below shows the code required for down-loading the maximum daytime temperature data for years 2000to 2005 using the function 该请求需要6个参数，而使用ecmwfr包则需要12个参数。3.1.1. 示例代码1库（ag5Tools）ag5_download（变量=“2m_temperature“，统计=“day_time_maximum“，day=“all”，month =“all”，year=2000：路径=“C：/custom_target_folder/”）数据被下载到函数调用中的path参数所指示的位置在此路径中，将为下载请求中包含的每一年创建一个子文件夹数据作为名为agera5_download.zip的临时zip文件下载，该文件在将文件复制到相应的文件夹后由ag5Tools软件包自动解压缩并删除解压zip文件后下载和提取的文件已经由CDS使用其命名系统命名。在上面的示例中，我们明确指出我们希望下载每个选定年份的所有日期和月份，但也可以请求特定的日期或月份。根据变量的不同，一些参数需要指定，而另一些则不需要。在前面的示例中，变量2m_temperature需要指定统计数据day_time_maximum。在相对湿度（2m_relative_humidity）的情况下，不应指示统计量，但必须指示时间。示例代码2显示了如何下载与上一示例相同年份的时间6：00和18：00的3.1.2. 示例代码2ag5_download（variable=“2m_relative_humidity”，time=c（“06_00“，“18_00“），日=“全部”，月=“全部”，年份=2000：2005，路径=“C：/custom_target_folder/”）3.2. 提取数据为了证明ag5_extract的功能，我们使用了在坦桑尼亚阿鲁沙随机生成的100个位置的合成数据集（图11）。 2）的情况。在这个例子中，我们将只关注可变的白天最高温度。表3显示了示例数据集的前10个数据点。如果表3中显示的数据存储在R data.frame对象中，则可以使用以下代码通过ag5_extract函数提取白天最高温度数据。合成数据示例的前10个数据点，显示地理坐标以及种植和收获日期。35.463−2.85135.453−3.856 1990年10月10日1991年7月2日35.170−3.216 1990年10月19日1991年16月2日36.537−2.502 1990年10月14日1991年11月2日1991年4月27日至1991年8月25日表4气 候 变 量 日 最 高 日 间 温 度 （ maxDT ） 、 最 低 夜 间 温 度 （ minNT ） 、 降 水 量（prec）、太阳辐射通量（srf）和上午09：00时的相对湿度（rhum_09），为示例数据集的试验数据点提取，并为相应的种植至收获期取平均值。最大DT（ ±C）最小NT（℃）精度（mm）srf（J）rhum_09（%）24.04 14.59 1.36 18778210.69 74.6227.44 19.34 3.74 19964845.93 71.7125.77 16.43 1.71 21830741.0727.47 16.82 2.61 21344995.40 60.0525.32 17.03 3.74 21727487.53 69.1620.60 11.02 11.48 21106727.64 70.3025.73 18.80 1.58 22175333.94 68.1428.97 17.85 0.73 23368231.39 60.1924.81 16.47 2.50 17724179.3124.89 14.72 1.00 20505541.25 56.973.2.1. 示例代码3AgERA5温度数据以开氏度提供。在我们的示例中，我们设置参数TRUE，提取数据单位为摄氏度。我们设置参数start_date和end_date ， 因 为 data.frame 中 的 列 名 有 不 同 的 列 名 ， 分 别 是planting_date和harvest_date。 但是，如果data.frame中与日期对应的列名命名为start_date和end_date，则可以省略这些参数。在示例代码3中，函数调用中省略了参数lon和lat，因为列名与默认函数参数匹配。如果输入data.frame中的列名与参数不匹配，则应提供与lon和lat对应的列名作为参数在函数调用中。当coords参数作为data.frame提供时，该函数返回一个data. frame列表，每个列表包含每个数据点（原始data.frame中的行）的时间序列，其中列名是从start_date到end_date的每个日期。如果数据旨在直接用作模型协变量，则需要计算所需的聚合度量（例如，每个时间序列的平均值。遵循相同的示例试验数据集，表4示出了针对变量白天最高温度（maxDT）、夜间最低温度（minNT）、降水量（prec）、太阳辐射（srf）和时间09：00 a.m.的相对湿度（rhum_09）提取的数据。 由于变量是作为每日观察值下载的，因此我们计算了合成数据集的每个试验数据点表4所示的数据可用作模型统计模型中的协变量此外，使用ag5_extract可用于计算其他气候变量经度纬度种植日期收获日期35.72636.102-2.1974/22/19911/24/19908/20/19915/24/1990David Brown、Kaué de Sousa和Jacob van Etten软件X 21（2023）1012675=−==图二、在 坦 桑 尼 亚 阿 鲁 沙 随 机 生 成 的数据点的 位 置 。或不能直接从Ag5ERA获得的指数。软件包包martrends[16]提供了计算一系列气候指数的功能。ag5_extract函数还可用于提取一个点位置的数据和一个点位置的一个日期或时间序列。在一个点位置的情况下，参数坐标应该以c（lon，lat）的形式作为长度为2的向量提供。例如，使用表3中第一行的坐标，参数坐标将是c（35.726，2.197）。这种功能在需要对单个地点进行气候特征描述的情况下可能是有用的。例如，示例代码4示出了针对合成数据集的第一位置提取的每日降水量数据的示例。如果只提取一个日期的数据，则参数dates应为长度向量1，以及字符或日期对象。另一方面，如果一个位置只需要一个时间序列，参数dates应该是一个长度为2的向量，其中第一个值表示序列的开始日期，第二个值表示序列的结束日期3.2.2. 示例代码4arusha_prec_01<- ag5_extract（坐标= c（35.726，-2.197162），dates = c（“1991-04-22”，“1991-08-20”），变量=“重复-通量”，路径4. 影响研究环境因子对基因型的影响例如，在育种试验中，环境是产量变异的主要来源[17]。使用气候数据作为模型协变量可以支持在作物品种评估中产生特定位置的见解[1，2，18]。AgERA5数据集提供了一个替代数据源，当气候数据没有收集在现场试验或当它是无法从当地气象站。当一项研究涉及区域或全球范围内的几个地点时，这一点甚至更为重要，气候数据可得性方面的差异。鉴于其时间跨度很大（1979年至今），AgERA5为建模目的提供了重要的气候信息来源。如Brown，Vanden Bergh [19]所述，重新利用和重新分析传统作物品种评估数据是这种宽时间跨度有用的一个例子。例如，Brown，de Bruin [20]使用ag5Tools软件包下载和提取气候数据，这些数据被用作建模和预测基因 型 表 现 的 协 变 量 。 ag5Tools 软 件 包 已 经 在 Comprehensive RArchive Network（CRAN）上发布，目前有超过2500次下载。5. 结论在这篇软件论文中，我们描述了R软件包ag5Tools的功能，用于下载和提取AgERA5数据。据我们所知，这是唯一一个带有专门为AgERA5数据集设计的下载和提取数据该软件包可在CRAN免费下载：https://cran.r-project.org/package=ag5Tools。我们提供了如何下载和提取AgERA5数据的示例。其他示例和信息可以在pack-age网站https://agrdatasci.github.io/ag5Tools/上找到。由于部署版本托管在GitHub中，因此可以通过在GitHub存储库中打开问题来管理当前功能问题或新功能请求。竞合利益作者声明，他们没有已知的竞争性财务利益或个人关系，可能会影响本文报告的工作数据可用性源代码和示例数据可在以下位置获得：https：//github.com/AgrDataSci/ag5ToolsDavid Brown、Kaué de Sousa和Jacob van Etten软件X 21（2023）1012676确认我们感谢Sytze de Bruin博士提出的建设性批评和有益的我们还感谢Vincent Johnson（生物多样性国际联盟和CIAT的科学写作服务）对本手稿的英文编辑。引用[1] vanEttenJ，etal.Cropvarietymanagementforclimateadaptationsupported by citizen science. Proc Natl Acad Sci2019;116（10）：4194-9.[2] Buntaran H，Forkman J，Piepho H-P.使用环境协变量和随机系数模型将分区多 环 境 试 验 的 结 果 投 影 到 新 位 置 ： 准 确 性 和 精 确 度 。 Theor ApplGenet2021;134（5）：1513-30.[3] Ramirez-Villegas J，Chelsea or A.评估农业应用的相关气候数据。农林气象2012;161：26-45.[4] 放大图片作者：Boogaard H. 1979年至今的农业气象指标来源于再分析。见：瓦赫宁根环境研究，编辑。哥白尼气候变化服务。2020年。[5] 放大图片作者：Boogaard H.数据流2：AgERA5历史和近实时强迫数据。In：ECMWF，editor.产品用户指南和规范。瓦赫宁根环境研究;2020年。[6] Hersbach H等人，ERA5全球再分析。Q J R Meteorol Soc2020;146（730）：1999-2049。[7]RCore团队。R：统计计算的语言和环境。维也纳，奥地利：R统 计 计 算 基金会; 2022年。[8]放大图片作者：Hufkens K. ecwmfr包：ECMWF API端点的接口。2019年。[9]HijmansRJ.Terra：空间数据分析。R包版本。2021年[10]RCore团队。写R扩展。2022年，可从：https://cran.r-project.org/doc/manuals/r-release/R-exts.html。[11]Wickham H，et al. Devtools：tools to make developing R packages easier.CRAN;2021年。[12]放大图片作者：UsheyK，Allaire J.Reticulate：Python的接口2022年。[13]放大图片作者：Hester J，Wickham H，Csárdi G. FS：基于'Libuv'的跨平台文件系统操作。CRAN：CRAN; 2021年。[14]佩贝斯马湖R的简单特性：对空间矢量数据的标准化支持。R J2018;10（1）：439-46。[15]ECMWF。Python API访问哥白尼气候数据存储。ECMWF;2019.[16]de Sousa K，van Etten J，Solberg S.气候趋势：生态模拟用气候变率指数。2020年。[17]谢努湾第13章-表征作物环境-性质、意义和应用。In：Sadras VO，CalderiniDF，editors.作物生理学。第二版San Diego：Academic Press; 2015，p.321-48[18]数据驱动的分散育种提高了具有挑战性的作物生产环境中的预测准确性。Commun Biol2021;4（1）：944.[19]Brown D，et al.作物品种评价的数据综合。审查. AgronSustain Dev2020;40（4）：25.[20]Brown D等人，《四个中美洲国家普通菜豆农场试验的基于等级的数据综合》。作物科学2022.