natcap.invest.reports.raster_utils

class natcap.invest.reports.raster_utils.RasterDatatype(value)

Bases: str, Enum

The type of measurement represented by the raster.

binary = 'binary': Use binary where 1 pixels are likely to be adjacent to white background and 0 (black) pixels, as in what_drains_to_stream maps.

binary_high_contrast = 'binary_high_contrast': Use binary_high_contrast where 1 pixels are likely to be surrounded by 0 pixels but _not_ adjacent to white background, as in stream network maps.

continuous = 'continuous': For numeric data.

divergent = 'divergent': For rasters where values span positive and negative values.

nominal = 'nominal': For rasters where the pixel values represent categories.

class natcap.invest.reports.raster_utils.RasterPlotConfig(raster_path: str, datatype: RasterDatatype, spec: Input | Output, transform: RasterTransform = RasterTransform.linear, title: str | None = None, colormap: str | Colormap | None = None, special_values: SpecialValueConfig | None = None)

Bases: object

A definition for how to plot a raster.

check_special_values_and_datatype()

colormap: str | Colormap | None = None: The string name of a registered matplotlib colormap or a colormap object.

datatype: RasterDatatype: Datatype will determine colormap, legend, and resampling algorithm

raster_path: str: Filepath to a raster to plot. The basename will be the plot title.

spec: Input | Output: The InVEST specification of the raster.

special_values: SpecialValueConfig | None = None: Will customize the color and labeling of a special range of values

title: str | None = None: An optional plot title. If None, the filename is used.

transform: RasterTransform = 'linear': For highly skewed data, a transformation can help reveal variation.

class natcap.invest.reports.raster_utils.RasterTransform(value)

Bases: str, Enum

The transformation to apply to values before mapping to colors.

Original values are plotted, but the colorbar will use this scale.

linear = 'linear'

log = 'log'

Bases: BaseModel

Configuration for customizing color and labeling of special value range.

The colorbar will be extended on either the lower or upper bounds (or both), and values beyond the thresholds will be colored with colors and the end of the colorbar will be labeled with labels.

colors: tuple[str | None, str | None]: Color(s) used for the special values

labels: tuple[str | None, str | None]: Label(s) to show on the colorbar for the special region

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

thresholds: tuple[float | None, float | None]: Boundary value for the special upper and lower bounds, respectively

validate_special_value_config()

natcap.invest.reports.raster_utils.base64_encode(figure)

Encode a Matplotlib-generated figure as a base64 string.

Parameters:: figure (matplotlib.Figure) – the figure to encode.
Returns:: A string representing the figure as a base64-encoded PNG.

natcap.invest.reports.raster_utils.base64_encode_file(filepath)

Encode a binary file as a base64 string.

Parameters:: filepath (str) – the file to encode.
Returns:: A string representing the file as a base64-encoded string.

natcap.invest.reports.raster_utils.caption_raster_list(raster_list: list[RasterPlotConfig])

natcap.invest.reports.raster_utils.geometamaker_load(filepath)

natcap.invest.reports.raster_utils.get_categorical_colors(num_colors)

natcap.invest.reports.raster_utils.plot_and_base64_encode_rasters(raster_list: list[RasterPlotConfig]) → str

Plot and base-64-encode a list of rasters.

Parameters:

raster_dtype_list (list[RasterPlotConfig]) – a list of RasterPlotConfig objects, each of which contains the path to a raster, the type of data in the raster (‘continuous’, ‘divergent’, ‘nominal’, ‘binary’, or ‘binary_high_contrast’), and the transformation to apply to the colormap (‘linear’ or ‘log’).

Returns:

A string representing a base64-encoded PNG in which each of the: provided rasters is plotted as a subplot.

natcap.invest.reports.raster_utils.plot_categorical_raster_with_table(raster_path_list: list[str])

Plot one or two categorical rasters and generate an HTML table legend.

Unique pixel values are determined either from an existing Raster Attribute Table or by calculating a frequency table from the array.

If two rasters are given, it is assumed the pixel values have a shared meaning and the tables are joined based on the value column. All rasters will share the same colormap.

Parameters:

raster_path_list (list[str]) – list of filepaths to categorical rasters

Returns:

A string representing a base64-encoded PNG
An html table to use as the legend for the image

Return type:

A tuple containing

natcap.invest.reports.raster_utils.plot_raster_facets(tif_list, datatype, transform=None, title_list=None, small_plots=False, colormap=None, supertitle=None)

Plot a list of rasters that will all share a fixed colorscale.

When all the rasters have the same shape and represent the same variable, it’s useful to scale the colorbar to the global min/max values across all rasters, so that the colors are visually comparable across the maps. All rasters share a datatype and a transform.

Parameters:

tif_list (list) – list of filepaths to rasters
datatype (str) – string describing the datatype of rasters. One of (‘continuous’, ‘divergent’).
transform (str) – string describing the transformation to apply to the colormap. Either ‘linear’ or ‘log’.
title_list (list) – Optional list of strings to use as subplot titles. If None, the raster filename is used as the title.
small_plots (bool) – Defaults to False. If True, the typical number of columns calculated for plotting facets will be increased by 1, making the plots smaller so more can be viewed side-by-side.
colormap (str) – Optional string name of a registered matplotlib colormap or a colormap object to use in place of the default derived from the raster datatype.
supertitle (str) – Optional title to use for the entire group of raster facets.

natcap.invest.reports.raster_utils.plot_raster_list(raster_list: list[RasterPlotConfig])

Plot a list of rasters.

Parameters:: raster_list (list[RasterPlotConfig]) – a list of RasterPlotConfig objects, each of which contains the path to a raster, the type of data in the raster (‘continuous’, ‘divergent’, ‘nominal’, ‘binary’, or ‘binary_high_contrast’), and the transformation to apply to the colormap (‘linear’ or ‘log’).
Returns:: matplotlib.figure.Figure

natcap.invest.reports.raster_utils.raster_inputs_summary(args_dict, model_spec): Create a table of stats for all rasters in an args_dict.

natcap.invest.reports.raster_utils.raster_workspace_summary(file_registry)

Create a table of stats for all rasters in a file_registry.

Metadata docs were already created by invest for files in the workspace.