#!/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

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 ic # noqa: F401

from .internals import _not_none, _pop_props, _version_cartopy, _version_mpl, 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

# Normalizer registry

NORMS = {

'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'):

NORMS['twoslope'] = mcolors.TwoSlopeNorm

# Locator registry

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

# locators with cartopy < 0.18.

LOCATORS = {

'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'):

LOCATORS['theta'] = mpolar.ThetaLocator

if _version_cartopy >= '0.18':

LOCATORS['dms'] = partial(pticker.DegreeLocator, dms=True)

LOCATORS['dmslon'] = partial(pticker.LongitudeLocator, dms=True)

LOCATORS['dmslat'] = partial(pticker.LatitudeLocator, dms=True)

# 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 proplot formatter.

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

# formatters with cartopy < 0.18.

FORMATTERS = { # 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, # NOTE: this is subclass of Mathtext class

'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)), # noqa: E501

'math': mticker.LogFormatterMathtext, # deprecated (use SciNotation subclass)

}

if hasattr(mpolar, 'ThetaFormatter'):

FORMATTERS['theta'] = mpolar.ThetaFormatter

if hasattr(mdates, 'ConciseDateFormatter'):

FORMATTERS['concise'] = mdates.ConciseDateFormatter

if _version_cartopy >= '0.18':

FORMATTERS['dms'] = partial(pticker.DegreeFormatter, dms=True)

FORMATTERS['dmslon'] = partial(pticker.LongitudeFormatter, dms=True)

FORMATTERS['dmslat'] = partial(pticker.LatitudeFormatter, dms=True)

# 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_proplot(

'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_proplot(

"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

`~proplot.colors.PerceptualColormap`,

`~proplot.colors.ContinuousColormap`, and

`~proplot.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

`~proplot.colors.ContinuousColormap.append`

or `~proplot.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 proplot colormap class.

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

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

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

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

`~proplot.colors.ContinuousColormap`.

* If RGB tuple or color string, a `~proplot.colors.PerceptualColormap`

is generated with `~proplot.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

`~proplot.colors.DiscreteColormap`, `~proplot.colors.PerceptualColormap`,

or `~proplot.colors.ContinuousColormap` is generated depending on

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

`~proplot.colors.PerceptualColormap`.

* If dictionary, a `~proplot.colors.PerceptualColormap` is

generated with `~proplot.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

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

colormap may be a `~proplot.colors.ContinuousColormap` or

`~proplot.colors.PerceptualColormap` depending on the data file.

* If ``'discrete'``, a `~proplot.colors.DiscreteColormap` is generated

using `~proplot.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 `~proplot.colors.PerceptualColormap`

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

* If ``'continuous'``, a `~proplot.colors.ContinuousColormap` is

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

* If ``'discrete'``, a `~proplot.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 `~proplot.colors.ContinuousColormap`\\ s, this is used to

generate `~proplot.colors.DiscreteColormap`\\ s with

`~proplot.colors.ContinuousColormap.to_discrete`. For

`~proplot.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

`~proplot.colors.DiscreteColormap`, we leave it alone, but when it is a

`~proplot.colors.ContinuousColormap`, we always call

`~proplot.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 `~proplot.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

`~proplot.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

`~proplot.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 `~proplot.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

`proplot.colors.ContinuousColormap.set_alpha`

