#!/usr/bin/env python3

"""

The constructor functions used to build class instances from simple shorthand arguments.

"""

# NOTE: These functions used to be in separate files like crs.py and

# ticker.py but makes more sense to group them together to ensure usage is

# consistent and so online documentation is easier to understand. Also in

# future version classes will not be imported into top-level namespace. This

# change will be easier to do with all constructor functions in separate file.

# NOTE: Used to include the raw variable names that define string keys as

# part of documentation, but this is redundant and pollutes the namespace.

# User should just inspect docstrings, use trial-error, or see online tables.

import copy

import os

import re

from functools import partial

from numbers import Number

from typing import Callable, Iterator, TypeVar

import cycler

import matplotlib.colors as mcolors

import matplotlib.dates as mdates

import matplotlib.projections.polar as mpolar

import matplotlib.scale as mscale

import matplotlib.ticker as mticker

import numpy as np

from . import colors as pcolors

from . import proj as pproj

from . import scale as pscale

from . import ticker as pticker

from .config import rc

from .internals import (

_not_none,

_pop_props,

_version_cartopy,

_version_mpl,

ic, # noqa: F401

warnings,

)

from .utils import get_colors, to_hex, to_rgba

try:

from mpl_toolkits.basemap import Basemap

except ImportError:

Basemap = object

try:

import cartopy.crs as ccrs

from cartopy.crs import Projection

except ModuleNotFoundError:

ccrs = None

Projection = object

__all__ = [

"Proj",

"Locator",

"Formatter",

"Scale",

"Colormap",

"Norm",

"Cycle",

"Colors", # deprecated

]

# Color cycle constants

# TODO: Also automatically truncate the 'bright' end of colormaps

# when building color cycles from colormaps? Or add simple option.

DEFAULT_CYCLE_SAMPLES = 10

DEFAULT_CYCLE_LUMINANCE = 90

_RegistryValue = TypeVar("_RegistryValue")

class _RefreshingRegistry(dict[str, _RegistryValue]):

"""

Dictionary-like registry that rebuilds itself before reads.

This keeps constructor registries aligned with modules that may be reloaded

in-place during tests or interactive use.

"""

def __init__(self, factory: Callable[[], dict[str, _RegistryValue]]) -> None:

self._factory = factory

super().__init__(factory())

def _refresh(self) -> None:

super().clear()

super().update(self._factory())

def __contains__(self, key: object) -> bool:

self._refresh()

return super().__contains__(key)

def __getitem__(self, key: str) -> _RegistryValue:

self._refresh()

return super().__getitem__(key)

def __iter__(self) -> Iterator[str]:

self._refresh()

return super().__iter__()

def __len__(self) -> int:

self._refresh()

return super().__len__()

def get(

self, key: str, default: _RegistryValue | None = None

) -> _RegistryValue | None:

self._refresh()

return super().get(key, default)

def items(self): # type: ignore[override]

self._refresh()

return super().items()

def keys(self): # type: ignore[override]

self._refresh()

return super().keys()

def values(self): # type: ignore[override]

self._refresh()

return super().values()

def copy(self) -> dict[str, _RegistryValue]:

self._refresh()

return dict(super().items())

def _build_norm_registry() -> dict[str, type[mcolors.Normalize]]:

registry: dict[str, type[mcolors.Normalize]] = {

"none": mcolors.NoNorm,

"null": mcolors.NoNorm,

"div": pcolors.DivergingNorm,

"diverging": pcolors.DivergingNorm,

"segmented": pcolors.SegmentedNorm,

"segments": pcolors.SegmentedNorm,

"log": mcolors.LogNorm,

"linear": mcolors.Normalize,

"power": mcolors.PowerNorm,

"symlog": mcolors.SymLogNorm,

}

if hasattr(mcolors, "TwoSlopeNorm"):

registry["twoslope"] = mcolors.TwoSlopeNorm

return registry

def _build_locator_registry() -> dict[str, object]:

registry = {

"none": mticker.NullLocator,

"null": mticker.NullLocator,

"auto": mticker.AutoLocator,

"log": mticker.LogLocator,

"maxn": mticker.MaxNLocator,

"linear": mticker.LinearLocator,

"multiple": mticker.MultipleLocator,

"fixed": mticker.FixedLocator,

"index": pticker.IndexLocator,

"discrete": pticker.DiscreteLocator,

"discreteminor": partial(pticker.DiscreteLocator, minor=True),

"symlog": mticker.SymmetricalLogLocator,

"logit": mticker.LogitLocator,

"minor": mticker.AutoMinorLocator,

"date": mdates.AutoDateLocator,

"microsecond": mdates.MicrosecondLocator,

"second": mdates.SecondLocator,

"minute": mdates.MinuteLocator,

"hour": mdates.HourLocator,

"day": mdates.DayLocator,

"weekday": mdates.WeekdayLocator,

"month": mdates.MonthLocator,

"year": mdates.YearLocator,

"lon": partial(pticker.LongitudeLocator, dms=False),

"lat": partial(pticker.LatitudeLocator, dms=False),

"deglon": partial(pticker.LongitudeLocator, dms=False),

"deglat": partial(pticker.LatitudeLocator, dms=False),

}

