Package 'SSURGOPortal'

Create Virtual Environment with SSURGO Portal Dependencies

Description

Uses 'reticulate' to create a virtual environment with the SSURGO Portal dependencies. Select the environment name, default "r-ssurgoportal", along with the specific Python and GDAL versions.

Usage

create_ssurgo_venv(
  envname = "r-ssurgoportal",
  python_version = SSURGOPORTAL_PYTHON_VERSION(),
  gdal_version = SSURGOPORTAL_GDAL_VERSION(),
  conda = FALSE,
  install_python = TRUE,
  ...
)

ssurgo_portal_python(
  envname = getOption("SSURGOPortal.virtualenv_name", default = "r-ssurgoportal"),
  conda = FALSE,
  ...
)

Arguments

envname	character. Python virtual environment name. Default: "r-ssurgoportal"
python_version	character. Semantic version number of 'Python' to install if not available. Default: '"3.10.2"
gdal_version	character. Semantic version number of 'GDAL' package to install. Default: "" for no specific version.
conda	logical. Look for Conda environment instead of virtual environment? Default: FALSE
install_python	logical. Install Python from official source using pyenv? Default: TRUE. Used for virtual environment installs when the system python does not match requested version, or usable Python is not otherwise detectable.
...	Additional arguments used only when conda=TRUE

Value

character. Path to virtual environment Python binary (invisible).

---

Get SSURGO ZIP files from Web Soil Survey 'Download Soils Data'

Description

Download ZIP files containing spatial (ESRI shapefile) and tabular (TXT) files with standard SSURGO format; optionally including the corresponding SSURGO Template Database with include_template=TRUE.

Usage

