soilReports

Reports are a handy way to summarize large volumes of data, particularly with figures and tables. soilReports is an R package “container” designed to accommodate the maintenance, documentation, and distribution of R-based reporting tools. Inside the package are report templates, setup files, documentation, and example configuration files.

The soilReports package provides a couple important helper functions that do most of the work:

listReports(): print a listing of the available reports, version numbers, and basic metadata
reportSetup(...): download any R packages required by the named report, e.g. “region2/mu-comparison”
reportInit(...) reportCopy(...): copy a named report template into a specific directory
reportUpdate(...): update a named report in a specific directory, replacing report.Rmd only

Each report contains several files:

report.Rmd: an R Markdown file that is “knit” into a final HTML or DOC report
README.md: report-specific instructions
custom.R: report-specific functions
categorical_definitions.R: report-specific color mapping and metadata for categorical raster data (user-editable)
config.R: configuration file to set report parameters (user-editable)
changes.txt: notes on changes and associated version numbers

R Profile Setup

NOTE: The following instructions are rarely, if ever, needed with R 4.2+

On many of our machines, the $HOME directory points to a network share. This can cause all kinds of problems when installing R packages, especially if you connect to the network by VPN. The following code is a one-time solution and will cause R packages to be installed on a local disk by adding an .Rprofile file to your $HOME directory. This file will instruct R to use C:/Users/FirstName.LastName/Documents/R/ for installing R packages. Again, you only have to do this once.

# determine your current $HOME directory
path.expand('~')

# install .Rprofile
source('https://raw.githubusercontent.com/ncss-tech/soilReports/master/R/installRprofile.R')
installRprofile(overwrite=TRUE)

soilReports Installation - First time or after R upgrade

Run this code if you don’t yet have the soilReports package or after a new version of R has been installed on your machine.

# need devtools to install packages from GitHub
install.packages('remotes', dep = TRUE)

# get the latest version of the 'soilReports' package
remotes::install_github("ncss-tech/soilReports", dependencies = FALSE, upgrade_dependencies = FALSE) 

Choose an Available Report

Region 2
Region 11
- Component Summary by Project
- MUPOLYGON Summary by Project

Example Output

Reports for Raster Summary by MU or MLRA

Reports for DMU QC/QA

Reports for Pedon Data

Run a Report - Example: Map Unit Comparison report

# load this library
library(soilReports)

# list reports in the package
listReports()

# install required packages for a named report
reportSetup(reportName='region2/mu-comparison')

# copy report file 'MU-comparison' to your current working directory
reportInit(reportName='region2/mu-comparison', outputDir='MU-comparison')

Updating Existing Reports - Example: Map Unit Comparison report

Updates to report templates, documentation, and custom functions are available after installing the latest soilReports package from GitHub. Use the following examples to update an existing copy of the “region2/mu-comparison” report. Note that your existing configuration files will not be modified.

# get latest version of package + report templates
remotes::install_github("ncss-tech/soilReports", dependencies=FALSE, upgrade_dependencies=FALSE)

# load this library
library(soilReports)

# get any new packages that may be required by the latest version
reportSetup(reportName='region2/mu-comparison')

# overwrite report files in an existing report instance (does NOT overwrite config)
reportUpdate(reportName='region2/mu-comparison', outputDir='MU-comparison')

Suggested Background Material

The user is familiar with Rstudio
NASIS selected set is loaded with the necessary tables (e.g. “Project - legend/mapunit/dmu by sso, pname & uprojectid”)
ODBC connection to NASIS is setup
custom .Rprofile exists
necessary R packages are installed

Troubleshooting

If you haven’t run R in a while, consider updating all packages with: update.packages(ask=FALSE, checkBuilt=TRUE).
Make sure that all raster data sources are GDAL-compatible formats: GeoTiff, ERDAS IMG, ArcGRID, etc. (not ESRI FGDB)
Make sure that the map unit polygon data source is an OGR-compatible format: ESRI SHP, ESRI FGDB, etc.
Make sure that the extent of raster data includes the full extent of map unit polygon data.
If there is a problem installing packages with reportSetup(), consider adding the upgrade=TRUE argument.
If you are encountering errors with “Knit HTML” in RStudio, try: update.packages(ask=FALSE, checkBuilt=TRUE).

TODO

See issue tracker for TODO items.