Basic Usage¶

This page describes how to run a basic hazard assessment using wildcat.

Running commands¶

After installing wildcat, you can run wildcat commands from the command line (CLI) or from within a Python session. For example:

CLI

wildcat assess <args>

Python

from wildcat import assess
assess(...)

There are four main commands in wildcat:

Command	Description
initialize	Creates a project folder for an assessment
preprocess	Reprojects and cleans input datasets
assess	Conducts a hazard assessment using preprocessed datasets
export	Export asssessment results to GIS formats (such as Shapefiles and GeoJSON)

You can learn more about each command by following the links in the table, but we recommend reading this page first for a general introduction.

Getting Started¶

Most users will start by using the initialize command to initialize a project folder for an assessment. The command requires the path to a project folder as input. When run, wildcat initialize will create the indicated folder and add a default configuration file. It will also create an empty inputs subfolder, which you can use to store input datasets for the assessment.

For example, running:

CLI

wildcat initialize my-project

Python

from wildcat import initialize
initialize(project="my-project")

will create the following file tree in the current folder:

my-project
├── configuration.py
└── inputs

The configuration.py file holds the settings that will be used to run wildcat commands for the assessment. When you initialize a project, the config settings will all be set to the wildcat defaults, which will implement a USGS-style hazard assessment. This should be sufficient for many users, but you can also edit configuration.py to change these settings. You can learn more about the configuration file and its settings in the configuration section.

Tip

The default config file will only hold the most commonly edited fields. To initialize a config file with every possible setting, use:

wildcat initialize project --config full

Input Datasets¶

Next, we’ll want to add various input dataset files to the project. Most assessments will need at least the following datasets:

Dataset	Description
`perimeter`	A fire perimeter mask. The mask will be buffered, and the extent of the buffered perimeter will define the domain of the analysis. Pixels in the perimeter may used used to delineate the stream segment network, and segments sufficiently within the perimeter are retained during network filtering. Usually a Polygon or MultiPolygon feature file, but may also be a raster mask.
`dem`	Digital elevation model (DEM) raster. Used by the preprocessor to set the CRS, resolution, and alignment of the preprocessed rasters. Used by the assessment to characterize the watershed (including flow directions). Should have approximately 10 meter resolution.
`dnbr`	Differenced normalized burn ratios (dNBRs). Used to estimate debris-flow likelihoods and rainfall thresholds. Optionally used to estimate burn severity. Should be (raw dNBR * 1000) with values ranging from approximately -1000 to 1000. Usually a raster, but also supports using a constant value throughout the watershed.
`severity`	BARC4-like burn severity. Used to locate burned areas, which are used to delineate the stream segment network. Also used to locate areas burned at moderate-or-high severity, which are used to estimate debris flow likelihoods, volumes, and rainfall thresholds. If missing, estimated from the dNBR dataset. Usually a raster, but may also be a Polygon or MultiPolygon feature file. Also supports using a constant value throughout the watershed.
`kf`	Soil KF-factors. Used to estimate likelihoods and rainfall thresholds. Values should be positive, and the preprocessor will convert non-positive values to NoData by default. Often a Polygon or MultiPolygon feature file, but may also be a numeric raster. Also supports using a constant value throughout the watershed.
`evt`	Existing vegetation type raster. Although not required for an assessment, the EVT is used to build water, development, and exclusion masks, which can improve the design of the stream segment network. Usually a raster of classification code integers.

And wildcat also supports the following optional datasets:

Dataset	Description
`retainments`	Locations of debris retainment features. Pixels downstream of these features are not used for network delineation. Usually a Point or MultiPoint feature file, but may also be a raster mask.
`excluded`	Mask of areas that should be excluded from network delineation. Pixels in these areas will not be used to delineate the network. Often a Polygon or MultiPolygon feature file, but may also be a raster mask.
`included`	Mask of areas that should be retained during network filtering. Any stream segments that intersect the mask will be retained in the network. Often a Polygon or MultiPolygon feature file, but may also be a raster mask.
`iswater`	Pre-computed water body mask. Areas within the mask will be excluded from network delineation. Often a Polygon or MultiPolygon feature file, but may also be a raster mask.
`isdeveloped`	Pre-defined human development mask. Used to inform network filtering. Often a Polygon or MultiPolygon feature file, but may also be a raster mask.
`kf_fill`	Spatially varying KF-factor fill values. Missing KF-factor values will be replaced with the co-located fill value. Often a Polygon or MultiPolygon feature file, but may also be a numeric raster.

You can follow the links in the tables to learn more about using each dataset, but we recommend reading this page first for an general introduction.

Constant valued datasets¶

The kf, dnbr, and severity datasets all support using a constant value throughout the watershed. This can be useful when a spatially complete dataset is not available. You can implement a constant value by setting a dataset equal to a number, rather than a file path.

Add Data to Project¶

