pycolorbar.settings package

Submodules

pycolorbar.settings.colorbar_io module

Define functions to read and write colorbar YAML files.

pycolorbar.settings.colorbar_io.is_single_colorbar_settings(dictionary)

Determine if a dictionary is a single colorbar settings.

pycolorbar.settings.colorbar_io.read_cbar_dict(filepath, name=None, validate=False)

Read colorbar YAML file with single colorbar settings.

This is an helper function and is not used by the ColorbarRegistry.

By default, the colorbar YAML file are not validated at read-time. Set validate=True to validate the dictionary at read-time.

pycolorbar.settings.colorbar_io.read_cbar_dicts(filepath)

Read colorbar YAML file with a single or multiple colorbar settings.

By default, the colorbar YAML file are not validated at read time !

pycolorbar.settings.colorbar_io.write_cbar_dict(cbar_dict, name, filepath, force=False, validate=True)

Write a single colorbar settings dictionary to a YAML file.

By default, the colorbar YAML file are validated before writing to disk !

pycolorbar.settings.colorbar_io.write_cbar_dicts(cbar_dicts, filepath, names=None, force=False, sort_keys=False, validate=True)

Write a multiple colorbar settings dictionary to a YAML file.

By default, the colorbar YAML file are validated before writing to disk !

pycolorbar.settings.colorbar_registry module

Define the register of univiariate colorbars.

class pycolorbar.settings.colorbar_registry.ColorbarRegistry

Bases: object

A singleton class to manage colorbar registrations.

This class provides methods to register colorbars settings, add new one on-the-fly, and to remove them.

_instance

The singleton instance of the ColorbarRegistry.

Type

ColorbarRegistry

registry

The dictionary holding the registered colorbar settings.

Type

dict

add_cbar_dict(cbar_dict: dict, name: str, verbose: bool = True, force: bool = True)

Add a colorbar configuration to the registry by providing a colorbar dictionary.

Parameters

• cbar_dict (dict) – The colorbar dictionary containing the colorbar’s configuration.

• name (str) – The name of the colorbar.

• verbose (bool, optional) – If True, the method will print a warning when overwriting an existing colorbar. The default is True.

• force (bool, optional) – If True, it allow to overwrites existing colorbar settings. The default is True. If False, it raise an error if attempting to overwrite an existing colorbar.

Notes

If a colorbar with the same name already exists, it will be overwritten. The configuration is validated when adding a colorbar configuration with this method !

available(category=None, exclude_referenced=False)

List the name of available colorbars for a specific category.

get_cbar_dict(name: str, resolve_reference=True, validate=True)

Retrieve the colorbar dictionary of a registered colorbar.

Parameters

• name (str) – The name of the colorbar.

• resolve_reference (bool) – Determines the behavior when the colorbar dictionary contains the ‘reference’ keyword. If True, the function resolves the reference by returning the actual colorbar dictionary that the reference points to. If False, the function returns the original colorbar dictionary, including the ‘reference’ keyword. The default is True.

• validate (bool) – Whether to validate the colorbar dictionary. The default is True.

Returns

The validated colorbar dictionary.

Return type

dict

Raises

ValueError – If the colorbar configuration is not registered.

get_cmap(name)

Retrieve the colormap of a registered colorbar.

Parameters

name (str) – The name of the colorbar.

Returns

The matplotlib Colormap.

Return type

matplotlib.colors.Colormap

Notes

This function also sets the over/under and bad colors specified in the colorbar configuration.

classmethod get_instance()

Return the singleton instance of the ColorbarRegistry.

get_plot_kwargs(name=None, user_plot_kwargs=None, user_cbar_kwargs=None)

Get pycolorbar plot kwargs (updated with optional user arguments).

get_referenced_settings()

Return the colorbar settings names which a reference to another colorbar.

get_standalone_settings()

Return the colorbar settings names which are not a reference to another colorbar.

property names

List the names of all registered colorbars settings.

register(filepath: str, verbose: bool = True, force: bool = True, validate=False)

Register colorbar(s) configuration(s) defined in a YAML file.

Parameters

• filepath (str) – The YAML file path where the colorbar(s) settings are specified. A single YAML file can contain the configuration of multiple colorbars ! The name of the YAML files it’s not used !

• force (bool, optional) – If True, it allow to overwrites existing colorbar settings. The default is True. If False, it raise an error if attempting to overwrite an existing colorbar.

• verbose (bool, optional) – If True, the method will print a warning when overwriting existing colorbars. The default is True.

• validate (bool, optional) – Whether to validate the colorbar configuration file before registering. The default is False.

Notes

If a a colorbar configuration with the same name already exists, it will be overwritten. The validity of the colorbar(s) configuration(s) is not validated at registration ! Use pycolorbar.colorbars.validate() to validate the registered colorbars.

reset()

Clears the entire Colorbar registry.

show_colorbar(name, user_plot_kwargs=None, user_cbar_kwargs=None, fig_size=(6, 1))

Display a colorbar (updated with optional user arguments).