or `proplot.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

`~proplot.colors.PerceptualColormap.from_hsl` and

`~proplot.colors.PerceptualColormap.from_color`.

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

an arbitrary perceptually uniform colormap with

`~proplot.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 `~proplot.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.

`proplot.colors.ContinuousColormap.save` or

`proplot.colors.DiscreteColormap.save`.

save_kw : dict-like, optional

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

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

`proplot.colors.DiscreteColormap.save`.

Other parameters

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

**kwargs

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

`proplot.colors.PerceptualColormap.copy`, or

`proplot.colors.DiscreteColormap.copy`.

Returns

-------

matplotlib.colors.Colormap

A `~proplot.colors.ContinuousColormap` or

`~proplot.colors.DiscreteColormap` instance.

See also

--------

matplotlib.colors.Colormap

matplotlib.colors.LinearSegmentedColormap

matplotlib.colors.ListedColormap

proplot.constructor.Norm

proplot.constructor.Cycle

proplot.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_proplot(

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:

try:

arg = pcolors._cmap_database[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[name] = cmap

# Save the colormap

if save:

save_kw = save_kw or {}

cmap.save(**save_kw)

return cmap

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

"""

Generate and merge `~cycler.Cycler` instances in a variety of ways.

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 `~proplot.colors.DiscreteColormap`, colors from the ``colors``

attribute are used.

* If a string cycle name, that `~proplot.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 `~proplot.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 `~proplot.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 `~proplot.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 `~proplot.colors.DiscreteColormap`

from which the cycler will draw its colors.

Returns

-------

cycler.Cycler

A `~cycler.Cycler` instance that can be passed

to `~matplotlib.axes.Axes.set_prop_cycle`.

See also

--------

cycler.cycler

cycler.Cycler

matplotlib.axes.Axes.set_prop_cycle

proplot.constructor.Colormap

proplot.constructor.Norm

proplot.utils.get_colors

"""

# Parse keyword arguments that rotate through other properties

# besides color cycles.

props = _pop_props(kwargs, 'line')

if 'sizes' in kwargs: # special case, gets translated back by scatter()

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

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

for key, value in tuple(props.items()): # permit in-place modification

if value is None:

return

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

value = (value,)

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

# If args is non-empty, means we want color cycle; otherwise is black

if not args:

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

if kwargs:

warnings._warn_proplot(f'Ignoring Cycle() keyword arg(s) {kwargs}.')

dicts = ()

# Merge cycler objects and/or update cycler objects with input kwargs

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

if kwargs:

warnings._warn_proplot(f'Ignoring Cycle() keyword arg(s) {kwargs}.')

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

return args[0]

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

# Get a cycler from a colormap

# NOTE: Passing discrete=True does not imply default_luminance=90 because

# someone might be trying to make qualitative colormap for use in 2D plot

else:

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

args, samples = args[:-1], _not_none(samples_positional=args[-1], samples=samples) # noqa: #501

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

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

kwargs['discrete'] = True # triggers application of default 'samples'

kwargs['default_luminance'] = DEFAULT_CYCLE_LUMINANCE

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

name = _not_none(name, cmap.name)

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

dicts = (dict_,)

# Update the cyler property

dicts = dicts + (props,)

props = {}

for dict_ in dicts:

for key, value in dict_.items():

props.setdefault(key, []).extend(value)

# Build cycler with matching property lengths

maxlen = np.lcm.reduce([len(value) for value in props.values()])

props = {key: value * (maxlen // len(value)) for key, value in props.items()}

cycle = cycler.cycler(**props)

cycle.name = _not_none(name, '_no_name')

return cycle

def Norm(norm, *args, **kwargs):

"""

Return an arbitrary `~matplotlib.colors.Normalize` instance. See this

`tutorial <https://matplotlib.org/stable/tutorials/colors/colormapnorms.html>`__

for an introduction to matplotlib normalizers.

Parameters

----------

norm : str or `~matplotlib.colors.Normalize`

The normalizer specification. If a `~matplotlib.colors.Normalize`

instance already, a `copy.copy` of the instance is returned.

Otherwise, `norm` should be a string corresponding to one of

the "registered" colormap normalizers (see below table).

If `norm` is a list or tuple and the first element is a "registered"

normalizer name, subsequent elements are passed to the normalizer class

as positional arguments.

.. _norm_table:

=============================== =====================================

Key(s) Class

=============================== =====================================

``'null'``, ``'none'`` `~matplotlib.colors.NoNorm`

``'diverging'``, ``'div'`` `~proplot.colors.DivergingNorm`

``'segmented'``, ``'segments'`` `~proplot.colors.SegmentedNorm`

``'linear'`` `~matplotlib.colors.Normalize`

``'log'`` `~matplotlib.colors.LogNorm`

``'power'`` `~matplotlib.colors.PowerNorm`

``'symlog'`` `~matplotlib.colors.SymLogNorm`

=============================== =====================================

Other parameters

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

*args, **kwargs

Passed to the `~matplotlib.colors.Normalize` initializer.

Returns

-------

matplotlib.colors.Normalize

A `~matplotlib.colors.Normalize` instance.

See also

--------

matplotlib.colors.Normalize

proplot.colors.DiscreteNorm

proplot.constructor.Colormap

"""

if np.iterable(norm) and not isinstance(norm, str):

norm, *args = *norm, *args

if isinstance(norm, mcolors.Normalize):

return copy.copy(norm)

if not isinstance(norm, str):

raise ValueError(f'Invalid norm name {norm!r}. Must be string.')

if norm not in NORMS:

raise ValueError(

f'Unknown normalizer {norm!r}. Options are: '

+ ', '.join(map(repr, NORMS))

+ '.'

)

if norm == 'symlog' and not args and 'linthresh' not in kwargs:

kwargs['linthresh'] = 1 # special case, needs argument

return NORMS[norm](*args, **kwargs)

def Locator(locator, *args, discrete=False, **kwargs):

"""

Return a `~matplotlib.ticker.Locator` instance.

Parameters

----------

locator : `~matplotlib.ticker.Locator`, str, bool, float, or sequence

The locator specification, interpreted as follows:

* If a `~matplotlib.ticker.Locator` instance already,

a `copy.copy` of the instance is returned.

* If ``False``, a `~matplotlib.ticker.NullLocator` is used, and if

``True``, the default `~matplotlib.ticker.AutoLocator` is used.

* If a number, this specifies the *step size* between tick locations.

Returns a `~matplotlib.ticker.MultipleLocator`.

