Unix	Windows	Release	License	Coverage	Downloads

rSFSW2: A R package to create soil water balance simulation experiment

Please cite the package if you publish results based on simulations carried out with our package, see citation("rSFSW2"), and we would like to hear about your publication.

Some other references

• Bradford, J. B., D. R. Schlaepfer, and W. K. Lauenroth. 2014. Ecohydrology of adjacent sagebrush and lodgepole pine ecosystems: The consequences of climate change and disturbance. Ecosystems 17:590-605.
• Palmquist, K.A., Schlaepfer, D.R., Bradford, J.B., and Lauenroth, W.K. 2016. Mid-latitude shrub steppe plant communities: climate change consequences for soil water resources. Ecology 97:2342-2354.
• Schlaepfer, D. R., W. K. Lauenroth, and J. B. Bradford. 2012. Ecohydrological niche of sagebrush ecosystems. Ecohydrology 5:453-466.

Obtain the source package

There are several options:

• Download the package zip file via your web browser.

• Use git to clone

  git clone -b master --single-branch https://github.com/DrylandEcology/rSFSW2.git rSFSW2
  

• Use git to clone step by step

  git clone https://github.com/DrylandEcology/rSFSW2.git rSFSW2
  cd rSFSW2/
  git checkout master
  

Installation

'rSFSW2' will compile some c code via 'Rcpp'. Your computer must be set up adequately.

• If you use a Windows OS, then you need the Rtools installed that match your R version; please find further information for instance here.
• If you use a macOS, then you need Xcode and its command-line tools installed; please find further information for instance here.

After you downloaded the source package, run

R CMD INSTALL rSFSW2

Or do all at once from within R:

system2(command = "git", args = "clone -b master --single-branch https://github.com/DrylandEcology/rSFSW2.git rSFSW2")
tools::Rcmd(args = paste("INSTALL rSFSW2"))

Binary package version

If you want a binary version of the 'rSFSW2' package (e.g., to distribute to someone without development tools) for a platform to which you do not have access, then you may consider using one of the cloud services (no endorsements):

• r-hub offers different Linux, Windows, and mac OS flavors as targets
• win-builder offers Windows OS as target

Alternatively, you may access the previous binary package version for Windows OS from our CI appveyor service if the build was successful and an artifact was generated for the binary package (this would be named 'rSWSF2_X.Y.Z.zip' with version number X.Y.Z) from here. If the latest build should have failed, then you may want to check out the 'History' tab for binaries of older versions.

Use rSFSW2 for your simulation project

Familiarize yourself with the demos and information at package?rSFSW2 as well as FAQs with vignette("rSFSW2_FAQs", package = "rSFSW2").

Setup a new simulation project:

