whitebox Tool Metadata
In whitebox: 'WhiteboxTools' R Frontend

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 6,
  fig.height = 6 
)

knitr::opts_chunk$set(echo = TRUE)

# R package dataset symbol names
wbttools <- NULL
wbttoolparameters <- NULL

data("wbttools", package = "whitebox")

`whitebox` Tool Metadata

This vignette provides an introduction to the data sets included in the whitebox package. These data sets contain names, arguments and other metadata for tools available in WhiteboxTools.

What version of WhiteboxTools are these data sets generated from?

Current version: r attr(wbttools, "version")

Internal data sets and functions defined in the R package correspond to tool names available in the most recent version of WhiteboxTools. Data sets are not dynamically generated from your WhiteboxTools installation. Relatively recent versions of WhiteboxTools should be supported backward-compatibly, though any newer functionality will not be usable.

WhiteboxTools Tool Names and R Function Names

The first data set describes tool names in WhiteboxTools and the corresponding exported function in the R package, along with the WhiteboxTools Toolbox name and a brief description.

data("wbttools", package = "whitebox")

str(wbttools)

The wbttools data set is a data.frame with r nrow(wbttools) tools and 7 variables

"tool_name" - WhiteboxTools tool name
"function_name" - R function tool name
"toolbox_name" - WhiteboxTools toolbox name
"label" - WhiteboxTools tool label
"description" - Brief description
"github" - GitHub link
"book" - Reference manual link
"is_extension" - Tool is part of General Toolset Extension (GTE), as opposed to the "open core"

head(wbttools)

The R function naming style differs from the tool names in WhiteboxTools, but the core words are the same.

R function names are derived from the WhiteboxTools name as follows:

PascalCase tool names change to snake_case
All R function names get the prefix wbt_

For example, StreamSlopeContinuous in WhiteboxTools becomes wbt_stream_slope_continuous() in R.

WhiteboxTools Tool and Parameter Names

The second data set provides details about the available function arguments by tool name.

data("wbttoolparameters", package = "whitebox")

The wbttoolparameters data set is a data.frame with r nrow(wbttoolparameters) parameters and r ncol(wbttoolparameters) variables:

"tool_name" - WhiteboxTools tool name
"function_name" - R function name
"toolbox_name" - WhiteboxTools toolbox name
"name" - WhiteboxTools tool parameter name
"flags" - flags used to specify parameter on command line; comma-separated
"description" - parameter description
"default_value" - parameter default value, if any
"optional" - parameter "optional" flag; note that some combination of optional parameters may be required for certain conditions
"parameter_class" - parameter type
"parameter_detail" - parameter details; character: data type followed by colon and more specifics, For OptionList possible values, comma-separated (if defined)
"is_input" - logical. Classification of 'input' parameters
"is_output" - logical. Classification of 'output' parameters
"argument_name" - labels for selected subset of "flags" used as R function argument names for wbt_ functions

head(wbttoolparameters)

Several fields in this table such as flags and parameter_type are "flattened" relative to the nested wbt_tool_parameters() output.

The nested parameter_type from the JSON result is replaced with two variables in the data set: parameter_class and parameter_details

This parameter data.frame is useful to construct your own functions with wbt_run_tool() or for inspecting the types of tools that can be run on particular data types.

str(wbttoolparameters, max.level = 1)

You will find that both tool_name and function_name are present, so you can look up by whatever is convenient.

The variable argument_name is processed to be the subset of flags that corresponds to arguments to R functions, which are denoted with function_name.

Example: Finding Tools by Parameter Type

To find the tools that have an "ExistingFile" argument with file type "Raster" we can use subset().

head(subset(wbttoolparameters, grepl("ExistingFile", parameter_class) & grepl("Raster", parameter_detail)))

Appendix: Tables of Function Names by Toolbox

The remainder of this vignette is tables of R function names and tool descriptions from wbttoolparameters, organized by WhiteboxTools toolbox/extension name.

# hide this, we add the parentheses for the docs
wbttoolsshow <- wbttools
wbttoolsshow$function_name <- paste0("`", wbttoolsshow$function_name, "()`")
wbttoolssplt <- split(wbttoolsshow[,colnames(wbttoolsshow) %in% c("function_name", "description")],
                      list(wbttoolsshow$toolbox_name))

if (requireNamespace("knitr")) {
  x <- sapply(names(wbttoolssplt), function(nm) {
    cat("###", nm, "\n\n")
    print(knitr::kable(
      wbttoolssplt[[nm]],
      caption = paste("Toolbox:", nm),
      col.names = c("Function Name",  "Description"),
      row.names = FALSE
    ))
  })
}