Merge pull request #59 from tamnva/joss_manuscript

add R-CMD check

.Rbuildignore

@@ -1,5 +1,7 @@
+^joss$
 ^.*\.Rproj$
 ^\.Rproj\.user$
 ^LICENSE\.md$
 ^doc$
 ^Meta$
+^\.github$

.github/.gitignore

@@ -0,0 +1 @@
+*.html

.github/workflows/R-CMD-check.yaml

@@ -0,0 +1,29 @@
+# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
+# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+name: R-CMD-check
+
+jobs:
+  R-CMD-check:
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+      R_KEEP_PKG_SOURCE: yes
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: any::rcmdcheck
+          needs: check
+
+      - uses: r-lib/actions/check-r-package@v2

joss/paper.bib

@@ -0,0 +1,243 @@
+@article{bieger2017,
+	author = {Bieger, Katrin and Arnold, Jeffrey G. and Rathjens, Hendrik and White, Michael J. and Bosch, David D. and Allen, Peter M. and Volk, Martin and Srinivasan, Raghavan},
+	title = {Introduction to SWAT+, A Completely Restructured Version of the Soil and Water Assessment Tool},
+	journal = {JAWRA Journal of the American Water Resources Association},
+	volume = {53},
+	number = {1},
+	pages = {115-130},
+	keywords = {watershed management, computational methods, simulation, watersheds, rivers/streams},
+	doi = {10.1111/1752-1688.12482},
+	url = {https://onlinelibrary.wiley.com/doi/abs/10.1111/1752-1688.12482},
+	eprint = {https://onlinelibrary.wiley.com/doi/pdf/10.1111/1752-1688.12482},
+	year = {2017}
+}
+
+@article{arnold1998,
+	author = {Arnold, J. G. and Srinivasan, R. and Muttiah, R. S. and Williams, J. R.},
+	title = {LARGE AREA HYDROLOGIC MODELING AND ASSESSMENT PART I: MODEL DEVELOPMENT1},
+	journal = {JAWRA Journal of the American Water Resources Association},
+	volume = {34},
+	number = {1},
+	pages = {73-89},
+	keywords = {simulation, surface water hydrology, erosion, sedimentation, nonpoint source pollution, large area modeling, plant growth, agricultural land management},
+	doi = {10.1111/j.1752-1688.1998.tb05961.x},
+	url = {https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1752-1688.1998.tb05961.x},
+	eprint = {https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1752-1688.1998.tb05961.x},
+	year = {1998}
+}
+
+@article{gassman2007,
+  title={The Soil and Water Assessment Tool: historical development, applications, and future research directions},
+  author={Gassman, Philip W and Reyes, Manuel R and Green, Colleen H and Arnold, Jeffrey G},
+  journal={Transactions of the ASABE},
+  volume={50},
+  number={4},
+  pages={1211--1250},
+  doi = {10.13031/2013.23637},
+  year={2007},
+  publisher={American Society of Agricultural and Biological Engineers}
+}
+
+@article{aloui2023,
+	title = {A review of Soil and Water Assessment Tool (SWAT) studies of Mediterranean catchments: Applications, feasibility, and future directions},
+	journal = {Journal of Environmental Management},
+	volume = {326},
+	pages = {116799},
+	year = {2023},
+	issn = {0301-4797},
+	doi = {10.1016/j.jenvman.2022.116799},
+	url = {https://www.sciencedirect.com/science/article/pii/S0301479722023726},
+	author = {Sarra Aloui and Annamaria Mazzoni and Adel Elomri and Jalel Aouissi and Abdelmadjid Boufekane and Adel Zghibi},
+	keywords = {Soil and water assessment tool, Watershed modeling, Mediterranean catchment, Model performance},
+}
+
+@article{ilampooranan2019,
+  author = {Ilampooranan, Idhayachandhiran and Van Meter, K. J. and Basu, Nandita B.},
+  title = {A Race Against Time: Modeling Time Lags in Watershed Response},
+  journal = {Water Resources Research},
+  volume = {55},
+  number = {5},
+  pages = {3941-3959},
+  keywords = {Nitrogen, Legacy, Lag Time, SWAT, Travel Time Distribution, Best Management Practices},
+  doi = {10.1029/2018WR023815},
+  url = {https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/2018WR023815},
+  eprint = {https://agupubs.onlinelibrary.wiley.com/doi/pdf/10.1029/2018WR023815},
+  year = {2019}
+}
+
+@article{nguyen2022,
+  title = {An interactive graphical interface tool for parameter calibration, sensitivity analysis, uncertainty analysis, and visualization for the Soil and Water Assessment Tool},
+  journal = {Environmental Modelling & Software},
+  volume = {156},
+  pages = {105497},
+  year = {2022},
+  issn = {1364-8152},
+  doi = {10.1016/j.envsoft.2022.105497},
+  url = {https://www.sciencedirect.com/science/article/pii/S1364815222002006},
+  author = {Tam Van Nguyen and J{\"o}g Dietrich and Thanh Duc Dang and Dang An Tran and Binh {Van Doan} and Fanny J. Sarrazin and Karim Abbaspour and Raghavan Srinivasan}
+}
+
+
+@misc{christoph2019,
+  author = {Christoph, Sch{\"u}rz},
+  title = {SWATplusR: Running SWAT2012 and SWAT+ Projects in R},
+  year = {2019},
+  publisher = {GitHub},
+  journal = {GitHub repository},
+  url = {https://github.com/chrisschuerz/SWATplusR},
+  doi = {10.5281/zenodo.3373859}
+}
+
+@article{lin2023,
+    author = {Lin, Qiaoying and Zhang, Dejian and Wu, Jiefeng and Fang, Yihui and Chen, Xingwei and Lin, Bingqing},
+    title = "{PAVLIB4SWAT: a Python analysis and visualization tool and library based on Kepler.gl for SWAT models}",
+    journal = {Journal of Hydroinformatics},
+    volume = {26},
+    number = {1},
+    pages = {189-202},
+    year = {2023},
+    month = {12},
+    issn = {1464-7141},
+    doi = {10.2166/hydro.2023.182},
+    url = {https://doi.org/10.2166/hydro.2023.182},
+    eprint = {https://iwaponline.com/jh/article-pdf/26/1/189/1360871/jh0260189.pdf},
+}
+
+@article{wang2023,
+  title = {Synergistic management of forest and reservoir infrastructure improves multistakeholders' benefits across the forest-water-energy-food nexus},
+  journal = {Journal of Cleaner Production},
+  volume = {422},
+  pages = {138575},
+  year = {2023},
+  issn = {0959-6526},
+  doi = {10.1016/j.jclepro.2023.138575},
+  url = {https://www.sciencedirect.com/science/article/pii/S0959652623027336},
+  author = {Lijuan Wang and Hua Zheng and Yongzhe Chen and Yanxu Long and Jinhang Chen and Ruonan Li and Xiaofei Hu and Zhiyun Ouyang},
+}
+
+@article{wu2024,
+  title = {Comprehensive effects of climate, land use/cover and management practices on runoff and nutrient variations in a rapidly urbanizing watershed},
+  journal = {Chemosphere},
+  volume = {349},
+  pages = {140934},
+  year = {2024},
+  issn = {0045-6535},
+  doi = {10.1016/j.chemosphere.2023.140934},
+  url = {https://www.sciencedirect.com/science/article/pii/S0045653523032046},
+  author = {Jiang Wu and Cheng-Xin Qin and Yao Yue and Shu-Peng Cheng and Hui Zeng and Ling-Yan He},
+}
+
+@article{li2024,
+	title = {Towards the hydrological effects of land use change in karst area, a case study in Lijiang River Basin, China},
+	journal = {Journal of Hydrology},
+	volume = {630},
+	pages = {130629},
+	year = {2024},
+	issn = {0022-1694},
+	doi = {10.1016/j.jhydrol.2024.130629},
+	url = {https://www.sciencedirect.com/science/article/pii/S0022169424000234},
+	author = {Wuhua Li and Xiangju Cheng and Dantong Zhu},
+}
+
+@article{karki2023,
+	title = {SWAT-3PG: Improving forest growth simulation with a process-based forest model in SWAT},
+	journal = {Environmental Modelling & Software},
+	volume = {164},
+	pages = {105705},
+	year = {2023},
+	issn = {1364-8152},
+	doi = {10.1016/j.envsoft.2023.105705},
+	url = {https://www.sciencedirect.com/science/article/pii/S1364815223000919},
+	author = {R. Karki and J. Qi and C.A. Gonzalez-Benecke and X. Zhang and T.A. Martin and J.G. Arnold},
+}
+
+@Article{ougahi2024,
+	AUTHOR = {Ougahi, Jamal Hassan and Rowan, John S.},
+	TITLE = {Combining Hydrological Models and Remote Sensing to Characterize Snowpack Dynamics in High Mountains},
+	JOURNAL = {Remote Sensing},
+	VOLUME = {16},
+	YEAR = {2024},
+	NUMBER = {2},
+	ARTICLE-NUMBER = {264},
+	URL = {https://www.mdpi.com/2072-4292/16/2/264},
+	ISSN = {2072-4292},
+	DOI = {10.3390/rs16020264}
+}
+
+@Article{myers2023,
+	AUTHOR = {Myers, D. T. and Jones, D. and Oviedo-Vargas, D. and Schmit, J. P. and Ficklin, D. L. and Zhang, X.},
+	TITLE = {Seasonal variation in landcover estimates reveals sensitivities and opportunities for environmental models},
+	JOURNAL = {EGUsphere},
+	VOLUME = {2023},
+	YEAR = {2023},
+	PAGES = {1--22},
+	URL = {https://egusphere.copernicus.org/preprints/2023/egusphere-2023-1171/},
+	DOI = {10.5194/egusphere-2023-1171}
+}
+
+@article{song2015,
+  title = {Global sensitivity analysis in hydrological modeling: Review of concepts, methods, theoretical framework, and applications},
+  journal = {Journal of Hydrology},
+  volume = {523},
+  pages = {739-757},
+  year = {2015},
+  issn = {0022-1694},
+  doi = {10.1016/j.jhydrol.2015.02.013},
+  url = {https://www.sciencedirect.com/science/article/pii/S0022169415001249},
+  author = {Xiaomeng Song and Jianyun Zhang and Chesheng Zhan and Yunqing Xuan and Ming Ye and Chonggang Xu},
+  keywords = {Global method, Hydrological model, Parameter optimization, Sensitivity analysis, Uncertainty analysis},
+}
+
+@article{abbaspour2022,
+	title = {The fallacy in the use of the "best-fit" solution in hydrologic modeling},
+	journal = {Science of The Total Environment},
+	volume = {802},
+	pages = {149713},
+	year = {2022},
+	issn = {0048-9697},
+	doi = {10.1016/j.scitotenv.2021.149713},
+	url = {https://www.sciencedirect.com/science/article/pii/S0048969721047884},
+	author = {K.C. Abbaspour},
+}
+
+@Article{delaigue2023,
+	AUTHOR = {Delaigue, O. and Brigode, P. and Thirel, G. and Coron, L.},
+	TITLE = {\texttt{airGRteaching}: an open-source tool for teaching hydrological modeling with~R},
+	JOURNAL = {Hydrology and Earth System Sciences},
+	VOLUME = {27},
+	YEAR = {2023},
+	NUMBER = {17},
+	PAGES = {3293--3327},
+	URL = {https://hess.copernicus.org/articles/27/3293/2023/},
+	DOI = {10.5194/hess-27-3293-2023}
+}
+
+@article{abbaspour2015,
+  title={SWAT-CUP: SWAT calibration and uncertainty programs-a user manual},
+  author={Abbaspour, Karim C},
+  journal={Eawag: D{\"u}bendorf, Switzerland},
+  year={2015}
+}
+
+@Article{Yen2019,
+AUTHOR = {Yen, Haw and Park, Seonggyu and Arnold, Jeffrey G. and Srinivasan, Raghavan and Chawanda, Celray James and Wang, Ruoyu and Feng, Qingyu and Wu, Jingwen and Miao, Chiyuan and Bieger, Katrin and Daggupati, Prasad and Griensven, Ann van and Kalin, Latif and Lee, Sangchul and Sheshukov, Aleksey Y. and White, Michael J. and Yuan, Yongping and Yeo, In-Young and Zhang, Minghua and Zhang, Xuesong},
+TITLE = {IPEAT+: A Built-In Optimization and Automatic Calibration Tool of SWAT+},
+JOURNAL = {Water},
+VOLUME = {11},
+YEAR = {2019},
+NUMBER = {8},
+ARTICLE-NUMBER = {1681},
+URL = {https://www.mdpi.com/2073-4441/11/8/1681},
+ISSN = {2073-4441},
+DOI = {10.3390/w11081681}
+}
+
+@Manual{r2021,
+  title = {R: A Language and Environment for Statistical Computing},
+  author = {{R Core Team}},
+  organization = {R Foundation for Statistical Computing},
+  address = {Vienna, Austria},
+  year = {2021},
+  url = {https://www.R-project.org/},
+}
+

joss/paper.md

@@ -0,0 +1,49 @@
+---
+title: 'RSWAT: An R package for the Soil and Water Assessment Tool models'
+tags:
+- R
+- SWAT
+- parameter calibration
+- sensitivity and uncertainty analysis
+date: "2 February 2024"
+output:
+  html_document:
+    df_print: paged
+authors:
+- name: Tam V. Nguyen
+  orcid: 0000-0001-9111-4393
+  equal-contrib: yes
+  affiliation: '1'
+bibliography: paper.bib
+affiliations:
+- name: Tam V. Nguyen, Helmholtz Centre for Environmental Research - UFZ,Germany
+  index: 1
+---
+
+# Summary
+
+Hydro-ecological model is an important tool for a quantitative understanding of hydro-ecological processes and their interactions. Parameter calibration, sensitivity, and uncertainty analyses play a crucial role in hydro-ecological modeling [@song2015; @abbaspour2022]. A model-specific tool is often required for parameter calibration, sensitivity, and uncertainty analyses as each model usually has its own input and output file format/structure. This study introduces the RSWAT package, which resulted from the continuous development of the R-SWAT shiny application [@nguyen2022] for the Soil and Water Assessment Tool (SWAT, @arnold1998) community. RSWAT has more functionalities compared to R-SWAT, allowing users to work with SWAT and different SWAT versions with or without using the graphical user interface (GUI).
+
+# Statement of need
+
+The SWAT model is one of the most widely used and tested hydro-ecological models [@gassman2007; @aloui2023]. SWAT has been constantly developed since its development due to an improved understanding of hydro-ecological processes [e.g., @ilampooranan2019] and to solve new challenges. On the other hand, SWAT also enhances our understanding of reality and contributes to water resources management at both local and regional scales [@gassman2007]. While most of the changes in SWAT are minors, there are major changes [@bieger2017]. Many technical challenges arise when working with models that are constantly changing. For example, model parameter calibration, sensitivity, and uncertainty analyses are not an easy task as (1) SWAT has numerous input files and parameters, and (2) there is a lack of a standard tool that can cope with these changes.
+
+Various tools have been developed to support SWAT modeling, for example, [ArcSWAT](https://swat.tamu.edu/software/arcswat/), [QSWAT](https://swat.tamu.edu/software/qswat/), R-SWAT [@nguyen2022], SWAT-CUP [@abbaspour2015], SWATrunR [@christoph2019], and IPEAT+ [@Yen2019]. Among those, R-SWAT is the only R-based application with the GUI that can work with various versions of SWAT (e.g., [SWAT-Carbon](https://sites.google.com/view/swat-carbon)) without modifying the R-SWAT code. R-SWAT has various built-in and add-on methods for automatic parameter calibration and/or parameter sensitivity and uncertainty analyses from the R community. However, as a shiny application (not an R package), installing R-SWAT is troublesome since R-SWAT depends on many R packages. In addition, R-SWAT has no clear separation of functions for the GUI and stand-alone functions for working without the GUI. No documentation of the R-SWAT functions also makes it difficult to use without the GUI. R-SWAT cannot be employed for SWAT+ [@bieger2017], a completely revised structure of SWAT. R-SWAT does not support interactive manual calibration of SWAT and SWAT+ in a similar way to airGRteaching [@delaigue2023], which is especially useful for teaching. Therefore, major changes in R-SWAT are needed to overcome the aforementioned limitations. 
+
+
+# Features
+RSWAT is an R [@r2021] package developed based on the original version of the R-SWAT shiny application. Therefore, RSWAT inherits the following functionalities of the R-SWAT: 
+
+  + Automatic parameter calibration, sensitivity, and uncertainty analyses for SWAT with the GUI using various approaches.
+  + Visualization of the simulated and observed variables. 
+
+Spatial visualization of the model results was not included in RSWAT as this option is not often used by users and there exist different tools for this (e.g., PAVLIB4SWAT, @lin2023). Additional features of RSWAT compared to R-SWAT are:
+
+  + Automatic parameter calibration, sensitivity, and uncertainty analyses for SWAT and SWAT+ with and without using the GUI. 
+  + Manual interactive calibration of SWAT and SWAT+.
+
+# Mention
+  R-SWAT/RSWAT is being adopted for SWAT/SWAT+ modeling. Currently, there are more than 160 users in the [R-SWAT Google group](https://groups.google.com/g/R-SWAT) with more than 120 discussion topics. R-SWAT/RSWAT was used in some recent publications (@wang2023 @wu2024 
+@li2024, @karki2023, @ougahi2024, @myers2023). With additional features, RSWAT is expected to be used not only in research but also in teaching.
+
+# References