search

ryanpmcg / WEPPCLIFF

An R-based command line tool designed to prepare climate inputs for WEPP, which has been extended to perform other general functions such as quality checking, gap filling, and erosion index calculations (climate inputs for USLE family models).
GNU Affero General Public License v3.0
12 stars 5 forks source link

readme

WEPPCLIFF

An R-based command line tool designed to prepare climate inputs for WEPP, which has been extended to perform other general functions such as quality checking, gap filling, and erosion index calculations (climate inputs for USLE family models). This software was published in the Journal of Open Source Software DOI.

Important Note -- Updated 1 October 2024

After many version updates and tests with different machines on various architectures and OSs, I have concluded that after a new device, OS, or R-version release, it is best to wait a few months before attempting to install WEPPCLIFF on those new versions as the required dependencies may or may not be available for the specific combination of hardware, OS, and software (e.g., R). If you encounter an issue with a particular combination, it is best to roll back to an earlier version of R that has been tested with WEPPCLIFF. Here is a list of known working versions for any device or OS I have tested:

  1. WEPPCLIFF v1.7 -- (R v4.4.1) -- (R v4.2.2)
  2. WEPPCLIFF v1.5 -- (R v3.6.1)

How to Install

Follow the following steps closely!

  1. Clone this repository to your own preferred location (for Windows, it is recommended to use the C:/ drive).
  2. Install R version 3.6.1 or later (WEPPCLIFF was most recently validated with R-4.2.2).
  3. If you are using Windows, install the corresponding version of Rtools from here.
  4. From the directory containing WEPPCLIFF.R run:

(UNIX) bash ./INSTALLER/Install.sh --OR-- (Windows) ./INSTALLER/Install.bat

Run Tutorial Manually (as Intended) on UNIX or Windows.

Open the Tutorial (and WEPPCLIFF Documentation if more information is desired) and follow the instructions within. Otherwise, follow instructions below for an automated tutorial and testing. For a comprehensive list of WEPPCLIFF flags and arguments, see the Manual.

Run Automated Tutorial on UNIX or Windows

UNIX: From the directory containing WEPPCLIFF.R run: bash ./TUTORIAL/AutoTutorial.sh

Windows: From the directory containing WEPPCLIFF.R run: ./TUTORIAL/AutoTutorial.bat

Run Automated Test (Installation Validation)

UNIX: From the directory containing WEPPCLIFF.R run: bash ./AUTOTEST/AutoTest.sh

Windows: From the directory containing WEPPCLIFF.R run: ./AUTOTEST/AutoTest.bat

Current Version

Version 1.7 is the most recent upload to this repository, which included a major update to support automated aggregation of precipitation data. This new functionality can be accessed via the option: '-ai ' as long as 1440 is divisible by the integer. The Manual has been updated with these changes, though the WEPPCLIFF Documentation is not planned to be updated until the next major release. Improvements to the gap-filling model (including a comprehensive validation of its capabilities) are planned for the next major release (i.e., WEPPCLIFF v2.0).

Contributions

Contributions are always warmly welcomed. Any contributions that materially improve performance, capabilities, accuracy, compatibility, etc. will be gladly incorporated in the source code, credited, and distributed through this repository. Ideally, contributions should proceed something like the following, but this should not be legalistic in any way:

  1. An issue is opened to see if the proposed changes have not already been considered and would be useful.
  2. If the feedback is positive, the contributor should fork the repository and make their proposed changes to the code.
  3. When edits to the branch (and testing by the contributor) are completed, the contributor should make a pull request.
  4. If there are no problems, the new changes will be merged and distributed with the next version release.

Support

Only WEPPCLIFF-related issues are supported. If you have trouble with installing R, running command-line scripts, or other basics, support is not guaranteed. With that said, you may ask questions on the General Questions and Support Issue here: https://github.com/ryanpmcg/WEPPCLIFF/issues/11.

Issues

To report a potential bug, suggest an improvement, or raise other points to the community, please open an issue. If there is a problem, please provide the following:

  1. Your OS and applicable hardware limitations
  2. Your version of R
  3. Your WEPPCLIFF command
  4. Your input files
  5. Your output (if there is any) and the correct output (if applicable)
  6. Your WEPPCLIFF/AUTOTEST/OUTPUT folder as a .zip file (if applicable)

Conduct

Do not let this become an issue. Obviously poor conduct will result in a ban.

Dependencies

WEPPCLIFF is grateful to the open source community and relies on the hard work of others for part of its own success. All of this work from others is represented by the various packages listed below, which are required for various portions of WEPPCLIFF code to work (listed in order of installation).

  1. backports
  2. crayon
  3. vctrs
  4. tzdb
  5. cli
  6. vroom
  7. readr
  8. rlist
  9. iterators
  10. foreach
  11. doParallel
  12. EnvStats
  13. mice
  14. RcppParallel
  15. withr
  16. ggplot2
  17. profvis
  18. data.table
  19. jsonlite
  20. climextRemes