SWATtunR：一种用于在R语言中脚本化SWAT+校准的透明且可重复的工作流程

《Environmental Modelling & Software》：SWATtunR: A Transparent and Reproducible Workflow for Scripted SWAT+ Calibration in R

　　**Svajūnas Plunge|Christoph Schürz|Michael Strauch|Miko?aj Piniewski**
**华沙生命科学大学（SGGW）水文学、气象学与水资源管理系，波兰华沙**

**摘要**
本文介绍了SWATtunR，这是一个托管在GitHub上的R语言包，用于脚本化工作流程，旨在简化并改进SWAT+水文模型的校准和验证过程。该工具解决了模型可重复性、透明度和用户控制方面的普遍挑战，将软校准和硬校准工作流程集成在一个完全可脚本化和过程可重复的环境中。SWATtunR支持专家引导和自动化工作流程，通过参数采样、性能评估和高级可视化实现灵活的模型校准。使用Little River Experimental Watershed进行的示范展示了其功能性和有效性。在这个案例研究中，所提出的工作流程在校准期间的模拟性能非常出色（NSE > 0.65，KGE > 0.75，|PBIAS| < 10%），在验证期间也表现良好，显著优于未校准的模型。通过促进透明和可重复的校准实践，SWATtunR为水文建模研究提供了实用的工具，并支持可靠的政策相关水资源评估。

**引言**
土壤和水资源评估工具（SWAT）及其最新版本SWAT+（Bieger等人，2017年）是一种半分布式的基于过程的水文-生态模型（Arnold等人，1998年），已成为水生态系统建模的关键工具，使全球研究人员能够模拟和理解复杂流域系统中的水文、农业和生态过程（Aloui等人，2023年；Tan等人，2020年；Akoko等人，2021年；Gassman等人，2007年；Gassman等人，2014年）。多年来，负责环境保护的水资源管理机构也依赖这一工具（Plunge和Piniewski，2024年；White等人，2022年）。

SWAT模型的主要优势在于它是一个开源模型，拥有庞大的用户和科学社区，以及大量由创作者免费分享的宝贵工具。例如，有许多工具可用于SWAT输入数据准备，如CMhyd气候变化数据偏差校正工具（Rathjens等人，2016年）、用于估算土壤特性的SELEEP（Ziadat等人，2015年）、WGN参数估计工具（Essenfelder，2016年）、WGN Excel宏（Boisrame，2011年）、SWAT降水输入预处理器以及露点估计工具（Liersch，2003年）等。

与传统的SWAT模型相比，SWAT+基于水文响应单元和空间对象引入了更加灵活和模块化的结构，从而更好地表示了景观过程和管理操作（Bieger等人，2017年）。这种增强了的灵活性允许更详细和可定制的模型配置，但也增加了模型设置、校准和工作流程管理的复杂性。在这种情况下，像R这样的脚本环境通过实现自动化、可重复性和数据预处理、模型执行和后处理步骤的无缝集成提供了重要优势。基于R的工具生态系统的发展为开发透明、基于脚本的工作流程奠定了基础，可以提高SWAT+建模研究的可靠性和可重复性。

对于SWAT和SWAT+，有几种软件包可用于模型参数校准、参数优化、不确定性和敏感性分析以及模拟结果的可视化。SWAT-CUP/SWATplus-CUP（Abbaspour等人，2007年）和SWAT+ Toolbox（Chawanda，2022年）是成熟且全面的独立程序，提供了多种模型参数校准和优化方法。Yen等人（2019年）在SWAT+代码中实现了综合参数估计和不确定性分析工具Plus（IPEAT+），该工具采用了动态维度搜索（DDS）算法（Tolson和Shoemaker，2007年）进行模型参数优化。其他工具则实现了在广泛使用的脚本语言中，如R（R Foundation，2025年），例如R-SWAT-FME工具（Wu & Liu，2014年）和R Shiny应用程序R-SWAT（Nguyen等人，2022年）。R-SWAT连接到R后端例程，执行参数敏感性算法（如Sobol方法，2001年）和优化算法（如粒子群优化-PSO，Kennedy & Eberhart，1995年）。另一个最新发展是hydroSWAT，这是一个专注于SWAT模型的多目标校准和工作流程的R包（Fernandez-Palomino，2026年）。

尽管这些工具为SWAT/SWAT+模型用户和科学界提供了宝贵支持，但在建模过程中仍存在一些挑战。其中最突出的是确保方法论透明度的难度，以及因此难以重现研究结果的挑战——这在同行评审的SWAT出版物中是一个普遍存在的问题（Van Griensven等人，2012年；Chawanda等人，2020年；Vos等人，2011年）。这一点尤其令人担忧，因为可重复性是依赖建模结果的决策者最重要的前提之一（?zkundakci等人，2018年）。