download_ssurgo(
  WHERE = NULL,
  areasymbols = NULL,
  destdir = tempdir(),
  exdir = destdir,
  include_template = FALSE,
  extract = TRUE,
  remove_zip = FALSE,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

WHERE	A SQL WHERE clause expression used to filter records in sacatalog table. Alternately WHERE can be any spatial object supported by SDA_spatialQuery() for defining the target extent.
areasymbols	Character vector of soil survey area symbols e.g. c("CA067", "CA077"). Used in lieu of WHERE argument.
destdir	Directory to download ZIP files into. Default tempdir().
exdir	Directory to extract ZIP archives into. May be a directory that does not yet exist. Each ZIP file will extract to a folder labeled with areasymbol in this directory. Default: destdir
include_template	Include the (possibly state-specific) MS Access template database? Default: FALSE
extract	Logical. Extract ZIP files to exdir? Default: TRUE
remove_zip	Logical. Remove ZIP files after extracting? Default: FALSE
overwrite	Logical. Overwrite by re-extracting if directory already exists? Default: FALSE
quiet	Logical. Passed to curl::curl_download().

Details

To specify the Soil Survey Areas you would like to obtain data you use a WHERE clause for query of sacatalog table such as areasymbol = 'CA067', "areasymbol IN ('CA628', 'CA067')" or ⁠areasymbol LIKE 'CT%'⁠.

Pipe-delimited TXT files are found in /tabular/ folder extracted from a SSURGO ZIP. The files are named for tables in the SSURGO schema. There is no header / the files do not have column names. See the Soil Data Access Tables and Columns Report: https://sdmdataaccess.nrcs.usda.gov/documents/TablesAndColumnsReport.pdf for details on tables, column names and metadata including the default sequence of columns used in TXT files. The function returns a try-error if the WHERE/areasymbols arguments result in

Several ESRI shapefiles are found in the /spatial/ folder extracted from a SSURGO ZIP. These have prefix soilmu_ (mapunit), soilsa_ (survey area), soilsf_ (special features). There will also be a TXT file with prefix soilsf_ describing any special features. Shapefile names then have an a_ (polygon), l_ (line), p_ (point) followed by the soil survey area symbol.

Value

Character. Paths to downloaded ZIP files (invisibly). May not exist if remove_zip=TRUE.

---

Download SSURGO Portal .PYZ file from Web Soil Survey

Description

This routine downloads the latest .pyz file from Web Soil Survey

Usage

install_ssurgo_portal(
  verbose = TRUE,
  overwrite = FALSE,
  timeout = 3000,
  src =
    "https://websoilsurvey.sc.egov.usda.gov/DSD/Download/SsurgoPortal/SSURGO_Portal.zip",
  envname = "r-ssurgoportal",
  python_version = SSURGOPORTAL_PYTHON_VERSION(),
  gdal_version = SSURGOPORTAL_GDAL_VERSION(),
  ...
)

Arguments

verbose	Show download progress and location of file on successful download? Default TRUE
overwrite	Overwrite existing .PYZ file? Default: FALSE
timeout	Default: 3000 seconds. Temporarily overrides options() for timeout.
src	Default: "https://websoilsurvey.sc.egov.usda.gov/DSD/Download/SsurgoPortal/SSURGO_Portal.zip"
envname	Virtual environment to create for installation. Default: "r-ssurgoportal". Use "" for no virtual environment modifications.
python_version	character. Semantic version number of 'Python' to install if not available. Default: "3.10.2"
gdal_version	character. Semantic version number of 'GDAL' package to install. Default: ""
...	Additional arguments to create_ssurgo_venv() when venv=TRUE.

Value

Path to downloaded file, or try-error on error.

Examples

## Not run: 
 install_ssurgo_portal()

## End(Not run)

---

Generate Requests for 'SSURGO Portal' Data Loader

Description

Generate commands for the 'SSURGO Portal' Data Loader command-line interface, and parse resulting JSON output.

Usage

ssurgo_portal(
  request = NULL,
  pyz_path = file.path(ssurgo_portal_dir("data"), "SSURGOPortal.pyz"),
  ...,
  schema = FALSE,
  command_only = FALSE
)

Arguments

request	One of the available request types, see Details.
pyz_path	Path to "SSURGO Portal" .pyz file. Default "SSURGOPortal.pyz" in ssurgo_portal_dir("data") directory.
...	Additional parameters for request
schema	Return request and response schemas? Default: FALSE
command_only	Return command string rather than executing it? Default: FALSE

Details

Request Name	Description
getstatus	Quick check for application responsiveness
getusage	Return usage information in payload.
getwindowsdriveletters	Return all drive letters (only valid for Microsoft Windows)
getfoldertree	Returns a file system tree.
gettemplatecatalog	Returns JSON containing information about all available empty SSURGO SQLite templates.
copytemplatefile	Copies a template file to a specified folder path and name.
opentemplate	Opens a SQLite file to confirm that it meets certain minimal criteria.
getdatabaseinventory	List survey areas and related data within a SQLite database.
deleteareasymbols	Delete the specified areasymbols from the database.
pretestimportcandidates	Perform a 'pre-test' on subfolders under a root folder.
importcandidates	Import SSURGO data from subfolders under a root folder. The import terminates if any folder fails.
importspatialdata	For internal use only. Import SSURGO spatial data from shapefiles under a specified path. Note that this activity is isolated to support its use in a child process.
getrecordlistbytable	Retrieve table rows for a specified table
generaterasters	Generate rasters of the mupolygon dataset in the user specified SSURGO Template Database.
logjavascripterror	Write an error to the log file
getsdvattributesbyfolder	Get Soil Data Viewer attributes
getsdvratingoptions	Get Soil Data Viewer rating options
generateaggregation	Generate an aggregation
sortratingtable	Sort a rating table by a specified column name
exportratingresults	Export rating results

Value

A list object corresponding to the JSON response. NULL (invisibly) on error along with any other standard output from the tool printed to the console.

Examples

## Not run: 
ssurgo_portal("getstatus")

ssurgo_portal("getstatus", schema = TRUE)

ssurgo_portal(
  "getfoldertree",
  path = "C:/SSURGO Portal/WV",
  folderpattern = "WV",
  filepattern = "txt",
  ignorefoldercase = TRUE,
  ignorefilecase = TRUE,
  showfiles = FALSE,
  maxdepth = 2
)

ssurgo_portal("gettemplatecatalog")

ssurgo_portal(
  "copytemplate",
  templatename = "GeoPackage",
  folder = "test",
  filename = "test.gpkg",
  overwrite = TRUE
)

dbp <- "C:/SSURGO Portal/Databases/West_Virginia_Geopackage.gpkg"

ssurgo_portal("opentemplate", database = dbp)

ssurgo_portal(
  "pretestimportcandidates",
  database = dbp,
  root = "C:/SSURGO Portal/WV",
  istabularonly = FALSE
)

ssurgo_portal(
  "importcandidates",
  database = dbp,
  root = "C:/SSURGO Portal/WV",
  istabularonly = FALSE,
  skippretest = TRUE,
  subfolders = list("WV603"),
  loadinspatialorder = FALSE,
  loadspatialdatawithinsubprocess = TRUE,
  dissolvemupolygon = TRUE
)

ssurgo_portal("getdatabaseinventory", database = dbp)

ssurgo_portal("deleteareasymbols",
              database = dbp,
              areasymbols = list("WV603"))

## End(Not run)

---

SSURGO Portal User Directories

Description

These are standard locations for storing data, config, and cache information for SSURGO Portal outside of the installation in the R package library.

Usage

ssurgo_portal_dir(which = "data")

Arguments

which

One or more of: "data", "config", "cache"

Value

character. Path to data, config or cache directories, respectively.

Examples

ssurgo_portal_dir("data")
ssurgo_portal_dir("config")
ssurgo_portal_dir("cache")

---

SSURGOPortal Environment Variables

Description

SSURGOPORTAL_PYTHON_VERSION(): returns value of system environment variable R_SSURGOPORTAL_PYTHON_VERSION or option SSURGOPortal.python_version. If neither are set then returns "3.10", the suggested Python version.

Usage

SSURGOPORTAL_PYTHON_VERSION()

SSURGOPORTAL_GDAL_VERSION()

Value

character. Version number for Python or GDAL to be used when building Python environment.

---