1. Install and attach 'rSFSW2' if not already done so (Note: required version of rSOILWAT2 must already be present)
2. Create a skeleton project `setup_rSFSW2_project_infrastructure(dir_prj = "path/to/project_folder")
   • This function will copy a default version of '1_Input' and the three demo R files to your directory
3. Work your way through 'SFSW2_project_code.R', i.e., define paths and actions, and provide simulation project description in 'SFSW2_project_descriptions.R' and run settings in 'SFSW2_project_settings.R'

How to contribute

You can contribute to this project in different ways:

1. Reporting issues
2. Contributing code following our protocols/guidelines and sending a pull request

Code development: Tests, documentation, and code form a trinity

• Code style

  • Use code style that passes our lintr unit tests which basically reflect Hadley's style recommendation. Note: we require lintr v1.0.2.900 or later.
  • Use 2-spaces instead of tabs and indent code hierarchically
  • Note, many function and variable names are "ancient" (too long; combine snake and camel-case)

• Updates to input files and/or demo code

  • If SOILWAT2 and rSOILWAT2 change their default inputs, then rSFSW2 will automatically experience these changes through function read_SOILWAT2_DefaultInputs. This function may need to be updated accordingly to provide suitable defaults for rSFSW2 runs.
  • If you change 'input files' in data-raw/1_Input (e.g., added a new column to experimental/design treatment file) then update the R/sysdata.rda object by running the Rscript from terminal ./data-raw/prepare_default_project_infrastructure.R. The file R/sysdata.rda is used to setup a new simulation project.
  • Additionally, if 'input files' and/or 'demo code' in demo/ changes, then update the unit test 'test project' tests/test_data/TestPrj4/ by running the Rscript from terminal ./data-raw/update_test_project_infrastructure.R and make any necessary additional changes by hand.

• Interactive code development

  • Use (a copy of) tests/test_data/TestPrj4/ as basis to interact with code and a real simulation project, for instance:

    library("devtools")
    load_all()
    setwd("rSFSW2/tests/test_data/TestPrj4/")
    
    # Adjust inputs if necessary and insert break points (e.g., calls to
    # `browser()` or `stop()`) if needed
    source("SFSW2_project_code.R") # run `TestPrj4` and stop where you need it
    
    # Develop/debug code
    # e.g., compare output with reference as if running `tests()`:
    compare_two_dbOutput("../0_ReferenceOutput/dbOutput_TestPrj4_v2.7.4.sqlite3", "4_Simulation/dbOutput.sqlite3")
    
    # Clean up `TestPrj4/`
    delete_test_output(dir_test = ".")
    

  • Do not commit, please:

    • Any changes to settings/inputs etc. in your local copy unless those changes are a feature of your coding task
    • Do not comment/turn-off any tests and/or checks
    • Print statements for local debugging purposes
    • Package bundles or binaries (e.g., as from R CMD build)
    • Package check reports (e.g., as from R CMD check)
    • Built vignettes
    • etc

• Code documentation

  • Read the section 'Object documentation' in Wickham's book 'R packages'
  • Use roxygen2 to write inline code documentation
  • Update help pages and NAMESPACE with the command devtools::document(); note: you may need to compile dynamic libraries first with pkgbuild::compile_dll().
  • Ideally, add examples to function documentation and check these examples with the command devtools::run_examples(). Note: "devtools" v2.0.1 mixed up the logic for "dontrun" examples (see https://github.com/r-lib/devtools/issues/2003); until this is fixed, use devtools::run_examples(run = FALSE).
  • Ideally, expand and/or add vignettes.

• Code tests

  • Notes:

    • Our code coverage is incomplete as of now at ; thus, any change may introduce bugs that may not be detected by our testing framework.
    • Please be careful and considerate and strive to write tests for any new feature.
    • Our tests behave differently depending on several run-time conditions:
      1. Level of verbosity is determined by interactive/non-interactive status whether or not simulations are run in parallel (non-interactive) or sequentially (interactive),
      2. Simulation runs are processed in parallel if session is non-interactive, not on travis-ci, not on appveyor-ci, and not on CRAN whereas they are processed sequentially if session is interactive, on travis-ci, on appveyor-ci, or on CRAN
      3. Live access to the internet is required by some unit tests, e.g., tests/testthat/test_netCDF_functions.R and tests/testthat/test_WeatherDB_DayMet.R
      4. Some unit tests are skipped if on CRAN, and/or on travis-ci, and/or on appveyor-ci, e.g., test/testthat/test_rSFSW2_Spelling.R and test/testthat/test_rSFSW2_CodeStylePractices.R

  • Test code locally during code development:

    • Interactive execution and exploration
    • Interactive execution of individual expectations expect_* and/or test_that() statements; write new expectations at the same time as writing and developing code.
    • Run tests from an individual test file with testthat::test_file()

      • You may likely need to first load the latest code version with devtools::load_all() for R code, and with devtools::load_all(recompile = TRUE) if your changes include C code

      • Most likely, this will run tests as if on CRAN (depending on your specific setup), i.e., it will skip several of our tests:

        • it is set as NOT_CRAN="true" if run with:
          • devtools::test() unless NOT_CRAN was previously set
          • devtools::check(cran = FALSE)
          • R CMD check *tar.gz
        • it is set as NOT_CRAN="false" (i.e, behaving as if run on CRAN) if run with:
          • Sys.setenv(NOT_CRAN = "false"); devtools::test()
          • devtools::check(cran = TRUE)
          • R CMD check *tar.gz --as-cran

      • If you don't like the output format of the tests (which differs depending on whether you run R interactively or not, whether you run R via RStudio or not, etc.), then chose a testthat-'reporter' explicitly, e.g., testthat::test_file(reporter = SummaryReporter)

    • Run all tests together with testthat::test(), but it is a waste of time and resources to re-run tests again and again during development that are not affected by your code changes
    • Currently defunct: Ideally, run test projects in repository rSFSW2_tools and add a new test project, if necessary due to new features.

  • Run the following steps locally in order to prepare a pull-request or commit that will be reviewed. Fix any problem and repeat as necessary.

    1. Make sure that the anticipated version of rSOILWAT2 is indeed installed, e.g.,

       packageVersion("rSOILWAT2")
       

    2. Make sure that the documentation is up-to-date with:

       pkgbuild::compile_dll()
       devtools::document()
       

    3. Run and check the code from the examples and vignettes:

       devtools::run_examples()
       

       Note: "devtools" v2.0.1 mixed up the logic for "dontrun" examples (see https://github.com/r-lib/devtools/issues/2003); until this is fixed, use devtools::run_examples(run = FALSE).

    4. Run tests as if not on CRAN, in an interactive R session, and with a sequential schedule.

       # Run in R.app, RStudio, or in an R terminal-session:
       Sys.setenv(NOT_CRAN = "true")
       devtools::test()
       

       Notes:

       • Make sure that no test is skipped. Investigate if any is skipped.
       • Investigate if any warning is reported.
       • This combines unit tests, documentation and code-style checks, and integration tests (e.g., TestPrj4); the latter two take a substantial amount of time to complete. The environmental variable RSFSW2_ALLTESTS determines whether or not long-running expectations/unit-tests are skipped; the default is "true", i.e., run all expectations/unit-tests. You may decide to run tests while temporary skipping time-intensive tests, e.g.,
       • Sys.setenv(RSFSW2_ALLTESTS = "false"); devtools::test()
       • RSFSW2_ALLTESTS="false" R CMD check *tar.gz

    5. Run tests as if not on CRAN, in an non-interactive session, and with a parallel schedule.

       # Run via shell in the terminal:
       R CMD INSTALL .
       Rscript -e 'Sys.setenv(NOT_CRAN = "true"); devtools::test()'
       

       Notes:

       • Parallel workers will load the package rSFSW2 "normally", i.e., from the R library path. Thus, the workers do not see the development version. Therefore, we need to install the current version before running tests in parallel. You can convince yourself of this by first removing rSFSW2 with remove.packages("rSFSW2") and then run above command -- the tests will fail with errors such as object 'SFSW2_glovars' not found or all(tp[["res"]][, "has_run"]) isn't true.
       • Make sure that the integration test (e.g., TestPrj4) was indeed run in parallel (output reports on the number of workers).

    6. The environmental variable RSFSW2_SAVETESTS determines whether or not the otherwise invisible internal testthat results are saved to file which can be useful for debugging; the default is "true" in non-interactive mode, i.e., save results, and "false" in interactive mode. To set it to true, e.g.,

       • Sys.setenv(RSFSW2_SAVETESTS = "true"); devtools::test()
       • RSFSW2_SAVETESTS="true" R CMD check *tar.gz

       To illustrate how to read in such reporter output and display its content (note: you may need to adjust the file path):

         utres <- readRDS(file.path("rSFSW2.Rcheck", "tests", "testthat_results.rds"))
         r <- ListReporter$new()
         r$start_reporter()
         force(utres) # print test results with `ListReporter`
         r$end_reporter()
       
         utres[[1]] # explore results of first set of tests
       

    7. Run R package-level checks as if on CRAN.

       # Run in R.app, RStudio, or in an R terminal-session:
       Sys.setenv(NOT_CRAN = "false")
       devtools::check(cran = TRUE)
       

       Notes:

       • Avoid adding new R CMD check warnings and/or notes; see, milestone Clean code

    Notes: The above steps can also be executed with different commands and there are more combinations that could be tested. For instance, you could use R CMD instead of devtools::check, e.g., see Writing R Extensions. As an example, R-package level checks could also be run with:

    R CMD build . && R CMD check *tar.gz
    

    Unless the build-step fails due to latex-troubles while building the vignette and/or help pages, then maybe:

    R CMD build --no-build-vignettes --no-manual .
    R CMD check *tar.gz --ignore-vignettes --no-manual
    

    You could also pass the argument --as-cran to R CMD check to simulate checks as if on CRAN.

    1. Fix any problem and repeat.

  • On github:

    • The command-line checks which include our unit tests will be run on the continuous integration frameworks 'travis' and 'appveyor'
    • Development/feature branches can only be merged into master if they pass all checks
    • Ideally, each pull-request will include fully-tested changes, at least they should be as thoroughly tested as master so that overall code coverage after merging into master does not decrease.
    • Please, don't use the CIs for debugging -- debug locally

  • We use the framework of testthat for unit testing and other tests for the package

  • Read the section 'Testing' in Wickham's book 'R packages' for additional information

Code of conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Funding

Work on this package has been supported by various funds managed by Dr. Bill Lauenroth (Yale University), Dr. John Bradford (USGS), and Dr. Daniel Schlaepfer.

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 of the License.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Notes

Organization renamed from Burke-Lauenroth-Lab to DrylandEcology on Dec 22, 2017

All existing information should automatically be redirected to the new name. Contributors are encouraged, however, to update local clones to point to the new URL, i.e.,

git remote set-url origin https://github.com/DrylandEcology/rSFSW2.git

Repository renamed from SoilWat_R_Wrapper to rSFSW2 on Feb 23, 2017 All existing information should automatically be redirected to the new name. Contributors are encouraged, however, to update local clones to point to the new URL, i.e.,

git remote set-url origin https://github.com/DrylandEcology/rSFSW2.git