大多数现有的SWAT/SWAT+工具是独立应用程序，难以集成到脚本化或可重复的工作流程中。因此，操作必须通过图形界面交互式完成，通常涉及多个步骤和许多迭代，这使得过程容易出错、难以记录，并且难以复制以获得相同的结果。为了解决这个问题，已经提出了并演示了脚本化工作流程（Coon & Shuai，2022年；Chawanda等人，2020年）。然而，这些工具是为特定项目设计的，通常具有某些用户限制。例如，Watershed Workflow专门用于自动化在美国境内高分辨率、集成式、分布式水文模型的输入数据提取和准备（Coon & Shuai，2022年）。同样，SWATPlus-AW（Chawanda等人，2020年）仅针对单一模型设置案例进行了测试和发布。它最近已过渡到Community SWAT（CoSWAT）建模框架，这是一个免费且开源的解决方案，旨在简化全球大规模SWAT+模型的开发。它自动化了数据检索、预处理和模型配置等关键过程，使用仅适用于全球范围研究的2公里分辨率数据源（Chawanda等人，2025年）。

为了方便SWAT+模型的校准和验证，我们开发了SWATtunR——一个托管在GitHub上的开源R包（Plunge等人，2024c）。该工具使用SWATrunR运行SWAT+模拟，但增加了多个功能，以帮助实现模型校准和验证的脚本化工作流程。SWATtunR通过减少潜在错误来源、提高过程可重复性以及改善校准和验证过程的文档记录来减少冗余迭代。该工具在参数采样和性能标准评估方面提供了灵活性，并通过高级绘图功能提供了引人注目的可视化效果。

**概念性的水文模型应用**通常使用观测时间序列数据进行校准，以确定合适的模型参数值（Seibert和McDonnell，2002年；Kuczera和Mroczkowski，1998年）。这类观测数据通常被称为“硬”数据，通常包括在流域内定义位置的长期测量时间序列，例如水文站的流量（Arnold等人，2015年）。虽然硬数据对于评估模型性能至关重要，但仅依赖硬数据存在众所周知的局限性。在许多情况下，许多参数组合可以同样好地再现观测时间序列（Kuczera和Mroczkowski，1998年；Beven和Freer，2001年），但在内部过程表示上可能存在显著差异（Kirchner，2006年）。此外，合适的硬数据可能稀少、不可用或存在显著不确定性，特别是在数据有限的流域中（Seibert和McDonnell，2002年）。

为了解决这些局限性，提出了软校准作为互补策略。根据Rodríguez-Castellanos等人（2025年）的研究，软校准旨在约束模型参数范围，以便即使在缺乏详细时间序列观测的情况下也能真实地模拟关键的水文和生物地球化学过程。在基于SWAT的模型中，这通常是通过结合聚合或间接信息（称为软数据）来实现的，这些信息反映了长期系统行为而不是点尺度测量（Seibert和McDonnell，2002年；Arnold等人，2012年）。这样的数据为具体模拟过程提供了定性或半定量的参考点，并且当与硬数据结合使用时可以显著减少参数等效性（Etheridge等人，2014年）。

在本研究中，软校准基于两种互补类型的信息：水分出产率和作物产出统计。水分出产率定义为长期平均流量与降水的比率，对流域水量平衡提供了综合约束，并确保了蒸散和径流之间的物理合理划分。在足够长的时间段内进行评估时，它在数学上等同于径流系数，但在这里使用SWAT/SWAT+术语来强调其在模型内部水量平衡结构中的解释。

作物产出统计作为粗分辨率的软数据，用于约束植物生长和蒸散过程。在SWAT+中，作物发育使用热量单位概念进行模拟，其中每日累积的热量单位与特定作物的热量单位需求进行比较。成熟天数参数直接影响这一需求，从而控制作物的成熟和收获时间。因此，确保真实的植物热量单位累积和收获时间对于模拟可信的作物产量和相关的用水量至关重要，这又会影响整个流域的水量平衡。

基于这些考虑，我们认为结合使用软数据和硬数据代表了模型校准的良好实践。因此，我们采用了两阶段校准策略，首先是软校准，然后是硬校准。在本文中，软校准是指使用软数据约束模型参数以确保关键过程的真实表示，而硬校准是指根据模拟和观测时间序列数据进行后续参数调整。在这个框架内，校准策略可以顺序或同时实施。顺序校准在这里定义为按预定义顺序调整模型参数的过程，通常是先校准流量，然后是沉积物运输（如果适用），再是养分循环（Arnold等人，2012年）。这种方法确保在处理依赖组件之前充分表示了基础水文过程。相比之下，同时（或联合）校准涉及同时调整多个目标变量的参数，从而明确考虑了过程之间的相互作用（Fohrer等人，2022年）。

