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.
You can install the development version of {SSURGOPortal} like so:
remotes::install_github("brownag/SSURGOPortalR")
This is example shows how to install the .PYZ file to a standard location:
library(SSURGOPortal)
install_ssurgo_portal()
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
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
)
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()
.
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.
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 routine only 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.