https://github.com/brownag/ssurgoportalr
Download and Interact with the 'SSURGO Portal' Tools for Building and Editing U.S. Soil Survey Databases
https://github.com/brownag/ssurgoportalr
Last synced: 2 months ago
JSON representation
Download and Interact with the 'SSURGO Portal' Tools for Building and Editing U.S. Soil Survey Databases
- Host: GitHub
- URL: https://github.com/brownag/ssurgoportalr
- Owner: brownag
- License: cc0-1.0
- Created: 2023-03-19T15:48:40.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-12-19T21:09:00.000Z (5 months ago)
- Last Synced: 2025-03-01T00:19:24.790Z (3 months ago)
- Language: R
- Homepage: http://humus.rocks/SSURGOPortalR/
- Size: 5.28 MB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.Rmd
- Changelog: NEWS.md
- License: LICENSE.md
Awesome Lists containing this project
README
---
output: github_document
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# SSURGOPortal
[](https://github.com/brownag/SSURGOPortalR/actions/workflows/R-CMD-check.yml)
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:
``` r
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.
```{r envvar, eval=FALSE}
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:
```{r libr, eval=TRUE}
library(SSURGOPortal)
```
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()`
```{r install, eval=FALSE}
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:
```{r}
ssurgo_portal("getstatus")
```
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:
```{r}
ssurgo_portal("copytemplate",
templatename = "GeoPackage",
folder = "sample_gpkg",
filename = "test",
overwrite = TRUE,
command_only = TRUE)
```
Now after inspecting the command, we can actually run it:
```{r}
ssurgo_portal("copytemplate",
templatename = "GeoPackage",
folder = "sample_gpkg",
filename = "test",
overwrite = TRUE)
```
## 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.
```{r, eval = FALSE}
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.
```{r, eval = FALSE}
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.
```{r, eval = FALSE}
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](https://github.com/brownag/SSSURGOPortalR/issues).