基于这些概念，本文介绍了SWATtunR包，该包旨在实现SWAT+模型校准和验证的透明、过程可重复且简化的流程。具体目标包括：（1）提出一种集成软校准和硬校准阶段的通用脚本化工作流程；（2）将SWATtunR展示为一个支持专家指导和自动化实现这一工作流程的工具；（3）使用Little River Experimental Watershed来演示其应用。

**部分代码片段**
对于SWAT和SWAT+，有多种不同的软校准程序，例如综合参数估计和不确定性分析工具-软硬数据评估（IPEAT-SD，Yen等人，2016年），或White等人（2022年）针对美国流域展示的SWAT+内部软校准程序。尽管SWAT+的内部软校准程序可以应用于任何流域建模研究，但“软”目标标准、要校准的参数选择以及作物软校准……

**我们的模型设置包括三种作物类型：玉米（SWAT代码corn）、棉花（cots）和花生（pnut）。作物软校准的目的是确保收获时的植物热量单位（PHU）比例在1.0到1.25之间（主要标准），同时尽可能使模拟产量与观测平均值接近（次要标准）。按照图4中展示的工作流程，进行了十六次模型运行，以准备结果。**

**通过脚本化工作流程提高可重复性**
SWATtunR的一个核心贡献在于其结构化、完全脚本化的SWAT+模型校准方法，解决了水文建模中广泛认可的挑战：模型设置和校准过程的有限可重复性和可追溯性。这一问题在文献中多次被强调（Van Griensven等人，2012年；Vos等人，2011年；?zkundakci等人，2018年），并且由于普遍依赖手动步骤、图形界面等原因而持续存在。

**结论**
本研究介绍了SWATtunR，这是一个基于R的脚本化框架，旨在支持SWAT+模型的透明、可重复和灵活的校准工作流程。通过在一个完全可脚本化的环境中集成软校准和硬校准方法，该工具实现了结构化和可追溯的校准过程，同时保持了用户对关键决策的控制。

**演示案例研究证实**所提出的工作流程可以实现稳健的模型性能，同时……

**CRediT作者贡献声明**
Miko?aj Piniewski：撰写 – 审稿与编辑、原始草稿撰写、方法论研究。
Svajunas Plunge：撰写 – 审稿与编辑、原始草稿撰写、可视化、软件设计、形式分析。
Christoph Schürz：软件设计、方法论研究、概念化。迈克尔·施特劳赫：写作——初稿、方法论、概念化
未引用的参考文献：奥胡斯大学（Aarhus University），2022年；Aplinkos项目管理机构（Aplinkos projekt? valdymo agentūra），2024年；R基金会（R Foundation），2025年；Schüerz，2022年；SWAT+网站（SWAT+ Website），2025年；Zambrano-Bigiarini，2024年。

软件与数据可用性
软件名称：SWATtunR
开发者：Svajunas Plunge
联系方式：[e-mail]
首次可用年份：2024年
编程语言：R
许可协议：MIT许可
存储与安装：该开源R软件包可在GitHub上免费获取，网址为：https://github.com/biopsichas/SWATtunR
文档说明：完整文档、示例代码及使用说明可访问：https://biopsichas.github.io/SWATtunR/
软件大小：159.4 KB

数据可用性
本研究使用的数据和SWAT模型设置均包含在SWATtunR软件包中，可直接从以下链接获取：
https://github.com/biopsichas/SWATtunR/tree/main/inst/extdata

关于写作过程中生成式AI与AI辅助技术的声明
在撰写本文期间，作者使用了ChatGPT、Gemini和Grammarly等工具来辅助语言编辑并提升文本清晰度。使用完这些工具/服务后，作者对内容进行了必要的审核和修改，并对最终发表的文章内容承担全部责任。

利益冲突声明
作者声明：他们不存在任何可能影响本文研究的已知财务利益冲突或个人关系。

致谢
本研究是在OPTAIN项目（“优化策略：在欧洲不同土壤-气候区域的小型农业流域中保留和再利用水资源与养分”）的框架下完成的，该项目得到了欧盟“地平线2020”（Horizon 2020）研究与创新计划的资助，授予协议编号为862756。此外，该研究还得到了NORDBALT-ECOSAFE项目的支持，该项目由欧盟“地平线欧洲”（Horizon Europe）研究与创新计划资助，授予协议编号为……（原文此处信息缺失）。