SSURGOPortal

The goal of SSURGOPortal is to provide a simple R interface to the ‘SSURGO Portal’ Python tools. Providing an R wrapper around the SSURGO Portal API allows users to automate many of the operations they might normally achieve through the graphical user interface.

Installation

You can install the development version of {SSURGOPortal} like so:

remotes::install_github("brownag/SSURGOPortalR")

Example

This example shows how to install the .PYZ file and run from a standard location.

If you are using a machine that cannot utilize custom virtual or Conda environments you must use the system interpreter. By default, to conform with best practices and to minimize unintended disturbances to the system python installation, SSURGOPortal will install and run the tool from a custom virtual environment. The default name of this environment is "r-ssurgoportal". To avoid the default virtual environment, before loading the package, set the environment variable "R_SSURGOPORTAL_USE_VIRTUALENV" to FALSE. You may opt to put this setting into a user or project-level .Renviron file, or in your user environment variables.

Sys.setenv(R_SSURGOPORTAL_USE_VIRTUALENV = FALSE)

You may also need to set your default Python interpreter if running the tool through RStudio. See Tools >> Global Options… >> Python. If using the system interpreter, you likely want to uncheck the box “Automatically use project-local Python environments”.

First load the R package:

library(SSURGOPortal)
#> SSURGOPortal R Interface v0.0.4
#>  Python: C:/Program Files/Python312/python.exe
#>  SSURGO Portal: C:/Users/Andrew.G.Brown/AppData/Roaming/R/data/R/SSURGOPortal/SSURGOPortal.pyz

You should see a message that indicates the Python binary that will be used for sending commands to SSURGOPortal.

If you have not installed an instance of SSURGOPortal, you will see that the PYZ file is “not found”. To install, use the R function install_ssurgo_portal()

install_ssurgo_portal()

This function has several additional/optional arguments that allow you to customize the target virtual environment name, Python version and GDAL version to use with the installation.

The above installation routine places the SSURGO Portal file in a platform-specific folder: ssurgo_portal_dir("data")

To verify everything is set up and working, we can send the "getstatus" command, like so:

ssurgo_portal("getstatus")
#> $status
#> [1] TRUE
#> 
#> $message
#> [1] "It\"s alive! runmode=RunMode.DATA_LOADER, isPyz=True, __file__=C:\\Users\\Andrew.G.Brown\\AppData\\Roaming\\R\\data\\R\\SSURGOPortal\\SSURGOPortal.pyz\\dlcore\\dlutilities.py, currentPath=C:\\Users\\Andrew.G.Brown\\AppData\\Roaming\\R\\data\\R\\SSURGOPortal"
#> 
#> $elapsedseconds
#> [1] 0

See the documentation for ssurgo_portal() (?ssurgo_portal) for other available commands and more examples.

In general, a command is structured as JSON with a specific request name and various other parameters. This JSON string is passed via the terminal to the .pyz file and Python interpreter.

We can inspect the commands that are generated using command_only=TRUE

For example, here is a sample "copytemplate" request to create a new GeoPackage database called "test.gpkg" from a template:

ssurgo_portal("copytemplate", 
              templatename = "GeoPackage", 
              folder = "sample_gpkg", 
              filename = "test", 
              overwrite = TRUE, 
              command_only = TRUE)
#> [1] "cmd /c echo {\"request\":\"copytemplatefile\",\"templatename\":\"GeoPackage\",\"folder\":\"sample_gpkg\",\"filename\":\"test\",\"overwrite\":true} | \"C:\\PROGRA~1\\PYTHON~1\\python.exe\" \"C:\\Users\\Andrew.G.Brown\\AppData\\Roaming/R/data/R/SSURGOPortal/SSURGOPortal.pyz\" @"

Now after inspecting the command, we can actually run it:

ssurgo_portal("copytemplate", 
              templatename = "GeoPackage", 
              folder = "sample_gpkg", 
              filename = "test", 
              overwrite = TRUE)
#> $status
#> [1] TRUE
#> 
#> $message
#> [1] "Copied templates/geopackage.gpkg to sample_gpkg\\test.gpkg"
#> 
#> $elapsedseconds
#> [1] 0

Download and Import Data

Using the {soilDB} package SSURGO data for input into template databases can easily be downloaded. For example here we specify a generic WHERE clause used against the sacatalog table in Soil Data Access.

td <- file.path(tempdir(), "ssurgo_test")

download_ssurgo("areasymbol LIKE 'RI%'", exdir = td)

In this instance the wildcard only returns a single survey, "RI600", but this pattern could be used in other areas to download multiple surveys within a state (without explicitly knowing their areasymbol).

After downloading and extracting soil survey area data to a temporary directory, we can “pretest” them as candidates for import into the template.

ssurgo_portal(
  "pretestimportcandidates",
  database = "sample_gpkg/test.gpkg",
  root = td,
  istabularonly = FALSE
)

If everything looks good, we can go ahead with the import. For this we use the "importcandidates" request.

ssurgo_portal(
  "importcandidates",
  database = "sample_gpkg/test.gpkg",
  root = td,
  istabularonly = FALSE,
  skippretest = TRUE,
  subfolders = c("RI600"),
  loadinspatialorder = FALSE,
  loadspatialdatawithinsubprocess = FALSE,
  dissolvemupolygon = FALSE
)

Python Versions Supported

There are built in routines and binaries for running the tool on Windows with Python 3.9 or 3.10. If using a different version of Python you will need to be sure the required modules are installed prior to running ssurgo_portal(). The tools have all been tested and verified to work with Python 3.12.

Python Dependencies

To prepare your Python system or virtual environment, run python -m pip install bottle gdal jsonschema (or similar) to make sure that the required modules are already installed before invoking the SSURGO Portal tools.

Cross-platform Support

This package applies patches to attempt to make the .PYZ contents minimally compatible with Linux and macOS. This feature is experimental and intended to provide feedback for future development. If these patches are not included the initialization routine will be triggered on non-Windows platforms.

This routineonly installs the bundled Windows wheel (.whl) files; it should be expected to fail on all other platforms and Python versions other than 3.9 and 3.10.

If you encounter other problems on non-Windows platforms, file an issue in the issue tracker.