* If a sequence of numbers, these points are ticked. Returns

a `~matplotlib.ticker.FixedLocator` by default or a

`~proplot.ticker.DiscreteLocator` if `discrete` is ``True``.

Otherwise, `locator` should be a string corresponding to one

of the "registered" locators (see below table). If `locator` is a

list or tuple and the first element is a "registered" locator name,

subsequent elements are passed to the locator class as positional

arguments. For example, ``pplt.Locator(('multiple', 5))`` is

equivalent to ``pplt.Locator('multiple', 5)``.

.. _locator_table:

======================= ============================================ =====================================================================================

Key Class Description

======================= ============================================ =====================================================================================

``'null'``, ``'none'`` `~matplotlib.ticker.NullLocator` No ticks

``'auto'`` `~matplotlib.ticker.AutoLocator` Major ticks at sensible locations

``'minor'`` `~matplotlib.ticker.AutoMinorLocator` Minor ticks at sensible locations

``'date'`` `~matplotlib.dates.AutoDateLocator` Default tick locations for datetime axes

``'fixed'`` `~matplotlib.ticker.FixedLocator` Ticks at these exact locations

``'discrete'`` `~proplot.ticker.DiscreteLocator` Major ticks restricted to these locations but subsampled depending on the axis length

``'discreteminor'`` `~proplot.ticker.DiscreteLocator` Minor ticks restricted to these locations but subsampled depending on the axis length

``'index'`` `~proplot.ticker.IndexLocator` Ticks on the non-negative integers

``'linear'`` `~matplotlib.ticker.LinearLocator` Exactly ``N`` ticks encompassing axis limits, spaced as ``numpy.linspace(lo, hi, N)``

``'log'`` `~matplotlib.ticker.LogLocator` For log-scale axes

``'logminor'`` `~matplotlib.ticker.LogLocator` For log-scale axes on the 1st through 9th multiples of each power of the base

``'logit'`` `~matplotlib.ticker.LogitLocator` For logit-scale axes

``'logitminor'`` `~matplotlib.ticker.LogitLocator` For logit-scale axes with ``minor=True`` passed to `~matplotlib.ticker.LogitLocator`

``'maxn'`` `~matplotlib.ticker.MaxNLocator` No more than ``N`` ticks at sensible locations

``'multiple'`` `~matplotlib.ticker.MultipleLocator` Ticks every ``N`` step away from zero

``'symlog'`` `~matplotlib.ticker.SymmetricalLogLocator` For symlog-scale axes

``'symlogminor'`` `~matplotlib.ticker.SymmetricalLogLocator` For symlog-scale axes on the 1st through 9th multiples of each power of the base

``'theta'`` `~matplotlib.projections.polar.ThetaLocator` Like the base locator but default locations are every `numpy.pi` / 8 radians

``'year'`` `~matplotlib.dates.YearLocator` Ticks every ``N`` years

``'month'`` `~matplotlib.dates.MonthLocator` Ticks every ``N`` months

``'weekday'`` `~matplotlib.dates.WeekdayLocator` Ticks every ``N`` weekdays

``'day'`` `~matplotlib.dates.DayLocator` Ticks every ``N`` days

``'hour'`` `~matplotlib.dates.HourLocator` Ticks every ``N`` hours

``'minute'`` `~matplotlib.dates.MinuteLocator` Ticks every ``N`` minutes

``'second'`` `~matplotlib.dates.SecondLocator` Ticks every ``N`` seconds

``'microsecond'`` `~matplotlib.dates.MicrosecondLocator` Ticks every ``N`` microseconds

``'lon'``, ``'deglon'`` `~proplot.ticker.LongitudeLocator` Longitude gridlines at sensible decimal locations

``'lat'``, ``'deglat'`` `~proplot.ticker.LatitudeLocator` Latitude gridlines at sensible decimal locations

``'dms'`` `~proplot.ticker.DegreeLocator` Gridlines on nice minute and second intervals

``'dmslon'`` `~proplot.ticker.LongitudeLocator` Longitude gridlines on nice minute and second intervals

``'dmslat'`` `~proplot.ticker.LatitudeLocator` Latitude gridlines on nice minute and second intervals

======================= ============================================ =====================================================================================

Other parameters

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

*args, **kwargs

Passed to the `~matplotlib.ticker.Locator` class.

Returns

-------

matplotlib.ticker.Locator

A `~matplotlib.ticker.Locator` instance.

See also

--------

matplotlib.ticker.Locator

proplot.axes.CartesianAxes.format

proplot.axes.PolarAxes.format

proplot.axes.GeoAxes.format

proplot.axes.Axes.colorbar

proplot.constructor.Formatter

""" # noqa: E501

if np.iterable(locator) and not isinstance(locator, str) and not all(

isinstance(num, Number) for num in locator

):

locator, *args = *locator, *args

if isinstance(locator, mticker.Locator):

return copy.copy(locator)