You are viewing the latest unreleased documentation v3.2.2.dev178. You may prefer a stable version.

Source code for iris.palette

# Copyright Iris contributors
#
# This file is part of Iris and is released under the LGPL license.
# See COPYING and COPYING.LESSER in the root of the repository for full
# licensing details.
"""
Load, configure and register color map palettes and initialise
color map meta-data mappings.

"""

from functools import wraps
import os
import os.path
import re

import cf_units
import matplotlib.cm as mpl_cm
import matplotlib.colors as mpl_colors
import numpy as np

import iris.config
import iris.cube

# Symmetric normalization function pivot points by SI unit.
PIVOT_BY_UNIT = {cf_units.Unit("K"): 273.15}

# Color map names by palette file metadata field value.
CMAP_BREWER = set()
_CMAP_BY_SCHEME = None
_CMAP_BY_KEYWORD = None
_CMAP_BY_STD_NAME = None

_MISSING_KWARG_CMAP = "missing kwarg cmap"
_MISSING_KWARG_NORM = "missing kwarg norm"


[docs]def is_brewer(cmap): """ Determine whether the color map is a Cynthia Brewer color map. Args: * cmap: The color map instance. Returns: Boolean. """ result = False if cmap is not None: result = cmap.name in CMAP_BREWER return result
def _default_cmap_norm(args, kwargs): """ This function injects default cmap and norm behavour into the keyword arguments, based on the cube referenced within the positional arguments. """ cube = None # Find the single cube reference within the positional arguments. for arg in args: if isinstance(arg, iris.cube.Cube): cube = arg break # Find the keyword arguments of interest. colors = kwargs.get("colors", None) # cmap = None to disable default behaviour. cmap = kwargs.get("cmap", _MISSING_KWARG_CMAP) # norm = None to disable default behaviour. norm = kwargs.get("norm", _MISSING_KWARG_NORM) # Note that "colors" and "cmap" keywords are mutually exclusive. if colors is None and cube is not None: std_name = cube.standard_name.lower() if cube.standard_name else "" # Perform default "cmap" keyword behaviour. if cmap == _MISSING_KWARG_CMAP: # Check for an exact match against standard name. cmaps = _CMAP_BY_STD_NAME.get(std_name, set()) if len(cmaps) == 0: # Check for a fuzzy match against a keyword. for keyword in _CMAP_BY_KEYWORD.keys(): if keyword in std_name: cmaps.update(_CMAP_BY_KEYWORD[keyword]) # Add default color map to keyword arguments. if len(cmaps): cmap = sorted(cmaps, reverse=True)[0] kwargs["cmap"] = mpl_cm.get_cmap(cmap) # Perform default "norm" keyword behaviour. if norm == _MISSING_KWARG_NORM: if "anomaly" in std_name: # Determine the pivot point. pivot = PIVOT_BY_UNIT.get(cube.units, 0) norm = SymmetricNormalize(pivot) kwargs["norm"] = norm return args, kwargs
[docs]def cmap_norm(cube): """ Determine the default :class:`matplotlib.colors.LinearSegmentedColormap` and :class:`iris.palette.SymmetricNormalize` instances associated with the cube. Args: * cube (:class:`iris.cube.Cube`): Source cube to generate default palette from. Returns: Tuple of :class:`matplotlib.colors.LinearSegmentedColormap` and :class:`iris.palette.SymmetricNormalize` """ args, kwargs = _default_cmap_norm((cube,), {}) return kwargs.get("cmap"), kwargs.get("norm")
[docs]def auto_palette(func): """ Decorator wrapper function to control the default behaviour of the matplotlib cmap and norm keyword arguments. Args: * func (callable): Callable function to be wrapped by the decorator. Returns: Closure wrapper function. """ @wraps(func) def wrapper_func(*args, **kwargs): """ Closure wrapper function to provide default keyword argument behaviour. """ # Update the keyword arguments with defaults. args, kwargs = _default_cmap_norm(args, kwargs) # Call the wrapped function and return its result. return func(*args, **kwargs) # Return the closure wrapper function. return wrapper_func
[docs]class SymmetricNormalize(mpl_colors.Normalize): """ Provides a symmetric normalization class around a given pivot point. """ def __init__(self, pivot, *args, **kwargs): self.pivot = pivot self._vmin = None self._vmax = None mpl_colors.Normalize.__init__(self, *args, **kwargs) def __repr__(self): return "%s(%r)" % (self.__class__.__name__, self.pivot) def _update(self, val, update_min=True, update_max=True): # Update both _vmin and _vmax from given value. val_diff = np.abs(val - self.pivot) vmin_diff = np.abs(self._vmin - self.pivot) if self._vmin else 0.0 vmax_diff = np.abs(self._vmax - self.pivot) if self._vmax else 0.0 diff = max(val_diff, vmin_diff, vmax_diff) if update_min: self._vmin = self.pivot - diff if update_max: self._vmax = self.pivot + diff @property def vmin(self): return getattr(self, "_vmin") @vmin.setter def vmin(self, val): if val is None: self._vmin = None elif self._vmax is None: # Don't set _vmax, it'll stop matplotlib from giving us one. self._update(val, update_max=False) else: # Set both _vmin and _vmax from value self._update(val) @property def vmax(self): return getattr(self, "_vmax") @vmax.setter def vmax(self, val): if val is None: self._vmax = None elif self._vmin is None: # Don't set _vmin, it'll stop matplotlib from giving us one. self._update(val, update_min=False) else: # Set both _vmin and _vmax from value self._update(val)
def _load_palette(): """ Load, configure and register color map palettes and initialise color map metadata mappings. """ # Reference these module level namespace variables. global CMAP_BREWER, _CMAP_BY_SCHEME, _CMAP_BY_KEYWORD, _CMAP_BY_STD_NAME _CMAP_BY_SCHEME = {} _CMAP_BY_KEYWORD = {} _CMAP_BY_STD_NAME = {} filenames = [] # Identify all .txt color map palette files. for root, dirs, files in os.walk(iris.config.PALETTE_PATH): # Prune any .svn directory from the tree walk. if ".svn" in dirs: del dirs[dirs.index(".svn")] # Identify any target .txt color map palette files. filenames.extend( [ os.path.join(root, filename) for filename in files if os.path.splitext(filename)[1] == ".txt" ] ) for filename in filenames: # Default color map name based on the file base-name (case-SENSITIVE). cmap_name = os.path.splitext(os.path.basename(filename))[0] cmap_scheme = None cmap_keywords = [] cmap_std_names = [] cmap_type = None # Perform default color map interpolation for quantization # levels per primary color. interpolate_flag = True # Read the file header. with open(filename) as file_handle: header = filter( lambda line: re.match(r"^\s*#.*:\s+.*$", line), file_handle.readlines(), ) # Extract the file header metadata. for line in header: line = line.replace("#", "", 1).split(":") head = line[0].strip().lower() body = line[1].strip() if head == "name": # Case-SENSITIVE. cmap_name = "brewer_{}".format(body) if head == "scheme": # Case-insensitive. cmap_scheme = body.lower() if head == "keyword": # Case-insensitive. keywords = [part.strip().lower() for part in body.split(",")] cmap_keywords.extend(keywords) if head == "std_name": # Case-insensitive. std_names = [part.strip().lower() for part in body.split(",")] cmap_std_names.extend(std_names) if head == "interpolate": # Case-insensitive. interpolate_flag = body.lower() != "off" if head == "type": # Case-insensitive. cmap_type = body.lower() # Integrity check for meta-data 'type' field. assert cmap_type is not None, ( 'Missing meta-data "type" keyword for color map file, "%s"' % filename ) assert ( cmap_type == "rgb" ), 'Invalid type [%s] for color map file "%s"' % (cmap_type, filename) # Update the color map look-up dictionaries. CMAP_BREWER.add(cmap_name) if cmap_scheme is not None: scheme_group = _CMAP_BY_SCHEME.setdefault(cmap_scheme, set()) scheme_group.add(cmap_name) for keyword in cmap_keywords: keyword_group = _CMAP_BY_KEYWORD.setdefault(keyword, set()) keyword_group.add(cmap_name) for std_name in cmap_std_names: std_name_group = _CMAP_BY_STD_NAME.setdefault(std_name, set()) std_name_group.add(cmap_name) # Load palette data and create the associated color map. cmap_data = np.loadtxt(filename) # Ensure to restrict the number of RGB quantization levels to # prevent color map interpolation. if interpolate_flag: # Perform default color map interpolation for quantization # levels per primary color. cmap = mpl_colors.LinearSegmentedColormap.from_list( cmap_name, cmap_data ) else: # Restrict quantization levels per primary color (turn-off # interpolation). # Typically used for Brewer color maps. cmap = mpl_colors.LinearSegmentedColormap.from_list( cmap_name, cmap_data, N=len(cmap_data) ) # Register the color map for use. mpl_cm.register_cmap(cmap=cmap) # Ensure to load the color map palettes. _load_palette()