if hasattr(mpolar, "ThetaLocator"):

registry["theta"] = mpolar.ThetaLocator

if _version_cartopy >= "0.18":

registry["dms"] = partial(pticker.DegreeLocator, dms=True)

registry["dmslon"] = partial(pticker.LongitudeLocator, dms=True)

registry["dmslat"] = partial(pticker.LatitudeLocator, dms=True)

return registry

def _build_formatter_registry() -> dict[str, object]:

registry = { # note default LogFormatter uses ugly e+00 notation

"none": mticker.NullFormatter,

"null": mticker.NullFormatter,

"auto": pticker.AutoFormatter,

"date": mdates.AutoDateFormatter,

"scalar": mticker.ScalarFormatter,

"simple": pticker.SimpleFormatter,

"fixed": mticker.FixedLocator,

"index": pticker.IndexFormatter,

"sci": pticker.SciFormatter,

"sigfig": pticker.SigFigFormatter,

"frac": pticker.FracFormatter,

"func": mticker.FuncFormatter,

"strmethod": mticker.StrMethodFormatter,

"formatstr": mticker.FormatStrFormatter,

"datestr": mdates.DateFormatter,

"log": mticker.LogFormatterSciNotation,

"logit": mticker.LogitFormatter,

"eng": mticker.EngFormatter,

"percent": mticker.PercentFormatter,

"e": partial(pticker.FracFormatter, symbol=r"$e$", number=np.e),

"pi": partial(pticker.FracFormatter, symbol=r"$\pi$", number=np.pi),

"tau": partial(pticker.FracFormatter, symbol=r"$\tau$", number=2 * np.pi),

"lat": partial(pticker.SimpleFormatter, negpos="SN"),

"lon": partial(pticker.SimpleFormatter, negpos="WE", wraprange=(-180, 180)),

"deg": partial(pticker.SimpleFormatter, suffix="\N{DEGREE SIGN}"),

"deglat": partial(

pticker.SimpleFormatter, suffix="\N{DEGREE SIGN}", negpos="SN"

),

"deglon": partial(

pticker.SimpleFormatter,

suffix="\N{DEGREE SIGN}",

negpos="WE",

wraprange=(-180, 180),

),

"math": mticker.LogFormatterMathtext,

}

if hasattr(mpolar, "ThetaFormatter"):

registry["theta"] = mpolar.ThetaFormatter

if hasattr(mdates, "ConciseDateFormatter"):

registry["concise"] = mdates.ConciseDateFormatter

if _version_cartopy >= "0.18":

registry["dms"] = partial(pticker.DegreeFormatter, dms=True)

registry["dmslon"] = partial(pticker.LongitudeFormatter, dms=True)

registry["dmslat"] = partial(pticker.LatitudeFormatter, dms=True)

return registry

# Normalizer registry

NORMS = _RefreshingRegistry(_build_norm_registry)

# Locator registry

# NOTE: Will raise error when you try to use degree-minute-second

# locators with cartopy < 0.18.

LOCATORS = _RefreshingRegistry(_build_locator_registry)

# Formatter registry

# NOTE: Critical to use SimpleFormatter for cardinal formatters rather than

# AutoFormatter because latter fails with Basemap formatting.

# NOTE: Define cartopy longitude/latitude formatters with dms=True because that

# is their distinguishing feature relative to ultraplot formatter.

# NOTE: Will raise error when you try to use degree-minute-second

# formatters with cartopy < 0.18.

FORMATTERS = _RefreshingRegistry(_build_formatter_registry)

# Scale registry and presets

SCALES = mscale._scale_mapping

SCALES_PRESETS = {

"quadratic": (

"power",

2,

),

"cubic": (

"power",

3,

),

"quartic": (

"power",

4,

),

"height": ("exp", np.e, -1 / 7, 1013.25, True),

"pressure": ("exp", np.e, -1 / 7, 1013.25, False),

"db": ("exp", 10, 1, 0.1, True),

"idb": ("exp", 10, 1, 0.1, False),

"np": ("exp", np.e, 1, 1, True),

"inp": ("exp", np.e, 1, 1, False),

}

mscale.register_scale(pscale.CutoffScale)

mscale.register_scale(pscale.ExpScale)

mscale.register_scale(pscale.FuncScale)

mscale.register_scale(pscale.InverseScale)

mscale.register_scale(pscale.LogScale)

mscale.register_scale(pscale.LinearScale)

