pywbt 0.2.3

A lightweight Python wrapper for WhiteboxTools command-line interface

PyWBT: WhiteboxTools Wrapper for Python

Features

PyWBT is a lightweight Python wrapper for the command-line interface of WhiteboxTools (WBT), a powerful Rust library for geospatial analysis. Designed to simplify the use of WhiteboxTools, PyWBT provides a Pythonic interface that enables users to easily run tools and create custom workflows. Notably, PyWBT relies solely on Python's built-in modules, ensuring a minimal dependency footprint.

Try PyWBT in your browser by clicking on the Binder badge above.

Installation

You can install PyWBT using either pip or micromamba:

Using pip:

pip install pywbt

Using micromamba (or conda/mamba):

micromamba install -c conda-forge pywbt

Usage

PyWBT offers a streamlined interface to WhiteboxTools (WBT) through a single function called whitebox_tools. This function executes user-provided WBT workflows in a temporary directory, saving only the specified output files rather than all intermediate files. It handles downloading the WBT executable for the user's operating system, setting up the environment, and running the tools.

The whitebox_tools function has several arguments, with two being mandatory and the rest optional. The two required arguments are:

1. src_dir: This will be the working directory for the WhiteboxTools session. The input files should be in this directory. Thus, when using the files in this directory in arg_dict, you must just use the filenames without the directory path.
2. arg_dict: A dictionary with tool names as keys and lists of each tool's arguments as values. Input and output filenames should be specified without directory paths.

For example workflows using arg_dict to perform geospatial operations, refer to the Workflows section of the documentation. We encourage users to contribute to this section by providing sequences of geospatial operations for performing specific tasks, helping to build a comprehensive resource for the community.

Note that by default, all generated intermediate files will be stored in save_dir (default is the current working directory). To save only the specified output files and delete the rest of intermediate files, use the files_to_save argument to specify the list of target outputs. This list should contain the filenames only specified without directory paths (as used in arg_dict).

Also, there are two helper function that can be used to get the list of available tools, their respective descriptions and parameters: list_tools and tool_parameters. For better viewing and querying the outputs of these two functions, it is recommended to use the pandas library. For example, you can use:

tools = pd.Series(pywbt.list_tools())
tools[tools.str.contains("depression", case=False)]

to get a pandas.Series of the tools containing the word "depression" in their descriptions. Then, we can get the parameters for the BreachDepressions tool using:

pd.DataFrame(pywbt.tool_parameters("BreachDepressions"))

Here's an example demonstrating how to use PyWBT to run a WBT workflow:

import pywbt
from pathlib import Path

fname = Path("path/to/input_files/dem.tif")
wbt_args = {
    "BreachDepressions": [f"-i={fname.name}", "--fill_pits", "-o=dem_corr.tif"],
    "D8Pointer": ["-i=dem_corr.tif", "-o=fdir.tif"],
    "D8FlowAccumulation": ["-i=fdir.tif", "--pntr", "-o=d8accum.tif"],
    "ExtractStreams": [
        "--flow_accum=d8accum.tif",
        "--threshold=600.0",
        "-o=streams.tif",
    ],
    "FindMainStem": ["--d8_pntr=fdir.tif", "--streams=d8accum.tif", "-o=mainstem.tif"],
    "StrahlerStreamOrder": [
        "--d8_pntr=fdir.tif",
        "--streams=streams.tif",
        "-o=strahler.tif",
    ],
    "Basins": ["--d8_pntr=fdir.tif", "-o=basins.tif"],
}
pywbt.whitebox_tools(
    fname.parent, wbt_args, ("strahler.tif", "mainstem.tif", "basins.tif")
)

For more examples, please visit PyWBT's documentation. For detailed information about the whitebox_tools function and its arguments, refer to the API Reference. Additionally, for comprehensive information on the various tools offered by WBT and their arguments, consult its documentation.

Contributing

Contributions to PyWBT are welcome! For more information on how to contribute, please refer to the CONTRIBUTING.md and CODE_OF_CONDUCT.md files.

License

PyWBT is licensed under the MIT License. For more details, please see the LICENSE file.