show_colorbars(category=None, exclude_referenced=True, subplot_size=None)

Display available colorbars (optionally of a specific category).

to_yaml(filepath, names=None, force=False, sort_keys=False)

Write the registered colorbars settings to a YAML file.

unregister(name: str)

Remove a specific colorbar configuration from the registry.

Parameters

name (str) – The name of the colorbar’s configuration to remove.

Raises

ValueError – If the colorbar with the specified name is not registered.

validate(name: Optional[str] = None)

Validate the registered colorbars. If a specific name is provided, only that colorbar is validated.

Parameters

name (str, optional) – The name of a specific colorbar to validate. If None, all registered colorbars are validated.

Raises

ValueError – If any of the validated colorbars have invalid configurations.

Notes

Invalid colorbar configurations are reported.

pycolorbar.settings.colorbar_registry.available_colorbars(category=None, exclude_referenced=False)

Return a list with the name of registered colorbars settings.

Parameters

• category (str, optional) – The name of an optional category to subset the list of registered colorbars. In the colorbar YAML file, the auxiliary/category field enable to specify the relevant categories of the colorbar. If None (the default), returns all available colorbars.

• exclude_referenced (bool, optional) – If True, exclude from the list the registered colorbars that refers to another colorbar for the actual configuration. The default is False.

Returns

names – List of registered colorbars.

Return type

str

pycolorbar.settings.colorbar_registry.get_cbar_dict(name, resolve_reference=True)

Retrieve the validated colorbar dictionary of a registered colorbar.

Parameters

• name (str) – The name of the colorbar.

• resolve_reference (bool) – Determines the behavior when the colorbar dictionary contains the ‘reference’ keyword. If True, the function resolves the reference by returning the actual colorbar dictionary that the reference points to. If False, the function returns the original colorbar dictionary, including the ‘reference’ keyword. The default is True.

Returns

The validated colorbar dictionary.

Return type

dict

pycolorbar.settings.colorbar_registry.get_plot_kwargs(name=None, user_plot_kwargs=None, user_cbar_kwargs=None)

Get matplotlib, xarray and geopandas compatible plot and colorbar kwargs.

Parameters

• name (str, optional) – Name of the registered colorbar settings. The default is None.

• user_plot_kwargs (dict, optional) – User-specific plot_kwargs. Example arguments includes ‘vmin’, ‘vmax’, ‘norm’, ‘cmap’, ‘levels’.

• user_cbar_kwargs (dict, optional) – User-specific cbar_kwargs. See matplotlib.colorbar.Colorbar for more details.

Returns

A tuple with the plot_kwargs and cbar_kwargs to pass to the plotting functions.

Return type

plot_kwargs, cbar_kwargs

Examples

xarray Example:

plot_kwargs, cbar_kwargs = get_plot_kwargs("my_variable_name")
da.plot.imshow(**plot_kwargs, cbar_kwargs=cbar_kwargs)

matplotlib Example:

plt.imshow(**plot_kwargs)
plt.colorbar(**cbar_kwargs)

geopandas Example:

gdf.plot(**plot_kwargs, legend=False)
plt.colorbar(**cbar_kwargs)

pycolorbar.settings.colorbar_registry.register_colorbar(filepath: str, verbose: bool = True, force: bool = True)

Register a single colorbar YAML file.

Parameters

• filepath (str) – The file path where the colorbar’s YAML file is located.

• force (bool, optional) – If True, it allow to overwrites existing colorbar settings. The default is True. If False, it raise an error if attempting to overwrite an existing colorbar.

• verbose (bool, optional) – If True, the method will print a warning when overwriting existing colorbars. The default is True.

Raises

ValueError – If the specified colorbar YAML file is not available in the directory.

Notes

If a a colorbar configuration with the same name already exists and force=True, it will be overwritten. The validity of the colorbar(s) configuration(s) is not validated at registration ! Use pycolorbar.colorbars.validate() to validate the registered colorbars.

pycolorbar.settings.colorbar_registry.register_colorbars(directory: str, verbose: bool = True, force: bool = True)

Register all colorbar YAML files present in the specified directory (if name=None).

This function assumes that all YAML files present in the directory are valid pycolorbar colorbars configuration files.

Parameters

• directory (str) – The directory where colorbar YAML files are located.

• force (bool, optional) – If True, it allow to overwrites existing colorbar settings. The default is True. If False, it raise an error if attempting to overwrite an existing colorbar.

• verbose (bool, optional) – If True, the method will print a warning when overwriting existing colorbars. The default is True.

Notes

If a a colorbar configuration with the same name already exists and force=True, it will be overwritten. The validity of the colorbar(s) configuration(s) is not validated at registration ! Use pycolorbar.colorbars.validate() to validate the registered colorbars.

pycolorbar.settings.colorbar_validator module

Implementation of pydantic validator for univariate colorbar YAML files.

class pycolorbar.settings.colorbar_validator.AsinhNormSettings(*, linear_width: Optional[Union[int, float]] = 1, vmin: Optional[float] = None, vmax: Optional[float] = None, clip: Optional[bool] = False)

