plot_bitfield

typhon.plots.plot_bitfield(ax, X, Y, bitfield, flag_dict, cmap, cax=None, pcolor_args={}, colorbar_args={}, unflagged='unflagged', joiner=', ')[source]

Plot a bitfield of categories with pcolor

The numeric values in a bitfield are not directly meaningful. Rather, the relevant information is whether a particular bit is set. This function plots a 2-D bitfield using pcolor, then displays each unique combination of flags (or the absence of any flags) as a distinct category, and shows the corresponding labels in the colourbar.

This assumes that, even when there are many possible flags, only a small subset of combinations of flags actually occurs within the data. Should this exceed a dozen or so, then the colorbar/legend will become particularly crowded.

Note that a colorbar may not be the optimal legend to show alongside categorical data but as this function already exists it is more convenient to exploit than others. Currently this function only works with pcolor, not with pcolormesh, scatter, or other plotting functions for 3-D data.

See https://gist.github.com/jakevdp/8a992f606899ac24b711 for an illustration of what the result may look like, although that is for the case of a scatter rather than pcolor plot.

Parameters:

  • ax (Axes) – Axes (or subclass thereof, such as GeoAxes) to plot in.

  • X (ndarray) – X-values for bitfield. Interpretation as for pcolor.

  • Y (ndarray) – Y-values for bitfield. Interpretation as for pcolor.

  • bitfield (ndarray) – Bitfield to be plotted.

  • flag_dict (Mapping[int, str]) – Mapping of flag values to their meanings. Keys should be powers of 2. For example, {1: “DO_NOT_USE”, 2: “BAD_GEOLOCATION”, 4: “BAD_TIME”}.

  • cmap (str) – Colourmap to use. This needs to be passed here because it needs to be converted to be discrete corresponding to the number of unique values. I recommend to choose a qualitative colourmap such as Set1, Set2, or Set3.

  • cax (Axes) – Optional. If given, put colorbar here.

  • pcolor_args (Mapping) – Extra arguments to be passed to pcolor.

  • colorbar_args (Mapping) – Extra arguments to be passed to colorbar.

  • unflagged (str) – Label to use for unflagged values. Defaults to “unflagged”.

  • joiner (str) – How to join different flags.

Returns:

(AxesImage, Colorbar) that were generated