mscale.register_scale(pscale.LogitScale)

mscale.register_scale(pscale.MercatorLatitudeScale)

mscale.register_scale(pscale.PowerScale)

mscale.register_scale(pscale.SineLatitudeScale)

mscale.register_scale(pscale.SymmetricalLogScale)

# Cartopy projection registry and basemap default keyword args

# NOTE: Normally basemap raises error if you omit keyword args

PROJ_DEFAULTS = {

"geos": {"lon_0": 0},

"eck4": {"lon_0": 0},

"moll": {"lon_0": 0},

"hammer": {"lon_0": 0},

"kav7": {"lon_0": 0},

"sinu": {"lon_0": 0},

"vandg": {"lon_0": 0},

"mbtfpq": {"lon_0": 0},

"robin": {"lon_0": 0},

"ortho": {"lon_0": 0, "lat_0": 0},

"nsper": {"lon_0": 0, "lat_0": 0},

"aea": {"lon_0": 0, "lat_0": 90, "width": 15000e3, "height": 15000e3},

"eqdc": {"lon_0": 0, "lat_0": 90, "width": 15000e3, "height": 15000e3},

"cass": {"lon_0": 0, "lat_0": 90, "width": 15000e3, "height": 15000e3},

"gnom": {"lon_0": 0, "lat_0": 90, "width": 15000e3, "height": 15000e3},

"poly": {"lon_0": 0, "lat_0": 0, "width": 10000e3, "height": 10000e3},

"npaeqd": {"lon_0": 0, "boundinglat": 10}, # NOTE: everything breaks if you

"nplaea": {"lon_0": 0, "boundinglat": 10}, # try to set boundinglat to zero

"npstere": {"lon_0": 0, "boundinglat": 10},

"spaeqd": {"lon_0": 0, "boundinglat": -10},

"splaea": {"lon_0": 0, "boundinglat": -10},

"spstere": {"lon_0": 0, "boundinglat": -10},

"lcc": {

"lon_0": 0,

"lat_0": 40,

"lat_1": 35,

"lat_2": 45, # use cartopy defaults

"width": 20000e3,

"height": 15000e3,

},

"tmerc": {"lon_0": 0, "lat_0": 0, "width": 10000e3, "height": 10000e3},

"merc": {

"llcrnrlat": -80,

"urcrnrlat": 84,

"llcrnrlon": -180,

"urcrnrlon": 180,

},

"omerc": {

"lat_0": 0,

"lon_0": 0,

"lat_1": -10,

"lat_2": 10,

"lon_1": 0,

"lon_2": 0,

"width": 10000e3,

"height": 10000e3,

},

}

if ccrs is None:

PROJS = {}

else:

PROJS = {

"aitoff": pproj.Aitoff,

"hammer": pproj.Hammer,

"kav7": pproj.KavrayskiyVII,

"wintri": pproj.WinkelTripel,

"npgnom": pproj.NorthPolarGnomonic,

"spgnom": pproj.SouthPolarGnomonic,

"npaeqd": pproj.NorthPolarAzimuthalEquidistant,

"spaeqd": pproj.SouthPolarAzimuthalEquidistant,

"nplaea": pproj.NorthPolarLambertAzimuthalEqualArea,

"splaea": pproj.SouthPolarLambertAzimuthalEqualArea,

}

PROJS_MISSING = {

"aea": "AlbersEqualArea",

"aeqd": "AzimuthalEquidistant",

"cyl": "PlateCarree", # only basemap name not matching PROJ

"eck1": "EckertI",

"eck2": "EckertII",

"eck3": "EckertIII",

"eck4": "EckertIV",

"eck5": "EckertV",

"eck6": "EckertVI",

"eqc": "PlateCarree", # actual PROJ name

"eqdc": "EquidistantConic",

"eqearth": "EqualEarth", # better looking Robinson; not in basemap

"euro": "EuroPP", # Europe; not in basemap or PROJ

"geos": "Geostationary",

"gnom": "Gnomonic",

"igh": "InterruptedGoodeHomolosine", # not in basemap

"laea": "LambertAzimuthalEqualArea",

"lcc": "LambertConformal",

"lcyl": "LambertCylindrical", # not in basemap or PROJ

"merc": "Mercator",

"mill": "Miller",

"moll": "Mollweide",

"npstere": "NorthPolarStereo", # np/sp stuff not in PROJ

"nsper": "NearsidePerspective",

"ortho": "Orthographic",

"osgb": "OSGB", # UK; not in basemap or PROJ

"osni": "OSNI", # Ireland; not in basemap or PROJ

"pcarree": "PlateCarree", # common alternate name

"robin": "Robinson",

"rotpole": "RotatedPole",

"sinu": "Sinusoidal",

"spstere": "SouthPolarStereo",

"stere": "Stereographic",

"tmerc": "TransverseMercator",

"utm": "UTM", # not in basemap

}

