Colormaps in GeoIPS#

A colormap is a class-based GeoIPS plugin that works in conjunction with an image-based output formatter to dictate which colors are used to represent your data. GeoIPS colormaps are structured as Python dictionaries that contain the information needed for the output formatter to apply a colormap to the final image. This information can include things like the matplotlib-compatible colormap (existing or user-created), the data range covered by the colormap, and information about the colorbar (if one is desired).

Most colormappers include a standard set of information that is useful for plotting:

cmap: The matplotlib colormap object that will be applied to the image.
norm: An object that scales your values so the colorbar covers the specified range.
colorbar: A boolean indicating whether to include a colorbar in the image.
cbar_ticks: Data points at which to place tick marks.
cbar_tick_labels: labels for the tick marks (a list of strings; should be the same length as cbar_ticks).
cbar_label: The label of the colorbar.
boundaries: A matplotlib parameter that is used to specify the boundaries within the colormap.
cbar_spacing: A matplotlib parameter that determines if each color has the same size in the colorbar, or if it is based on the proportion of data it covers.
cbar_full_width: A boolean indicating whether the colorbar should cover the full width of the image.

Other keyword arguments can be passed to the matplotlib colorbar in some output formatters using the colorbar_kwargs, set_ticks_kwargs, and set_label_kwargs keys.

For an example of how a custom colormapper is formatted, see the Infrared colormapper.

Using a Colormapper#

Colormappers can be applied in two ways:

1. Inclusion in Product Specifications: If using one of the existing output formatters in GeoIPS, the colormapper can be included in the product default specification, which can be executed via the command line or a test script using a GeoIPS procflow.

For examples of including a colormapper in a product implementation, see the Extend GeoIPS with a Colormapper and product defaults tutorials.

2. Direct Invocation: If you have your own output formatter, the colormapper can be called directly:

from geoips.interfaces import colormappers
cmap_name = "Infrared"
mpl_colors_info = colormappers.get_plugin(cmap_name)

The output of the plugin can then be applied to the plot of the image. For example:

from geoips.image_utils.mpl_utils import create_colorbar

main_ax.imshow(
    data,
    transform=mapobj,
    extent=mapobj.bounds,
    cmap=mpl_colors_info["cmap"],  # Use the colormap defined in the colormapper
    norm=mpl_colors_info["norm"],  # with the defined norm.
    **extra_args,
)

if mpl_colors_info["colorbar"] is True:
    # Create the colorbar defined in the colormapper.
    create_colorbar(fig, mpl_colors_info)

Plugin arguments#

The arguments accepted by a colormapper step (validated in Order-Based Processing workflows) are defined by the model below. These fields are generated directly from the code, so they always reflect the current validation rules.

pydantic model geoips.pydantic_models.v1.colormappers.ColormapperArgumentsModel[source]

Colormapper step argument definition.

Pydantic model defining and validating Colormapper step arguments.

Fields:

Validators:

field cbar_full_width: bool = False: “Extend the colorbar across the full width of the image”

field cbar_label: str = 'plugin_provided': Positional parameter passed to cbar.set_label If specified, use cbar_label string as colorbar label.

field cbar_spacing: str = 'proportional': “spacing” argument to pass to fig.colorbar; can also specify directly within “colorbar_kwargs”

field cbar_tick_labels: list[str] | None = None: ‘labels’ argument to pass to cbar.set_ticks. can also specify directly within ‘set_ticks_kwarg’

field cbar_ticks: list[float] | None = None: Positional parameter passed to cbar.set_ticks Specify explicit list of ticks to include for colorbar.None indicates ticks at int(min) and int(max) values

field cmap_name: str = 'plugin_provided': Specify the name of the resulting matplotlib colormap. If no ascii_path specified, will use builtin matplotlib colormap of name cmap_name.

field cmap_path: str | None = None

field cmap_source: str = 'plugin_provided'

field colorbar_kwargs: dict | None = None: keyword arguments to pass through directly to ‘fig.colorbar’

field create_colorbar: bool | None = True: Specify whether the image should contain a colorbar or not.

field data_range: tuple[float, float] | str = 'plugin_provided': Min and max value for colormapmatplotlib.colors.Normalize(vmin=min_val, vmax=max_val)

field pressure_range_legend: List[str] | None = None: List of strings that are used for setting the cbar tick labels

field set_label_kwarg: dict | None = None: keyword arguments to pass through directly to “cbar.set_label”

field set_ticks_kwargs: dict | None = None: keyword arguments to pass through directly to “cbar.set_ticks”