| Unix | Windows | Release | License | Coverage | Downloads | | :---- | :---- | :---- | :---- | :---- | :---- | | | | | | |
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
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
'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"))
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.
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'
You can contribute to this project in different ways:
lintr
unit tests
which basically reflect
Hadley's style recommendation.
Note: we require lintr v1.0.2.900
or later.Note, many function and variable names are "ancient" (too long; combine snake and camel-case)
Updates to input files and/or demo code
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.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:
```{r}
library("devtools")
load_all()
setwd("rSFSW2/tests/test_data/TestPrj4/")
browser()
or stop()
) if neededsource("SFSW2_project_code.R") # run TestPrj4
and stop where you need it
tests()
:compare_two_dbOutput("../0_ReferenceOutput/dbOutput_TestPrj4_v2.7.4.sqlite3", "4_Simulation/dbOutput.sqlite3")
TestPrj4/
delete_test_output(dir_test = ".") ```
Do not commit, please:
R CMD build
)R CMD check
)Code documentation
devtools::document()
;
note: you may need to compile dynamic libraries first with
pkgbuild::compile_dll()
.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:
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:
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()
devtools::load_all()
for R code, and with
devtools::load_all(recompile = TRUE)
if your changes include C codeNOT_CRAN="true"
if run with:devtools::test()
unless NOT_CRAN
was previously setdevtools::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)
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 changesRun the following steps locally in order to prepare a pull-request or commit that will be reviewed. Fix any problem and repeat as necessary.
Make sure that the anticipated version of rSOILWAT2
is indeed
installed, e.g.,
{r}
packageVersion("rSOILWAT2")
Make sure that the documentation is up-to-date with:
{r}
pkgbuild::compile_dll()
devtools::document()
Run and check the code from the examples and vignettes:
{r}
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)
.
Run tests as if not on CRAN, in an interactive R session,
and with a sequential schedule.
{r}
# Run in R.app, RStudio, or in an R terminal-session:
Sys.setenv(NOT_CRAN = "true")
devtools::test()
Notes:
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
Run tests as if not on CRAN, in an non-interactive session,
and with a parallel schedule.
{bash}
# Run via shell in the terminal:
R CMD INSTALL .
Rscript -e 'Sys.setenv(NOT_CRAN = "true"); devtools::test()'
Notes:
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
.TestPrj4
) was indeed run
in parallel (output reports on the number of workers).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):
``{r}
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
```
{r}
# Run in R.app, RStudio, or in an R terminal-session:
Sys.setenv(NOT_CRAN = "false")
devtools::check(cran = TRUE)
Notes:R CMD check
warnings and/or notes; see, milestone
Clean codeNotes: 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:
{bash}
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:
{bash}
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.
On github:
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
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.
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.
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.
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
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.