---
title: "whitebox Tool Metadata"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{whitebox Tool Metadata}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 6,
  fig.height = 6 
)
```

```{r setup, include=FALSE}
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.

```{r}
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"

```{r}
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:

 1. `PascalCase` tool names change to `snake_case`
 
 2. 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. 

```{r}
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

```{r}
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.

```{r}
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()`.

```{r}
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.

```{r, echo=FALSE, results='asis'}
# 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
    ))
  })
}
```