Skip to content

An R package that assists with the setup and operation of a collection of soil data summary, comparison, and evaluation reports. These reports are primarily used by USDA-NRCS soil scientists in both initial and update mapping.

Notifications You must be signed in to change notification settings

ncss-tech/soilReports

Repository files navigation

R-CMD-check

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

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

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.

Related Packages

About

An R package that assists with the setup and operation of a collection of soil data summary, comparison, and evaluation reports. These reports are primarily used by USDA-NRCS soil scientists in both initial and update mapping.

Topics

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published