Bases: BaseModel

Pydantic model for AsinhNorm settings.

classmethod check_valid_args(values)

Check for no excess parameters in AsinhNorm.

classmethod check_vmin_vmax(values)

Check vmin and vmax for AsinhNorm.

clip: Optional[bool]

linear_width: Optional[Union[int, float]]

model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[dict[str, FieldInfo]] = {'clip': FieldInfo(annotation=Union[bool, NoneType], required=False, default=False), 'linear_width': FieldInfo(annotation=Union[int, float, NoneType], required=False, default=1), 'vmax': FieldInfo(annotation=Union[float, NoneType], required=False), 'vmin': FieldInfo(annotation=Union[float, NoneType], required=False)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo].

This replaces Model.__fields__ from Pydantic V1.

classmethod validate_clip(v)

Validate clip option for AsinhNorm.

classmethod validate_linear_width(v)

Validate linear_width for AsinhNorm.

vmax: Optional[float]

vmin: Optional[float]

class pycolorbar.settings.colorbar_validator.BoundaryNormSettings(*, boundaries: list[float], clip: Optional[bool] = False, extend: Optional[str] = 'neither', ncolors: Optional[int] = None)

Bases: BaseModel

Pydantic model for BoundaryNorm settings.

boundaries: list[float]

classmethod check_valid_args(values)

Check for no excess parameters in BoundaryNorm.

clip: Optional[bool]

extend: Optional[str]

model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[dict[str, FieldInfo]] = {'boundaries': FieldInfo(annotation=list[float], required=True), 'clip': FieldInfo(annotation=Union[bool, NoneType], required=False, default=False), 'extend': FieldInfo(annotation=Union[str, NoneType], required=False, default='neither'), 'ncolors': FieldInfo(annotation=Union[int, NoneType], required=False)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo].

This replaces Model.__fields__ from Pydantic V1.

ncolors: Optional[int]

classmethod validate_boundaries(v)

Validate boundaries list for BoundaryNorm.

classmethod validate_clip(v)

Validate clip option for BoundaryNorm.

classmethod validate_extend(v)

Validate extend option for BoundaryNorm.

validate_ncolors()

Validate ncolors for BoundaryNorm.

class pycolorbar.settings.colorbar_validator.CategoryNormSettings(*, labels: list[str], first_value: Optional[int] = 0)

Bases: BaseModel

Pydantic model for CategoryNorm settings.

classmethod check_valid_args(values)

Check for no excess parameters in CategoryNorm.

first_value: Optional[int]

labels: list[str]

model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[dict[str, FieldInfo]] = {'first_value': FieldInfo(annotation=Union[int, NoneType], required=False, default=0), 'labels': FieldInfo(annotation=list[str], required=True)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo].

This replaces Model.__fields__ from Pydantic V1.

classmethod validate_first_value(v)

Validate first_value for CategoryNorm.

classmethod validate_labels(v)

Validate labels for CategoryNorm.

class pycolorbar.settings.colorbar_validator.CenteredNormSettings(*, vcenter: Optional[Union[int, float]] = 0, halfrange: Optional[Union[int, float]] = None, clip: Optional[bool] = False)

Bases: BaseModel

Pydantic model for CenteredNorm settings.

classmethod check_valid_args(values)

Check for no excess parameters in CenteredNorm.

clip: Optional[bool]

halfrange: Optional[Union[int, float]]

model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[dict[str, FieldInfo]] = {'clip': FieldInfo(annotation=Union[bool, NoneType], required=False, default=False), 'halfrange': FieldInfo(annotation=Union[int, float, NoneType], required=False), 'vcenter': FieldInfo(annotation=Union[int, float, NoneType], required=False, default=0)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo].

This replaces Model.__fields__ from Pydantic V1.

classmethod validate_clip(v)

Validate clip option for CenteredNorm.

classmethod validate_halfrange(v)

Validate halfrange for CenteredNorm.

classmethod validate_vcenter(v)

Validate vcenter for CenteredNorm.

vcenter: Optional[Union[int, float]]

class pycolorbar.settings.colorbar_validator.ColorbarSettings(*, extend: Optional[str] = 'neither', extendfrac: Optional[Union[float, list[float], str]] = 'auto', extendrect: Optional[bool] = False, label: Optional[str] = None, ticklabels: Optional[list[str]] = None, ticks: Optional[list[Union[int, float]]] = None, ticklocation: Optional[str] = 'auto', spacing: Optional[str] = 'uniform', drawedges: Optional[bool] = False, shrink: Optional[float] = 1)

Bases: BaseModel

Pydantic model for colorbar settings.

drawedges: Optional[bool]

extend: Optional[str]

extendfrac: Optional[Union[float, list[float], str]]

extendrect: Optional[bool]

label: Optional[str]