for _key, _cls in tuple(PROJS_MISSING.items()):

if hasattr(ccrs, _cls):

PROJS[_key] = getattr(ccrs, _cls)

del PROJS_MISSING[_key]

if PROJS_MISSING:

warnings._warn_ultraplot(

"The following cartopy projection(s) are unavailable: "

+ ", ".join(map(repr, PROJS_MISSING))

+ " . Please consider updating cartopy."

)

PROJS_TABLE = "The known cartopy projection classes are:\n" + "\n".join(

" " + key + " " * (max(map(len, PROJS)) - len(key) + 10) + cls.__name__

for key, cls in PROJS.items()

)

# Geographic feature properties

FEATURES_CARTOPY = { # positional arguments passed to NaturalEarthFeature

"land": ("physical", "land"),

"ocean": ("physical", "ocean"),

"lakes": ("physical", "lakes"),

"coast": ("physical", "coastline"),

"rivers": ("physical", "rivers_lake_centerlines"),

"borders": ("cultural", "admin_0_boundary_lines_land"),

"innerborders": ("cultural", "admin_1_states_provinces_lakes"),

}

FEATURES_BASEMAP = { # names of relevant basemap methods

"land": "fillcontinents",

"coast": "drawcoastlines",

"rivers": "drawrivers",

"borders": "drawcountries",

"innerborders": "drawstates",

}

# Resolution names

# NOTE: Maximum basemap resolutions are much finer than cartopy

RESOS_CARTOPY = {

"lo": "110m",

"med": "50m",

"hi": "10m",

"x-hi": "10m", # extra high

"xx-hi": "10m", # extra extra high

}

RESOS_BASEMAP = {

"lo": "c", # coarse

"med": "l",

"hi": "i", # intermediate

"x-hi": "h",

"xx-hi": "f", # fine

}

def _modify_colormap(cmap, *, cut, left, right, reverse, shift, alpha, samples):

"""

Modify colormap using a variety of methods.

"""

if cut is not None or left is not None or right is not None:

if isinstance(cmap, pcolors.DiscreteColormap):

if cut is not None:

warnings._warn_ultraplot(

"Invalid argument 'cut' for ListedColormap. Ignoring."

)

cmap = cmap.truncate(left=left, right=right)

else:

cmap = cmap.cut(cut, left=left, right=right)

if reverse:

cmap = cmap.reversed()

if shift is not None:

cmap = cmap.shifted(shift)

if alpha is not None:

cmap = cmap.copy(alpha=alpha)

if samples is not None:

if isinstance(cmap, pcolors.DiscreteColormap):

cmap = cmap.copy(N=samples)

else:

cmap = cmap.to_discrete(samples)

return cmap

@warnings._rename_kwargs(

"0.8.0", fade="saturation", shade="luminance", to_listed="discrete"

)

def Colormap(

*args,

name=None,

listmode="perceptual",

filemode="continuous",

discrete=False,

cycle=None,

save=False,

save_kw=None,

**kwargs,

):

