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.


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time



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
  • 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

# install .Rprofile

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

# list reports in the package

# install required packages for a named report

# 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

# get any new packages that may be required by the latest version

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

Suggested Background Material


  • 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).


See issue tracker for TODO items.


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.







No releases published


No packages published