Please not that rSOILWAT2
compiles C source code of SOILWAT2
-- see section on binary version below for alternatives.
Your computer must be set up adequately (see below for requirements).
On the command line
git clone -b main --single-branch --recursive \
https://github.com/DrylandEcology/rSOILWAT2.git rSOILWAT2
R CMD INSTALL rSOILWAT2
Using R
system2(
command = "git",
args = paste(
"clone -b main --single-branch --recursive",
"https://github.com/DrylandEcology/rSOILWAT2.git",
"rSOILWAT2"
)
)
tools::Rcmd(args = "INSTALL rSOILWAT2")
Using the remotes
R package
remotes::install_github("DrylandEcology/rSOILWAT2", build_vignettes = TRUE)
Please note that "remotes" will download the latest version of SOILWAT2
irrespective of what the actual submodule status requests
(see remotes issue #260).
If it happens that the latest SOILWAT2 version doesn't yet work
correctly with the latest version of rSOILWAT2
(as has happened in issue #175),
then please use one of the other options above to
correctly install rSOILWAT2
or explore one of the development branches.
If you require a binary version of the 'rSOILWAT2' 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), e.g.,
Linux
, Windows
, and macOS
flavors as targetsRtools
that match your R versionmacOS
:
xcode
command line tools
(run xcode-select --install
on the command line)xcode
license (run xcodebuild -license
)xcode
installationlatex
installation (see below) and
pandoc
(RStudio
comes bundled with pandoc
)
to generate package vignetteslatex
installationinstall the R package tinytex
install.packages("tinytex")
tinytex::install_tinytex()
if you don't have write permission for /usr/local/bin
,
then appropriate symlinks are not generated;
thus, locate the path to tlmgr
, e.g.,
with help of tinytex::tinytex_root()
, and
fix symlinks with escalated privileges
sudo [path/to/]tlmgr path add
rSOILWAT2
offers documentation and code examples of exported functions
help(package = "rSOILWAT2")
, in particular ?sw_exec
,
and several vignettes
vignette(package = "rSOILWAT2")
, in particular
vignette("rSOILWAT2_demo", package = "rSOILWAT2")
.
The DrylandEcology
team hosts a group of related repositories and R packages.
They are organized around two simulation models, i.e., SOILWAT2, an dryland ecosystem water balance simulation model, and STEPWAT2, an individual-based model for dryland plant communities. They are both written in compiled languages.
We developed a family of R packages to support SOILWAT2 and STEPWAT2 simulation experiments:
netCDF
filesYou can help us in different ways:
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.
We develop code on development branches and, after they are reviewed and pass our checks, merge them into the main branch for release:
DESCRIPTION
) to a
development version (ending in -9000
)NEWS
DESCRIPTION
NEWS
rSOILWAT2
releaseNAMESPACE
file with the command
devtools::document()
devtools::run_examples()
lintr::lint_package()
to confirm that code conforms to
our style guide (see file .lintr
) and update code style where needed
before pushing a commit or finalizing a pull-request.This is based on the section 'Testing' of the book 'R packages' by Wickham
Unit tests
devtools::test()
Package checks
Package checks are run with
devtools::check(cran = TRUE, env_vars = c(NOT_CRAN = "true"))
or
R CMD build . && NOT_CRAN = "true" R CMD check *.tar.gz
Package checks include unit tests, code style, and spelling
These checks will be run on the continuous integration frameworks
via a workflow in Github Action
for pull requests
Development/feature branches can only be merged into main if they pass all checks
Integration tests: run a default example and examine the
output (see also ?sw_exec
), e.g.,
path_demo <- system.file("extdata", "example1", package = "rSOILWAT2")
x <- rSOILWAT2::sw_exec(dir = path_demo)
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.
Make sure that the documentation is up-to-date with:
pkgbuild::compile_dll()
devtools::document()
Run and check the code from the examples and vignettes:
devtools::run_examples()
Run tests as if not on CRAN in an interactive R session.
# Run in R.app, RStudio, or in an R terminal-session:
Sys.setenv(NOT_CRAN = "true")
devtools::test()
Notes:
RSOILWAT_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(RSOILWAT_ALLTESTS = "false"); devtools::test()
RSOILWAT_ALLTESTS="false" R CMD check *tar.gz
Run tests as if not on CRAN in an non-interactive session.
# Run via shell in the terminal:
R CMD INSTALL .
Rscript -e 'Sys.setenv(NOT_CRAN = "true"); devtools::test()'
The environmental variable RSOILWAT_INTEGRATIONTESTS
determines
whether intensive (and potentially interactive) integration tests are
executed; the default is "false".
To set it to true, e.g.,
Sys.setenv(RSOILWAT_INTEGRATIONTESTS = "true"); devtools::test()
RSOILWAT_INTEGRATIONTESTS="true" R CMD check *tar.gz
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:
R CMD check
warnings and/or notes; see, milestone
Clean codeThere are additional tests available in tools/
(which may have additional dependencies), e.g.,
test_dbW_concurrency.R
Debugging compiled code
src/
and src/SOILWAT2/
in 'debugging' mode.
This will define SWDEBUG
in SOILWAT2
source code
(see the README of SOILWAT2):
MAKEFLAGS="PKG_DEBUG=-DRSWDEBUG" R CMD INSTALL --preclean --clean .
devtools
(e.g., while running R interactively):
Sys.setenv(PKG_DEBUG="-DRSWDEBUG")
devtools::clean_dll() # if you debug in `src/SOILWAT2`
devtools::load_all(compile = TRUE)
gdb
/lldb
, please see the
section 'Debugging-compiled-code' in the 'R-exts' manualHow to update the submodule 'SOILWAT2' to the latest commit
git submodule update --remote #--remote: uses the latest commit; without --remote: uses the previously defined commit
git commit -am "Pulled down latest commit 'COMMIT-FLAG' for submodule SOILWAT2"
git push
Change the branch of submodule SOILWAT2
open .gitmodules # and change branch = <branch> to the desired <branch>
git submodule init
git submodule update --remote #--remote: uses the latest commit; without --remote: uses the previously defined commit
git commit -am "Changed to branch 'branch' commit 'COMMIT-FLAG' for submodule SOILWAT2"
git push
Run the script ./data-raw/prepare_testInput_objects.R
from within rSOILWAT2/
if the SOILWAT2
updated included changes to the input files.
We base our versions on the guidelines of semantic versioning
with version numbers of MAJOR.MINOR.PATCH
.
We create a new release for each update to the main branch;
a new release is identified by the package version (DESCRIPTION
) and
by a github release
that also creates a git tag of the same name.
The main branch is updated via pull requests from development branches
after they are reviewed and pass required checks.
If the version numbers changes, then the following files must be updated
DESCRIPTION
: adjust lines 'Version'NEWS
: add a new section describing pertinent changes to a package user
(see section 'NEWS' of the book 'R packages' by Wickham and
tidyverse
news style)Please cite the package if you publish results based on simulations carried
out with our package, see citation("rSOILWAT2")
, and we would like to hear
about your publication.
Some other references
References for the original version of Soilwat
We haven't really published the code yet nor prepared it for sharing (though
through our use of github
made it openly accessible), it is actively and
gradually being developed by the Lauenroth lab and affiliates, and there is
no manual either - we cannot give you individual support in setting up and
running the model except if we agreed on a collaboration or similar agreement.
Not every part of the code has been extensively tested or is in a stable state. Similarly, not every combination of model inputs and options has been evaluated in depth and there is not guarantee for anything to work. The code comes with no warranty and no guarantees, expressed or implied, as to suitability, completeness, accuracy, and whatever other claim you would like to make.
There is no graphical user interface, help pages and available documentation may be out of date, and you will need to write your own tools to analyze outputs.
Work on this package has been supported by various funds managed by Dr. John Bradford (USGS), Dr. Bill Lauenroth (Yale University), Dr. Kyle Palmquist (Marshall University), 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.