"""

Generate, retrieve, modify, and/or merge instances of

:class:`~ultraplot.colors.PerceptualColormap`,

:class:`~ultraplot.colors.ContinuousColormap`, and

:class:`~ultraplot.colors.DiscreteColormap`.

Parameters

----------

*args : colormap-spec

Positional arguments that individually generate colormaps. If more

than one argument is passed, the resulting colormaps are *merged* with

`~ultraplot.colors.ContinuousColormap.append`

or `~ultraplot.colors.DiscreteColormap.append`.

The arguments are interpreted as follows:

* If a registered colormap name, that colormap instance is looked up.

If colormap instance is a native matplotlib colormap class, it is

converted to a ultraplot colormap class.

* If a filename string with valid extension, the colormap data

is loaded with `ultraplot.colors.ContinuousColormap.from_file` or

`ultraplot.colors.DiscreteColormap.from_file` depending on the value of

`filemode` (see below). Default behavior is to load a

:class:`~ultraplot.colors.ContinuousColormap`.

* If RGB tuple or color string, a :class:`~ultraplot.colors.PerceptualColormap`

is generated with `~ultraplot.colors.PerceptualColormap.from_color`.

If the string ends in ``'_r'``, the monochromatic map will be

*reversed*, i.e. will go from dark to light instead of light to dark.

* If sequence of RGB tuples or color strings, a

:class:`~ultraplot.colors.DiscreteColormap`, :class:`~ultraplot.colors.PerceptualColormap`,

or :class:`~ultraplot.colors.ContinuousColormap` is generated depending on

the value of `listmode` (see below). Default behavior is to generate a

:class:`~ultraplot.colors.PerceptualColormap`.

* If dictionary, a :class:`~ultraplot.colors.PerceptualColormap` is

generated with `~ultraplot.colors.PerceptualColormap.from_hsl`.

The dictionary should contain the keys ``'hue'``, ``'saturation'``,

``'luminance'``, and optionally ``'alpha'``, or their aliases (see below).

name : str, optional

Name under which the final colormap is registered. It can

then be reused by passing ``cmap='name'`` to plotting

functions. Names with leading underscores are ignored.

filemode : {'perceptual', 'continuous', 'discrete'}, optional

Controls how colormaps are generated when you input list(s) of colors.

The options are as follows:

* If ``'perceptual'`` or ``'continuous'``, a colormap is generated using

`~ultraplot.colors.ContinuousColormap.from_file`. The resulting

colormap may be a :class:`~ultraplot.colors.ContinuousColormap` or

:class:`~ultraplot.colors.PerceptualColormap` depending on the data file.

* If ``'discrete'``, a :class:`~ultraplot.colors.DiscreteColormap` is generated

using `~ultraplot.colors.ContinuousColormap.from_file`.

Default is ``'continuous'`` when calling `Colormap` directly and

``'discrete'`` when `Colormap` is called by `Cycle`.

listmode : {'perceptual', 'continuous', 'discrete'}, optional

Controls how colormaps are generated when you input sequence(s)

of colors. The options are as follows:

* If ``'perceptual'``, a :class:`~ultraplot.colors.PerceptualColormap`

is generated with `~ultraplot.colors.PerceptualColormap.from_list`.

* If ``'continuous'``, a :class:`~ultraplot.colors.ContinuousColormap` is

generated with `~ultraplot.colors.ContinuousColormap.from_list`.

* If ``'discrete'``, a :class:`~ultraplot.colors.DiscreteColormap` is generated

by simply passing the colors to the class.

Default is ``'perceptual'`` when calling `Colormap` directly and

``'discrete'`` when `Colormap` is called by `Cycle`.

samples : int or sequence of int, optional

For :class:`~ultraplot.colors.ContinuousColormap`\\ s, this is used to

generate :class:`~ultraplot.colors.DiscreteColormap`\\ s with

`~ultraplot.colors.ContinuousColormap.to_discrete`. For

:class:`~ultraplot.colors.DiscreteColormap`\\ s, this is used to updates the

number of colors in the cycle. If `samples` is integer, it applies

to the final *merged* colormap. If it is a sequence of integers,

it applies to each input colormap individually.

discrete : bool, optional

If ``True``, when the final colormap is a

:class:`~ultraplot.colors.DiscreteColormap`, we leave it alone, but when it is a

:class:`~ultraplot.colors.ContinuousColormap`, we always call

`~ultraplot.colors.ContinuousColormap.to_discrete` with a

default `samples` value of ``10``. This argument is not

necessary if you provide the `samples` argument.

left, right : float or sequence of float, optional

Truncate the left or right edges of the colormap.

Passed to :method:`~ultraplot.colors.ContinuousColormap.truncate`.

If float, these apply to the final *merged* colormap. If sequence

of float, these apply to each input colormap individually.

cut : float or sequence of float, optional

Cut out the center of the colormap. Passed to

`~ultraplot.colors.ContinuousColormap.cut`. If float,

this applies to the final *merged* colormap. If sequence of

float, these apply to each input colormap individually.

reverse : bool or sequence of bool, optional

Reverse the colormap. Passed to

`~ultraplot.colors.ContinuousColormap.reversed`. If

float, this applies to the final *merged* colormap. If

sequence of float, these apply to each input colormap individually.

shift : float or sequence of float, optional

Cyclically shift the colormap.

Passed to :property:`~ultraplot.colors.ContinuousColormap.shifted`.

If float, this applies to the final *merged* colormap. If sequence

of float, these apply to each input colormap individually.

a

Shorthand for `alpha`.

alpha : float or color-spec or sequence, optional

The opacity of the colormap or the opacity gradation. Passed to

`ultraplot.colors.ContinuousColormap.set_alpha`

or `ultraplot.colors.DiscreteColormap.set_alpha`. If float, this applies

to the final *merged* colormap. If sequence of float, these apply to

each colormap individually.

h, s, l, c

Shorthands for `hue`, `luminance`, `saturation`, and `chroma`.

hue, saturation, luminance : float or color-spec or sequence, optional

The channel value(s) used to generate colormaps with

`~ultraplot.colors.PerceptualColormap.from_hsl` and

`~ultraplot.colors.PerceptualColormap.from_color`.

* If you provided no positional arguments, these are used to create

an arbitrary perceptually uniform colormap with

`~ultraplot.colors.PerceptualColormap.from_hsl`. This

is an alternative to passing a dictionary as a positional argument

with `hue`, `saturation`, and `luminance` as dictionary keys (see `args`).

* If you did provide positional arguments, and any of them are

color specifications, these control the look of monochromatic colormaps

generated with `~ultraplot.colors.PerceptualColormap.from_color`.

To use different values for each colormap, pass a sequence of floats

instead of a single float. Note the default `luminance` is ``90`` if

`discrete` is ``True`` and ``100`` otherwise.

chroma

Alias for `saturation`.

cycle : str, optional

The registered cycle name used to interpret color strings like ``'C0'``

and ``'C2'``. Default is from the active property :rcraw:`cycle`. This lets

you make monochromatic colormaps using colors selected from arbitrary cycles.

save : bool, optional

Whether to call the colormap/color cycle save method, i.e.

`ultraplot.colors.ContinuousColormap.save` or

`ultraplot.colors.DiscreteColormap.save`.

save_kw : dict-like, optional

Ignored if `save` is ``False``. Passed to the colormap/color cycle

save method, i.e. `ultraplot.colors.ContinuousColormap.save` or

`ultraplot.colors.DiscreteColormap.save`.

Other parameters

----------------

**kwargs

Passed to `ultraplot.colors.ContinuousColormap.copy`,

`ultraplot.colors.PerceptualColormap.copy`, or

`ultraplot.colors.DiscreteColormap.copy`.

Returns

-------

matplotlib.colors.Colormap

A :class:`~ultraplot.colors.ContinuousColormap` or

:class:`~ultraplot.colors.DiscreteColormap` instance.

See also

--------

matplotlib.colors.Colormap

matplotlib.colors.LinearSegmentedColormap

matplotlib.colors.ListedColormap

ultraplot.constructor.Norm

ultraplot.constructor.Cycle

ultraplot.utils.get_colors

"""

