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