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.

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'

class natcap.invest.reports.raster_utils.SpecialValueConfig(extend: Literal['min', 'max'], threshold: float, label: str, color: str)

Bases: object

Configuration for customizing color and labeling of special value range.

The colorbar will be extended on the side specified by extend, and values beyond the threshold will be colored with color and the end of the colorbar will be labeled with label.

color: str: Color used for the special values

extend: Literal['min', 'max']: Which side of the colorbar to extend

label: str: Label to show on the colorbar for the special region

threshold: float: Boundary value for the special range

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.build_raster_plot_configs(id_lookup_table, raster_plot_tuples)

Build RasterPlotConfigs for use in plotting input or output rasters.

Parameters:

id_lookup_table (dict) – Where to look up each raster id to find its filepath. Typically this will be either the args dict that was passed to the model’s execute method, or the FileRegistry that was generated by the model run.
raster_plot_tuples (list[tuple[str]]) – A list of 2- and/or 3-tuples, each of which should contain the following: - first, the id of the raster (as defined in the model spec), - second, the datatype of the raster (‘continuous’, ‘divergent’, ‘nominal’, ‘binary’, or ‘binary_high_contrast’), and - third (optionally), the transform to apply to the colormap when plotting (either ‘linear’ or ‘log’; will default to ‘linear’ if not specified).

Returns:

A list of RasterPlotConfig suitable for passing to: natcap.invest.reports.raster_utils.plot_and_base64_encode_rasters

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.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_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.