# Helper function

# NOTE: Very careful here! Try to support common use cases. For example

# adding opacity gradations to colormaps with Colormap('cmap', alpha=(0.5, 1))

# or sampling maps with Colormap('cmap', samples=np.linspace(0, 1, 11)) should

# be allowable.

# If *args is singleton try to preserve it.

def _pop_modification(key):

value = kwargs.pop(key, None)

if not np.iterable(value) or isinstance(value, str):

values = (None,) * len(args)

elif len(args) == len(value):

values, value = tuple(value), None

elif len(args) == 1: # e.g. Colormap('cmap', alpha=(0.5, 1))

values = (None,)

else:

raise ValueError(

f"Got {len(args)} colormap-specs "

f"but {len(value)} values for {key!r}."

)

return value, values

# Parse keyword args that can apply to the merged colormap or each one

hsla = _pop_props(kwargs, "hsla")

if not args and hsla.keys() - {"alpha"}:

args = (hsla,)

else:

kwargs.update(hsla)

default_luminance = kwargs.pop("default_luminance", None) # used internally

cut, cuts = _pop_modification("cut")

left, lefts = _pop_modification("left")

right, rights = _pop_modification("right")

shift, shifts = _pop_modification("shift")

reverse, reverses = _pop_modification("reverse")

samples, sampless = _pop_modification("samples")

alpha, alphas = _pop_modification("alpha")

luminance, luminances = _pop_modification("luminance")

saturation, saturations = _pop_modification("saturation")

if luminance is not None:

luminances = (luminance,) * len(args)

if saturation is not None:

saturations = (saturation,) * len(args)

# Issue warnings and errors

if not args:

raise ValueError(

"Colormap() requires either positional arguments or "

"'hue', 'chroma', 'saturation', and/or 'luminance' keywords."

)

deprecated = {"listed": "discrete", "linear": "continuous"}

if listmode in deprecated:

oldmode, listmode = listmode, deprecated[listmode]

warnings._warn_ultraplot(

f"Please use listmode={listmode!r} instead of listmode={oldmode!r}."

"Option was renamed in v0.8 and will be removed in a future relase."

)

options = {"discrete", "continuous", "perceptual"}

for key, mode in zip(("listmode", "filemode"), (listmode, filemode)):

if mode not in options:

raise ValueError(

f"Invalid {key}={mode!r}. Options are: "

+ ", ".join(map(repr, options))

+ "."

)

# Loop through colormaps

cmaps = []

for (

arg,

icut,

ileft,

iright,

ireverse,

ishift,

isamples,

iluminance,

isaturation,

ialpha,

) in zip( # noqa: E501

args,

cuts,

lefts,

rights,

reverses,

shifts,

sampless,

luminances,

saturations,

alphas, # noqa: E501

):

# Load registered colormaps and maps on file

# TODO: Document how 'listmode' also affects loaded files

if isinstance(arg, str):

if "." in arg and os.path.isfile(arg):

if filemode == "discrete":

arg = pcolors.DiscreteColormap.from_file(arg)

else:

arg = pcolors.ContinuousColormap.from_file(arg)

else:

# FIXME: This error is baffling too me. Colors and colormaps