model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[dict[str, FieldInfo]] = {'drawedges': FieldInfo(annotation=Union[bool, NoneType], required=False, default=False), 'extend': FieldInfo(annotation=Union[str, NoneType], required=False, default='neither'), 'extendfrac': FieldInfo(annotation=Union[float, list[float], str, NoneType], required=False, default='auto'), 'extendrect': FieldInfo(annotation=Union[bool, NoneType], required=False, default=False), 'label': FieldInfo(annotation=Union[str, NoneType], required=False), 'shrink': FieldInfo(annotation=Union[float, NoneType], required=False, default=1), 'spacing': FieldInfo(annotation=Union[str, NoneType], required=False, default='uniform'), 'ticklabels': FieldInfo(annotation=Union[list[str], NoneType], required=False), 'ticklocation': FieldInfo(annotation=Union[str, NoneType], required=False, default='auto'), 'ticks': FieldInfo(annotation=Union[list[Union[int, float]], NoneType], required=False)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo].

This replaces Model.__fields__ from Pydantic V1.

shrink: Optional[float]

spacing: Optional[str]

ticklabels: Optional[list[str]]

ticklocation: Optional[str]

ticks: Optional[list[Union[int, float]]]

classmethod validate_extend(v)

Validate extend option.

classmethod validate_extendfrac(v)

Validate extend fraction.

classmethod validate_extendrect(v)

Validate extend rectangle option.

classmethod validate_label(v)

Validate label as string.

class pycolorbar.settings.colorbar_validator.ColormapSettings(*, name: Union[str, list[str]], n: Optional[Union[int, list[int]]] = None, bad_color: Optional[Union[str, list, tuple]] = None, bad_alpha: Optional[float] = None, over_color: Optional[Union[str, list, tuple]] = None, over_alpha: Optional[float] = None, under_color: Optional[Union[str, list, tuple]] = None, under_alpha: Optional[float] = None)

Bases: BaseModel

Pydantic model for colormap settings.

bad_alpha: Optional[float]

bad_color: Optional[Union[str, list, tuple]]

model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[dict[str, FieldInfo]] = {'bad_alpha': FieldInfo(annotation=Union[float, NoneType], required=False), 'bad_color': FieldInfo(annotation=Union[str, list, tuple, NoneType], required=False), 'n': FieldInfo(annotation=Union[int, list[int], NoneType], required=False), 'name': FieldInfo(annotation=Union[str, list[str]], required=True), 'over_alpha': FieldInfo(annotation=Union[float, NoneType], required=False), 'over_color': FieldInfo(annotation=Union[str, list, tuple, NoneType], required=False), 'under_alpha': FieldInfo(annotation=Union[float, NoneType], required=False), 'under_color': FieldInfo(annotation=Union[str, list, tuple, NoneType], required=False)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo].

This replaces Model.__fields__ from Pydantic V1.

n: Optional[Union[int, list[int]]]

name: Union[str, list[str]]

over_alpha: Optional[float]

over_color: Optional[Union[str, list, tuple]]

under_alpha: Optional[float]

under_color: Optional[Union[str, list, tuple]]

classmethod validate_bad_alpha(v)

Validate bad_alpha values.

classmethod validate_colors(v)

Validate colors values.

classmethod validate_n(v, values)

Validate n values.

classmethod validate_name(v)

Validate colormap name.

Check if colormap name a registered matplotlib or pycolorbar colormap.

class pycolorbar.settings.colorbar_validator.LogNormSettings(*, vmin: Optional[float] = None, vmax: Optional[float] = None, clip: Optional[bool] = False)

Bases: BaseModel

Pydantic model for LogNorm settings.

classmethod check_valid_args(values)

Check for no excess parameters in LogNorm.

classmethod check_vmin_vmax(values)

Check vmin and vmax for LogNorm.

clip: Optional[bool]

model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[dict[str, FieldInfo]] = {'clip': FieldInfo(annotation=Union[bool, NoneType], required=False, default=False), 'vmax': FieldInfo(annotation=Union[float, NoneType], required=False), 'vmin': FieldInfo(annotation=Union[float, NoneType], required=False)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo].

This replaces Model.__fields__ from Pydantic V1.

classmethod validate_clip(v)

Validate clip option for LogNorm.

vmax: Optional[float]

vmin: Optional[float]

class pycolorbar.settings.colorbar_validator.NoNormSettings(*, vmin: Optional[float] = None, vmax: Optional[float] = None, clip: Optional[bool] = False)

Bases: BaseModel

Pydanctic model for NoNorm settings.

classmethod check_valid_args(values)

Check for no excess parameters in NoNorm.

classmethod check_vmin_vmax(values)

Check vmin and vmax for NoNorm.

clip: Optional[bool]

model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[dict[str, FieldInfo]] = {'clip': FieldInfo(annotation=Union[bool, NoneType], required=False, default=False), 'vmax': FieldInfo(annotation=Union[float, NoneType], required=False), 'vmin': FieldInfo(annotation=Union[float, NoneType], required=False)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo].

This replaces Model.__fields__ from Pydantic V1.

classmethod validate_clip(v)

