Overview

Introducing {soils}: an R package for all your soil health data visualization and reporting needs. {soils} provides an RStudio project template to generate customized, interactive soil health reports. These reports include plots and tables to show how the participant’s results compare to simple averages of results from samples of the same crop, same county, and across the entire project.

Any scientist leading a soil health survey can use {soils} to create custom reports for all survey participants. Democratize your data by giving back to the farmers and land managers who contributed soil samples to your survey project. Use these reports to empower each participant to explore and better understand their data.

The Washington State Department of Agriculture and Washington State University developed {soils} as part of the Washington Soil Health Initiative. Learn more about {soils} in this blog post or this webinar.

Requirements

The report template uses Quarto, which is the next-generation version of R Markdown.

We assume you’re using RStudio v2022.07 or later for editing and previewing Quarto documents. We strongly recommend you use the latest release of RStudio for support of all Quarto features. You can also download and install the latest version of Quarto independently from RStudio.

To render Microsoft Word (MS Word) documents, you must have MS Word installed and activated.

If you’re new to Quarto and Markdown formatting syntax, first take a look at the Primers on Quarto and Markdown to learn how they’re used in {soils} and get familiar with their features.

Installation

Install the development version of {soils} from our r-universe with:

install.packages(
  "soils",
  repos = c("https://wa-department-of-agriculture.r-universe.dev")
)

Or install from GitHub with {pak}:

# Uncomment the below line if {pak} is not installed.
# install.packages("pak")
pak::pkg_install("WA-Department-of-Agriculture/soils")

Load the example datasets and functions with:

library(soils)

Usage

{soils} was developed to work ‘out of the box’ so you can immediately install and render an example report. However, you will need to customize and edit content to fit your project.

Our recommended workflow is to 1) create a new {soils} project, 2) try to render the example reports to make sure everything works on your system, and 3) customize the template files to use your own data, content, and styling.

We provide a series of Primers and Tutorials to prepare and guide you through this workflow. See below for short demo videos and links to the relevant tutorials.

1. Create a new {soils} project

Follow along in the Create a {soils} project tutorial. Choose between two report templates: English or Spanish.

2. Render the example reports

Follow along in the Render the example reports tutorial.

See the rendered example reports.

HTML

MS Word

3. Create reports with your own data

To use your own data, customize the reports for your project, and render all reports, follow along with these tutorials:

Troubleshooting

As you edit the content, errors are bound to occur. Read tips and workflows for troubleshooting

Acknowledgement and citation

The below acknowledgement is automatically embedded in each report:

This report was generated using the {soils} R package. {soils} was developed by the Washington State Department of Agriculture and Washington State University, as part of the Washington Soil Health Initiative. Text and figures were adapted from WSU Extension publication #FS378E Soil Health in Washington Vineyards. Learn more about {soils} in this blog post or this webinar.

citation <- citation("soils")

header <- format(citation, style = "citation")[[1]]
text <- format(citation, style = "textVersion")

cat(header)

To cite {soils} in publications, please use:

cat(">", text)

Ryan JN, McIlquham M, Sarpong KA, Michel LM, Potter TS, Griffin LaHue D, Gelardi DL. 2024. Visualize and Report Soil Health Survey Data with {soils}. Washington Soil Health Initiative. https://github.com/WA-Department-of-Agriculture/soils

Credits

{soils} adapts from existing R project templating resources and packages:

Text and figures were adapted from WSU Extension publication #FS378E Soil Health in Washington Vineyards.

Report text and images were translated by Erica Tello, Eber Rivera, and Kate Smith with WSU Food Systems and Skagit County Extension as part of the USDA NRCS Innovation in Conservation program, led by Viva Farms (grant number NR22-13G004).