# are used interchangeable here

try:

arg = pcolors._cmap_database.get_cmap(arg)

except KeyError:

pass

# Convert matplotlib colormaps to subclasses

if isinstance(arg, mcolors.Colormap):

cmap = pcolors._translate_cmap(arg)

# Dictionary of hue/sat/luminance values or 2-tuples

elif isinstance(arg, dict):

cmap = pcolors.PerceptualColormap.from_hsl(**arg)

# List of color tuples or color strings, i.e. iterable of iterables

elif (

not isinstance(arg, str)

and np.iterable(arg)

and all(np.iterable(color) for color in arg)

):

if listmode == "discrete":

cmap = pcolors.DiscreteColormap(arg)

elif listmode == "continuous":

cmap = pcolors.ContinuousColormap.from_list(arg)

else:

cmap = pcolors.PerceptualColormap.from_list(arg)

# Monochrome colormap from input color

# NOTE: Do not print color names in error message. Too long to be useful.

else:

jreverse = isinstance(arg, str) and arg[-2:] == "_r"

if jreverse:

arg = arg[:-2]

try:

color = to_rgba(arg, cycle=cycle)

except (ValueError, TypeError):

message = f"Invalid colormap, color cycle, or color {arg!r}."

if isinstance(arg, str) and arg[:1] != "#":

message += (

" Options include: "

+ ", ".join(sorted(map(repr, pcolors._cmap_database)))

+ "."

)

raise ValueError(message) from None

iluminance = _not_none(iluminance, default_luminance)

cmap = pcolors.PerceptualColormap.from_color(

color, luminance=iluminance, saturation=isaturation

)

ireverse = _not_none(ireverse, False)

ireverse = ireverse ^ jreverse # xor

# Modify the colormap

cmap = _modify_colormap(

cmap,

cut=icut,

left=ileft,

right=iright,

reverse=ireverse,

shift=ishift,

alpha=ialpha,

samples=isamples,

)

cmaps.append(cmap)

# Merge the resulting colormaps

if len(cmaps) > 1: # more than one map and modify arbitrary properties

cmap = cmaps[0].append(*cmaps[1:], **kwargs)

else:

cmap = cmaps[0].copy(**kwargs)

# Modify the colormap

if discrete and isinstance(cmap, pcolors.ContinuousColormap): # noqa: E501

samples = _not_none(samples, DEFAULT_CYCLE_SAMPLES)

cmap = _modify_colormap(

cmap,

cut=cut,

left=left,

right=right,

reverse=reverse,

shift=shift,

alpha=alpha,

samples=samples,

)

# Initialize

if not cmap._isinit:

cmap._init()

# Register the colormap

if name is None:

name = cmap.name # may have been modified by e.g. reversed()

else:

cmap.name = name

if not isinstance(name, str):

raise ValueError("The colormap name must be a string.")

pcolors._cmap_database.register(cmap, name=name)

# Save the colormap

if save:

save_kw = save_kw or {}

cmap.save(**save_kw)

return cmap

class Cycle(cycler.Cycler):