Validate clip option for NoNorm.

vmax: Optional[float]

vmin: Optional[float]

class pycolorbar.settings.colorbar_validator.NormalizeSettings(*, vmin: Optional[float] = None, vmax: Optional[float] = None, clip: Optional[bool] = False)

Bases: BaseModel

Pydanctic model for Normalize settings.

classmethod check_valid_args(values)

Check for no excess parameters in Normalize.

classmethod check_vmin_vmax(values)

Check vmin and vmax for Normalize.

clip: Optional[bool]

model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[dict[str, FieldInfo]] = {'clip': FieldInfo(annotation=Union[bool, NoneType], required=False, default=False), 'vmax': FieldInfo(annotation=Union[float, NoneType], required=False), 'vmin': FieldInfo(annotation=Union[float, NoneType], required=False)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo].

This replaces Model.__fields__ from Pydantic V1.

classmethod validate_clip(v)

Validate clip option for Normalize.

vmax: Optional[float]

vmin: Optional[float]

class pycolorbar.settings.colorbar_validator.PowerNormSettings(*, gamma: float, vmin: Optional[float] = None, vmax: Optional[float] = None, clip: Optional[bool] = False)

Bases: BaseModel

Pydantic model for PowerNorm settings.

classmethod check_valid_args(values)

Check for no excess parameters in PowerNorm.

classmethod check_vmin_vmax(values)

Check vmin and vmax for PowerNorm.

clip: Optional[bool]

gamma: float

model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[dict[str, FieldInfo]] = {'clip': FieldInfo(annotation=Union[bool, NoneType], required=False, default=False), 'gamma': FieldInfo(annotation=float, required=True), 'vmax': FieldInfo(annotation=Union[float, NoneType], required=False), 'vmin': FieldInfo(annotation=Union[float, NoneType], required=False)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo].

This replaces Model.__fields__ from Pydantic V1.

classmethod validate_clip(v)

Validate clip option for PowerNorm.

classmethod validate_gamma(v)

Validate gamma for PowerNorm.

vmax: Optional[float]

vmin: Optional[float]

class pycolorbar.settings.colorbar_validator.SymLogNormSettings(*, linthresh: float, linscale: Optional[float] = 1.0, base: Optional[float] = 10, vmin: Optional[float] = None, vmax: Optional[float] = None, clip: Optional[bool] = False)

Bases: BaseModel

Pydanctic model for SymLogNorm settings.

base: Optional[float]

classmethod check_valid_args(values)

Check for no excess parameters in SymLogNorm.

classmethod check_vmin_vmax(values)

Check vmin and vmax for SymLogNorm.

clip: Optional[bool]

linscale: Optional[float]

linthresh: float

model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[dict[str, FieldInfo]] = {'base': FieldInfo(annotation=Union[float, NoneType], required=False, default=10), 'clip': FieldInfo(annotation=Union[bool, NoneType], required=False, default=False), 'linscale': FieldInfo(annotation=Union[float, NoneType], required=False, default=1.0), 'linthresh': FieldInfo(annotation=float, required=True), 'vmax': FieldInfo(annotation=Union[float, NoneType], required=False), 'vmin': FieldInfo(annotation=Union[float, NoneType], required=False)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo].

This replaces Model.__fields__ from Pydantic V1.

classmethod validate_clip(v)

Validate clip option for SymLogNorm.

classmethod validate_linscale_base(v, field)

Validate linscale and base for SymLogNorm.

classmethod validate_linthresh(v)

Validate linthresh for SymLogNorm.

vmax: Optional[float]

vmin: Optional[float]

class pycolorbar.settings.colorbar_validator.TwoSlopeNormSettings(*, vcenter: float, vmin: Optional[float] = None, vmax: Optional[float] = None)

Bases: BaseModel

Pydantic model for TwoSlopeNorm settings.

classmethod check_valid_args(values)

Check for no excess parameters in TwoSlopeNorm.

classmethod check_vmin_vcenter_vmax(values)

