3.2.7. spatial module

This module implements the ws3.spatial.ForestRaster` class, which can be used to allocate an aspatial disturbance schedule (for example, an optimal solution to a wood supply problem generated by an instance of the ws3.forest.ForestModel class) to a rasterized representation of the forest inventory.

class spatial.ForestRaster(hdt_map, hdt_func, src_path, snk_path, acode_map, forestmodel, base_year, horizon=None, period_length=10, tif_compress='lzw', tif_dtype=<MagicMock id='126733653471728'>, piggyback_acodes=None, time_step=1, disturb_thresh=10)[source]

Bases: object

The ws3.spatial.ForestRaster class can be used to allocate an aspatial disturbance schedule (for example, an optimal solution to a wood supply problem generated by an instance of the ws3.forest.ForestModel class) to a rasterized representation of the forest inventory.

Parameters:

  • hdt_map (dict) – A dictionary mapping hash values to development types. The rasterized forest inventory is stored in a 3-layer GeoTIFF file. Pixel values for layer 1 represent the theme values (i.e., the stratification variables used to stratify the forest inventory into development types). The value of the hdt_map parameter is used to expand hash value back into a tuple of theme values. Pixel values for layer 2 represent age (time unit may vary depending on how the model was compiled). Pixel values for layer 3 represent block ID code (the notion of what constitutes a block, and how ID codes are assigned, is entirely up to the user when compiling the rasterized inventory).

  • hdt_func (function) – A function that accepts a tuple of theme values, and returns a hash value. Must be the same function used to encode the rasterized forest inventory (see documentation of the hdt_map parameter, above).

  • src_path (str) – Filesystem path pointing to the input GeoTIFF file (i.e., the rasterized forest inventory). Note that this file will be used as a model for the output GeoTIFF files (i.e., pixel matrix height and width, coordinate reference system, compression parameters, etc.).

  • snk_path (str) – Filesystem path pointing to a directory where the output GeoTIFF files. The output GeoTIFF files are automatically created inside the class constructor method (one GeoTIFF file for each combination of disturbance type and year.

  • acode_map (dict) – Dict keyed on disturbance codes, returning string prefix to use for GeoTIFF output filenames.

  • forestmodel (int) – An instance of the ForestModel class.

  • horizon (int or None) – Length of planning horizon (expressed as a number of periods). If None, defaults to forestmodel.horizon.

  • base_year (int) – Base year for numbering of annual time steps (affects GeoTIFF output filenames).

  • tiff_compress (str) – GeoTIFF output file compression mode (uses LZW lossless compression by default).

  • tif_dtype (rasterio.dtype) – Data type for output GeoTIFF files (defaults to rasterio.uint8, i.e., an 8-byte unsigned integer).

  • piggyback_acodes (dict(str, list)) – A dictionary of list of tuples, describing piggyback disturbance parameters. By piggyback disturbance, we mean a disturbance that was not explicitly scheduled by the ForestModel instance, but rather is modelled as a (randomly-selected) subset of one of the explicitly modelled disturbances.

For example, if we want to model that 85% of pixels disturbed using the clearcut disturbance are disturbed by a piggybacked slashburn disturbance, we would pass a value of {'clearcut':[('slashburn', 0.85)]} for the piggyback_acodes parameter.

allocate_schedule(mask=None, verbose=False, commit=True, sda_mode='randblk', da=0, ovrflwthr=0, fudge=1.0, nthresh=0, minage=1, aggregate_disturbance=False)[source]

Allocates the current disturbance schedule from the :py:class:~`.forest.ForestModel` instance passed via the forestmodel parameter. This is the core method of the ForestRaster class. This method should only be called once. Calls the commit() method by default, which closes the open file handles for the output GeoTIFF files (else the files are locked until the instance is destroyed).

The ForestRaster class defines both __enter__ and __exit__ methods, so instance scope and lifetime can easily be managed using a with block. This will automatically closes all open file handles, thereby avoid hard-to-debug problems downstream (highly recommended). For example

with ForestRaster(**kwargs) as fr:
    fr.allocate_schedule()

This method allocates the aspatial disturbance schedule (simulated in the ForestModel instance passed to the ForestRaster instance constructor) to a spatial raster grid. The raster grid specifications are copied from the input GeoTIFF file (containing initial forest inventory data), such that the output GeoTIFF files can be exactly overlaid onto the raster inventory layers. The ForestModel simulates disturbances using time steps of user-defined length. This method disaggregates the disturbance schedule down to annual time steps (assuming uniform distribution of disturbed area within each planning period).

Note

The algorithm uses the development-type-wise operability rules from the ForestModel instance to allocate the aspatial schedule to the raster pixels. Thus, the output should be feasible with respect to the original model.

Note

Currently this method randomly selects a subset of operable pixels for disturbance at each annual time step. This is not likely to produce a realistic landscape-level spatial disturbance pattern. Realistically, each disturbance type is likely to have a distinct patch size distribution (e.g., clearcut harvest disturbances might have a uniform patch size distribution, whereas wildfire disturbances might follow a Weibull distribution, etc.). We may revisit this in a later release, possibly adding extra parameters to allow disturbance-type-wise parametrization of pixel aggregation methodology.

Piggyback disturbances (if specified in the piggyback_acodes parameter in the constructor) are simulated at the end of the process.

Parameters:

  • mask (tuple(str)) – Tuple of strings, used to filter development types. Typically, this will be used to filter multi-management-unit models (e.g., if input raster inventory and output disturbance raster files need to be generated on a per-management-unit basis).

  • verbose (bool) – Prints extra info to the console if True (default False).

  • commit (bool) – Automatically calls commit() if True (default True).

  • da (int) – [FOR DEBUG USE ONLY. DO NOT MODIFY.]

  • fudge (float) – [FOR DEBUG USE ONLY. DO NOT MODIFY.]

cleanup()[source]

Calls commit(), and also closes the open file handle for the forest inventory input GeoTIFF file. The ForestRaster instance is essentially expired after this method has been called, and further calls to allocate_schedule() will trigger a RuntimeError exception.

commit()[source]

Closes all open handles for output GeoTIFF files, which commits changes stored in data buffer memory. The ForestRaster instance is essentially expired after this method has been called, and further calls to allocate_schedule() will trigger a RuntimeError exception.

grow()[source]

Grows trees, only increment non-NA values