"""

Generate and merge `~cycler.Cycler` instances in a variety of ways. The new generated class can be used to internally map keywords to the properties of the `~cycler.Cycler` instance. It is used by various plot functions to cycle through colors, linestyles, markers, etc.

Parameters

----------

*args : colormap-spec or cycle-spec, optional

Positional arguments control the *colors* in the `~cycler.Cycler`

object. If zero arguments are passed, the single color ``'black'``

is used. If more than one argument is passed, the resulting cycles

are merged. Arguments are interpreted as follows:

* If a `~cycler.Cycler`, nothing more is done.

* If a sequence of RGB tuples or color strings, these colors are used.

* If a :class:`~ultraplot.colors.DiscreteColormap`, colors from the ``colors``

attribute are used.

* If a string cycle name, that :class:`~ultraplot.colors.DiscreteColormap`

is looked up and its ``colors`` are used.

* In all other cases, the argument is passed to `Colormap`, and

colors from the resulting :class:`~ultraplot.colors.ContinuousColormap`

are used. See the `samples` argument.

If the last positional argument is numeric, it is used for the

`samples` keyword argument.

N

Shorthand for `samples`.

samples : float or sequence of float, optional

For :class:`~ultraplot.colors.DiscreteColormap`\\ s, this is the number of

colors to select. For example, ``Cycle('538', 4)`` returns the first 4

colors of the ``'538'`` color cycle.

For :class:`~ultraplot.colors.ContinuousColormap`\\ s, this is either a

sequence of sample coordinates used to draw colors from the colormap, or

an integer number of colors to draw. If the latter, the sample coordinates

are ``np.linspace(0, 1, samples)``. For example, ``Cycle('Reds', 5)``

divides the ``'Reds'`` colormap into five evenly spaced colors.

Other parameters

----------------

c, color, colors : sequence of color-spec, optional

A sequence of colors passed as keyword arguments. This is equivalent

to passing a sequence of colors as the first positional argument and is

included for consistency with `~matplotlib.axes.Axes.set_prop_cycle`.

If positional arguments were passed, the colors in this list are

appended to the colors resulting from the positional arguments.

lw, ls, d, a, m, ms, mew, mec, mfc

Shorthands for the below keywords.

linewidth, linestyle, dashes, alpha, marker, markersize, markeredgewidth, \

markeredgecolor, markerfacecolor : object or sequence of object, optional

Lists of `~matplotlib.lines.Line2D` properties that can be added to the

`~cycler.Cycler` instance. If the input was already a `~cycler.Cycler`,

these are added or appended to the existing cycle keys. If the lists have

unequal length, they are repeated to their least common multiple (unlike

`~cycler.cycler`, which throws an error in this case). For more info

on cyclers see `~matplotlib.axes.Axes.set_prop_cycle`. Also see

the `line style reference \

<https://matplotlib.org/2.2.5/gallery/lines_bars_and_markers/line_styles_reference.html>`__,

the `marker reference \

<https://matplotlib.org/stable/gallery/lines_bars_and_markers/marker_reference.html>`__,

and the `custom dashes reference \

<https://matplotlib.org/stable/gallery/lines_bars_and_markers/line_demo_dash_control.html>`__.

linewidths, linestyles, dashes, alphas, markers, markersizes, markeredgewidths, \

markeredgecolors, markerfacecolors

Aliases for the above keywords.

**kwargs

If the input is not already a `~cycler.Cycler` instance, these are passed

to `Colormap` and used to build the :class:`~ultraplot.colors.DiscreteColormap`

from which the cycler will draw its colors.

See also

--------

cycler.cycler

cycler.Cycler

matplotlib.axes.Axes.set_prop_cycle

ultraplot.constructor.Colormap

ultraplot.constructor.Norm

ultraplot.utils.get_colors

"""

def __init__(self, *args, N=None, samples=None, name=None, **kwargs):

cycler_props = self._parse_basic_properties(kwargs)

samples = _not_none(samples=samples, N=N) # trigger Colormap default

if not args:

self._handle_empty_args(cycler_props, kwargs)

elif self._is_all_cyclers(args):

self._handle_cycler_args(args, cycler_props, kwargs)

else:

self._handle_colormap_args(args, cycler_props, kwargs, samples, name)

self._iterator = None # internal reference for cycle

self.name = _not_none(name, "_no_name")

def _parse_basic_properties(self, kwargs):

"""Parse and validate basic properties from kwargs."""

props = _pop_props(kwargs, "line")

if "sizes" in kwargs:

props.setdefault("markersize", kwargs.pop("sizes"))

for key, value in tuple(props.items()):

if value is None:

props[key] = ["black"] # default instead of early return

elif not np.iterable(value) or isinstance(value, str):

props[key] = [value]

else:

props[key] = list(value) # ensure mutable list

return props

def _handle_empty_args(self, props, kwargs):

"""Handle case when no positional arguments are provided."""

props.setdefault("color", ["black"])

if kwargs:

warnings._warn_ultraplot(f"Ignoring Cycle() keyword arg(s) {kwargs}.")

self._build_cycler((props,))

def _handle_cycler_args(self, args, props, kwargs):

"""Handle case when arguments are cycler objects."""

if kwargs:

warnings._warn_ultraplot(f"Ignoring Cycle() keyword arg(s) {kwargs}.")

if len(args) == 1 and not props:

self._build_cycler((args[0].by_key(),))

else:

dicts = tuple(arg.by_key() for arg in args)

self._build_cycler(dicts + (props,))

def _handle_colormap_args(self, args, props, kwargs, samples, name):

"""Handle case when arguments are for creating a colormap."""

if isinstance(args[-1], Number):

args, samples = args[:-1], _not_none(

samples_positional=args[-1], samples=samples

)

cmap = self._create_colormap(args, name, samples, kwargs)

dict_ = {"color": [c if isinstance(c, str) else to_hex(c) for c in cmap.colors]}

self._build_cycler((dict_, props))

self.name = _not_none(name, cmap.name)

def _create_colormap(self, args, name, samples, kwargs):

"""Create a colormap from the given arguments."""

kwargs.setdefault("listmode", "discrete")

kwargs.setdefault("filemode", "discrete")

kwargs["discrete"] = True

kwargs["default_luminance"] = DEFAULT_CYCLE_LUMINANCE

return Colormap(*args, name=name, samples=samples, **kwargs)

def _is_all_cyclers(self, args):

"""Check if all arguments are Cycler objects."""

return all(isinstance(arg, cycler.Cycler) for arg in args)

def _build_cycler(self, dicts):