Check vmin`, ``vcenter, and vmax for TwoSlopeNorm.

model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[dict[str, FieldInfo]] = {'vcenter': FieldInfo(annotation=float, required=True), 'vmax': FieldInfo(annotation=Union[float, NoneType], required=False), 'vmin': FieldInfo(annotation=Union[float, NoneType], required=False)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo].

This replaces Model.__fields__ from Pydantic V1.

classmethod validate_vcenter(v)

Validate vcenter for TwoSlopeNorm.

vcenter: float

vmax: Optional[float]

vmin: Optional[float]

pycolorbar.settings.colorbar_validator.check_norm_settings(norm_settings)

Validate norm settings.

pycolorbar.settings.colorbar_validator.resolve_colorbar_reference(cbar_dict, name, checked_references=None)

Resolve a colorbar reference in a colorbar dictionary.

pycolorbar.settings.colorbar_validator.validate_cbar_dict(cbar_dict: dict, name: str, resolve_reference=False)

Validate a colorbar dictionary.

pycolorbar.settings.colorbar_visualization module

Define functions to visualize univariate colorbars.

pycolorbar.settings.colorbar_visualization.plot_colorbar(plot_kwargs, cbar_kwargs, ax=None, subplot_size=(6, 1))

Plot a single colorbar.

pycolorbar.settings.colorbar_visualization.plot_colorbars(list_args, cols=None, subplot_size=None, dpi=200)

Plot multiple colorbars in a single figure.

pycolorbar.settings.colorbar_visualization.show_colorbar(name=None, user_plot_kwargs=None, user_cbar_kwargs=None, fig_size=(6, 1))

Show a single pycolorbar colorbar.

pycolorbar.settings.colorbar_visualization.show_colorbars(category=None, exclude_referenced=True, subplot_size=None)

Show pycolorbar colorbars.

pycolorbar.settings.colormap_io module

Define functions to read and write colormap YAML files.

pycolorbar.settings.colormap_io.read_cmap_dict(filepath, decode=True, validate=True)

Read a pycolorbar colormap YAML file.

By default, the colormap YAML file are validated at read-time. Set validate=False to not validate the dictionary at read-time.

pycolorbar.settings.colormap_io.write_cmap_dict(cmap_dict, filepath, force=False, encode=True, validate=True)

Write a pycolorbar colormap YAML file.

By default, the colormap YAML file are validated before writing it. It assumes that the specified colors are in the internal representation (decoded).

pycolorbar.settings.colormap_registry module

Define the register of univiariate colormaps.

class pycolorbar.settings.colormap_registry.ColormapRegistry

Bases: object

A singleton class to manage colormap registrations.

This class provides methods to register colormaps, remove them, retrieve colormap file paths, and add new colormaps to a temporary directory for further processing.

_instance

The singleton instance of the ColormapRegistry.

Type

ColormapRegistry

registry

The dictionary holding the registered colormap names and their corresponding configuration YAML file paths.

Type

dict

tmp_dir

The path of a temporary directory where colormap YAML files are stored when specifying a colormap on-the-fly with add_cmap_dict(cmap_dict).

Type

str

add_cmap_dict(cmap_dict: dict, name: str, verbose: bool = True, force=True)

Add a colormap to the registry by providing a colormap dictionary and the colormap name.

A temporary file YAML configuration file is created in ColormapRegistry.tmp_dir.

Parameters

• cmap_dict (dict) – The colormap dictionary containing the colormap’s configuration.

• name (str) – The name of the colormap.

• verbose (bool, optional) – If True, the method will print a warning when overwriting an existing colormap. The default is True.

• force (bool, optional) – If True, it allow to overwrites an existing colormap. The default is True. If False, it raise an error if attempting to overwrite an existing colormap.

Notes

If a colormap with the same name already exists, it will be overwritten, and a warning will be printed. The YAML file for the colormap is stored in a temporary directory.

available(category=None, include_reversed=False)

List the name of available colormaps for a specific category.

get_cmap(name: str)

Retrieve the colormap.

Parameters

name (str) – The name of the colormap.

Returns

The matplotlib colormap.

Return type

matplotlib.Colormap

Raises

ValueError – If the colormap configuration is invalid or cannot be read.

get_cmap_dict(name: str)

Retrieve the validated colormap dictionary of a registered colormap.

Parameters

name (str) – The name of the colormap.

Returns

The validated colormap dictionary.

Return type

dict

Raises

ValueError – If the colormap configuration is invalid or cannot be read.

get_cmap_filepath(name: str)

Retrieve the colormap’s YAML configuration file path.

Parameters

name (str) – The name of the colormap.

Returns

The colormap’s YAML configuration file path.

Return type

str

Raises

ValueError – If the colormap with the specified name is not registered.

classmethod get_instance()

Return the singleton instance of the ColormapRegistry.

property names

List the names of all registered colormaps.

register(filepath: str, verbose: bool = True, force: bool = True)

Register a colormap by its name and file path.

Parameters

• filepath (str) – The file path where the colormap’s YAML file is located. The name of the colormap correspond to the name of the YAML file !

• verbose (bool, optional) – If True, the method will print a warning when overwriting an existing colormap. The default is True.

• force (bool, optional) – If True, it allow to overwrites an existing colormap. The default is True. If False, it raise an error if attempting to overwrite an existing colormap.

Notes

If a colormap with the same name already exists, it will be overwritten, and a warning will be printed. The validity of the colormap’s YAML file is not validated !

reset()

Clears the entire colormap registry.

show_colormap(name)

Display a colormap.

show_colormaps(category=None, include_reversed=False, subplot_size=None)

Display available colormaps (optionally of a specific category).

to_yaml(name, filepath, force=False)

Write the colormap configuration to a YAML file.

unregister(name: str)

Remove a colormap from the registry.

Parameters

name (str) – The name of the colormap to remove.

Raises

ValueError – If the colormap with the specified name is not registered.

validate(name: Optional[str] = None)

Validate the registered colormaps. If a specific name is provided, only that colormap is validated.

Parameters

name (str, optional) – The name of a specific colormap to validate. If None, all registered colormaps are validated.

Raises

ValueError – If any of the validated colormaps have invalid configurations.

Notes

Invalid colormap configurations are reported.

pycolorbar.settings.colormap_registry.available_colormaps(category=None, include_reversed=False)

Return a list with the name of registered colormaps.

Parameters

• category (str, optional) – The name of an optional category to subset the list of registered colormaps. In the colormap YAML file, the auxiliary/category field enable to specify the relevant categories of the colormap. Common categories are ‘diverging’, ‘cyclic’, ‘sequential’, ‘categorical’, ‘qualitative’, ‘perceptual’. If None (the default), returns all available colormaps.

• include_reversed (bool, optional) – Whether to include also the name of the reversed colormap suffixed by _r. The default is False.

Returns

names – List of registered colormaps.

Return type

str

pycolorbar.settings.colormap_registry.check_colormap_archive()

Check the pycolorbar colormap archive.

pycolorbar.settings.colormap_registry.get_cmap(name: Optional[str] = None, lut: Optional[int] = None)

Get a colormap instance.

Parameters

• name (str) – The name of a colormap known to pycolorbar or Matplotlib. If the name ends with the suffix _r, the colormap is reversed.

• lut (int or None) – If not None (the default), the colormap will be resampled to have lut entries in the lookup table. If the name ends with the suffix _r, the resampling is done after reversing the colormap.

Return type

Colormap

pycolorbar.settings.colormap_registry.get_cmap_dict(name)

Retrieve the validated colormap dictionary of a registered colormap.

Parameters

name (str) – The name of the colormap.

Returns

The validated colormap dictionary.

Return type

dict

Raises

Exception – If the colormap configuration is invalid or cannot be read.

pycolorbar.settings.colormap_registry.register_colormap(filepath: str, verbose: bool = True, force: bool = True)

Register a single colormap YAML file.

Parameters

• filepath (str) – The file path where the colormap’s YAML file is located. The name of the colormap correspond to the name of the YAML file !

• force (bool, optional) – If True, it allow to overwrites an existing colormap. The default is True. If False, it raise an error if attempting to overwrite an existing colormap.

• verbose (bool, optional) – If True, the method will print a warning when overwriting an existing colormap. The default is True.

Raises

ValueError – If the specified colormap YAML file is not available in the directory or if trying to register an already registered colormap and force=False.

pycolorbar.settings.colormap_registry.register_colormaps(directory: str, name: Optional[str] = None, verbose: bool = True, force: bool = True)

Register all colormap YAML files present in the specified directory (if name=None).

This function assumes that all YAML files present in the directory are valid pycolorbar colormaps configuration files.

Parameters

• directory (str) – The directory where colormap YAML files are located.

• name (str, optional) – The specific name of a colormap to register. If None, all colormaps in the directory are registered.

• force (bool, optional) – If True, it allow to overwrites existing colormaps. The default is True. If False, it raise an error if attempting to overwrite an existing colormap.

• verbose (bool, optional) – If True, the method will print a warning when overwriting existing colormaps. The default is True.

pycolorbar.settings.colormap_utility module

Define functions to build colormaps in multiple color spaces.

pycolorbar.settings.colormap_utility.convert_colors(colors, color_space)

Convert colors to the RGB color space.

pycolorbar.settings.colormap_utility.create_cmap(cmap_dict, name)

Create a colormap from the colormap dictionary.

pycolorbar.settings.colormap_validator module

Implementation of pydantic validator for univariate colormap YAML files.

class pycolorbar.settings.colormap_validator.ColormapValidator(*, colors_decoded: Optional[bool] = True, colormap_type: str, color_space: str, color_palette: Optional[Union[ndarray, list]] = None, segmentdata: Optional[dict] = None, n: Optional[float] = None, auxiliary: Optional[dict] = {})

Bases: BaseModel

A validator for colormap configurations using Pydantic.

Validates the fields of a colormap configuration, including the type of colormap, the color space, the colors themselves, and the alpha transparency settings.

colors_decoded

If True, assumes that the colors have been already decoded (internal representation). If False, assumes that the colors have not been decoded (external representation). The default is True.

Type

bool

colormap_type

The type of the colormap (e.g., ListedColormap, LinearSegmentedColormap).

Type

str

color_space

The color space of the colormap (e.g., rgb, hsv).

Type

str

color_palette

The array of colors defined for the colormap.

Type

np.ndarray

validate_colormap_type(cls, v):

Validates the colormap_type field.

validate_color_space(cls, v):

Validates the color_space field.

validate_colors(cls, v, values):

Validates the colors field.

validate_segmentdata(cls, v, values)

Validates the segmentdata field.

auxiliary: Optional[dict]

color_palette: Optional[Union[ndarray, list]]

color_space: str

colormap_type: str

colors_decoded: Optional[bool]

model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[dict[str, FieldInfo]] = {'auxiliary': FieldInfo(annotation=Union[dict, NoneType], required=False, default={}), 'color_palette': FieldInfo(annotation=Union[ndarray, list, NoneType], required=False), 'color_space': FieldInfo(annotation=str, required=True), 'colormap_type': FieldInfo(annotation=str, required=True), 'colors_decoded': FieldInfo(annotation=Union[bool, NoneType], required=False, default=True), 'n': FieldInfo(annotation=Union[float, NoneType], required=False), 'segmentdata': FieldInfo(annotation=Union[dict, NoneType], required=False)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo].

This replaces Model.__fields__ from Pydantic V1.

n: Optional[float]

segmentdata: Optional[dict]

classmethod validate_color_palette(v, values)

Validate the color_palette array.

classmethod validate_color_space(v)

Validate the color_space field.

classmethod validate_colormap_type(v)

Validate the colormap_type field.

classmethod validate_colors_decoded(v)

Validate the colors_decoded flag.

classmethod validate_segmentdata(v, values)

Validate the segmentdata dictionary.

pycolorbar.settings.colormap_validator.check_color_space(color_space)

Check color space validity.

pycolorbar.settings.colormap_validator.get_valid_color_space()

Get list of valid color spaces.

pycolorbar.settings.colormap_validator.is_monotonically_increasing(values)

Check if a list of values is monotonically increasing.

pycolorbar.settings.colormap_validator.validate_cmap_dict(cmap_dict: dict, decoded_colors=True)

Check the validity of a colormap dictionary.

Parameters

• cmap_dict (dict) – Colormap dictionary.

• decoded_colors (bool, optional) – Whether the colors are decoded (internal representation) or not. The default is True.

Returns

cmap_dict – Validated colormap dictionary.

Return type

dict

pycolorbar.settings.colormap_validator.validate_colors_values(colors, color_space, decoded_colors=True)

Validates the colors array based on the specified color space.

Parameters

• colors (np.ndarray) – The array of colors to validate.

• color_space (str) – The color space of the colors array (e.g., “hex”, “rgb”, “rgba”, etc.).

• decoded_colors (bool) – If True, assumes that the colors are decoded (internal representation). If False, assumes that the colors are not decoded (external representation).

Raises

ValueError – If the color_space is not supported or if the colors array fails validation checks for the specified color space.

pycolorbar.settings.colormap_validator.validate_hex_colors(colors: ndarray) → bool

Validates the array of HEX colors.

Parameters

colors (np.ndarray) – The array of colors to validate.

Raises

ValueError – If the colors array is not 1-D or if any color is not a valid hex string.

pycolorbar.settings.colormap_validator.validate_name_colors(colors: ndarray) → bool

Validates the array of named colors.

For more info on named colors, see https://matplotlib.org/stable/gallery/color/named_colors.html

Parameters

colors (np.ndarray) – The array of colors to validate.

Raises

ValueError – If the colors array is not 1-D, if color values are not strings, or if any color name is not a valid named color.

pycolorbar.settings.colormap_visualization module

Define functions to visualize univariate colormaps.

pycolorbar.settings.colormap_visualization.plot_colormap(cmap, dpi=200)

Plot a single colormap.

pycolorbar.settings.colormap_visualization.plot_colormaps(cmaps, cols=None, subplot_size=None, dpi=200)

Plot a list of colormaps.

pycolorbar.settings.colormap_visualization.show_colormap(cmap)

Show a registered colormap.

pycolorbar.settings.colormap_visualization.show_colormaps(category=None, include_reversed=False, cols=None, subplot_size=None)

Show all registered colormaps.

pycolorbar.settings.matplotlib_kwargs module

Define functions to retrieve the plotting arguments.

pycolorbar.settings.matplotlib_kwargs.create_category_norm(labels, first_value=0)

Define a BoundaryNorm that deal with categorical data.

pycolorbar.settings.matplotlib_kwargs.get_cmap(cbar_dict)

Retrieve the colormap from a validated colorbar configuration dictionary.

pycolorbar.settings.matplotlib_kwargs.get_default_cbar_kwargs()

Define the default colorbar kwargs.

pycolorbar.settings.matplotlib_kwargs.get_norm(norm_settings)

Define the norm instance from a validated cbar_dict.

pycolorbar.settings.matplotlib_kwargs.get_norm_function(name)

Retrieve the norm function.

pycolorbar.settings.matplotlib_kwargs.get_plot_cbar_kwargs(cbar_dict)

Retrieve the plot and colorbar kwargs from a validated colorbar dictionary.

pycolorbar.settings.matplotlib_kwargs.update_plot_cbar_kwargs(default_plot_kwargs, default_cbar_kwargs, user_plot_kwargs=None, user_cbar_kwargs=None)

Update the default plot and colorbar kwargs with user-provided arguments.

pycolorbar.settings.utils module

Utility functions for settings module.

pycolorbar.settings.utils.get_auxiliary_categories(dictionary)

Retrieve list of categories keys from a cmap or colorbar dictionary.

Module contents