Once you have collected the dataset files, you should update configuration.py with the paths to these files. If a data file is in the inputs subfolder, then you only need to provide the file name. If a data file is elsewhere on your machine, then you should provide the absolute file path. The latter is useful when you have large data files that you don’t want to copy or move into the project folder.

For example, say we’ve collected the 6 standard datasets in the above table. Four of our datasets are small, so we place them in the inputs folder, but two of the datasets (EVT and KF-factors) are large, so we keep them on an external drive. Our file tree resembles the following:

.
├── my-project
|   ├── configuration.py
|   └── inputs
|       ├── my-perimeter.shp
|       ├── my-dnbr.tif
|       ├── my-severity.tif
|       └── my-dem-tile.tif
└── external-drive
    └── large-files
        ├── EVT-CONUS.tif
        └── soil-data.shp

We should now update the indicated sections of configuration.py as follows:

# Required Datasets
perimeter = r"my-perimeter.shp"
dem = r"my-dem-tile.tif"

# Recommended Datasets
dnbr = r"my-dnbr.tif"
severity = r"my-severity.tif"
kf = r"/external-drive/large-files/soil-data.shp"
evt = r"/external-drive/large-files/EVT-CONUS.shp"

Note that we used absolute paths for the files on the external drive.

What’s with the r?

The r character at the start of the file paths stops Python from interpreting \ characters (used as folder separators on Windows) as escape sequences. This ensures that the config file behaves the same across different operating systems.

Finalize Configuration¶

We can now make any additional changes to configuration.py that we deem necessary. Continuing the example, the KF-factor dataset soil-data.shp appears to be a Polygon shapefile, so we will need to use the kf_field config setting to indicate the data attribute field that holds the KF-factor data:

# In configuration.py
kf_field = "KFFACT"

You can find a guide to all available config settings in the config file API.

Preprocess¶

We’re now ready to run the other wildcat commands. We’ll start by using the preprocess command to clean and reproject the input datasets:

CLI

wildcat preprocess my-project

Python

from wildcat import preprocess
preprocess("my-project")

This will create a preprocessed subfolder within our project. This subfolder contains the preprocessed rasters ready for the assessment and also a record of the config settings used to run the preprocessor. The preprocessed folder can be of interest for archival purposes, as it contains the minimum dataset needed to reproduce a hazard assessment.

Continuing the example, our file tree is now:

my-project
├── configuration.py
├── inputs
|   └── ...
└── preprocessed
    ├── perimeter.tif
    ├── dem.tif
    ├── dnbr.tif
    ├── severity.tif
    ├── kf.tif
    ├── evt.tif
    ├── iswater.tif
    ├── isdeveloped.tif
    └── configuration.txt

where configuration.txt is the config record for the preprocessor. Most wildcat commands will create similarly named config records. As a rule, you can use the record to exactly reproduce a command’s outputs by copying the record into a configuration.py file and rerunning the command.

Tip

If you add a dataset to a project after running the preprocessor, then you will need to rerun the preprocessor to include the new dataset in the assessment. This most commonly occurs when adding an excluded area mask to a project.

Assess¶

We’re now ready to run an assessment using the assess command:

CLI

wildcat assess my-project

Python

from wildcat import assess
assess("my-project")

This will characterize the watershed, design a stream segment network, and estimate debris-flow likelihoods, volumes, hazards, and rainfall thresholds. The command will create an assessment subfolder in our project, which contains the assessment results. Specifically, these are:

File	Description
`segments.geojson`	Results for the stream segments as LineString features
`outlets.geojson`	Results for the drainage outlets as Point features
`basins.geojson`	Results for the outlet catchment basins as Polygon features
`configuration.txt`	Record of the config settings used to run the assessment

Our file tree is now:

my-project
├── configuration.py
├── inputs
|   └── ...
├── preprocessed
|   └── ...
└── assessment
    ├── segments.geojson
    ├── outlets.geojson
    ├── basins.geojson
    └── configuration.txt

If you are comfortable working with GeoJSON, then you may use these results directly, and the saved data fields are documented in the assessment properties section. However, most users prefer to use the export command instead. This command can export results to other GIS formats, and also includes options to help format the output data fields.

Warning

You should treat these output files as read-only. Altering their contents can cause other wildcat commands to fail unexpectedly.

Export¶

Our final step is to run the export command:

CLI

wildcat export my-project

Python

from wildcat import export
export("my-project")

This will created an exports subfolder in our project with exported results and the usual config record. By default, the command will export results to Shapefile, but you can also export to many other GIS formats. The command also includes a variety of options to help format exported data fields, which you can learn about on the next page.

Our final file tree will be:

my-project
├── configuration.py
├── inputs
|   └── ...
├── preprocessed
|   └── ...
├── assessment
|   └── ...
└── exports
    ├── segments.shp
    ├── outlets.shp
    ├── basins.shp
    └── configuration.txt

Note

The exports folder will also include the .cpg, .dbf, .prj, and .shx files associated with each Shapefile, but we have omitted them here for brevity.