From 86e8aec4d6ffa0b28df31d2e5f35260e9c1327fb Mon Sep 17 00:00:00 2001 From: cvanelteren Date: Tue, 1 Sep 2026 19:44:08 +1000 Subject: [PATCH 1/9] tryout for pylance --- docs/conf.py | 16 +++++ pyproject.toml | 3 + ultraplot/axes/cartesian.py | 8 ++- ultraplot/figure.py | 15 +++-- ultraplot/gridspec.py | 25 ++++++-- ultraplot/internals/docstring.py | 54 ++++++++++------- ultraplot/internals/inputs.py | 21 ++++--- ultraplot/internals/kwargs.py | 9 ++- ultraplot/internals/warnings.py | 9 ++- ultraplot/tests/test_docstring_helpers.py | 72 +++++++++++++++++++++++ ultraplot/tests/test_kwargs_helpers.py | 11 ++++ ultraplot/ui.py | 6 +- 12 files changed, 197 insertions(+), 52 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index cb17889ef..47515e8d7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -13,6 +13,7 @@ # Import statements import datetime +import inspect import logging import os import re @@ -637,5 +638,20 @@ def _replace_snippet(match): pass +def process_signature( + app, what, name, obj, options, signature, return_annotation +): + """Use compact signatures marked by UltraPlot only in generated docs.""" + marked = getattr(obj, "__ultraplot_doc_signature__", None) + if marked is None and inspect.ismethod(obj): + marked = getattr(obj.__func__, "__ultraplot_doc_signature__", None) + if marked is None and inspect.isclass(obj): + marked = getattr(obj.__init__, "__ultraplot_doc_signature__", None) + if marked is not None: + return marked, return_annotation + return signature, return_annotation + + def setup(app): app.connect("autodoc-process-docstring", process_docstring) + app.connect("autodoc-process-signature", process_signature) diff --git a/pyproject.toml b/pyproject.toml index 8084e38ce..cc7348015 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -49,6 +49,9 @@ dynamic = ["version"] packages = {find = {exclude=["docs*", "baseline*", "logo*"]}} include-package-data = true +[tool.setuptools.package-data] +ultraplot = ["py.typed"] + [tool.setuptools_scm] write_to = "ultraplot/_version.py" write_to_template = "__version__ = '{version}'\n" diff --git a/ultraplot/axes/cartesian.py b/ultraplot/axes/cartesian.py index 064c1eed8..9957e1b2c 100644 --- a/ultraplot/axes/cartesian.py +++ b/ultraplot/axes/cartesian.py @@ -7,7 +7,7 @@ import functools import inspect from dataclasses import dataclass, field -from typing import Any, Dict, Optional, Tuple, Union +from typing import Any, Callable, Dict, Optional, Tuple, TypeVar, Union, cast import matplotlib.axis as maxis import matplotlib.dates as mdates @@ -40,6 +40,8 @@ __all__ = ["CartesianAxes"] +_F = TypeVar("_F", bound=Callable[..., Any]) + # Tuple of date converters DATE_CONVERTERS = (mdates.DateConverter,) @@ -1860,7 +1862,7 @@ def get_tightbbox(self, renderer, *args, **kwargs): return super().get_tightbbox(renderer, *args, **kwargs) -def _capture_explicit_format_keys(func): +def _capture_explicit_format_keys(func: _F) -> _F: """ Preserve raw keyword names before Python binds them to the format signature. """ @@ -1870,7 +1872,7 @@ def wrapper(self, *args, **kwargs): kwargs.setdefault("_explicit_format_keys", set(kwargs)) return func(self, *args, **kwargs) - return wrapper + return cast(_F, wrapper) # tmp diff --git a/ultraplot/figure.py b/ultraplot/figure.py index 89c830bc1..8d6ceebf0 100644 --- a/ultraplot/figure.py +++ b/ultraplot/figure.py @@ -7,6 +7,7 @@ import inspect import os from contextlib import ExitStack +from typing import Callable, TypeVar, cast try: from typing import Any, Iterable, List, Optional, Tuple, Union @@ -50,6 +51,8 @@ "Figure", ] +_F = TypeVar("_F", bound=Callable[..., Any]) + def _any_not_none(*values): """Return whether at least one value is not ``None``.""" @@ -695,7 +698,7 @@ def _draw_context(): return canvas -def _clear_border_cache(func): +def _clear_border_cache(func: _F) -> _F: """ Decorator that clears the border cache after function execution. """ @@ -707,7 +710,7 @@ def wrapper(self, *args, **kwargs): delattr(self, "_cached_border_axes") return result - return wrapper + return cast(_F, wrapper) class Figure(mfigure.Figure): @@ -3387,28 +3390,28 @@ def add_axes(self, rect, **kwargs): @docstring._concatenate_inherited @docstring._snippet_manager - def add_subplot(self, *args, **kwargs): + def add_subplot(self, *args, **kwargs) -> paxes.Axes: """ %(figure.subplot)s """ return self._add_subplot(*args, **kwargs) @docstring._snippet_manager - def subplot(self, *args, **kwargs): # shorthand + def subplot(self, *args, **kwargs) -> paxes.Axes: # shorthand """ %(figure.subplot)s """ return self._add_subplot(*args, **kwargs) @docstring._snippet_manager - def add_subplots(self, *args, **kwargs): + def add_subplots(self, *args, **kwargs) -> pgridspec.SubplotGrid: """ %(figure.subplots)s """ return self._add_subplots(*args, **kwargs) @docstring._snippet_manager - def subplots(self, *args, **kwargs): + def subplots(self, *args, **kwargs) -> pgridspec.SubplotGrid: """ %(figure.subplots)s """ diff --git a/ultraplot/gridspec.py b/ultraplot/gridspec.py index 89915645e..df086ae60 100644 --- a/ultraplot/gridspec.py +++ b/ultraplot/gridspec.py @@ -9,7 +9,7 @@ from collections.abc import MutableSequence from functools import wraps from numbers import Integral -from typing import List, Optional, Tuple, Union +from typing import Callable, List, Optional, Tuple, TypeVar, Union, cast, overload import matplotlib.axes as maxes import matplotlib.gridspec as mgridspec @@ -122,8 +122,23 @@ def _dummy_method(*args): return _dummy_method -def _apply_to_all(func=None, *, doc_key=None): - def decorator(f): +_F = TypeVar("_F", bound=Callable[..., object]) + + +@overload +def _apply_to_all(func: _F, *, doc_key: Optional[str] = None) -> _F: ... + + +@overload +def _apply_to_all( + func: None = None, *, doc_key: Optional[str] = None +) -> Callable[[_F], _F]: ... + + +def _apply_to_all( + func: Optional[_F] = None, *, doc_key: Optional[str] = None +) -> Union[_F, Callable[[_F], _F]]: + def decorator(f: _F) -> _F: @wraps(f) def wrapper(self, *args, **kwargs): objs = self._apply_command(f.__name__, *args, **kwargs) @@ -158,7 +173,7 @@ def wrapper(self, *args, **kwargs): wrapper.__doc__ = doc - return wrapper + return cast(_F, wrapper) if func is not None: return decorator(func) @@ -2051,7 +2066,7 @@ def _validate_item(self, items, scalar=False): return items @docstring._snippet_manager - def format(self, **kwargs): + def format(self, **kwargs) -> None: """ Call the ``format`` command for the `~SubplotGrid.figure` and every axes in the grid. diff --git a/ultraplot/internals/docstring.py b/ultraplot/internals/docstring.py index 205e92bbf..eff0772fe 100644 --- a/ultraplot/internals/docstring.py +++ b/ultraplot/internals/docstring.py @@ -23,43 +23,48 @@ # ... print(*_iter_doc(uplt)) import inspect import re +from typing import Any, Callable, TypeVar, cast, overload from . import ic # noqa: F401 +_F = TypeVar("_F", bound=Callable[..., Any]) +_T = TypeVar("_T") -def _obfuscate_kwargs(func): + +def _obfuscate_kwargs(func: _F) -> _F: """ - Obfuscate keyword args. + Mark keyword arguments as compact in generated API documentation. """ return _obfuscate_signature(func, lambda **kwargs: None) -def _obfuscate_params(func): +def _obfuscate_params(func: _F) -> _F: """ - Obfuscate all parameters. + Mark all parameters as compact in generated API documentation. """ return _obfuscate_signature(func, lambda *args, **kwargs: None) -def _obfuscate_signature(func, dummy): +def _obfuscate_signature(func: _F, dummy: Callable[..., Any]) -> _F: """ - Obfuscate a misleading or incomplete call signature. - Instead users should inspect the parameter table. + Mark a misleading or incomplete signature as compact in generated docs. + + The callable's actual signature remains available to Python and language + servers; Sphinx reads the marker below when rendering API headings. """ - # Obfuscate signature by converting to *args **kwargs. Note this does - # not change behavior of function! Copy parameters from a dummy function - # because I'm too lazy to figure out inspect.Parameters API - # See: https://stackoverflow.com/a/33112180/4970632 - sig = inspect.signature(func) - sig_repl = inspect.signature(dummy) - func.__signature__ = sig.replace(parameters=tuple(sig_repl.parameters.values())) + # Keep the compact signature available to documentation tooling without + # changing the callable's runtime signature. Sphinx uses this marker to + # avoid filling API headings with inherited or dynamically routed options. + setattr(func, "__ultraplot_doc_signature__", str(inspect.signature(dummy))) return func -def _concatenate_inherited(func, prepend_summary=False): +def _concatenate_inherited( + func: _F, prepend_summary: bool = False +) -> _F: """ Concatenate docstrings from a matplotlib axes method with a ultraplot - axes method and obfuscate the call signature. + axes method and mark its generated-documentation signature as compact. """ import matplotlib.axes as maxes import matplotlib.figure as mfigure @@ -102,7 +107,7 @@ def _concatenate_inherited(func, prepend_summary=False): """ # Return docstring - # NOTE: Also obfuscate parameters to avoid partial coverage of call signatures + # Keep generated API headings compact to avoid showing partial call signatures. func.__doc__ = inspect.cleandoc(doc) func = _obfuscate_params(func) return func @@ -143,7 +148,13 @@ def __missing__(self, key): return dict.__getitem__(self, key) raise KeyError(key) - def __call__(self, obj): + @overload + def __call__(self, obj: str) -> str: ... + + @overload + def __call__(self, obj: _T) -> _T: ... + + def __call__(self, obj: _T | str) -> _T | str: """ Add snippets to the string or object using ``%(name)s`` substitution. Here ``%(name)s`` is used rather than ``.format`` to support invalid identifiers. @@ -151,9 +162,10 @@ def __call__(self, obj): if isinstance(obj, str): obj %= self # add snippets to a string else: - obj.__doc__ = inspect.getdoc(obj) # also dedents the docstring - if obj.__doc__: - obj.__doc__ %= self # insert snippets after dedent + documented = cast(Any, obj) + documented.__doc__ = inspect.getdoc(documented) # also dedents the docstring + if documented.__doc__: + documented.__doc__ %= self # insert snippets after dedent return obj def __setitem__(self, key, value): diff --git a/ultraplot/internals/inputs.py b/ultraplot/internals/inputs.py index e3dd461b6..16d1bf686 100644 --- a/ultraplot/internals/inputs.py +++ b/ultraplot/internals/inputs.py @@ -5,6 +5,7 @@ import functools import sys +from typing import Any, Callable, TypeVar, cast import numpy as np import numpy.ma as ma @@ -21,6 +22,8 @@ except ModuleNotFoundError: Triangulation = object +_F = TypeVar("_F", bound=Callable[..., Any]) + # Constants BASEMAP_FUNCS = ( # default latlon=True @@ -289,13 +292,15 @@ def _parse_triangulation_inputs(*args, **kwargs): return triangulation, z, args[1:], kwargs -def _parse_triangulation_with_preprocess(*keys, keywords=None, allow_extra=True): +def _parse_triangulation_with_preprocess( + *keys, keywords=None, allow_extra=True +) -> Callable[[_F], _F]: """ Combines _parse_triangulation with _preprocess_or_redirect for backwards compatibility. """ - def _decorator(func): - def triangulation_wrapper(self, *args, **kwargs): + def _decorator(func: _F) -> _F: + def triangulation_wrapper(self, *args, **kwargs) -> Any: triangulation, z, remaining_args, updated_kwargs = ( _parse_triangulation_inputs(*args, **kwargs) ) @@ -318,14 +323,14 @@ def _tri_cartopy_default(args, kwargs): # Finally make sure all other metadata is correct functools.update_wrapper(final_wrapper, func) - return final_wrapper + return cast(_F, final_wrapper) return _decorator def _preprocess_or_redirect( *keys, keywords=None, allow_extra=True, cartopy_default_transform=True -): +) -> Callable[[_F], _F]: """ Redirect internal plotting calls to native matplotlib methods. Also convert keyword args to positional and pass arguments through 'data' dictionary. @@ -336,12 +341,12 @@ def _preprocess_or_redirect( if isinstance(keywords, str): keywords = (keywords,) - def _decorator(func): + def _decorator(func: _F) -> _F: name = func.__name__ from . import _kwargs_to_args @functools.wraps(func) - def _preprocess_or_redirect(self, *args, **kwargs): + def _preprocess_or_redirect(self, *args, **kwargs) -> Any: if getattr(self, "_internal_call", None): # Redirect internal matplotlib call to native function from ..axes import PlotAxes @@ -404,7 +409,7 @@ def _preprocess_or_redirect(self, *args, **kwargs): # Call main function return func(self, *args, **kwargs) # call unbound method - return _preprocess_or_redirect + return cast(_F, _preprocess_or_redirect) return _decorator diff --git a/ultraplot/internals/kwargs.py b/ultraplot/internals/kwargs.py index 82396b837..7b98eb04b 100644 --- a/ultraplot/internals/kwargs.py +++ b/ultraplot/internals/kwargs.py @@ -10,9 +10,12 @@ import functools import inspect +from typing import Any, Callable, TypeVar, cast from . import warnings +_F = TypeVar("_F", bound=Callable[..., Any]) + __all__ = [ "_not_none", "_alias_kwargs", @@ -52,7 +55,7 @@ def _not_none(*args, default=None, **kwargs): return first -def _alias_kwargs(**aliases): +def _alias_kwargs(**aliases) -> Callable[[_F], _F]: """ Fold keyword-argument aliases into their canonical names before a call. @@ -71,7 +74,7 @@ def _alias_kwargs(**aliases): # so the first non-``None`` one wins, exactly like `_not_none`. lookup = {syn: canon for canon, syns in aliases.items() for syn in syns} - def decorator(func): + def decorator(func: _F) -> _F: @functools.wraps(func) def wrapper(*args, **kwargs): for syn, canon in lookup.items(): @@ -91,7 +94,7 @@ def wrapper(*args, **kwargs): ) return func(*args, **kwargs) - return wrapper + return cast(_F, wrapper) return decorator diff --git a/ultraplot/internals/warnings.py b/ultraplot/internals/warnings.py index 80e32fdeb..63deb111a 100644 --- a/ultraplot/internals/warnings.py +++ b/ultraplot/internals/warnings.py @@ -7,9 +7,12 @@ import re import sys import warnings +from typing import Any, Callable, TypeVar, cast from . import ic # noqa: F401 +_F = TypeVar("_F", bound=Callable[..., Any]) + # Internal modules omitted from warning message REGEX_INTERNAL = re.compile(r"\A(matplotlib|mpl_toolkits|ultraplot)\.") @@ -92,14 +95,14 @@ def _deprecated_function(*args, new_obj=new_obj, message=message, **kwargs): return tuple(objs) -def _rename_kwargs(version, **kwargs_rename): +def _rename_kwargs(version, **kwargs_rename) -> Callable[[_F], _F]: """ Emit a basic deprecation warning after removing or renaming keyword argument(s). Each key should be an old keyword, and each argument should be the new keyword or *instructions* for what to use instead. """ - def _decorator(func_orig): + def _decorator(func_orig: _F) -> _F: @functools.wraps(func_orig) def _deprecate_kwargs_wrapper(*args, **kwargs): for key_old, key_new in kwargs_rename.items(): @@ -118,6 +121,6 @@ def _deprecate_kwargs_wrapper(*args, **kwargs): ) return func_orig(*args, **kwargs) - return _deprecate_kwargs_wrapper + return cast(_F, _deprecate_kwargs_wrapper) return _decorator diff --git a/ultraplot/tests/test_docstring_helpers.py b/ultraplot/tests/test_docstring_helpers.py index 17d826d49..2ff7627ef 100644 --- a/ultraplot/tests/test_docstring_helpers.py +++ b/ultraplot/tests/test_docstring_helpers.py @@ -1,6 +1,16 @@ """Tests for the shared style docstrings in ``ultraplot.internals.docstring``.""" +import inspect + import ultraplot as uplt +from ultraplot.axes import ( + Axes, + CartesianAxes, + GeoAxes, + PolarAxes, + TaylorAxes, +) +from ultraplot.figure import Figure from ultraplot.internals import docstring @@ -61,3 +71,65 @@ def test_geo_format_folds_alias_entries() -> None: assert ( "Aliases: ``lonminorlines_kw`` and ``latminorlines_kw``, respectively." in geo ) + + +def test_compact_doc_markers_preserve_runtime_signatures() -> None: + """Documentation presentation must not alter callable introspection.""" + + def keyword_only(*, explicit=None, **kwargs): + return explicit, kwargs + + def positional(first, second=None): + return first, second + + keyword_signature = inspect.signature(keyword_only) + positional_signature = inspect.signature(positional) + assert docstring._obfuscate_kwargs(keyword_only) is keyword_only + assert docstring._obfuscate_params(positional) is positional + assert inspect.signature(keyword_only) == keyword_signature + assert inspect.signature(positional) == positional_signature + assert keyword_only.__ultraplot_doc_signature__ == "(**kwargs)" + assert positional.__ultraplot_doc_signature__ == "(*args, **kwargs)" + + +def test_format_implementation_signatures_remain_visible() -> None: + """Format methods retain their declared signatures for tools and editors.""" + cases = ( + (Axes, "title"), + (CartesianAxes, "xlim"), + (PolarAxes, "r0"), + (GeoAxes, "lonlim"), + (TaylorAxes, "corrlabel"), + ) + for cls, representative_parameter in cases: + signature = inspect.signature(cls.format) + assert signature == cls._format_signatures[cls] + assert representative_parameter in signature.parameters + assert cls.format.__ultraplot_doc_signature__ == "(**kwargs)" + + assert inspect.signature(Figure.format) == Figure._format_signature + assert "suptitle" in inspect.signature(Figure.format).parameters + assert Figure.format.__ultraplot_doc_signature__ == "(**kwargs)" + + figure_signature = inspect.signature(Figure) + assert "refnum" in figure_signature.parameters + assert Figure.__init__.__ultraplot_doc_signature__ == "(**kwargs)" + + +def test_snippet_manager_preserves_callable_signature() -> None: + """Docstring expansion acts as a typed identity decorator.""" + + @docstring._snippet_manager + def documented(value, *, option=None): + """Return the input value.""" + return value, option + + assert str(inspect.signature(documented)) == "(value, *, option=None)" + + +def test_inherited_docstrings_preserve_callable_signature() -> None: + """Matplotlib docstring concatenation only compacts the Sphinx heading.""" + signature = inspect.signature(Axes.legend) + assert "handles" in signature.parameters + assert "labels" in signature.parameters + assert Axes.legend.__ultraplot_doc_signature__ == "(*args, **kwargs)" diff --git a/ultraplot/tests/test_kwargs_helpers.py b/ultraplot/tests/test_kwargs_helpers.py index 853131d78..fd63fa3e1 100644 --- a/ultraplot/tests/test_kwargs_helpers.py +++ b/ultraplot/tests/test_kwargs_helpers.py @@ -1,9 +1,11 @@ """Tests for the keyword-argument / alias helpers in ``ultraplot.internals.kwargs``.""" +import inspect import warnings from ultraplot import internals from ultraplot.internals import kwargs as ikwargs +from ultraplot.internals import warnings as uwarnings def test_kwargs_helpers_reexported_from_package() -> None: @@ -45,6 +47,15 @@ def func(*, refnum=1, figwidth=None, **kwargs): assert func(width=5) == (1, 5, {}) # synonym folded to canonical assert func(ref=2, figwidth=3) == (2, 3, {}) # mix of alias + canonical assert func(other=9) == (1, None, {"other": 9}) # unrelated kwargs pass through + assert str(inspect.signature(func)) == "(*, refnum=1, figwidth=None, **kwargs)" + + +def test_rename_kwargs_preserves_callable_signature() -> None: + @uwarnings._rename_kwargs("0.1.0", old="current") + def func(*, current=None): + return current + + assert str(inspect.signature(func)) == "(*, current=None)" def test_alias_kwargs_none_synonym_defers_to_default() -> None: diff --git a/ultraplot/ui.py b/ultraplot/ui.py index f61b03840..6a5a3136f 100644 --- a/ultraplot/ui.py +++ b/ultraplot/ui.py @@ -125,7 +125,7 @@ def isinteractive(): @docstring._snippet_manager -def figure(**kwargs): +def figure(**kwargs) -> pfigure.Figure: """ Create an empty figure. Subplots can be subsequently added using `~ultraplot.figure.Figure.add_subplot` or `~ultraplot.figure.Figure.subplots`. @@ -153,7 +153,7 @@ def figure(**kwargs): @docstring._snippet_manager -def subplot(**kwargs): +def subplot(**kwargs) -> tuple[pfigure.Figure, paxes.Axes]: """ Return a figure and a single subplot. This command is analogous to `matplotlib.pyplot.subplot`, @@ -196,7 +196,7 @@ def subplot(**kwargs): @docstring._snippet_manager -def subplots(*args, **kwargs): +def subplots(*args, **kwargs) -> tuple[pfigure.Figure, pgridspec.SubplotGrid]: """ Return a figure and an arbitrary grid of subplots. This command is analogous to `matplotlib.pyplot.subplots`, From 039abcd1bedc1268c797783040a5da2bb5c5ceb3 Mon Sep 17 00:00:00 2001 From: cvanelteren Date: Tue, 1 Sep 2026 19:54:17 +1000 Subject: [PATCH 2/9] black --- ultraplot/internals/docstring.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/ultraplot/internals/docstring.py b/ultraplot/internals/docstring.py index eff0772fe..5b3d8afbc 100644 --- a/ultraplot/internals/docstring.py +++ b/ultraplot/internals/docstring.py @@ -59,9 +59,7 @@ def _obfuscate_signature(func: _F, dummy: Callable[..., Any]) -> _F: return func -def _concatenate_inherited( - func: _F, prepend_summary: bool = False -) -> _F: +def _concatenate_inherited(func: _F, prepend_summary: bool = False) -> _F: """ Concatenate docstrings from a matplotlib axes method with a ultraplot axes method and mark its generated-documentation signature as compact. @@ -163,7 +161,9 @@ def __call__(self, obj: _T | str) -> _T | str: obj %= self # add snippets to a string else: documented = cast(Any, obj) - documented.__doc__ = inspect.getdoc(documented) # also dedents the docstring + documented.__doc__ = inspect.getdoc( + documented + ) # also dedents the docstring if documented.__doc__: documented.__doc__ %= self # insert snippets after dedent return obj From f2571e1f5fe92c49bed1c241a0bd208da9fd55ed Mon Sep 17 00:00:00 2001 From: cvanelteren Date: Thu, 3 Sep 2026 22:58:13 +1000 Subject: [PATCH 3/9] add stubs --- .gitattributes | 2 + .github/workflows/main.yml | 41 +- docs/contributing.rst | 31 + pyproject.toml | 6 +- tools/ci/stub_consumer.py | 6 + tools/generate_stubs.py | 723 ++ ultraplot/__init__.pyi | 177 + ultraplot/_animation.pyi | 315 + ultraplot/_interaction.pyi | 212 + ultraplot/_layout.pyi | 206 + ultraplot/_lazy.pyi | 63 + ultraplot/_subplots.pyi | 70 + ultraplot/_version.pyi | 3 + ultraplot/animation.pyi | 343 + ultraplot/axes/__init__.pyi | 20 + ultraplot/axes/_formatting.pyi | 39 + ultraplot/axes/base.pyi | 2094 ++++ ultraplot/axes/cartesian.pyi | 1041 ++ ultraplot/axes/container.pyi | 243 + ultraplot/axes/geo.pyi | 1652 ++++ ultraplot/axes/plot.py | 2 + ultraplot/axes/plot.pyi | 9628 +++++++++++++++++++ ultraplot/axes/plot_types/__init__.pyi | 3 + ultraplot/axes/plot_types/circlize.pyi | 51 + ultraplot/axes/plot_types/curved_quiver.pyi | 158 + ultraplot/axes/plot_types/ribbon.pyi | 20 + ultraplot/axes/plot_types/sankey.pyi | 105 + ultraplot/axes/polar.pyi | 541 ++ ultraplot/axes/shared.pyi | 50 + ultraplot/axes/taylor.pyi | 561 ++ ultraplot/axes/three.pyi | 40 + ultraplot/colorbar.pyi | 101 + ultraplot/colors.pyi | 1385 +++ ultraplot/config.py | 1 + ultraplot/config.pyi | 710 ++ ultraplot/constructor.pyi | 855 ++ ultraplot/demos.pyi | 294 + ultraplot/externals/__init__.pyi | 7 + ultraplot/externals/hsluv.pyi | 144 + ultraplot/figure.pyi | 2536 +++++ ultraplot/gridspec.pyi | 1287 +++ ultraplot/internals/__init__.pyi | 43 + ultraplot/internals/benchmarks.pyi | 23 + ultraplot/internals/context.pyi | 35 + ultraplot/internals/docstring.pyi | 68 + ultraplot/internals/fonts.pyi | 64 + ultraplot/internals/guides.pyi | 55 + ultraplot/internals/inputs.pyi | 194 + ultraplot/internals/kwargs.pyi | 68 + ultraplot/internals/labels.pyi | 30 + ultraplot/internals/rcsetup.pyi | 222 + ultraplot/internals/versions.pyi | 49 + ultraplot/internals/warnings.pyi | 38 + ultraplot/legend.pyi | 479 + ultraplot/proj.pyi | 221 + ultraplot/py.typed | 1 + ultraplot/scale.pyi | 573 ++ ultraplot/tests/test_docstring_helpers.py | 14 + ultraplot/tests/test_stubs.py | 138 + ultraplot/text.pyi | 78 + ultraplot/textalign.pyi | 159 + ultraplot/ticker.pyi | 605 ++ ultraplot/ui.pyi | 635 ++ ultraplot/ultralayout.pyi | 157 + ultraplot/utils.pyi | 630 ++ 65 files changed, 30343 insertions(+), 2 deletions(-) create mode 100644 .gitattributes create mode 100644 tools/ci/stub_consumer.py create mode 100644 tools/generate_stubs.py create mode 100644 ultraplot/__init__.pyi create mode 100644 ultraplot/_animation.pyi create mode 100644 ultraplot/_interaction.pyi create mode 100644 ultraplot/_layout.pyi create mode 100644 ultraplot/_lazy.pyi create mode 100644 ultraplot/_subplots.pyi create mode 100644 ultraplot/_version.pyi create mode 100644 ultraplot/animation.pyi create mode 100644 ultraplot/axes/__init__.pyi create mode 100644 ultraplot/axes/_formatting.pyi create mode 100644 ultraplot/axes/base.pyi create mode 100644 ultraplot/axes/cartesian.pyi create mode 100644 ultraplot/axes/container.pyi create mode 100644 ultraplot/axes/geo.pyi create mode 100644 ultraplot/axes/plot.pyi create mode 100644 ultraplot/axes/plot_types/__init__.pyi create mode 100644 ultraplot/axes/plot_types/circlize.pyi create mode 100644 ultraplot/axes/plot_types/curved_quiver.pyi create mode 100644 ultraplot/axes/plot_types/ribbon.pyi create mode 100644 ultraplot/axes/plot_types/sankey.pyi create mode 100644 ultraplot/axes/polar.pyi create mode 100644 ultraplot/axes/shared.pyi create mode 100644 ultraplot/axes/taylor.pyi create mode 100644 ultraplot/axes/three.pyi create mode 100644 ultraplot/colorbar.pyi create mode 100644 ultraplot/colors.pyi create mode 100644 ultraplot/config.pyi create mode 100644 ultraplot/constructor.pyi create mode 100644 ultraplot/demos.pyi create mode 100644 ultraplot/externals/__init__.pyi create mode 100644 ultraplot/externals/hsluv.pyi create mode 100644 ultraplot/figure.pyi create mode 100644 ultraplot/gridspec.pyi create mode 100644 ultraplot/internals/__init__.pyi create mode 100644 ultraplot/internals/benchmarks.pyi create mode 100644 ultraplot/internals/context.pyi create mode 100644 ultraplot/internals/docstring.pyi create mode 100644 ultraplot/internals/fonts.pyi create mode 100644 ultraplot/internals/guides.pyi create mode 100644 ultraplot/internals/inputs.pyi create mode 100644 ultraplot/internals/kwargs.pyi create mode 100644 ultraplot/internals/labels.pyi create mode 100644 ultraplot/internals/rcsetup.pyi create mode 100644 ultraplot/internals/versions.pyi create mode 100644 ultraplot/internals/warnings.pyi create mode 100644 ultraplot/legend.pyi create mode 100644 ultraplot/proj.pyi create mode 100644 ultraplot/py.typed create mode 100644 ultraplot/scale.pyi create mode 100644 ultraplot/tests/test_stubs.py create mode 100644 ultraplot/text.pyi create mode 100644 ultraplot/textalign.pyi create mode 100644 ultraplot/ticker.pyi create mode 100644 ultraplot/ui.pyi create mode 100644 ultraplot/ultralayout.pyi create mode 100644 ultraplot/utils.pyi diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 000000000..528fa8e6e --- /dev/null +++ b/.gitattributes @@ -0,0 +1,2 @@ +ultraplot/*.pyi linguist-generated=true +ultraplot/**/*.pyi linguist-generated=true diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 1a2fcadb2..3744db5b7 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -22,6 +22,7 @@ jobs: - 'environment.yml' - '.github/workflows/**' - 'tools/ci/**' + - 'tools/generate_stubs.py' select-tests: runs-on: ubuntu-latest @@ -99,6 +100,7 @@ jobs: --always-full 'pyproject.toml' \ --always-full 'environment.yml' \ --always-full 'ultraplot/__init__.py' \ + --always-full 'tools/generate_stubs.py' \ --ignore 'docs/**' \ --ignore 'README.rst' echo "Selection output:" @@ -138,6 +140,42 @@ jobs: echo "Detected test matrix: $(echo "$OUTPUT" | jq -c '.test_matrix')" python tools/ci/version_support.py --format github-output >> $GITHUB_OUTPUT + stubs: + name: Static API stubs + runs-on: ubuntu-latest + needs: + - run-if-changes + if: always() && needs.run-if-changes.outputs.run == 'true' + steps: + - uses: actions/checkout@v7 + + - uses: actions/setup-python@v7 + with: + python-version: "3.13" + cache: pip + + - name: Install UltraPlot and typing tools + run: pip install -e ".[typing]" + + - name: Verify generated stubs + run: python tools/generate_stubs.py --check + + - name: Check Pylance-compatible consumption + run: basedpyright tools/ci/stub_consumer.py --level error + + - name: Check Pyrefly consumption and generated syntax + run: | + pyrefly check tools/ci/stub_consumer.py \ + --search-path . \ + --python-interpreter-path "$(command -v python)" \ + --progress-bar no + pyrefly check 'ultraplot/**/*.pyi' \ + --search-path . \ + --python-interpreter-path "$(command -v python)" \ + --ignore-missing-imports icecream \ + --ignore-missing-imports matplotlib.fontconfig_pattern \ + --progress-bar no + coverage: name: Coverage runs-on: ubuntu-latest @@ -213,6 +251,7 @@ jobs: needs: - build - run-if-changes + - stubs if: always() runs-on: ubuntu-latest steps: @@ -220,7 +259,7 @@ jobs: if [[ '${{ needs.run-if-changes.outputs.run }}' == 'false' ]]; then echo "No changes detected, tests skipped." else - if [[ '${{ needs.build.result }}' == 'success' ]]; then + if [[ '${{ needs.build.result }}' == 'success' && '${{ needs.stubs.result }}' == 'success' ]]; then echo "All tests passed successfully!" else echo "Tests failed!" diff --git a/docs/contributing.rst b/docs/contributing.rst index 6ccc4cc9c..e98b7d1a4 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -130,6 +130,37 @@ When adding a new submodule, make sure it is compatible with the lazy loader: By following these steps, your module will integrate cleanly with the lazy loading system without requiring manual registry updates. +Editor type information and docstrings +-------------------------------------- + +UltraPlot ships generated ``.pyi`` files so static analysis tools such as Pylance +and Pyrefly can see the public API and fully expanded docstrings without importing +the package. The runtime modules remain the source of truth and continue to use the +lazy loader. + +After changing a Python signature, annotation, public import, or docstring snippet, +install the pinned typing tools, regenerate the stubs from the repository root, and +commit the updated ``.pyi`` files: + +.. code-block:: bash + + pip install -e ".[typing]" + python tools/generate_stubs.py + +Installation does not generate or modify these files. Release artifacts include the +stubs that were generated and checked into the repository. The generator runs +Pyrefly against an isolated source-only package, merges its inferred annotations +into a complete syntax-derived representation of the package, and statically +expands registered docstring snippets. This preserves declarations that Pyrefly +cannot discover through decorators or lazy loading. + +To rerun inference and verify that every committed stub is up to date without +changing files, run: + +.. code-block:: bash + + python tools/generate_stubs.py --check + .. _contrib_pr: diff --git a/pyproject.toml b/pyproject.toml index b4f047456..d58800c69 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -50,7 +50,7 @@ packages = {find = {exclude=["docs*", "baseline*", "logo*"]}} include-package-data = true [tool.setuptools.package-data] -ultraplot = ["py.typed"] +ultraplot = ["py.typed", "*.pyi", "**/*.pyi"] [tool.setuptools_scm] write_to = "ultraplot/_version.py" @@ -74,6 +74,10 @@ filterwarnings = [ ] mpl-default-style = { axes.prop_cycle = "cycler('color', ['#4c72b0ff', '#55a868ff', '#c44e52ff', '#8172b2ff', '#ccb974ff', '#64b5cdff'])" } [project.optional-dependencies] +typing = [ + "basedpyright==1.31.4", + "pyrefly==1.2.0", +] docs = [ "jupyter", "jupytext", diff --git a/tools/ci/stub_consumer.py b/tools/ci/stub_consumer.py new file mode 100644 index 000000000..717362aae --- /dev/null +++ b/tools/ci/stub_consumer.py @@ -0,0 +1,6 @@ +"""Representative lazy public imports consumed by static type checkers.""" + +import ultraplot as uplt + +reveal_type(uplt.subplots) +reveal_type(uplt.Axes.format) diff --git a/tools/generate_stubs.py b/tools/generate_stubs.py new file mode 100644 index 000000000..bdfbb3c62 --- /dev/null +++ b/tools/generate_stubs.py @@ -0,0 +1,723 @@ +"""Generate bundled type stubs with statically expanded docstrings.""" + +from __future__ import annotations + +import argparse +import ast +import builtins +import copy +import os +import re +import shutil +import subprocess +import sys +import tempfile +import warnings +from collections import defaultdict, deque +from collections.abc import Iterable +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +PACKAGE = ROOT / "ultraplot" +HEADER = "# @generated by tools/generate_stubs.py; do not edit\n# fmt: off\n" +VERSION_STUB = "__version__: str\n" +PYREFLY_VERSION = "1.2.0" +EXCLUDED_PARTS = {"tests", "results", "__pycache__"} +STATIC_DECORATORS = { + "abstractmethod", + "asynccontextmanager", + "cached_property", + "classmethod", + "contextmanager", + "dataclass", + "deprecated", + "final", + "getter", + "overload", + "override", + "property", + "setter", + "deleter", + "singledispatch", + "singledispatchmethod", + "staticmethod", +} +SNIPPET_PATTERN = re.compile(r"%\(([^)]+)\)s") +BUILTIN_NAMES = set(dir(builtins)) | {"None"} +TRY_NODES = (ast.Try,) + ((ast.TryStar,) if hasattr(ast, "TryStar") else ()) + + +def _dotted_name(node: ast.expr) -> str | None: + """Return the dotted name represented by an expression.""" + if isinstance(node, ast.Call): + node = node.func + names = [] + while isinstance(node, ast.Attribute): + names.append(node.attr) + node = node.value + if isinstance(node, ast.Name): + names.append(node.id) + return ".".join(reversed(names)) + return None + + +def _is_overload(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool: + """Return whether a function is an overload declaration.""" + return any( + (_dotted_name(item) or "").split(".")[-1] == "overload" + for item in node.decorator_list + ) + + +def _has_decorator( + node: ast.FunctionDef | ast.AsyncFunctionDef, name: str +) -> bool: + """Return whether a function has a decorator with the given final name.""" + return any( + (_dotted_name(item) or "").split(".")[-1] == name + for item in node.decorator_list + ) + + +def _is_simple_target(node: ast.expr) -> bool: + """Return whether an assignment target is declarative stub syntax.""" + if isinstance(node, ast.Name): + return True + if isinstance(node, (ast.List, ast.Tuple)): + return all(_is_simple_target(item) for item in node.elts) + return False + + +def _target_names(node: ast.expr) -> list[str]: + """Return names contained in a simple assignment target.""" + if isinstance(node, ast.Name): + return [node.id] + if isinstance(node, (ast.List, ast.Tuple)): + return [name for item in node.elts for name in _target_names(item)] + return [] + + +def _is_unstable_expression(node: ast.expr) -> bool: + """Return whether ``ast.unparse`` changed for this expression by version.""" + unstable = ( + ast.DictComp, + ast.GeneratorExp, + ast.JoinedStr, + ast.Lambda, + ast.ListComp, + ast.SetComp, + ) + return any(isinstance(item, unstable) for item in ast.walk(node)) + + +def _is_type_checking(node: ast.expr) -> bool: + """Return whether *node* is a ``TYPE_CHECKING`` guard.""" + return (isinstance(node, ast.Name) and node.id == "TYPE_CHECKING") or ( + isinstance(node, ast.Attribute) and node.attr == "TYPE_CHECKING" + ) + + +def _is_docstring_statement(node: ast.stmt) -> bool: + """Return whether *node* is a module/class/function docstring statement.""" + return ( + isinstance(node, ast.Expr) + and isinstance(node.value, ast.Constant) + and isinstance(node.value.value, str) + ) + + +def _scope_statements(statements: list[ast.stmt]): + """Yield declarations from module/class scopes, including guarded branches.""" + for statement in statements: + yield statement + if isinstance(statement, ast.If): + yield from _scope_statements(statement.body) + yield from _scope_statements(statement.orelse) + elif isinstance(statement, TRY_NODES): + yield from _scope_statements(statement.body) + yield from _scope_statements(statement.orelse) + yield from _scope_statements(statement.finalbody) + for handler in statement.handlers: + yield from _scope_statements(handler.body) + + +def _declarations(statements: list[ast.stmt], prefix: tuple[str, ...] = ()): + """Yield qualified function declarations without descending into functions.""" + for statement in _scope_statements(statements): + if isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef)): + yield ".".join((*prefix, statement.name)), statement + elif isinstance(statement, ast.ClassDef): + yield from _declarations(statement.body, (*prefix, statement.name)) + + +def _parameter_names(node: ast.FunctionDef | ast.AsyncFunctionDef) -> tuple[str, ...]: + """Return a signature key that distinguishes overloads and parameter kinds.""" + arguments = node.args + return ( + *(f"pos:{arg.arg}" for arg in (*arguments.posonlyargs, *arguments.args)), + *((f"var:{arguments.vararg.arg}",) if arguments.vararg else ()), + *(f"kw:{arg.arg}" for arg in arguments.kwonlyargs), + *((f"vkw:{arguments.kwarg.arg}",) if arguments.kwarg else ()), + ) + + +def _module_names(tree: ast.Module) -> set[str]: + """Return names that inferred annotations may safely reference in a stub.""" + names = set(BUILTIN_NAMES) + + def collect(statements: list[ast.stmt]): + for statement in _scope_statements(statements): + if isinstance(statement, ast.Import): + names.update( + alias.asname or alias.name.split(".")[0] + for alias in statement.names + ) + elif isinstance(statement, ast.ImportFrom): + names.update(alias.asname or alias.name for alias in statement.names) + elif isinstance( + statement, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef) + ): + names.add(statement.name) + if isinstance(statement, ast.ClassDef): + collect(statement.body) + elif isinstance(statement, ast.Assign): + for target in statement.targets: + names.update(_target_names(target)) + elif isinstance(statement, ast.AnnAssign): + names.update(_target_names(statement.target)) + + collect(tree.body) + names.add("Incomplete") + return names + + +class _AnnotationNameCollector(ast.NodeVisitor): + """Collect names, including names hidden inside forward-reference strings.""" + + def __init__(self): + self.names = set() + self._literal_depth = 0 + + def visit_Name(self, node: ast.Name) -> None: + if isinstance(node.ctx, ast.Load): + self.names.add(node.id) + + def visit_Constant(self, node: ast.Constant) -> None: + if not isinstance(node.value, str) or self._literal_depth: + return + try: + expression = ast.parse(node.value, mode="eval") + except SyntaxError: + return + self.names.update( + item.id + for item in ast.walk(expression) + if isinstance(item, ast.Name) and isinstance(item.ctx, ast.Load) + ) + + def visit_Subscript(self, node: ast.Subscript) -> None: + self.visit(node.value) + is_literal = (_dotted_name(node.value) or "").split(".")[-1] == "Literal" + self._literal_depth += is_literal + self.visit(node.slice) + self._literal_depth -= is_literal + + +def _safe_annotation(annotation: ast.expr | None, available: set[str]) -> ast.expr | None: + """Return a copied inferred annotation only when all root names resolve.""" + if annotation is None: + return None + if isinstance(annotation, (ast.Dict, ast.List, ast.Set, ast.Tuple)): + return None + collector = _AnnotationNameCollector() + collector.visit(annotation) + if collector.names <= available: + return copy.deepcopy(annotation) + return None + + +def _missing_annotation() -> ast.Name: + """Return the typing-spec placeholder used for an unknown annotation.""" + return ast.Name(id="Incomplete", ctx=ast.Load()) + + +def _merge_annotations( + tree: ast.Module, inferred: ast.Module | None +) -> tuple[int, int, int, int]: + """Fill missing source annotations using matching Pyrefly declarations. + + Explicit source annotations always win. If Pyrefly omitted a declaration or + inferred a name that is not available in the module, ``Incomplete`` is used + as the honest static placeholder recommended for generated stubs. + """ + candidates = defaultdict(deque) + if inferred is not None: + for qualname, node in _declarations(inferred.body): + candidates[(qualname, _parameter_names(node))].append(node) + + available = _module_names(tree) + inferred_count = fallback_count = unmatched_count = discarded_count = 0 + for qualname, node in _declarations(tree.body): + queue = candidates.get((qualname, _parameter_names(node))) + inferred_node = queue.popleft() if queue else None + if inferred_node is None: + unmatched_count += 1 + + source_args = ( + *node.args.posonlyargs, + *node.args.args, + *node.args.kwonlyargs, + ) + # Inferences copied from an overridden third-party method change with + # the installed dependency version. Keep only explicit source types for + # overrides so generation remains reproducible across supported envs. + use_inference = inferred_node is not None and not _has_decorator( + node, "override" + ) + inferred_args = () + if use_inference: + inferred_args = ( + *inferred_node.args.posonlyargs, + *inferred_node.args.args, + *inferred_node.args.kwonlyargs, + ) + inferred_by_name = {arg.arg: arg for arg in inferred_args} + for argument in source_args: + if argument.arg in {"self", "cls"}: + continue + if argument.annotation is not None: + annotation = _safe_annotation(argument.annotation, available) + if annotation is not None: + continue + argument.annotation = None + discarded_count += 1 + annotation = _safe_annotation( + inferred_by_name.get(argument.arg).annotation + if argument.arg in inferred_by_name + else None, + available, + ) + argument.annotation = annotation or _missing_annotation() + inferred_count += annotation is not None + fallback_count += annotation is None + + for source_arg, inferred_arg in ( + ( + node.args.vararg, + inferred_node.args.vararg if use_inference else None, + ), + (node.args.kwarg, inferred_node.args.kwarg if use_inference else None), + ): + if source_arg is None: + continue + if source_arg.annotation is not None: + annotation = _safe_annotation(source_arg.annotation, available) + if annotation is not None: + continue + source_arg.annotation = None + discarded_count += 1 + annotation = _safe_annotation( + inferred_arg.annotation if inferred_arg else None, available + ) + source_arg.annotation = annotation or _missing_annotation() + inferred_count += annotation is not None + fallback_count += annotation is None + + if node.returns is not None and _safe_annotation(node.returns, available) is None: + node.returns = None + discarded_count += 1 + if node.returns is None: + if node.name == "__init__": + node.returns = ast.Constant(None) + inferred_count += 1 + else: + annotation = _safe_annotation( + inferred_node.returns if use_inference else None, available + ) + node.returns = annotation or _missing_annotation() + inferred_count += annotation is not None + fallback_count += annotation is None + return inferred_count, fallback_count, unmatched_count, discarded_count + + +def _pyrefly_version(executable: str) -> str: + """Return the installed Pyrefly version or raise an actionable error.""" + result = subprocess.run( + [executable, "--version"], capture_output=True, text=True, check=True + ) + match = re.search(r"\b(\d+\.\d+\.\d+)\b", result.stdout + result.stderr) + if not match: + raise RuntimeError(f"Could not determine Pyrefly version from: {result.stdout!r}") + return match.group(1) + + +def _run_pyrefly(executable: str) -> tuple[dict[Path, ast.Module], list[Path]]: + """Run Pyrefly on a source-only package and parse its inferred stubs.""" + version = _pyrefly_version(executable) + if version != PYREFLY_VERSION: + raise RuntimeError( + f"Stub generation requires pyrefly=={PYREFLY_VERSION}; found {version}. " + f"Install with `python -m pip install pyrefly=={PYREFLY_VERSION}`." + ) + print(f"Running Pyrefly {version} type inference on a source-only package copy...") + with tempfile.TemporaryDirectory(prefix="ultraplot-stubgen-") as directory: + temporary = Path(directory) + source_root = temporary / "source" + source_package = source_root / PACKAGE.name + output_root = temporary / "inferred" + shutil.copytree( + PACKAGE, + source_package, + ignore=shutil.ignore_patterns( + "*.pyi", "tests", "results", "__pycache__", "*.pyc" + ), + ) + command = [ + executable, + "stubgen", + str(source_package), + "--output-dir", + str(output_root), + "--include-docstrings", + "--include-private", + "--threads", + "0", + "--search-path", + str(source_root), + "--python-interpreter-path", + sys.executable, + "--check-unannotated-defs", + "true", + "--infer-return-types", + "checked", + ] + result = subprocess.run( + command, cwd=ROOT, capture_output=True, text=True, check=False + ) + if result.returncode: + details = (result.stdout + "\n" + result.stderr).strip() + raise RuntimeError(f"Pyrefly stub generation failed:\n{details}") + + trees = {} + invalid = [] + for source_path in _source_files(): + relative = source_path.relative_to(PACKAGE).with_suffix(".pyi") + inferred_path = output_root / relative + if not inferred_path.exists(): + continue + try: + with warnings.catch_warnings(): + warnings.simplefilter("ignore", SyntaxWarning) + trees[source_path] = ast.parse( + inferred_path.read_text(), filename=str(inferred_path) + ) + except SyntaxError: + # Pyrefly 1.2.0 currently emits invalid ``((x: T) -> U)`` syntax + # for one callable assignment in rcsetup.py. The structural base + # and Incomplete fallbacks keep that module valid and complete. + invalid.append(relative) + return trees, invalid + + +class _StubTransformer(ast.NodeTransformer): + """Reduce implementation syntax to declarations suitable for ``.pyi`` files.""" + + def __init__(self, expand_docstring): + self._expand_docstring = expand_docstring + + def _decorators(self, nodes: list[ast.expr]) -> list[ast.expr]: + kept = [] + for node in nodes: + name = (_dotted_name(node) or "").split(".")[-1] + if name in STATIC_DECORATORS: + kept.append(node) + return kept + + def _doc_body(self, node: ast.AST) -> list[ast.stmt]: + doc = ast.get_docstring(node, clean=True) + body = [] + if doc: + body.append(ast.Expr(value=ast.Constant(self._expand_docstring(doc)))) + body.append(ast.Expr(value=ast.Constant(Ellipsis))) + return body + + def _scope_body(self, statements: list[ast.stmt]) -> list[ast.stmt]: + overloaded = { + item.name + for item in statements + if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)) + and _is_overload(item) + } + body = [] + for statement in statements: + if ( + isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef)) + and statement.name in overloaded + and not _is_overload(statement) + ): + continue + transformed = self.visit(statement) + if transformed is None: + continue + if isinstance(transformed, list): + body.extend(transformed) + else: + body.append(transformed) + return body + + def visit_Module(self, node: ast.Module) -> ast.Module: + node.body = self._scope_body(node.body) + insertion = int(bool(node.body) and _is_docstring_statement(node.body[0])) + node.body.insert( + insertion, + ast.ImportFrom( + module="_typeshed", + names=[ast.alias(name="Incomplete")], + level=0, + ), + ) + return node + + def visit_ClassDef(self, node: ast.ClassDef) -> ast.ClassDef: + node.decorator_list = self._decorators(node.decorator_list) + node.body = self._scope_body(node.body) + if not node.body: + node.body = [ast.Expr(value=ast.Constant(Ellipsis))] + return node + + def visit_FunctionDef(self, node: ast.FunctionDef) -> ast.FunctionDef: + node.decorator_list = self._decorators(node.decorator_list) + node.body = self._doc_body(node) + return node + + def visit_AsyncFunctionDef( + self, node: ast.AsyncFunctionDef + ) -> ast.AsyncFunctionDef: + node.decorator_list = self._decorators(node.decorator_list) + node.body = self._doc_body(node) + return node + + def visit_Expr(self, node: ast.Expr) -> ast.Expr | None: + if isinstance(node.value, ast.Constant) and isinstance(node.value.value, str): + value = self._expand_docstring(node.value.value) + return ast.Expr(value=ast.Constant(value)) + return None + + def visit_Assign(self, node: ast.Assign) -> ast.Assign | None: + if all(_is_simple_target(target) for target in node.targets): + names = [name for target in node.targets for name in _target_names(target)] + if ( + names and all(name.endswith("_docstring") for name in names) + ) or _is_unstable_expression(node.value): + # Comprehension parentheses, lambda spacing, and f-string quote + # selection changed across supported Python versions. These + # implementation values are irrelevant to static declarations. + node.value = ast.Constant(Ellipsis) + return node + return None + + def visit_AnnAssign(self, node: ast.AnnAssign) -> ast.AnnAssign | None: + if _is_simple_target(node.target): + if node.value is not None and _is_unstable_expression(node.value): + node.value = ast.Constant(Ellipsis) + return node + return None + + def visit_AugAssign(self, node: ast.AugAssign) -> None: + return None + + def visit_If(self, node: ast.If) -> ast.If | list[ast.stmt] | None: + if _is_type_checking(node.test): + return self._scope_body(node.body) + node.body = self._scope_body(node.body) + node.orelse = self._scope_body(node.orelse) + if not node.body: + return node.orelse or None + return node + + def visit_Try(self, node: ast.Try) -> ast.Try | list[ast.stmt] | None: + node.body = self._scope_body(node.body) + node.orelse = self._scope_body(node.orelse) + node.finalbody = self._scope_body(node.finalbody) + for handler in node.handlers: + handler.body = self._scope_body(handler.body) + if not node.body: + return [item for handler in node.handlers for item in handler.body] or None + return node + + def visit_For(self, node: ast.For) -> None: + return None + + def visit_AsyncFor(self, node: ast.AsyncFor) -> None: + return None + + def visit_While(self, node: ast.While) -> None: + return None + + def visit_With(self, node: ast.With) -> None: + return None + + def visit_AsyncWith(self, node: ast.AsyncWith) -> None: + return None + + def visit_Match(self, node: ast.Match) -> None: + return None + + def visit_ImportFrom(self, node: ast.ImportFrom) -> ast.ImportFrom | None: + # Future annotations are unnecessary in stubs, and both Pylance and + # Pyrefly require future imports to precede generated module docstrings. + if node.module == "__future__": + return None + return node + + +def _source_files() -> Iterable[Path]: + """Yield Python implementation files included in the distributed package.""" + for path in sorted(PACKAGE.rglob("*.py")): + if not EXCLUDED_PARTS.intersection(path.parts): + yield path + + +def _snippet_expander(): + """Return a function that expands all registered UltraPlot snippets.""" + os.environ.setdefault("MPLCONFIGDIR", "/tmp/ultraplot-matplotlib") + sys.path.insert(0, str(ROOT)) + from ultraplot.internals.docstring import _snippet_manager + + def expand(doc: str) -> str: + def replace(match: re.Match) -> str: + key = match.group(1) + try: + return str(_snippet_manager[key]) + except KeyError: + # Some internal helper docstrings explain the placeholder syntax. + return match.group(0) + + previous = None + while previous != doc: + previous = doc + doc = SNIPPET_PATTERN.sub(replace, doc) + return doc + + return expand + + +def _render( + source_path: Path, expand_docstring, inferred: ast.Module | None +) -> tuple[str, tuple[int, int, int, int]]: + """Render one implementation module as a deterministic type stub.""" + if source_path == PACKAGE / "_version.py": + # setuptools-scm rewrites this module while building each commit. Its + # public interface is stable even though the assigned value is not. + return HEADER + VERSION_STUB, (0, 0, 0, 0) + source = source_path.read_text() + tree = ast.parse(source, filename=str(source_path)) + annotation_counts = _merge_annotations(tree, inferred) + tree = _StubTransformer(expand_docstring).visit(copy.deepcopy(tree)) + ast.fix_missing_locations(tree) + rendered = ast.unparse(tree).rstrip() + "\n" + return HEADER + rendered, annotation_counts + + +def _stub_path(source_path: Path) -> Path: + return source_path.with_suffix(".pyi") + + +def _is_generated_stub(path: Path) -> bool: + try: + return path.read_text().startswith(HEADER.splitlines()[0]) + except OSError: + return False + + +def main(argv: list[str] | None = None) -> int: + """Generate bundled stubs, or report stale output with ``--check``.""" + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--check", action="store_true") + parser.add_argument( + "--pyrefly", + help="Pyrefly executable (default: resolve `pyrefly` from PATH)", + ) + args = parser.parse_args(argv) + + executable = args.pyrefly or shutil.which("pyrefly") + if not executable: + parser.error( + f"pyrefly=={PYREFLY_VERSION} is required; install the `typing` extra " + "or pass --pyrefly PATH" + ) + try: + inferred_trees, invalid_inference = _run_pyrefly(executable) + except (OSError, subprocess.SubprocessError, RuntimeError) as error: + parser.error(str(error)) + + expand_docstring = _snippet_expander() + source_files = list(_source_files()) + expected = set() + changed = [] + inferred_count = fallback_count = unmatched_count = discarded_count = 0 + if args.check: + print(f"Checking {len(source_files)} source modules and their stubs...") + for source_path in source_files: + stub_path = _stub_path(source_path) + expected.add(stub_path) + rendered, counts = _render( + source_path, expand_docstring, inferred_trees.get(source_path) + ) + inferred_count += counts[0] + fallback_count += counts[1] + unmatched_count += counts[2] + discarded_count += counts[3] + current = stub_path.read_text() if stub_path.exists() else None + if current == rendered: + continue + changed.append(stub_path) + if not args.check: + stub_path.write_text(rendered) + + obsolete = [ + path + for path in PACKAGE.rglob("*.pyi") + if path not in expected and _is_generated_stub(path) + ] + if not args.check: + for path in obsolete: + path.unlink() + + for path in changed: + action = "Stale" if args.check else "Generated" + print(f"{action}: {path.relative_to(ROOT)}") + for path in obsolete: + action = "Obsolete" if args.check else "Removed" + print(f"{action}: {path.relative_to(ROOT)}") + print( + f"Annotation merge: {inferred_count} inferred, " + f"{fallback_count} marked Incomplete; " + f"{discarded_count} invalid source annotations replaced; " + f"{unmatched_count} source declarations absent from Pyrefly output." + ) + if invalid_inference: + print( + "Pyrefly output skipped after syntax validation: " + + ", ".join(str(path) for path in invalid_inference) + ) + if args.check: + if changed or obsolete: + count = len(changed) + len(obsolete) + print( + f"Check failed: {count} stale or obsolete stub(s). " + "Run `python tools/generate_stubs.py` to update them." + ) + else: + print(f"Checked {len(expected)} stubs: all up to date.") + else: + unchanged = len(expected) - len(changed) + print( + f"Stub generation complete: {len(changed)} updated, " + f"{unchanged} unchanged, {len(obsolete)} obsolete removed." + ) + return int(args.check and bool(changed or obsolete)) + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/ultraplot/__init__.pyi b/ultraplot/__init__.pyi new file mode 100644 index 000000000..3ed33ba41 --- /dev/null +++ b/ultraplot/__init__.pyi @@ -0,0 +1,177 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +A succinct matplotlib wrapper for making beautiful, publication-quality graphics. +""" +from _typeshed import Incomplete +import sys +from pathlib import Path +from typing import TYPE_CHECKING, Optional +from ._lazy import LazyLoader, install_module_proxy +import matplotlib.pyplot as pyplot +from .animation import ArtistAnimation as ArtistAnimation +from .animation import FuncAnimation as FuncAnimation +from .axes import Axes as Axes +from .axes import CartesianAxes as CartesianAxes +from .axes import ExternalAxesContainer as ExternalAxesContainer +from .axes import GeoAxes as GeoAxes +from .axes import PlotAxes as PlotAxes +from .axes import PolarAxes as PolarAxes +from .axes import TaylorAxes as TaylorAxes +from .axes import ThreeAxes as ThreeAxes +from .colors import ColormapDatabase as ColormapDatabase +from .colors import ColorDatabase as ColorDatabase +from .colors import ContinuousColormap as ContinuousColormap +from .colors import DiscreteColormap as DiscreteColormap +from .colors import DiscreteNorm as DiscreteNorm +from .colors import DivergingNorm as DivergingNorm +from .colors import PerceptualColormap as PerceptualColormap +from .colors import SegmentedNorm as SegmentedNorm +from .colors import _cmap_database as colormaps +from .config import config_inline_backend as config_inline_backend +from .config import Configurator as Configurator +from .config import rc as rc +from .config import rc_matplotlib as rc_matplotlib +from .config import rc_ultraplot as rc_ultraplot +from .config import register_cmaps as register_cmaps +from .config import register_colors as register_colors +from .config import register_cycles as register_cycles +from .config import register_fonts as register_fonts +from .config import use_style as use_style +from .constructor import Colormap as Colormap +from .constructor import Cycle as Cycle +from .constructor import Formatter as Formatter +from .constructor import FORMATTERS as FORMATTERS +from .constructor import Locator as Locator +from .constructor import LOCATORS as LOCATORS +from .constructor import Norm as Norm +from .constructor import NORMS as NORMS +from .constructor import Proj as Proj +from .constructor import PROJS as PROJS +from .constructor import Scale as Scale +from .constructor import SCALES as SCALES +from .demos import show_channels as show_channels +from .demos import show_cmaps as show_cmaps +from .demos import show_colorspaces as show_colorspaces +from .demos import show_colors as show_colors +from .demos import show_cycles as show_cycles +from .demos import show_fonts as show_fonts +from .figure import Figure as Figure +from .gridspec import GridSpec as GridSpec +from .gridspec import SubplotGrid as SubplotGrid +from .legend import GeometryEntry as GeometryEntry +from .legend import Legend as Legend +from .legend import LegendEntry as LegendEntry +from .proj import Aitoff as Aitoff +from .proj import Hammer as Hammer +from .proj import KavrayskiyVII as KavrayskiyVII +from .proj import NorthPolarAzimuthalEquidistant as NorthPolarAzimuthalEquidistant +from .proj import NorthPolarGnomonic as NorthPolarGnomonic +from .proj import NorthPolarLambertAzimuthalEqualArea as NorthPolarLambertAzimuthalEqualArea +from .proj import SouthPolarAzimuthalEquidistant as SouthPolarAzimuthalEquidistant +from .proj import SouthPolarGnomonic as SouthPolarGnomonic +from .proj import SouthPolarLambertAzimuthalEqualArea as SouthPolarLambertAzimuthalEqualArea +from .proj import WinkelTripel as WinkelTripel +from .scale import CutoffScale as CutoffScale +from .scale import ExpScale as ExpScale +from .scale import FuncScale as FuncScale +from .scale import InverseScale as InverseScale +from .scale import LinearScale as LinearScale +from .scale import LogitScale as LogitScale +from .scale import LogScale as LogScale +from .scale import MercatorLatitudeScale as MercatorLatitudeScale +from .scale import PowerScale as PowerScale +from .scale import SineLatitudeScale as SineLatitudeScale +from .scale import SymmetricalLogScale as SymmetricalLogScale +from .text import CurvedText as CurvedText +from .textalign import align_text as align_text +from .ultralayout import ColorbarLayoutSolver as ColorbarLayoutSolver +from .ultralayout import compute_ultra_positions as compute_ultra_positions +from .ultralayout import get_grid_positions_ultra as get_grid_positions_ultra +from .ultralayout import is_orthogonal_layout as is_orthogonal_layout +from .ultralayout import UltraLayoutSolver as UltraLayoutSolver +from .ticker import AutoCFDatetimeFormatter as AutoCFDatetimeFormatter +from .ticker import AutoCFDatetimeLocator as AutoCFDatetimeLocator +from .ticker import AutoFormatter as AutoFormatter +from .ticker import CFDatetimeFormatter as CFDatetimeFormatter +from .ticker import DegreeFormatter as DegreeFormatter +from .ticker import DegreeLocator as DegreeLocator +from .ticker import DiscreteLocator as DiscreteLocator +from .ticker import FracFormatter as FracFormatter +from .ticker import IndexFormatter as IndexFormatter +from .ticker import IndexLocator as IndexLocator +from .ticker import LatitudeFormatter as LatitudeFormatter +from .ticker import LatitudeLocator as LatitudeLocator +from .ticker import LongitudeFormatter as LongitudeFormatter +from .ticker import LongitudeLocator as LongitudeLocator +from .ticker import SciFormatter as SciFormatter +from .ticker import SigFigFormatter as SigFigFormatter +from .ticker import SimpleFormatter as SimpleFormatter +from .ui import close as close +from .ui import figure as figure +from .ui import ioff as ioff +from .ui import ion as ion +from .ui import isinteractive as isinteractive +from .ui import show as show +from .ui import subplot as subplot +from .ui import subplots as subplots +from .ui import switch_backend as switch_backend +from .utils import arange as arange +from .utils import check_for_update as check_for_update +from .utils import edges as edges +from .utils import edges2d as edges2d +from .utils import get_colors as get_colors +from .utils import scale_luminance as scale_luminance +from .utils import scale_saturation as scale_saturation +from .utils import set_alpha as set_alpha +from .utils import set_hue as set_hue +from .utils import set_luminance as set_luminance +from .utils import set_saturation as set_saturation +from .utils import shift_hue as shift_hue +from .utils import to_hex as to_hex +from .utils import to_rgb as to_rgb +from .utils import to_rgba as to_rgba +from .utils import to_xyz as to_xyz +from .utils import to_xyza as to_xyza +from .utils import units as units +name = 'ultraplot' +try: + from ._version import __version__ +except ImportError: + __version__ = 'unknown' +version = __version__ +_SETUP_DONE = False +_SETUP_RUNNING = False +_EAGER_DONE = False +_EXPOSED_MODULES = set() +_ATTR_MAP = None +_REGISTRY_ATTRS = None +_LAZY_LOADING_EXCEPTIONS = {'constructor': ('constructor', None), 'crs': ('proj', None), 'colormaps': ('colors', '_cmap_database'), 'check_for_update': ('utils', 'check_for_update'), 'NORMS': ('constructor', 'NORMS'), 'LOCATORS': ('constructor', 'LOCATORS'), 'FORMATTERS': ('constructor', 'FORMATTERS'), 'SCALES': ('constructor', 'SCALES'), 'PROJS': ('constructor', 'PROJS'), 'internals': ('internals', None), 'externals': ('externals', None), 'Proj': ('constructor', 'Proj'), 'tests': ('tests', None), 'rcsetup': ('internals', 'rcsetup'), 'warnings': ('internals', 'warnings'), 'figure': ('ui', 'figure'), 'Figure': ('figure', 'Figure'), 'Colormap': ('constructor', 'Colormap'), 'Cycle': ('constructor', 'Cycle'), 'Norm': ('constructor', 'Norm'), 'Locator': ('constructor', 'Locator'), 'Scale': ('constructor', 'Scale'), 'Formatter': ('constructor', 'Formatter')} + +def _setup() -> None: + ... + +def setup(eager: Optional[bool]=None) -> None: + """Initialize registries and optionally import the public API eagerly.""" + ... + +def _build_registry_map() -> None: + ... + +def _get_registry_attr(name: Incomplete) -> None: + ... +_LOADER: LazyLoader = ... + +def __getattr__(name: Incomplete) -> Incomplete: + ... + +def __dir__() -> list[str]: + ... + +def _patch_seaborn_move_legend() -> None: + """Let ``sns.move_legend(ax, ...)`` accept singleton :class:`SubplotGrid` objects. + +Seaborn only accepts native Matplotlib axes, figures, and its own grids. The +wrapper unwraps a singleton grid to its underlying axes; callers can avoid +this compatibility patch by passing ``ax[0]`` directly.""" + ... diff --git a/ultraplot/_animation.pyi b/ultraplot/_animation.pyi new file mode 100644 index 000000000..a0b025a28 --- /dev/null +++ b/ultraplot/_animation.pyi @@ -0,0 +1,315 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Helpers for responsive interactive and animated UltraPlot figures. +""" +from _typeshed import Incomplete +from collections.abc import Iterable +from contextlib import contextmanager +from weakref import WeakSet +import matplotlib.artist as martist +import matplotlib.axis as maxis +import matplotlib.collections as mcollections +import matplotlib.image as mimage +import matplotlib.lines as mlines +import matplotlib.text as mtext +import matplotlib.transforms as mtransforms +import numpy as np +from matplotlib.backend_bases import DrawEvent +from ._interaction import _NavigationInteractionManager +from ._layout import _is_internal_ticker +_POINTS_PER_INCH = 72.0 +_STROKE_HALF_WIDTH = 0.5 +_SQRT2 = np.sqrt(2.0) +_MITER_LIMIT = 4.0 +_BBOX_TOLERANCE = 1e-06 +_MISSING = object() +_OPAQUE_TICKER_TYPES = frozenset(('FuncFormatter', 'FuncScale', 'FuncScaleLog')) + +class _SelectiveDrawManager: + """ + Retain safe draw layers and bypass unchanged Matplotlib traversal. + + Multi-axes figures retain each complete axes as one layer. Single Cartesian + axes retain the stable draw-order prefix below their first clipped numeric + line, then redraw that line and every later artist as an exact z-order suffix. + Unknown stale artists, geometry changes, overlapping layers, unsupported + artist orders, and export draws fall back to a complete draw. The first display + is always untouched; a later complete draw primes the retained layers. + """ + _data_artist_types = (mlines.Line2D, mcollections.Collection, mimage.AxesImage) + _region_pad = 2 + _min_axes_for_view_redraw = 3 + + def __init__(self, canvas: Incomplete, figure: Incomplete=None) -> None: + ... + + @staticmethod + def _bbox_signature(bbox: Incomplete) -> tuple[float, ...]: + ... + + def _axes_signature(self, ax: Incomplete) -> Incomplete: + ... + + @staticmethod + def _ticker_fingerprint(ticker: Incomplete) -> Incomplete: + """Return a value that changes when a locator or formatter is retuned.""" + ... + + @staticmethod + def _ticker_axes(ax: Incomplete) -> Incomplete: + """Return the named axis objects that own locators and formatters.""" + ... + + @classmethod + def _ticker_signature(cls, ax: Incomplete) -> Incomplete: + """Return the tuned state of every locator and formatter on an axes.""" + ... + + @classmethod + def _has_untrusted_ticker(cls, ax: Incomplete) -> bool: + """Return whether any ticker on *ax* can change without being noticed.""" + ... + + def _axes_view_signature(self, ax: Incomplete) -> Incomplete: + """Return paint-only limits, scales, and projection camera state.""" + ... + + def _current_canvas_signature(self) -> tuple[float, tuple[float, ...], float, float, float] | None: + """Return framebuffer properties that invalidate copied pixel regions.""" + ... + + def _view_signature(self, axes: Incomplete=None) -> Incomplete: + """Return the view state last presented by a complete canvas draw.""" + ... + + @staticmethod + def _camera_signature(ax: Incomplete) -> tuple[float, float, float, int, tuple[float, ...], tuple[float, ...], tuple[float, ...], float, tuple[float, ...]] | None: + """Return 3D camera and limits, or ``None`` for ordinary 2D axes.""" + ... + + def _visible_axes(self) -> Incomplete: + ... + + def _has_explicit_blit_manager(self) -> bool: + ... + + def _has_animated_artist(self, axes: Incomplete) -> bool: + ... + + def _figure_overlay_bboxes(self, renderer: Incomplete) -> Incomplete: + """Return display bboxes of figure artists that can paint over an axes, or +``None`` if any of them cannot be measured. + +Every axes queries the same set within one draw pass, so measure the +figure once and let each query reuse it.""" + ... + + def _has_overlapping_figure_artist(self, targets: Incomplete) -> bool: + """Return whether a figure artist overlaps retained artists or regions.""" + ... + + @staticmethod + def _bbox_contains(outer: Incomplete, inner: Incomplete, tolerance: Incomplete=_BBOX_TOLERANCE) -> Incomplete: + ... + + def _suffix_fits_region(self, suffix: Incomplete, region: Incomplete, renderer: Incomplete) -> bool: + """Return whether restoring *region* clears every suffix paint extent.""" + ... + + @staticmethod + def _has_numeric_line_data(line: Incomplete) -> bool: + """Return whether line conversion cannot mutate categorical/date axes.""" + ... + + def _resolve_line_suffix(self, ax: Incomplete) -> Incomplete: + """Return the exact draw-order suffix starting at the first data line.""" + ... + + @staticmethod + def _max_concurrent(intervals: Incomplete) -> int: + """Return the largest number of intervals open at any one coordinate.""" + ... + + @classmethod + def _regions_overlap(cls, regions: Incomplete) -> bool: + """Return whether any two regions share a positive-area intersection.""" + ... + _bounded_path_effects = frozenset(('Normal', 'Stroke', 'withStroke')) + + @classmethod + def _path_effect_overhang(cls, artist: Incomplete, dpi: Incomplete) -> float | None: + """Return pixels *artist*'s path effects add, or ``None`` if unbounded.""" + ... + + @staticmethod + def _has_miter_join(artist: Incomplete) -> bool: + """Return whether *artist* joins segments with an unbounded miter.""" + ... + + @classmethod + def _stroke_overhang(cls, artist: Incomplete, dpi: Incomplete) -> Incomplete: + """Return pixels *artist* can paint beyond its measured extent.""" + ... + + def _expand_for_overhang(self, ax: Incomplete, renderer: Incomplete, region: Incomplete) -> Incomplete: + """Grow an already padded *region* to cover strokes painting past their +measured extents. Artist extents carry the same safety pad, so the result +clears every painted pixel by ``_region_pad`` on all sides.""" + ... + + def _region_signature(self, ax: Incomplete) -> Incomplete: + """Return a cheap key for a resolved region, or ``None`` if unusable.""" + ... + + def _resolve_region(self, ax: Incomplete, renderer: Incomplete, cached_regions: Incomplete) -> Incomplete: + ... + + @staticmethod + def _mark_axes_clean(axes: Incomplete) -> None: + """Clear placeholder staleness left behind by ``Axes.draw()``.""" + ... + + def invalidate(self) -> None: + """Discard all retained axes layers.""" + ... + + def _on_resize(self, event: Incomplete) -> None: + ... + + def _on_draw(self, event: Incomplete) -> None: + ... + + @contextmanager + def full_draw_context(self) -> Incomplete: + """Temporarily split a full draw into static and axes layers.""" + ... + + def _dirty_axes(self) -> Incomplete: + ... + + def _damage_closure(self, dirty: Incomplete, damage: Incomplete) -> Incomplete: + """Expand damage to intersecting axes and preserve figure-level order.""" + ... + + def _view_damage(self, dirty: Incomplete, renderer: Incomplete) -> Incomplete: + """Resolve exact damage after view changes and axes needing repaint.""" + ... + + def draw_if_possible(self) -> bool: + """Use retained axes layers for paint-only data changes.""" + ... + + @contextmanager + def save_context(self) -> Incomplete: + """Suspend retained drawing while producing external output.""" + ... + + def close(self) -> None: + ... + +class _BlitManager: + """ + Manage efficient updates of a small set of changing artists. + + The manager caches the static canvas background, restores it for each + update, redraws only the managed artists, and blits the affected region. + Backends without blitting support safely fall back to ``draw_idle()``. + + Parameters + ---------- + canvas : `~matplotlib.backend_bases.FigureCanvasBase` + Canvas containing the artists. + artists : iterable of `~matplotlib.artist.Artist`, optional + Artists that will change between updates. + bbox : `~matplotlib.transforms.Bbox` or object with a ``bbox`` attribute, optional + Region to cache and blit. By default, the union of the managed artists' + axes bounding boxes is used. Figure-level artists fall back to the full + figure bounding box. + + Notes + ----- + Managed artists are drawn above the cached static background, matching + Matplotlib's standard blitting behavior. + """ + + def __init__(self, canvas: Incomplete, artists: Iterable[martist.Artist]=(), bbox: Incomplete=None) -> None: + ... + + @property + def artists(self) -> Incomplete: + """Managed artists as an immutable tuple.""" + ... + + @property + def supports_blit(self) -> bool: + """Whether the associated canvas supports blitting.""" + ... + + def _resolve_bbox(self) -> Incomplete: + ... + + def _draw_artists(self) -> None: + ... + + def _on_draw(self, event: Incomplete) -> None: + ... + + def _on_resize(self, event: Incomplete) -> None: + ... + + def add_artist(self, artist: martist.Artist) -> Incomplete: + """Add an artist to the managed update set. + +Returns +------- +_BlitManager + This manager, to permit chained calls.""" + ... + + def remove_artist(self, artist: martist.Artist) -> Incomplete: + """Stop managing an artist and restore its original animated state. + +Returns +------- +_BlitManager + This manager, to permit chained calls.""" + ... + + def invalidate(self) -> None: + """Discard the cached background before the next update.""" + ... + + @contextmanager + def _save_context(self) -> Incomplete: + """Temporarily restore original artist states for a complete export.""" + ... + + def update(self, *, flush: Incomplete=False) -> bool: + """Redraw the managed artists. + +Parameters +---------- +flush : bool, default: False + Whether to immediately process pending GUI events after blitting. + +Returns +------- +bool + ``True`` when the blitting fast path was used, otherwise ``False``.""" + ... + + def close(self, *, redraw: Incomplete=True) -> None: + """Disconnect callbacks and restore the artists' animated states. + +Parameters +---------- +redraw : bool, default: True + Whether to schedule a normal full redraw after restoring the artists.""" + ... + + def __enter__(self) -> Incomplete: + ... + + def __exit__(self, exc_type: Incomplete, exc: Incomplete, traceback: Incomplete) -> None: + ... diff --git a/ultraplot/_interaction.pyi b/ultraplot/_interaction.pyi new file mode 100644 index 000000000..dfccd1ed2 --- /dev/null +++ b/ultraplot/_interaction.pyi @@ -0,0 +1,212 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +"""Private helpers for responsive interactive figure navigation.""" +from _typeshed import Incomplete +from contextlib import contextmanager +from dataclasses import dataclass, field +import time +import matplotlib.collections as mcollections +import numpy as np +from matplotlib.backend_bases import TimerBase +from matplotlib.ticker import MaxNLocator, NullLocator +_MISSING = object() +_MIN_PREVIEW_SURFACE_CELLS = 625 +_PREVIEW_SURFACE_SAMPLES = 10 +_PREVIEW_TICK_COUNT = 3 +_TARGET_FRAME_RATE = 60 +_MS_PER_SECOND = 1000 + +def _preview_enabled() -> Incomplete: + """Return the current runtime setting for approximate navigation frames.""" + ... + +def _state_equal(left: Incomplete, right: Incomplete) -> bool: + """Return whether an artist property still matches our preview value.""" + ... + +@dataclass +class _LocatorPreviewState: + """Exact and temporary locators for one axis.""" + axis: object + original_major: object + original_minor: object + preview_major: object + preview_minor: object + + def restore(self) -> None: + ... + +@dataclass +class _LinePreviewState: + """Exact and sampled data for one line artist.""" + artist: object + original: tuple + preview: tuple + dimensions: str + + def restore(self) -> None: + ... + +@dataclass +class _ScatterPreviewState: + """Exact and sampled private collection fields for one scatter artist.""" + artist: object + original: dict + preview: dict + + def restore(self) -> None: + ... + +@dataclass +class _SurfacePreviewState: + """Temporary surface proxy attachment and draw-suppression state.""" + artist: object + proxy: object + ax: object + proxy_attached: bool + proxy_visible: bool + hidden_marker: object + + def restore(self) -> None: + ... + +@dataclass +class _AxesPreviewState: + """All temporary navigation state owned for one axes.""" + ax: object + grid_marker: object = _MISSING + locators: list = field(default_factory=list) + lines: list = field(default_factory=list) + scatters: list = field(default_factory=list) + surfaces: list = field(default_factory=list) + restored: bool = False + + def restore(self) -> None: + ... + +@dataclass +class _SurfaceProxyRecipe: + """Lazy recipe for a coarse surface used only during navigation.""" + arrays: tuple + args: tuple + kwargs: dict + geometry_signature: tuple + facecolor_signature: tuple + proxy: object = None + +def _surface_geometry_signature(surface: Incomplete) -> Incomplete: + ... + +def _surface_facecolor_signature(surface: Incomplete) -> Incomplete: + ... + +def _register_surface_preview(surface: Incomplete, X: Incomplete, Y: Incomplete, Z: Incomplete, args: Incomplete, kwargs: Incomplete) -> None: + """Attach a lazy coarse-surface recipe without constructing another artist.""" + ... + +def _sync_surface_proxy(surface: Incomplete, proxy: Incomplete) -> None: + """Copy safe presentation properties from an exact surface to its proxy.""" + ... + +def _prepare_surface_preview(surface: Incomplete) -> Incomplete: + """Synchronize an attached proxy and return whether to suppress the exact one.""" + ... + +def _resolve_surface_proxy(surface: Incomplete) -> Incomplete: + """Create or return a valid lazy surface proxy for an exact collection.""" + ... + +class _FramePacer: + """Coalesce GUI draws and submit the newest view near a 60 Hz cadence.""" + _interval = 1 / _TARGET_FRAME_RATE + + def __init__(self, canvas: Incomplete, is_active: Incomplete) -> None: + ... + + def cancel(self) -> None: + ... + + def _submit(self) -> Incomplete: + ... + + def _schedule(self) -> bool: + ... + + def request(self, draw: Incomplete) -> bool: + ... + + def acknowledge(self) -> None: + ... + +class _NavigationInteractionManager: + """Temporarily simplify dense scenes during interactive navigation.""" + _line_limit = 2000 + _scatter_limit = 2000 + + def __init__(self, canvas: Incomplete, figure: Incomplete, selective: Incomplete) -> None: + ... + + def _is_active(self) -> Incomplete: + ... + + @staticmethod + def _is_three_axes(ax: Incomplete) -> Incomplete: + ... + + @staticmethod + def _subset_indices(arrays: Incomplete, limit: Incomplete) -> Incomplete: + ... + + @staticmethod + def _shared_view_axes(ax: Incomplete) -> Incomplete: + ... + + @staticmethod + def _shared_two_axes(ax: Incomplete) -> Incomplete: + ... + + @staticmethod + def _simplify_locator(axis: Incomplete, state: Incomplete) -> None: + ... + + def _simplify_line(self, line: Incomplete, dimensions: Incomplete, state: Incomplete) -> None: + ... + + def _simplify_scatter(self, artist: Incomplete, arrays: Incomplete, indices: Incomplete, names: Incomplete, state: Incomplete) -> None: + ... + + def _simplify_three_axes(self, ax: Incomplete) -> _AxesPreviewState: + ... + + def _simplify_two_axes(self, ax: Incomplete) -> _AxesPreviewState: + ... + + def activate(self, ax: Incomplete) -> bool: + """Activate preview quality for the navigated axes and shared siblings.""" + ... + + def deactivate(self, *, redraw: Incomplete=True) -> bool: + """Restore exact artists and formatting after interactive navigation.""" + ... + + def request_draw(self, draw: Incomplete) -> bool: + ... + + @contextmanager + def full_quality_context(self) -> Incomplete: + ... + + def _on_press(self, event: Incomplete) -> None: + ... + + def _on_release(self, event: Incomplete) -> None: + ... + + def _on_draw(self, event: Incomplete) -> None: + ... + + def _on_close(self, event: Incomplete) -> None: + ... + + def close(self) -> None: + ... diff --git a/ultraplot/_layout.pyi b/ultraplot/_layout.pyi new file mode 100644 index 000000000..b489092ee --- /dev/null +++ b/ultraplot/_layout.pyi @@ -0,0 +1,206 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Private helpers for reducing repeated layout work. + +There are two cache lifetimes: + +- Tick computations are reused only within one layout-and-render transaction. +- Relative axes outsets persist across transactions until their dependencies + change. + +``_LayoutTransaction`` owns both lifecycles. Temporary matplotlib method +overrides are restored when the transaction exits, including after exceptions. +""" +from _typeshed import Incomplete +from collections import OrderedDict +from contextlib import ExitStack +from dataclasses import dataclass +import matplotlib.transforms as mtransforms +import numpy as np +_MISSING = object() + +def _is_internal_ticker(obj: Incomplete) -> bool: + """Return whether a locator or formatter is safe for draw-local reuse.""" + ... + +def _interval_key(values: Incomplete) -> Incomplete: + """Convert a numerical interval to an immutable exact cache key.""" + ... + +@dataclass(frozen=True) +class _AxisTickState: + """State that can affect ``Axis._update_ticks`` within one canvas draw.""" + view_interval: tuple + data_interval: tuple + axes_size: tuple + dpi: float + scale: str + major_locator: int + major_formatter: int + minor_locator: int + minor_formatter: int + converter: int + units: int + +@dataclass +class _AxisTickResult: + """Cached ticks and formatter locations for one axis state.""" + ticks: list + major_locs: np.ndarray | tuple + minor_locs: np.ndarray | tuple + +class _AxisTickCache: + """ + Cache repeated tick updates during one layout-and-render transaction. + + Tight bounding-box calculation and the final axes draw repeatedly call + ``Axis._update_ticks`` with identical state. The method runs locators, + formatters, tick positioning, and visibility filtering each time. This + manager replaces the method on individual axes for the duration of a + canvas draw and restores the original instance state afterwards. + + Custom third-party locators and formatters conservatively bypass the + cache because they may rely on repeated side effects. + """ + _MAX_STATES_PER_AXIS = 4 + + def __init__(self, figure: Incomplete) -> None: + ... + + def __enter__(self) -> Incomplete: + ... + + def __exit__(self, *args: Incomplete) -> None: + ... + + def refresh(self) -> None: + """Patch axes added while queued guides and panels are materialized.""" + ... + + def _patch(self, axis: Incomplete) -> None: + ... + + @staticmethod + def _is_cacheable(axis: Incomplete) -> bool: + ... + + def _get_state(self, axis: Incomplete) -> _AxisTickState: + ... + + @staticmethod + def _copy_formatter_locs(formatter: Incomplete) -> Incomplete: + ... + + @staticmethod + def _restore_formatter_locs(axis: Incomplete, result: Incomplete) -> None: + ... + +@dataclass(frozen=True) +class _AxesExtentState: + """Geometry that can alter outsets relative to an axes rectangle.""" + bbox_size: tuple + bbox_position: tuple + dpi: float + axis_states: tuple + decorations: tuple + subset_titles: tuple + +@dataclass +class _AxesExtentRecord: + """One relative tight-bbox measurement.""" + version: int + state: _AxesExtentState + outsets: tuple + +class _LayoutExtentStore: + """ + Persist relative axes outsets and dependency versions between layouts. + + Absolute axes positions are solver outputs. Tick labels, axis labels, and + titles are better represented as four overhangs around those positions. + Standard Cartesian axes can therefore move without repeating renderer text + measurements. Position-sensitive axes and extra artists automatically add + the absolute origin to their state key. + """ + + def __init__(self, figure: Incomplete) -> None: + ... + + def __enter__(self) -> Incomplete: + ... + + def refresh(self) -> Incomplete: + """Synchronize axes added by queued guide and panel creation.""" + ... + + def __exit__(self, *args: Incomplete) -> None: + ... + + def get_tightbbox(self, axes: Incomplete, renderer: Incomplete, *, include_subset_titles: Incomplete=True, use_cache: Incomplete=True) -> Incomplete: + """Return an exact or reconstructed tight bbox in display units.""" + ... + + def _get_state(self, axes: Incomplete, include_subset_titles: Incomplete=True) -> _AxesExtentState: + ... + + def _rebase_records(self) -> None: + """Rebase reusable outsets onto final post-render axes dimensions. + +UltraLayout may make a small solver adjustment after measuring an axes. +The final render updates locator/formatter locations for that geometry. +If those locations and every non-size dependency are unchanged, the +relative outsets remain valid for the next layout transaction.""" + ... + + def _get_retained_bboxes(self, axes: Incomplete) -> Incomplete: + """Return exact cached display bboxes for retained axes drawing.""" + ... + + @staticmethod + def _get_decoration_state(axes: Incomplete) -> Incomplete: + ... + + def _get_subset_title_state(self, axes: Incomplete, include_subset_titles: Incomplete) -> Incomplete: + ... + + @staticmethod + def _is_position_sensitive(axes: Incomplete) -> bool: + ... + + @staticmethod + def _is_cacheable_axes(axes: Incomplete) -> bool: + ... + + @staticmethod + def _get_outsets(axes_bbox: Incomplete, tight_bbox: Incomplete) -> Incomplete: + ... + + @staticmethod + def _bbox_from_outsets(axes_bbox: Incomplete, outsets: Incomplete) -> Incomplete: + ... + + @staticmethod + def _measure_tightbbox(axes: Incomplete, renderer: Incomplete, include_subset_titles: Incomplete) -> Incomplete: + ... + +class _LayoutTransaction: + """ + Own temporary and persistent caches for one dirty canvas draw. + + Figure code only needs to know whether a transaction is active. Cache setup, + dynamic-axes refresh, and exception-safe cleanup stay private to this object. + """ + + def __init__(self, figure: Incomplete, *, cache_ticks: Incomplete=True, cache_extents: Incomplete=True) -> None: + ... + + def __enter__(self) -> Incomplete: + ... + + def __exit__(self, *args: Incomplete) -> Incomplete: + ... + + def refresh(self) -> None: + """Synchronize caches after queued guides create axes or panels.""" + ... diff --git a/ultraplot/_lazy.pyi b/ultraplot/_lazy.pyi new file mode 100644 index 000000000..a0b280d71 --- /dev/null +++ b/ultraplot/_lazy.pyi @@ -0,0 +1,63 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Helpers for lazy attribute loading in :mod:`ultraplot`. +""" +from _typeshed import Incomplete +import ast +import importlib.util +import types +from importlib import import_module +from pathlib import Path +from typing import Any, Callable, Dict, Mapping, MutableMapping, Optional + +class LazyLoader: + """ + Encapsulates lazy-loading mechanics for the ultraplot top-level module. + """ + + def __init__(self, *, package: str, package_path: Path, exceptions: Mapping[str, tuple[str, Optional[str]]], setup_callback: Callable[[], None], registry_attr_callback: Callable[[str], Optional[type]], registry_build_callback: Callable[[], None], registry_names_callback: Callable[[], Optional[Mapping[str, type]]], attr_map_key: str='_ATTR_MAP', eager_key: str='_EAGER_DONE') -> None: + ... + + def _import_module(self, module_name: str) -> types.ModuleType: + ... + + def _get_attr_map(self, module_globals: Mapping[str, Any]) -> Optional[Dict[str, tuple[str, Optional[str]]]]: + ... + + def _set_attr_map(self, module_globals: MutableMapping[str, Any], value: Dict[str, tuple[str, Optional[str]]]) -> None: + ... + + def _get_eager_done(self, module_globals: Mapping[str, Any]) -> bool: + ... + + def _set_eager_done(self, module_globals: MutableMapping[str, Any], value: bool) -> None: + ... + + @staticmethod + def _parse_all(path: Path) -> Optional[list[str]]: + ... + + def _discover_modules(self, module_globals: MutableMapping[str, Any]) -> None: + ... + + def resolve_extra(self, name: str, module_globals: MutableMapping[str, Any]) -> Any: + ... + + def load_all(self, module_globals: MutableMapping[str, Any]) -> list[str]: + ... + + def get_attr(self, name: str, module_globals: MutableMapping[str, Any]) -> Any: + ... + + def iter_dir_names(self, module_globals: MutableMapping[str, Any]) -> list[str]: + ... + +class _UltraPlotModule(types.ModuleType): + + def __setattr__(self, name: str, value: Any) -> None: + ... + +def install_module_proxy(module: Optional[types.ModuleType]) -> None: + """Prevent lazy-loading names from being clobbered by submodule imports.""" + ... diff --git a/ultraplot/_subplots.pyi b/ultraplot/_subplots.pyi new file mode 100644 index 000000000..a69c78bb8 --- /dev/null +++ b/ultraplot/_subplots.pyi @@ -0,0 +1,70 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Subplot creation and management for ultraplot figures. +""" +from _typeshed import Incomplete +from numbers import Integral +from typing import TYPE_CHECKING +import matplotlib.axes as maxes +import matplotlib.gridspec as mgridspec +import matplotlib.projections as mproj +import numpy as np +from . import axes as paxes +from . import constructor +from . import gridspec as pgridspec +from .internals import _not_none, _pop_params, warnings +from .figure import Figure + +class SubplotManager: + """ + Manages subplot creation, gridspec ownership, and projection parsing + for a Figure instance. + + Parameters + ---------- + figure : `~ultraplot.figure.Figure` + The parent figure. + """ + + def __init__(self, figure: 'Figure') -> None: + ... + + def reset(self) -> None: + """Forget every subplot and release the gridspec. + +Called by `~ultraplot.figure.Figure.clear`, which destroys the axes this +manager tracks. Without this the figure keeps handing out axes that are no +longer attached to it.""" + ... + + @property + def gridspec(self) -> Incomplete: + """The single GridSpec used for all subplots in the figure.""" + ... + + @gridspec.setter + def gridspec(self, gs: Incomplete) -> None: + ... + + @staticmethod + def parse_backend(backend: Incomplete=None, basemap: Incomplete=None) -> Incomplete: + """Handle deprecation of basemap and cartopy package.""" + ... + + def parse_proj(self, proj: Incomplete=None, projection: Incomplete=None, proj_kw: Incomplete=None, projection_kw: Incomplete=None, backend: Incomplete=None, basemap: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Translate user-input projection into a registered matplotlib axes class.""" + ... + + def add_subplot(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """The driver function for adding single subplots.""" + ... + + def add_subplots(self, array: Incomplete=None, nrows: Incomplete=1, ncols: Incomplete=1, order: Incomplete='C', proj: Incomplete=None, projection: Incomplete=None, proj_kw: Incomplete=None, projection_kw: Incomplete=None, backend: Incomplete=None, basemap: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """The driver function for adding multiple subplots.""" + ... + + @property + def subplotgrid(self) -> Incomplete: + """A SubplotGrid of numbered subplots sorted by number.""" + ... diff --git a/ultraplot/_version.pyi b/ultraplot/_version.pyi new file mode 100644 index 000000000..362a9157c --- /dev/null +++ b/ultraplot/_version.pyi @@ -0,0 +1,3 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +__version__: str diff --git a/ultraplot/animation.pyi b/ultraplot/animation.pyi new file mode 100644 index 000000000..4f9f5c67d --- /dev/null +++ b/ultraplot/animation.pyi @@ -0,0 +1,343 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Fast drop-in replacements for the `matplotlib.animation` classes. + +The classes here subclass their Matplotlib counterparts, so the constructor +signatures, the attributes, and the notebook representations are unchanged. +What differs is how frames are rendered: + +* `~ultraplot.animation.FuncAnimation.save` bypasses the per-frame + `~matplotlib.figure.Figure.savefig` call used by Matplotlib's writers and + instead renders straight into the Agg buffer, piping raw ``RGBA`` bytes to + the encoder. No PNG round-trip, no ``print_figure`` machinery. +* The expensive UltraPlot tight-layout pass runs once, for the first frame, + rather than on every frame. +* Blitting is used while saving, not just interactively, so only the artists + the update function returns are redrawn per frame. + +Everything falls back to Matplotlib's own implementation when the fast path +cannot be used (custom writer instances, ``bbox_inches``, vector output, and +so on), so the output is never silently wrong. +""" +from _typeshed import Incomplete +import itertools +import os +import subprocess +from contextlib import ExitStack, contextmanager, suppress +from tempfile import TemporaryFile +from pathlib import Path +import matplotlib as mpl +import matplotlib.animation as manimation +import numpy as np +from matplotlib import cbook +__all__ = ['FuncAnimation', 'ArtistAnimation'] +_FFMPEG_SUFFIXES = frozenset(('.mp4', '.m4v', '.mov', '.mkv', '.webm', '.avi', '.ogv', '.ogg') + ('.gif', '.webp', '.apng', '.avif')) +_PILLOW_SUFFIXES = frozenset(('.gif', '.webp', '.apng')) +_SUFFIX_CODECS = frozenset(('.gif', '.webp', '.apng', '.avif')) +_FAST_WRITERS = frozenset(('ffmpeg', 'pillow')) + +def _suffix(filename: Incomplete) -> Incomplete: + """Return the lowercase suffix of a path-like filename.""" + ... + +class _RawWriter: + """ + Base class for writers that consume raw ``RGBA`` frames. + + Subclasses implement `write`, `_close`, and `_discard`. The output file is + deleted unless `finish` completed, so an animation that fails halfway + through never leaves a truncated movie that looks like a whole one. + """ + + def __init__(self, filename: Incomplete, fps: Incomplete) -> None: + ... + + def setup(self, width: Incomplete, height: Incomplete) -> Incomplete: + ... + + def write(self, buffer: Incomplete) -> Incomplete: + ... + + def _close(self) -> Incomplete: + ... + + def _discard(self) -> Incomplete: + ... + + def finish(self) -> Incomplete: + """Complete the file. Anything short of this counts as a failed save.""" + ... + + def cleanup(self) -> Incomplete: + """Release resources, and remove the output of an unfinished save.""" + ... + +class _RawFFMpegWriter(_RawWriter): + """ + Pipe raw ``RGBA`` frames into ``ffmpeg`` with no intermediate encoding. + """ + + def __init__(self, filename: Incomplete, fps: Incomplete, *, codec: Incomplete=None, bitrate: Incomplete=None, extra_args: Incomplete=None, metadata: Incomplete=None) -> None: + ... + + @staticmethod + def available() -> Incomplete: + """Return whether the configured ``ffmpeg`` binary can be executed.""" + ... + + def _command(self) -> Incomplete: + ... + + def setup(self, width: Incomplete, height: Incomplete) -> Incomplete: + ... + + def _stderr_text(self) -> Incomplete: + ... + + def write(self, buffer: Incomplete) -> Incomplete: + ... + + def _close(self) -> Incomplete: + ... + + def _discard(self) -> Incomplete: + ... + +class _RawPillowWriter(_RawWriter): + """ + Collect raw ``RGBA`` frames and write an animated image with Pillow. + """ + + def __init__(self, filename: Incomplete, fps: Incomplete) -> None: + ... + + def write(self, buffer: Incomplete) -> Incomplete: + ... + + def _close(self) -> Incomplete: + ... + + def _discard(self) -> Incomplete: + ... + +class _FastSaveMixin: + """ + The fast `save` path, shared by the animation classes. + + Subclasses supply the three frame hooks below; everything else here is the + machinery that renders those frames into a movie file. + """ + + def _fast_frame_seq(self) -> Incomplete: + ... + + def _fast_frame_artists(self, frame: Incomplete) -> Incomplete: + ... + + def _fast_init_artists(self, frame: Incomplete) -> Incomplete: + ... + + @contextmanager + def _frozen_layout(self) -> Incomplete: + """Run the UltraPlot layout solver once instead of once per frame. + +UltraPlot recomputes tight layout whenever the figure is marked dirty. +During an animation the geometry must stay fixed anyway, or frames +would jitter, so the solver is switched off after the first draw. Yields +a function that marks the current layout as final.""" + ... + + @contextmanager + def _animated_artists(self, artists: Incomplete=()) -> Incomplete: + """Temporarily mark artists as animated so full draws skip them. + +Yields a function that marks further artists, for update functions that +return a different set of artists as the animation goes on.""" + ... + + @contextmanager + def _suspended_event_source(self) -> Incomplete: + """Keep the interactive timer from starting on the frames drawn here. + +`matplotlib.animation.Animation` starts itself from the figure's first +``draw_event``. The draws below are for the movie file, not the screen.""" + ... + + @contextmanager + def _suspended_figure_blitting(self) -> Incomplete: + """Stand down the figure's own retained-draw machinery while saving. + +`~ultraplot.figure.Figure.savefig` does the same before printing. A live +`~ultraplot._animation._BlitManager` keeps its artists flagged animated +and repaints them from a ``draw_event`` handler, which would fight the +frames drawn here.""" + ... + + @contextmanager + def _agg_canvas(self) -> Incomplete: + """Ensure the figure has a canvas that can blit and expose an RGBA buffer.""" + ... + + def _resolve_writer(self, filename: Incomplete, writer: Incomplete, savefig_kwargs: Incomplete, extra_anim: Incomplete) -> Incomplete: + """Return the name of the fast writer to use, or ``None`` for none. + +The fast path must pick the same writer Matplotlib would, or the same +call would produce a differently encoded file than before.""" + ... + + def _make_raw_writer(self, filename: Incomplete, writer: Incomplete, fps: Incomplete, codec: Incomplete, bitrate: Incomplete, extra_args: Incomplete, metadata: Incomplete) -> Incomplete: + """Return the raw-frame writer for the resolved writer name.""" + ... + + def _fast_save(self, filename: Incomplete, writer: Incomplete, fps: Incomplete, dpi: Incomplete, codec: Incomplete, bitrate: Incomplete, extra_args: Incomplete, metadata: Incomplete, progress_callback: Incomplete, blit: Incomplete) -> Incomplete: + """Render every frame straight into the Agg buffer and pipe it out.""" + ... + + def save(self, filename: Incomplete, writer: Incomplete=None, fps: Incomplete=None, dpi: Incomplete=None, codec: Incomplete=None, bitrate: Incomplete=None, extra_args: Incomplete=None, metadata: Incomplete=None, extra_anim: Incomplete=None, savefig_kwargs: Incomplete=None, *, progress_callback: Incomplete=None, fast: Incomplete=None, blit: Incomplete=None) -> Incomplete: + """Save the animation to a movie file. + +Parameters +---------- +filename : path-like + The output file, e.g. ``'movie.mp4'`` or ``'movie.gif'``. +writer : str or `~matplotlib.animation.AbstractMovieWriter`, optional + Same meaning as in `matplotlib.animation.Animation.save`. Passing a + writer *instance*, or a writer the fast path does not implement, + transparently falls back to Matplotlib's implementation. +fps : int, optional + Frames per second. Defaults to the animation interval. +dpi : float, optional + Resolution of the saved frames. Unlike Matplotlib, which uses + :rc:`savefig.dpi`, this defaults to the figure's own dpi. UltraPlot + sets ``savefig.dpi`` to 1000 for publication-quality stills, which + for a movie means hundredfold larger frames and a hundredfold + slower encode. +codec, bitrate, extra_args, metadata : optional + Passed to the encoder, as in Matplotlib. +extra_anim : list, optional + Additional animations to composite. Forces the Matplotlib path. +savefig_kwargs : dict, optional + Extra `~matplotlib.figure.Figure.savefig` arguments. Any value here + forces the Matplotlib path, since the fast path skips ``savefig``. +progress_callback : callable, optional + Called as ``progress_callback(current_frame, total_frames)``. +fast : bool, optional + Whether to use the fast renderer. The default, ``None``, uses it + whenever it can reproduce the requested output exactly. Passing + ``True`` raises if the fast path is unavailable. +blit : bool, optional + Whether to blit while saving. Defaults to the animation's own + ``blit`` setting. Blitting only redraws the artists returned by the + update function, so anything else changed per frame (titles, ticks, + axes limits) will not appear. Pass ``False`` to redraw everything. + +Other Parameters +---------------- +See `matplotlib.animation.Animation.save`. + +See also +-------- +matplotlib.animation.Animation.save""" + ... + +class FuncAnimation(_FastSaveMixin, manimation.FuncAnimation): + """ + A faster drop-in replacement for `matplotlib.animation.FuncAnimation`. + + The signature matches Matplotlib's, with two differences: `blit` defaults + to ``True`` instead of ``False``, and `freeze_layout` is added. Saving + renders frames directly into the Agg buffer instead of calling + `~matplotlib.figure.Figure.savefig` once per frame, which removes the + per-frame PNG round-trip and the repeated UltraPlot tight-layout pass. + + Parameters + ---------- + fig : `~ultraplot.figure.Figure` + The figure to animate. + func : callable + The update function, called as ``func(frame, *fargs)``. It should + return an iterable of the artists it modified. This is required when + `blit` is ``True``, and lets the fast path skip untouched artists. + frames : int, iterable, generator, or None, optional + Source of frame data, as in Matplotlib. + init_func : callable, optional + Function drawing the clear frame. Should return the animated artists. + fargs : tuple, optional + Extra positional arguments for `func` and `init_func`. + save_count : int, optional + Number of frames to cache from a generator. + blit : bool, default: True + Whether to redraw only the artists returned by `func`. This is the main + source of the speedup, but it means changes to artists that are *not* + returned, such as titles or tick labels, will not show up. Pass + ``False`` to redraw the whole figure each frame, which is still faster + than Matplotlib because the layout solver is frozen. + cache_frame_data : bool, default: True + Whether to cache frame data, as in Matplotlib. + **kwargs + Passed to `matplotlib.animation.TimedAnimation`, e.g. `interval`, + `repeat`, and `repeat_delay`. + + Examples + -------- + >>> import ultraplot as uplt + >>> import numpy as np + >>> fig, ax = uplt.subplots() + >>> x = np.linspace(0, 2 * np.pi, 200) + >>> (line,) = ax.plot(x, np.sin(x)) + >>> def update(frame): + ... line.set_ydata(np.sin(x + frame / 10)) + ... return (line,) + ... + >>> ani = uplt.FuncAnimation(fig, update, frames=100) + >>> ani.save('waves.mp4') + + See also + -------- + matplotlib.animation.FuncAnimation + ultraplot.animation.ArtistAnimation + """ + + def __init__(self, fig: Incomplete, func: Incomplete, frames: Incomplete=None, init_func: Incomplete=None, fargs: Incomplete=None, save_count: Incomplete=None, *, blit: Incomplete=True, **kwargs: Incomplete) -> None: + ... + + def _fast_frame_seq(self) -> Incomplete: + ... + + def _fast_init_artists(self, frame: Incomplete) -> Incomplete: + ... + + def _fast_frame_artists(self, frame: Incomplete) -> Incomplete: + ... + +class ArtistAnimation(_FastSaveMixin, manimation.ArtistAnimation): + """ + A faster drop-in replacement for `matplotlib.animation.ArtistAnimation`. + + Frames are lists of artists that are made visible in turn. Saving uses the + same direct-to-buffer renderer as `FuncAnimation`. + + Parameters + ---------- + fig : `~ultraplot.figure.Figure` + The figure to animate. + artists : list of list of `~matplotlib.artist.Artist` + Each entry is the collection of artists making up one frame. + **kwargs + Passed to `matplotlib.animation.TimedAnimation`. + + See also + -------- + matplotlib.animation.ArtistAnimation + ultraplot.animation.FuncAnimation + """ + + def _fast_frame_seq(self) -> Incomplete: + ... + + def _fast_init_artists(self, frame: Incomplete) -> Incomplete: + ... + + def _fast_frame_artists(self, frame: Incomplete) -> Incomplete: + ... diff --git a/ultraplot/axes/__init__.pyi b/ultraplot/axes/__init__.pyi new file mode 100644 index 000000000..1a7c30814 --- /dev/null +++ b/ultraplot/axes/__init__.pyi @@ -0,0 +1,20 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +The various axes classes used throughout ultraplot. +""" +from _typeshed import Incomplete +import matplotlib.projections as mproj +from ..internals import context +from .base import Axes +from .cartesian import CartesianAxes +from .container import ExternalAxesContainer +from .geo import GeoAxes, _BasemapAxes, _CartopyAxes +from .plot import PlotAxes +from .polar import PolarAxes +from .shared import _SharedAxes +from .taylor import TaylorAxes +from .three import ThreeAxes +__all__ = ['Axes', 'PlotAxes', 'CartesianAxes', 'PolarAxes', 'TaylorAxes', 'GeoAxes', 'ThreeAxes', 'ExternalAxesContainer'] +_cls_dict = {} +_cls_table = ... diff --git a/ultraplot/axes/_formatting.pyi b/ultraplot/axes/_formatting.pyi new file mode 100644 index 000000000..a2d65bf1c --- /dev/null +++ b/ultraplot/axes/_formatting.pyi @@ -0,0 +1,39 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Shared metadata for axis formatting keyword routing and persistence. +""" +from _typeshed import Incomplete +import inspect +_AXIS_STYLE_FIELD_TEMPLATES = {'color': ('{axis}color', 'color', '{axis}ec', 'ec', '{axis}edgecolor', 'edgecolor', 'axesec', 'axesedgecolor'), 'linewidth': ('{axis}linewidth', 'linewidth', '{axis}lw', 'lw', 'axeslw', 'axeslinewidth'), 'rotation': ('{axis}rotation', 'rotation'), 'spineloc': ('{axis}spineloc', '{axis}loc'), 'tickloc': ('{axis}tickloc',), 'ticklabelloc': ('{axis}ticklabelloc',), 'labelloc': ('{axis}labelloc',), 'offsetloc': ('{axis}offsetloc',), 'grid': ('{axis}grid',), 'gridminor': ('{axis}gridminor',), 'gridcolor': ('{axis}gridcolor', 'gridcolor'), 'tickdir': ('{axis}tickdir', 'tickdir'), 'tickcolor': ('{axis}tickcolor', 'tickcolor'), 'ticklen': ('{axis}ticklen', 'ticklen'), 'ticklenratio': ('{axis}ticklenratio', 'ticklenratio'), 'tickwidth': ('{axis}tickwidth', 'tickwidth'), 'tickwidthratio': ('{axis}tickwidthratio', 'tickwidthratio'), 'ticklabeldir': ('{axis}ticklabeldir', 'ticklabeldir'), 'ticklabelpad': ('{axis}ticklabelpad',), 'ticklabelcolor': ('{axis}ticklabelcolor', 'ticklabelcolor'), 'ticklabelsize': ('{axis}ticklabelsize', 'ticklabelsize'), 'ticklabelweight': ('{axis}ticklabelweight', 'ticklabelweight'), 'labelpad': ('{axis}labelpad',), 'labelcolor': ('{axis}labelcolor', 'labelcolor'), 'labelsize': ('{axis}labelsize', 'labelsize'), 'labelweight': ('{axis}labelweight', 'labelweight')} +_PAINT_ONLY_AXIS_STYLE_FIELDS = {'color', 'linewidth', 'grid', 'gridminor', 'gridcolor', 'tickcolor', 'tickwidth', 'tickwidthratio', 'ticklabelcolor', 'labelcolor'} + +def _dedupe(items: Incomplete) -> Incomplete: + ... +GENERIC_AXIS_FORMAT_KEYS = ... +PAINT_ONLY_AXIS_FORMAT_KEYS = ... +CARTESIAN_PARENT_FILTER_KEYS = GENERIC_AXIS_FORMAT_KEYS + ('label_kw', 'scale_kw', 'locator_kw', 'formatter_kw', 'minorlocator_kw') + +def axis_format_requires_layout(keys: Incomplete) -> bool: + """Return whether explicit Cartesian formatting keys can affect layout. + +Unknown keys are treated as layout-affecting so new formatting options +remain correct until they are deliberately classified.""" + ... + +def get_axis_style_fields(axis: Incomplete) -> dict[str, tuple[str, ...]]: + """Return the parameter names used to store explicit style overrides.""" + ... + +def _signature_param_names(*funcs: Incomplete) -> Incomplete: + ... + +def pop_axis_format_kwargs(kwargs: Incomplete, *funcs: Incomplete) -> Incomplete: + """Pop axis-format kwargs so they survive rc parsing. + +Returns +------- +tuple(dict, dict) + The signature-defined keyword arguments and the generic alias keyword + arguments that are not represented in the stored signatures.""" + ... diff --git a/ultraplot/axes/base.pyi b/ultraplot/axes/base.pyi new file mode 100644 index 000000000..cff7cd0dc --- /dev/null +++ b/ultraplot/axes/base.pyi @@ -0,0 +1,2094 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +The first-level axes subclass used for all ultraplot figures. +Implements basic shared functionality. +""" +from _typeshed import Incomplete +import contextlib +import copy +import inspect +import re +import sys +import types +from collections.abc import Iterable as IterableType +from numbers import Integral, Number +from typing import Any, Iterable, MutableMapping, Optional, Tuple, Union +try: + from typing import override +except ImportError: + from typing_extensions import override +import matplotlib.axes as maxes +import matplotlib.axis as maxis +import matplotlib.cm as mcm +import matplotlib.colors as mcolors +import matplotlib.container as mcontainer +import matplotlib.contour as mcontour +import matplotlib.offsetbox as moffsetbox +import matplotlib.patches as mpatches +import matplotlib.projections as mproj +import matplotlib.text as mtext +import matplotlib.ticker as mticker +import matplotlib.transforms as mtransforms +import numpy as np +from matplotlib import cbook +from packaging import version +from .. import colors as pcolors +from .. import constructor +from .. import legend as plegend +from .. import ticker as pticker +from ..colorbar import UltraColorbar, _apply_inset_colorbar_layout, _determine_label_rotation, _get_axis_for, _get_colorbar_long_axis, _legacy_inset_colorbar_bounds, _reflow_inset_colorbar_frame, _register_inset_colorbar_reflow, _solve_inset_colorbar_bounds +from ..config import rc +from ..internals import _kwargs_to_args, _not_none, _pop_kwargs, _pop_params, _pop_props, _pop_rc, _translate_loc, _version_mpl, docstring, guides, ic, labels, rcsetup, warnings +from ..ultralayout import KIWI_AVAILABLE, ColorbarLayoutSolver +from ..utils import _fontsize_to_pt, edges, units +try: + from cartopy.crs import CRS, PlateCarree +except Exception: + CRS = PlateCarree = object +__all__ = ['Axes'] +ABC_STRING = 'abcdefghijklmnopqrstuvwxyz' +_proj_docstring = ... +_proj_kw_docstring = ... +_backend_docstring = ... +_space_docstring = ... +_transform_docstring = ... +_inset_docstring = ... +_indicate_inset_docstring = ... +_panel_loc_docstring = ... +_panel_docstring = ... +_axes_format_docstring = ... +_figure_format_docstring = ... +_rc_init_docstring = ... +_rc_format_docstring = ... +_colorbar_args_docstring = ... +_colorbar_kwargs_docstring = ... +_edgefix_docstring = ... +_legend_args_docstring = ... +_legend_kwargs_docstring = ... + +def _align_bbox(align: Incomplete, length: Incomplete) -> Incomplete: + """Return a simple alignment bounding box for intersection calculations.""" + ... + +def _get_side_colorbar_ticklocation(side: Incomplete, orientation: Incomplete, tickloc: Incomplete, ticklocation: Incomplete, *, orientation_explicit: Incomplete=False) -> Incomplete: + """Return the outward-facing tick location for a side colorbar.""" + ... + +def _convert_side_colorbar_units(axes: Incomplete, orientation: Incomplete, length: Incomplete, width: Incomplete, pad: Incomplete) -> Incomplete: + """Convert side colorbar dimensions to axes-relative units.""" + ... + +def _get_side_colorbar_bounds(side: Incomplete, align: Incomplete, length: Incomplete, width: Incomplete, xpad: Incomplete, ypad: Incomplete) -> Incomplete: + """Return axes-relative bounds for a side colorbar.""" + ... + +def _get_filled_colorbar_bounds(side: Incomplete, align: Incomplete, length: Incomplete) -> Incomplete: + """Return panel-relative bounds for a side colorbar.""" + ... + +def _get_colorbar_aligned_position(side: Incomplete, align: Incomplete, length: Incomplete) -> Incomplete: + """Validate colorbar alignment and return its long-axis start position.""" + ... + +class _TransformedBoundsLocator: + """ + Axes locator for `~Axes.inset_axes` and other axes. + """ + + def __init__(self, bounds: Incomplete, transform: Incomplete) -> None: + ... + + def __call__(self, ax: Incomplete, renderer: Incomplete) -> Incomplete: + ... + +class _AspectAwareTransformedBoundsLocator(_TransformedBoundsLocator): + """Preserve an inset's lower-left anchor after box-aspect adjustment.""" + + def __call__(self, ax: Incomplete, renderer: Incomplete) -> Incomplete: + ... + +class _SideColorbarLocator: + """Position a side colorbar beyond its parent axes decorations.""" + + def __init__(self, parent: Incomplete, side: Incomplete, bounds: Incomplete, pad: Incomplete, previous: Incomplete=()) -> None: + ... + + def __call__(self, ax: Incomplete, renderer: Incomplete) -> Incomplete: + ... + +class _ExternalModeMixin: + """ + Mixin providing explicit external-mode control and a context manager. + """ + + def set_external(self, value: Incomplete=True) -> Incomplete: + """Set explicit external-mode override for this axes. + +value: + - True: force external behavior (defer on-the-fly guides, etc.) + - False: force UltraPlot behavior""" + ... + + class _ExternalContext: + + def __init__(self, ax: Incomplete, value: Incomplete=True) -> None: + ... + + def __enter__(self) -> Incomplete: + ... + + def __exit__(self, exc_type: Incomplete, exc: Incomplete, tb: Incomplete) -> Incomplete: + ... + + def external(self, value: Incomplete=True) -> Incomplete: + """Context manager toggling external mode during the block.""" + ... + + def _in_external_context(self) -> Incomplete: + """Return True if UltraPlot helper behaviors should be suppressed.""" + ... + +class Axes(_ExternalModeMixin, maxes.Axes): + """ + The lowest-level `~matplotlib.axes.Axes` subclass used by ultraplot. + Implements basic universal features. + """ + _name = None + _name_aliases = () + _make_inset_locator = _TransformedBoundsLocator + + def __repr__(self) -> str: + ... + + def __str__(self) -> str: + ... + + def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: + """Parameters +---------- +*args + Passed to `matplotlib.axes.Axes`. +title : str or sequence, optional + The axes title. Can optionally be a sequence strings, in which case + the title will be selected from the sequence according to `~Axes.number`. +abc : bool or str or sequence, default: :rc:`abc` + The "a-b-c" subplot label style. Must contain the character `a` or `A`, + for example ``'a.'``, or ``'A'``. If ``True`` then the default style of + ``'a'`` is used. The `a` or ``A`` is replaced with the alphabetic character + matching the `~Axes.number`. If `~Axes.number` is greater than 26, the + characters loop around to a, ..., z, aa, ..., zz, aaa, ..., zzz, etc. + Can also be a sequence of strings, in which case the "a-b-c" label will be selected sequentially from the list. For example `axs.format(abc = ["X", "Y"])` for a two-panel figure, and `axes[3:5].format(abc = ["X", "Y"])` for a two-panel subset of a larger figure. +abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` + Strings indicating the location for the a-b-c label and main title. + The following locations are valid: + + .. _title_table: + + ======================== ============================ + Location Valid keys + ======================== ============================ + center above axes ``'center'``, ``'c'`` + left above axes ``'left'``, ``'l'`` + right above axes ``'right'``, ``'r'`` + lower center inside axes ``'lower center'``, ``'lc'`` + upper center inside axes ``'upper center'``, ``'uc'`` + upper right inside axes ``'upper right'``, ``'ur'`` + upper left inside axes ``'upper left'``, ``'ul'`` + lower left inside axes ``'lower left'``, ``'ll'`` + lower right inside axes ``'lower right'``, ``'lr'`` + left of y axis ``'outer left'``, ``'ol'`` + right of y axis ``'outer right'``, ``'or'`` + ======================== ============================ + +abcborder, titleborder : bool, default: :rc:`abc.border` and :rc:`title.border` + Whether to draw a white border around titles and a-b-c labels positioned + inside the axes. This can help them stand out on top of artists + plotted inside the axes. +abcbbox, titlebbox : bool, default: :rc:`abc.bbox` and :rc:`title.bbox` + Whether to draw a white bbox around titles and a-b-c labels positioned + inside the axes. This can help them stand out on top of artists plotted + inside the axes. +abcpad : float or unit-spec, default: :rc:`abc.pad` + Horizontal offset to shift the a-b-c label position. Positive values move + the label right, negative values move it left. This is separate from + `abctitlepad`, which controls spacing between abc and title when co-located. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +abc_kw, title_kw : dict-like, optional + Additional settings used to update the a-b-c label and title + with ``text.update()``. +titlepad : float, default: :rc:`title.pad` + The padding for the inner and outer titles and a-b-c labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +titleabove : bool, default: :rc:`title.above` + Whether to try to put outer titles and a-b-c labels above panels, + colorbars, or legends that are above the axes. +abctitlepad : float, default: :rc:`abc.titlepad` + The horizontal padding between a-b-c labels and titles in the same location. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle : str or sequence, optional + Shorthands for the below keywords. + lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle : str or sequence, optional +lowerlefttitle, lowercentertitle, lowerrighttitle : str or sequence, optional + Additional titles in specific positions (see `title` for details). This works as + an alternative to the ``ax.format(title='Title', titleloc=loc)`` workflow and + permits adding more than one title-like label for a single axes. +a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle : default: + :rc:`axes.alpha` (default: 1.0), :rc:`axes.facecolor` (default: white), :rc:`axes.edgecolor` (default: black), :rc:`axes.linewidth` (default: 0.6), - + Additional settings applied to the background patch, and their + shorthands. Their defaults values are the ``'axes'`` properties. + +Other parameters +---------------- +rc_mode : int, optional + The context mode passed to `~ultraplot.config.Configurator.context`. +rc_kw : dict-like, optional + An alternative to passing extra keyword arguments. See below. +**kwargs + Remaining keyword arguments are passed to `matplotlib.axes.Axes`.\\n Keyword arguments that match the name of an `~ultraplot.config.rc` setting are + passed to `ultraplot.config.Configurator.context` and used to update the axes. + If the setting name has "dots" you can simply omit the dots. For example, + ``abc='A.'`` modifies the :rcraw:`abc` setting, ``titleloc='left'`` modifies the + :rcraw:`title.loc` setting, ``gridminor=True`` modifies the :rcraw:`gridminor` + setting, and ``gridbelow=True`` modifies the :rcraw:`grid.below` setting. Many + of the keyword arguments documented above are internally applied by retrieving + settings passed to `~ultraplot.config.Configurator.context`. + +See also +-------- +Axes.format +matplotlib.axes.Axes +ultraplot.axes.PlotAxes +ultraplot.axes.CartesianAxes +ultraplot.axes.PolarAxes +ultraplot.axes.GeoAxes +ultraplot.figure.Figure.subplot +ultraplot.figure.Figure.add_subplot""" + ... + + def _add_inset_axes(self, bounds: Incomplete, transform: Incomplete=None, *, proj: Incomplete=None, projection: Incomplete=None, zoom: Incomplete=None, zoom_kw: Incomplete=None, zorder: Incomplete=None, **kwargs: Incomplete) -> Axes: + """Add an inset axes using arbitrary projection.""" + ... + + def _add_queued_guides(self) -> None: + """Draw the queued-up legends and colorbars. Wrapper funcs and legend func let +user add handles to location lists with successive calls.""" + ... + + def _add_guide_frame(self, xmin: Incomplete, ymin: Incomplete, width: Incomplete, height: Incomplete, *, fontsize: Incomplete, fancybox: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Add a colorbar or multilegend frame.""" + ... + + def _add_guide_panel(self, loc: str='fill', align: str='center', length: Union[float, str]=0, span: Optional[Union[int, Tuple[int, int]]]=None, row: Optional[int]=None, col: Optional[int]=None, rows: Optional[Union[int, Tuple[int, int]]]=None, cols: Optional[Union[int, Tuple[int, int]]]=None, **kwargs: Incomplete) -> 'Axes': + """Add a panel to be filled by an "outer" colorbar or legend.""" + ... + + def _add_colorbar(self, mappable: Incomplete, values: Incomplete=None, *, loc: Optional[str]=None, align: Optional[str]=None, space: Optional[Union[float, str]]=None, pad: Optional[Union[float, str]]=None, width: Optional[Union[float, str]]=None, length: Optional[Union[float, str]]=None, span: Optional[Union[int, Tuple[int, int]]]=None, row: Optional[int]=None, col: Optional[int]=None, rows: Optional[Union[int, Tuple[int, int]]]=None, cols: Optional[Union[int, Tuple[int, int]]]=None, shrink: Optional[Union[float, str]]=None, label: Incomplete=None, title: Incomplete=None, reverse: Incomplete=False, rotation: Incomplete=None, grid: Incomplete=None, edges: Incomplete=None, drawedges: Incomplete=None, extend: Incomplete=None, extendsize: Incomplete=None, extendfrac: Incomplete=None, ticks: Incomplete=None, locator: Incomplete=None, locator_kw: Incomplete=None, format: Incomplete=None, formatter: Incomplete=None, ticklabels: Incomplete=None, formatter_kw: Incomplete=None, minorticks: Incomplete=None, minorlocator: Incomplete=None, minorlocator_kw: Incomplete=None, tickminor: Incomplete=None, ticklen: Incomplete=None, ticklenratio: Incomplete=None, tickdir: Incomplete=None, tickdirection: Incomplete=None, tickwidth: Incomplete=None, tickwidthratio: Incomplete=None, ticklabelsize: Incomplete=None, ticklabelweight: Incomplete=None, ticklabelcolor: Incomplete=None, labelloc: Incomplete=None, labellocation: Incomplete=None, labelsize: Incomplete=None, labelweight: Incomplete=None, labelcolor: Incomplete=None, c: Incomplete=None, color: Incomplete=None, lw: Incomplete=None, linewidth: Incomplete=None, edgefix: Incomplete=None, rasterized: Incomplete=None, frame: Optional[bool]=None, frameon: Optional[bool]=None, outline: Union[bool, None]=None, labelrotation: Union[str, float]=None, center_levels: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + ... + + def _add_legend(self, handles: Incomplete=None, labels: Incomplete=None, *, loc: Incomplete=None, align: Incomplete=None, width: Incomplete=None, pad: Incomplete=None, space: Incomplete=None, frame: Incomplete=None, frameon: Incomplete=None, ncol: Incomplete=None, ncols: Incomplete=None, alphabetize: Incomplete=False, center: Incomplete=None, order: Incomplete=None, label: Incomplete=None, title: Incomplete=None, fontsize: Incomplete=None, fontweight: Incomplete=None, fontcolor: Incomplete=None, titlefontsize: Incomplete=None, titlefontweight: Incomplete=None, titlefontcolor: Incomplete=None, handle_kw: Incomplete=None, handler_map: Incomplete=None, span: Optional[Union[int, Tuple[int, int]]]=None, row: Optional[int]=None, col: Optional[int]=None, rows: Optional[Union[int, Tuple[int, int]]]=None, cols: Optional[Union[int, Tuple[int, int]]]=None, **kwargs: Incomplete) -> Incomplete: + ... + + def _apply_title_above(self) -> None: + """Change assignment of outer titles between main subplot and upper panels. +This is called when a panel is created or `_update_title` is called.""" + ... + + def _apply_auto_share(self) -> None: + """Automatically configure axis sharing based on the horizontal and +vertical extent of subplots in the figure gridspec.""" + ... + + def _artist_fully_clipped(self, artist: Incomplete) -> Incomplete: + """Return a boolean flag, ``True`` if the artist is clipped to the axes +and can thus be skipped in layout calculations.""" + ... + + def _format_inset(self, bounds: tuple[float, float, float, float], parent: 'Axes', **kwargs: Incomplete) -> Incomplete: + ... + + def __format_inset(self, bounds: tuple[float, float, float, float], parent: 'Axes', **kwargs: Incomplete) -> Incomplete: + ... + + def __format_inset_legacy(self, bounds: tuple[float, float, float, float], parent: 'Axes', **kwargs: Incomplete) -> tuple[mpatches.Rectangle, list[mpatches.ConnectionPatch]]: + ... + + def _get_legend_handles(self, handler_map: Incomplete=None) -> Incomplete: + """Internal implementation of matplotlib's ``get_legend_handles_labels``.""" + ... + + def _get_share_axes(self, sx: Incomplete, panels: Incomplete=False) -> Incomplete: + """Return the axes whose horizontal or vertical extent in the main gridspec +matches the horizontal or vertical extent of this axes.""" + ... + + def _get_span_axes(self, side: Incomplete, panels: Incomplete=False) -> Incomplete: + """Return the axes whose left, right, top, or bottom sides abutt against +the same row or column as this axes. Deflect to shared panels.""" + ... + + def _get_size_inches(self) -> Incomplete: + """Return the width and height of the axes in inches.""" + ... + + def _get_topmost_axes(self) -> Incomplete: + """Return the topmost axes including panels and parents.""" + ... + + def _get_transform(self, transform: Incomplete, default: Incomplete='data') -> Incomplete: + """Translates user input transform. Also used in an axes method.""" + ... + + def _parse_anchor(self, coordinates: Incomplete, transform: Incomplete=None, default: Incomplete='data') -> Incomplete: + """Parse coordinates and their transform. + +Coordinates can be passed with the transform separately or packaged as +a ``(coordinates, transform)`` tuple. The latter is useful for APIs +that accept a single anchor argument, such as ``inset_axes``.""" + ... + + def _register_guide(self, guide: Incomplete, obj: Incomplete, key: Incomplete, **kwargs: Incomplete) -> None: + """Queue up or replace objects for legends and list-of-artist style colorbars.""" + ... + + def _update_guide(self, objs: Incomplete, legend: Incomplete=None, legend_kw: Incomplete=None, queue_legend: Incomplete=True, colorbar: Incomplete=None, colorbar_kw: Incomplete=None, queue_colorbar: Incomplete=True) -> None: + """Update queues for on-the-fly legends and colorbars or track keyword arguments.""" + ... + + @staticmethod + def _parse_frame(guide: Incomplete, fancybox: Incomplete=None, shadow: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Parse frame arguments.""" + ... + + @staticmethod + def _parse_colorbar_arg(mappable: Incomplete, values: Incomplete=None, norm: Incomplete=None, norm_kw: Incomplete=None, vmin: Incomplete=None, vmax: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Generate a mappable from flexible non-mappable input. Useful in bridging +the gap between legends and colorbars (e.g., creating colorbars from line +objects whose data values span a natural colormap range).""" + ... + + def _parse_colorbar_filled(self, length: Incomplete=None, align: Incomplete=None, tickloc: Incomplete=None, ticklocation: Incomplete=None, orientation: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Return the axes and adjusted keyword args for a panel-filling colorbar.""" + ... + + def _parse_colorbar_inset(self, loc: Incomplete=None, width: Incomplete=None, length: Incomplete=None, shrink: Incomplete=None, frame: Incomplete=None, frameon: Incomplete=None, label: Incomplete=None, labelsize: Incomplete=None, pad: Incomplete=None, tickloc: Incomplete=None, ticklocation: Incomplete=None, orientation: Incomplete=None, labelloc: Incomplete=None, labelrotation: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Return the axes and adjusted keyword args for an inset colorbar.""" + ... + + def _add_colorbar_child_axes(self, bounds: Incomplete, locator: Incomplete=None, track_parent: Incomplete=True) -> Axes: + """Add and return a colorbar axes positioned relative to this axes.""" + ... + + def _parse_colorbar_inset_side(self, loc: Incomplete=None, align: Incomplete=None, width: Incomplete=None, length: Incomplete=None, shrink: Incomplete=None, space: Incomplete=None, pad: Incomplete=None, tickloc: Incomplete=None, ticklocation: Incomplete=None, orientation: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Return the axes and adjusted keyword args for a side colorbar on an inset axes.""" + ... + + def _parse_legend_aligned(self, pairs: Incomplete, ncol: Incomplete=None, order: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Draw an individual legend with aligned columns. Includes support +for switching legend-entries between column-major and row-major.""" + ... + + def _parse_legend_centered(self, pairs: Incomplete, *, fontsize: Incomplete, loc: Incomplete=None, title: Incomplete=None, frameon: Incomplete=None, kw_frame: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Draw "legend" with centered rows by creating separate legends for +each row. The label spacing/border spacing will be exactly replicated.""" + ... + + @staticmethod + def _parse_legend_group(handles: Incomplete, labels: Incomplete=None, handler_map: Incomplete=None) -> Incomplete: + """Parse possibly tuple-grouped input handles.""" + ... + + def _parse_legend_handles(self, handles: Incomplete, labels: Incomplete, ncol: Incomplete=None, order: Incomplete=None, center: Incomplete=None, alphabetize: Incomplete=None, handler_map: Incomplete=None) -> Incomplete: + """Parse input handles and labels.""" + ... + + def _range_subplotspec(self, s: Incomplete) -> Incomplete: + """Return the column or row range for the subplotspec.""" + ... + + def _range_tightbbox(self, s: Incomplete) -> Incomplete: + """Return the tight bounding box span from the cached bounding box.""" + ... + + def _unshare(self, *, which: str) -> None: + """Remove this Axes from the shared Grouper for the given axis ('x', 'y', 'z', or 'view'). +Note this isolates the axis and does not preserve the transitivity of sharing.""" + ... + + def _sharex_setup(self, sharex: Incomplete, **kwargs: Incomplete) -> None: + """Configure x-axis sharing for panels. See also `~CartesianAxes._sharex_setup`.""" + ... + + def _sharey_setup(self, sharey: Incomplete, **kwargs: Incomplete) -> None: + """Configure y-axis sharing for panels. See also `~CartesianAxes._sharey_setup`.""" + ... + + def _share_short_axis(self, share: Incomplete, side: Incomplete, **kwargs: Incomplete) -> None: + """Share the "short" axes of panels in this subplot with other panels.""" + ... + + def _share_long_axis(self, share: Incomplete, side: Incomplete, **kwargs: Incomplete) -> None: + """Share the "long" axes of panels in this subplot with other panels.""" + ... + + def _reposition_subplot(self) -> None: + """Reposition the subplot axes.""" + ... + + def _update_abc(self, **kwargs: Incomplete) -> None: + """Update the a-b-c label.""" + ... + + def _update_outer_abc_loc(self, loc: Incomplete) -> None: + """For the outer labels, we need to align them vertically and create the +offset based on the tick length and the tick label. This function loops +through all axes in the figure to find maximum tick length and label size +and transforms the position accordingly.""" + ... + + def _update_title(self, loc: Incomplete, title: Incomplete=None, **kwargs: Incomplete) -> None: + """Update the title at the specified location.""" + ... + + def _update_title_position(self, renderer: Incomplete) -> None: + """Update the position of inset titles and outer titles. This is called +by matplotlib at drawtime.""" + ... + + def _update_super_title(self, suptitle: Incomplete=None, **kwargs: Incomplete) -> None: + """Update the figure super title.""" + ... + + def _update_super_labels(self, side: Incomplete, labels: Incomplete=None, **kwargs: Incomplete) -> None: + """Update the figure super labels.""" + ... + + @staticmethod + def get_center_of_axes(axes: Incomplete=None) -> Incomplete: + ... + + def _update_share_labels(self, axes: Incomplete=None, target: Incomplete='x') -> None: + """Update shared axis labels for a group of axes. + +Parameters +---------- +axes : list of int or list of Axes, optional + The axes indices or Axes objects to share labels between +target : {'x', 'y'}, optional + Which axis labels to share ('x' for x-axis, 'y' for y-axis)""" + ... + + def format(self, *, title: Incomplete=None, title_kw: Incomplete=None, abc_kw: Incomplete=None, ltitle: Incomplete=None, lefttitle: Incomplete=None, ctitle: Incomplete=None, centertitle: Incomplete=None, rtitle: Incomplete=None, righttitle: Incomplete=None, ultitle: Incomplete=None, upperlefttitle: Incomplete=None, uctitle: Incomplete=None, uppercentertitle: Incomplete=None, urtitle: Incomplete=None, upperrighttitle: Incomplete=None, lltitle: Incomplete=None, lowerlefttitle: Incomplete=None, lctitle: Incomplete=None, lowercentertitle: Incomplete=None, lrtitle: Incomplete=None, lowerrighttitle: Incomplete=None, share_xlabels: Incomplete=None, share_ylabels: Incomplete=None, **kwargs: Incomplete) -> None: + """Modify the a-b-c label, axes title(s), and background patch, +and call `ultraplot.figure.Figure.format` on the axes figure. + +Parameters +---------- +title : str or sequence, optional + The axes title. Can optionally be a sequence strings, in which case + the title will be selected from the sequence according to `~Axes.number`. +abc : bool or str or sequence, default: :rc:`abc` + The "a-b-c" subplot label style. Must contain the character `a` or `A`, + for example ``'a.'``, or ``'A'``. If ``True`` then the default style of + ``'a'`` is used. The `a` or ``A`` is replaced with the alphabetic character + matching the `~Axes.number`. If `~Axes.number` is greater than 26, the + characters loop around to a, ..., z, aa, ..., zz, aaa, ..., zzz, etc. + Can also be a sequence of strings, in which case the "a-b-c" label will be selected sequentially from the list. For example `axs.format(abc = ["X", "Y"])` for a two-panel figure, and `axes[3:5].format(abc = ["X", "Y"])` for a two-panel subset of a larger figure. +abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` + Strings indicating the location for the a-b-c label and main title. + The following locations are valid: + + .. _title_table: + + ======================== ============================ + Location Valid keys + ======================== ============================ + center above axes ``'center'``, ``'c'`` + left above axes ``'left'``, ``'l'`` + right above axes ``'right'``, ``'r'`` + lower center inside axes ``'lower center'``, ``'lc'`` + upper center inside axes ``'upper center'``, ``'uc'`` + upper right inside axes ``'upper right'``, ``'ur'`` + upper left inside axes ``'upper left'``, ``'ul'`` + lower left inside axes ``'lower left'``, ``'ll'`` + lower right inside axes ``'lower right'``, ``'lr'`` + left of y axis ``'outer left'``, ``'ol'`` + right of y axis ``'outer right'``, ``'or'`` + ======================== ============================ + +abcborder, titleborder : bool, default: :rc:`abc.border` and :rc:`title.border` + Whether to draw a white border around titles and a-b-c labels positioned + inside the axes. This can help them stand out on top of artists + plotted inside the axes. +abcbbox, titlebbox : bool, default: :rc:`abc.bbox` and :rc:`title.bbox` + Whether to draw a white bbox around titles and a-b-c labels positioned + inside the axes. This can help them stand out on top of artists plotted + inside the axes. +abcpad : float or unit-spec, default: :rc:`abc.pad` + Horizontal offset to shift the a-b-c label position. Positive values move + the label right, negative values move it left. This is separate from + `abctitlepad`, which controls spacing between abc and title when co-located. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +abc_kw, title_kw : dict-like, optional + Additional settings used to update the a-b-c label and title + with ``text.update()``. +titlepad : float, default: :rc:`title.pad` + The padding for the inner and outer titles and a-b-c labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +titleabove : bool, default: :rc:`title.above` + Whether to try to put outer titles and a-b-c labels above panels, + colorbars, or legends that are above the axes. +abctitlepad : float, default: :rc:`abc.titlepad` + The horizontal padding between a-b-c labels and titles in the same location. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle : str or sequence, optional + Shorthands for the below keywords. + lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle : str or sequence, optional +lowerlefttitle, lowercentertitle, lowerrighttitle : str or sequence, optional + Additional titles in specific positions (see `title` for details). This works as + an alternative to the ``ax.format(title='Title', titleloc=loc)`` workflow and + permits adding more than one title-like label for a single axes. +a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle : default: + :rc:`axes.alpha` (default: 1.0), :rc:`axes.facecolor` (default: white), :rc:`axes.edgecolor` (default: black), :rc:`axes.linewidth` (default: 0.6), - + Additional settings applied to the background patch, and their + shorthands. Their defaults values are the ``'axes'`` properties. + +Important +--------- +`abc`, `abcloc`, `titleloc`, `titleabove`, `titlepad`, and +`abctitlepad` are actually :ref:`configuration settings `. +We explicitly document these arguments here because it is common to +change them for specific axes. But many :ref:`other configuration +settings ` can be passed to ``format`` too. + +Other parameters +---------------- +rowlabels, collabels, llabels, tlabels, rlabels, blabels + Aliases for `leftlabels` and `toplabels`, and for `leftlabels`, + `toplabels`, `rightlabels`, and `bottomlabels`, respectively. +leftlabels, toplabels, rightlabels, bottomlabels : sequence of str, optional + Labels for the subplots lying along the left, top, right, and + bottom edges of the figure. The length of each list must match + the number of subplots along the corresponding edge. +leftlabelpad, toplabelpad, rightlabelpad, bottomlabelpad : float or unit-spec, default +: :rc:`leftlabel.pad`, :rc:`toplabel.pad`, :rc:`rightlabel.pad`, :rc:`bottomlabel.pad` + The padding between the labels and the axes content. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +leftlabelsharedpad, toplabelsharedpad, rightlabelsharedpad, bottomlabelsharedpad : float or unit-spec, default +: :rc:`leftlabel.sharedpad`, :rc:`toplabel.sharedpad`, :rc:`rightlabel.sharedpad`, :rc:`bottomlabel.sharedpad` + The padding between side labels and a shared spanning axis label on the + same side. The spanning label is placed outside the side labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +leftlabels_kw, toplabels_kw, rightlabels_kw, bottomlabels_kw : dict-like, optional + Additional settings used to update the labels with ``text.update()``. +figtitle + Alias for `suptitle`. +suptitle : str, optional + The figure "super" title, centered between the left edge of the leftmost + subplot and the right edge of the rightmost subplot. +suptitlepad : float, default: :rc:`suptitle.pad` + The padding between the super title and the axes content. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +suptitle_kw : optional + Additional settings used to update the super title with ``text.update()``. +includepanels : bool, default: False + Whether to include panels when aligning figure "super titles" along the top + of the subplot grid and when aligning the `spanx` *x* axis labels and + `spany` *y* axis labels along the sides of the subplot grid. +rc_mode : int, optional + The context mode passed to `~ultraplot.config.Configurator.context`. +rc_kw : dict-like, optional + An alternative to passing extra keyword arguments. See below. +**kwargs + Keyword arguments that match the name of an `~ultraplot.config.rc` setting are + passed to `ultraplot.config.Configurator.context` and used to update the axes. + If the setting name has "dots" you can simply omit the dots. For example, + ``abc='A.'`` modifies the :rcraw:`abc` setting, ``titleloc='left'`` modifies the + :rcraw:`title.loc` setting, ``gridminor=True`` modifies the :rcraw:`gridminor` + setting, and ``gridbelow=True`` modifies the :rcraw:`grid.below` setting. Many + of the keyword arguments documented above are internally applied by retrieving + settings passed to `~ultraplot.config.Configurator.context`. + +See also +-------- +ultraplot.axes.CartesianAxes.format +ultraplot.axes.PolarAxes.format +ultraplot.axes.GeoAxes.format +ultraplot.figure.Figure.format +ultraplot.gridspec.SubplotGrid.format +ultraplot.config.Configurator.context""" + ... + + def draw(self, renderer: Incomplete=None, *args: Incomplete, **kwargs: Incomplete) -> None: + ... + + def get_tightbbox(self, renderer: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + ... + + def get_default_bbox_extra_artists(self) -> Incomplete: + ... + + def set_prop_cycle(self, *args: Incomplete, **kwargs: Incomplete) -> None: + ... + + def _is_panel_group_member(self, other: 'Axes') -> bool: + """Determine if the current axes and another axes belong to the same panel group. + +Two axes belong to the same panel group if any of the following is true: +1. One axis is the parent of the other +2. Both axes are panels sharing the same parent + +Parameters +---------- +other : Axes + The other axes to compare with + +Returns +------- +bool + True if both axes belong to the same panel group, False otherwise""" + ... + + def _label_key(self, side: str) -> str: + """Map requested side name to the correct tick_params key across mpl versions. + +This accounts for the API change around Matplotlib 3.10 where labeltop/labelbottom +became first-class tick parameter keys. For older versions, these map to +labelright/labelleft respectively.""" + ... + + def _is_ticklabel_on(self, side: str) -> bool: + """Check if tick labels are on for the specified sides.""" + ... + + def inset(self, *args: Incomplete, **kwargs: Incomplete) -> Axes: + """Add an inset axes. +This is similar to `matplotlib.axes.Axes.inset_axes`. + +Parameters +----------- +bounds : 4-tuple of float or (4-tuple, transform) + The (left, bottom, width, height) coordinates for the axes. To specify the + coordinate system alongside the coordinates, pass ``(bounds, transform)``. +transform : {'data', 'axes', 'figure', 'subfigure'} or `~matplotlib.transforms.Transform`, optional + The transform used to interpret the bounds. Can be a + :class:`~matplotlib.transforms.Transform` instance or a string representing + the :class:`~matplotlib.axes.Axes.transData`, :class:`~matplotlib.axes.Axes.transAxes`, + :class:`~matplotlib.figure.Figure.transFigure`, or + :class:`~matplotlib.figure.Figure.transSubfigure`, transforms. + Default is to use the same projection as the current axes. +proj, projection : +str, `cartopy.crs.Projection`, or `~mpl_toolkits.basemap.Basemap`, optional + The map projection specification(s). If ``'cart'`` or ``'cartesian'`` + (the default), a `~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, + a :class:`~ultraplot.axes.PolarAxes` is created. Otherwise, the argument is + interpreted by `~ultraplot.constructor.Proj`, and the result is used + to make a `~ultraplot.axes.GeoAxes` (in this case the argument can be + a `cartopy.crs.Projection` instance, a `~mpl_toolkits.basemap.Basemap` + instance, or a projection name listed in :ref:`this table `). +proj_kw, projection_kw : dict-like, optional + Keyword arguments passed to `~mpl_toolkits.basemap.Basemap` or + cartopy `~cartopy.crs.Projection` classes on instantiation. +backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` + Whether to use `~mpl_toolkits.basemap.Basemap` or + `~cartopy.crs.Projection` for map projections. + + .. deprecated:: 3.0.0 + The ``'basemap'`` backend is deprecated and may be removed in a + future release. Please use the ``'cartopy'`` backend instead. +zorder : float, default: 4 + The `zorder `__ + of the axes. Should be greater than the zorder of elements in the parent axes. +zoom : bool, default: True or False + Whether to draw lines indicating the inset zoom using `~Axes.indicate_inset_zoom`. + The line positions will automatically adjust when the parent or inset axes limits + change. Default is ``True`` only if both axes are `~ultraplot.axes.CartesianAxes`. +zoom_kw : dict, optional + Passed to `~Axes.indicate_inset_zoom`. + +Other parameters +----------------- +**kwargs + Passed to `ultraplot.axes.Axes`. + +Returns +-------- +ultraplot.axes.Axes + The inset axes. + +See also +--------- +Axes.indicate_inset_zoom +matplotlib.axes.Axes.inset_axes +matplotlib.axes.Axes.indicate_inset +matplotlib.axes.Axes.indicate_inset_zoom""" + ... + + def inset_axes(self, *args: Incomplete, **kwargs: Incomplete) -> Axes: + """Add an inset axes. +This is similar to `matplotlib.axes.Axes.inset_axes`. + +Parameters +----------- +bounds : 4-tuple of float or (4-tuple, transform) + The (left, bottom, width, height) coordinates for the axes. To specify the + coordinate system alongside the coordinates, pass ``(bounds, transform)``. +transform : {'data', 'axes', 'figure', 'subfigure'} or `~matplotlib.transforms.Transform`, optional + The transform used to interpret the bounds. Can be a + :class:`~matplotlib.transforms.Transform` instance or a string representing + the :class:`~matplotlib.axes.Axes.transData`, :class:`~matplotlib.axes.Axes.transAxes`, + :class:`~matplotlib.figure.Figure.transFigure`, or + :class:`~matplotlib.figure.Figure.transSubfigure`, transforms. + Default is to use the same projection as the current axes. +proj, projection : +str, `cartopy.crs.Projection`, or `~mpl_toolkits.basemap.Basemap`, optional + The map projection specification(s). If ``'cart'`` or ``'cartesian'`` + (the default), a `~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, + a :class:`~ultraplot.axes.PolarAxes` is created. Otherwise, the argument is + interpreted by `~ultraplot.constructor.Proj`, and the result is used + to make a `~ultraplot.axes.GeoAxes` (in this case the argument can be + a `cartopy.crs.Projection` instance, a `~mpl_toolkits.basemap.Basemap` + instance, or a projection name listed in :ref:`this table `). +proj_kw, projection_kw : dict-like, optional + Keyword arguments passed to `~mpl_toolkits.basemap.Basemap` or + cartopy `~cartopy.crs.Projection` classes on instantiation. +backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` + Whether to use `~mpl_toolkits.basemap.Basemap` or + `~cartopy.crs.Projection` for map projections. + + .. deprecated:: 3.0.0 + The ``'basemap'`` backend is deprecated and may be removed in a + future release. Please use the ``'cartopy'`` backend instead. +zorder : float, default: 4 + The `zorder `__ + of the axes. Should be greater than the zorder of elements in the parent axes. +zoom : bool, default: True or False + Whether to draw lines indicating the inset zoom using `~Axes.indicate_inset_zoom`. + The line positions will automatically adjust when the parent or inset axes limits + change. Default is ``True`` only if both axes are `~ultraplot.axes.CartesianAxes`. +zoom_kw : dict, optional + Passed to `~Axes.indicate_inset_zoom`. + +Other parameters +----------------- +**kwargs + Passed to `ultraplot.axes.Axes`. + +Returns +-------- +ultraplot.axes.Axes + The inset axes. + +See also +--------- +Axes.indicate_inset_zoom +matplotlib.axes.Axes.inset_axes +matplotlib.axes.Axes.indicate_inset +matplotlib.axes.Axes.indicate_inset_zoom""" + ... + + @override + def indicate_inset_zoom(self, **kwargs: Incomplete) -> Incomplete: + """Add indicators denoting the zoom range of the inset axes. +This will replace previously drawn zoom indicators. + +Parameters +----------- +linewidth : unit-spec, default: :rc:`patch.linewidth` + The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyle : str, default: '-' + The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. +edgecolor : color-spec, default: 'none' + The edge color of the patch(es). Aliases: ``ec``, ``edgecolors``. +facecolor : color-spec, optional + The face color of the patch(es). The property `cycle` is used by default. Aliases: ``fc``, ``facecolors``, ``fillcolor``, ``fillcolors``. +alpha : float, optional + The opacity of the patch(es). Inferred from `facecolor` and `edgecolor` by default. Aliases: ``a``, ``alphas``. +zorder : float, default: 3.5 + The `zorder `__ of + the indicators. Should be greater than the zorder of elements in the parent axes. + +Other parameters +----------------- +**kwargs + Passed to `~matplotlib.patches.Patch`. + +Note +----- +This command must be called from the inset axes rather than the parent axes. +It is called automatically when ``zoom=True`` is passed to `~Axes.inset_axes` +and whenever the axes are drawn (so the line positions always track the axis +limits even if they are later changed). + +See also +--------- +matplotlib.axes.Axes.indicate_inset +matplotlib.axes.Axes.indicate_inset_zoom""" + ... + + def panel(self, side: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Add a panel axes. + +Parameters +----------- +side : str, optional + The panel location. Valid location keys are as follows. + + ========== ===================== + Location Valid keys + ========== ===================== + left ``'left'``, ``'l'`` + right ``'right'``, ``'r'`` + bottom ``'bottom'``, ``'b'`` + top ``'top'``, ``'t'`` + ========== ===================== + +width : unit-spec, default: :rc:`subplots.panelwidth` + The panel width. + If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. +space : unit-spec, default: None + The fixed space between the panel and the subplot edge. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + When the :ref:`tight layout algorithm ` is active for the figure, + `space` is computed automatically (see `pad`). Otherwise, `space` is set to + a suitable default. +pad : unit-spec, default: :rc:`subplots.panelpad` + The :ref:`tight layout padding ` between the panel and the subplot. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +row, rows + Aliases for `span` for panels on the left or right side (vertical panels). +col, cols + Aliases for `span` for panels on the top or bottom side (horizontal panels). +span : int or 2-tuple of int, default: None + Integer(s) indicating the span of the panel across rows and columns of + subplots. For panels on the left or right side, use `rows` or `row` to + specify which rows the panel should span. For panels on the top or bottom + side, use `cols` or `col` to specify which columns the panel should span. + For example, ``ax.panel('b', col=1)`` draws a panel beneath only the + leftmost column, and ``ax.panel('b', cols=(1, 2))`` draws a panel beneath + the left two columns. By default the panel will span all rows or columns + aligned with the parent axes. +share : bool, default: True + Whether to enable axis sharing between the *x* and *y* axes of the + main subplot and the panel long axes for each panel in the "stack". + Sharing between the panel short axis and other panel short axes + is determined by figure-wide `sharex` and `sharey` settings. + +Other parameters +----------------- +**kwargs + Passed to `ultraplot.axes.CartesianAxes`. Supports all valid + `~ultraplot.axes.CartesianAxes.format` keywords. + +Returns +-------- +ultraplot.axes.CartesianAxes + The panel axes.""" + ... + + def panel_axes(self, side: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Add a panel axes. + +Parameters +----------- +side : str, optional + The panel location. Valid location keys are as follows. + + ========== ===================== + Location Valid keys + ========== ===================== + left ``'left'``, ``'l'`` + right ``'right'``, ``'r'`` + bottom ``'bottom'``, ``'b'`` + top ``'top'``, ``'t'`` + ========== ===================== + +width : unit-spec, default: :rc:`subplots.panelwidth` + The panel width. + If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. +space : unit-spec, default: None + The fixed space between the panel and the subplot edge. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + When the :ref:`tight layout algorithm ` is active for the figure, + `space` is computed automatically (see `pad`). Otherwise, `space` is set to + a suitable default. +pad : unit-spec, default: :rc:`subplots.panelpad` + The :ref:`tight layout padding ` between the panel and the subplot. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +row, rows + Aliases for `span` for panels on the left or right side (vertical panels). +col, cols + Aliases for `span` for panels on the top or bottom side (horizontal panels). +span : int or 2-tuple of int, default: None + Integer(s) indicating the span of the panel across rows and columns of + subplots. For panels on the left or right side, use `rows` or `row` to + specify which rows the panel should span. For panels on the top or bottom + side, use `cols` or `col` to specify which columns the panel should span. + For example, ``ax.panel('b', col=1)`` draws a panel beneath only the + leftmost column, and ``ax.panel('b', cols=(1, 2))`` draws a panel beneath + the left two columns. By default the panel will span all rows or columns + aligned with the parent axes. +share : bool, default: True + Whether to enable axis sharing between the *x* and *y* axes of the + main subplot and the panel long axes for each panel in the "stack". + Sharing between the panel short axis and other panel short axes + is determined by figure-wide `sharex` and `sharey` settings. + +Other parameters +----------------- +**kwargs + Passed to `ultraplot.axes.CartesianAxes`. Supports all valid + `~ultraplot.axes.CartesianAxes.format` keywords. + +Returns +-------- +ultraplot.axes.CartesianAxes + The panel axes.""" + ... + + def colorbar(self, mappable: Incomplete, values: Incomplete=None, loc: Incomplete=None, location: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Add an inset colorbar or an outer colorbar along the edge of the axes. + +Parameters +---------- + mappable : mappable, colormap-spec, sequence of color-spec, + or sequence of :class:`~matplotlib.artist.Artist` + There are four options here: + + 1. A `~matplotlib.cm.ScalarMappable` (e.g., an object returned by + `~ultraplot.axes.PlotAxes.contourf` or `~ultraplot.axes.PlotAxes.pcolormesh`). + 2. A `~matplotlib.colors.Colormap` or registered colormap name used to build a + `~matplotlib.cm.ScalarMappable` on-the-fly. The colorbar range and ticks depend + on the arguments `values`, `vmin`, `vmax`, and `norm`. The default for a + :class:`~ultraplot.colors.ContinuousColormap` is ``vmin=0`` and ``vmax=1`` (note that + passing `values` will "discretize" the colormap). The default for a + :class:`~ultraplot.colors.DiscreteColormap` is ``values=np.arange(0, cmap.N)``. + 3. A sequence of hex strings, color names, or RGB[A] tuples. A + :class:`~ultraplot.colors.DiscreteColormap` will be generated from these colors and + used to build a `~matplotlib.cm.ScalarMappable` on-the-fly. The colorbar + range and ticks depend on the arguments `values`, `norm`, and + `norm_kw`. The default is ``values=np.arange(0, len(mappable))``. + 4. A sequence of `matplotlib.artist.Artist` instances (e.g., a list of + `~matplotlib.lines.Line2D` instances returned by `~ultraplot.axes.PlotAxes.plot`). + A colormap will be generated from the colors of these objects (where the + color is determined by ``get_color``, if available, or ``get_facecolor``). + The colorbar range and ticks depend on the arguments `values`, `norm`, and + `norm_kw`. The default is to infer colorbar ticks and tick labels + by calling `~matplotlib.artist.Artist.get_label` on each artist. + + values : sequence of float or str, optional + Ignored if `mappable` is a `~matplotlib.cm.ScalarMappable`. This maps the colormap + colors to numeric values using `~ultraplot.colors.DiscreteNorm`. If the colormap is + a :class:`~ultraplot.colors.ContinuousColormap` then its colors will be "discretized". + These These can also be strings, in which case the list indices are used for + tick locations and the strings are applied as tick labels. + loc, location : int or str, default: :rc:`colorbar.loc` + The colorbar location. Valid location keys are shown in the below table. + + .. _colorbar_table: + + ================== ======================================= + Location Valid keys + ================== ======================================= + outer left ``'left'``, ``'l'`` + outer right ``'right'``, ``'r'`` + outer bottom ``'bottom'``, ``'b'`` + outer top ``'top'``, ``'t'`` + default inset ``'best'``, ``'inset'``, ``'i'``, ``0`` + upper right inset ``'upper right'``, ``'ur'``, ``1`` + upper left inset ``'upper left'``, ``'ul'``, ``2`` + lower left inset ``'lower left'``, ``'ll'``, ``3`` + lower right inset ``'lower right'``, ``'lr'``, ``4`` + "filled" ``'fill'`` + ================== ======================================= + + shrink + Alias for `length`. This is included for consistency with + `matplotlib.figure.Figure.colorbar`. + length : float or unit-spec, default: :rc:`colorbar.length` or :rc:`colorbar.insetlength` + The colorbar length. For outer colorbars, units are relative to the axes + width or height (default is :rcraw:`colorbar.length`). For inset + colorbars, floats interpreted as em-widths and strings interpreted + by `~ultraplot.utils.units` (default is :rcraw:`colorbar.insetlength`). + width : unit-spec, default: :rc:`colorbar.width` or :rc:`colorbar.insetwidth` + The colorbar width. For outer colorbars, floats are interpreted as inches + (default is :rcraw:`colorbar.width`). For inset colorbars, floats are + interpreted as em-widths (default is :rcraw:`colorbar.insetwidth`). + Strings are interpreted by `~ultraplot.utils.units`. + queue : bool, optional + If ``True`` and `loc` is the same as an existing colorbar, the input + arguments are added to a queue and this function returns ``None``. + This is used to "update" the same colorbar with successive ``ax.colorbar(...)`` + calls. If ``False`` (the default) and `loc` is the same as an existing + *inset* colorbar, the old colorbar is removed. If ``False`` and `loc` is an + *outer* colorbar, the colorbars are "stacked". +space : unit-spec, default: None + For outer colorbars only. The fixed space between the colorbar and the subplot + edge. If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + When the :ref:`tight layout algorithm ` is active for the figure, + `space` is computed automatically (see `pad`). Otherwise, `space` is set to + a suitable default. +pad : unit-spec, default: :rc:`subplots.panelpad` or :rc:`colorbar.insetpad` + For outer colorbars, this is the :ref:`tight layout padding ` + between the colorbar and the subplot (default is :rcraw:`subplots.panelpad`). + For inset colorbars, this is the fixed space between the axes + edge and the colorbar (default is :rcraw:`colorbar.insetpad`). + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +align : {'center', 'top', 'bottom', 'left', 'right', 't', 'b', 'l', 'r'}, optional + For outer colorbars only. How to align the colorbar against the subplot edge. + The values ``'top'`` and ``'bottom'`` are valid for left and right colorbars + and ``'left'`` and ``'right'`` are valid for top and bottom colorbars. + The default is always ``'center'``. + Has no visible effect if `length` is ``1``. + Other parameters + ---------------- + orientation : {None, 'horizontal', 'vertical'}, optional + The colorbar orientation. By default this depends on the "side" of the subplot + or figure where the colorbar is drawn. Inset colorbars are always horizontal. +norm : norm-spec, optional + Ignored if `mappable` is a `~matplotlib.cm.ScalarMappable`. This is the continuous + normalizer used to scale the :class:`~ultraplot.colors.ContinuousColormap` (or passed + to `~ultraplot.colors.DiscreteNorm` if `values` was passed). Passed to the + `~ultraplot.constructor.Norm` constructor function. +norm_kw : dict-like, optional + Ignored if `mappable` is a `~matplotlib.cm.ScalarMappable`. These are the + normalizer keyword arguments. Passed to `~ultraplot.constructor.Norm`. +vmin, vmax : float, optional + Ignored if `mappable` is a `~matplotlib.cm.ScalarMappable`. These are the minimum + and maximum colorbar values. Passed to `~ultraplot.constructor.Norm`. +label, title : str, optional + The colorbar label. The `title` keyword is also accepted for + consistency with `~matplotlib.axes.Axes.legend`. +reverse : bool, optional + Whether to reverse the direction of the colorbar. This is done automatically + when descending levels are used with `~ultraplot.colors.DiscreteNorm`. +rotation : float, default: 0 + The tick label rotation. +grid, edges, drawedges : bool, default: :rc:`colorbar.grid` + Whether to draw "grid" dividers between each distinct color. +extend : {'neither', 'both', 'min', 'max'}, optional + Direction for drawing colorbar "extensions" (i.e. color keys for out-of-bounds + data on the end of the colorbar). Default behavior is to use the value of `extend` + passed to the plotting command or use ``'neither'`` if the value is unknown. +extendfrac : float, optional + The length of the colorbar "extensions" relative to the length of the colorbar. + This is a native matplotlib `~matplotlib.figure.Figure.colorbar` keyword. +extendsize : unit-spec, default: :rc:`colorbar.extend` or :rc:`colorbar.insetextend` + The length of the colorbar "extensions" in physical units. Default is + :rcraw:`colorbar.extend` for outer colorbars and :rcraw:`colorbar.insetextend` + for inset colorbars. If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +extendrect : bool, default: False + Whether to draw colorbar "extensions" as rectangles. If ``False`` then + the extensions are drawn as triangles. +locator, ticks : locator-spec, optional + Used to determine the colorbar tick positions. Passed to the + `~ultraplot.constructor.Locator` constructor function. By default + `~matplotlib.ticker.AutoLocator` is used for continuous color levels + and `~ultraplot.ticker.DiscreteLocator` is used for discrete color levels. +locator_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Locator` class. +minorlocator, minorticks + As with `locator`, `ticks` but for the minor ticks. By default + `~matplotlib.ticker.AutoMinorLocator` is used for continuous color levels + and `~ultraplot.ticker.DiscreteLocator` is used for discrete color levels. +minorlocator_kw + As with `locator_kw`, but for the minor ticks. +format, formatter, ticklabels : formatter-spec, optional + The tick label format. Passed to the `~ultraplot.constructor.Formatter` + constructor function. +formatter_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Formatter` class. +frame, frameon : bool, optional + For inset colorbars, indicates whether to draw a background "frame", + just like `~matplotlib.axes.Axes.legend`. Defaults to + :rc:`colorbar.frameon` for inset colorbars. For outer colorbars, this is a + backwards-compatible alias for `outline`; when omitted, outer colorbars + still default to :rc:`colorbar.outline`. +tickminor : bool, optional + Whether to add minor ticks using `~matplotlib.colorbar.ColorbarBase.minorticks_on`. +tickloc, ticklocation : {'bottom', 'top', 'left', 'right'}, optional + Where to draw tick marks on the colorbar. Default is toward the outside + of the subplot for outer colorbars and ``'bottom'`` for inset colorbars. +tickdir, tickdirection : {'out', 'in', 'inout'}, default: :rc:`tick.dir` + Direction of major and minor colorbar ticks. +ticklen : unit-spec, default: :rc:`tick.len` + Major tick lengths for the colorbar ticks. +ticklenratio : float, default: :rc:`tick.lenratio` + Relative scaling of `ticklen` used to determine minor tick lengths. +tickwidth : unit-spec, default: `linewidth` + Major tick widths for the colorbar ticks. + or :rc:`tick.width` if `linewidth` was not passed. +tickwidthratio : float, default: :rc:`tick.widthratio` + Relative scaling of `tickwidth` used to determine minor tick widths. +ticklabelcolor, ticklabelsize, ticklabelweight: default: :rc:`tick.labelcolor`, :rc:`tick.labelsize`, :rc:`tick.labelweight`. + The font color, size, and weight for colorbar tick labels +labelloc, labellocation : {'bottom', 'top', 'left', 'right'} + The colorbar label location. Inherits from `tickloc` by default. Default is toward + the outside of the subplot for outer colorbars and ``'bottom'`` for inset colorbars. +labelcolor, labelsize, labelweight: default: :rc:`label.color`, :rc:`label.size`, and :rc:`label.weight`. + The font color, size, and weight for the colorbar label. +a, alpha, framealpha, fc, facecolor, framecolor, ec, edgecolor, ew, edgewidth : default: :rc:`colorbar.framealpha`, :rc:`colorbar.framecolor` + For inset colorbars only. Controls the transparency and color of + the background frame. +lw, linewidth, c, color : optional + Controls the line width and edge color for both the colorbar + outline and the level dividers. +edgefix : bool or float, default: :rc:`edgefix` + Whether to fix the common issue where white lines appear between adjacent + patches in saved vector graphics (this can slow down figure rendering). + See this `github repo `__ for a + demonstration of the problem. If ``True``, a small default linewidth of + ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), + this specific linewidth is used to cover up the white lines. This feature is + automatically disabled when the patches have transparency. +rasterize : bool, default: :rc:`colorbar.rasterized` + Whether to rasterize the colorbar solids. The matplotlib default was ``True`` + but ultraplot changes this to ``False`` since rasterization can cause misalignment + between the color patches and the colorbar outline. +outline : bool, None default : None + Controls the visibility of the outer colorbar outline. When set to False, + the spines of the colorbar are hidden. If set to `None` it uses the + `rc['colorbar.outline']` value. +labelrotation : str, float, default: None + Controls the rotation of the colorbar label. When set to None it takes on the value of `rc["colorbar.labelrotation"]`. When set to auto it produces a sensible default where the rotation is adjusted to where the colorbar is located. For example, a horizontal colorbar with a label to the left or right will match the horizontal alignment and rotate the label to 0 degrees. Users can provide a float to rotate to any arbitrary angle. + + + +**kwargs + Passed to `~matplotlib.figure.Figure.colorbar`. + +See also +-------- +ultraplot.figure.Figure.colorbar +matplotlib.figure.Figure.colorbar""" + ... + + def legend(self, handles: Incomplete=None, labels: Incomplete=None, loc: Incomplete=None, location: Incomplete=None, span: Optional[Union[int, Tuple[int, int]]]=None, row: Optional[int]=None, col: Optional[int]=None, rows: Optional[Union[int, Tuple[int, int]]]=None, cols: Optional[Union[int, Tuple[int, int]]]=None, **kwargs: Incomplete) -> Incomplete: + """Add an inset legend or outer legend along the edge of the axes. + +Parameters +---------- +handles : list of artist, optional + List of matplotlib artists, or a list of lists of artist instances (see the `center` + keyword). If not passed, artists with valid labels (applied by passing `label` or + `labels` to a plotting command or calling `~matplotlib.artist.Artist.set_label`) + are retrieved automatically. If the object is a `~matplotlib.contour.ContourSet`, + `~matplotlib.contour.ContourSet.legend_elements` is used to select the central + artist in the list (generally useful for single-color contour plots). Note that + ultraplot's `~ultraplot.axes.PlotAxes.contour` and `~ultraplot.axes.PlotAxes.contourf` + accept a legend `label` keyword argument. +labels : list of str, optional + A matching list of string labels or ``None`` placeholders, or a matching list of + lists (see the `center` keyword). Wherever ``None`` appears in the list (or + if no labels were passed at all), labels are retrieved by calling + `~matplotlib.artist.Artist.get_label` on each `~matplotlib.artist.Artist` in the + handle list. If a handle consists of a tuple group of artists, labels are inferred + from the artists in the tuple (if there are multiple unique labels in the tuple + group of artists, the tuple group is expanded into unique legend entries -- + otherwise, the tuple group elements are drawn on top of eachother). For details + on matplotlib legend handlers and tuple groups, see the matplotlib `legend guide +-`__. +loc, location : int or str, default: :rc:`legend.loc` + The legend location. Valid location keys are shown in the below table. + + .. _legend_table: + + ================== ======================================= + Location Valid keys + ================== ======================================= + outer left ``'left'``, ``'l'`` + outer right ``'right'``, ``'r'`` + outer bottom ``'bottom'``, ``'b'`` + outer top ``'top'``, ``'t'`` + "best" inset ``'best'``, ``'inset'``, ``'i'``, ``0`` + upper right inset ``'upper right'``, ``'ur'``, ``1`` + upper left inset ``'upper left'``, ``'ul'``, ``2`` + lower left inset ``'lower left'``, ``'ll'``, ``3`` + lower right inset ``'lower right'``, ``'lr'``, ``4`` + center left inset ``'center left'``, ``'cl'``, ``5`` + center right inset ``'center right'``, ``'cr'``, ``6`` + lower center inset ``'lower center'``, ``'lc'``, ``7`` + upper center inset ``'upper center'``, ``'uc'``, ``8`` + center inset ``'center'``, ``'c'``, ``9`` + "filled" ``'fill'`` + ================== ======================================= + +width : unit-spec, optional + For outer legends only. The space allocated for the legend + box. This does nothing if the :ref:`tight layout algorithm + ` is active for the figure. + If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. +queue : bool, optional + If ``True`` and `loc` is the same as an existing legend, the input + arguments are added to a queue and this function returns ``None``. + This is used to "update" the same legend with successive ``ax.legend(...)`` + calls. If ``False`` (the default) and `loc` is the same as an existing + *inset* legend, the old legend is removed. If ``False`` and `loc` is an + *outer* legend, the legends are "stacked". +space : unit-spec, default: None + For outer legends only. The fixed space between the legend and the subplot + edge. If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + When the :ref:`tight layout algorithm ` is active for the figure, + `space` is computed automatically (see `pad`). Otherwise, `space` is set to + a suitable default. +pad : unit-spec, default: :rc:`subplots.panelpad` or :rc:`legend.borderaxespad` + For outer legends, this is the :ref:`tight layout padding ` + between the legend and the subplot (default is :rcraw:`subplots.panelpad`). + For inset legends, this is the fixed space between the axes + edge and the legend (default is :rcraw:`legend.borderaxespad`). + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +align : {'center', 'top', 'bottom', 'left', 'right', 't', 'b', 'l', 'r'}, optional + For outer legends only. How to align the legend against the subplot edge. + The values ``'top'`` and ``'bottom'`` are valid for left and right legends + and ``'left'`` and ``'right'`` are valid for top and bottom legends. + The default is always ``'center'``. + +Other parameters +---------------- +frame, frameon : bool, optional + Toggles the legend frame. For centered-row legends, a frame + independent from matplotlib's built-in legend frame is created. +ncol, ncols : int, optional + The number of columns. `ncols` is an alias, added + for consistency with `~matplotlib.pyplot.subplots`. +order : {'C', 'F'}, optional + Whether legend handles are drawn in row-major (``'C'``) or column-major + (``'F'``) order. Analagous to `numpy.array` ordering. The matplotlib + default was ``'F'`` but ultraplot changes this to ``'C'``. +center : bool, optional + Whether to center each legend row individually. If ``True``, we draw + successive single-row legends "stacked" on top of each other. If ``None``, + we infer this setting from `handles`. By default, `center` is set to ``True`` + if `handles` is a list of lists (each sublist is used as a row in the legend). +alphabetize : bool, default: False + Whether to alphabetize the legend entries according to + the legend labels. +title, label : str, optional + The legend title. The `label` keyword is also accepted, for consistency + with `~matplotlib.figure.Figure.colorbar`. +fontsize, fontweight, fontcolor : optional + The font size, weight, and color for the legend text. Font size is interpreted + by `~ultraplot.utils.units`. The default font size is :rcraw:`legend.fontsize`. +titlefontsize, titlefontweight, titlefontcolor : optional + The font size, weight, and color for the legend title. Font size is interpreted + by `~ultraplot.utils.units`. The default size is `fontsize`. +borderpad, borderaxespad, handlelength, handleheight, handletextpad, labelspacing, columnspacing : unit-spec, optional + Various matplotlib `~matplotlib.axes.Axes.legend` spacing arguments. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +a, alpha, framealpha, fc, facecolor, framecolor, ec, edgecolor, ew, edgewidth: default: :rc:`legend.framealpha`, :rc:`legend.facecolor`, :rc:`legend.edgecolor`, :rc:`axes.linewidth` The opacity, face color, edge color, and edge width for the legend frame. +c, color, lw, linewidth, m, marker, ls, linestyle, dashes, ms, markersize : optional + Properties used to override the legend handles. For example, for a + legend describing variations in line style ignoring variations + in color, you might want to use ``color='black'``. +handle_kw : dict-like, optional + Additional properties used to override legend handles, e.g. + ``handle_kw={'edgecolor': 'black'}``. Only line properties + can be passed as keyword arguments. +handler_map : dict-like, optional + A dictionary mapping instances or types to a legend handler. + This `handler_map` updates the default handler map found at + `matplotlib.legend.Legend.get_legend_handler_map`. +**kwargs + Passed to `~matplotlib.axes.Axes.legend`. + +See also +-------- +ultraplot.figure.Figure.legend +matplotlib.axes.Axes.legend""" + ... + + def add_legend(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Back-compatibility alias for older Matplotlib/Seaborn integrations that call +``add_legend``. + +Newer code should call :meth:`legend`, but some callers still rely on this +Matplotlib-internal entry point.""" + ... + + def catlegend(self, categories: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Build a categorical legend — one handle per unique category — and +optionally draw it. + +Parameters +---------- +categories : iterable + Category labels in display order. Duplicates are collapsed; the + first occurrence determines position. +color, marker + A style value resolved per legend entry. Accepts a **scalar** (applied + to every entry), a **list / tuple / ndarray** (one value per entry, + cycled to match the number of entries), or a **dict** (mapping from + label — or from numeric value for ``sizelegend`` / ``numlegend`` — to + style; missing keys fall back to the default). A 3- or 4-element + sequence of floats in ``[0, 1]`` is treated as a single RGB(A) color + rather than as per-entry values, so ``color=[0.5, 0.5, 0.5]`` and + ``color=(0.5, 0.5, 0.5)`` behave the same. + Defaults to ultraplot's color cycle for ``color`` and ``"o"`` for + ``marker`` (or :rc:`legend.cat.marker` when set). +line : bool, optional + Whether to render connector lines through the markers. Falls back + to :rc:`legend.cat.line`. Setting a non-default ``linestyle`` + implicitly enables this. +Other parameters +---------------- +Common style keywords accepted via ``handle_kw`` or ``**kwargs``: + +``color`` / ``c`` + Marker (and line, when ``line=True``) color. ``c`` is the short alias. +``marker`` / ``m`` + Marker spec. Set to ``None`` or ``""`` to suppress the marker. +``markersize`` / ``ms``, ``markeredgewidth`` / ``mew`` + Marker dimensions. ``markersize`` / ``ms`` denote marker diameter in points. +``s`` / ``size`` / ``sizes`` + Scatter-style marker areas, converted to marker diameters for the legend + handle. Use ``markersize`` / ``ms`` when specifying diameters directly. +``markerfacecolor`` / ``mfc``, ``markeredgecolor`` / ``mec``, ``markerfacecoloralt`` / ``mfcalt`` + Marker fills and edges. +``linestyle`` / ``ls``, ``linewidth`` / ``lw`` + Connector line styling. Setting a non-default ``linestyle`` implicitly + enables ``line=True``. +``alpha``, ``antialiased`` / ``aa``, ``fillstyle`` / ``fs`` + Generic appearance. +``marker_capstyle``, ``marker_joinstyle``, ``marker_transform`` + Advanced ``MarkerStyle`` properties; wrapped into the rendered marker. + +Plural forms (``colors``, ``markers``, ``edgecolors``, ``facecolors``, +``linestyles``, ``linewidths``) are accepted as synonyms for the singular +per-entry form for backward compatibility. ``sizes`` is accepted as a +scatter-style area alias. +Each value accepts the scalar / sequence / mapping forms described in +``A style value resolved per legend entry. Accepts a **scalar** (applied + to every entry), a **list / tuple / ndarray** (one value per entry, + cycled to match the number of entries), or a **dict** (mapping from + label — or from numeric value for ``sizelegend`` / ``numlegend`` — to + style; missing keys fall back to the default). A 3- or 4-element + sequence of floats in ``[0, 1]`` is treated as a single RGB(A) color + rather than as per-entry values, so ``color=[0.5, 0.5, 0.5]`` and + ``color=(0.5, 0.5, 0.5)`` behave the same.``. +handle_kw : dict, optional + Style overrides applied to each generated handle. Same vocabulary as + ``**kwargs``; useful when style kwargs would otherwise collide with + matplotlib's :class:`~matplotlib.legend.Legend` keywords (``loc``, + ``title``, …). +add : bool, default: True + When ``True`` (default), draw the legend on the axes and return the + legend artist. When ``False``, return ``(handles, labels)`` without + drawing — useful for composing into a parent legend. +**kwargs + Style keywords applied per entry (see above), plus any + :class:`~matplotlib.legend.Legend` keyword. + +See also +-------- +Axes.entrylegend +Axes.sizelegend""" + ... + + def entrylegend(self, entries: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Build generic semantic legend entries from explicit ``{label: style}`` +entries and optionally draw the legend. + +Parameters +---------- +entries : iterable or mapping + Entry specifications. Either a sequence of ``{**style_kwargs}`` + dicts (each requiring at least ``label``) or a mapping from label + to style-kwargs dict. +line : bool, optional + Whether each entry shows a connector line. Falls back to + :rc:`legend.cat.line`. +marker, color + A style value resolved per legend entry. Accepts a **scalar** (applied + to every entry), a **list / tuple / ndarray** (one value per entry, + cycled to match the number of entries), or a **dict** (mapping from + label — or from numeric value for ``sizelegend`` / ``numlegend`` — to + style; missing keys fall back to the default). A 3- or 4-element + sequence of floats in ``[0, 1]`` is treated as a single RGB(A) color + rather than as per-entry values, so ``color=[0.5, 0.5, 0.5]`` and + ``color=(0.5, 0.5, 0.5)`` behave the same. +Other parameters +---------------- +Common style keywords accepted via ``handle_kw`` or ``**kwargs``: + +``color`` / ``c`` + Marker (and line, when ``line=True``) color. ``c`` is the short alias. +``marker`` / ``m`` + Marker spec. Set to ``None`` or ``""`` to suppress the marker. +``markersize`` / ``ms``, ``markeredgewidth`` / ``mew`` + Marker dimensions. ``markersize`` / ``ms`` denote marker diameter in points. +``s`` / ``size`` / ``sizes`` + Scatter-style marker areas, converted to marker diameters for the legend + handle. Use ``markersize`` / ``ms`` when specifying diameters directly. +``markerfacecolor`` / ``mfc``, ``markeredgecolor`` / ``mec``, ``markerfacecoloralt`` / ``mfcalt`` + Marker fills and edges. +``linestyle`` / ``ls``, ``linewidth`` / ``lw`` + Connector line styling. Setting a non-default ``linestyle`` implicitly + enables ``line=True``. +``alpha``, ``antialiased`` / ``aa``, ``fillstyle`` / ``fs`` + Generic appearance. +``marker_capstyle``, ``marker_joinstyle``, ``marker_transform`` + Advanced ``MarkerStyle`` properties; wrapped into the rendered marker. + +Plural forms (``colors``, ``markers``, ``edgecolors``, ``facecolors``, +``linestyles``, ``linewidths``) are accepted as synonyms for the singular +per-entry form for backward compatibility. ``sizes`` is accepted as a +scatter-style area alias. +Each value accepts the scalar / sequence / mapping forms described in +``A style value resolved per legend entry. Accepts a **scalar** (applied + to every entry), a **list / tuple / ndarray** (one value per entry, + cycled to match the number of entries), or a **dict** (mapping from + label — or from numeric value for ``sizelegend`` / ``numlegend`` — to + style; missing keys fall back to the default). A 3- or 4-element + sequence of floats in ``[0, 1]`` is treated as a single RGB(A) color + rather than as per-entry values, so ``color=[0.5, 0.5, 0.5]`` and + ``color=(0.5, 0.5, 0.5)`` behave the same.``. +handle_kw : dict, optional + Style overrides applied to each generated handle. Same vocabulary as + ``**kwargs``; useful when style kwargs would otherwise collide with + matplotlib's :class:`~matplotlib.legend.Legend` keywords (``loc``, + ``title``, …). +add : bool, default: True + When ``True`` (default), draw the legend on the axes and return the + legend artist. When ``False``, return ``(handles, labels)`` without + drawing — useful for composing into a parent legend. +**kwargs + Style keywords applied per entry (see above), plus any + :class:`~matplotlib.legend.Legend` keyword. + +See also +-------- +Axes.catlegend +Axes.sizelegend""" + ... + + def sizelegend(self, levels: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Build a size legend — one handle per level, scaled by marker size — +and optionally draw it. + +Parameters +---------- +levels : iterable of float + Numeric values to render as size-scaled markers. +labels : iterable or mapping, optional + Custom labels. A mapping ``{level: label}`` overrides individual + entries (every level must be a key). When omitted, labels are + formatted from ``levels`` via ``fmt``. +color, marker + A style value resolved per legend entry. Accepts a **scalar** (applied + to every entry), a **list / tuple / ndarray** (one value per entry, + cycled to match the number of entries), or a **dict** (mapping from + label — or from numeric value for ``sizelegend`` / ``numlegend`` — to + style; missing keys fall back to the default). A 3- or 4-element + sequence of floats in ``[0, 1]`` is treated as a single RGB(A) color + rather than as per-entry values, so ``color=[0.5, 0.5, 0.5]`` and + ``color=(0.5, 0.5, 0.5)`` behave the same. + Defaults to :rc:`legend.size.color` and :rc:`legend.size.marker`. +area : bool, optional + Treat ``levels`` as marker areas (``True``, default) or + diameters (``False``). Areas are converted with + ``ms = sqrt(level) * scale``. Falls back to :rc:`legend.size.area`. +values : array-like, optional + Full scatter-size data used to infer the scaling range for + ``levels``. When provided, or when any of ``vmin``, ``vmax``, + ``smin``, ``smax``, ``area_size``, or ``absolute_size`` are + provided, ``levels`` are transformed with the same size scaling + rules used by :meth:`~ultraplot.axes.PlotAxes.scatter` while + labels remain based on the original ``levels``. When these options + are omitted and a compatible UltraPlot scatter artist already exists + on the axes, its size scale is inferred automatically. +vmin, vmax : float, optional + Explicit data range for scatter-style size scaling. Defaults to the + finite range of ``values`` or ``levels``. +smin, smax : float, optional + Minimum and maximum scaled marker sizes, with the same meaning as + in :meth:`~ultraplot.axes.PlotAxes.scatter`. +area_size, absolute_size : bool, optional + Scatter-style size scaling switches. Defaults match + :meth:`~ultraplot.axes.PlotAxes.scatter` when scatter-style scaling + is active. When scatter-style scaling is active and ``area_size`` is + omitted, an explicit ``area=False`` is treated like + ``area_size=False``. +scale : float, optional + Multiplier applied after area/diameter conversion. + Falls back to :rc:`legend.size.scale`. +minsize : float, optional + Lower bound on rendered marker size. + Falls back to :rc:`legend.size.minsize`. +fmt : str or callable, optional + Format used to label levels. Falls back to :rc:`legend.size.format`. + +Other parameters +---------------- +Common style keywords accepted via ``handle_kw`` or ``**kwargs``: + +``color`` / ``c`` + Marker (and line, when ``line=True``) color. ``c`` is the short alias. +``marker`` / ``m`` + Marker spec. Set to ``None`` or ``""`` to suppress the marker. +``markersize`` / ``ms``, ``markeredgewidth`` / ``mew`` + Marker dimensions. ``markersize`` / ``ms`` denote marker diameter in points. +``s`` / ``size`` / ``sizes`` + Scatter-style marker areas, converted to marker diameters for the legend + handle. Use ``markersize`` / ``ms`` when specifying diameters directly. +``markerfacecolor`` / ``mfc``, ``markeredgecolor`` / ``mec``, ``markerfacecoloralt`` / ``mfcalt`` + Marker fills and edges. +``linestyle`` / ``ls``, ``linewidth`` / ``lw`` + Connector line styling. Setting a non-default ``linestyle`` implicitly + enables ``line=True``. +``alpha``, ``antialiased`` / ``aa``, ``fillstyle`` / ``fs`` + Generic appearance. +``marker_capstyle``, ``marker_joinstyle``, ``marker_transform`` + Advanced ``MarkerStyle`` properties; wrapped into the rendered marker. + +Plural forms (``colors``, ``markers``, ``edgecolors``, ``facecolors``, +``linestyles``, ``linewidths``) are accepted as synonyms for the singular +per-entry form for backward compatibility. ``sizes`` is accepted as a +scatter-style area alias. +Each value accepts the scalar / sequence / mapping forms described in +``A style value resolved per legend entry. Accepts a **scalar** (applied + to every entry), a **list / tuple / ndarray** (one value per entry, + cycled to match the number of entries), or a **dict** (mapping from + label — or from numeric value for ``sizelegend`` / ``numlegend`` — to + style; missing keys fall back to the default). A 3- or 4-element + sequence of floats in ``[0, 1]`` is treated as a single RGB(A) color + rather than as per-entry values, so ``color=[0.5, 0.5, 0.5]`` and + ``color=(0.5, 0.5, 0.5)`` behave the same.``. +handle_kw : dict, optional + Style overrides applied to each generated handle. Same vocabulary as + ``**kwargs``; useful when style kwargs would otherwise collide with + matplotlib's :class:`~matplotlib.legend.Legend` keywords (``loc``, + ``title``, …). +add : bool, default: True + When ``True`` (default), draw the legend on the axes and return the + legend artist. When ``False``, return ``(handles, labels)`` without + drawing — useful for composing into a parent legend. +**kwargs + Style keywords applied per entry (see above), plus any + :class:`~matplotlib.legend.Legend` keyword. + +See also +-------- +Axes.catlegend +Axes.numlegend""" + ... + + def numlegend(self, levels: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Build a numeric legend — one patch handle per level, colored from a +colormap — and optionally draw it. + +Parameters +---------- +levels : iterable of float, optional + Numeric levels to render. When omitted, ``n`` evenly spaced + levels are derived from ``vmin`` / ``vmax``. +vmin, vmax : float, optional + Limits for sampling ``cmap`` when ``norm`` is not provided. +n : int, optional + Number of levels to sample when ``levels`` is omitted. + Falls back to :rc:`legend.num.n`. +cmap : str or `~matplotlib.colors.Colormap`, optional + Colormap used to color the patches. + Falls back to :rc:`legend.num.cmap`. +norm : `~matplotlib.colors.Normalize`, optional + Normalization applied to ``levels`` before colormap lookup. +fmt : str or callable, optional + Format used to label levels. + Falls back to :rc:`legend.num.format`. +facecolor, edgecolor + A style value resolved per legend entry. Accepts a **scalar** (applied + to every entry), a **list / tuple / ndarray** (one value per entry, + cycled to match the number of entries), or a **dict** (mapping from + label — or from numeric value for ``sizelegend`` / ``numlegend`` — to + style; missing keys fall back to the default). A 3- or 4-element + sequence of floats in ``[0, 1]`` is treated as a single RGB(A) color + rather than as per-entry values, so ``color=[0.5, 0.5, 0.5]`` and + ``color=(0.5, 0.5, 0.5)`` behave the same. + ``facecolor`` defaults to colormap-derived values; ``edgecolor`` + falls back to :rc:`legend.num.edgecolor`. +linewidth, linestyle, alpha + Patch outline width, style, and transparency. ``linewidth`` / + ``alpha`` fall back to :rc:`legend.num.linewidth` / + :rc:`legend.num.alpha`. + +Other parameters +---------------- +Patch-style keywords accepted via ``handle_kw`` or ``**kwargs``: + +``facecolor`` / ``fc``, ``edgecolor`` / ``ec``, ``color`` / ``c`` + Patch fills and edges. +``linewidth`` / ``lw``, ``linestyle`` / ``ls`` + Patch outline styling. +``alpha``, ``antialiased`` / ``aa``, ``hatch``, ``fill``, +``joinstyle``, ``capstyle`` + Generic patch appearance. + +Plural collection forms (``colors``, ``facecolors``, ``edgecolors``, +``linestyles``, ``linewidths``) map to the singular per-entry form. +Each value accepts the scalar / sequence / mapping forms described in +``A style value resolved per legend entry. Accepts a **scalar** (applied + to every entry), a **list / tuple / ndarray** (one value per entry, + cycled to match the number of entries), or a **dict** (mapping from + label — or from numeric value for ``sizelegend`` / ``numlegend`` — to + style; missing keys fall back to the default). A 3- or 4-element + sequence of floats in ``[0, 1]`` is treated as a single RGB(A) color + rather than as per-entry values, so ``color=[0.5, 0.5, 0.5]`` and + ``color=(0.5, 0.5, 0.5)`` behave the same.``. +handle_kw : dict, optional + Style overrides applied to each generated handle. Same vocabulary as + ``**kwargs``; useful when style kwargs would otherwise collide with + matplotlib's :class:`~matplotlib.legend.Legend` keywords (``loc``, + ``title``, …). +add : bool, default: True + When ``True`` (default), draw the legend on the axes and return the + legend artist. When ``False``, return ``(handles, labels)`` without + drawing — useful for composing into a parent legend. +**kwargs + Style keywords applied per entry (see above), plus any + :class:`~matplotlib.legend.Legend` keyword. + +See also +-------- +Axes.sizelegend +Axes.geolegend""" + ... + + def geolegend(self, entries: Incomplete, labels: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Build a geometry legend — one patch handle per geometry entry — and +optionally draw it. + +Parameters +---------- +entries : iterable or mapping + Either a sequence of ``(label, geometry)`` pairs or a mapping + from label to geometry specification (string keyword, shapely + geometry, ``cartopy`` feature, or a country name when + ``country_reso`` is set). +labels : iterable, optional + Labels overriding those derived from ``entries``. +country_reso : str, optional + Natural Earth resolution for country geometries (e.g. ``"110m"``). + Falls back to :rc:`legend.geo.country_reso`. +country_territories : bool, optional + Whether country lookups include overseas territories. + Falls back to :rc:`legend.geo.country_territories`. +country_proj : any, optional + Projection used to render country geometries; ignored for non- + country entries. Falls back to :rc:`legend.geo.country_proj`. +handlesize : float, optional + Multiplier applied to legend ``handlelength`` / ``handleheight`` + to enlarge geometry handles. Falls back to + :rc:`legend.geo.handlesize`. Must be positive. +facecolor, edgecolor + A style value resolved per legend entry. Accepts a **scalar** (applied + to every entry), a **list / tuple / ndarray** (one value per entry, + cycled to match the number of entries), or a **dict** (mapping from + label — or from numeric value for ``sizelegend`` / ``numlegend`` — to + style; missing keys fall back to the default). A 3- or 4-element + sequence of floats in ``[0, 1]`` is treated as a single RGB(A) color + rather than as per-entry values, so ``color=[0.5, 0.5, 0.5]`` and + ``color=(0.5, 0.5, 0.5)`` behave the same. + Default to :rc:`legend.geo.facecolor` / :rc:`legend.geo.edgecolor`. +linewidth, alpha, fill + Patch outline width, transparency, and fill toggle. + Defaults from :rc:`legend.geo.linewidth` / :rc:`legend.geo.alpha` / + :rc:`legend.geo.fill`. + +Other parameters +---------------- +Patch-style keywords accepted via ``handle_kw`` or ``**kwargs``: + +``facecolor`` / ``fc``, ``edgecolor`` / ``ec``, ``color`` / ``c`` + Patch fills and edges. +``linewidth`` / ``lw``, ``linestyle`` / ``ls`` + Patch outline styling. +``alpha``, ``antialiased`` / ``aa``, ``hatch``, ``fill``, +``joinstyle``, ``capstyle`` + Generic patch appearance. + +Plural collection forms (``colors``, ``facecolors``, ``edgecolors``, +``linestyles``, ``linewidths``) map to the singular per-entry form. +Each value accepts the scalar / sequence / mapping forms described in +``A style value resolved per legend entry. Accepts a **scalar** (applied + to every entry), a **list / tuple / ndarray** (one value per entry, + cycled to match the number of entries), or a **dict** (mapping from + label — or from numeric value for ``sizelegend`` / ``numlegend`` — to + style; missing keys fall back to the default). A 3- or 4-element + sequence of floats in ``[0, 1]`` is treated as a single RGB(A) color + rather than as per-entry values, so ``color=[0.5, 0.5, 0.5]`` and + ``color=(0.5, 0.5, 0.5)`` behave the same.``. +handle_kw : dict, optional + Style overrides applied to each generated handle. Same vocabulary as + ``**kwargs``; useful when style kwargs would otherwise collide with + matplotlib's :class:`~matplotlib.legend.Legend` keywords (``loc``, + ``title``, …). +add : bool, default: True + When ``True`` (default), draw the legend on the axes and return the + legend artist. When ``False``, return ``(handles, labels)`` without + drawing — useful for composing into a parent legend. +**kwargs + Style keywords applied per entry (see above), plus any + :class:`~matplotlib.legend.Legend` keyword. + +Notes +----- +Geometry legend entries use normalized patch proxies inside the legend +handle box rather than reusing the original map artist directly. This +preserves the general geometry shape and copied patch styling, but very +small or high-aspect-ratio handles can still make hatches difficult to +read at legend scale. + +See also +-------- +Axes.numlegend""" + ... + + @classmethod + def _coerce_curve_xy(cls, x: Incomplete, y: Incomplete) -> Incomplete: + """Return validated 1D numeric curve coordinates or ``None``.""" + ... + + @classmethod + def _coerce_curve_xy_from_xy_arg(cls, xy: Incomplete) -> Incomplete: + """Parse annotate-style ``xy`` into validated curve arrays or ``None``.""" + ... + + @staticmethod + def _curve_center(x: Incomplete, y: Incomplete, transform: Incomplete) -> tuple[float, float]: + """Return the arc-length midpoint of a curve in the curve coordinate system.""" + ... + + def text(self, *args: Incomplete, avoid_overlap: Incomplete=None, border: Incomplete=False, bbox: Incomplete=False, bordercolor: Incomplete='w', borderwidth: Incomplete=2, borderinvert: Incomplete=False, borderstyle: Incomplete=None, bboxcolor: Incomplete='w', bboxstyle: Incomplete='round', bboxalpha: Incomplete=0.5, bboxpad: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Add text to the axes. + +Parameters +---------- +x, y, [z] : float + The coordinates for the text. `~ultraplot.axes.ThreeAxes` accept an + optional third coordinate. If only two are provided this automatically + redirects to the `~mpl_toolkits.mplot3d.Axes3D.text2D` method. +s, text : str + The string for the text. +transform : {'data', 'axes', 'figure', 'subfigure'} or `~matplotlib.transforms.Transform`, optional + The transform used to interpret the bounds. Can be a + :class:`~matplotlib.transforms.Transform` instance or a string representing + the :class:`~matplotlib.axes.Axes.transData`, :class:`~matplotlib.axes.Axes.transAxes`, + :class:`~matplotlib.figure.Figure.transFigure`, or + :class:`~matplotlib.figure.Figure.transSubfigure`, transforms. + +Other parameters +---------------- +avoid_overlap : bool, default: :rc:`text.align` + Whether to automatically nudge this text at draw time so it does not + overlap other auto-aligned text or the plotted data. See + `~ultraplot.axes.Axes.auto_align_text` for the solver settings. +border : bool, default: False + Whether to draw border around text. +borderwidth : float, default: 2 + The width of the text border. +bordercolor : color-spec, default: 'w' + The color of the text border. +borderinvert : bool, optional + If ``True``, the text and border colors are swapped. +borderstyle : {'miter', 'round', 'bevel'}, default: :rc:`text.borderstyle` + The `line join style `__ + used for the border. +bbox : bool, default: False + Whether to draw a bounding box around text. +bboxcolor : color-spec, default: 'w' + The color of the text bounding box. +bboxstyle : boxstyle, default: 'round' + The style of the bounding box. +bboxalpha : float, default: 0.5 + The alpha for the bounding box. +bboxpad : float, default: :rc:`title.bboxpad` + The padding for the bounding box. +fontfamily : str, optional + The font typeface name (e.g., ``'Fira Math'``) or font family name (e.g., + ``'serif'``). Matplotlib falls back to the system default if not found. Aliases: ``family``, ``name``, ``fontname``. +fontsize : unit-spec or str, optional + The font size. Aliases: ``size``. If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + This can also be a string indicating some scaling relative to + :rcraw:`font.size`. The sizes and scalings are shown below. The + scalings ``'med'``, ``'med-small'``, and ``'med-large'`` are + added by ultraplot while the rest are native matplotlib sizes. + + .. _font_table: + + ========================== ===== + Size Scale + ========================== ===== + ``'xx-small'`` 0.579 + ``'x-small'`` 0.694 + ``'small'``, ``'smaller'`` 0.833 + ``'med-small'`` 0.9 + ``'med'``, ``'medium'`` 1.0 + ``'med-large'`` 1.1 + ``'large'``, ``'larger'`` 1.2 + ``'x-large'`` 1.440 + ``'xx-large'`` 1.728 + ``'larger'`` 1.2 + ========================== ===== + +**kwargs + Passed to `matplotlib.axes.Axes.text`. + +See also +-------- +matplotlib.axes.Axes.text +ultraplot.axes.Axes.auto_align_text""" + ... + + def _register_align_text(self, obj: Incomplete, avoid_overlap: Incomplete=None) -> Incomplete: + """Queue a text object for draw-time overlap avoidance, or release it.""" + ... + + def auto_align_text(self, *objs: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Automatically reposition text so that it does not overlap. + +Labels are relaxed away from each other, from the plotted data and from +the axes edges at draw time, then pulled back towards where you put them. +Because the solver runs on every draw, the layout stays valid when the +figure is resized or the data limits change. + +Parameters +---------- +*objs : `~matplotlib.text.Text`, optional + The text or annotation objects to align. Default is every text + created with ``avoid_overlap=True`` plus, if none were, all the text + you added to the axes. +pad : float, default: :rc:`text.align.pad` + Padding in points kept around each label. +avoid_points : bool, default: True + Whether labels also repel the data points of lines and scatter plots. +avoid : sequence of `~matplotlib.artist.Artist`, optional + Extra artists whose bounding boxes the labels must stay clear of. +only_move : {'xy', 'x', 'y'}, default: 'xy' + Restrict movement to one axis. Use ``'y'`` when the horizontal + position of a label carries meaning, as on a time series. +max_iter : int, default: :rc:`text.align.maxiter` + Maximum number of relaxation iterations. +spring : float, default: 0.05 + Strength of the pull back towards the original position. Larger + values keep labels closer to their anchors at the cost of overlap. +step : float, default: 0.6 + Damping applied to each iteration's displacement. +clip : bool, default: True + Whether to keep labels inside the axes. +arrows : bool or dict, default: :rc:`text.align.arrows` + Whether to draw a connector from each displaced label back to the + point it labels. A dict is passed to `~matplotlib.patches.FancyArrowPatch`. +min_arrow_dist : float, default: 8.0 + Only draw connectors for labels displaced further than this, in points. + +Examples +-------- +>>> import ultraplot as uplt +>>> fig, ax = uplt.subplots() +>>> ax.scatter(x, y) +>>> for xi, yi, name in zip(x, y, names): +... ax.text(xi, yi, name) +>>> ax.auto_align_text() + +See also +-------- +ultraplot.axes.Axes.text +ultraplot.axes.Axes.annotate""" + ... + + def _apply_align_text(self, renderer: Incomplete) -> None: + """Run the overlap solver for this axes (called on every draw).""" + ... + + def annotate(self, text: str, xy: Union[Tuple[float, float], Tuple[Iterable[float], Iterable[float]], Iterable[float], np.ndarray], xytext: Optional[Union[Tuple[float, float], Iterable[float], np.ndarray]]=None, xycoords: Union[str, mtransforms.Transform]='data', textcoords: Optional[Union[str, mtransforms.Transform]]=None, arrowprops: Optional[dict[str, Any]]=None, annotation_clip: Optional[bool]=None, avoid_overlap: Optional[bool]=None, **kwargs: Any) -> Incomplete: + """Add an annotation. If `xy` is a pair of 1D arrays, draw curved text. + +For curved input with `arrowprops`, the arrow points to the curve center. + +Parameters +---------- +avoid_overlap : bool, default: :rc:`text.align` + Whether to automatically nudge this annotation at draw time so it + does not overlap other auto-aligned text or the plotted data. See + `~ultraplot.axes.Axes.auto_align_text`.""" + ... + + def curvedtext(self, x: Incomplete, y: Incomplete, text: Incomplete, *, upright: Incomplete=None, ellipsis: Incomplete=None, avoid_overlap: Incomplete=None, overlap_tol: Incomplete=None, curvature_pad: Incomplete=None, min_advance: Incomplete=None, border: Incomplete=False, bbox: Incomplete=False, bordercolor: Incomplete='w', borderwidth: Incomplete=2, borderinvert: Incomplete=False, borderstyle: Incomplete='miter', bboxcolor: Incomplete='w', bboxstyle: Incomplete='round', bboxalpha: Incomplete=0.5, bboxpad: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Add curved text that follows a curve. + +Parameters +---------- +x, y : array-like + Curve coordinates. +text : str + The string for the text. +transform : {'data', 'axes', 'figure', 'subfigure'} or `~matplotlib.transforms.Transform`, optional + The transform used to interpret the bounds. Can be a + :class:`~matplotlib.transforms.Transform` instance or a string representing + the :class:`~matplotlib.axes.Axes.transData`, :class:`~matplotlib.axes.Axes.transAxes`, + :class:`~matplotlib.figure.Figure.transFigure`, or + :class:`~matplotlib.figure.Figure.transSubfigure`, transforms. + +Other parameters +---------------- +border : bool, default: False + Whether to draw border around text. +borderwidth : float, default: 2 + The width of the text border. +bordercolor : color-spec, default: 'w' + The color of the text border. +borderinvert : bool, optional + If ``True``, the text and border colors are swapped. +upright : bool, default: :rc:`text.curved.upright` + Whether to flip the curve direction to keep text upright. +ellipsis : bool, default: :rc:`text.curved.ellipsis` + Whether to show an ellipsis when the text exceeds curve length. +avoid_overlap : bool, default: :rc:`text.curved.avoid_overlap` + Whether to hide glyphs that overlap after rotation. +overlap_tol : float, default: :rc:`text.curved.overlap_tol` + Fractional overlap area (0–1) required before hiding a glyph. +curvature_pad : float, default: :rc:`text.curved.curvature_pad` + Extra spacing in pixels per radian of local curvature. +min_advance : float, default: :rc:`text.curved.min_advance` + Minimum additional spacing (pixels) enforced between glyph centers. +borderstyle : {'miter', 'round', 'bevel'}, default: 'miter' + The `line join style `__ + used for the border. +bbox : bool, default: False + Whether to draw a bounding box around text. +bboxcolor : color-spec, default: 'w' + The color of the text bounding box. +bboxstyle : boxstyle, default: 'round' + The style of the bounding box. +bboxalpha : float, default: 0.5 + The alpha for the bounding box. +bboxpad : float, default: :rc:`title.bboxpad` + The padding for the bounding box. +fontfamily : str, optional + The font typeface name (e.g., ``'Fira Math'``) or font family name (e.g., + ``'serif'``). Matplotlib falls back to the system default if not found. Aliases: ``family``, ``name``, ``fontname``. +fontsize : unit-spec or str, optional + The font size. Aliases: ``size``. If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + This can also be a string indicating some scaling relative to + :rcraw:`font.size`. The sizes and scalings are shown below. The + scalings ``'med'``, ``'med-small'``, and ``'med-large'`` are + added by ultraplot while the rest are native matplotlib sizes. + + .. _font_table: + + ========================== ===== + Size Scale + ========================== ===== + ``'xx-small'`` 0.579 + ``'x-small'`` 0.694 + ``'small'``, ``'smaller'`` 0.833 + ``'med-small'`` 0.9 + ``'med'``, ``'medium'`` 1.0 + ``'med-large'`` 1.1 + ``'large'``, ``'larger'`` 1.2 + ``'x-large'`` 1.440 + ``'xx-large'`` 1.728 + ``'larger'`` 1.2 + ========================== ===== + +**kwargs + Passed to `matplotlib.text.Text`.""" + ... + + def _toggle_spines(self, spines: Union[bool, Iterable, str]) -> None: + """Turns spines on or off depending on input. Spines can be a list such as ['left', 'right'] etc""" + ... + + def _iter_axes(self, hidden: Incomplete=False, children: Incomplete=False, panels: Incomplete=True) -> Incomplete: + """Return a list of visible axes, panel axes, and child axes of both. + +Parameters +---------- +hidden : bool, optional + Whether to include "hidden" panels. +children : bool, optional + Whether to include children. Note this now includes "twin" axes. +panels : bool or str or sequence of str, optional + Whether to include panels or the panels to include.""" + ... + + @property + def number(self) -> Incomplete: + """The axes number. This controls the order of a-b-c labels and the +order of appearance in the :class:`~ultraplot.gridspec.SubplotGrid` returned +by `~ultraplot.figure.Figure.subplots`.""" + ... + + @number.setter + def number(self, num: Incomplete) -> None: + ... + + @property + def use_sticky_edges(self) -> Incomplete: + """Whether plotting commands like `plot`, `plotx`, `vlines`, `hlines`, +`fill_between`, and `fill_betweenx` add "sticky" edges to their artists, +i.e. whether the default axis limits are the artist bounds with no padding. +Initialized from :rcraw:`axes.sticky_edges`.""" + ... + + @use_sticky_edges.setter + def use_sticky_edges(self, value: Incomplete) -> None: + ... + +def _get_pos_from_locator(loc: str, x_pad: float, y_pad: float) -> tuple[float, float]: + """Helper function to map string locators to x and y coordinates.""" + ... + +def _get_axis_for(labelloc: str, loc: str, *, ax: Axes, orientation: str) -> Axes: + """Helper function to determine the axis for a label. +Particularly used for colorbars but can be used for other purposes""" + ... + +def _determine_label_rotation(labelrotation: str | Number, labelloc: str, orientation: str, kw_label: MutableMapping) -> Incomplete: + """Note we update kw_label in place.""" + ... + +def _resolve_label_rotation(labelrotation: str | Number, *, labelloc: str, orientation: str) -> float: + ... + +def _measure_label_points(label: str, rotation: float, fontsize: float, figure: Incomplete) -> Optional[Tuple[float, float]]: + ... + +def _measure_text_artist_points(text: mtext.Text, figure: Incomplete) -> Optional[Tuple[float, float]]: + ... + +def _measure_ticklabel_extent_points(axis: Incomplete, figure: Incomplete) -> Optional[Tuple[float, float]]: + ... + +def _measure_text_overhang_axes(text: mtext.Text, axes: Incomplete) -> Optional[Tuple[float, float, float, float]]: + ... + +def _measure_ticklabel_overhang_axes(axis: Incomplete, axes: Incomplete) -> Optional[Tuple[float, float, float, float]]: + ... + +def _get_colorbar_long_axis(colorbar: Incomplete) -> Incomplete: + ... + +def _register_inset_colorbar_reflow(fig: Incomplete) -> Incomplete: + ... + +def _solve_inset_colorbar_bounds(*, axes: 'Axes', loc: str, orientation: str, length: float, width: float, xpad: float, ypad: float, ticklocation: str, labelloc: Optional[str], label: Incomplete, labelrotation: Union[str, float, None], tick_fontsize: float, label_fontsize: float) -> Tuple[list[float], list[float]]: + ... + +def _legacy_inset_colorbar_bounds(*, axes: 'Axes', loc: str, orientation: str, length: float, width: float, xpad: float, ypad: float, ticklocation: str, labelloc: Optional[str], label: Incomplete, labelrotation: Union[str, float, None], tick_fontsize: float, label_fontsize: float) -> Tuple[list[float], list[float]]: + ... + +def _apply_inset_colorbar_layout(axes: 'Axes', *, bounds_inset: list[float], bounds_frame: list[float], frame: Optional[mpatches.FancyBboxPatch]) -> Incomplete: + ... + +def _has_finite_bbox(bbox: Incomplete) -> bool: + ... + +def _collect_inset_colorbar_bboxes(colorbar: Incomplete, *, labelloc_layout: str, loc: str, orientation: str, renderer: Incomplete) -> Incomplete: + ... + +def _inset_colorbar_frame_needs_reflow(colorbar: Incomplete, *, labelloc: str, renderer: Incomplete) -> bool: + ... + +def _reflow_inset_colorbar_frame(colorbar: Incomplete, *, labelloc: str, ticklen: float, renderer: Incomplete=None) -> Incomplete: + ... diff --git a/ultraplot/axes/cartesian.pyi b/ultraplot/axes/cartesian.pyi new file mode 100644 index 000000000..c32fb1c0e --- /dev/null +++ b/ultraplot/axes/cartesian.pyi @@ -0,0 +1,1041 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +The standard Cartesian axes used for most ultraplot figures. +""" +from _typeshed import Incomplete +import copy +import functools +import inspect +from dataclasses import dataclass, field +from typing import Any, Callable, Dict, Optional, Tuple, TypeVar, Union, cast +import matplotlib.axis as maxis +import matplotlib.dates as mdates +import matplotlib.ticker as mticker +import numpy as np +from packaging import version +from .. import constructor +from .. import scale as pscale +from .. import ticker as pticker +from ..config import rc +from ..internals import _not_none, _pop_params, _pop_rc, _version_mpl, docstring, ic, labels, warnings +from ..utils import units +from ._formatting import CARTESIAN_PARENT_FILTER_KEYS, axis_format_requires_layout, get_axis_style_fields, pop_axis_format_kwargs +from . import plot, shared +__all__ = ['CartesianAxes'] +_F = TypeVar('_F', bound=Callable[..., Any]) +DATE_CONVERTERS = (mdates.DateConverter,) +OPPOSITE_SIDE = {'left': 'right', 'right': 'left', 'bottom': 'top', 'top': 'bottom'} +_format_docstring = ... +_shared_x_keys = {'x': 'x', 'x1': 'bottom', 'x2': 'top', 'y': 'y', 'y1': 'left', 'y2': 'right'} +_shared_y_keys = {'x': 'y', 'x1': 'left', 'x2': 'right', 'y': 'x', 'y1': 'bottom', 'y2': 'top'} +_shared_docstring = ... +_alt_descrip = '\nAdd an axis locked to the same location with a\ndistinct {x} axis.\nThis is an alias and arguably more intuitive name for\n`~ultraplot.axes.CartesianAxes.twin{y}`, which generates\ntwo {x} axes with a shared ("twin") {y} axes.\n' +_alt_docstring = ... +_twin_descrip = '\nAdd an axis locked to the same location with a\ndistinct {x} axis.\nThis builds upon `matplotlib.axes.Axes.twin{y}`.\n' +_twin_docstring = ... +_dual_descrip = '\nAdd an axes locked to the same location whose {x} axis denotes\nequivalent coordinates in alternate units.\nThis is an alternative to `matplotlib.axes.Axes.secondary_{x}axis` with\nadditional convenience features.\n' +_dual_extra = '\nfuncscale : callable, 2-tuple of callables, or scale-spec\n The scale used to transform units from the parent axis to the secondary\n axis. This can be a `~ultraplot.scale.FuncScale` itself or a function,\n (function, function) tuple, or an axis scale specification interpreted\n by the `~ultraplot.constructor.Scale` constructor function, any of which\n will be used to build a `~ultraplot.scale.FuncScale` and applied\n to the dual axis (see `~ultraplot.scale.FuncScale` for details).\n' +_dual_docstring = ... + +@dataclass +class _AxisFormatConfig: + """A dataclass to hold formatting options for a single axis.""" + min_: Optional[float] = None + max_: Optional[float] = None + lim: Optional[Tuple[Optional[float], Optional[float]]] = None + reverse: Optional[bool] = None + margin: Optional[float] = None + bounds: Optional[Tuple[float, float]] = None + tickrange: Optional[Tuple[float, float]] = None + wraprange: Optional[Tuple[float, float]] = None + scale: Any = None + scale_kw: Dict[str, Any] = field(default_factory=dict) + spineloc: Any = None + tickloc: Any = None + ticklabelloc: Any = None + labelloc: Any = None + offsetloc: Any = None + grid: Optional[bool] = None + gridminor: Optional[bool] = None + gridcolor: Any = None + locator: Any = None + locator_kw: Dict[str, Any] = field(default_factory=dict) + minorlocator: Any = None + minorlocator_kw: Dict[str, Any] = field(default_factory=dict) + formatter: Any = None + formatter_kw: Dict[str, Any] = field(default_factory=dict) + label: Optional[str] = None + label_kw: Dict[str, Any] = field(default_factory=dict) + labelpad: Any = None + labelcolor: Any = None + labelsize: Any = None + labelweight: Optional[str] = None + color: Any = None + linewidth: Any = None + rotation: Optional[Union[float, str]] = None + tickminor: Optional[bool] = None + tickdir: Optional[str] = None + tickcolor: Any = None + ticklen: Any = None + ticklenratio: Optional[float] = None + tickwidth: Any = None + tickwidthratio: Optional[float] = None + ticklabeldir: Optional[str] = None + ticklabelpad: Any = None + ticklabelcolor: Any = None + ticklabelsize: Any = None + ticklabelweight: Optional[str] = None + +class CartesianAxes(shared._SharedAxes, plot.PlotAxes): + """ + Axes subclass for plotting in ordinary Cartesian coordinates. Adds the + `~CartesianAxes.format` method and overrides several existing methods. + + Important + --------- + This is the default axes subclass. It can be specified explicitly by passing + ``proj='cart'``, ``proj='cartesian'``, ``proj='rect'``, or ``proj='rectilinear'`` + to axes-creation commands like `~ultraplot.figure.Figure.add_axes`, + `~ultraplot.figure.Figure.add_subplot`, and `~ultraplot.figure.Figure.subplots`. + """ + _name = 'cartesian' + _name_aliases = ('cart', 'rect', 'rectilinar') + + def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: + """Parameters +---------- +*args + Passed to `matplotlib.axes.Axes`. +aspect : {'auto', 'equal'} or float, optional + The data aspect ratio. See :func:`~matplotlib.axes.Axes.set_aspect` + for details. +xlabel, ylabel : str, optional + The x and y axis labels. Applied with `~matplotlib.axes.Axes.set_xlabel` + and `~matplotlib.axes.Axes.set_ylabel`. +xlabel_kw, ylabel_kw : dict-like, optional + Additional axis label settings applied with `~matplotlib.axes.Axes.set_xlabel` + and `~matplotlib.axes.Axes.set_ylabel`. See also `labelpad`, `labelcolor`, + `labelsize`, and `labelweight` below. +xlim, ylim : 2-tuple of floats or None, optional + The x and y axis data limits. Applied with :func:`~matplotlib.axes.Axes.set_xlim` + and :func:`~matplotlib.axes.Axes.set_ylim`. +xmin, ymin : float, optional + The x and y minimum data limits. Useful if you do not want + to set the maximum limits. +xmax, ymax : float, optional + The x and y maximum data limits. Useful if you do not want + to set the minimum limits. +xreverse, yreverse : bool, optional + Whether to "reverse" the x and y axis direction. Makes the x and + y axes ascend left-to-right and top-to-bottom, respectively. +xscale, yscale : scale-spec, optional + The x and y axis scales. Passed to the `~ultraplot.scale.Scale` constructor. + For example, ``xscale='log'`` applies logarithmic scaling, and + ``xscale=('cutoff', 100, 2)`` applies a `~ultraplot.scale.CutoffScale`. +xscale_kw, yscale_kw : dict-like, optional + The x and y axis scale settings. Passed to `~ultraplot.scale.Scale`. +xmargin, ymargin, margin : float, default: :rc:`margin` + The default margin between plotted content and the x and y axis spines in + axes-relative coordinates. This is useful if you don't witch to explicitly set + axis limits. Use the keyword `margin` to set both at once. +xbounds, ybounds : 2-tuple of float, optional + The x and y axis data bounds within which to draw the spines. For example, + ``xlim=(0, 4)`` combined with ``xbounds=(2, 4)`` will prevent the spines + from meeting at the origin. This also applies ``xspineloc='bottom'`` and + ``yspineloc='left'`` by default if both spines are currently visible. +xtickrange, ytickrange : 2-tuple of float, optional + The x and y axis data ranges within which major tick marks are labelled. + For example, ``xlim=(-5, 5)`` combined with ``xtickrange=(-1, 1)`` and a + tick interval of 1 will only label the ticks marks at -1, 0, and 1. See + `~ultraplot.ticker.AutoFormatter` for details. +xwraprange, ywraprange : 2-tuple of float, optional + The x and y axis data ranges with which major tick mark values are wrapped. For + example, ``xwraprange=(0, 3)`` causes the values 0 through 9 to be formatted as + 0, 1, 2, 0, 1, 2, 0, 1, 2, 0. See `~ultraplot.ticker.AutoFormatter` for details. This + can be combined with `xtickrange` and `ytickrange` to make "stacked" line plots. +xloc, yloc : optional + Shorthands for `xspineloc`, `yspineloc`. +xspineloc, yspineloc : {'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right', 'both', 'neither', 'none', 'zero', 'center'} or 2-tuple, optional + The x and y spine locations. Applied with `~matplotlib.spines.Spine.set_position`. + Propagates to `tickloc` unless specified otherwise. +xtickloc, ytickloc : {'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right', 'both', 'neither', 'none'}, optional + Which x and y axis spines should have major and minor tick marks. Inherits from + `spineloc` by default and propagates to `ticklabelloc` unless specified otherwise. +xticklabelloc, yticklabelloc : {'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right', 'both', 'neither', 'none'}, optional + Which x and y axis spines should have major tick labels. Inherits from `tickloc` + by default and propagates to `labelloc` and `offsetloc` unless specified otherwise. +xlabelloc, ylabelloc : {'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right'}, optional + Which x and y axis spines should have axis labels. Inherits from + `ticklabelloc` by default (if `ticklabelloc` is a single side). +xoffsetloc, yoffsetloc : {'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right'}, optional + Which x and y axis spines should have the axis offset indicator. Inherits from + `ticklabelloc` by default (if `ticklabelloc` is a single side). +xtickdir, ytickdir, tickdir : {'out', 'in', 'inout'}, optional + Direction that major and minor tick marks point for the x and y axis. + Use the keyword `tickdir` to control both. +xticklabeldir, yticklabeldir : {'in', 'out'}, optional + Whether to place x and y axis tick label text inside or outside the axes. + Propagates to `xtickdir` and `ytickdir` unless specified otherwise. +xrotation, yrotation : float, default: 0 + The rotation for x and y axis tick labels. + for normal axes, :rc:`formatter.timerotation` for time x axes. +xgrid, ygrid, grid : bool, default: :rc:`grid` + Whether to draw major gridlines on the x and y axis. + Use the keyword `grid` to toggle both. +xgridminor, ygridminor, gridminor : bool, default: :rc:`gridminor` + Whether to draw minor gridlines for the x and y axis. + Use the keyword `gridminor` to toggle both. +xtickminor, ytickminor, tickminor : bool, default: :rc:`tick.minor` + Whether to draw minor ticks on the x and y axes. + Use the keyword `tickminor` to toggle both. +xticks, yticks : optional + Aliases for `xlocator`, `ylocator`. +xlocator, ylocator : locator-spec, optional + Used to determine the x and y axis tick mark positions. Passed + to the `~ultraplot.constructor.Locator` constructor. Can be float, + list of float, string, or `matplotlib.ticker.Locator` instance. + Use ``[]``, ``'null'``, or ``'none'`` for no ticks. +xlocator_kw, ylocator_kw : dict-like, optional + Keyword arguments passed to the `matplotlib.ticker.Locator` class. +xminorticks, yminorticks : optional + Aliases for `xminorlocator`, `yminorlocator`. +xminorlocator, yminorlocator : optional + As for `xlocator`, `ylocator`, but for the minor ticks. +xminorlocator_kw, yminorlocator_kw + As for `xlocator_kw`, `ylocator_kw`, but for the minor locator. +xticklabels, yticklabels : optional + Aliases for `xformatter`, `yformatter`. +xformatter, yformatter : formatter-spec, optional + Used to determine the x and y axis tick label string format. + Passed to the `~ultraplot.constructor.Formatter` constructor. + Can be string, list of strings, or `matplotlib.ticker.Formatter` instance. + Use ``[]``, ``'null'``, or ``'none'`` for no labels. +xformatter_kw, yformatter_kw : dict-like, optional + Keyword arguments passed to the `matplotlib.ticker.Formatter` class. +xcolor, ycolor, color : color-spec, default: :rc:`meta.color` + Color for the x and y axis spines, ticks, tick labels, and axis labels. + Use the keyword `color` to set both at once. +xgridcolor, ygridcolor, gridcolor : color-spec, default: :rc:`grid.color` + Color for the x and y axis major and minor gridlines. + Use the keyword `gridcolor` to set both at once. +xlinewidth, ylinewidth, linewidth : color-spec, default: :rc:`meta.width` + Line width for the x and y axis spines and major ticks. Propagates to `tickwidth` + unless specified otherwise. Use the keyword `linewidth` to set both at once. +xtickcolor, ytickcolor, tickcolor : color-spec, default: :rc:`tick.color` + Color for the x and y axis ticks. Defaults are `xcolor`, `ycolor`, and `color` + if they were passed. Use the keyword `tickcolor` to set both at once. +xticklen, yticklen, ticklen : unit-spec, default: :rc:`tick.len` + Major tick lengths for the x and y axis. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + Use the keyword `ticklen` to set both at once. +xticklenratio, yticklenratio, ticklenratio : float, default: :rc:`tick.lenratio` + Relative scaling of `xticklen` and `yticklen` used to determine minor + tick lengths. Use the keyword `ticklenratio` to set both at once. +xtickwidth, ytickwidth, tickwidth, : unit-spec, default: :rc:`tick.width` + Major tick widths for the x ans y axis. Default is `linewidth` if it was passed. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + Use the keyword `tickwidth` to set both at once. +xtickwidthratio, ytickwidthratio, tickwidthratio : float, default: :rc:`tick.widthratio` + Relative scaling of `xtickwidth` and `ytickwidth` used to determine + minor tick widths. Use the keyword `tickwidthratio` to set both at once. +xticklabelpad, yticklabelpad, ticklabelpad : unit-spec, default: :rc:`tick.labelpad` + The padding between the x and y axis ticks and tick labels. Use the + keyword `ticklabelpad` to set both at once. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +xticklabelcolor, yticklabelcolor, ticklabelcolor : color-spec, default: :rc:`tick.labelcolor` + Color for the x and y tick labels. Defaults are `xcolor`, `ycolor`, and `color` + if they were passed. Use the keyword `ticklabelcolor` to set both at once. +xticklabelsize, yticklabelsize, ticklabelsize : unit-spec or str, default: :rc:`tick.labelsize` + Font size for the x and y tick labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + Use the keyword `ticklabelsize` to set both at once. +xticklabelweight, yticklabelweight, ticklabelweight : str, default: :rc:`tick.labelweight` + Font weight for the x and y tick labels. + Use the keyword `ticklabelweight` to set both at once. +xlabelpad, ylabelpad : unit-spec, default: :rc:`label.pad` + The padding between the x and y axis bounding box and the x and y axis labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +xlabelcolor, ylabelcolor, labelcolor : color-spec, default: :rc:`label.color` + Color for the x and y axis labels. Defaults are `xcolor`, `ycolor`, and `color` + if they were passed. Use the keyword `labelcolor` to set both at once. +xlabelsize, ylabelsize, labelsize : unit-spec or str, default: :rc:`label.size` + Font size for the x and y axis labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + Use the keyword `labelsize` to set both at once. +xlabelweight, ylabelweight, labelweight : str, default: :rc:`label.weight` + Font weight for the x and y axis labels. + Use the keyword `labelweight` to set both at once. +fixticks : bool, default: False + Whether to transform the tick locators to a `~matplotlib.ticker.FixedLocator`. + If your axis ticks are doing weird things (for example, ticks are drawn + outside of the axis spine) you can try setting this to ``True``. + +Other parameters +---------------- +title : str or sequence, optional + The axes title. Can optionally be a sequence strings, in which case + the title will be selected from the sequence according to `~Axes.number`. +abc : bool or str or sequence, default: :rc:`abc` + The "a-b-c" subplot label style. Must contain the character `a` or `A`, + for example ``'a.'``, or ``'A'``. If ``True`` then the default style of + ``'a'`` is used. The `a` or ``A`` is replaced with the alphabetic character + matching the `~Axes.number`. If `~Axes.number` is greater than 26, the + characters loop around to a, ..., z, aa, ..., zz, aaa, ..., zzz, etc. + Can also be a sequence of strings, in which case the "a-b-c" label will be selected sequentially from the list. For example `axs.format(abc = ["X", "Y"])` for a two-panel figure, and `axes[3:5].format(abc = ["X", "Y"])` for a two-panel subset of a larger figure. +abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` + Strings indicating the location for the a-b-c label and main title. + The following locations are valid: + + .. _title_table: + + ======================== ============================ + Location Valid keys + ======================== ============================ + center above axes ``'center'``, ``'c'`` + left above axes ``'left'``, ``'l'`` + right above axes ``'right'``, ``'r'`` + lower center inside axes ``'lower center'``, ``'lc'`` + upper center inside axes ``'upper center'``, ``'uc'`` + upper right inside axes ``'upper right'``, ``'ur'`` + upper left inside axes ``'upper left'``, ``'ul'`` + lower left inside axes ``'lower left'``, ``'ll'`` + lower right inside axes ``'lower right'``, ``'lr'`` + left of y axis ``'outer left'``, ``'ol'`` + right of y axis ``'outer right'``, ``'or'`` + ======================== ============================ + +abcborder, titleborder : bool, default: :rc:`abc.border` and :rc:`title.border` + Whether to draw a white border around titles and a-b-c labels positioned + inside the axes. This can help them stand out on top of artists + plotted inside the axes. +abcbbox, titlebbox : bool, default: :rc:`abc.bbox` and :rc:`title.bbox` + Whether to draw a white bbox around titles and a-b-c labels positioned + inside the axes. This can help them stand out on top of artists plotted + inside the axes. +abcpad : float or unit-spec, default: :rc:`abc.pad` + Horizontal offset to shift the a-b-c label position. Positive values move + the label right, negative values move it left. This is separate from + `abctitlepad`, which controls spacing between abc and title when co-located. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +abc_kw, title_kw : dict-like, optional + Additional settings used to update the a-b-c label and title + with ``text.update()``. +titlepad : float, default: :rc:`title.pad` + The padding for the inner and outer titles and a-b-c labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +titleabove : bool, default: :rc:`title.above` + Whether to try to put outer titles and a-b-c labels above panels, + colorbars, or legends that are above the axes. +abctitlepad : float, default: :rc:`abc.titlepad` + The horizontal padding between a-b-c labels and titles in the same location. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle : str or sequence, optional + Shorthands for the below keywords. + lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle : str or sequence, optional +lowerlefttitle, lowercentertitle, lowerrighttitle : str or sequence, optional + Additional titles in specific positions (see `title` for details). This works as + an alternative to the ``ax.format(title='Title', titleloc=loc)`` workflow and + permits adding more than one title-like label for a single axes. +a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle : default: + :rc:`axes.alpha` (default: 1.0), :rc:`axes.facecolor` (default: white), :rc:`axes.edgecolor` (default: black), :rc:`axes.linewidth` (default: 0.6), - + Additional settings applied to the background patch, and their + shorthands. Their defaults values are the ``'axes'`` properties. +rc_mode : int, optional + The context mode passed to `~ultraplot.config.Configurator.context`. +rc_kw : dict-like, optional + An alternative to passing extra keyword arguments. See below. +**kwargs + Remaining keyword arguments are passed to `matplotlib.axes.Axes`.\\n Keyword arguments that match the name of an `~ultraplot.config.rc` setting are + passed to `ultraplot.config.Configurator.context` and used to update the axes. + If the setting name has "dots" you can simply omit the dots. For example, + ``abc='A.'`` modifies the :rcraw:`abc` setting, ``titleloc='left'`` modifies the + :rcraw:`title.loc` setting, ``gridminor=True`` modifies the :rcraw:`gridminor` + setting, and ``gridbelow=True`` modifies the :rcraw:`grid.below` setting. Many + of the keyword arguments documented above are internally applied by retrieving + settings passed to `~ultraplot.config.Configurator.context`. + +See also +-------- +CartesianAxes.format +ultraplot.axes.Axes +ultraplot.axes.PlotAxes +ultraplot.figure.Figure.subplot +ultraplot.figure.Figure.add_subplot""" + ... + + def _get_axis_style_state(self, axis: Incomplete) -> Incomplete: + """Return the cached explicit style overrides for this axis.""" + ... + + def _merge_axis_style_state(self, axis: Incomplete, params: Incomplete) -> Incomplete: + """Merge the current explicit style overrides with the cached overrides.""" + ... + + def _set_axis_style_state(self, axis: Incomplete, params: Incomplete) -> None: + """Cache the explicit style overrides for this axis.""" + ... + + def _apply_axis_sharing(self) -> None: + """Enforce the "shared" axis labels and axis tick labels. If this is not +called at drawtime, "shared" labels can be inadvertantly turned off.""" + ... + + def _apply_axis_sharing_for_axis(self, axis_name: str, border_axes: dict[str, plot.PlotAxes]) -> None: + """Apply axis sharing for a specific axis (x or y). + +Parameters +---------- +axis_name : str + Either 'x' or 'y' +border_axes : dict + Dictionary from _get_border_axes() containing border information""" + ... + + def _determine_tick_label_visibility(self, axis: maxis.Axis, shared_axis: maxis.Axis, axis_name: str, label_params: list[str], border_sides: list[str], border_axes: dict[str, list[plot.PlotAxes]]) -> dict[str, bool]: + """Determine which tick labels should be visible based on sharing rules and borders. + +Parameters +---------- +axis : matplotlib axis + The current axis object +shared_axis : Axes + The axes this one shares with +axis_name : str + Either 'x' or 'y' +label_params : list + List of label parameter names (e.g., ['labeltop', 'labelbottom']) +border_sides : list + List of border side names (e.g., ['top', 'bottom']) +border_axes : dict + Dictionary from _get_border_axes() + +Returns +------- +dict + Dictionary of label visibility parameters""" + ... + + def _add_alt(self, sx: Incomplete, **kwargs: Incomplete) -> CartesianAxes: + """Add an alternate axes.""" + ... + + def _dual_scale(self, s: Incomplete, funcscale: Incomplete=None) -> None: + """Lock the child "dual" axis limits to the parent.""" + ... + + def _fix_ticks(self, s: Incomplete, fixticks: Incomplete=False) -> None: + """Ensure there are no out-of-bounds ticks. Mostly a brute-force version of +`~matplotlib.axis.Axis.set_smart_bounds` (which I couldn't get to work).""" + ... + + def _get_spine_side(self, s: Incomplete, loc: Incomplete) -> Incomplete: + """Get the spine side implied by the input location or position. This +propagates to tick mark, tick label, and axis label positions.""" + ... + + def _sharex_limits(self, sharex: Incomplete) -> None: + """Safely share limits and tickers without resetting things.""" + ... + + def _sharey_limits(self, sharey: Incomplete) -> None: + """Safely share limits and tickers without resetting things.""" + ... + + def _sharex_setup(self, sharex: Incomplete, *, labels: Incomplete=True, limits: Incomplete=True) -> None: + """Configure shared axes accounting. Input is the 'parent' axes from which this +one will draw its properties. Use keyword args to override settings.""" + ... + + def _sharey_setup(self, sharey: Incomplete, *, labels: Incomplete=True, limits: Incomplete=True) -> None: + """Configure shared axes accounting for panels. The input is the +'parent' axes, from which this one will draw its properties.""" + ... + + def _apply_log_formatter_on_scale(self, s: Incomplete) -> None: + """Enforce log formatter when log scale is set and rc is enabled.""" + ... + + def set_xscale(self, value: Incomplete, **kwargs: Incomplete) -> None: + ... + + def set_yscale(self, value: Incomplete, **kwargs: Incomplete) -> None: + ... + + def _update_formatter(self, s: Incomplete, formatter: Incomplete=None, *, formatter_kw: Incomplete=None, tickrange: Incomplete=None, wraprange: Incomplete=None) -> None: + """Update the axis formatter. Passes `formatter` through `Formatter` with kwargs.""" + ... + + def _update_labels(self, s: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> None: + """Apply axis labels to the relevant shared axis. If spanning labels are toggled +this keeps the labels synced for all subplots in the same row or column. Label +positions will be adjusted at draw-time with figure._align_axislabels.""" + ... + + def _update_locators(self, s: Incomplete, locator: Incomplete=None, minorlocator: Incomplete=None, *, tickminor: Incomplete=None, locator_kw: Incomplete=None, minorlocator_kw: Incomplete=None) -> None: + """Update the locators. Requires `Locator` instances.""" + ... + + def _update_limits(self, s: Incomplete, *, min_: Incomplete=None, max_: Incomplete=None, lim: Incomplete=None, reverse: Incomplete=None) -> None: + """Update the axis limits.""" + ... + + def _update_rotation(self, s: Incomplete, *, rotation: Incomplete=None) -> None: + """Rotate the tick labels. Rotate 90 degrees by default for datetime *x* axes.""" + ... + + def _update_spines(self, s: Incomplete, *, loc: Incomplete=None, bounds: Incomplete=None) -> None: + """Update the spine settings.""" + ... + + def _update_locs(self, s: Incomplete, *, tickloc: Incomplete=None, ticklabelloc: Incomplete=None, labelloc: Incomplete=None, offsetloc: Incomplete=None) -> None: + """Update the tick, tick label, and axis label locations.""" + ... + + def _format_axis(self, s: str, config: _AxisFormatConfig, fixticks: bool) -> None: + """Helper for `format` that applies settings to a single axis.""" + ... + + def _resolve_axis_format(self, axis: Incomplete, params: Incomplete, rc_kw: Incomplete) -> _AxisFormatConfig: + """Resolve formatting parameters for a single axis (x or y).""" + ... + + def format(self, *, aspect: Incomplete=None, xloc: Incomplete=None, yloc: Incomplete=None, xspineloc: Incomplete=None, yspineloc: Incomplete=None, xoffsetloc: Incomplete=None, yoffsetloc: Incomplete=None, xwraprange: Incomplete=None, ywraprange: Incomplete=None, xreverse: Incomplete=None, yreverse: Incomplete=None, xlim: Incomplete=None, ylim: Incomplete=None, xmin: Incomplete=None, ymin: Incomplete=None, xmax: Incomplete=None, ymax: Incomplete=None, xscale: Incomplete=None, yscale: Incomplete=None, xbounds: Incomplete=None, ybounds: Incomplete=None, xmargin: Incomplete=None, ymargin: Incomplete=None, xrotation: Incomplete=None, yrotation: Incomplete=None, xformatter: Incomplete=None, yformatter: Incomplete=None, xticklabels: Incomplete=None, yticklabels: Incomplete=None, xticks: Incomplete=None, yticks: Incomplete=None, xlocator: Incomplete=None, ylocator: Incomplete=None, xminorticks: Incomplete=None, yminorticks: Incomplete=None, xminorlocator: Incomplete=None, yminorlocator: Incomplete=None, xcolor: Incomplete=None, ycolor: Incomplete=None, xlinewidth: Incomplete=None, ylinewidth: Incomplete=None, xtickloc: Incomplete=None, ytickloc: Incomplete=None, fixticks: Incomplete=False, xtickdir: Incomplete=None, ytickdir: Incomplete=None, xtickminor: Incomplete=None, ytickminor: Incomplete=None, xtickrange: Incomplete=None, ytickrange: Incomplete=None, xtickcolor: Incomplete=None, ytickcolor: Incomplete=None, xticklen: Incomplete=None, yticklen: Incomplete=None, xticklenratio: Incomplete=None, yticklenratio: Incomplete=None, xtickwidth: Incomplete=None, ytickwidth: Incomplete=None, xtickwidthratio: Incomplete=None, ytickwidthratio: Incomplete=None, xticklabelloc: Incomplete=None, yticklabelloc: Incomplete=None, xticklabeldir: Incomplete=None, yticklabeldir: Incomplete=None, xticklabelpad: Incomplete=None, yticklabelpad: Incomplete=None, xticklabelcolor: Incomplete=None, yticklabelcolor: Incomplete=None, xticklabelsize: Incomplete=None, yticklabelsize: Incomplete=None, xticklabelweight: Incomplete=None, yticklabelweight: Incomplete=None, xlabel: Incomplete=None, ylabel: Incomplete=None, xlabelloc: Incomplete=None, ylabelloc: Incomplete=None, xlabelpad: Incomplete=None, ylabelpad: Incomplete=None, xlabelcolor: Incomplete=None, ylabelcolor: Incomplete=None, xlabelsize: Incomplete=None, ylabelsize: Incomplete=None, xlabelweight: Incomplete=None, ylabelweight: Incomplete=None, xgrid: Incomplete=None, ygrid: Incomplete=None, xgridminor: Incomplete=None, ygridminor: Incomplete=None, xgridcolor: Incomplete=None, ygridcolor: Incomplete=None, xlabel_kw: Incomplete=None, ylabel_kw: Incomplete=None, xscale_kw: Incomplete=None, yscale_kw: Incomplete=None, xlocator_kw: Incomplete=None, ylocator_kw: Incomplete=None, xformatter_kw: Incomplete=None, yformatter_kw: Incomplete=None, xminorlocator_kw: Incomplete=None, yminorlocator_kw: Incomplete=None, **kwargs: Incomplete) -> None: + """Modify axes limits, axis scales, axis labels, spine locations, +tick locations, tick labels, and more. + +Parameters +---------- +aspect : {'auto', 'equal'} or float, optional + The data aspect ratio. See :func:`~matplotlib.axes.Axes.set_aspect` + for details. +xlabel, ylabel : str, optional + The x and y axis labels. Applied with `~matplotlib.axes.Axes.set_xlabel` + and `~matplotlib.axes.Axes.set_ylabel`. +xlabel_kw, ylabel_kw : dict-like, optional + Additional axis label settings applied with `~matplotlib.axes.Axes.set_xlabel` + and `~matplotlib.axes.Axes.set_ylabel`. See also `labelpad`, `labelcolor`, + `labelsize`, and `labelweight` below. +xlim, ylim : 2-tuple of floats or None, optional + The x and y axis data limits. Applied with :func:`~matplotlib.axes.Axes.set_xlim` + and :func:`~matplotlib.axes.Axes.set_ylim`. +xmin, ymin : float, optional + The x and y minimum data limits. Useful if you do not want + to set the maximum limits. +xmax, ymax : float, optional + The x and y maximum data limits. Useful if you do not want + to set the minimum limits. +xreverse, yreverse : bool, optional + Whether to "reverse" the x and y axis direction. Makes the x and + y axes ascend left-to-right and top-to-bottom, respectively. +xscale, yscale : scale-spec, optional + The x and y axis scales. Passed to the `~ultraplot.scale.Scale` constructor. + For example, ``xscale='log'`` applies logarithmic scaling, and + ``xscale=('cutoff', 100, 2)`` applies a `~ultraplot.scale.CutoffScale`. +xscale_kw, yscale_kw : dict-like, optional + The x and y axis scale settings. Passed to `~ultraplot.scale.Scale`. +xmargin, ymargin, margin : float, default: :rc:`margin` + The default margin between plotted content and the x and y axis spines in + axes-relative coordinates. This is useful if you don't witch to explicitly set + axis limits. Use the keyword `margin` to set both at once. +xbounds, ybounds : 2-tuple of float, optional + The x and y axis data bounds within which to draw the spines. For example, + ``xlim=(0, 4)`` combined with ``xbounds=(2, 4)`` will prevent the spines + from meeting at the origin. This also applies ``xspineloc='bottom'`` and + ``yspineloc='left'`` by default if both spines are currently visible. +xtickrange, ytickrange : 2-tuple of float, optional + The x and y axis data ranges within which major tick marks are labelled. + For example, ``xlim=(-5, 5)`` combined with ``xtickrange=(-1, 1)`` and a + tick interval of 1 will only label the ticks marks at -1, 0, and 1. See + `~ultraplot.ticker.AutoFormatter` for details. +xwraprange, ywraprange : 2-tuple of float, optional + The x and y axis data ranges with which major tick mark values are wrapped. For + example, ``xwraprange=(0, 3)`` causes the values 0 through 9 to be formatted as + 0, 1, 2, 0, 1, 2, 0, 1, 2, 0. See `~ultraplot.ticker.AutoFormatter` for details. This + can be combined with `xtickrange` and `ytickrange` to make "stacked" line plots. +xloc, yloc : optional + Shorthands for `xspineloc`, `yspineloc`. +xspineloc, yspineloc : {'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right', 'both', 'neither', 'none', 'zero', 'center'} or 2-tuple, optional + The x and y spine locations. Applied with `~matplotlib.spines.Spine.set_position`. + Propagates to `tickloc` unless specified otherwise. +xtickloc, ytickloc : {'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right', 'both', 'neither', 'none'}, optional + Which x and y axis spines should have major and minor tick marks. Inherits from + `spineloc` by default and propagates to `ticklabelloc` unless specified otherwise. +xticklabelloc, yticklabelloc : {'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right', 'both', 'neither', 'none'}, optional + Which x and y axis spines should have major tick labels. Inherits from `tickloc` + by default and propagates to `labelloc` and `offsetloc` unless specified otherwise. +xlabelloc, ylabelloc : {'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right'}, optional + Which x and y axis spines should have axis labels. Inherits from + `ticklabelloc` by default (if `ticklabelloc` is a single side). +xoffsetloc, yoffsetloc : {'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right'}, optional + Which x and y axis spines should have the axis offset indicator. Inherits from + `ticklabelloc` by default (if `ticklabelloc` is a single side). +xtickdir, ytickdir, tickdir : {'out', 'in', 'inout'}, optional + Direction that major and minor tick marks point for the x and y axis. + Use the keyword `tickdir` to control both. +xticklabeldir, yticklabeldir : {'in', 'out'}, optional + Whether to place x and y axis tick label text inside or outside the axes. + Propagates to `xtickdir` and `ytickdir` unless specified otherwise. +xrotation, yrotation : float, default: 0 + The rotation for x and y axis tick labels. + for normal axes, :rc:`formatter.timerotation` for time x axes. +xgrid, ygrid, grid : bool, default: :rc:`grid` + Whether to draw major gridlines on the x and y axis. + Use the keyword `grid` to toggle both. +xgridminor, ygridminor, gridminor : bool, default: :rc:`gridminor` + Whether to draw minor gridlines for the x and y axis. + Use the keyword `gridminor` to toggle both. +xtickminor, ytickminor, tickminor : bool, default: :rc:`tick.minor` + Whether to draw minor ticks on the x and y axes. + Use the keyword `tickminor` to toggle both. +xticks, yticks : optional + Aliases for `xlocator`, `ylocator`. +xlocator, ylocator : locator-spec, optional + Used to determine the x and y axis tick mark positions. Passed + to the `~ultraplot.constructor.Locator` constructor. Can be float, + list of float, string, or `matplotlib.ticker.Locator` instance. + Use ``[]``, ``'null'``, or ``'none'`` for no ticks. +xlocator_kw, ylocator_kw : dict-like, optional + Keyword arguments passed to the `matplotlib.ticker.Locator` class. +xminorticks, yminorticks : optional + Aliases for `xminorlocator`, `yminorlocator`. +xminorlocator, yminorlocator : optional + As for `xlocator`, `ylocator`, but for the minor ticks. +xminorlocator_kw, yminorlocator_kw + As for `xlocator_kw`, `ylocator_kw`, but for the minor locator. +xticklabels, yticklabels : optional + Aliases for `xformatter`, `yformatter`. +xformatter, yformatter : formatter-spec, optional + Used to determine the x and y axis tick label string format. + Passed to the `~ultraplot.constructor.Formatter` constructor. + Can be string, list of strings, or `matplotlib.ticker.Formatter` instance. + Use ``[]``, ``'null'``, or ``'none'`` for no labels. +xformatter_kw, yformatter_kw : dict-like, optional + Keyword arguments passed to the `matplotlib.ticker.Formatter` class. +xcolor, ycolor, color : color-spec, default: :rc:`meta.color` + Color for the x and y axis spines, ticks, tick labels, and axis labels. + Use the keyword `color` to set both at once. +xgridcolor, ygridcolor, gridcolor : color-spec, default: :rc:`grid.color` + Color for the x and y axis major and minor gridlines. + Use the keyword `gridcolor` to set both at once. +xlinewidth, ylinewidth, linewidth : color-spec, default: :rc:`meta.width` + Line width for the x and y axis spines and major ticks. Propagates to `tickwidth` + unless specified otherwise. Use the keyword `linewidth` to set both at once. +xtickcolor, ytickcolor, tickcolor : color-spec, default: :rc:`tick.color` + Color for the x and y axis ticks. Defaults are `xcolor`, `ycolor`, and `color` + if they were passed. Use the keyword `tickcolor` to set both at once. +xticklen, yticklen, ticklen : unit-spec, default: :rc:`tick.len` + Major tick lengths for the x and y axis. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + Use the keyword `ticklen` to set both at once. +xticklenratio, yticklenratio, ticklenratio : float, default: :rc:`tick.lenratio` + Relative scaling of `xticklen` and `yticklen` used to determine minor + tick lengths. Use the keyword `ticklenratio` to set both at once. +xtickwidth, ytickwidth, tickwidth, : unit-spec, default: :rc:`tick.width` + Major tick widths for the x ans y axis. Default is `linewidth` if it was passed. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + Use the keyword `tickwidth` to set both at once. +xtickwidthratio, ytickwidthratio, tickwidthratio : float, default: :rc:`tick.widthratio` + Relative scaling of `xtickwidth` and `ytickwidth` used to determine + minor tick widths. Use the keyword `tickwidthratio` to set both at once. +xticklabelpad, yticklabelpad, ticklabelpad : unit-spec, default: :rc:`tick.labelpad` + The padding between the x and y axis ticks and tick labels. Use the + keyword `ticklabelpad` to set both at once. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +xticklabelcolor, yticklabelcolor, ticklabelcolor : color-spec, default: :rc:`tick.labelcolor` + Color for the x and y tick labels. Defaults are `xcolor`, `ycolor`, and `color` + if they were passed. Use the keyword `ticklabelcolor` to set both at once. +xticklabelsize, yticklabelsize, ticklabelsize : unit-spec or str, default: :rc:`tick.labelsize` + Font size for the x and y tick labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + Use the keyword `ticklabelsize` to set both at once. +xticklabelweight, yticklabelweight, ticklabelweight : str, default: :rc:`tick.labelweight` + Font weight for the x and y tick labels. + Use the keyword `ticklabelweight` to set both at once. +xlabelpad, ylabelpad : unit-spec, default: :rc:`label.pad` + The padding between the x and y axis bounding box and the x and y axis labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +xlabelcolor, ylabelcolor, labelcolor : color-spec, default: :rc:`label.color` + Color for the x and y axis labels. Defaults are `xcolor`, `ycolor`, and `color` + if they were passed. Use the keyword `labelcolor` to set both at once. +xlabelsize, ylabelsize, labelsize : unit-spec or str, default: :rc:`label.size` + Font size for the x and y axis labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + Use the keyword `labelsize` to set both at once. +xlabelweight, ylabelweight, labelweight : str, default: :rc:`label.weight` + Font weight for the x and y axis labels. + Use the keyword `labelweight` to set both at once. +fixticks : bool, default: False + Whether to transform the tick locators to a `~matplotlib.ticker.FixedLocator`. + If your axis ticks are doing weird things (for example, ticks are drawn + outside of the axis spine) you can try setting this to ``True``. + +Other parameters +---------------- +title : str or sequence, optional + The axes title. Can optionally be a sequence strings, in which case + the title will be selected from the sequence according to `~Axes.number`. +abc : bool or str or sequence, default: :rc:`abc` + The "a-b-c" subplot label style. Must contain the character `a` or `A`, + for example ``'a.'``, or ``'A'``. If ``True`` then the default style of + ``'a'`` is used. The `a` or ``A`` is replaced with the alphabetic character + matching the `~Axes.number`. If `~Axes.number` is greater than 26, the + characters loop around to a, ..., z, aa, ..., zz, aaa, ..., zzz, etc. + Can also be a sequence of strings, in which case the "a-b-c" label will be selected sequentially from the list. For example `axs.format(abc = ["X", "Y"])` for a two-panel figure, and `axes[3:5].format(abc = ["X", "Y"])` for a two-panel subset of a larger figure. +abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` + Strings indicating the location for the a-b-c label and main title. + The following locations are valid: + + .. _title_table: + + ======================== ============================ + Location Valid keys + ======================== ============================ + center above axes ``'center'``, ``'c'`` + left above axes ``'left'``, ``'l'`` + right above axes ``'right'``, ``'r'`` + lower center inside axes ``'lower center'``, ``'lc'`` + upper center inside axes ``'upper center'``, ``'uc'`` + upper right inside axes ``'upper right'``, ``'ur'`` + upper left inside axes ``'upper left'``, ``'ul'`` + lower left inside axes ``'lower left'``, ``'ll'`` + lower right inside axes ``'lower right'``, ``'lr'`` + left of y axis ``'outer left'``, ``'ol'`` + right of y axis ``'outer right'``, ``'or'`` + ======================== ============================ + +abcborder, titleborder : bool, default: :rc:`abc.border` and :rc:`title.border` + Whether to draw a white border around titles and a-b-c labels positioned + inside the axes. This can help them stand out on top of artists + plotted inside the axes. +abcbbox, titlebbox : bool, default: :rc:`abc.bbox` and :rc:`title.bbox` + Whether to draw a white bbox around titles and a-b-c labels positioned + inside the axes. This can help them stand out on top of artists plotted + inside the axes. +abcpad : float or unit-spec, default: :rc:`abc.pad` + Horizontal offset to shift the a-b-c label position. Positive values move + the label right, negative values move it left. This is separate from + `abctitlepad`, which controls spacing between abc and title when co-located. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +abc_kw, title_kw : dict-like, optional + Additional settings used to update the a-b-c label and title + with ``text.update()``. +titlepad : float, default: :rc:`title.pad` + The padding for the inner and outer titles and a-b-c labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +titleabove : bool, default: :rc:`title.above` + Whether to try to put outer titles and a-b-c labels above panels, + colorbars, or legends that are above the axes. +abctitlepad : float, default: :rc:`abc.titlepad` + The horizontal padding between a-b-c labels and titles in the same location. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle : str or sequence, optional + Shorthands for the below keywords. + lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle : str or sequence, optional +lowerlefttitle, lowercentertitle, lowerrighttitle : str or sequence, optional + Additional titles in specific positions (see `title` for details). This works as + an alternative to the ``ax.format(title='Title', titleloc=loc)`` workflow and + permits adding more than one title-like label for a single axes. +a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle : default: + :rc:`axes.alpha` (default: 1.0), :rc:`axes.facecolor` (default: white), :rc:`axes.edgecolor` (default: black), :rc:`axes.linewidth` (default: 0.6), - + Additional settings applied to the background patch, and their + shorthands. Their defaults values are the ``'axes'`` properties. +rowlabels, collabels, llabels, tlabels, rlabels, blabels + Aliases for `leftlabels` and `toplabels`, and for `leftlabels`, + `toplabels`, `rightlabels`, and `bottomlabels`, respectively. +leftlabels, toplabels, rightlabels, bottomlabels : sequence of str, optional + Labels for the subplots lying along the left, top, right, and + bottom edges of the figure. The length of each list must match + the number of subplots along the corresponding edge. +leftlabelpad, toplabelpad, rightlabelpad, bottomlabelpad : float or unit-spec, default +: :rc:`leftlabel.pad`, :rc:`toplabel.pad`, :rc:`rightlabel.pad`, :rc:`bottomlabel.pad` + The padding between the labels and the axes content. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +leftlabelsharedpad, toplabelsharedpad, rightlabelsharedpad, bottomlabelsharedpad : float or unit-spec, default +: :rc:`leftlabel.sharedpad`, :rc:`toplabel.sharedpad`, :rc:`rightlabel.sharedpad`, :rc:`bottomlabel.sharedpad` + The padding between side labels and a shared spanning axis label on the + same side. The spanning label is placed outside the side labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +leftlabels_kw, toplabels_kw, rightlabels_kw, bottomlabels_kw : dict-like, optional + Additional settings used to update the labels with ``text.update()``. +figtitle + Alias for `suptitle`. +suptitle : str, optional + The figure "super" title, centered between the left edge of the leftmost + subplot and the right edge of the rightmost subplot. +suptitlepad : float, default: :rc:`suptitle.pad` + The padding between the super title and the axes content. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +suptitle_kw : optional + Additional settings used to update the super title with ``text.update()``. +includepanels : bool, default: False + Whether to include panels when aligning figure "super titles" along the top + of the subplot grid and when aligning the `spanx` *x* axis labels and + `spany` *y* axis labels along the sides of the subplot grid. +rc_mode : int, optional + The context mode passed to `~ultraplot.config.Configurator.context`. +rc_kw : dict-like, optional + An alternative to passing extra keyword arguments. See below. +**kwargs + Keyword arguments that match the name of an `~ultraplot.config.rc` setting are + passed to `ultraplot.config.Configurator.context` and used to update the axes. + If the setting name has "dots" you can simply omit the dots. For example, + ``abc='A.'`` modifies the :rcraw:`abc` setting, ``titleloc='left'`` modifies the + :rcraw:`title.loc` setting, ``gridminor=True`` modifies the :rcraw:`gridminor` + setting, and ``gridbelow=True`` modifies the :rcraw:`grid.below` setting. Many + of the keyword arguments documented above are internally applied by retrieving + settings passed to `~ultraplot.config.Configurator.context`. + +See also +-------- +ultraplot.axes.Axes.format +ultraplot.figure.Figure.format +ultraplot.config.Configurator.context + +Note +---- +If you plot something with a `datetime64 `__, +`pandas.Timestamp`, `pandas.DatetimeIndex`, `datetime.date`, `datetime.time`, +or `datetime.datetime` array as the x or y axis coordinate, the axis ticks +and tick labels will be automatically formatted as dates.""" + ... + + def altx(self, **kwargs: Incomplete) -> CartesianAxes: + """Add an axis locked to the same location with a +distinct x axis. +This is an alias and arguably more intuitive name for +`~ultraplot.axes.CartesianAxes.twiny`, which generates +two x axes with a shared ("twin") y axes. + +Parameters +---------- +**kwargs + Passed to `~ultraplot.axes.CartesianAxes`. Supports all valid + `~ultraplot.axes.CartesianAxes.format` keywords. You can optionally + omit the x from keywords beginning with ``x`` -- for example + ``ax.altx(lim=(0, 10))`` is equivalent to ``ax.altx(xlim=(0, 10))``. + You can also change the default side for the axis spine, axis tick marks, + axis tick labels, and/or axis labels by passing ``loc`` keywords. For example, + ``ax.altx(loc='bottom')`` changes the default side from top to bottom. + +Returns +------- +ultraplot.axes.CartesianAxes + The resulting axes. + +Note +---- +This enforces the following default settings: + +* Places the old x axis on the bottom and the new x + axis on the top. +* Makes the old top spine invisible and the new bottom, left, + and right spines invisible. +* Adjusts the x axis tick, tick label, and axis label positions + according to the visible spine positions. +* Syncs the old and new y axis limits and scales, and makes the + new y axis labels invisible.""" + ... + + def alty(self, **kwargs: Incomplete) -> CartesianAxes: + """Add an axis locked to the same location with a +distinct y axis. +This is an alias and arguably more intuitive name for +`~ultraplot.axes.CartesianAxes.twinx`, which generates +two y axes with a shared ("twin") x axes. + +Parameters +---------- +**kwargs + Passed to `~ultraplot.axes.CartesianAxes`. Supports all valid + `~ultraplot.axes.CartesianAxes.format` keywords. You can optionally + omit the y from keywords beginning with ``y`` -- for example + ``ax.alty(lim=(0, 10))`` is equivalent to ``ax.alty(ylim=(0, 10))``. + You can also change the default side for the axis spine, axis tick marks, + axis tick labels, and/or axis labels by passing ``loc`` keywords. For example, + ``ax.alty(loc='left')`` changes the default side from right to left. + +Returns +------- +ultraplot.axes.CartesianAxes + The resulting axes. + +Note +---- +This enforces the following default settings: + +* Places the old y axis on the left and the new y + axis on the right. +* Makes the old right spine invisible and the new left, bottom, + and top spines invisible. +* Adjusts the y axis tick, tick label, and axis label positions + according to the visible spine positions. +* Syncs the old and new x axis limits and scales, and makes the + new x axis labels invisible.""" + ... + + def dualx(self, funcscale: Incomplete, **kwargs: Incomplete) -> CartesianAxes: + """Add an axes locked to the same location whose x axis denotes +equivalent coordinates in alternate units. +This is an alternative to `matplotlib.axes.Axes.secondary_xaxis` with +additional convenience features. + +Parameters +---------- +funcscale : callable, 2-tuple of callables, or scale-spec + The scale used to transform units from the parent axis to the secondary + axis. This can be a `~ultraplot.scale.FuncScale` itself or a function, + (function, function) tuple, or an axis scale specification interpreted + by the `~ultraplot.constructor.Scale` constructor function, any of which + will be used to build a `~ultraplot.scale.FuncScale` and applied + to the dual axis (see `~ultraplot.scale.FuncScale` for details). +**kwargs + Passed to `~ultraplot.axes.CartesianAxes`. Supports all valid + `~ultraplot.axes.CartesianAxes.format` keywords. You can optionally + omit the x from keywords beginning with ``x`` -- for example + ``ax.altx(lim=(0, 10))`` is equivalent to ``ax.altx(xlim=(0, 10))``. + You can also change the default side for the axis spine, axis tick marks, + axis tick labels, and/or axis labels by passing ``loc`` keywords. For example, + ``ax.altx(loc='bottom')`` changes the default side from top to bottom. + +Returns +------- +ultraplot.axes.CartesianAxes + The resulting axes. + +Note +---- +This enforces the following default settings: + +* Places the old x axis on the bottom and the new x + axis on the top. +* Makes the old top spine invisible and the new bottom, left, + and right spines invisible. +* Adjusts the x axis tick, tick label, and axis label positions + according to the visible spine positions. +* Syncs the old and new y axis limits and scales, and makes the + new y axis labels invisible.""" + ... + + def dualy(self, funcscale: Incomplete, **kwargs: Incomplete) -> CartesianAxes: + """Add an axes locked to the same location whose y axis denotes +equivalent coordinates in alternate units. +This is an alternative to `matplotlib.axes.Axes.secondary_yaxis` with +additional convenience features. + +Parameters +---------- +funcscale : callable, 2-tuple of callables, or scale-spec + The scale used to transform units from the parent axis to the secondary + axis. This can be a `~ultraplot.scale.FuncScale` itself or a function, + (function, function) tuple, or an axis scale specification interpreted + by the `~ultraplot.constructor.Scale` constructor function, any of which + will be used to build a `~ultraplot.scale.FuncScale` and applied + to the dual axis (see `~ultraplot.scale.FuncScale` for details). +**kwargs + Passed to `~ultraplot.axes.CartesianAxes`. Supports all valid + `~ultraplot.axes.CartesianAxes.format` keywords. You can optionally + omit the y from keywords beginning with ``y`` -- for example + ``ax.alty(lim=(0, 10))`` is equivalent to ``ax.alty(ylim=(0, 10))``. + You can also change the default side for the axis spine, axis tick marks, + axis tick labels, and/or axis labels by passing ``loc`` keywords. For example, + ``ax.alty(loc='left')`` changes the default side from right to left. + +Returns +------- +ultraplot.axes.CartesianAxes + The resulting axes. + +Note +---- +This enforces the following default settings: + +* Places the old y axis on the left and the new y + axis on the right. +* Makes the old right spine invisible and the new left, bottom, + and top spines invisible. +* Adjusts the y axis tick, tick label, and axis label positions + according to the visible spine positions. +* Syncs the old and new x axis limits and scales, and makes the + new x axis labels invisible.""" + ... + + def twinx(self, **kwargs: Incomplete) -> CartesianAxes: + """Add an axis locked to the same location with a +distinct y axis. +This builds upon `matplotlib.axes.Axes.twinx`. + +Parameters +---------- +**kwargs + Passed to `~ultraplot.axes.CartesianAxes`. Supports all valid + `~ultraplot.axes.CartesianAxes.format` keywords. You can optionally + omit the y from keywords beginning with ``y`` -- for example + ``ax.alty(lim=(0, 10))`` is equivalent to ``ax.alty(ylim=(0, 10))``. + You can also change the default side for the axis spine, axis tick marks, + axis tick labels, and/or axis labels by passing ``loc`` keywords. For example, + ``ax.alty(loc='left')`` changes the default side from right to left. + +Returns +------- +ultraplot.axes.CartesianAxes + The resulting axes. + +Note +---- +This enforces the following default settings: + +* Places the old y axis on the left and the new y + axis on the right. +* Makes the old right spine invisible and the new left, bottom, + and top spines invisible. +* Adjusts the y axis tick, tick label, and axis label positions + according to the visible spine positions. +* Syncs the old and new x axis limits and scales, and makes the + new x axis labels invisible.""" + ... + + def twiny(self, **kwargs: Incomplete) -> CartesianAxes: + """Add an axis locked to the same location with a +distinct x axis. +This builds upon `matplotlib.axes.Axes.twiny`. + +Parameters +---------- +**kwargs + Passed to `~ultraplot.axes.CartesianAxes`. Supports all valid + `~ultraplot.axes.CartesianAxes.format` keywords. You can optionally + omit the x from keywords beginning with ``x`` -- for example + ``ax.altx(lim=(0, 10))`` is equivalent to ``ax.altx(xlim=(0, 10))``. + You can also change the default side for the axis spine, axis tick marks, + axis tick labels, and/or axis labels by passing ``loc`` keywords. For example, + ``ax.altx(loc='bottom')`` changes the default side from top to bottom. + +Returns +------- +ultraplot.axes.CartesianAxes + The resulting axes. + +Note +---- +This enforces the following default settings: + +* Places the old x axis on the bottom and the new x + axis on the top. +* Makes the old top spine invisible and the new bottom, left, + and right spines invisible. +* Adjusts the x axis tick, tick label, and axis label positions + according to the visible spine positions. +* Syncs the old and new y axis limits and scales, and makes the + new y axis labels invisible.""" + ... + + def draw(self, renderer: Incomplete=None, *args: Incomplete, **kwargs: Incomplete) -> None: + ... + + def get_tightbbox(self, renderer: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + ... + +def _capture_explicit_format_keys(func: _F) -> _F: + """Preserve raw keyword names before Python binds them to the format signature.""" + ... diff --git a/ultraplot/axes/container.pyi b/ultraplot/axes/container.pyi new file mode 100644 index 000000000..660917c8b --- /dev/null +++ b/ultraplot/axes/container.pyi @@ -0,0 +1,243 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Container class for external axes (e.g., mpltern, cartopy custom axes). + +This module provides the ExternalAxesContainer class which acts as a wrapper +around external axes classes, allowing them to be used within ultraplot's +figure system while maintaining their native functionality. +""" +from _typeshed import Incomplete +import matplotlib.axes as maxes +import matplotlib.transforms as mtransforms +from matplotlib import cbook, container +from ..config import rc +from ..internals import _pop_rc, warnings +from .cartesian import CartesianAxes +__all__ = ['ExternalAxesContainer'] +_ABOVE_AXES_TITLE_LOCS = {'left', 'center', 'right'} + +class ExternalAxesContainer(CartesianAxes): + """ + Container axes that wraps an external axes instance. + + This class inherits from ultraplot's CartesianAxes and creates/manages an external + axes as a child. It provides ultraplot's interface while delegating + drawing and interaction to the wrapped external axes. + + Parameters + ---------- + *args + Positional arguments passed to Axes.__init__ + external_axes_class : type + The external axes class to instantiate (e.g., mpltern.TernaryAxes) + external_axes_kwargs : dict, optional + Keyword arguments to pass to the external axes constructor + external_shrink_factor : float, optional, default: :rc:`external.shrink` + The factor by which to shrink the external axes within the container + to leave room for labels. For ternary plots, labels extend significantly + beyond the plot area, so a value of 0.90 (10% padding) helps prevent + overlap with adjacent subplots while keeping the axes large. + external_padding : float, optional, default: 5.0 + Padding in points to add around the external axes tight bbox. This creates + space between the external axes and adjacent subplots, preventing overlap + with tick labels or other elements. Set to 0 to disable padding. + **kwargs + Keyword arguments passed to Axes.__init__ + + Notes + ----- + When using external axes containers with multiple subplots, the external axes + (e.g., ternary plots) are automatically shrunk to prevent label overlap with + adjacent subplots. If you still experience overlap, you can: + + 1. Increase spacing with ``wspace`` or ``hspace`` in subplots() + 2. Decrease ``external_shrink_factor`` (more aggressive shrinking) + 3. Use tight_layout or constrained_layout for automatic spacing + + Example: ``uplt.subplots(ncols=2, projection=('ternary', None), wspace=5)`` + + To reduce padding between external axes and adjacent subplots, use: + ``external_padding=2`` or ``external_padding=0`` to disable padding entirely. + """ + _EXTERNAL_DELEGATE_BLOCKLIST = {'format', 'colorbar', 'legend', 'set_title'} + + def __init__(self, *args: Incomplete, external_axes_class: Incomplete=None, external_axes_kwargs: Incomplete=None, **kwargs: Incomplete) -> None: + """Initialize the container and create the external axes child.""" + ... + + def _create_external_axes(self) -> None: + """Create the external axes instance as a child of this container.""" + ... + + def _shrink_external_for_labels(self, base_pos: Incomplete=None) -> None: + """Shrink the external axes to leave room for labels that extend beyond the plot area. + +This is particularly important for ternary plots where axis labels can extend +significantly beyond the triangular plot region.""" + ... + + def _ensure_external_fits_within_container(self, renderer: Incomplete) -> None: + """Iteratively shrink external axes until it fits completely within container bounds. + +This ensures that external axes labels don't extend beyond the container's +allocated space and overlap with adjacent subplots.""" + ... + + def _sync_position_to_external(self) -> None: + """Synchronize the container position to the external axes.""" + ... + + def set_position(self, pos: Incomplete, which: Incomplete='both') -> None: + """Override to sync position changes to external axes.""" + ... + + def _reposition_subplot(self) -> None: + ... + + def _update_title_position(self, renderer: Incomplete) -> None: + ... + + def _title_reserves_external_space(self, loc: Incomplete) -> bool: + """Return whether a title-like artist needs room above an external axes.""" + ... + + def _iter_axes(self, hidden: Incomplete=True, children: Incomplete=True, panels: Incomplete=True) -> Incomplete: + """Override to only yield the container itself, not the external axes. + +The external axes is a rendering child, not a logical ultraplot child, +so we don't want ultraplot's iteration to find it and call ultraplot +methods on it.""" + ... + + def plot(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Delegate plot to external axes.""" + ... + + def scatter(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Delegate scatter to external axes.""" + ... + + def fill(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Delegate fill to external axes.""" + ... + + def contour(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Delegate contour to external axes.""" + ... + + def contourf(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Delegate contourf to external axes.""" + ... + + def pcolormesh(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Delegate pcolormesh to external axes.""" + ... + + def tripcolor(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Delegate tripcolor to external axes.""" + ... + + def tricontour(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Delegate tricontour to external axes.""" + ... + + def tricontourf(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Delegate tricontourf to external axes.""" + ... + + def triplot(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Delegate triplot to external axes.""" + ... + + def imshow(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Delegate imshow to external axes.""" + ... + + def hexbin(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Delegate hexbin to external axes.""" + ... + + def get_external_axes(self) -> Incomplete: + """Get the wrapped external axes instance. + +Returns +------- +axes + The external axes instance, or None if not created""" + ... + + def has_external_child(self) -> Incomplete: + """Check if this container has an external axes child. + +Returns +------- +bool + True if an external axes instance exists, False otherwise""" + ... + + def get_external_child(self) -> Incomplete: + """Get the external axes child (alias for get_external_axes). + +Returns +------- +axes + The external axes instance, or None if not created""" + ... + + def clear(self) -> None: + """Clear the container and mark external axes as stale.""" + ... + + def format(self, **kwargs: Incomplete) -> None: + """Format the container and delegate to external axes where appropriate. + +This method handles ultraplot-specific formatting on the container +and attempts to delegate common parameters to the external axes. + +Parameters +---------- +**kwargs + Formatting parameters. Common matplotlib parameters (title, xlabel, + ylabel, xlim, ylim) are delegated to the external axes if supported.""" + ... + + def draw(self, renderer: Incomplete) -> None: + """Override draw to render container (with abc/titles) and external axes.""" + ... + + def stale_callback(self, *args: Incomplete, **kwargs: Incomplete) -> None: + """Mark external axes as stale when container is marked stale.""" + ... + + def get_tightbbox(self, renderer: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Override to return the container bbox for consistent layout positioning. + +By returning the container's bbox, we ensure the layout engine positions +the container properly within the subplot grid, and we rely on our +iterative shrinking to ensure the external axes fits within the container.""" + ... + + def __getattr__(self, name: Incomplete) -> Incomplete: + """Delegate missing attributes to the external axes unless blocked.""" + ... + + def __dir__(self) -> list[str]: + """Include external axes attributes in dir() output.""" + ... + +def create_external_axes_container(external_axes_class: Incomplete, projection_name: Incomplete=None) -> Incomplete: + """Factory function to create a container class for a specific external axes type. + +Parameters +---------- +external_axes_class : type + The external axes class to wrap +projection_name : str, optional + The projection name to register with matplotlib + +Returns +------- +type + A subclass of ExternalAxesContainer configured for the external axes class""" + ... diff --git a/ultraplot/axes/geo.pyi b/ultraplot/axes/geo.pyi new file mode 100644 index 000000000..ba0aac785 --- /dev/null +++ b/ultraplot/axes/geo.pyi @@ -0,0 +1,1652 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Axes filled with cartographic projections. +""" +from _typeshed import Incomplete +import copy +import inspect +from dataclasses import dataclass +from functools import partial +from numbers import Real +from types import SimpleNamespace +try: + from typing import override +except ImportError: + from typing_extensions import override +from collections.abc import Iterator, Mapping, MutableMapping, Sequence +from typing import Any, Optional, Protocol +import matplotlib.axis as maxis +import matplotlib.axes as maxes +import matplotlib.collections as mcollections +import matplotlib.patches as mpatches +import matplotlib.path as mpath +import matplotlib.text as mtext +import matplotlib.ticker as mticker +import matplotlib.transforms as mtransforms +import numpy as np +from .. import constructor +from .. import proj as pproj +from .. import ticker as pticker +from ..config import rc +from ..internals import _not_none, _pop_params, _pop_props, _pop_rc, _version_cartopy, docstring, ic, labels, warnings +from ..utils import units +from . import plot, shared +try: + import cartopy.crs as ccrs + import cartopy.feature as cfeature + import cartopy.mpl.gridliner as cgridliner + from cartopy.crs import Projection + from cartopy.mpl.geoaxes import GeoAxes as _GeoAxes +except ModuleNotFoundError: + ccrs = cfeature = cgridliner = None + _GeoAxes = Projection = object +try: + from mpl_toolkits.basemap import Basemap +except ModuleNotFoundError: + Basemap = object +__all__ = ['GeoAxes'] +GridlineDict = MutableMapping[float, tuple[list[Any], list[mtext.Text]]] +_GRIDLINER_PAD_SCALE = 2.0 +_MINOR_TICK_SCALE = 0.6 +_BASEMAP_LABEL_SIZE_SCALE = 0.5 +_BASEMAP_LABEL_Y_SCALE = 0.65 +_BASEMAP_LABEL_X_SCALE = 0.25 +_CARTOPY_LABEL_SIDES = ('labelleft', 'labelright', 'labelbottom', 'labeltop', 'geo') +_BASEMAP_LABEL_SIDES = ('labelleft', 'labelright', 'labelbottom', 'labeltop', 'geo') +_HAWKEYE_ANCHORS = {'ul': (0, 1), 'upper left': (0, 1), 'ur': (1, 1), 'upper right': (1, 1), 'll': (0, 0), 'lower left': (0, 0), 'lr': (1, 0), 'lower right': (1, 0), 'c': (0.5, 0.5), 'center': (0.5, 0.5), 'uc': (0.5, 1), 'upper center': (0.5, 1), 'lc': (0.5, 0), 'lower center': (0.5, 0), 'cl': (0, 0.5), 'center left': (0, 0.5), 'cr': (1, 0.5), 'center right': (1, 0.5)} + +class _AnchoredInsetLocator: + """Locate an inset by anchoring one of its points to a parent coordinate.""" + + def __init__(self, parent: Incomplete, xy: Incomplete, size: Incomplete, transform: Incomplete, anchor: Incomplete, square: Incomplete=False) -> None: + ... + + def __call__(self, ax: Incomplete, renderer: Incomplete) -> Incomplete: + ... +_HAWKEYE_TRANSFORM_NAMES = frozenset({'axes', 'data', 'figure', 'subfigure', 'map'}) + +def _parse_hawkeye_anchor(anchor: Incomplete, axes_relative: Incomplete=True) -> Incomplete: + """Translate a named hawkeye anchor to normalized axes coordinates. + +String anchors are always axes-relative. When ``axes_relative`` is False the +caller supplied a non-default ``anchor_transform``, so a coordinate 2-tuple +is required and string aliases are rejected.""" + ... + +def _parse_hawkeye_size(size: Incomplete) -> Incomplete: + """Normalize scalar hawkeye sizes to square inset dimensions.""" + ... + +def _hawkeye_crs_from_name(name: Incomplete) -> Incomplete: + """Resolve a projection name to a cartopy CRS for hawkeye coordinates.""" + ... + +def _hawkeye_crs(transform: Incomplete, param: Incomplete) -> Incomplete: + """Resolve a hawkeye geographic transform to a cartopy CRS. + +Accepts ``'map'`` (an alias for `~cartopy.crs.PlateCarree`), a cartopy CRS +instance, or a registered projection name (e.g. ``'cyl'``, ``'moll'``).""" + ... + +def _parse_hawkeye_extent_transform(transform: Incomplete) -> Incomplete: + """Translate hawkeye extent transforms to cartopy coordinate systems.""" + ... + +def _parse_hawkeye_anchor_transform(transform: Incomplete) -> Incomplete: + """Resolve the coordinate system for a hawkeye anchor point. + +``'axes'`` (the default) leaves the anchor as an inset axes fraction and is +signalled by returning ``None``. Any other value is resolved to a cartopy CRS +so the anchor can be interpreted as a geographic or projected point.""" + ... + +def _hawkeye_anchor_fraction(inset: Incomplete, anchor: Incomplete, anchor_transform: Incomplete) -> Incomplete: + """Convert a hawkeye anchor point to an inset axes fraction. + +With ``anchor_transform`` None the anchor is already an axes fraction and is +returned unchanged. Otherwise the anchor is a point in ``anchor_transform`` +coordinates; it is projected into the inset projection and normalized against +the inset view limits, which are fixed by the time this runs.""" + ... + +def _parse_hawkeye_connector(connector: Incomplete) -> Incomplete: + """Normalize connector shorthand to a named presentation mode.""" + ... + +def _parse_hawkeye_shape(value: Incomplete, name: Incomplete) -> Incomplete: + """Validate a hawkeye inset or target shape.""" + ... + +def _square_hawkeye_view(inset: Incomplete) -> Incomplete: + """Expand the shorter projected dimension to make a square map viewport.""" + ... + +def _infer_hawkeye_relation(parent_extent: Incomplete, inset_extent: Incomplete) -> Incomplete: + """Infer whether an inset is a geographic detail or overview.""" + ... + +def _segments_intersect(start1: Incomplete, end1: Incomplete, start2: Incomplete, end2: Incomplete) -> Incomplete: + """Return whether two display-coordinate line segments intersect.""" + ... + +def _select_hawkeye_connector_pairs(extent_display: Incomplete, frame_display: Incomplete) -> Incomplete: + """Select the shortest pair of non-crossing overview connectors.""" + ... + +def _add_hawkeye_overview_connectors(parent: Incomplete, inset: Incomplete, extent: Incomplete, transform: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Connect the parent frame to its geographic extent on an overview inset.""" + ... + +def _add_hawkeye_leader(inset: Incomplete, target_axes: Incomplete, target_xy: Incomplete, transform: Incomplete, target_patch: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Draw a leader from an inset edge to a geographic target point.""" + ... + +def _add_hawkeye_zoom_indicator(parent: 'GeoAxes', inset: 'GeoAxes', **kwargs: Any) -> Incomplete: + """Draw an ``indicate_inset_zoom`` marker with a version-stable return. + +matplotlib >= 3.10 returns an ``InsetIndicator`` artist exposing +``.rectangle`` and ``.connectors``. Earlier versions return a plain +``(rectangle, connectors)`` tuple, so wrap it to expose the same accessors.""" + ... + +def _select_enveloping_connectors(indicator: Incomplete, inset: 'GeoAxes', renderer: Incomplete=None) -> None: + """Show the two zoom connectors that wrap around the inset (outer tangents). + +The visible pair is chosen from the sign of the inset-to-indicator centre +offset: a diagonally opposite pair envelops the inset, whereas a same-side +pair would run parallel and cross the frustum.""" + ... + +def _envelop_hawkeye_zoom_connectors(indicator: Incomplete, inset: 'GeoAxes') -> None: + """Reassert the enveloping connector pair on every draw. + +matplotlib fixes connector visibility once, from a bounding-box rule that can +pick a parallel pair for a diagonally placed inset. The inset position is only +final at draw time, so recompute the enveloping pair from a draw hook: on +matplotlib >= 3.10 the ``InsetIndicator`` resolves its connectors in its own +``draw``, while the legacy wrapper draws its rectangle before the connectors.""" + ... + +@dataclass +class _HawkeyeSpec: + """ + Validated inputs for :meth:`GeoAxes.hawkeye`. + + ``extent_transform`` and ``relation`` are only fully resolved when ``extent`` + is not ``None`` (they require a geographic extent to normalize and infer); + otherwise they retain their raw defaults and are never consumed. ``aspect`` is + intentionally not stored here because ``'projection'`` can only be resolved + from the live inset axes (see :meth:`GeoAxes._build_hawkeye_inset`). When + ``anchor_transform`` is not ``None`` the ``anchor`` is a geographic/projected + point rather than an axes fraction; it is converted to a fraction against the + live inset view limits in :meth:`GeoAxes._build_hawkeye_inset`. + """ + xy: tuple[float, float] + size: tuple[float, float] + anchor: tuple[float, float] + anchor_transform: Any + transform: Any + extent: Optional[tuple[float, float, float, float]] + extent_transform: Any + relation: str + connector: Optional[str] + shape: str + target: str + +def _apply_hawkeye_circle_boundary(inset: 'GeoAxes', aspect: str | float) -> None: + """Clip a hawkeye inset to a circular map boundary matching its view.""" + ... + +def _make_hawkeye_indicator_patch(extent: Sequence[float], transform: Any, target: str, **kwargs: Any) -> mpatches.Patch: + """Build the outline patch (box or circle) marking a hawkeye extent.""" + ... +_format_docstring = ... +_hawkeye_docstring = ... +_choropleth_docstring = ... + +class _GeoLabel(object): + """ + Optionally omit overlapping check if an rc setting is disabled. + """ + + def check_overlapping(self, *args: Any, **kwargs: Any) -> bool: + ... +if cgridliner is not None and hasattr(cgridliner, 'Label'): + + class _CartopyLabel(_GeoLabel, cgridliner.Label): + """Label class with configurable overlap checks.""" + + class _CartopyGridliner(cgridliner.Gridliner): + """ + Gridliner subclass to localize cartopy quirks in one place. + """ + LabelClass = _CartopyLabel + + def _generate_labels(self) -> Iterator[_CartopyLabel]: + """Yield label objects, reusing cached instances when possible.""" + ... + + def _axes_domain(self, *args: Any, **kwargs: Any) -> tuple[Any, Any]: + ... + + def _draw_gridliner(self, *args: Any, **kwargs: Any) -> Any: + ... +else: + _CartopyGridliner = None + +class _GeoAxis(object): + """ + Dummy axis used by longitude and latitude locators and for storing view limits on + longitude and latitude coordinates. Modeled after how `matplotlib.ticker._DummyAxis` + and `matplotlib.ticker.TickHelper` are used to control tick locations and labels. + """ + + def __init__(self, axes: 'GeoAxes') -> None: + ... + + def _get_extent(self) -> tuple[float, float, float, float]: + ... + + @staticmethod + def _pad_ticks(ticks: np.ndarray, vmin: float, vmax: float) -> np.ndarray: + ... + + def get_scale(self) -> str: + ... + + def get_tick_space(self) -> int: + ... + + def get_major_formatter(self) -> mticker.Formatter | None: + ... + + def get_major_locator(self) -> mticker.Locator | None: + ... + + def get_minor_locator(self) -> mticker.Locator | None: + ... + + def get_majorticklocs(self) -> np.ndarray: + ... + + def get_minorticklocs(self) -> np.ndarray: + ... + + def set_major_formatter(self, formatter: mticker.Formatter, default: bool=False) -> None: + ... + + def set_major_locator(self, locator: mticker.Locator, default: bool=False) -> None: + ... + + def set_minor_locator(self, locator: mticker.Locator, default: bool=False) -> None: + ... + + def set_view_interval(self, vmin: float, vmax: float) -> None: + ... + + def _copy_locator_properties(self, other: '_GeoAxis') -> None: + """This function copies the locator properties. It is +used when the @self is sharing with @other.""" + ... + +class _GridlinerAdapter(Protocol): + """ + Lightweight facade used to normalize cartopy and basemap gridliner behavior. + These adapters let GeoAxes apply gridline label toggles and styles without + backend-specific branching. + """ + + def labels_for_sides(self, *, bottom: bool | str | None=None, top: bool | str | None=None, left: bool | str | None=None, right: bool | str | None=None) -> dict[str, list[mtext.Text]]: + ... + + def toggle_labels(self, *, labelleft: bool | str | None=None, labelright: bool | str | None=None, labelbottom: bool | str | None=None, labeltop: bool | str | None=None, geo: bool | str | None=None) -> None: + ... + + def apply_style(self, *, axis: str='both', pad: float | None=None, labelsize: float | str | None=None, labelcolor: Any=None, labelrotation: float | None=None, linecolor: Any=None, linewidth: float | None=None) -> None: + ... + + def tick_positions(self, axis: str, *, lonaxis: '_GeoAxis', lataxis: '_GeoAxis') -> np.ndarray: + ... + + def is_label_on(self, side: str) -> bool: + ... + +class _CartopyGridlinerProtocol(Protocol): + """ + Structural protocol for the subset of cartopy Gridliner attributes we use. + This keeps type hints tight without importing cartopy at runtime. + """ + collection_kwargs: dict[str, Any] + xlabel_style: dict[str, Any] + ylabel_style: dict[str, Any] + xlocator: mticker.Locator + ylocator: mticker.Locator + xpadding: float | None + ypadding: float | None + xlines: bool + ylines: bool + x_inline: bool | None + y_inline: bool | None + rotate_labels: bool | None + inline_labels: bool | str | None + geo_labels: bool | str | None + left_label_artists: list[mtext.Text] + right_label_artists: list[mtext.Text] + bottom_label_artists: list[mtext.Text] + top_label_artists: list[mtext.Text] + xline_artists: list[Any] + + def _axes_domain(self, *args: Any, **kwargs: Any) -> tuple[Any, Any]: + ... + + def _draw_gridliner(self, *args: Any, **kwargs: Any) -> Any: + ... + +class _CartopyGridlinerAdapter(_GridlinerAdapter): + """ + Adapter for cartopy's Gridliner, translating common label/style operations + into the Gridliner API while hiding cartopy version differences. + """ + + def __init__(self, gridliner: Optional[_CartopyGridlinerProtocol]) -> None: + ... + + @staticmethod + def _side_labels() -> tuple[str, str, str, str]: + ... + + def labels_for_sides(self, *, bottom: bool | str | None=None, top: bool | str | None=None, left: bool | str | None=None, right: bool | str | None=None) -> dict[str, list[mtext.Text]]: + ... + + def toggle_labels(self, *, labelleft: bool | str | None=None, labelright: bool | str | None=None, labelbottom: bool | str | None=None, labeltop: bool | str | None=None, geo: bool | str | None=None) -> None: + ... + + def apply_style(self, *, axis: str='both', pad: float | None=None, labelsize: float | str | None=None, labelcolor: Any=None, labelrotation: float | None=None, linecolor: Any=None, linewidth: float | None=None) -> None: + ... + + def tick_positions(self, axis: str, *, lonaxis: _GeoAxis, lataxis: _GeoAxis) -> np.ndarray: + ... + + def is_label_on(self, side: str) -> bool: + ... + +class _BasemapGridlinerAdapter(_GridlinerAdapter): + """ + Adapter for basemap meridian/parallel dictionaries, emulating the subset + of cartopy Gridliner behavior needed by GeoAxes (labels, toggles, styling). + """ + + def __init__(self, lonlines: GridlineDict | None, latlines: GridlineDict | None) -> None: + ... + + def labels_for_sides(self, *, bottom: bool | str | None=None, top: bool | str | None=None, left: bool | str | None=None, right: bool | str | None=None) -> dict[str, list[mtext.Text]]: + ... + + def toggle_labels(self, *, labelleft: bool | str | None=None, labelright: bool | str | None=None, labelbottom: bool | str | None=None, labeltop: bool | str | None=None, geo: bool | str | None=None) -> None: + ... + + def apply_style(self, *, axis: str='both', pad: float | None=None, labelsize: float | str | None=None, labelcolor: Any=None, labelrotation: float | None=None, linecolor: Any=None, linewidth: float | None=None) -> None: + ... + + def tick_positions(self, axis: str, *, lonaxis: _GeoAxis, lataxis: _GeoAxis) -> np.ndarray: + ... + + def is_label_on(self, side: str) -> bool: + ... + +class _LonAxis(_GeoAxis): + """ + Axis with default longitude locator. + """ + axis_name = 'lon' + + def __init__(self, axes: 'GeoAxes') -> None: + ... + + def _get_ticklocs(self, locator: mticker.Locator) -> np.ndarray: + ... + + def get_view_interval(self) -> tuple[float, float]: + ... + +class _LatAxis(_GeoAxis): + """ + Axis with default latitude locator. + """ + axis_name = 'lat' + + def __init__(self, axes: 'GeoAxes', latmax: float=90) -> None: + ... + + def _get_ticklocs(self, locator: mticker.Locator) -> np.ndarray: + ... + + def get_latmax(self) -> float: + ... + + def get_view_interval(self) -> tuple[float, float]: + ... + + def set_latmax(self, latmax: float) -> None: + ... + +def _gridliner_sides_from_arrays(lonarray: Sequence[bool | None] | None, latarray: Sequence[bool | None] | None, *, order: Sequence[str], allow_xy: bool, include_false: bool) -> dict[str, bool | str]: + """Map lon/lat label arrays to gridliner toggle flags. + +Parameters +---------- +allow_xy + Use "x"/"y" to preserve axis-specific toggles when only one of lon/lat + is enabled for a given side (cartopy behavior). +include_false + Include explicit False entries to actively hide existing labels instead + of leaving previous state untouched (backend-dependent behavior).""" + ... + +class GeoAxes(shared._SharedAxes, plot.PlotAxes): + """ + Axes subclass for plotting in geographic projections. Uses either cartopy + or basemap as a "backend". + + Note + ---- + This subclass uses longitude and latitude as the default coordinate system for all + plotting commands by internally passing ``transform=cartopy.crs.PlateCarree()`` to + cartopy commands and ``latlon=True`` to basemap commands. Also, when using basemap + as the "backend", plotting is still done "cartopy-style" by calling methods from + the axes instance rather than the `~mpl_toolkits.basemap.Basemap` instance. + + Important + --------- + This axes subclass can be used by passing ``proj='proj_name'`` + to axes-creation commands like `~ultraplot.figure.Figure.add_axes`, + `~ultraplot.figure.Figure.add_subplot`, and `~ultraplot.figure.Figure.subplots`, + where ``proj_name`` is a registered :ref:`PROJ projection name `. + You can also pass a `~cartopy.crs.Projection` or `~mpl_toolkits.basemap.Basemap` + instance instead of a projection name. Alternatively, you can pass any of the + matplotlib-recognized axes subclass names ``proj='cartopy'``, ``proj='geo'``, or + ``proj='geographic'`` with a `~cartopy.crs.Projection` `map_projection` keyword + argument, or pass ``proj='basemap'`` with a `~mpl_toolkits.basemap.Basemap` + `map_projection` keyword argument. + """ + + def __init__(self, *args: Any, **kwargs: Any) -> None: + """Parameters +---------- +*args + Passed to `matplotlib.axes.Axes`. +map_projection : `~cartopy.crs.Projection` or `~mpl_toolkits.basemap.Basemap` + The cartopy or basemap projection instance. This is + passed automatically when calling axes-creation + commands like `~ultraplot.figure.Figure.add_subplot`. +aspect : {'auto', 'equal'} or float, optional + The map aspect ratio. ``'auto'`` makes the map fill its subplot slot, which + can be useful for aligning it with neighboring Cartesian axes but distorts + the projection. See :func:`~matplotlib.axes.Axes.set_aspect` for details. +abcanchor : {'axes', 'slot'}, default: 'axes' + The coordinate box used for the a-b-c label. ``'axes'`` attaches it to the + visible map boundary. ``'slot'`` attaches it to the unadjusted GridSpec + slot, keeping labels aligned with neighboring subplots when fixed map + aspect leaves empty space inside a slot. +round : bool, default: :rc:`geo.round` + *For polar cartopy axes only*. + Whether to bound polar projections with circles rather than squares. Note that outer + gridline labels cannot be added to circle-bounded polar projections. When basemap + is the backend this argument must be passed to `~ultraplot.constructor.Proj` instead. +extent : {'globe', 'auto'}, default: :rc:`geo.extent` + *For cartopy axes only*. + Whether to auto adjust the map bounds based on plotted content. If ``'globe'`` then + non-polar projections are fixed with `~cartopy.mpl.geoaxes.GeoAxes.set_global`, + non-Gnomonic polar projections are bounded at the equator, and Gnomonic polar + projections are bounded at 30 degrees latitude. If ``'auto'`` nothing is done. +lonlim, latlim : 2-tuple of float, optional + *For cartopy axes only.* + The approximate longitude and latitude boundaries of the map, applied + with `~cartopy.mpl.geoaxes.GeoAxes.set_extent`. When basemap is the backend + this argument must be passed to `~ultraplot.constructor.Proj` instead. +boundinglat : float, optional + *For cartopy axes only.* + The edge latitude for the circle bounding North Pole and South Pole-centered + projections. When basemap is the backend this argument must be passed to + `~ultraplot.constructor.Proj` instead. +longrid, latgrid, grid : bool, default: :rc:`grid` + Whether to draw longitude and latitude gridlines. + Use the keyword `grid` to toggle both at once. +longridminor, latgridminor, gridminor : bool, default: :rc:`gridminor` + Whether to draw "minor" longitude and latitude lines. + Use the keyword `gridminor` to toggle both at once. +lonticklen, latticklen, ticklen : unit-spec, default: :rc:`tick.len` + Major tick lengths for the longitudinal (x) and latitude (y) axis. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + Use the keyword `ticklen` to set both at once. +latmax : float, default: 80 + The maximum absolute latitude for gridlines. Longitude gridlines are cut off + poleward of this value (note this feature does not work in cartopy 0.18). +nsteps : int, default: :rc:`grid.nsteps` + *For cartopy axes only.* + The number of interpolation steps used to draw gridlines. +lonlocator, latlocator : locator-spec, optional + Used to determine the longitude and latitude gridline locations. + Aliases: ``lonlines`` and ``latlines``, respectively. + Passed to the `~ultraplot.constructor.Locator` constructor. Can be + string, float, list of float, or `matplotlib.ticker.Locator` instance. + + For basemap or cartopy < 0.18, the defaults are ``'deglon'`` and + ``'deglat'``, which correspond to the `~ultraplot.ticker.LongitudeLocator` + and `~ultraplot.ticker.LatitudeLocator` locators (adapted from cartopy). + For cartopy >= 0.18, the defaults are ``'dmslon'`` and ``'dmslat'``, + which uses the same locators with ``dms=True``. This selects gridlines + at nice degree-minute-second intervals when the map extent is very small. +lonlocator_kw, latlocator_kw : dict-like, optional + Keyword arguments passed to the `matplotlib.ticker.Locator` class. + Aliases: ``lonlines_kw`` and ``latlines_kw``, respectively. +lonminorlocator, latminorlocator : optional + As with `lonlocator` and `latlocator` but for the "minor" gridlines. + Aliases: ``lonminorlines`` and ``latminorlines``, respectively. +lonminorlocator_kw, latminorlocator_kw : optional + As with `lonlocator_kw`, and `latlocator_kw` but for the "minor" gridlines. + Aliases: ``lonminorlines_kw`` and ``latminorlines_kw``, respectively. +lonlabels, latlabels, labels : str, bool, or sequence, :rc:`grid.labels` + Whether to add non-inline longitude and latitude gridline labels, and on + which sides of the map. Use the keyword `labels` to set both at once. The + argument must conform to one of the following options: + + * A boolean. ``True`` indicates the bottom side for longitudes and + the left side for latitudes, and ``False`` disables all labels. + * A string or sequence of strings indicating the side names, e.g. + ``'top'`` for longitudes or ``('left', 'right')`` for latitudes. + * A string indicating the side names with single characters, e.g. + ``'bt'`` for longitudes or ``'lr'`` for latitudes. + * A string matching ``'neither'`` (no labels), ``'both'`` (equivalent + to ``'bt'`` for longitudes and ``'lr'`` for latitudes), or ``'all'`` + (equivalent to ``'lrbt'``, i.e. all sides). + * A boolean 2-tuple indicating whether to draw labels + on the ``(bottom, top)`` sides for longitudes, + and the ``(left, right)`` sides for latitudes. + * A boolean 4-tuple indicating whether to draw labels on the + ``(left, right, bottom, top)`` sides, as with the basemap + :func:`~mpl_toolkits.basemap.Basemap.drawmeridians` and + :func:`~mpl_toolkits.basemap.Basemap.drawparallels` `labels` keyword. + +loninline, latinline, inlinelabels : bool, default: :rc:`grid.inlinelabels` + *For cartopy axes only.* + Whether to add inline longitude and latitude gridline labels. Use + the keyword `inlinelabels` to set both at once. +rotatelabels : bool, default: :rc:`grid.rotatelabels` + *For cartopy axes only.* + Whether to rotate non-inline gridline labels so that they automatically + follow the map boundary curvature. +labelrotation : float, optional + The rotation angle in degrees for both longitude and latitude tick labels. + Use `lonlabelrotation` and `latlabelrotation` to set them separately. +lonlabelrotation : float, optional + The rotation angle in degrees for longitude tick labels. + Works for both cartopy and basemap backends. +latlabelrotation : float, optional + The rotation angle in degrees for latitude tick labels. + Works for both cartopy and basemap backends. +labelpad : unit-spec, default: :rc:`grid.labelpad` + *For cartopy axes only.* + The padding between non-inline gridline labels and the map boundary. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +dms : bool, default: :rc:`grid.dmslabels` + *For cartopy axes only.* + Whether the default locators and formatters should use "minutes" and "seconds" + for gridline labels on small scales rather than decimal degrees. Setting this to + ``False`` is equivalent to ``ax.format(lonlocator='deglon', latlocator='deglat')`` + and ``ax.format(lonformatter='deglon', latformatter='deglat')``. +lonformatter, latformatter : formatter-spec, optional + Formatter used to style longitude and latitude gridline labels. + Passed to the `~ultraplot.constructor.Formatter` constructor. Can be + string, list of string, or `matplotlib.ticker.Formatter` instance. + + For basemap or cartopy < 0.18, the defaults are ``'deglon'`` and + ``'deglat'``, which correspond to `~ultraplot.ticker.SimpleFormatter` + presets with degree symbols and cardinal direction suffixes. + For cartopy >= 0.18, the defaults are ``'dmslon'`` and ``'dmslat'``, + which uses cartopy's `~cartopy.mpl.ticker.LongitudeFormatter` and + `~cartopy.mpl.ticker.LatitudeFormatter` formatters with ``dms=True``. + This formats gridlines that do not fall on whole degrees as "minutes" and + "seconds" rather than decimal degrees. Use ``dms=False`` to disable this. +lonformatter_kw, latformatter_kw : dict-like, optional + Keyword arguments passed to the `matplotlib.ticker.Formatter` class. +land, ocean, coast, rivers, lakes, borders, innerborders : bool, optional + Toggles various geographic features. These are actually the + :rcraw:`land`, :rcraw:`ocean`, :rcraw:`coast`, :rcraw:`rivers`, + :rcraw:`lakes`, :rcraw:`borders`, and :rcraw:`innerborders` + settings passed to `~ultraplot.config.Configurator.context`. + The style can be modified using additional `rc` settings. + + For example, to change :rcraw:`land.color`, use + ``ax.format(landcolor='green')``, and to change + :rcraw:`land.zorder`, use ``ax.format(landzorder=4)``. +reso : {'lo', 'med', 'hi', 'x-hi', 'xx-hi'}, optional + *For cartopy axes only.* + The resolution of geographic features. When basemap is the backend this + must be passed to `~ultraplot.constructor.Proj` instead. +color : color-spec, default: :rc:`meta.color` + The color for the axes edge. Propagates to `labelcolor` unless specified + otherwise (similar to :func:`~ultraplot.axes.CartesianAxes.format`). +gridcolor : color-spec, default: :rc:`grid.color` + The color for the gridline labels. +labelcolor : color-spec, default: `color` or :rc:`grid.labelcolor` + The color for the gridline labels (`gridlabelcolor` is also allowed). +labelsize : unit-spec or str, default: :rc:`grid.labelsize` + The font size for the gridline labels (`gridlabelsize` is also allowed). + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +labelweight : str, default: :rc:`grid.labelweight` + The font weight for the gridline labels (`gridlabelweight` is also allowed). + +Other parameters +---------------- +title : str or sequence, optional + The axes title. Can optionally be a sequence strings, in which case + the title will be selected from the sequence according to `~Axes.number`. +abc : bool or str or sequence, default: :rc:`abc` + The "a-b-c" subplot label style. Must contain the character `a` or `A`, + for example ``'a.'``, or ``'A'``. If ``True`` then the default style of + ``'a'`` is used. The `a` or ``A`` is replaced with the alphabetic character + matching the `~Axes.number`. If `~Axes.number` is greater than 26, the + characters loop around to a, ..., z, aa, ..., zz, aaa, ..., zzz, etc. + Can also be a sequence of strings, in which case the "a-b-c" label will be selected sequentially from the list. For example `axs.format(abc = ["X", "Y"])` for a two-panel figure, and `axes[3:5].format(abc = ["X", "Y"])` for a two-panel subset of a larger figure. +abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` + Strings indicating the location for the a-b-c label and main title. + The following locations are valid: + + .. _title_table: + + ======================== ============================ + Location Valid keys + ======================== ============================ + center above axes ``'center'``, ``'c'`` + left above axes ``'left'``, ``'l'`` + right above axes ``'right'``, ``'r'`` + lower center inside axes ``'lower center'``, ``'lc'`` + upper center inside axes ``'upper center'``, ``'uc'`` + upper right inside axes ``'upper right'``, ``'ur'`` + upper left inside axes ``'upper left'``, ``'ul'`` + lower left inside axes ``'lower left'``, ``'ll'`` + lower right inside axes ``'lower right'``, ``'lr'`` + left of y axis ``'outer left'``, ``'ol'`` + right of y axis ``'outer right'``, ``'or'`` + ======================== ============================ + +abcborder, titleborder : bool, default: :rc:`abc.border` and :rc:`title.border` + Whether to draw a white border around titles and a-b-c labels positioned + inside the axes. This can help them stand out on top of artists + plotted inside the axes. +abcbbox, titlebbox : bool, default: :rc:`abc.bbox` and :rc:`title.bbox` + Whether to draw a white bbox around titles and a-b-c labels positioned + inside the axes. This can help them stand out on top of artists plotted + inside the axes. +abcpad : float or unit-spec, default: :rc:`abc.pad` + Horizontal offset to shift the a-b-c label position. Positive values move + the label right, negative values move it left. This is separate from + `abctitlepad`, which controls spacing between abc and title when co-located. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +abc_kw, title_kw : dict-like, optional + Additional settings used to update the a-b-c label and title + with ``text.update()``. +titlepad : float, default: :rc:`title.pad` + The padding for the inner and outer titles and a-b-c labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +titleabove : bool, default: :rc:`title.above` + Whether to try to put outer titles and a-b-c labels above panels, + colorbars, or legends that are above the axes. +abctitlepad : float, default: :rc:`abc.titlepad` + The horizontal padding between a-b-c labels and titles in the same location. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle : str or sequence, optional + Shorthands for the below keywords. + lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle : str or sequence, optional +lowerlefttitle, lowercentertitle, lowerrighttitle : str or sequence, optional + Additional titles in specific positions (see `title` for details). This works as + an alternative to the ``ax.format(title='Title', titleloc=loc)`` workflow and + permits adding more than one title-like label for a single axes. +a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle : default: + :rc:`axes.alpha` (default: 1.0), :rc:`axes.facecolor` (default: white), :rc:`axes.edgecolor` (default: black), :rc:`axes.linewidth` (default: 0.6), - + Additional settings applied to the background patch, and their + shorthands. Their defaults values are the ``'axes'`` properties. +rc_mode : int, optional + The context mode passed to `~ultraplot.config.Configurator.context`. +rc_kw : dict-like, optional + An alternative to passing extra keyword arguments. See below. +**kwargs + Remaining keyword arguments are passed to `matplotlib.axes.Axes`.\\n Keyword arguments that match the name of an `~ultraplot.config.rc` setting are + passed to `ultraplot.config.Configurator.context` and used to update the axes. + If the setting name has "dots" you can simply omit the dots. For example, + ``abc='A.'`` modifies the :rcraw:`abc` setting, ``titleloc='left'`` modifies the + :rcraw:`title.loc` setting, ``gridminor=True`` modifies the :rcraw:`gridminor` + setting, and ``gridbelow=True`` modifies the :rcraw:`grid.below` setting. Many + of the keyword arguments documented above are internally applied by retrieving + settings passed to `~ultraplot.config.Configurator.context`. + +See also +-------- +GeoAxes.format +ultraplot.constructor.Proj +ultraplot.axes.Axes +ultraplot.axes.PlotAxes +ultraplot.figure.Figure.subplot +ultraplot.figure.Figure.add_subplot""" + ... + + def _sync_shared_tick_state(self, which: str, *, copy_major_locator: bool=False, copy_minor_locator: bool=False, copy_major_formatter: bool=False) -> None: + """Copy explicit tick-state changes from this axis to shared GeoAxes siblings.""" + ... + + def hawkeye(self, xy: Sequence[float], size: float | Sequence[float], *, transform: Any='axes', anchor: str | Sequence[float]='upper right', anchor_transform: Any='axes', aspect: str | float='projection', extent: Optional[Sequence[float]]=None, extent_transform: Any='map', relation: str='auto', indicator: bool=True, connector: bool | str=False, shape: str='box', target: str='box', indicator_kw: Optional[Mapping[str, Any]]=None, **kwargs: Any) -> 'GeoAxes': + """Add a transform-anchored geographic callout inset. + +Parameters +---------- +xy : 2-tuple of float + The parent-axes coordinate at which to anchor the inset. +size : float or 2-tuple of float + The requested inset width and height as fractions of the parent axes box. A scalar + requests equal width and height before geographic aspect adjustment. +transform : coordinate system, default: 'axes' + Coordinate system for *xy*. One of: + + * ``'axes'`` -- parent axes fractions (`~matplotlib.axes.Axes.transAxes`). + * ``'data'`` -- parent *projected* coordinates + (`~matplotlib.axes.Axes.transData`), i.e. the parent projection's native + units (metres for most projections). This coincides with longitude-latitude + only for a default `~cartopy.crs.PlateCarree` parent, so it is rarely what + you want on a map; use ``'map'`` for longitude-latitude. + * ``'figure'`` / ``'subfigure'`` -- figure or subfigure fractions. + * ``'map'`` -- longitude-latitude degrees (`~cartopy.crs.PlateCarree`). + * a projection name (e.g. ``'cyl'``, ``'moll'``), a `~cartopy.crs.Projection`, + or a `~matplotlib.transforms.Transform` -- *xy* in arbitrary projected + coordinates. +anchor : str or 2-tuple of float, default: 'upper right' + The inset point placed at *xy*. String aliases include ``'ul'``, ``'ur'``, + ``'ll'``, ``'lr'``, and ``'c'``. A float 2-tuple is interpreted in + `anchor_transform` coordinates. String aliases are always axes-relative. +anchor_transform : coordinate system, default: 'axes' + Coordinate system for a float-tuple `anchor`. ``'axes'`` (the default) reads + the anchor as inset axes fractions, matching string aliases. ``'map'``, a + projection name, or a `~cartopy.crs.Projection` reads the anchor as a + geographic/projected point, so a specific location on the inset map (e.g. + ``anchor=(103.8, 1.3), anchor_transform='map'``) is placed at *xy*. The point + must fall within the inset extent. Requires the cartopy backend. +aspect : {'auto', 'projection'} or float, default: 'projection' + The inset aspect. ``'projection'`` preserves the geographic projection aspect + inside the requested box, while ``'auto'`` stretches the map to fill that box. + Circular insets expand the shorter projected dimension to avoid distorting the + projection. +grid : bool, default: False + Whether to draw gridlines in the inset. +extent : 4-tuple of float, optional + The geographic scope ``(west, east, south, north)`` displayed by the inset. +extent_transform : coordinate system, default: 'map' + Coordinate system for *extent*. ``'map'`` uses `~cartopy.crs.PlateCarree` + (longitude-latitude). A projection name (e.g. ``'cyl'``) or a + `~cartopy.crs.Projection` is also accepted. +relation : {'auto', 'detail', 'overview'}, default: 'auto' + Whether the inset is a zoomed detail of the parent or an overview containing the + parent extent. ``'auto'`` compares the rectangular extent sizes. This determines + where the extent outline and connectors are drawn. +indicator : bool, default: True + Whether to outline *extent* on the parent map when an extent is supplied. +connector : {False, True, 'corners', 'line'}, default: False + The connector presentation. ``True`` and ``'corners'`` draw corner links between + the extent outline and inset. ``'line'`` draws one leader from the inset boundary + to the target centre. Requires *extent*. +shape, target : {'box', 'circle'}, default: 'box' + The inset clipping shape and target marker shape. Circular targets require + ``connector='line'`` or no connector. +indicator_kw : dict-like, optional + Patch properties for the extent outline and connector lines. + +Other parameters +---------------- +**kwargs + Passed to `~Axes.inset_axes`. + +Returns +------- +GeoAxes + The geographic inset axes.""" + ... + + def _resolve_hawkeye_spec(self, xy: Sequence[float], size: float | Sequence[float], transform: Any, anchor: str | Sequence[float], anchor_transform: Any, extent: Optional[Sequence[float]], extent_transform: Any, relation: str, connector: bool | str, shape: str, target: str) -> '_HawkeyeSpec': + """Validate and normalize raw hawkeye arguments into a :class:`_HawkeyeSpec`.""" + ... + + def _resolve_hawkeye_xy_transform(self, transform: Any) -> Any: + """Resolve the *xy* transform, accepting projection names. + +Reserved names (``'axes'``, ``'data'``, ``'figure'``, ``'subfigure'``, +``'map'``), matplotlib transforms, and cartopy CRS instances are handled +by :meth:`_get_transform`. Any other string is treated as a projection +name and resolved to a cartopy CRS so *xy* can be given in arbitrary +projected coordinates.""" + ... + + def _build_hawkeye_inset(self, spec: '_HawkeyeSpec', aspect: str | float, **kwargs: Any) -> 'GeoAxes': + """Create the inset axes and configure its extent, aspect, and boundary.""" + ... + + def _add_hawkeye_indicator(self, inset: 'GeoAxes', spec: '_HawkeyeSpec', indicator_kw: Optional[Mapping[str, Any]], color: Any) -> None: + """Draw the extent indicator patch and any connectors onto the hawkeye.""" + ... + + @override + def _sharey_limits(self, sharey: 'GeoAxes') -> None: + ... + + @override + def _sharex_limits(self, sharex: 'GeoAxes') -> None: + ... + + def _share_limits_with(self, other: 'GeoAxes', which: str) -> None: + """Safely share limits and tickers without resetting things.""" + ... + + def _is_rectilinear(self) -> bool: + ... + + def __share_axis_setup(self, other: 'GeoAxes', *, which: str, labels: bool, limits: bool) -> None: + ... + + @override + def _sharey_setup(self, sharey: 'GeoAxes', *, labels: bool=True, limits: bool=True) -> None: + """Configure shared axes accounting for panels. The input is the +'parent' axes, from which this one will draw its properties.""" + ... + + @override + def _sharex_setup(self, sharex: 'GeoAxes', *, labels: bool=True, limits: bool=True) -> None: + ... + + def _toggle_ticks(self, label: Any, which: str) -> None: + """Toggle x/y tick positions from geo label specifications. + +Accepts the same `labels` forms as format(), including booleans, strings, +and boolean/string sequences. Only sides relevant to the requested axis +are considered: bottom/top for ``which='x'`` and left/right for +``which='y'``.""" + ... + + def _set_gridliner_adapter(self, which: str, adapter: Optional[_GridlinerAdapter]) -> None: + ... + + def _get_gridliner_adapter(self, which: str) -> Optional[_GridlinerAdapter]: + ... + + def _gridliner_adapter(self, which: str, *, create: bool=True) -> Optional[_GridlinerAdapter]: + """Return a cached gridliner adapter, optionally creating it via the backend +builder when missing.""" + ... + + def _iter_gridliner_adapters(self, which: str) -> Iterator[_GridlinerAdapter]: + """Yield available gridliner adapters for the requested tick selection.""" + ... + + def _gridliner_tick_positions(self, axis: str, *, which: str='major') -> np.ndarray: + """Return tick positions from the backend gridliner for a given axis.""" + ... + + @override + def tick_params(self, *args: Any, **kwargs: Any) -> Any: + """Apply tick parameters and mirror a subset of settings onto the backend +gridliner artists so gridline labels respond to common tick tweaks.""" + ... + + def _apply_axis_sharing(self) -> None: + """Enforce the "shared" axis labels and axis tick labels. If this is not +called at drawtime, "shared" labels can be inadvertantly turned off. + +Notes: + - Critical to apply labels to *shared* axes attributes rather than testing + extents or we end up sharing labels with twin axes. + - Similar to how align_super_labels() calls apply_title_above(), this is called + inside align_axis_labels() so we align the correct text. + - The "panel sharing group" refers to axes and panels *above* the bottommost + or to the *right* of the leftmost panel. But the sharing level used for + the leftmost and bottommost is the *figure* sharing level.""" + ... + + def _apply_aspect_and_adjust_panels(self, *, tol: float=1e-09) -> None: + """Apply aspect and then align panels to the adjusted axes box. + +Notes +----- +Cartopy and basemap use different tolerances when detecting whether +apply_aspect() actually changed the axes position.""" + ... + + def _compute_span_extent(self, side: Incomplete, panel: Incomplete, gs: Incomplete, p_r1: Incomplete, p_r2: Incomplete, p_c1: Incomplete, p_c2: Incomplete) -> tuple[float, float] | None: + """If the panel spans beyond the parent's SubplotSpec, compute the visual +extent (min, max) along the span axis from all non-panel axes in range. +Returns None if not a span override or no valid extent found.""" + ... + + @staticmethod + def _compute_adjusted_panel_pos(side: Incomplete, panel_pos: Incomplete, span_extent: Incomplete, original_pos: Incomplete, main_pos: Incomplete, sx: Incomplete, sy: Incomplete, tol: Incomplete) -> Incomplete: + """Compute the new [x0, y0, width, height] for a panel on the given side, +accounting for aspect-adjusted main axes and optional span extent. +Returns the new position list, or None for unknown sides.""" + ... + + def _adjust_panel_positions(self, *, tol: float=1e-09) -> None: + """Adjust panel positions to align with the aspect-constrained main axes. +After apply_aspect() shrinks the main axes, panels should flank the actual +map boundaries rather than the full gridspec allocation.""" + ... + + def _get_gridliner_labels(self, bottom: bool | str | None=None, top: bool | str | None=None, left: bool | str | None=None, right: bool | str | None=None) -> dict[str, list[mtext.Text]]: + ... + + def _update_title_position(self, renderer: Any) -> None: + """Optionally anchor the a-b-c label to the unadjusted subplot slot.""" + ... + + def _toggle_gridliner_labels(self, labeltop: bool | str | None=None, labelbottom: bool | str | None=None, labelleft: bool | str | None=None, labelright: bool | str | None=None, geo: bool | str | None=None) -> None: + """Toggle visibility of gridliner labels for each direction via the backend +adapter. + +Parameters +---------- +labeltop, labelbottom, labelleft, labelright : bool or None + Whether to show labels on each side. If None, do not change. +geo : optional + Not used in this method.""" + ... + + @override + def _is_ticklabel_on(self, side: str) -> bool: + """Check if tick labels are visible on the requested side via the backend adapter.""" + ... + + def _clear_edge_lon_labels(self) -> None: + ... + + def _sync_edge_lon_labels(self) -> None: + """Ensure cartopy top longitude labels include the endpoints when requested.""" + ... + + def _clear_edge_lat_labels(self) -> None: + ... + + def _sync_edge_lat_labels(self) -> None: + """Ensure cartopy left/right latitude labels include the endpoints when requested.""" + ... + + def _prune_corner_labels(self) -> bool: + """Drop endpoint labels at the map corners to reduce crowding.""" + ... + + @override + def draw(self, renderer: Any=None, *args: Any, **kwargs: Any) -> None: + ... + + def _get_lonticklocs(self, which: str='major') -> np.ndarray: + """Retrieve longitude tick locations.""" + ... + + def _get_latticklocs(self, which: str='major') -> np.ndarray: + """Retrieve latitude tick locations.""" + ... + + def _set_view_intervals(self, extent: Sequence[float]) -> None: + """Update view intervals for lon and lat axis.""" + ... + + @staticmethod + def _to_label_array(arg: Any, lon: bool=True) -> list[bool | None]: + """Convert labels argument to length-5 boolean array.""" + ... + + def _format_init_basemap_boundary(self) -> None: + """Initialize basemap boundaries before format triggers gridline work. + +Basemap can create a hidden boundary when gridlines are drawn before the +map boundary is initialized, so we force initialization here.""" + ... + + def _format_rc_context(self, kwargs: MutableMapping[str, Any], *, ticklen: Any, labelcolor: Any, labelsize: Any, labelweight: Any) -> tuple[dict[str, Any], int, Any]: + """Pop rc overrides and prepare context settings for format().""" + ... + + def _format_normalize_label_inputs(self, *, labels: Any, lonlabels: Any, latlabels: Any, loninline: bool | None, latinline: bool | None, inlinelabels: bool | None) -> tuple[Any, Any]: + """Normalize label inputs before rc context is applied.""" + ... + + def _format_resolve_label_arrays(self, *, labels: Any, lonlabels: Any, latlabels: Any) -> tuple[Any, Any, list[bool | None], list[bool | None]]: + """Resolve label toggles and return label arrays for gridliners.""" + ... + + def _format_update_latmax(self, latmax: float | None) -> None: + """Update the latitude gridline cutoff.""" + ... + + def _format_update_major_locators(self, *, lonlocator: Any, lonlines: Any, latlocator: Any, latlines: Any, lonlocator_kw: MutableMapping | None, lonlines_kw: MutableMapping | None, latlocator_kw: MutableMapping | None, latlines_kw: MutableMapping | None) -> None: + """Update major longitude/latitude locators.""" + ... + + def _format_update_minor_locators(self, *, lonminorlocator: Any, lonminorlines: Any, latminorlocator: Any, latminorlines: Any, lonminorlocator_kw: MutableMapping | None, lonminorlines_kw: MutableMapping | None, latminorlocator_kw: MutableMapping | None, latminorlines_kw: MutableMapping | None) -> None: + """Update minor longitude/latitude locators.""" + ... + + def _format_resolve_gridline_params(self, *, loninline: bool | None, latinline: bool | None, inlinelabels: bool | None, rotatelabels: bool | None, labelrotation: float | None, lonlabelrotation: float | None, latlabelrotation: float | None, labelpad: Any, dms: bool | None, nsteps: int | None) -> tuple[bool | None, bool | None, bool | None, float | None, float | None, Any, bool | None, int | None]: + """Resolve gridline-related parameters with rc defaults.""" + ... + + def _format_update_formatters(self, *, lonformatter: Any, latformatter: Any, lonformatter_kw: MutableMapping | None, latformatter_kw: MutableMapping | None, dms: bool | None) -> None: + """Update longitude/latitude formatters and DMS flags.""" + ... + + def _format_apply_grid_updates(self, *, lonlim: tuple[float | None, float | None] | None, latlim: tuple[float | None, float | None] | None, boundinglat: float | None, longrid: bool | None, latgrid: bool | None, longridminor: bool | None, latgridminor: bool | None, lonarray: Sequence[bool | None], latarray: Sequence[bool | None], loninline: bool | None, latinline: bool | None, rotatelabels: bool | None, lonlabelrotation: float | None, latlabelrotation: float | None, labelpad: Any, nsteps: int | None) -> tuple[tuple[float | None, float | None], tuple[float | None, float | None]]: + """Apply extent, features, and gridline updates for format().""" + ... + + def _format_apply_ticklen(self, *, lonlim: tuple[float | None, float | None], latlim: tuple[float | None, float | None], boundinglat: float | None, ticklen: Any, lonticklen: Any, latticklen: Any) -> None: + """Apply tick length updates, including any extent refresh for geoticks.""" + ... + + def format(self, *, aspect: str | float | None=None, abcanchor: str | None=None, extent: str | None=None, round: bool | None=None, lonlim: tuple[float | None, float | None] | None=None, latlim: tuple[float | None, float | None] | None=None, boundinglat: float | None=None, longrid: bool | None=None, latgrid: bool | None=None, longridminor: bool | None=None, latgridminor: bool | None=None, ticklen: Any=None, lonticklen: Any=None, latticklen: Any=None, latmax: float | None=None, nsteps: int | None=None, lonlocator: Any=None, lonlines: Any=None, latlocator: Any=None, latlines: Any=None, lonminorlocator: Any=None, lonminorlines: Any=None, latminorlocator: Any=None, latminorlines: Any=None, lonlocator_kw: MutableMapping | None=None, lonlines_kw: MutableMapping | None=None, latlocator_kw: MutableMapping | None=None, latlines_kw: MutableMapping | None=None, lonminorlocator_kw: MutableMapping | None=None, lonminorlines_kw: MutableMapping | None=None, latminorlocator_kw: MutableMapping | None=None, latminorlines_kw: MutableMapping | None=None, lonformatter: Any=None, latformatter: Any=None, lonformatter_kw: MutableMapping | None=None, latformatter_kw: MutableMapping | None=None, labels: Any=None, latlabels: Any=None, lonlabels: Any=None, rotatelabels: bool | None=None, labelrotation: float | None=None, lonlabelrotation: float | None=None, latlabelrotation: float | None=None, loninline: bool | None=None, latinline: bool | None=None, inlinelabels: bool | None=None, dms: bool | None=None, labelpad: Any=None, labelcolor: Any=None, labelsize: Any=None, labelweight: Any=None, **kwargs: Any) -> None: + """Modify map limits, longitude and latitude +gridlines, geographic features, and more. + +Parameters +---------- +aspect : {'auto', 'equal'} or float, optional + The map aspect ratio. ``'auto'`` makes the map fill its subplot slot, which + can be useful for aligning it with neighboring Cartesian axes but distorts + the projection. See :func:`~matplotlib.axes.Axes.set_aspect` for details. +abcanchor : {'axes', 'slot'}, default: 'axes' + The coordinate box used for the a-b-c label. ``'axes'`` attaches it to the + visible map boundary. ``'slot'`` attaches it to the unadjusted GridSpec + slot, keeping labels aligned with neighboring subplots when fixed map + aspect leaves empty space inside a slot. +round : bool, default: :rc:`geo.round` + *For polar cartopy axes only*. + Whether to bound polar projections with circles rather than squares. Note that outer + gridline labels cannot be added to circle-bounded polar projections. When basemap + is the backend this argument must be passed to `~ultraplot.constructor.Proj` instead. +extent : {'globe', 'auto'}, default: :rc:`geo.extent` + *For cartopy axes only*. + Whether to auto adjust the map bounds based on plotted content. If ``'globe'`` then + non-polar projections are fixed with `~cartopy.mpl.geoaxes.GeoAxes.set_global`, + non-Gnomonic polar projections are bounded at the equator, and Gnomonic polar + projections are bounded at 30 degrees latitude. If ``'auto'`` nothing is done. +lonlim, latlim : 2-tuple of float, optional + *For cartopy axes only.* + The approximate longitude and latitude boundaries of the map, applied + with `~cartopy.mpl.geoaxes.GeoAxes.set_extent`. When basemap is the backend + this argument must be passed to `~ultraplot.constructor.Proj` instead. +boundinglat : float, optional + *For cartopy axes only.* + The edge latitude for the circle bounding North Pole and South Pole-centered + projections. When basemap is the backend this argument must be passed to + `~ultraplot.constructor.Proj` instead. +longrid, latgrid, grid : bool, default: :rc:`grid` + Whether to draw longitude and latitude gridlines. + Use the keyword `grid` to toggle both at once. +longridminor, latgridminor, gridminor : bool, default: :rc:`gridminor` + Whether to draw "minor" longitude and latitude lines. + Use the keyword `gridminor` to toggle both at once. +lonticklen, latticklen, ticklen : unit-spec, default: :rc:`tick.len` + Major tick lengths for the longitudinal (x) and latitude (y) axis. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + Use the keyword `ticklen` to set both at once. +latmax : float, default: 80 + The maximum absolute latitude for gridlines. Longitude gridlines are cut off + poleward of this value (note this feature does not work in cartopy 0.18). +nsteps : int, default: :rc:`grid.nsteps` + *For cartopy axes only.* + The number of interpolation steps used to draw gridlines. +lonlocator, latlocator : locator-spec, optional + Used to determine the longitude and latitude gridline locations. + Aliases: ``lonlines`` and ``latlines``, respectively. + Passed to the `~ultraplot.constructor.Locator` constructor. Can be + string, float, list of float, or `matplotlib.ticker.Locator` instance. + + For basemap or cartopy < 0.18, the defaults are ``'deglon'`` and + ``'deglat'``, which correspond to the `~ultraplot.ticker.LongitudeLocator` + and `~ultraplot.ticker.LatitudeLocator` locators (adapted from cartopy). + For cartopy >= 0.18, the defaults are ``'dmslon'`` and ``'dmslat'``, + which uses the same locators with ``dms=True``. This selects gridlines + at nice degree-minute-second intervals when the map extent is very small. +lonlocator_kw, latlocator_kw : dict-like, optional + Keyword arguments passed to the `matplotlib.ticker.Locator` class. + Aliases: ``lonlines_kw`` and ``latlines_kw``, respectively. +lonminorlocator, latminorlocator : optional + As with `lonlocator` and `latlocator` but for the "minor" gridlines. + Aliases: ``lonminorlines`` and ``latminorlines``, respectively. +lonminorlocator_kw, latminorlocator_kw : optional + As with `lonlocator_kw`, and `latlocator_kw` but for the "minor" gridlines. + Aliases: ``lonminorlines_kw`` and ``latminorlines_kw``, respectively. +lonlabels, latlabels, labels : str, bool, or sequence, :rc:`grid.labels` + Whether to add non-inline longitude and latitude gridline labels, and on + which sides of the map. Use the keyword `labels` to set both at once. The + argument must conform to one of the following options: + + * A boolean. ``True`` indicates the bottom side for longitudes and + the left side for latitudes, and ``False`` disables all labels. + * A string or sequence of strings indicating the side names, e.g. + ``'top'`` for longitudes or ``('left', 'right')`` for latitudes. + * A string indicating the side names with single characters, e.g. + ``'bt'`` for longitudes or ``'lr'`` for latitudes. + * A string matching ``'neither'`` (no labels), ``'both'`` (equivalent + to ``'bt'`` for longitudes and ``'lr'`` for latitudes), or ``'all'`` + (equivalent to ``'lrbt'``, i.e. all sides). + * A boolean 2-tuple indicating whether to draw labels + on the ``(bottom, top)`` sides for longitudes, + and the ``(left, right)`` sides for latitudes. + * A boolean 4-tuple indicating whether to draw labels on the + ``(left, right, bottom, top)`` sides, as with the basemap + :func:`~mpl_toolkits.basemap.Basemap.drawmeridians` and + :func:`~mpl_toolkits.basemap.Basemap.drawparallels` `labels` keyword. + +loninline, latinline, inlinelabels : bool, default: :rc:`grid.inlinelabels` + *For cartopy axes only.* + Whether to add inline longitude and latitude gridline labels. Use + the keyword `inlinelabels` to set both at once. +rotatelabels : bool, default: :rc:`grid.rotatelabels` + *For cartopy axes only.* + Whether to rotate non-inline gridline labels so that they automatically + follow the map boundary curvature. +labelrotation : float, optional + The rotation angle in degrees for both longitude and latitude tick labels. + Use `lonlabelrotation` and `latlabelrotation` to set them separately. +lonlabelrotation : float, optional + The rotation angle in degrees for longitude tick labels. + Works for both cartopy and basemap backends. +latlabelrotation : float, optional + The rotation angle in degrees for latitude tick labels. + Works for both cartopy and basemap backends. +labelpad : unit-spec, default: :rc:`grid.labelpad` + *For cartopy axes only.* + The padding between non-inline gridline labels and the map boundary. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +dms : bool, default: :rc:`grid.dmslabels` + *For cartopy axes only.* + Whether the default locators and formatters should use "minutes" and "seconds" + for gridline labels on small scales rather than decimal degrees. Setting this to + ``False`` is equivalent to ``ax.format(lonlocator='deglon', latlocator='deglat')`` + and ``ax.format(lonformatter='deglon', latformatter='deglat')``. +lonformatter, latformatter : formatter-spec, optional + Formatter used to style longitude and latitude gridline labels. + Passed to the `~ultraplot.constructor.Formatter` constructor. Can be + string, list of string, or `matplotlib.ticker.Formatter` instance. + + For basemap or cartopy < 0.18, the defaults are ``'deglon'`` and + ``'deglat'``, which correspond to `~ultraplot.ticker.SimpleFormatter` + presets with degree symbols and cardinal direction suffixes. + For cartopy >= 0.18, the defaults are ``'dmslon'`` and ``'dmslat'``, + which uses cartopy's `~cartopy.mpl.ticker.LongitudeFormatter` and + `~cartopy.mpl.ticker.LatitudeFormatter` formatters with ``dms=True``. + This formats gridlines that do not fall on whole degrees as "minutes" and + "seconds" rather than decimal degrees. Use ``dms=False`` to disable this. +lonformatter_kw, latformatter_kw : dict-like, optional + Keyword arguments passed to the `matplotlib.ticker.Formatter` class. +land, ocean, coast, rivers, lakes, borders, innerborders : bool, optional + Toggles various geographic features. These are actually the + :rcraw:`land`, :rcraw:`ocean`, :rcraw:`coast`, :rcraw:`rivers`, + :rcraw:`lakes`, :rcraw:`borders`, and :rcraw:`innerborders` + settings passed to `~ultraplot.config.Configurator.context`. + The style can be modified using additional `rc` settings. + + For example, to change :rcraw:`land.color`, use + ``ax.format(landcolor='green')``, and to change + :rcraw:`land.zorder`, use ``ax.format(landzorder=4)``. +reso : {'lo', 'med', 'hi', 'x-hi', 'xx-hi'}, optional + *For cartopy axes only.* + The resolution of geographic features. When basemap is the backend this + must be passed to `~ultraplot.constructor.Proj` instead. +color : color-spec, default: :rc:`meta.color` + The color for the axes edge. Propagates to `labelcolor` unless specified + otherwise (similar to :func:`~ultraplot.axes.CartesianAxes.format`). +gridcolor : color-spec, default: :rc:`grid.color` + The color for the gridline labels. +labelcolor : color-spec, default: `color` or :rc:`grid.labelcolor` + The color for the gridline labels (`gridlabelcolor` is also allowed). +labelsize : unit-spec or str, default: :rc:`grid.labelsize` + The font size for the gridline labels (`gridlabelsize` is also allowed). + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +labelweight : str, default: :rc:`grid.labelweight` + The font weight for the gridline labels (`gridlabelweight` is also allowed). + +Other parameters +---------------- +title : str or sequence, optional + The axes title. Can optionally be a sequence strings, in which case + the title will be selected from the sequence according to `~Axes.number`. +abc : bool or str or sequence, default: :rc:`abc` + The "a-b-c" subplot label style. Must contain the character `a` or `A`, + for example ``'a.'``, or ``'A'``. If ``True`` then the default style of + ``'a'`` is used. The `a` or ``A`` is replaced with the alphabetic character + matching the `~Axes.number`. If `~Axes.number` is greater than 26, the + characters loop around to a, ..., z, aa, ..., zz, aaa, ..., zzz, etc. + Can also be a sequence of strings, in which case the "a-b-c" label will be selected sequentially from the list. For example `axs.format(abc = ["X", "Y"])` for a two-panel figure, and `axes[3:5].format(abc = ["X", "Y"])` for a two-panel subset of a larger figure. +abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` + Strings indicating the location for the a-b-c label and main title. + The following locations are valid: + + .. _title_table: + + ======================== ============================ + Location Valid keys + ======================== ============================ + center above axes ``'center'``, ``'c'`` + left above axes ``'left'``, ``'l'`` + right above axes ``'right'``, ``'r'`` + lower center inside axes ``'lower center'``, ``'lc'`` + upper center inside axes ``'upper center'``, ``'uc'`` + upper right inside axes ``'upper right'``, ``'ur'`` + upper left inside axes ``'upper left'``, ``'ul'`` + lower left inside axes ``'lower left'``, ``'ll'`` + lower right inside axes ``'lower right'``, ``'lr'`` + left of y axis ``'outer left'``, ``'ol'`` + right of y axis ``'outer right'``, ``'or'`` + ======================== ============================ + +abcborder, titleborder : bool, default: :rc:`abc.border` and :rc:`title.border` + Whether to draw a white border around titles and a-b-c labels positioned + inside the axes. This can help them stand out on top of artists + plotted inside the axes. +abcbbox, titlebbox : bool, default: :rc:`abc.bbox` and :rc:`title.bbox` + Whether to draw a white bbox around titles and a-b-c labels positioned + inside the axes. This can help them stand out on top of artists plotted + inside the axes. +abcpad : float or unit-spec, default: :rc:`abc.pad` + Horizontal offset to shift the a-b-c label position. Positive values move + the label right, negative values move it left. This is separate from + `abctitlepad`, which controls spacing between abc and title when co-located. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +abc_kw, title_kw : dict-like, optional + Additional settings used to update the a-b-c label and title + with ``text.update()``. +titlepad : float, default: :rc:`title.pad` + The padding for the inner and outer titles and a-b-c labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +titleabove : bool, default: :rc:`title.above` + Whether to try to put outer titles and a-b-c labels above panels, + colorbars, or legends that are above the axes. +abctitlepad : float, default: :rc:`abc.titlepad` + The horizontal padding between a-b-c labels and titles in the same location. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle : str or sequence, optional + Shorthands for the below keywords. + lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle : str or sequence, optional +lowerlefttitle, lowercentertitle, lowerrighttitle : str or sequence, optional + Additional titles in specific positions (see `title` for details). This works as + an alternative to the ``ax.format(title='Title', titleloc=loc)`` workflow and + permits adding more than one title-like label for a single axes. +a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle : default: + :rc:`axes.alpha` (default: 1.0), :rc:`axes.facecolor` (default: white), :rc:`axes.edgecolor` (default: black), :rc:`axes.linewidth` (default: 0.6), - + Additional settings applied to the background patch, and their + shorthands. Their defaults values are the ``'axes'`` properties. +rowlabels, collabels, llabels, tlabels, rlabels, blabels + Aliases for `leftlabels` and `toplabels`, and for `leftlabels`, + `toplabels`, `rightlabels`, and `bottomlabels`, respectively. +leftlabels, toplabels, rightlabels, bottomlabels : sequence of str, optional + Labels for the subplots lying along the left, top, right, and + bottom edges of the figure. The length of each list must match + the number of subplots along the corresponding edge. +leftlabelpad, toplabelpad, rightlabelpad, bottomlabelpad : float or unit-spec, default +: :rc:`leftlabel.pad`, :rc:`toplabel.pad`, :rc:`rightlabel.pad`, :rc:`bottomlabel.pad` + The padding between the labels and the axes content. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +leftlabelsharedpad, toplabelsharedpad, rightlabelsharedpad, bottomlabelsharedpad : float or unit-spec, default +: :rc:`leftlabel.sharedpad`, :rc:`toplabel.sharedpad`, :rc:`rightlabel.sharedpad`, :rc:`bottomlabel.sharedpad` + The padding between side labels and a shared spanning axis label on the + same side. The spanning label is placed outside the side labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +leftlabels_kw, toplabels_kw, rightlabels_kw, bottomlabels_kw : dict-like, optional + Additional settings used to update the labels with ``text.update()``. +figtitle + Alias for `suptitle`. +suptitle : str, optional + The figure "super" title, centered between the left edge of the leftmost + subplot and the right edge of the rightmost subplot. +suptitlepad : float, default: :rc:`suptitle.pad` + The padding between the super title and the axes content. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +suptitle_kw : optional + Additional settings used to update the super title with ``text.update()``. +includepanels : bool, default: False + Whether to include panels when aligning figure "super titles" along the top + of the subplot grid and when aligning the `spanx` *x* axis labels and + `spany` *y* axis labels along the sides of the subplot grid. +rc_mode : int, optional + The context mode passed to `~ultraplot.config.Configurator.context`. +rc_kw : dict-like, optional + An alternative to passing extra keyword arguments. See below. +**kwargs + Keyword arguments that match the name of an `~ultraplot.config.rc` setting are + passed to `ultraplot.config.Configurator.context` and used to update the axes. + If the setting name has "dots" you can simply omit the dots. For example, + ``abc='A.'`` modifies the :rcraw:`abc` setting, ``titleloc='left'`` modifies the + :rcraw:`title.loc` setting, ``gridminor=True`` modifies the :rcraw:`gridminor` + setting, and ``gridbelow=True`` modifies the :rcraw:`grid.below` setting. Many + of the keyword arguments documented above are internally applied by retrieving + settings passed to `~ultraplot.config.Configurator.context`. + +See also +-------- +ultraplot.axes.Axes.format +ultraplot.config.Configurator.context""" + ... + + def choropleth(self, geometries: Sequence[Any], values: Sequence[Any] | None=None, *, transform: Any=None, country: bool=False, country_reso: str | None=None, country_territories: bool | None=None, colorbar: Any=None, colorbar_kw: MutableMapping[str, Any] | None=None, missing_kw: MutableMapping[str, Any] | None=None, **kwargs: Any) -> mcollections.PatchCollection: + """Draw polygon geometries colored by numeric values. + +Parameters +---------- +geometries + Sequence of polygon-like shapely geometries. Typical inputs include + GeoPandas ``geometry`` arrays or lists of shapely polygons in + longitude-latitude coordinates. When `country=True`, this can also + be a sequence of country codes/names or a mapping of country + identifiers to values. +values + Numeric values mapped to colors. Must have the same length as + `geometries`. Optional when `country=True` and `geometries` is a + mapping of country identifiers to values. +transform : cartopy CRS, optional + The input coordinate system for `geometries`. By default, cartopy + backends assume `~cartopy.crs.PlateCarree` and basemap backends + assume longitude-latitude input. +country : bool, optional + Interpret `geometries` as country identifiers and resolve them to + Natural Earth polygons before plotting. +country_reso : {'110m', '50m', '10m'}, optional + The Natural Earth country resolution used when `country=True`. + Defaults to :rc:`geo.choropleth.country_reso`. +country_territories : bool, optional + Whether to keep distant territories for multi-part country + geometries when `country=True`. Defaults to + :rc:`geo.choropleth.country_territories`. +colorbar, colorbar_kw + Passed to `~ultraplot.axes.Axes.colorbar`. +missing_kw : dict-like, optional + Style applied to geometries whose values are missing or non-finite. + If omitted, missing geometries are skipped. + +Other parameters +---------------- +cmap, cmap_kw, norm, norm_kw, vmin, vmax, levels, values + Standard UltraPlot colormap arguments. +edgecolor, linewidth, alpha, hatch, rasterized, zorder, label, ... + Collection styling arguments passed to the polygon collection. + +Returns +------- +matplotlib.collections.PatchCollection + The scalar-mappable collection for finite-valued polygons.""" + ... + + def _add_geoticks(self, x_or_y: str, itick: Any, ticklen: Any) -> None: + """Add tick marks to the geographic axes. + +Parameters +---------- +x_or_y : {'x', 'y'} + The axis to add ticks to ('x' for longitude, 'y' for latitude). +itick, ticklen : unit-spec, default: :rc:`tick.len` + Major tick lengths for the x and y axis. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + Use the argument `ticklen` to set both at once. + +Notes +----- +This method handles proper tick mark drawing for geographic projections +while respecting the current gridline settings.""" + ... + + def _add_gridline_labels(self, ax: maxis.Axis, gl: tuple[GridlineDict, GridlineDict], padding: float | int=8) -> None: + """This function is intended for the Basemap backend +and mirrors the label placement behavior of Cartopy. +See: https://cartopy.readthedocs.io/stable/reference/generated/cartopy.mpl.gridliner.Gridliner.html""" + ... + + @property + def gridlines_major(self) -> Any: + """The cartopy `~cartopy.mpl.gridliner.Gridliner` +used for major gridlines or a 2-tuple containing the +(longitude, latitude) major gridlines returned by +basemap's :func:`~mpl_toolkits.basemap.Basemap.drawmeridians` +and :func:`~mpl_toolkits.basemap.Basemap.drawparallels`. +This can be used for customization and debugging.""" + ... + + @property + def gridlines_minor(self) -> Any: + """The cartopy `~cartopy.mpl.gridliner.Gridliner` +used for minor gridlines or a 2-tuple containing the +(longitude, latitude) minor gridlines returned by +basemap's :func:`~mpl_toolkits.basemap.Basemap.drawmeridians` +and :func:`~mpl_toolkits.basemap.Basemap.drawparallels`. +This can be used for customization and debugging.""" + ... + + @property + def projection(self) -> Any: + """The cartopy `~cartopy.crs.Projection` or basemap `~mpl_toolkits.basemap.Basemap` +instance associated with this axes.""" + ... + + @projection.setter + def projection(self, map_projection: Any) -> None: + ... + +class _CartopyAxes(GeoAxes, _GeoAxes): + """ + Axes subclass for plotting cartopy projections. + """ + _name = 'cartopy' + _name_aliases = ('geo', 'geographic') + _proj_class = Projection + _PANEL_TOL = 1e-09 + _proj_north = (pproj.NorthPolarStereo, pproj.NorthPolarGnomonic, pproj.NorthPolarAzimuthalEquidistant, pproj.NorthPolarLambertAzimuthalEqualArea) + _proj_south = (pproj.SouthPolarStereo, pproj.SouthPolarGnomonic, pproj.SouthPolarAzimuthalEquidistant, pproj.SouthPolarLambertAzimuthalEqualArea) + _proj_polar = _proj_north + _proj_south + + def __init__(self, *args: Any, map_projection: Any=None, **kwargs: Any) -> None: + """Parameters +---------- +map_projection : ~cartopy.crs.Projection + The map projection. +*args, **kwargs + Passed to `GeoAxes`.""" + ... + + @staticmethod + def _get_circle_path(N: int=100) -> mpath.Path: + """Return a circle `~matplotlib.path.Path` used as the outline for polar +stereographic, azimuthal equidistant, Lambert conformal, and gnomonic +projections. This was developed from `this cartopy example `__.""" + ... + + def _get_global_extent(self) -> list[float]: + """Return the global extent with meridian properly shifted.""" + ... + + def _get_lon0(self) -> float: + """Get the central longitude. Default is ``0``.""" + ... + + def gridlines(self, crs: Any=None, draw_labels: bool | str | None=False, xlocs: mticker.Locator | Sequence[float] | None=None, ylocs: mticker.Locator | Sequence[float] | None=None, dms: bool=False, x_inline: bool | None=None, y_inline: bool | None=None, auto_inline: bool=True, xformatter: Any=None, yformatter: Any=None, xlim: Sequence[float] | None=None, ylim: Sequence[float] | None=None, rotate_labels: bool | float | None=None, xlabel_style: MutableMapping[str, Any] | None=None, ylabel_style: MutableMapping[str, Any] | None=None, labels_bbox_style: MutableMapping[str, Any] | None=None, xpadding: float | None=5, ypadding: float | None=5, offset_angle: float=25, auto_update: bool | None=None, formatter_kwargs: MutableMapping[str, Any] | None=None, **kwargs: Any) -> _CartopyGridlinerProtocol: + """Override cartopy gridlines to use a local Gridliner subclass.""" + ... + + def _init_gridlines(self) -> _CartopyGridlinerProtocol: + """Create "major" and "minor" gridliners managed by ultraplot.""" + ... + + def _build_gridliner_adapter(self, which: str='major') -> Optional[_GridlinerAdapter]: + ... + + def _update_background(self, **kwargs: Any) -> None: + """Update the map background patches. This is called in `Axes.format`.""" + ... + + def _update_boundary(self, round: bool | None=None) -> None: + """Update the map boundary path.""" + ... + + def _update_extent_mode(self, extent: str | None=None, boundinglat: float | None=None) -> None: + """Update the extent mode.""" + ... + + def _update_extent(self, lonlim: tuple[float | None, float | None] | None=None, latlim: tuple[float | None, float | None] | None=None, boundinglat: float | None=None) -> None: + """Set the projection extent.""" + ... + + def _update_features(self) -> None: + """Update geographic features.""" + ... + + def _update_gridlines(self, gl: _CartopyGridlinerProtocol, which: str='major', longrid: bool | None=None, latgrid: bool | None=None, nsteps: int | None=None) -> None: + """Update gridliner object with axis locators, and toggle gridlines on and off.""" + ... + + def _update_major_gridlines(self, longrid: bool | None=None, latgrid: bool | None=None, lonarray: Sequence[bool | None] | None=None, latarray: Sequence[bool | None] | None=None, loninline: bool | None=None, latinline: bool | None=None, labelpad: Any=None, rotatelabels: bool | None=None, lonlabelrotation: float | None=None, latlabelrotation: float | None=None, nsteps: int | None=None) -> None: + """Update major gridlines.""" + ... + + def _update_minor_gridlines(self, longrid: bool | None=None, latgrid: bool | None=None, nsteps: int | None=None) -> None: + """Update minor gridlines.""" + ... + + def get_extent(self, crs: Any=None) -> Sequence[float]: + ... + + @override + def draw(self, renderer: Any=None, *args: Any, **kwargs: Any) -> None: + """Override draw to adjust panel positions for cartopy axes. + +Cartopy's apply_aspect() can shrink the main axes to enforce the projection +aspect ratio. Panels occupy separate gridspec slots, so we reposition them +after the main axes has applied its aspect but before the panel axes are drawn.""" + ... + + def get_tightbbox(self, renderer: Any, *args: Any, **kwargs: Any) -> Any: + ... + + def set_extent(self, extent: Sequence[float], crs: Any=None) -> Any: + ... + + def set_global(self) -> Any: + ... + +class _BasemapAxes(GeoAxes): + """ + Axes subclass for plotting basemap projections. + """ + _name = 'basemap' + _proj_class = Basemap + _proj_north = ('npaeqd', 'nplaea', 'npstere') + _proj_south = ('spaeqd', 'splaea', 'spstere') + _proj_polar = _proj_north + _proj_south + _proj_non_rectangular = _proj_polar + ('ortho', 'geos', 'nsper', 'moll', 'hammer', 'robin', 'eck4', 'kav7', 'mbtfpq', 'sinu', 'vandg') + _PANEL_TOL = 1e-06 + + def __init__(self, *args: Any, map_projection: Any=None, **kwargs: Any) -> None: + """Parameters +---------- +map_projection : ~mpl_toolkits.basemap.Basemap + The map projection. +*args, **kwargs + Passed to `GeoAxes`.""" + ... + + def get_tightbbox(self, renderer: Any, *args: Any, **kwargs: Any) -> Any: + """Get tight bounding box, adjusting panel positions after aspect is applied. + +This ensures panels are properly aligned when saving figures, as apply_aspect() +may be called during the rendering process.""" + ... + + @override + def draw(self, renderer: Any=None, *args: Any, **kwargs: Any) -> None: + """Override draw to adjust panel positions for basemap axes. + +Basemap projections also rely on apply_aspect() and can shrink the main axes; +panels must be repositioned to flank the visible map boundaries.""" + ... + + def _turnoff_tick_labels(self, locator: GridlineDict) -> None: + """For GeoAxes with are dealing with a duality. Basemap axes behave differently than Cartopy axes and vice versa. UltraPlot abstracts away from these by providing GeoAxes. For basemap axes we need to turn off the tick labels as they will be handles by GeoAxis""" + ... + + def _get_lon0(self) -> float: + """Get the central longitude.""" + ... + + @staticmethod + def _iter_gridlines(dict_: GridlineDict | None) -> Iterator[Any]: + """Iterate over longitude latitude lines.""" + ... + + def _build_gridliner_adapter(self, which: str='major') -> Optional[_GridlinerAdapter]: + ... + + def _update_background(self, **kwargs: Any) -> None: + """Update the map boundary patches. This is called in `Axes.format`.""" + ... + + def _update_boundary(self, round: bool | None=None) -> None: + """No-op. Boundary mode cannot be changed in basemap.""" + ... + + def _update_extent_mode(self, extent: str | None=None, boundinglat: float | None=None) -> None: + """No-op. Extent mode cannot be changed in basemap.""" + ... + + def _update_extent(self, lonlim: tuple[float | None, float | None] | None=None, latlim: tuple[float | None, float | None] | None=None, boundinglat: float | None=None) -> None: + """No-op. Map bounds cannot be changed in basemap.""" + ... + + def _update_features(self) -> None: + """Update geographic features.""" + ... + + def _update_gridlines(self, which: str='major', longrid: bool | None=None, latgrid: bool | None=None, lonarray: Sequence[bool | None] | None=None, latarray: Sequence[bool | None] | None=None, lonlabelrotation: float | None=None, latlabelrotation: float | None=None) -> None: + """Apply changes to the basemap axes.""" + ... + + def _update_major_gridlines(self, longrid: bool | None=None, latgrid: bool | None=None, lonarray: Sequence[bool | None] | None=None, latarray: Sequence[bool | None] | None=None, loninline: bool | None=None, latinline: bool | None=None, rotatelabels: bool | None=None, lonlabelrotation: float | None=None, latlabelrotation: float | None=None, labelpad: Any=None, nsteps: int | None=None) -> None: + """Update major gridlines.""" + ... + + def _update_minor_gridlines(self, longrid: bool | None=None, latgrid: bool | None=None, nsteps: int | None=None) -> None: + """Update minor gridlines.""" + ... + +def _is_platecarree_crs(transform: Any) -> bool: + """Return whether `transform` represents plain longitude-latitude coordinates.""" + ... + +def _choropleth_close_path(vertices: Any) -> mpath.Path | None: + """Convert a single polygon ring into a closed path.""" + ... + +def _choropleth_iter_rings(geometry: Any) -> Iterator[Any]: + """Yield polygon rings from shapely-like polygon geometries.""" + ... + +def _choropleth_project_vertices(ax: GeoAxes, vertices: Any, *, transform: Any=None) -> np.ndarray: + """Project polygon-ring vertices into the target map coordinate system.""" + ... + +def _choropleth_geometry_path(ax: GeoAxes, geometry: Any, *, transform: Any=None) -> mpath.Path | None: + """Convert a polygon geometry to a projected matplotlib path.""" + ... + +def _choropleth_country_inputs(geometries: Any, values: Any, *, transform: Any=None, resolution: str='110m', include_far: bool=False) -> tuple[list[Any], Any, Any]: + """Resolve country identifiers into polygon geometries.""" + ... + +def _choropleth_edge_collection_kw(kw: Mapping[str, Any], *, zorder: float, explicit_zorder: bool=False) -> dict[str, Any] | None: + """Return edge-only collection settings when polygon outlines should overlay features.""" + ... + +def _is_rectilinear_projection(ax: Any) -> bool: + """Check if the axis has a flat projection (works with Cartopy).""" + ... diff --git a/ultraplot/axes/plot.py b/ultraplot/axes/plot.py index acb4a7a63..06c5ee361 100644 --- a/ultraplot/axes/plot.py +++ b/ultraplot/axes/plot.py @@ -2486,6 +2486,7 @@ def ribbon( topic_label_box=topic_label_box, ) + @docstring._snippet_manager def circos( self, sectors: Mapping[str, Any], @@ -2741,6 +2742,7 @@ def radar(self, *args, **kwargs): """ return self.radar_chart(*args, **kwargs) + @docstring._snippet_manager def circos( self, sectors: Mapping[str, Any], diff --git a/ultraplot/axes/plot.pyi b/ultraplot/axes/plot.pyi new file mode 100644 index 000000000..da28483aa --- /dev/null +++ b/ultraplot/axes/plot.pyi @@ -0,0 +1,9628 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +The second-level axes subclass used for all ultraplot figures. +Implements plotting method overrides. +""" +from _typeshed import Incomplete +import contextlib +import inspect +import itertools +import re +import sys +from collections.abc import Callable, Iterable +from numbers import Integral, Number +from typing import Any, Iterable, Mapping, Optional, Sequence, TypeAlias, Union +import matplotlib as mpl +import matplotlib.artist as martist +import matplotlib.axes as maxes +import matplotlib.cbook as cbook +import matplotlib.cm as mcm +import matplotlib.collections as mcollections +import matplotlib.colors as mcolors +import matplotlib.container as mcontainer +import matplotlib.contour as mcontour +import matplotlib.image as mimage +import matplotlib.lines as mlines +import matplotlib.patches as mpatches +import matplotlib.pyplot as mplt +import matplotlib.ticker as mticker +import numpy as np +import numpy.ma as ma +from numpy.typing import ArrayLike +from packaging import version +from .. import colors as pcolors +from .. import constructor, utils +from ..config import rc +from ..internals import _get_aliases, _not_none, _pop_kwargs, _pop_params, _pop_props, _version_mpl, context, docstring, guides, ic, inputs, warnings +from ..utils import units +from . import base +try: + from cartopy.crs import PlateCarree +except ModuleNotFoundError: + PlateCarree = object +__all__ = ['PlotAxes'] +EDGEWIDTH = 0.3 +DataInput: TypeAlias = ArrayLike +ColorTupleRGB: TypeAlias = tuple[float, float, float] +ColorTupleRGBA: TypeAlias = tuple[float, float, float, float] +ColorInput: TypeAlias = DataInput | str | ColorTupleRGB | ColorTupleRGBA | None +ParsedColor: TypeAlias = DataInput | list[str] | str | None +_args_1d_docstring = ... +_args_1d_multi_docstring = ... +_args_2d_docstring = ... +_args_1d_shared_docstring = ... +_args_2d_shared_docstring = ... +_curved_quiver_docstring = ... +_sankey_docstring = ... +_chord_docstring = ... +_radar_docstring = ... +_circos_docstring = ... +_phylogeny_docstring = ... +_circos_bed_docstring = ... +_guide_docstring = ... +_inbounds_docstring = ... +_error_means_docstring = ... +_error_bars_docstring = ... +_error_shading_docstring = ... +_cycle_docstring = ... +_cmap_norm_docstring = ... +_log_doc = '\nPlot {kind}\n\nUltraPlot is optimized for visualizing logarithmic scales by default. For cases with large differences in magnitude,\nwe recommend setting `rc["formatter.log"] = True` to enhance axis label formatting.\n{matplotlib_doc}\n' +_vmin_vmax_docstring = ... +_manual_levels_docstring = ... +_auto_levels_docstring = ... +_label_docstring = ... +_labels_1d_docstring = ... +_labels_2d_docstring = ... +_negpos_docstring = ... +_plot_docstring = ... +_step_docstring = ... +_stem_docstring = ... +_lines_docstring = ... +_parametric_docstring = ... +_scatter_docstring = ... +_beeswarm_docstring = ... +_bar_docstring = ... +_lollipop_docstring = ... +_fill_docstring = ... +_boxplot_docstring = ... +_violinplot_docstring = ... +_ridgeline_docstring = ... +_hist_docstring = ... +_weights_docstring = ... +_hist2d_docstring = ... +_bins_docstring = ... +_pie_docstring = ... +_contour_docstring = ... +_graph_docstring = ... +_pcolor_docstring = ... +_heatmap_descrip = '\ngrid boxes with formatting suitable for heatmaps. Ensures square grid\nboxes, adds major ticks to the center of each grid box, disables minor\nticks and gridlines, and sets :rcraw:`cmap.discrete` to ``False`` by default\n'.strip() +_heatmap_aspect = "\naspect : {'equal', 'auto'} or float, default: :rc:`image.aspet`\n Modify the axes aspect ratio. The aspect ratio is of particular relevance for\n heatmaps since it may lead to non-square grid boxes. This parameter is a shortcut\n for calling `~matplotlib.axes.set_aspect`. The options are as follows:\n\n * Number: The data aspect ratio.\n * ``'equal'``: A data aspect ratio of 1.\n * ``'auto'``: Allows the data aspect ratio to change depending on\n the layout. In general this results in non-square grid boxes.\n".rstrip() +_show_docstring = ... +_flow_docstring = ... + +def _get_vert(vert: Incomplete=None, orientation: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Get the orientation specified as either `vert` or `orientation`. This is +used internally by various helper functions.""" + ... + +def _parse_vert(vert: Incomplete=None, orientation: Incomplete=None, default_vert: Incomplete=None, default_orientation: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Interpret both 'vert' and 'orientation' and add to outgoing keyword args +if a default is provided.""" + ... + +def _parse_kde_kw(kde_kw: Incomplete=None, *, points: Incomplete=None, weights: Incomplete=None) -> Incomplete: + """Split `kde_kw` into the keyword arguments that control the kernel density +estimate, i.e. those accepted by `~ultraplot.internals.inputs._dist_kde`, and +the remaining line properties meant for `~matplotlib.axes.Axes.plot`. The +`points` and `weights` arguments supply defaults from the parent command.""" + ... + +def _get_hist_colors(res: Incomplete, n: Incomplete) -> Incomplete: + """Return one color per column of a histogram drawn by +`~matplotlib.axes.Axes.hist`, so that overlays can be colored to match.""" + ... + +class PlotAxes(base.Axes): + """ + The second lowest-level `~matplotlib.axes.Axes` subclass used by ultraplot. + Implements all plotting overrides. + """ + + def curved_quiver(self, x: np.ndarray, y: np.ndarray, u: np.ndarray, v: np.ndarray, linewidth: Optional[float]=None, color: Optional[Union[str, Any]]=None, cmap: Optional[Any]=None, norm: Optional[Any]=None, arrowsize: Optional[float]=None, arrowstyle: Optional[str]=None, transform: Optional[Any]=None, zorder: Optional[int]=None, start_points: Optional[np.ndarray]=None, scale: Optional[float]=None, grains: Optional[int]=None, density: Optional[int]=None, arrow_at_end: Optional[bool]=None, colorbar: Optional[str]=None, colorbar_kw: Optional[dict[str, Any]]=None) -> Incomplete: + """Draws curved vector field arrows (streamlines with arrows) for 2D vector fields. + +Parameters +---------- +x, y : 1D or 2D arrays + Grid coordinates. +u, v : 2D arrays + Vector components. +color : color or 2D array, optional + Streamline color. +density : float or (float, float), optional + Controls the closeness of streamlines. +grains : int or (int, int), optional + Number of seed points in x and y. +linewidth : float or 2D array, optional + Width of streamlines. +cmap, norm : optional + Colormap and normalization for array colors. +colorbar, colorbar_kw : optional + Add a colorbar for array-valued streamline colors. +arrowsize : float, optional + Arrow size scaling. +arrowstyle : str, optional + Arrow style specification. +transform : optional + Matplotlib transform. +zorder : float, optional + Z-order for lines/arrows. +start_points : (N, 2) array, optional + Starting points for streamlines. + +Returns +------- +CurvedQuiverSet + Container with attributes: + - lines: LineCollection of streamlines + - arrows: PatchCollection of arrows + +Notes +----- +The implementation of this function is based on the `dfm_tools` repository. +Original file: https://github.com/Deltares/dfm_tools/blob/829e76f48ebc42460aae118cc190147a595a5f26/dfm_tools/modplot.py""" + ... + + def sankey(self, flows: Any, labels: Optional[Sequence[str]]=None, orientations: Optional[Sequence[int]]=None, pathlengths: Optional[Union[float, Sequence[float]]]=None, trunklength: Optional[float]=None, patchlabel: Optional[str]=None, *, nodes: Any=None, links: Any=None, node_kw: Optional[Mapping[str, Any]]=None, flow_kw: Optional[Mapping[str, Any]]=None, label_kw: Optional[Mapping[str, Any]]=None, node_label_kw: Optional[Mapping[str, Any]]=None, flow_label_kw: Optional[Mapping[str, Any]]=None, node_label_box: Optional[Union[bool, Mapping[str, Any]]]=None, style: Optional[str]=None, node_order: Optional[Sequence[Any]]=None, layer_order: Optional[Sequence[int]]=None, group_cycle: Optional[Sequence[Any]]=None, flow_other: Optional[float]=None, other_label: Optional[str]=None, value_format: Optional[Union[str, Callable[[float], str]]]=None, node_label_outside: Optional[Union[bool, str]]=None, node_label_offset: Optional[float]=None, flow_sort: Optional[bool]=None, flow_label_pos: Optional[float]=None, node_labels: Optional[bool]=None, flow_labels: Optional[bool]=None, align: Optional[str]=None, layers: Optional[Mapping[Any, int]]=None, scale: Optional[float]=None, unit: Optional[str]=None, format: Optional[str]=None, gap: Optional[float]=None, radius: Optional[float]=None, shoulder: Optional[float]=None, offset: Optional[float]=None, head_angle: Optional[float]=None, margin: Optional[float]=None, tolerance: Optional[float]=None, prior: Optional[int]=None, connect: Optional[tuple[int, int]]=None, rotation: Optional[float]=None, **kwargs: Any) -> Any: + """Draw a Sankey diagram. + +Parameters +---------- +flows : sequence of float or flow tuples + If a numeric sequence, use Matplotlib's Sankey implementation. + Otherwise, expect flow tuples or dicts describing (source, target, value). +nodes : sequence or dict, optional + Node identifiers or dicts with ``id``/``label``/``color`` keys. If omitted, + nodes are inferred from flow sources/targets. +labels : sequence of str, optional + Labels for each flow in Matplotlib's Sankey mode. +orientations : sequence of int, optional + Flow orientations (-1: down, 0: right, 1: up) for Matplotlib's Sankey. +pathlengths : float or sequence of float, optional + Path lengths for each flow in Matplotlib's Sankey. Defaults to + :rc:`sankey.pathlengths` when omitted. +trunklength : float, optional + Length of the trunk between the input and output flows. Defaults to + :rc:`sankey.trunklength` when omitted. +patchlabel : str, optional + Label for the main patch in Matplotlib's Sankey mode. Defaults to + :rc:`sankey.pathlabel` when omitted. +scale, unit, format, gap, radius, shoulder, offset, head_angle, margin, tolerance : optional + Passed to `matplotlib.sankey.Sankey`. +prior : int, optional + Index of a prior diagram to connect to. +connect : (int, int), optional + Flow indices for the prior and current diagram connection. Defaults to + :rc:`sankey.connect` when omitted. +rotation : float, optional + Rotation angle in degrees. Defaults to :rc:`sankey.rotation` when omitted. +node_kw, flow_kw, label_kw : dict-like, optional + Style dictionaries for the layered Sankey renderer. +node_label_kw, flow_label_kw : dict-like, optional + Label style dictionaries for node and flow labels in layered mode. +node_label_box : bool or dict-like, optional + If ``True``, draw a rounded box behind node labels. If dict-like, used as + the ``bbox`` argument for node label styling. +style : {'budget', 'pastel', 'mono'}, optional + Built-in styling presets for layered mode. +node_order : sequence, optional + Explicit node ordering for layered mode. +layer_order : sequence, optional + Explicit layer ordering for layered mode. +group_cycle : sequence, optional + Cycle for flow group colors (defaults to flow cycle). +flow_other : float, optional + Aggregate flows below this threshold into a single ``other_label``. +other_label : str, optional + Label for the aggregated flow target. Defaults to :rc:`sankey.other_label` + when omitted. +value_format : str or callable, optional + Formatter for flow labels when not explicitly provided. +node_label_outside : {'auto', True, False}, optional + Place node labels outside narrow nodes. Defaults to + :rc:`sankey.node_label_outside` when omitted. +node_label_offset : float, optional + Offset for outside node labels (axes-relative units). Defaults to + :rc:`sankey.node_label_offset` when omitted. +flow_sort : bool, optional + Whether to sort flows by target position to reduce crossings. Defaults to + :rc:`sankey.flow_sort` when omitted. +flow_label_pos : float, optional + Horizontal placement for single flow labels (0 to 1 along the ribbon). + Defaults to :rc:`sankey.flow_label_pos` when omitted. + When flow labels overlap, positions are redistributed between 0.25 and 0.75. +node_labels, flow_labels : bool, optional + Whether to draw node or flow labels in layered mode. Defaults to + :rc:`sankey.node_labels` and :rc:`sankey.flow_labels` when omitted. +align : {'center', 'top', 'bottom'}, optional + Vertical alignment for nodes within each layer in layered mode. Defaults to + :rc:`sankey.align` when omitted. +layers : dict-like, optional + Manual layer assignments for nodes in layered mode. +**kwargs + Patch properties passed to `matplotlib.sankey.Sankey.add` in Matplotlib mode. + +Layered defaults +---------------- +Layered mode uses :rc:`sankey.nodepad`, :rc:`sankey.nodewidth`, +:rc:`sankey.margin`, :rc:`sankey.flow.alpha`, :rc:`sankey.flow.curvature`, +and :rc:`sankey.node.facecolor` when not set explicitly. + +Returns +------- +matplotlib.sankey.Sankey or list or SankeyDiagram + The Sankey diagram instance, or a list for multi-diagram usage. For layered + mode, returns a `~ultraplot.axes.plot_types.sankey.SankeyDiagram`.""" + ... + + def ribbon(self, data: Any, *, id_col: str='id', period_col: str='period', topic_col: str='topic', value_col: str | None=None, period_order: Sequence[Any] | None=None, topic_order: Sequence[Any] | None=None, group_map: Mapping[Any, Any] | None=None, group_order: Sequence[Any] | None=None, group_colors: Mapping[Any, Any] | None=None, xmargin: Optional[float]=None, ymargin: Optional[float]=None, row_height_ratio: Optional[float]=None, node_width: Optional[float]=None, flow_curvature: Optional[float]=None, flow_alpha: Optional[float]=None, show_topic_labels: Optional[bool]=None, topic_label_offset: Optional[float]=None, topic_label_size: Optional[float]=None, topic_label_box: Optional[bool]=None) -> dict[str, Any]: + """Draw a fixed-row, top-aligned ribbon flow diagram from long-form records. + +Parameters +---------- +data : pandas.DataFrame or mapping-like + Long-form records with entity id, period, and topic columns. +id_col, period_col, topic_col : str, optional + Column names for entity id, period, and topic. +value_col : str, optional + Optional weight column. If omitted, each record is weighted as 1. +period_order, topic_order : sequence, optional + Explicit ordering for periods and topic rows. +group_map : mapping, optional + Topic-to-group mapping used for grouped ordering and colors. +group_order : sequence, optional + Group ordering for row arrangement. +group_colors : mapping, optional + Group-to-color mapping. Missing groups use the patch color cycle. +xmargin, ymargin : float, optional + Plot-space margins in normalized axes coordinates. +row_height_ratio : float, optional + Scale factor controlling row occupancy by nodes/flows. +node_width : float, optional + Node column width in normalized axes coordinates. +flow_curvature : float, optional + Bezier curvature for ribbons. +flow_alpha : float, optional + Ribbon alpha. +show_topic_labels : bool, optional + Whether to draw topic labels on the right. +topic_label_offset : float, optional + Offset for right-side topic labels. +topic_label_size : float, optional + Topic label font size. +topic_label_box : bool, optional + Whether to draw white backing boxes behind topic labels. + +Returns +------- +dict + Mapping of created artists and resolved orders.""" + ... + + def circos(self, sectors: Mapping[str, Any], *, start: float=0, end: float=360, space: float | Sequence[float]=0, endspace: bool=True, sector2clockwise: Mapping[str, bool] | None=None, show_axis_for_debug: bool=False, plot: bool=False, tooltip: bool=False) -> Incomplete: + """Create a Circos instance using pyCirclize. + +Parameters +---------- +sectors : mapping + Sector name and size (or range) mapping. +start, end : float, optional + Plot start and end degrees (-360 <= start < end <= 360). +space : float or sequence of float, optional + Space degrees between sectors. +endspace : bool, optional + If True, insert space after the final sector. +sector2clockwise : dict, optional + Override clockwise settings per sector. +show_axis_for_debug : bool, optional + Show the polar axis for debug layout. +plot : bool, optional + If True, immediately render the circos figure on this axes. +tooltip : bool, optional + Enable interactive tooltips (requires ipympl). + +Returns +------- +pycirclize.Circos + The underlying Circos instance.""" + ... + + def phylogeny(self, tree_data: Any, *, start: Optional[float]=None, end: Optional[float]=None, r_lim: Optional[tuple[float, float]]=None, format: Optional[str]=None, outer: Optional[bool]=None, align_leaf_label: Optional[bool]=None, ignore_branch_length: Optional[bool]=None, leaf_label_size: Optional[float]=None, leaf_label_rmargin: Optional[float]=None, reverse: Optional[bool]=None, ladderize: Optional[bool]=None, line_kw: Optional[Mapping[str, Any]]=None, label_formatter: Optional[Callable[[str], str]]=None, align_line_kw: Optional[Mapping[str, Any]]=None, tooltip: bool=False) -> Incomplete: + """Draw a phylogenetic tree using pyCirclize. + +Parameters +---------- +tree_data : str, Path, or Tree + Tree data (file, URL, Tree object, or tree string). +start, end : float, optional + Plot start and end degrees (-360 <= start < end <= 360). +r_lim : 2-tuple of float, optional + Tree track radius limits (0 to 100). +format : str, optional + Tree format (`newick`, `phyloxml`, `nexus`, `nexml`, `cdao`). +outer : bool, optional + If True, plot tree on the outer side. +align_leaf_label : bool, optional + If True, align leaf labels. +ignore_branch_length : bool, optional + Ignore branch lengths when plotting. +leaf_label_size : float, optional + Leaf label size. +leaf_label_rmargin : float, optional + Leaf label radius margin. +reverse : bool, optional + Reverse tree direction. +ladderize : bool, optional + Ladderize tree. +line_kw, align_line_kw : dict-like, optional + Keyword arguments for tree line styling. +label_formatter : callable, optional + Formatter for leaf labels. +tooltip : bool, optional + Enable interactive tooltips (requires ipympl). + +Returns +------- +pycirclize.Circos, pycirclize.TreeViz + The Circos instance and TreeViz helper.""" + ... + + def circos_bed(self, bed_file: Any, *, start: float=0, end: float=360, space: float | Sequence[float]=0, endspace: bool=True, sector2clockwise: Mapping[str, bool] | None=None, plot: bool=False, tooltip: bool=False) -> Incomplete: + """Create a Circos instance from a BED file using pyCirclize. + +Parameters +---------- +bed_file : str or Path + BED file describing chromosome ranges. +start, end : float, optional + Plot start and end degrees (-360 <= start < end <= 360). +space : float or sequence of float, optional + Space degrees between sectors. +endspace : bool, optional + If True, insert space after the final sector. +sector2clockwise : dict, optional + Override clockwise settings per sector. +plot : bool, optional + If True, immediately render the circos figure on this axes. +tooltip : bool, optional + Enable interactive tooltips (requires ipympl). + +Returns +------- +pycirclize.Circos + The underlying Circos instance.""" + ... + + def bed(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Alias for `~PlotAxes.circos_bed`.""" + ... + + def chord_diagram(self, matrix: Any, *, start: Optional[float]=None, end: Optional[float]=None, space: Optional[Union[float, Sequence[float]]]=None, endspace: Optional[bool]=None, r_lim: Optional[tuple[float, float]]=None, cmap: Any=None, link_cmap: Optional[list[tuple[str, str, str]]]=None, ticks_interval: Optional[int]=None, order: Optional[Union[str, list[str]]]=None, label_kw: Optional[Mapping[str, Any]]=None, ticks_kw: Optional[Mapping[str, Any]]=None, link_kw: Optional[Mapping[str, Any]]=None, link_kw_handler: Optional[Callable[[str, str], Optional[Mapping[str, Any]]]]=None, tooltip: bool=False) -> Incomplete: + """Draw a chord diagram using pyCirclize. + +Parameters +---------- +matrix : str, Path, pandas.DataFrame, or Matrix + Input matrix for the chord diagram. +start, end : float, optional + Plot start and end degrees (-360 <= start < end <= 360). +space : float or sequence of float, optional + Space degrees between sectors. +endspace : bool, optional + If True, insert space after the final sector. +r_lim : 2-tuple of float, optional + Outer track radius limits (0 to 100). +cmap : str or dict, optional + Colormap name or name-to-color mapping for sectors and links. If omitted, + UltraPlot's color cycle is used. +link_cmap : list of (from, to, color), optional + Override link colors. +ticks_interval : int, optional + Tick interval for sector tracks. If None, no ticks are shown. +order : {'asc', 'desc'} or list, optional + Node ordering strategy or explicit node order. +label_kw, ticks_kw, link_kw : dict-like, optional + Keyword arguments passed to pyCirclize for labels, ticks, and links. +link_kw_handler : callable, optional + Callback to customize per-link keyword arguments. +tooltip : bool, optional + Enable interactive tooltips (requires ipympl). + +Returns +------- +pycirclize.Circos + The underlying Circos instance.""" + ... + + def chord(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Alias for `~PlotAxes.chord_diagram`.""" + ... + + def radar_chart(self, table: Any, *, r_lim: Optional[tuple[float, float]]=None, vmin: Optional[float]=None, vmax: Optional[float]=None, fill: Optional[bool]=None, marker_size: Optional[int]=None, bg_color: Optional[str]=None, circular: Optional[bool]=None, cmap: Any=None, show_grid_label: Optional[bool]=None, grid_interval_ratio: Optional[float]=None, grid_line_kw: Optional[Mapping[str, Any]]=None, grid_label_kw: Optional[Mapping[str, Any]]=None, grid_label_formatter: Optional[Callable[[float], str]]=None, label_kw_handler: Optional[Callable[[str], Mapping[str, Any]]]=None, line_kw_handler: Optional[Callable[[str], Mapping[str, Any]]]=None, marker_kw_handler: Optional[Callable[[str], Mapping[str, Any]]]=None) -> Incomplete: + """Draw a radar chart using pyCirclize. + +Parameters +---------- +table : str, Path, pandas.DataFrame, or RadarTable + Input table for the radar chart. +r_lim : 2-tuple of float, optional + Radar chart radius limits (0 to 100). +vmin, vmax : float, optional + Value range for the radar chart. +fill : bool, optional + Whether to fill the radar polygons. +marker_size : int, optional + Marker size for radar points. +bg_color : color-spec or None, optional + Background fill color. +circular : bool, optional + Whether to draw circular grid lines. +cmap : str or dict, optional + Colormap name or row-name-to-color mapping. If omitted, UltraPlot's + color cycle is used. +show_grid_label : bool, optional + Whether to show radial grid labels. +grid_interval_ratio : float or None, optional + Grid interval ratio (0 to 1). +grid_line_kw, grid_label_kw : dict-like, optional + Keyword arguments passed to pyCirclize for grid lines and labels. +grid_label_formatter : callable, optional + Formatter for grid label values. +label_kw_handler, line_kw_handler, marker_kw_handler : callable, optional + Per-series styling callbacks passed to pyCirclize. + +Returns +------- +pycirclize.Circos + The underlying Circos instance.""" + ... + + def radar(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Alias for `~PlotAxes.radar_chart`.""" + ... + + def circos(self, sectors: Mapping[str, Any], *, start: float=0, end: float=360, space: float | Sequence[float]=0, endspace: bool=True, sector2clockwise: Mapping[str, bool] | None=None, show_axis_for_debug: bool=False, plot: bool=False, tooltip: bool=False) -> Incomplete: + """Create a Circos instance using pyCirclize. + +Parameters +---------- +sectors : mapping + Sector name and size (or range) mapping. +start, end : float, optional + Plot start and end degrees (-360 <= start < end <= 360). +space : float or sequence of float, optional + Space degrees between sectors. +endspace : bool, optional + If True, insert space after the final sector. +sector2clockwise : dict, optional + Override clockwise settings per sector. +show_axis_for_debug : bool, optional + Show the polar axis for debug layout. +plot : bool, optional + If True, immediately render the circos figure on this axes. +tooltip : bool, optional + Enable interactive tooltips (requires ipympl). + +Returns +------- +pycirclize.Circos + The underlying Circos instance.""" + ... + + def phylogeny(self, tree_data: Any, *, start: Optional[float]=None, end: Optional[float]=None, r_lim: Optional[tuple[float, float]]=None, format: Optional[str]=None, outer: Optional[bool]=None, align_leaf_label: Optional[bool]=None, ignore_branch_length: Optional[bool]=None, leaf_label_size: Optional[float]=None, leaf_label_rmargin: Optional[float]=None, reverse: Optional[bool]=None, ladderize: Optional[bool]=None, line_kw: Optional[Mapping[str, Any]]=None, label_formatter: Optional[Callable[[str], str]]=None, align_line_kw: Optional[Mapping[str, Any]]=None, tooltip: bool=False) -> Incomplete: + """Draw a phylogenetic tree using pyCirclize. + +Parameters +---------- +tree_data : str, Path, or Tree + Tree data (file, URL, Tree object, or tree string). +start, end : float, optional + Plot start and end degrees (-360 <= start < end <= 360). +r_lim : 2-tuple of float, optional + Tree track radius limits (0 to 100). +format : str, optional + Tree format (`newick`, `phyloxml`, `nexus`, `nexml`, `cdao`). +outer : bool, optional + If True, plot tree on the outer side. +align_leaf_label : bool, optional + If True, align leaf labels. +ignore_branch_length : bool, optional + Ignore branch lengths when plotting. +leaf_label_size : float, optional + Leaf label size. +leaf_label_rmargin : float, optional + Leaf label radius margin. +reverse : bool, optional + Reverse tree direction. +ladderize : bool, optional + Ladderize tree. +line_kw, align_line_kw : dict-like, optional + Keyword arguments for tree line styling. +label_formatter : callable, optional + Formatter for leaf labels. +tooltip : bool, optional + Enable interactive tooltips (requires ipympl). + +Returns +------- +pycirclize.Circos, pycirclize.TreeViz + The Circos instance and TreeViz helper.""" + ... + + def circos_bed(self, bed_file: Any, *, start: float=0, end: float=360, space: float | Sequence[float]=0, endspace: bool=True, sector2clockwise: Mapping[str, bool] | None=None, plot: bool=False, tooltip: bool=False) -> Incomplete: + """Create a Circos instance from a BED file using pyCirclize. + +Parameters +---------- +bed_file : str or Path + BED file describing chromosome ranges. +start, end : float, optional + Plot start and end degrees (-360 <= start < end <= 360). +space : float or sequence of float, optional + Space degrees between sectors. +endspace : bool, optional + If True, insert space after the final sector. +sector2clockwise : dict, optional + Override clockwise settings per sector. +plot : bool, optional + If True, immediately render the circos figure on this axes. +tooltip : bool, optional + Enable interactive tooltips (requires ipympl). + +Returns +------- +pycirclize.Circos + The underlying Circos instance.""" + ... + + def bed(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Alias for `~PlotAxes.circos_bed`.""" + ... + + def chord_diagram(self, matrix: Any, *, start: Optional[float]=None, end: Optional[float]=None, space: Optional[Union[float, Sequence[float]]]=None, endspace: Optional[bool]=None, r_lim: Optional[tuple[float, float]]=None, cmap: Any=None, link_cmap: Optional[list[tuple[str, str, str]]]=None, ticks_interval: Optional[int]=None, order: Optional[Union[str, list[str]]]=None, label_kw: Optional[Mapping[str, Any]]=None, ticks_kw: Optional[Mapping[str, Any]]=None, link_kw: Optional[Mapping[str, Any]]=None, link_kw_handler: Optional[Callable[[str, str], Optional[Mapping[str, Any]]]]=None, tooltip: bool=False) -> Incomplete: + """Draw a chord diagram using pyCirclize. + +Parameters +---------- +matrix : str, Path, pandas.DataFrame, or Matrix + Input matrix for the chord diagram. +start, end : float, optional + Plot start and end degrees (-360 <= start < end <= 360). +space : float or sequence of float, optional + Space degrees between sectors. +endspace : bool, optional + If True, insert space after the final sector. +r_lim : 2-tuple of float, optional + Outer track radius limits (0 to 100). +cmap : str or dict, optional + Colormap name or name-to-color mapping for sectors and links. If omitted, + UltraPlot's color cycle is used. +link_cmap : list of (from, to, color), optional + Override link colors. +ticks_interval : int, optional + Tick interval for sector tracks. If None, no ticks are shown. +order : {'asc', 'desc'} or list, optional + Node ordering strategy or explicit node order. +label_kw, ticks_kw, link_kw : dict-like, optional + Keyword arguments passed to pyCirclize for labels, ticks, and links. +link_kw_handler : callable, optional + Callback to customize per-link keyword arguments. +tooltip : bool, optional + Enable interactive tooltips (requires ipympl). + +Returns +------- +pycirclize.Circos + The underlying Circos instance.""" + ... + + def chord(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Alias for `~PlotAxes.chord_diagram`.""" + ... + + def radar_chart(self, table: Any, *, r_lim: Optional[tuple[float, float]]=None, vmin: Optional[float]=None, vmax: Optional[float]=None, fill: Optional[bool]=None, marker_size: Optional[int]=None, bg_color: Optional[str]=None, circular: Optional[bool]=None, cmap: Any=None, show_grid_label: Optional[bool]=None, grid_interval_ratio: Optional[float]=None, grid_line_kw: Optional[Mapping[str, Any]]=None, grid_label_kw: Optional[Mapping[str, Any]]=None, grid_label_formatter: Optional[Callable[[float], str]]=None, label_kw_handler: Optional[Callable[[str], Mapping[str, Any]]]=None, line_kw_handler: Optional[Callable[[str], Mapping[str, Any]]]=None, marker_kw_handler: Optional[Callable[[str], Mapping[str, Any]]]=None) -> Incomplete: + """Draw a radar chart using pyCirclize. + +Parameters +---------- +table : str, Path, pandas.DataFrame, or RadarTable + Input table for the radar chart. +r_lim : 2-tuple of float, optional + Radar chart radius limits (0 to 100). +vmin, vmax : float, optional + Value range for the radar chart. +fill : bool, optional + Whether to fill the radar polygons. +marker_size : int, optional + Marker size for radar points. +bg_color : color-spec or None, optional + Background fill color. +circular : bool, optional + Whether to draw circular grid lines. +cmap : str or dict, optional + Colormap name or row-name-to-color mapping. If omitted, UltraPlot's + color cycle is used. +show_grid_label : bool, optional + Whether to show radial grid labels. +grid_interval_ratio : float or None, optional + Grid interval ratio (0 to 1). +grid_line_kw, grid_label_kw : dict-like, optional + Keyword arguments passed to pyCirclize for grid lines and labels. +grid_label_formatter : callable, optional + Formatter for grid label values. +label_kw_handler, line_kw_handler, marker_kw_handler : callable, optional + Per-series styling callbacks passed to pyCirclize. + +Returns +------- +pycirclize.Circos + The underlying Circos instance.""" + ... + + def radar(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Alias for `~PlotAxes.radar_chart`.""" + ... + + def _call_native(self, name: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Call the plotting method and redirect internal calls to native methods.""" + ... + + def _call_negpos(self, name: Incomplete, x: Incomplete, *ys: Incomplete, negcolor: Incomplete=None, poscolor: Incomplete=None, colorkey: Incomplete='facecolor', use_where: Incomplete=False, use_zero: Incomplete=False, **kwargs: Incomplete) -> Incomplete: + """Call the plotting method separately for "negative" and "positive" data.""" + ... + + def _add_auto_labels(self, obj: Incomplete, cobj: Incomplete=None, labels: Incomplete=False, labels_kw: Incomplete=None, fmt: Incomplete=None, formatter: Incomplete=None, formatter_kw: Incomplete=None, precision: Incomplete=None) -> None: + """Add number labels. Default formatter is `~ultraplot.ticker.SimpleFormatter` +with a default maximum precision of ``3`` decimal places.""" + ... + + def _add_quadmesh_labels(self, obj: Incomplete, fmt: Incomplete, *, c: Incomplete=None, color: Incomplete=None, colors: Incomplete=None, size: Incomplete=None, fontsize: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Add labels to QuadMesh cells with support for shade-dependent text colors. +Values are inferred from the unnormalized mesh cell color.""" + ... + + def _add_collection_labels(self, obj: Incomplete, fmt: Incomplete, *, c: Incomplete=None, color: Incomplete=None, colors: Incomplete=None, size: Incomplete=None, fontsize: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Add labels to pcolor boxes with support for shade-dependent text colors. +Values are inferred from the unnormalized grid box color.""" + ... + + def _add_contour_labels(self, obj: Incomplete, cobj: Incomplete, fmt: Incomplete, *, c: Incomplete=None, color: Incomplete=None, colors: Incomplete=None, size: Incomplete=None, fontsize: Incomplete=None, inline_spacing: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Add labels to contours with support for shade-dependent filled contour labels. +Text color is inferred from filled contour object and labels are always drawn +on unfilled contour object (otherwise errors crop up).""" + ... + + def _add_error_bars(self, x: Incomplete, y: Incomplete, *_: Incomplete, distribution: Incomplete=None, default_barstds: Incomplete=False, default_boxstds: Incomplete=False, default_barpctiles: Incomplete=False, default_boxpctiles: Incomplete=False, default_marker: Incomplete=False, bars: Incomplete=None, boxes: Incomplete=None, barstd: Incomplete=None, barstds: Incomplete=None, barpctile: Incomplete=None, barpctiles: Incomplete=None, bardata: Incomplete=None, boxstd: Incomplete=None, boxstds: Incomplete=None, boxpctile: Incomplete=None, boxpctiles: Incomplete=None, boxdata: Incomplete=None, capsize: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Add up to 2 error indicators: thick "boxes" and thin "bars". The ``default`` +keywords toggle default range indicators when distributions are passed.""" + ... + + def _add_error_shading(self, x: Incomplete, y: Incomplete, *_: Incomplete, distribution: Incomplete=None, color_key: Incomplete='color', shade: Incomplete=None, shadestd: Incomplete=None, shadestds: Incomplete=None, shadepctile: Incomplete=None, shadepctiles: Incomplete=None, shadedata: Incomplete=None, fade: Incomplete=None, fadestd: Incomplete=None, fadestds: Incomplete=None, fadepctile: Incomplete=None, fadepctiles: Incomplete=None, fadedata: Incomplete=None, shadelabel: Incomplete=False, fadelabel: Incomplete=False, **kwargs: Incomplete) -> Incomplete: + """Add up to 2 error indicators: more opaque "shading" and less opaque "fading".""" + ... + + def _fix_contour_edges(self, method: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Fix the filled contour edges by secretly adding solid contours with +the same input data.""" + ... + + def _fix_sticky_edges(self, objs: Incomplete, axis: Incomplete, *args: Incomplete, only: Incomplete=None) -> None: + """Fix sticky edges for the input artists using the minimum and maximum of the +input coordinates. This is used to copy `bar` behavior to `area` and `lines`.""" + ... + + @staticmethod + def _fix_patch_edges(obj: Incomplete, edgefix: Incomplete=None, default_linewidth: float | None=None, **kwargs: Incomplete) -> None: + """Fix white lines between between filled patches and fix issues +with colormaps that are transparent. If keyword args passed by user +include explicit edge properties then we skip this step.""" + ... + + @contextlib.contextmanager + def _keep_grid_bools(self) -> Incomplete: + """Preserve the gridline booleans during the operation. This prevents `pcolor` +methods from disabling grids (mpl < 3.5) and emitting warnings (mpl >= 3.5).""" + ... + + def _inbounds_extent(self, *, inbounds: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Capture the `inbounds` keyword arg and return data limit +extents if it is ``True``. Otherwise return ``None``. When +``_inbounds_xylim`` gets ``None`` it will silently exit.""" + ... + + def _inbounds_vlim(self, x: Incomplete, y: Incomplete, z: Incomplete, *, to_centers: Incomplete=False) -> Incomplete: + """Restrict the sample data used for automatic `vmin` and `vmax` selection +based on the existing x and y axis limits.""" + ... + + def _inbounds_xylim(self, extents: Incomplete, x: Incomplete, y: Incomplete, **kwargs: Incomplete) -> None: + """Restrict the `dataLim` to exclude out-of-bounds data when x (y) limits +are fixed and we are determining default y (x) limits. This modifies +the mutable input `extents` to support iteration over columns.""" + ... + + def _add_kde_lines(self, xs: Incomplete, *, edges: Incomplete, colors: Incomplete, density: Incomplete=None, stack: Incomplete=False, orientation: Incomplete='vertical', points: Incomplete=None, bw_method: Incomplete=None, weights: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Add a gaussian kernel density estimate line for each column of `xs`, drawn +in `colors` and passing `**kwargs` to `~matplotlib.axes.Axes.plot`. + +Unless `density` is ``True`` each estimate is rescaled from a probability +density to the bin counts implied by the histogram bin `edges`. Stacked +histograms share a single evaluation grid so that the estimates accumulate +the way the bin counts do. Remaining arguments go to +`~ultraplot.internals.inputs._dist_kde`.""" + ... + + def _parse_1d_args(self, x: Incomplete, *ys: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Interpret positional arguments for all 1D plotting commands.""" + ... + + def _parse_1d_format(self, x: Incomplete, *ys: Incomplete, zerox: Incomplete=False, autox: Incomplete=True, autoy: Incomplete=True, autoformat: Incomplete=None, autoreverse: Incomplete=True, autolabels: Incomplete=True, autovalues: Incomplete=False, autoguide: Incomplete=True, label: Incomplete=None, labels: Incomplete=None, value: Incomplete=None, values: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Try to retrieve default coordinates from array-like objects and apply default +formatting. Also update the keyword arguments.""" + ... + + def _parse_2d_args(self, x: Incomplete, y: Incomplete, *zs: Incomplete, globe: Incomplete=False, edges: Incomplete=False, allow1d: Incomplete=False, transpose: Incomplete=None, order: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Interpret positional arguments for all 2D plotting commands.""" + ... + + def _parse_2d_format(self, x: Incomplete, y: Incomplete, *zs: Incomplete, autoformat: Incomplete=None, autoguide: Incomplete=True, autoreverse: Incomplete=True, **kwargs: Incomplete) -> Incomplete: + """Try to retrieve default coordinates from array-like objects and apply default +formatting. Also apply optional transpose and update the keyword arguments.""" + ... + + def _parse_color(self, x: DataInput, y: DataInput, c: ColorInput, *, apply_cycle: bool=True, infer_rgb: bool=False, force_cmap: bool=False, **kwargs: Any) -> tuple[ParsedColor, dict[str, Any]]: + """Parse either a colormap or color cycler. Colormap will be discrete and fade +to subwhite luminance by default. Returns a HEX string if needed so we don't +get ambiguous color warnings. Used with scatter, streamplot, quiver, barbs.""" + ... + + def _scatter_c_is_scalar_data(self, x: DataInput, y: DataInput, c: ColorInput) -> bool: + """Return whether scatter ``c=`` should be treated as scalar data. + +Matplotlib treats 1D numeric arrays matching the point count as values to +be colormapped, even though short float sequences can also look like an +RGBA tuple to ``is_color_like``. Preserve explicit RGB/RGBA arrays via the +existing ``N x 3``/``N x 4`` path and reserve this override for the 1D +numeric case only.""" + ... + + def _parse_cmap(self, *args: Incomplete, cmap: Incomplete=None, cmap_kw: Incomplete=None, c: Incomplete=None, color: Incomplete=None, colors: Incomplete=None, norm: Incomplete=None, norm_kw: Incomplete=None, extend: Incomplete=None, vmin: Incomplete=None, vmax: Incomplete=None, discrete: Incomplete=None, default_cmap: Incomplete=None, default_discrete: Incomplete=True, skip_autolev: Incomplete=False, min_levels: Incomplete=None, plot_lines: Incomplete=False, plot_contours: Incomplete=False, center_levels: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Parse colormap and normalizer arguments. + +Parameters +---------- +c, color, colors : sequence of color-spec, optional + Build a `DiscreteColormap` from the input color(s). +cmap, cmap_kw : optional + Colormap specs. +norm, norm_kw : optional + Normalize specs. +extend : optional + The colormap extend setting. +vmin, vmax : float, optional + The normalization range. +sequential, diverging, cyclic, qualitative : bool, optional + Toggle various colormap types. +discrete : bool, optional + Whether to apply `DiscreteNorm` to the colormap. +default_discrete : bool, optional + The default `discrete`. Depends on plotting method. +skip_autolev : bool, optional + Whether to skip automatic level generation. +min_levels : int, optional + The minimum number of valid levels. 1 for line contour plots 2 otherwise. +plot_lines : bool, optional + Whether these are lines. If so the default monochromatic luminance is 90. +plot_contours : bool, optional + Whether these are contours. If so then a discrete of `True` is required.""" + ... + + def _parse_cycle(self, ncycle: Incomplete=None, *, cycle: Incomplete=None, cycle_kw: Incomplete=None, cycle_manually: Incomplete=None, return_cycle: Incomplete=False, **kwargs: Incomplete) -> Incomplete: + """Parse property cycle-related arguments. + +Parameters +---------- +ncycle : int, optional + The number of samples to draw for the cycle. +cycle : cycle-spec, optional + The property cycle specifier. +cycle_kw : dict-like, optional + The property cycle keyword arguments +cycle_manually : dict-like, optional + Mapping of property cycle keys to plotting function keys. Used + to translate property cycle line properties to scatter properties. +return_cycle : bool, optional + Whether to simply return the property cycle or apply it. The cycle is + only applied (and therefore reset) if it differs from the current one.""" + ... + + def _parse_level_lim(self, *args: Incomplete, vmin: Incomplete=None, vmax: Incomplete=None, robust: Incomplete=None, inbounds: Incomplete=None, negative: Incomplete=None, positive: Incomplete=None, symmetric: Incomplete=None, to_centers: Incomplete=False, **kwargs: Incomplete) -> Incomplete: + """Return a suitable vmin and vmax based on the input data. + +Parameters +---------- +*args + The sample data. +vmin, vmax : float, optional + The user input minimum and maximum. +robust : bool, optional + Whether to limit the default range to exclude outliers. +inbounds : bool, optional + Whether to filter to in-bounds data. +negative, positive, symmetric : bool, optional + Whether limits should be negative, positive, or symmetric. +to_centers : bool, optional + Whether to convert coordinates to 'centers'. + +Returns +------- +vmin, vmax : float + The minimum and maximum. +**kwargs + Unused arguemnts.""" + ... + + def _parse_level_num(self, *args: Incomplete, levels: Incomplete=None, locator: Incomplete=None, locator_kw: Incomplete=None, vmin: Incomplete=None, vmax: Incomplete=None, norm: Incomplete=None, norm_kw: Incomplete=None, extend: Incomplete=None, symmetric: Incomplete=None, center_levels: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Return a suitable level list given the input data, normalizer, +locator, and vmin and vmax. + +Parameters +---------- +*args + The sample data. Passed to `_parse_level_lim`. +levels : int + The approximate number of levels. +locator, locator_kw + The tick locator used to draw levels. +vmin, vmax : float, optional + The minimum and maximum values passed to the tick locator. +norm, norm_kw : optional + The continuous normalizer. Affects the default locator used to draw levels. +extend : str, optional + The extend setting. Affects level trimming settings. +symmetric : bool, optional + Whether the resulting levels should be symmetric about zero. + +Returns +------- +levels : list of float + The level edges. +**kwargs + Unused arguments.""" + ... + + def _parse_level_vals(self, *args: Incomplete, N: Incomplete=None, levels: Incomplete=None, values: Incomplete=None, extend: Incomplete=None, positive: Incomplete=False, negative: Incomplete=False, nozero: Incomplete=False, norm: Incomplete=None, norm_kw: Incomplete=None, vmin: Incomplete=None, vmax: Incomplete=None, skip_autolev: Incomplete=False, min_levels: Incomplete=None, center_levels: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Return levels resulting from a wide variety of keyword options. + +Parameters +---------- +*args + The sample data. Passed to `_parse_level_lim`. +N + Shorthand for `levels`. +levels : int or sequence of float, optional + The levels list or (approximate) number of levels to create. +values : int or sequence of float, optional + The level center list or (approximate) number of level centers to create. +positive, negative, nozero : bool, optional + Whether to remove out non-positive, non-negative, and zero-valued + levels. The latter is useful for single-color contour plots. +norm, norm_kw : optional + Passed to `Norm`. Used to possibly infer levels or to convert values. +vmin, vmax : float, optional + The user input normalization range. +skip_autolev : bool, optional + Whether to skip automatic level generation. +min_levels : int, optional + The minimum number of levels allowed. + +Returns +------- +levels : list of float + The level edges. +explicit_limits : bool + Whether the user explicitly provided `vmin` and/or `vmax`. +**kwargs + Unused arguments.""" + ... + + @staticmethod + def _parse_level_norm(levels: Incomplete, norm: Incomplete, cmap: Incomplete, *, extend: Incomplete=None, min_levels: Incomplete=None, discrete_ticks: Incomplete=None, discrete_labels: Incomplete=None, center_levels: Incomplete=None, explicit_limits: Incomplete=False, **kwargs: Incomplete) -> Incomplete: + """Create a `~ultraplot.colors.DiscreteNorm` or `~ultraplot.colors.BoundaryNorm` +from the input colormap and normalizer. + +Parameters +---------- +levels : sequence of float + The level boundaries. +norm : `~matplotlib.colors.Normalize` + The continuous normalizer. +cmap : `~matplotlib.colors.Colormap` + The colormap. +extend : str, optional + The extend setting. +min_levels : int, optional + The minimum number of levels. +discrete_ticks : array-like, optional + The colorbar locations to tick. +discrete_labels : array-like, optional + The colorbar tick labels. +explicit_limits : bool, optional + Whether `vmin`/`vmax` were explicitly provided by the user. + +Returns +------- +norm : `~ultraplot.colors.DiscreteNorm` or `~matplotlib.colors.Normalize` + The discrete normalizer, or the original continuous normalizer when + line contours have explicit limits or use qualitative color lists. +cmap : `~matplotlib.colors.Colormap` + The possibly-modified colormap. +kwargs + Unused arguments.""" + ... + + def _apply_plot(self, *pairs: Incomplete, vert: Incomplete=True, **kwargs: Incomplete) -> Incomplete: + """Plot standard lines.""" + ... + + def line(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot standard lines. + +Parameters +---------- +*args : y or x, y + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `y` coordinates are passed, try to infer the `x` coordinates + from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the + :class:`~xarray.DataArray` coordinates. Otherwise, the `x` coordinates + are ``np.arange(0, y.shape[0])``. + * If the `y` coordinates are a 2D array, plot each column of data in succession + (except where each column of data represents a statistical distribution, as with + ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +linewidth : unit-spec, default: :rc:`lines.linewidth` + The width of the line(s). Aliases: ``lw``, ``linewidths``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyle : str, default: :rc:`lines.linestyle` + The style of the line(s). Aliases: ``ls``, ``linestyles``. +color : color-spec, optional + The color of the line(s). The property `cycle` is used by default. Aliases: ``c``, ``colors``. +alpha : float, optional + The opacity of the line(s). Inferred from `color` by default. Aliases: ``a``, ``alphas``. +mean, means : bool, default: False + Whether to plot the means of each column for 2D `y` coordinates. Means + are calculated with `numpy.nanmean`. If no other arguments are specified, + this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). +median, medians : bool, default: False + Whether to plot the medians of each column for 2D `y` coordinates. Medians + are calculated with `numpy.nanmedian`. If no other arguments arguments are + specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). +bars : bool, default: None + Shorthand for `barstd`, `barstds`. +barstd, barstds : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. Standard deviation multiples for + *thin error bars* with optional whiskers (i.e., caps). If scalar, then +/- that + multiple is used. If ``True``, the default standard deviation range of +/-3 is used. +barpctile, barpctiles : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. As with `barstd`, but instead + using percentiles for the error bars. If scalar, that percentile range is + used (e.g., ``90`` shows the 5th to 95th percentiles). If ``True``, the default + percentile range of 0 to 100 is used. +bardata : array-like, optional + Valid only if `mean` and `median` are ``False``. If shape is 2 x N, these + are the lower and upper bounds for the thin error bars. If shape is N, these + are the absolute, symmetric deviations from the central points. +boxes : bool, default: None + Shorthand for `boxstd`, `boxstds`. +boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional + As with `barstd`, `barpctile`, and `bardata`, but for *thicker error bars* + representing a smaller interval than the thin error bars. If `boxstds` is + ``True``, the default standard deviation range of +/-1 is used. If `boxpctiles` + is ``True``, the default percentile range of 25 to 75 is used (i.e., the + interquartile range). When "boxes" and "bars" are combined, this has the + effect of drawing miniature box-and-whisker plots. +capsize : float, default: :rc:`errorbar.capsize` + The cap size for thin error bars in points. +barz, barzorder, boxz, boxzorder : float, default: 2.5 + The "zorder" for the thin and thick error bars. +barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` + Colors for the thin and thick error bars. +barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` + Line widths for the thin and thick error bars, in points. The default for boxes + is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. +boxm, boxmarker : bool or marker-spec, default: 'o' + Whether to draw a small marker in the middle of the box denoting + the mean or median position. Ignored if `boxes` is ``False``. +boxms, boxmarkersize : size-spec, default: ``(2 * boxlinewidth) ** 2`` + The marker size for the `boxmarker` marker in points ** 2. +boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor : color-spec, default: 'w' + Color, face color, and edge color for the `boxmarker` marker. +shade : bool, default: None + Shorthand for `shadestd`. +shadestd, shadestds, shadepctile, shadepctiles, shadedata : optional + As with `barstd`, `barpctile`, and `bardata`, but using *shading* to indicate + the error range. If `shadestds` is ``True``, the default standard deviation + range of +/-2 is used. If `shadepctiles` is ``True``, the default + percentile range of 10 to 90 is used. +fade : bool, default: None + Shorthand for `fadestd`. +fadestd, fadestds, fadepctile, fadepctiles, fadedata : optional + As with `shadestd`, `shadepctile`, and `shadedata`, but for an additional, + more faded, *secondary* shaded region. If `fadestds` is ``True``, the default + standard deviation range of +/-3 is used. If `fadepctiles` is ``True``, + the default percentile range of 0 to 100 is used. +shadec, shadecolor, fadec, fadecolor : color-spec, default: None + Colors for the different shaded regions. The parent artist color is used by default. +shadez, shadezorder, fadez, fadezorder : float, default: 1.5 + The "zorder" for the different shaded regions. +shadea, shadealpha, fadea, fadealpha : float, default: 0.4, 0.2 + The opacity for the different shaded regions. +shadelw, shadelinewidth, fadelw, fadelinewidth : float, default: :rc:`patch.linewidth`. + The edge line width for the shading patches. +shdeec, shadeedgecolor, fadeec, fadeedgecolor : float, default: 'none' + The edge color for the shading patches. +shadelabel, fadelabel : bool or str, optional + Labels for the shaded regions to be used as separate legend entries. To toggle + labels "on" and apply a *default* label, use e.g. ``shadelabel=True``. To apply + a *custom* label, use e.g. ``shadelabel='label'``. Otherwise, the shading is + drawn underneath the line and/or marker in the legend entry. +inbounds : bool, default: :rc:`axes.inbounds` + Whether to restrict the default `y` (`x`) axis limits to account for only + in-bounds data when the `x` (`y`) axis limits have been locked. + See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to :func:`~matplotlib.axes.Axes.plot`. + +See also +-------- +PlotAxes.plot +PlotAxes.plotx +matplotlib.axes.Axes.plot""" + ... + + def linex(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot standard lines. + +Parameters +---------- +*args : x or y, x + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `x` coordinates are passed, try to infer the `y` coordinates + from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the + :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + are ``np.arange(0, x.shape[0])``. + * If the `x` coordinates are a 2D array, plot each column of data in succession + (except where each column of data represents a statistical distribution, as with + ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +linewidth : unit-spec, default: :rc:`lines.linewidth` + The width of the line(s). Aliases: ``lw``, ``linewidths``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyle : str, default: :rc:`lines.linestyle` + The style of the line(s). Aliases: ``ls``, ``linestyles``. +color : color-spec, optional + The color of the line(s). The property `cycle` is used by default. Aliases: ``c``, ``colors``. +alpha : float, optional + The opacity of the line(s). Inferred from `color` by default. Aliases: ``a``, ``alphas``. +mean, means : bool, default: False + Whether to plot the means of each column for 2D `x` coordinates. Means + are calculated with `numpy.nanmean`. If no other arguments are specified, + this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). +median, medians : bool, default: False + Whether to plot the medians of each column for 2D `x` coordinates. Medians + are calculated with `numpy.nanmedian`. If no other arguments arguments are + specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). +bars : bool, default: None + Shorthand for `barstd`, `barstds`. +barstd, barstds : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. Standard deviation multiples for + *thin error bars* with optional whiskers (i.e., caps). If scalar, then +/- that + multiple is used. If ``True``, the default standard deviation range of +/-3 is used. +barpctile, barpctiles : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. As with `barstd`, but instead + using percentiles for the error bars. If scalar, that percentile range is + used (e.g., ``90`` shows the 5th to 95th percentiles). If ``True``, the default + percentile range of 0 to 100 is used. +bardata : array-like, optional + Valid only if `mean` and `median` are ``False``. If shape is 2 x N, these + are the lower and upper bounds for the thin error bars. If shape is N, these + are the absolute, symmetric deviations from the central points. +boxes : bool, default: None + Shorthand for `boxstd`, `boxstds`. +boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional + As with `barstd`, `barpctile`, and `bardata`, but for *thicker error bars* + representing a smaller interval than the thin error bars. If `boxstds` is + ``True``, the default standard deviation range of +/-1 is used. If `boxpctiles` + is ``True``, the default percentile range of 25 to 75 is used (i.e., the + interquartile range). When "boxes" and "bars" are combined, this has the + effect of drawing miniature box-and-whisker plots. +capsize : float, default: :rc:`errorbar.capsize` + The cap size for thin error bars in points. +barz, barzorder, boxz, boxzorder : float, default: 2.5 + The "zorder" for the thin and thick error bars. +barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` + Colors for the thin and thick error bars. +barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` + Line widths for the thin and thick error bars, in points. The default for boxes + is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. +boxm, boxmarker : bool or marker-spec, default: 'o' + Whether to draw a small marker in the middle of the box denoting + the mean or median position. Ignored if `boxes` is ``False``. +boxms, boxmarkersize : size-spec, default: ``(2 * boxlinewidth) ** 2`` + The marker size for the `boxmarker` marker in points ** 2. +boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor : color-spec, default: 'w' + Color, face color, and edge color for the `boxmarker` marker. +shade : bool, default: None + Shorthand for `shadestd`. +shadestd, shadestds, shadepctile, shadepctiles, shadedata : optional + As with `barstd`, `barpctile`, and `bardata`, but using *shading* to indicate + the error range. If `shadestds` is ``True``, the default standard deviation + range of +/-2 is used. If `shadepctiles` is ``True``, the default + percentile range of 10 to 90 is used. +fade : bool, default: None + Shorthand for `fadestd`. +fadestd, fadestds, fadepctile, fadepctiles, fadedata : optional + As with `shadestd`, `shadepctile`, and `shadedata`, but for an additional, + more faded, *secondary* shaded region. If `fadestds` is ``True``, the default + standard deviation range of +/-3 is used. If `fadepctiles` is ``True``, + the default percentile range of 0 to 100 is used. +shadec, shadecolor, fadec, fadecolor : color-spec, default: None + Colors for the different shaded regions. The parent artist color is used by default. +shadez, shadezorder, fadez, fadezorder : float, default: 1.5 + The "zorder" for the different shaded regions. +shadea, shadealpha, fadea, fadealpha : float, default: 0.4, 0.2 + The opacity for the different shaded regions. +shadelw, shadelinewidth, fadelw, fadelinewidth : float, default: :rc:`patch.linewidth`. + The edge line width for the shading patches. +shdeec, shadeedgecolor, fadeec, fadeedgecolor : float, default: 'none' + The edge color for the shading patches. +shadelabel, fadelabel : bool or str, optional + Labels for the shaded regions to be used as separate legend entries. To toggle + labels "on" and apply a *default* label, use e.g. ``shadelabel=True``. To apply + a *custom* label, use e.g. ``shadelabel='label'``. Otherwise, the shading is + drawn underneath the line and/or marker in the legend entry. +inbounds : bool, default: :rc:`axes.inbounds` + Whether to restrict the default `y` (`x`) axis limits to account for only + in-bounds data when the `x` (`y`) axis limits have been locked. + See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to :func:`~matplotlib.axes.Axes.plot`. + +See also +-------- +PlotAxes.plot +PlotAxes.plotx +matplotlib.axes.Axes.plot""" + ... + + def _apply_lollipop(self, xs: Incomplete, hs: Incomplete, ws: Incomplete, bs: Incomplete, *, horizontal: Incomplete=False, **kwargs: Incomplete) -> Incomplete: + """Lollipop graphs are an alternative way to visualize bar charts. We can utilize the bar internal mechanics to generate the charts and then replace the look with the lollipop graphs""" + ... + + def beeswarm(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Beeswarm plot with `SHAP-style `_ feature value coloring. + +Parameters +---------- +data: array-like + The data to be plotted. It is assumed the shape of `data` is (N, M) where N is the number of points and M is the number of features. +levels: array-like, optional + The levels to use for the beeswarm plot. If not provided, the levels are automatically determined based on the data. +n_bins: int or array-like, default: 50 + Number of bins to use to reduce the overlap between points. + Bins are used to determine how crowded the points are for each level of the `y` coordinate. + s, size, ms, markersize : float or array-like or unit-spec, optional + The marker size area(s). If this is an array matching the shape of `x` and `y`, + the units are scaled by `smin` and `smax`. If this contains unit string(s), it + is processed by `~ultraplot.utils.units` and represents the width rather than area. + c, color, colors, mc, markercolor, markercolors, fc, facecolor, facecolors : array-like or color-spec, optional + The marker color(s). If this is an array matching the shape of `x` and `y`, + the colors are generated using `cmap`, `norm`, `vmin`, and `vmax`. Otherwise, + this should be a valid matplotlib color. + smin, smax : float, optional + The minimum and maximum marker size area in units ``points ** 2``. Ignored + if `absolute_size` is ``True``. Default value for `smin` is ``1`` and for + `smax` is the square of :rc:`lines.markersize`. + area_size : bool, default: True + Whether the marker sizes `s` are scaled by area or by radius. The default + ``True`` is consistent with matplotlib. When `absolute_size` is ``True``, + the `s` units are ``points ** 2`` if `area_size` is ``True`` and ``points`` + if `area_size` is ``False``. + absolute_size : bool, default: True or False + Whether `s` should be taken to represent "absolute" marker sizes in units + ``points`` or ``points ** 2`` or "relative" marker sizes scaled by `smin` + and `smax`. Default is ``True`` if `s` is scalar and ``False`` if `s` is + array-like or `smin` or `smax` were passed. + vmin, vmax : float, optional + The minimum and maximum color scale values used with the `norm` normalizer. + If `discrete` is ``False`` these are the absolute limits, and if `discrete` + is ``True`` these are the approximate limits used to automatically determine + `levels` or `values` lists at "nice" intervals. If `levels` or `values` were + already passed as lists, these are ignored, and `vmin` and `vmax` are set to + the minimum and maximum of the lists. If `robust` was passed, the default `vmin` + and `vmax` are some percentile range of the data values. Otherwise, the default + `vmin` and `vmax` are the minimum and maximum of the data values. + data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + + Other parameters + ---------------- + cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` + The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor + function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization + range contains negative and positive values then :rcraw:`cmap.diverging` is used. + Otherwise :rcraw:`cmap.sequential` is used. +cmap_kw : dict-like, optional + Passed to :class:`~ultraplot.constructor.Colormap`. +c, color, colors : color-spec or sequence of color-spec, optional + The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + If not passed, `cmap` is used. +norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` + The data value normalizer, passed to the `~ultraplot.constructor.Norm` + constructor function. If `discrete` is ``True`` then 1) this affects the default + level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and + 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they + are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). + If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains + negative and positive values then `~ultraplot.colors.DivergingNorm` is used. + Otherwise `~matplotlib.colors.Normalize` is used. +norm_kw : dict-like, optional + Passed to `~ultraplot.constructor.Norm`. +extend : {'neither', 'both', 'min', 'max'}, default: 'neither' + Direction for drawing colorbar "extensions" indicating + out-of-bounds data on the end of the colorbar. +discrete : bool, default: :rc:`cmap.discrete` + If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the + colormap. Instead, for non-contour plots, the number of levels will be + roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + using `levels=large_number` but it may improve rendering speed. Default is + ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` + and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. +sequential, diverging, cyclic, qualitative : bool, default: None + Boolean arguments used if `cmap` is not passed. Set these to ``True`` + to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, + :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. + The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + as the default continuous normalizer. + N + Shorthand for `levels`. +levels : int or sequence of float, default: :rc:`cmap.levels` + The number of level edges or a sequence of level edges. If the former, `locator` + is used to generate this many level edges at "nice" intervals. If the latter, + the levels should be monotonically increasing or decreasing (note decreasing + levels fail with ``contour`` plots). +values : int or sequence of float, default: None + The number of level centers or a sequence of level centers. If the former, + `locator` is used to generate this many level centers at "nice" intervals. + If the latter, levels are inferred using `~ultraplot.utils.edges`. + This will override any `levels` input. +center_levels : bool, default False + If set to true, the discrete color bar bins will be centered on the level values + instead of using the level values as the edges of the discrete bins. This option + can be used for diverging, discrete color bars with both positive and negative + data to ensure data near zero is properly represented. + robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` + If ``True`` and `vmin` or `vmax` were not provided, they are + determined from the 2nd and 98th data percentiles rather than the + minimum and maximum. If float, this percentile range is used (for example, + ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, + these specific percentiles should be used. This feature is useful + when your data has large outliers. +inbounds : bool, default: :rc:`cmap.inbounds` + If ``True`` and `vmin` or `vmax` were not provided, when axis limits + have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` + or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. + See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. +locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + The locator used to determine level locations if `levels` or `values` were not + already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. + Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. +locator_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Locator` class. +symmetric : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + symmetric about zero. +positive : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + positive with a minimum at zero. +negative : bool, default: False + If ``True``, the normaliation range or discrete colormap levels are + negative with a minimum at zero. +nozero : bool, default: False + If ``True``, ``0`` is removed from the level list. This is mainly useful for + single-color `~matplotlib.axes.Axes.contour` plots. + cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. + lw, linewidth, linewidths, mew, markeredgewidth, markeredgewidths : float or sequence, optional + The marker edge width(s). + edgecolors, markeredgecolor, markeredgecolors : color-spec or sequence, optional + The marker edge color(s). + mean, means : bool, default: False + Whether to plot the means of each column for 2D `y` coordinates. Means + are calculated with `numpy.nanmean`. If no other arguments are specified, + this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). +median, medians : bool, default: False + Whether to plot the medians of each column for 2D `y` coordinates. Medians + are calculated with `numpy.nanmedian`. If no other arguments arguments are + specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). + bars : bool, default: None + Shorthand for `barstd`, `barstds`. +barstd, barstds : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. Standard deviation multiples for + *thin error bars* with optional whiskers (i.e., caps). If scalar, then +/- that + multiple is used. If ``True``, the default standard deviation range of +/-3 is used. +barpctile, barpctiles : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. As with `barstd`, but instead + using percentiles for the error bars. If scalar, that percentile range is + used (e.g., ``90`` shows the 5th to 95th percentiles). If ``True``, the default + percentile range of 0 to 100 is used. +bardata : array-like, optional + Valid only if `mean` and `median` are ``False``. If shape is 2 x N, these + are the lower and upper bounds for the thin error bars. If shape is N, these + are the absolute, symmetric deviations from the central points. +boxes : bool, default: None + Shorthand for `boxstd`, `boxstds`. +boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional + As with `barstd`, `barpctile`, and `bardata`, but for *thicker error bars* + representing a smaller interval than the thin error bars. If `boxstds` is + ``True``, the default standard deviation range of +/-1 is used. If `boxpctiles` + is ``True``, the default percentile range of 25 to 75 is used (i.e., the + interquartile range). When "boxes" and "bars" are combined, this has the + effect of drawing miniature box-and-whisker plots. +capsize : float, default: :rc:`errorbar.capsize` + The cap size for thin error bars in points. +barz, barzorder, boxz, boxzorder : float, default: 2.5 + The "zorder" for the thin and thick error bars. +barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` + Colors for the thin and thick error bars. +barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` + Line widths for the thin and thick error bars, in points. The default for boxes + is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. +boxm, boxmarker : bool or marker-spec, default: 'o' + Whether to draw a small marker in the middle of the box denoting + the mean or median position. Ignored if `boxes` is ``False``. +boxms, boxmarkersize : size-spec, default: ``(2 * boxlinewidth) ** 2`` + The marker size for the `boxmarker` marker in points ** 2. +boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor : color-spec, default: 'w' + Color, face color, and edge color for the `boxmarker` marker. + shade : bool, default: None + Shorthand for `shadestd`. +shadestd, shadestds, shadepctile, shadepctiles, shadedata : optional + As with `barstd`, `barpctile`, and `bardata`, but using *shading* to indicate + the error range. If `shadestds` is ``True``, the default standard deviation + range of +/-2 is used. If `shadepctiles` is ``True``, the default + percentile range of 10 to 90 is used. +fade : bool, default: None + Shorthand for `fadestd`. +fadestd, fadestds, fadepctile, fadepctiles, fadedata : optional + As with `shadestd`, `shadepctile`, and `shadedata`, but for an additional, + more faded, *secondary* shaded region. If `fadestds` is ``True``, the default + standard deviation range of +/-3 is used. If `fadepctiles` is ``True``, + the default percentile range of 0 to 100 is used. +shadec, shadecolor, fadec, fadecolor : color-spec, default: None + Colors for the different shaded regions. The parent artist color is used by default. +shadez, shadezorder, fadez, fadezorder : float, default: 1.5 + The "zorder" for the different shaded regions. +shadea, shadealpha, fadea, fadealpha : float, default: 0.4, 0.2 + The opacity for the different shaded regions. +shadelw, shadelinewidth, fadelw, fadelinewidth : float, default: :rc:`patch.linewidth`. + The edge line width for the shading patches. +shdeec, shadeedgecolor, fadeec, fadeedgecolor : float, default: 'none' + The edge color for the shading patches. +shadelabel, fadelabel : bool or str, optional + Labels for the shaded regions to be used as separate legend entries. To toggle + labels "on" and apply a *default* label, use e.g. ``shadelabel=True``. To apply + a *custom* label, use e.g. ``shadelabel='label'``. Otherwise, the shading is + drawn underneath the line and/or marker in the legend entry. + inbounds : bool, default: :rc:`axes.inbounds` + Whether to restrict the default `y` (`x`) axis limits to account for only + in-bounds data when the `x` (`y`) axis limits have been locked. + See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. + label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. + colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + **kwargs + Passed to `~matplotlib.axes.Axes.scatter`. + + See also + -------- + PlotAxes.scatter + PlotAxes.scatterx + matplotlib.axes.Axes.scatter""" + ... + + def _apply_beeswarm(self, data: np.ndarray, levels: np.ndarray=None, feature_values: np.ndarray=None, ss: float | np.ndarray=None, orientation: str='horizontal', n_bins: int=50, **kwargs: Incomplete) -> mcollections.Collection: + ... + + def lollipop(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot individual or group lollipop graphs. + +A lollipop graph is a bar graph with the bars replaced by dots connected to the x-axis by lines. + +Inputs such as arrays (`x` or `y`) or dataframes (`pandas` or `xarray`) are passed through :func:`~ultraplot.PlotAxes.bar`. Colors are inferred from the bar objects and parsed automatically. Formatting of the lollipop consists of controlling the `stem` and the `marker`. The stem properties can be set for the width, size, or color. Marker formatting follows the same inputs to :func:`~ultraplot.PlotAxes.scatter`. + +Parameters +---------- +*args : x or y, x + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `x` coordinates are passed, try to infer the `y` coordinates + from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the + :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + are ``np.arange(0, x.shape[0])``. + * If the `x` coordinates are a 2D array, plot each column of data in succession + (except where each column of data represents a statistical distribution, as with + ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +stemlinewdith: str, default `rc["lollipop.stemlinewidth"]` +stemcolor: str, default `rc["lollipop.stemcolor"]` + Line color of the lines connecting the dots to the x-axis. Defaults to `rc["lollipop.linecolor"]`. +stemlinestyle: str, default: `rc["lollipop.stemlinestyle"]` + The style of the lines connecting the dots to the x-axis. Defaults to `rc["lollipop.linestyle"]`. +s, size, ms, markersize : float or array-like or unit-spec, optional + The marker size area(s). If this is an array matching the shape of `x` and `y`, + the units are scaled by `smin` and `smax`. If this contains unit string(s), it + is processed by `~ultraplot.utils.units` and represents the width rather than area. +c, color, colors, mc, markercolor, markercolors, fc, facecolor, facecolors : array-like or color-spec, optional + The marker color(s). If this is an array matching the shape of `x` and `y`, + the colors are generated using `cmap`, `norm`, `vmin`, and `vmax`. Otherwise, + this should be a valid matplotlib color. +smin, smax : float, optional + The minimum and maximum marker size area in units ``points ** 2``. Ignored + if `absolute_size` is ``True``. Default value for `smin` is ``1`` and for + `smax` is the square of :rc:`lines.markersize`. +area_size : bool, default: True + Whether the marker sizes `s` are scaled by area or by radius. The default + ``True`` is consistent with matplotlib. When `absolute_size` is ``True``, + the `s` units are ``points ** 2`` if `area_size` is ``True`` and ``points`` + if `area_size` is ``False``. +absolute_size : bool, default: True or False + Whether `s` should be taken to represent "absolute" marker sizes in units + ``points`` or ``points ** 2`` or "relative" marker sizes scaled by `smin` + and `smax`. Default is ``True`` if `s` is scalar and ``False`` if `s` is + array-like or `smin` or `smax` were passed. +vmin, vmax : float, optional + The minimum and maximum color scale values used with the `norm` normalizer. + If `discrete` is ``False`` these are the absolute limits, and if `discrete` + is ``True`` these are the approximate limits used to automatically determine + `levels` or `values` lists at "nice" intervals. If `levels` or `values` were + already passed as lists, these are ignored, and `vmin` and `vmax` are set to + the minimum and maximum of the lists. If `robust` was passed, the default `vmin` + and `vmax` are some percentile range of the data values. Otherwise, the default + `vmin` and `vmax` are the minimum and maximum of the data values. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` + The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor + function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization + range contains negative and positive values then :rcraw:`cmap.diverging` is used. + Otherwise :rcraw:`cmap.sequential` is used. +cmap_kw : dict-like, optional + Passed to :class:`~ultraplot.constructor.Colormap`. +c, color, colors : color-spec or sequence of color-spec, optional + The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + If not passed, `cmap` is used. +norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` + The data value normalizer, passed to the `~ultraplot.constructor.Norm` + constructor function. If `discrete` is ``True`` then 1) this affects the default + level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and + 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they + are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). + If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains + negative and positive values then `~ultraplot.colors.DivergingNorm` is used. + Otherwise `~matplotlib.colors.Normalize` is used. +norm_kw : dict-like, optional + Passed to `~ultraplot.constructor.Norm`. +extend : {'neither', 'both', 'min', 'max'}, default: 'neither' + Direction for drawing colorbar "extensions" indicating + out-of-bounds data on the end of the colorbar. +discrete : bool, default: :rc:`cmap.discrete` + If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the + colormap. Instead, for non-contour plots, the number of levels will be + roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + using `levels=large_number` but it may improve rendering speed. Default is + ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` + and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. +sequential, diverging, cyclic, qualitative : bool, default: None + Boolean arguments used if `cmap` is not passed. Set these to ``True`` + to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, + :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. + The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + as the default continuous normalizer. +N + Shorthand for `levels`. +levels : int or sequence of float, default: :rc:`cmap.levels` + The number of level edges or a sequence of level edges. If the former, `locator` + is used to generate this many level edges at "nice" intervals. If the latter, + the levels should be monotonically increasing or decreasing (note decreasing + levels fail with ``contour`` plots). +values : int or sequence of float, default: None + The number of level centers or a sequence of level centers. If the former, + `locator` is used to generate this many level centers at "nice" intervals. + If the latter, levels are inferred using `~ultraplot.utils.edges`. + This will override any `levels` input. +center_levels : bool, default False + If set to true, the discrete color bar bins will be centered on the level values + instead of using the level values as the edges of the discrete bins. This option + can be used for diverging, discrete color bars with both positive and negative + data to ensure data near zero is properly represented. +robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` + If ``True`` and `vmin` or `vmax` were not provided, they are + determined from the 2nd and 98th data percentiles rather than the + minimum and maximum. If float, this percentile range is used (for example, + ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, + these specific percentiles should be used. This feature is useful + when your data has large outliers. +inbounds : bool, default: :rc:`cmap.inbounds` + If ``True`` and `vmin` or `vmax` were not provided, when axis limits + have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` + or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. + See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. +locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + The locator used to determine level locations if `levels` or `values` were not + already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. + Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. +locator_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Locator` class. +symmetric : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + symmetric about zero. +positive : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + positive with a minimum at zero. +negative : bool, default: False + If ``True``, the normaliation range or discrete colormap levels are + negative with a minimum at zero. +nozero : bool, default: False + If ``True``, ``0`` is removed from the level list. This is mainly useful for + single-color `~matplotlib.axes.Axes.contour` plots. +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +lw, linewidth, linewidths, mew, markeredgewidth, markeredgewidths : float or sequence, optional + The marker edge width(s). +edgecolors, markeredgecolor, markeredgecolors : color-spec or sequence, optional + The marker edge color(s). +mean, means : bool, default: False + Whether to plot the means of each column for 2D `x` coordinates. Means + are calculated with `numpy.nanmean`. If no other arguments are specified, + this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). +median, medians : bool, default: False + Whether to plot the medians of each column for 2D `x` coordinates. Medians + are calculated with `numpy.nanmedian`. If no other arguments arguments are + specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). +bars : bool, default: None + Shorthand for `barstd`, `barstds`. +barstd, barstds : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. Standard deviation multiples for + *thin error bars* with optional whiskers (i.e., caps). If scalar, then +/- that + multiple is used. If ``True``, the default standard deviation range of +/-3 is used. +barpctile, barpctiles : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. As with `barstd`, but instead + using percentiles for the error bars. If scalar, that percentile range is + used (e.g., ``90`` shows the 5th to 95th percentiles). If ``True``, the default + percentile range of 0 to 100 is used. +bardata : array-like, optional + Valid only if `mean` and `median` are ``False``. If shape is 2 x N, these + are the lower and upper bounds for the thin error bars. If shape is N, these + are the absolute, symmetric deviations from the central points. +boxes : bool, default: None + Shorthand for `boxstd`, `boxstds`. +boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional + As with `barstd`, `barpctile`, and `bardata`, but for *thicker error bars* + representing a smaller interval than the thin error bars. If `boxstds` is + ``True``, the default standard deviation range of +/-1 is used. If `boxpctiles` + is ``True``, the default percentile range of 25 to 75 is used (i.e., the + interquartile range). When "boxes" and "bars" are combined, this has the + effect of drawing miniature box-and-whisker plots. +capsize : float, default: :rc:`errorbar.capsize` + The cap size for thin error bars in points. +barz, barzorder, boxz, boxzorder : float, default: 2.5 + The "zorder" for the thin and thick error bars. +barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` + Colors for the thin and thick error bars. +barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` + Line widths for the thin and thick error bars, in points. The default for boxes + is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. +boxm, boxmarker : bool or marker-spec, default: 'o' + Whether to draw a small marker in the middle of the box denoting + the mean or median position. Ignored if `boxes` is ``False``. +boxms, boxmarkersize : size-spec, default: ``(2 * boxlinewidth) ** 2`` + The marker size for the `boxmarker` marker in points ** 2. +boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor : color-spec, default: 'w' + Color, face color, and edge color for the `boxmarker` marker. +shade : bool, default: None + Shorthand for `shadestd`. +shadestd, shadestds, shadepctile, shadepctiles, shadedata : optional + As with `barstd`, `barpctile`, and `bardata`, but using *shading* to indicate + the error range. If `shadestds` is ``True``, the default standard deviation + range of +/-2 is used. If `shadepctiles` is ``True``, the default + percentile range of 10 to 90 is used. +fade : bool, default: None + Shorthand for `fadestd`. +fadestd, fadestds, fadepctile, fadepctiles, fadedata : optional + As with `shadestd`, `shadepctile`, and `shadedata`, but for an additional, + more faded, *secondary* shaded region. If `fadestds` is ``True``, the default + standard deviation range of +/-3 is used. If `fadepctiles` is ``True``, + the default percentile range of 0 to 100 is used. +shadec, shadecolor, fadec, fadecolor : color-spec, default: None + Colors for the different shaded regions. The parent artist color is used by default. +shadez, shadezorder, fadez, fadezorder : float, default: 1.5 + The "zorder" for the different shaded regions. +shadea, shadealpha, fadea, fadealpha : float, default: 0.4, 0.2 + The opacity for the different shaded regions. +shadelw, shadelinewidth, fadelw, fadelinewidth : float, default: :rc:`patch.linewidth`. + The edge line width for the shading patches. +shdeec, shadeedgecolor, fadeec, fadeedgecolor : float, default: 'none' + The edge color for the shading patches. +shadelabel, fadelabel : bool or str, optional + Labels for the shaded regions to be used as separate legend entries. To toggle + labels "on" and apply a *default* label, use e.g. ``shadelabel=True``. To apply + a *custom* label, use e.g. ``shadelabel='label'``. Otherwise, the shading is + drawn underneath the line and/or marker in the legend entry. +inbounds : bool, default: :rc:`axes.inbounds` + Whether to restrict the default `y` (`x`) axis limits to account for only + in-bounds data when the `x` (`y`) axis limits have been locked. + See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `~matplotlib.axes.Axes.scatter`. + +See for more info on the grouping behavior :func:`~ultraplot.PlotAxes.bar`, and for formatting :func:`~ultraplot.PlotAxes.scatter`. +Returns +------- +List of ~matplotlib.collections.PatchCollection, and a ~matplotlib.collections.LineCollection""" + ... + + def lollipoph(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot individual or group lollipop graphs. + +A lollipop graph is a bar graph with the bars replaced by dots connected to the x-axis by lines. + +Inputs such as arrays (`x` or `y`) or dataframes (`pandas` or `xarray`) are passed through :func:`~ultraplot.PlotAxes.bar`. Colors are inferred from the bar objects and parsed automatically. Formatting of the lollipop consists of controlling the `stem` and the `marker`. The stem properties can be set for the width, size, or color. Marker formatting follows the same inputs to :func:`~ultraplot.PlotAxes.scatter`. + +Parameters +---------- +*args : x or y, x + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `x` coordinates are passed, try to infer the `y` coordinates + from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the + :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + are ``np.arange(0, x.shape[0])``. + * If the `x` coordinates are a 2D array, plot each column of data in succession + (except where each column of data represents a statistical distribution, as with + ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +stemlinewdith: str, default `rc["lollipop.stemlinewidth"]` +stemcolor: str, default `rc["lollipop.stemcolor"]` + Line color of the lines connecting the dots to the x-axis. Defaults to `rc["lollipop.linecolor"]`. +stemlinestyle: str, default: `rc["lollipop.stemlinestyle"]` + The style of the lines connecting the dots to the x-axis. Defaults to `rc["lollipop.linestyle"]`. +s, size, ms, markersize : float or array-like or unit-spec, optional + The marker size area(s). If this is an array matching the shape of `x` and `y`, + the units are scaled by `smin` and `smax`. If this contains unit string(s), it + is processed by `~ultraplot.utils.units` and represents the width rather than area. +c, color, colors, mc, markercolor, markercolors, fc, facecolor, facecolors : array-like or color-spec, optional + The marker color(s). If this is an array matching the shape of `x` and `y`, + the colors are generated using `cmap`, `norm`, `vmin`, and `vmax`. Otherwise, + this should be a valid matplotlib color. +smin, smax : float, optional + The minimum and maximum marker size area in units ``points ** 2``. Ignored + if `absolute_size` is ``True``. Default value for `smin` is ``1`` and for + `smax` is the square of :rc:`lines.markersize`. +area_size : bool, default: True + Whether the marker sizes `s` are scaled by area or by radius. The default + ``True`` is consistent with matplotlib. When `absolute_size` is ``True``, + the `s` units are ``points ** 2`` if `area_size` is ``True`` and ``points`` + if `area_size` is ``False``. +absolute_size : bool, default: True or False + Whether `s` should be taken to represent "absolute" marker sizes in units + ``points`` or ``points ** 2`` or "relative" marker sizes scaled by `smin` + and `smax`. Default is ``True`` if `s` is scalar and ``False`` if `s` is + array-like or `smin` or `smax` were passed. +vmin, vmax : float, optional + The minimum and maximum color scale values used with the `norm` normalizer. + If `discrete` is ``False`` these are the absolute limits, and if `discrete` + is ``True`` these are the approximate limits used to automatically determine + `levels` or `values` lists at "nice" intervals. If `levels` or `values` were + already passed as lists, these are ignored, and `vmin` and `vmax` are set to + the minimum and maximum of the lists. If `robust` was passed, the default `vmin` + and `vmax` are some percentile range of the data values. Otherwise, the default + `vmin` and `vmax` are the minimum and maximum of the data values. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` + The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor + function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization + range contains negative and positive values then :rcraw:`cmap.diverging` is used. + Otherwise :rcraw:`cmap.sequential` is used. +cmap_kw : dict-like, optional + Passed to :class:`~ultraplot.constructor.Colormap`. +c, color, colors : color-spec or sequence of color-spec, optional + The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + If not passed, `cmap` is used. +norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` + The data value normalizer, passed to the `~ultraplot.constructor.Norm` + constructor function. If `discrete` is ``True`` then 1) this affects the default + level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and + 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they + are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). + If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains + negative and positive values then `~ultraplot.colors.DivergingNorm` is used. + Otherwise `~matplotlib.colors.Normalize` is used. +norm_kw : dict-like, optional + Passed to `~ultraplot.constructor.Norm`. +extend : {'neither', 'both', 'min', 'max'}, default: 'neither' + Direction for drawing colorbar "extensions" indicating + out-of-bounds data on the end of the colorbar. +discrete : bool, default: :rc:`cmap.discrete` + If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the + colormap. Instead, for non-contour plots, the number of levels will be + roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + using `levels=large_number` but it may improve rendering speed. Default is + ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` + and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. +sequential, diverging, cyclic, qualitative : bool, default: None + Boolean arguments used if `cmap` is not passed. Set these to ``True`` + to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, + :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. + The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + as the default continuous normalizer. +N + Shorthand for `levels`. +levels : int or sequence of float, default: :rc:`cmap.levels` + The number of level edges or a sequence of level edges. If the former, `locator` + is used to generate this many level edges at "nice" intervals. If the latter, + the levels should be monotonically increasing or decreasing (note decreasing + levels fail with ``contour`` plots). +values : int or sequence of float, default: None + The number of level centers or a sequence of level centers. If the former, + `locator` is used to generate this many level centers at "nice" intervals. + If the latter, levels are inferred using `~ultraplot.utils.edges`. + This will override any `levels` input. +center_levels : bool, default False + If set to true, the discrete color bar bins will be centered on the level values + instead of using the level values as the edges of the discrete bins. This option + can be used for diverging, discrete color bars with both positive and negative + data to ensure data near zero is properly represented. +robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` + If ``True`` and `vmin` or `vmax` were not provided, they are + determined from the 2nd and 98th data percentiles rather than the + minimum and maximum. If float, this percentile range is used (for example, + ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, + these specific percentiles should be used. This feature is useful + when your data has large outliers. +inbounds : bool, default: :rc:`cmap.inbounds` + If ``True`` and `vmin` or `vmax` were not provided, when axis limits + have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` + or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. + See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. +locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + The locator used to determine level locations if `levels` or `values` were not + already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. + Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. +locator_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Locator` class. +symmetric : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + symmetric about zero. +positive : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + positive with a minimum at zero. +negative : bool, default: False + If ``True``, the normaliation range or discrete colormap levels are + negative with a minimum at zero. +nozero : bool, default: False + If ``True``, ``0`` is removed from the level list. This is mainly useful for + single-color `~matplotlib.axes.Axes.contour` plots. +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +lw, linewidth, linewidths, mew, markeredgewidth, markeredgewidths : float or sequence, optional + The marker edge width(s). +edgecolors, markeredgecolor, markeredgecolors : color-spec or sequence, optional + The marker edge color(s). +mean, means : bool, default: False + Whether to plot the means of each column for 2D `x` coordinates. Means + are calculated with `numpy.nanmean`. If no other arguments are specified, + this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). +median, medians : bool, default: False + Whether to plot the medians of each column for 2D `x` coordinates. Medians + are calculated with `numpy.nanmedian`. If no other arguments arguments are + specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). +bars : bool, default: None + Shorthand for `barstd`, `barstds`. +barstd, barstds : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. Standard deviation multiples for + *thin error bars* with optional whiskers (i.e., caps). If scalar, then +/- that + multiple is used. If ``True``, the default standard deviation range of +/-3 is used. +barpctile, barpctiles : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. As with `barstd`, but instead + using percentiles for the error bars. If scalar, that percentile range is + used (e.g., ``90`` shows the 5th to 95th percentiles). If ``True``, the default + percentile range of 0 to 100 is used. +bardata : array-like, optional + Valid only if `mean` and `median` are ``False``. If shape is 2 x N, these + are the lower and upper bounds for the thin error bars. If shape is N, these + are the absolute, symmetric deviations from the central points. +boxes : bool, default: None + Shorthand for `boxstd`, `boxstds`. +boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional + As with `barstd`, `barpctile`, and `bardata`, but for *thicker error bars* + representing a smaller interval than the thin error bars. If `boxstds` is + ``True``, the default standard deviation range of +/-1 is used. If `boxpctiles` + is ``True``, the default percentile range of 25 to 75 is used (i.e., the + interquartile range). When "boxes" and "bars" are combined, this has the + effect of drawing miniature box-and-whisker plots. +capsize : float, default: :rc:`errorbar.capsize` + The cap size for thin error bars in points. +barz, barzorder, boxz, boxzorder : float, default: 2.5 + The "zorder" for the thin and thick error bars. +barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` + Colors for the thin and thick error bars. +barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` + Line widths for the thin and thick error bars, in points. The default for boxes + is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. +boxm, boxmarker : bool or marker-spec, default: 'o' + Whether to draw a small marker in the middle of the box denoting + the mean or median position. Ignored if `boxes` is ``False``. +boxms, boxmarkersize : size-spec, default: ``(2 * boxlinewidth) ** 2`` + The marker size for the `boxmarker` marker in points ** 2. +boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor : color-spec, default: 'w' + Color, face color, and edge color for the `boxmarker` marker. +shade : bool, default: None + Shorthand for `shadestd`. +shadestd, shadestds, shadepctile, shadepctiles, shadedata : optional + As with `barstd`, `barpctile`, and `bardata`, but using *shading* to indicate + the error range. If `shadestds` is ``True``, the default standard deviation + range of +/-2 is used. If `shadepctiles` is ``True``, the default + percentile range of 10 to 90 is used. +fade : bool, default: None + Shorthand for `fadestd`. +fadestd, fadestds, fadepctile, fadepctiles, fadedata : optional + As with `shadestd`, `shadepctile`, and `shadedata`, but for an additional, + more faded, *secondary* shaded region. If `fadestds` is ``True``, the default + standard deviation range of +/-3 is used. If `fadepctiles` is ``True``, + the default percentile range of 0 to 100 is used. +shadec, shadecolor, fadec, fadecolor : color-spec, default: None + Colors for the different shaded regions. The parent artist color is used by default. +shadez, shadezorder, fadez, fadezorder : float, default: 1.5 + The "zorder" for the different shaded regions. +shadea, shadealpha, fadea, fadealpha : float, default: 0.4, 0.2 + The opacity for the different shaded regions. +shadelw, shadelinewidth, fadelw, fadelinewidth : float, default: :rc:`patch.linewidth`. + The edge line width for the shading patches. +shdeec, shadeedgecolor, fadeec, fadeedgecolor : float, default: 'none' + The edge color for the shading patches. +shadelabel, fadelabel : bool or str, optional + Labels for the shaded regions to be used as separate legend entries. To toggle + labels "on" and apply a *default* label, use e.g. ``shadelabel=True``. To apply + a *custom* label, use e.g. ``shadelabel='label'``. Otherwise, the shading is + drawn underneath the line and/or marker in the legend entry. +inbounds : bool, default: :rc:`axes.inbounds` + Whether to restrict the default `y` (`x`) axis limits to account for only + in-bounds data when the `x` (`y`) axis limits have been locked. + See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `~matplotlib.axes.Axes.scatter`. + +See for more info on the grouping behavior :func:`~ultraplot.PlotAxes.bar`, and for formatting :func:`~ultraplot.PlotAxes.scatter`. +Returns +------- +List of ~matplotlib.collections.PatchCollection, and a ~matplotlib.collections.LineCollection (horizontal lollipop)""" + ... + + def loglog(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot loglog + +UltraPlot is optimized for visualizing logarithmic scales by default. For cases with large differences in magnitude, +we recommend setting `rc["formatter.log"] = True` to enhance axis label formatting. +Make a plot with log scaling on both the x- and y-axis. + +Call signatures:: + + loglog([x], y, [fmt], data=None, **kwargs) + loglog([x], y, [fmt], [x2], y2, [fmt2], ..., **kwargs) + +This is just a thin wrapper around `.plot` which additionally changes +both the x-axis and the y-axis to log scaling. All the concepts and +parameters of plot can be used here as well. + +The additional parameters *base*, *subs* and *nonpositive* control the +x/y-axis properties. They are just forwarded to `.Axes.set_xscale` and +`.Axes.set_yscale`. To use different properties on the x-axis and the +y-axis, use e.g. +``ax.set_xscale("log", base=10); ax.set_yscale("log", base=2)``. + +Parameters +---------- +base : float, default: 10 + Base of the logarithm. + +subs : sequence, optional + The location of the minor ticks. If *None*, reasonable locations + are automatically chosen depending on the number of decades in the + plot. See `.Axes.set_xscale`/`.Axes.set_yscale` for details. + +nonpositive : {'mask', 'clip'}, default: 'clip' + Non-positive values can be masked as invalid, or clipped to a very + small positive number. + +**kwargs + All parameters supported by `.plot`. + +Returns +------- +list of `.Line2D` + Objects representing the plotted data. + +Notes +----- + +.. note:: + + This is the :ref:`pyplot wrapper ` for `.axes.Axes.loglog`.""" + ... + + def semilogy(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot semilogy + +UltraPlot is optimized for visualizing logarithmic scales by default. For cases with large differences in magnitude, +we recommend setting `rc["formatter.log"] = True` to enhance axis label formatting. +Make a plot with log scaling on the y-axis. + +Call signatures:: + + semilogy([x], y, [fmt], data=None, **kwargs) + semilogy([x], y, [fmt], [x2], y2, [fmt2], ..., **kwargs) + +This is just a thin wrapper around `.plot` which additionally changes +the y-axis to log scaling. All the concepts and parameters of plot can +be used here as well. + +The additional parameters *base*, *subs*, and *nonpositive* control the +y-axis properties. They are just forwarded to `.Axes.set_yscale`. + +Parameters +---------- +base : float, default: 10 + Base of the y logarithm. + +subs : array-like, optional + The location of the minor yticks. If *None*, reasonable locations + are automatically chosen depending on the number of decades in the + plot. See `.Axes.set_yscale` for details. + +nonpositive : {'mask', 'clip'}, default: 'clip' + Non-positive values in y can be masked as invalid, or clipped to a + very small positive number. + +**kwargs + All parameters supported by `.plot`. + +Returns +------- +list of `.Line2D` + Objects representing the plotted data. + +Notes +----- + +.. note:: + + This is the :ref:`pyplot wrapper ` for `.axes.Axes.semilogy`.""" + ... + + def semilogx(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot semilogx + +UltraPlot is optimized for visualizing logarithmic scales by default. For cases with large differences in magnitude, +we recommend setting `rc["formatter.log"] = True` to enhance axis label formatting. +Make a plot with log scaling on the x-axis. + +Call signatures:: + + semilogx([x], y, [fmt], data=None, **kwargs) + semilogx([x], y, [fmt], [x2], y2, [fmt2], ..., **kwargs) + +This is just a thin wrapper around `.plot` which additionally changes +the x-axis to log scaling. All the concepts and parameters of plot can +be used here as well. + +The additional parameters *base*, *subs*, and *nonpositive* control the +x-axis properties. They are just forwarded to `.Axes.set_xscale`. + +Parameters +---------- +base : float, default: 10 + Base of the x logarithm. + +subs : array-like, optional + The location of the minor xticks. If *None*, reasonable locations + are automatically chosen depending on the number of decades in the + plot. See `.Axes.set_xscale` for details. + +nonpositive : {'mask', 'clip'}, default: 'clip' + Non-positive values in x can be masked as invalid, or clipped to a + very small positive number. + +**kwargs + All parameters supported by `.plot`. + +Returns +------- +list of `.Line2D` + Objects representing the plotted data. + +Notes +----- + +.. note:: + + This is the :ref:`pyplot wrapper ` for `.axes.Axes.semilogx`.""" + ... + + def plot(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot standard lines. + +Parameters +---------- +*args : y or x, y + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `y` coordinates are passed, try to infer the `x` coordinates + from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the + :class:`~xarray.DataArray` coordinates. Otherwise, the `x` coordinates + are ``np.arange(0, y.shape[0])``. + * If the `y` coordinates are a 2D array, plot each column of data in succession + (except where each column of data represents a statistical distribution, as with + ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +linewidth : unit-spec, default: :rc:`lines.linewidth` + The width of the line(s). Aliases: ``lw``, ``linewidths``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyle : str, default: :rc:`lines.linestyle` + The style of the line(s). Aliases: ``ls``, ``linestyles``. +color : color-spec, optional + The color of the line(s). The property `cycle` is used by default. Aliases: ``c``, ``colors``. +alpha : float, optional + The opacity of the line(s). Inferred from `color` by default. Aliases: ``a``, ``alphas``. +mean, means : bool, default: False + Whether to plot the means of each column for 2D `y` coordinates. Means + are calculated with `numpy.nanmean`. If no other arguments are specified, + this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). +median, medians : bool, default: False + Whether to plot the medians of each column for 2D `y` coordinates. Medians + are calculated with `numpy.nanmedian`. If no other arguments arguments are + specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). +bars : bool, default: None + Shorthand for `barstd`, `barstds`. +barstd, barstds : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. Standard deviation multiples for + *thin error bars* with optional whiskers (i.e., caps). If scalar, then +/- that + multiple is used. If ``True``, the default standard deviation range of +/-3 is used. +barpctile, barpctiles : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. As with `barstd`, but instead + using percentiles for the error bars. If scalar, that percentile range is + used (e.g., ``90`` shows the 5th to 95th percentiles). If ``True``, the default + percentile range of 0 to 100 is used. +bardata : array-like, optional + Valid only if `mean` and `median` are ``False``. If shape is 2 x N, these + are the lower and upper bounds for the thin error bars. If shape is N, these + are the absolute, symmetric deviations from the central points. +boxes : bool, default: None + Shorthand for `boxstd`, `boxstds`. +boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional + As with `barstd`, `barpctile`, and `bardata`, but for *thicker error bars* + representing a smaller interval than the thin error bars. If `boxstds` is + ``True``, the default standard deviation range of +/-1 is used. If `boxpctiles` + is ``True``, the default percentile range of 25 to 75 is used (i.e., the + interquartile range). When "boxes" and "bars" are combined, this has the + effect of drawing miniature box-and-whisker plots. +capsize : float, default: :rc:`errorbar.capsize` + The cap size for thin error bars in points. +barz, barzorder, boxz, boxzorder : float, default: 2.5 + The "zorder" for the thin and thick error bars. +barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` + Colors for the thin and thick error bars. +barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` + Line widths for the thin and thick error bars, in points. The default for boxes + is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. +boxm, boxmarker : bool or marker-spec, default: 'o' + Whether to draw a small marker in the middle of the box denoting + the mean or median position. Ignored if `boxes` is ``False``. +boxms, boxmarkersize : size-spec, default: ``(2 * boxlinewidth) ** 2`` + The marker size for the `boxmarker` marker in points ** 2. +boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor : color-spec, default: 'w' + Color, face color, and edge color for the `boxmarker` marker. +shade : bool, default: None + Shorthand for `shadestd`. +shadestd, shadestds, shadepctile, shadepctiles, shadedata : optional + As with `barstd`, `barpctile`, and `bardata`, but using *shading* to indicate + the error range. If `shadestds` is ``True``, the default standard deviation + range of +/-2 is used. If `shadepctiles` is ``True``, the default + percentile range of 10 to 90 is used. +fade : bool, default: None + Shorthand for `fadestd`. +fadestd, fadestds, fadepctile, fadepctiles, fadedata : optional + As with `shadestd`, `shadepctile`, and `shadedata`, but for an additional, + more faded, *secondary* shaded region. If `fadestds` is ``True``, the default + standard deviation range of +/-3 is used. If `fadepctiles` is ``True``, + the default percentile range of 0 to 100 is used. +shadec, shadecolor, fadec, fadecolor : color-spec, default: None + Colors for the different shaded regions. The parent artist color is used by default. +shadez, shadezorder, fadez, fadezorder : float, default: 1.5 + The "zorder" for the different shaded regions. +shadea, shadealpha, fadea, fadealpha : float, default: 0.4, 0.2 + The opacity for the different shaded regions. +shadelw, shadelinewidth, fadelw, fadelinewidth : float, default: :rc:`patch.linewidth`. + The edge line width for the shading patches. +shdeec, shadeedgecolor, fadeec, fadeedgecolor : float, default: 'none' + The edge color for the shading patches. +shadelabel, fadelabel : bool or str, optional + Labels for the shaded regions to be used as separate legend entries. To toggle + labels "on" and apply a *default* label, use e.g. ``shadelabel=True``. To apply + a *custom* label, use e.g. ``shadelabel='label'``. Otherwise, the shading is + drawn underneath the line and/or marker in the legend entry. +inbounds : bool, default: :rc:`axes.inbounds` + Whether to restrict the default `y` (`x`) axis limits to account for only + in-bounds data when the `x` (`y`) axis limits have been locked. + See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to :func:`~matplotlib.axes.Axes.plot`. + +See also +-------- +PlotAxes.plot +PlotAxes.plotx +matplotlib.axes.Axes.plot""" + ... + + def plotx(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot standard lines. + +Parameters +---------- +*args : x or y, x + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `x` coordinates are passed, try to infer the `y` coordinates + from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the + :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + are ``np.arange(0, x.shape[0])``. + * If the `x` coordinates are a 2D array, plot each column of data in succession + (except where each column of data represents a statistical distribution, as with + ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +linewidth : unit-spec, default: :rc:`lines.linewidth` + The width of the line(s). Aliases: ``lw``, ``linewidths``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyle : str, default: :rc:`lines.linestyle` + The style of the line(s). Aliases: ``ls``, ``linestyles``. +color : color-spec, optional + The color of the line(s). The property `cycle` is used by default. Aliases: ``c``, ``colors``. +alpha : float, optional + The opacity of the line(s). Inferred from `color` by default. Aliases: ``a``, ``alphas``. +mean, means : bool, default: False + Whether to plot the means of each column for 2D `x` coordinates. Means + are calculated with `numpy.nanmean`. If no other arguments are specified, + this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). +median, medians : bool, default: False + Whether to plot the medians of each column for 2D `x` coordinates. Medians + are calculated with `numpy.nanmedian`. If no other arguments arguments are + specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). +bars : bool, default: None + Shorthand for `barstd`, `barstds`. +barstd, barstds : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. Standard deviation multiples for + *thin error bars* with optional whiskers (i.e., caps). If scalar, then +/- that + multiple is used. If ``True``, the default standard deviation range of +/-3 is used. +barpctile, barpctiles : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. As with `barstd`, but instead + using percentiles for the error bars. If scalar, that percentile range is + used (e.g., ``90`` shows the 5th to 95th percentiles). If ``True``, the default + percentile range of 0 to 100 is used. +bardata : array-like, optional + Valid only if `mean` and `median` are ``False``. If shape is 2 x N, these + are the lower and upper bounds for the thin error bars. If shape is N, these + are the absolute, symmetric deviations from the central points. +boxes : bool, default: None + Shorthand for `boxstd`, `boxstds`. +boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional + As with `barstd`, `barpctile`, and `bardata`, but for *thicker error bars* + representing a smaller interval than the thin error bars. If `boxstds` is + ``True``, the default standard deviation range of +/-1 is used. If `boxpctiles` + is ``True``, the default percentile range of 25 to 75 is used (i.e., the + interquartile range). When "boxes" and "bars" are combined, this has the + effect of drawing miniature box-and-whisker plots. +capsize : float, default: :rc:`errorbar.capsize` + The cap size for thin error bars in points. +barz, barzorder, boxz, boxzorder : float, default: 2.5 + The "zorder" for the thin and thick error bars. +barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` + Colors for the thin and thick error bars. +barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` + Line widths for the thin and thick error bars, in points. The default for boxes + is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. +boxm, boxmarker : bool or marker-spec, default: 'o' + Whether to draw a small marker in the middle of the box denoting + the mean or median position. Ignored if `boxes` is ``False``. +boxms, boxmarkersize : size-spec, default: ``(2 * boxlinewidth) ** 2`` + The marker size for the `boxmarker` marker in points ** 2. +boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor : color-spec, default: 'w' + Color, face color, and edge color for the `boxmarker` marker. +shade : bool, default: None + Shorthand for `shadestd`. +shadestd, shadestds, shadepctile, shadepctiles, shadedata : optional + As with `barstd`, `barpctile`, and `bardata`, but using *shading* to indicate + the error range. If `shadestds` is ``True``, the default standard deviation + range of +/-2 is used. If `shadepctiles` is ``True``, the default + percentile range of 10 to 90 is used. +fade : bool, default: None + Shorthand for `fadestd`. +fadestd, fadestds, fadepctile, fadepctiles, fadedata : optional + As with `shadestd`, `shadepctile`, and `shadedata`, but for an additional, + more faded, *secondary* shaded region. If `fadestds` is ``True``, the default + standard deviation range of +/-3 is used. If `fadepctiles` is ``True``, + the default percentile range of 0 to 100 is used. +shadec, shadecolor, fadec, fadecolor : color-spec, default: None + Colors for the different shaded regions. The parent artist color is used by default. +shadez, shadezorder, fadez, fadezorder : float, default: 1.5 + The "zorder" for the different shaded regions. +shadea, shadealpha, fadea, fadealpha : float, default: 0.4, 0.2 + The opacity for the different shaded regions. +shadelw, shadelinewidth, fadelw, fadelinewidth : float, default: :rc:`patch.linewidth`. + The edge line width for the shading patches. +shdeec, shadeedgecolor, fadeec, fadeedgecolor : float, default: 'none' + The edge color for the shading patches. +shadelabel, fadelabel : bool or str, optional + Labels for the shaded regions to be used as separate legend entries. To toggle + labels "on" and apply a *default* label, use e.g. ``shadelabel=True``. To apply + a *custom* label, use e.g. ``shadelabel='label'``. Otherwise, the shading is + drawn underneath the line and/or marker in the legend entry. +inbounds : bool, default: :rc:`axes.inbounds` + Whether to restrict the default `y` (`x`) axis limits to account for only + in-bounds data when the `x` (`y`) axis limits have been locked. + See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to :func:`~matplotlib.axes.Axes.plot`. + +See also +-------- +PlotAxes.plot +PlotAxes.plotx +matplotlib.axes.Axes.plot""" + ... + + def _apply_step(self, *pairs: Incomplete, vert: Incomplete=True, where: Incomplete='pre', **kwargs: Incomplete) -> Incomplete: + """Plot the steps.""" + ... + + def step(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot step lines. + +Parameters +---------- +*args : y or x, y + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `y` coordinates are passed, try to infer the `x` coordinates + from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the + :class:`~xarray.DataArray` coordinates. Otherwise, the `x` coordinates + are ``np.arange(0, y.shape[0])``. + * If the `y` coordinates are a 2D array, plot each column of data in succession + (except where each column of data represents a statistical distribution, as with + ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +linewidth : unit-spec, default: :rc:`lines.linewidth` + The width of the line(s). Aliases: ``lw``, ``linewidths``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyle : str, default: :rc:`lines.linestyle` + The style of the line(s). Aliases: ``ls``, ``linestyles``. +color : color-spec, optional + The color of the line(s). The property `cycle` is used by default. Aliases: ``c``, ``colors``. +alpha : float, optional + The opacity of the line(s). Inferred from `color` by default. Aliases: ``a``, ``alphas``. +inbounds : bool, default: :rc:`axes.inbounds` + Whether to restrict the default `y` (`x`) axis limits to account for only + in-bounds data when the `x` (`y`) axis limits have been locked. + See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `~matplotlib.axes.Axes.step`. + +See also +-------- +PlotAxes.step +PlotAxes.stepx +matplotlib.axes.Axes.step""" + ... + + def stepx(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot step lines. + +Parameters +---------- +*args : x or y, x + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `x` coordinates are passed, try to infer the `y` coordinates + from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the + :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + are ``np.arange(0, x.shape[0])``. + * If the `x` coordinates are a 2D array, plot each column of data in succession + (except where each column of data represents a statistical distribution, as with + ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +linewidth : unit-spec, default: :rc:`lines.linewidth` + The width of the line(s). Aliases: ``lw``, ``linewidths``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyle : str, default: :rc:`lines.linestyle` + The style of the line(s). Aliases: ``ls``, ``linestyles``. +color : color-spec, optional + The color of the line(s). The property `cycle` is used by default. Aliases: ``c``, ``colors``. +alpha : float, optional + The opacity of the line(s). Inferred from `color` by default. Aliases: ``a``, ``alphas``. +inbounds : bool, default: :rc:`axes.inbounds` + Whether to restrict the default `y` (`x`) axis limits to account for only + in-bounds data when the `x` (`y`) axis limits have been locked. + See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `~matplotlib.axes.Axes.step`. + +See also +-------- +PlotAxes.step +PlotAxes.stepx +matplotlib.axes.Axes.step""" + ... + + def _apply_stem(self, x: Incomplete, y: Incomplete, *, linefmt: Incomplete=None, markerfmt: Incomplete=None, basefmt: Incomplete=None, orientation: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Plot stem lines and markers.""" + ... + + def stem(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot stem lines. + +Parameters +---------- +*args : x or y, x + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `x` coordinates are passed, try to infer the `y` coordinates + from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the + :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + are ``np.arange(0, x.shape[0])``. + * If the `x` coordinates are a 2D array, plot each column of data in succession + (except where each column of data represents a statistical distribution, as with + ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +inbounds : bool, default: :rc:`axes.inbounds` + Whether to restrict the default `y` (`x`) axis limits to account for only + in-bounds data when the `x` (`y`) axis limits have been locked. + See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `~matplotlib.axes.Axes.stem`.""" + ... + + def stemx(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot stem lines. + +Parameters +---------- +*args : x or y, x + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `x` coordinates are passed, try to infer the `y` coordinates + from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the + :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + are ``np.arange(0, x.shape[0])``. + * If the `x` coordinates are a 2D array, plot each column of data in succession + (except where each column of data represents a statistical distribution, as with + ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +inbounds : bool, default: :rc:`axes.inbounds` + Whether to restrict the default `y` (`x`) axis limits to account for only + in-bounds data when the `x` (`y`) axis limits have been locked. + See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `~matplotlib.axes.Axes.stem`.""" + ... + + def parametric(self, x: Incomplete, y: Incomplete, c: Incomplete, *, interp: Incomplete=0, scalex: Incomplete=True, scaley: Incomplete=True, **kwargs: Incomplete) -> Incomplete: + """Plot a parametric line. + +Parameters +---------- +*args : y or x, y + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `y` coordinates are passed, try to infer the `x` coordinates + from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the + :class:`~xarray.DataArray` coordinates. Otherwise, the `x` coordinates + are ``np.arange(0, y.shape[0])``. + * If the `y` coordinates are a 2D array, plot each column of data in succession + (except where each column of data represents a statistical distribution, as with + ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +c, color, colors, values, labels : sequence of float, str, or color-spec, optional + The parametric coordinate(s). These can be passed as a third positional + argument or as a keyword argument. If they are float, the colors will be + determined from `norm` and `cmap`. If they are strings, the color values + will be ``np.arange(len(colors))`` and eventual colorbar ticks will + be labeled with the strings. If they are colors, they are used for the + line segments and `cmap` is ignored -- for example, ``colors='blue'`` + makes a monochromatic "parametric" line. +interp : int, default: 0 + Interpolate to this many additional points between the parametric + coordinates. This can be increased to make the color gradations + between a small number of coordinates appear "smooth". +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` + The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor + function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization + range contains negative and positive values then :rcraw:`cmap.diverging` is used. + Otherwise :rcraw:`cmap.sequential` is used. +cmap_kw : dict-like, optional + Passed to :class:`~ultraplot.constructor.Colormap`. +c, color, colors : color-spec or sequence of color-spec, optional + The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + If not passed, `cmap` is used. +norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` + The data value normalizer, passed to the `~ultraplot.constructor.Norm` + constructor function. If `discrete` is ``True`` then 1) this affects the default + level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and + 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they + are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). + If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains + negative and positive values then `~ultraplot.colors.DivergingNorm` is used. + Otherwise `~matplotlib.colors.Normalize` is used. +norm_kw : dict-like, optional + Passed to `~ultraplot.constructor.Norm`. +extend : {'neither', 'both', 'min', 'max'}, default: 'neither' + Direction for drawing colorbar "extensions" indicating + out-of-bounds data on the end of the colorbar. +discrete : bool, default: :rc:`cmap.discrete` + If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the + colormap. Instead, for non-contour plots, the number of levels will be + roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + using `levels=large_number` but it may improve rendering speed. Default is + ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` + and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. +sequential, diverging, cyclic, qualitative : bool, default: None + Boolean arguments used if `cmap` is not passed. Set these to ``True`` + to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, + :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. + The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + as the default continuous normalizer. +vmin, vmax : float, optional + The minimum and maximum color scale values used with the `norm` normalizer. + If `discrete` is ``False`` these are the absolute limits, and if `discrete` + is ``True`` these are the approximate limits used to automatically determine + `levels` or `values` lists at "nice" intervals. If `levels` or `values` were + already passed as lists, these are ignored, and `vmin` and `vmax` are set to + the minimum and maximum of the lists. If `robust` was passed, the default `vmin` + and `vmax` are some percentile range of the data values. Otherwise, the default + `vmin` and `vmax` are the minimum and maximum of the data values. +inbounds : bool, default: :rc:`axes.inbounds` + Whether to restrict the default `y` (`x`) axis limits to account for only + in-bounds data when the `x` (`y`) axis limits have been locked. + See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. +scalex, scaley : bool, optional + Whether the view limits are adapted to the data limits. The values are + passed on to `~matplotlib.axes.Axes.autoscale_view`. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Valid :class:`~matplotlib.collections.LineCollection` properties. + +Returns +------- +:class:`~matplotlib.collections.LineCollection` + The parametric line. See `this matplotlib example `__. + +See also +-------- +PlotAxes.plot +PlotAxes.plotx +matplotlib.collections.LineCollection""" + ... + + def _apply_lines(self, xs: Incomplete, ys1: Incomplete, ys2: Incomplete, colors: Incomplete, *, vert: Incomplete=True, stack: Incomplete=None, stacked: Incomplete=None, negpos: Incomplete=False, **kwargs: Incomplete) -> Incomplete: + """Plot vertical or hotizontal lines at each point.""" + ... + + def vlines(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot vertical lines. + +Parameters +---------- +*args : y2 or x, y2, or x, y1, y2 + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `y` coordinates are passed, try to infer the `x` coordinates from + the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the :class:`~xarray.DataArray` + coordinates. Otherwise, the `x` coordinates are ``np.arange(0, y2.shape[0])``. + * If only `x` and `y2` coordinates are passed, set the `y1` coordinates + to zero. This draws elements originating from the zero line. + * If both `y1` and `y2` are provided, draw elements between these points. If + either are 2D, draw elements by iterating over each column. + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +stack, stacked : bool, default: False + Whether to "stack" lines from successive columns of y data + or plot lines on top of each other. +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +linewidth : unit-spec, default: :rc:`lines.linewidth` + The width of the line(s). Aliases: ``lw``, ``linewidths``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyle : str, default: :rc:`lines.linestyle` + The style of the line(s). Aliases: ``ls``, ``linestyles``. +color : color-spec, optional + The color of the line(s). The property `cycle` is used by default. Aliases: ``c``, ``colors``. +alpha : float, optional + The opacity of the line(s). Inferred from `color` by default. Aliases: ``a``, ``alphas``. +negpos : bool, default: False + Whether to shade lines where ``ymax >= ymin`` with `poscolor` + and where ``ymax < ymin`` with `negcolor`. If ``True`` this + function will return a length-2 silent list of handles. +negcolor, poscolor : color-spec, default: :rc:`negcolor`, :rc:`poscolor` + Colors to use for the negative and positive lines. Ignored if + `negpos` is ``False``. +inbounds : bool, default: :rc:`axes.inbounds` + Whether to restrict the default `y` (`x`) axis limits to account for only + in-bounds data when the `x` (`y`) axis limits have been locked. + See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `~matplotlib.axes.Axes.vlines`. + +See also +-------- +PlotAxes.vlines +PlotAxes.hlines +matplotlib.axes.Axes.vlines +matplotlib.axes.Axes.hlines""" + ... + + def hlines(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot horizontal lines. + +Parameters +---------- +*args : x2 or y, x2, or y, x1, x2 + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `x` coordinates are passed, try to infer the `y` coordinates from + the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the :class:`~xarray.DataArray` + coordinates. Otherwise, the `y` coordinates are ``np.arange(0, x2.shape[0])``. + * If only `y` and `x2` coordinates are passed, set the `x1` coordinates + to zero. This draws elements originating from the zero line. + * If both `x1` and `x2` are provided, draw elements between these points. If + either are 2D, draw elements by iterating over each column. + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +stack, stacked : bool, default: False + Whether to "stack" lines from successive columns of x data + or plot lines on top of each other. +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +linewidth : unit-spec, default: :rc:`lines.linewidth` + The width of the line(s). Aliases: ``lw``, ``linewidths``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyle : str, default: :rc:`lines.linestyle` + The style of the line(s). Aliases: ``ls``, ``linestyles``. +color : color-spec, optional + The color of the line(s). The property `cycle` is used by default. Aliases: ``c``, ``colors``. +alpha : float, optional + The opacity of the line(s). Inferred from `color` by default. Aliases: ``a``, ``alphas``. +negpos : bool, default: False + Whether to shade lines where ``ymax >= ymin`` with `poscolor` + and where ``ymax < ymin`` with `negcolor`. If ``True`` this + function will return a length-2 silent list of handles. +negcolor, poscolor : color-spec, default: :rc:`negcolor`, :rc:`poscolor` + Colors to use for the negative and positive lines. Ignored if + `negpos` is ``False``. +inbounds : bool, default: :rc:`axes.inbounds` + Whether to restrict the default `y` (`x`) axis limits to account for only + in-bounds data when the `x` (`y`) axis limits have been locked. + See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `~matplotlib.axes.Axes.hlines`. + +See also +-------- +PlotAxes.vlines +PlotAxes.hlines +matplotlib.axes.Axes.vlines +matplotlib.axes.Axes.hlines""" + ... + + def _parse_markersize(self, s: Incomplete, *, smin: Incomplete=None, smax: Incomplete=None, area_size: Incomplete=True, absolute_size: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Scale the marker sizes with optional keyword args.""" + ... + + def _apply_scatter(self, xs: Incomplete, ys: Incomplete, ss: Incomplete, cc: Incomplete, *, vert: Incomplete=True, **kwargs: Incomplete) -> Incomplete: + """Apply scatter or scatterx markers.""" + ... + + def scatter(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot markers with flexible keyword arguments. + +Parameters +---------- +*args : y or x, y + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `y` coordinates are passed, try to infer the `x` coordinates + from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the + :class:`~xarray.DataArray` coordinates. Otherwise, the `x` coordinates + are ``np.arange(0, y.shape[0])``. + * If the `y` coordinates are a 2D array, plot each column of data in succession + (except where each column of data represents a statistical distribution, as with + ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +s, size, ms, markersize : float or array-like or unit-spec, optional + The marker size area(s). If this is an array matching the shape of `x` and `y`, + the units are scaled by `smin` and `smax`. If this contains unit string(s), it + is processed by `~ultraplot.utils.units` and represents the width rather than area. +c, color, colors, mc, markercolor, markercolors, fc, facecolor, facecolors : array-like or color-spec, optional + The marker color(s). If this is an array matching the shape of `x` and `y`, + the colors are generated using `cmap`, `norm`, `vmin`, and `vmax`. Otherwise, + this should be a valid matplotlib color. To pass explicit RGB(A) colors, + use an ``N x 3`` or ``N x 4`` array, or pass a single color with `color=`. + One-dimensional numeric arrays matching the point count are interpreted as + scalar values for colormapping. +smin, smax : float, optional + The minimum and maximum marker size area in units ``points ** 2``. Ignored + if `absolute_size` is ``True``. Default value for `smin` is ``1`` and for + `smax` is the square of :rc:`lines.markersize`. +area_size : bool, default: True + Whether the marker sizes `s` are scaled by area or by radius. The default + ``True`` is consistent with matplotlib. When `absolute_size` is ``True``, + the `s` units are ``points ** 2`` if `area_size` is ``True`` and ``points`` + if `area_size` is ``False``. +absolute_size : bool, default: True or False + Whether `s` should be taken to represent "absolute" marker sizes in units + ``points`` or ``points ** 2`` or "relative" marker sizes scaled by `smin` + and `smax`. Default is ``True`` if `s` is scalar and ``False`` if `s` is + array-like or `smin` or `smax` were passed. +vmin, vmax : float, optional + The minimum and maximum color scale values used with the `norm` normalizer. + If `discrete` is ``False`` these are the absolute limits, and if `discrete` + is ``True`` these are the approximate limits used to automatically determine + `levels` or `values` lists at "nice" intervals. If `levels` or `values` were + already passed as lists, these are ignored, and `vmin` and `vmax` are set to + the minimum and maximum of the lists. If `robust` was passed, the default `vmin` + and `vmax` are some percentile range of the data values. Otherwise, the default + `vmin` and `vmax` are the minimum and maximum of the data values. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` + The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor + function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization + range contains negative and positive values then :rcraw:`cmap.diverging` is used. + Otherwise :rcraw:`cmap.sequential` is used. +cmap_kw : dict-like, optional + Passed to :class:`~ultraplot.constructor.Colormap`. +c, color, colors : color-spec or sequence of color-spec, optional + The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + If not passed, `cmap` is used. +norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` + The data value normalizer, passed to the `~ultraplot.constructor.Norm` + constructor function. If `discrete` is ``True`` then 1) this affects the default + level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and + 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they + are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). + If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains + negative and positive values then `~ultraplot.colors.DivergingNorm` is used. + Otherwise `~matplotlib.colors.Normalize` is used. +norm_kw : dict-like, optional + Passed to `~ultraplot.constructor.Norm`. +extend : {'neither', 'both', 'min', 'max'}, default: 'neither' + Direction for drawing colorbar "extensions" indicating + out-of-bounds data on the end of the colorbar. +discrete : bool, default: :rc:`cmap.discrete` + If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the + colormap. Instead, for non-contour plots, the number of levels will be + roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + using `levels=large_number` but it may improve rendering speed. Default is + ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` + and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. +sequential, diverging, cyclic, qualitative : bool, default: None + Boolean arguments used if `cmap` is not passed. Set these to ``True`` + to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, + :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. + The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + as the default continuous normalizer. +N + Shorthand for `levels`. +levels : int or sequence of float, default: :rc:`cmap.levels` + The number of level edges or a sequence of level edges. If the former, `locator` + is used to generate this many level edges at "nice" intervals. If the latter, + the levels should be monotonically increasing or decreasing (note decreasing + levels fail with ``contour`` plots). +values : int or sequence of float, default: None + The number of level centers or a sequence of level centers. If the former, + `locator` is used to generate this many level centers at "nice" intervals. + If the latter, levels are inferred using `~ultraplot.utils.edges`. + This will override any `levels` input. +center_levels : bool, default False + If set to true, the discrete color bar bins will be centered on the level values + instead of using the level values as the edges of the discrete bins. This option + can be used for diverging, discrete color bars with both positive and negative + data to ensure data near zero is properly represented. +robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` + If ``True`` and `vmin` or `vmax` were not provided, they are + determined from the 2nd and 98th data percentiles rather than the + minimum and maximum. If float, this percentile range is used (for example, + ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, + these specific percentiles should be used. This feature is useful + when your data has large outliers. +inbounds : bool, default: :rc:`cmap.inbounds` + If ``True`` and `vmin` or `vmax` were not provided, when axis limits + have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` + or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. + See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. +locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + The locator used to determine level locations if `levels` or `values` were not + already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. + Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. +locator_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Locator` class. +symmetric : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + symmetric about zero. +positive : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + positive with a minimum at zero. +negative : bool, default: False + If ``True``, the normaliation range or discrete colormap levels are + negative with a minimum at zero. +nozero : bool, default: False + If ``True``, ``0`` is removed from the level list. This is mainly useful for + single-color `~matplotlib.axes.Axes.contour` plots. +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +lw, linewidth, linewidths, mew, markeredgewidth, markeredgewidths : float or sequence, optional + The marker edge width(s). +edgecolors, markeredgecolor, markeredgecolors : color-spec or sequence, optional + The marker edge color(s). +mean, means : bool, default: False + Whether to plot the means of each column for 2D `y` coordinates. Means + are calculated with `numpy.nanmean`. If no other arguments are specified, + this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). +median, medians : bool, default: False + Whether to plot the medians of each column for 2D `y` coordinates. Medians + are calculated with `numpy.nanmedian`. If no other arguments arguments are + specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). +bars : bool, default: None + Shorthand for `barstd`, `barstds`. +barstd, barstds : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. Standard deviation multiples for + *thin error bars* with optional whiskers (i.e., caps). If scalar, then +/- that + multiple is used. If ``True``, the default standard deviation range of +/-3 is used. +barpctile, barpctiles : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. As with `barstd`, but instead + using percentiles for the error bars. If scalar, that percentile range is + used (e.g., ``90`` shows the 5th to 95th percentiles). If ``True``, the default + percentile range of 0 to 100 is used. +bardata : array-like, optional + Valid only if `mean` and `median` are ``False``. If shape is 2 x N, these + are the lower and upper bounds for the thin error bars. If shape is N, these + are the absolute, symmetric deviations from the central points. +boxes : bool, default: None + Shorthand for `boxstd`, `boxstds`. +boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional + As with `barstd`, `barpctile`, and `bardata`, but for *thicker error bars* + representing a smaller interval than the thin error bars. If `boxstds` is + ``True``, the default standard deviation range of +/-1 is used. If `boxpctiles` + is ``True``, the default percentile range of 25 to 75 is used (i.e., the + interquartile range). When "boxes" and "bars" are combined, this has the + effect of drawing miniature box-and-whisker plots. +capsize : float, default: :rc:`errorbar.capsize` + The cap size for thin error bars in points. +barz, barzorder, boxz, boxzorder : float, default: 2.5 + The "zorder" for the thin and thick error bars. +barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` + Colors for the thin and thick error bars. +barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` + Line widths for the thin and thick error bars, in points. The default for boxes + is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. +boxm, boxmarker : bool or marker-spec, default: 'o' + Whether to draw a small marker in the middle of the box denoting + the mean or median position. Ignored if `boxes` is ``False``. +boxms, boxmarkersize : size-spec, default: ``(2 * boxlinewidth) ** 2`` + The marker size for the `boxmarker` marker in points ** 2. +boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor : color-spec, default: 'w' + Color, face color, and edge color for the `boxmarker` marker. +shade : bool, default: None + Shorthand for `shadestd`. +shadestd, shadestds, shadepctile, shadepctiles, shadedata : optional + As with `barstd`, `barpctile`, and `bardata`, but using *shading* to indicate + the error range. If `shadestds` is ``True``, the default standard deviation + range of +/-2 is used. If `shadepctiles` is ``True``, the default + percentile range of 10 to 90 is used. +fade : bool, default: None + Shorthand for `fadestd`. +fadestd, fadestds, fadepctile, fadepctiles, fadedata : optional + As with `shadestd`, `shadepctile`, and `shadedata`, but for an additional, + more faded, *secondary* shaded region. If `fadestds` is ``True``, the default + standard deviation range of +/-3 is used. If `fadepctiles` is ``True``, + the default percentile range of 0 to 100 is used. +shadec, shadecolor, fadec, fadecolor : color-spec, default: None + Colors for the different shaded regions. The parent artist color is used by default. +shadez, shadezorder, fadez, fadezorder : float, default: 1.5 + The "zorder" for the different shaded regions. +shadea, shadealpha, fadea, fadealpha : float, default: 0.4, 0.2 + The opacity for the different shaded regions. +shadelw, shadelinewidth, fadelw, fadelinewidth : float, default: :rc:`patch.linewidth`. + The edge line width for the shading patches. +shdeec, shadeedgecolor, fadeec, fadeedgecolor : float, default: 'none' + The edge color for the shading patches. +shadelabel, fadelabel : bool or str, optional + Labels for the shaded regions to be used as separate legend entries. To toggle + labels "on" and apply a *default* label, use e.g. ``shadelabel=True``. To apply + a *custom* label, use e.g. ``shadelabel='label'``. Otherwise, the shading is + drawn underneath the line and/or marker in the legend entry. +inbounds : bool, default: :rc:`axes.inbounds` + Whether to restrict the default `y` (`x`) axis limits to account for only + in-bounds data when the `x` (`y`) axis limits have been locked. + See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `~matplotlib.axes.Axes.scatter`. + +See also +-------- +PlotAxes.scatter +PlotAxes.scatterx +matplotlib.axes.Axes.scatter""" + ... + + def scatterx(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot markers with flexible keyword arguments. + +Parameters +---------- +*args : x or y, x + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `x` coordinates are passed, try to infer the `y` coordinates + from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the + :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + are ``np.arange(0, x.shape[0])``. + * If the `x` coordinates are a 2D array, plot each column of data in succession + (except where each column of data represents a statistical distribution, as with + ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +s, size, ms, markersize : float or array-like or unit-spec, optional + The marker size area(s). If this is an array matching the shape of `x` and `y`, + the units are scaled by `smin` and `smax`. If this contains unit string(s), it + is processed by `~ultraplot.utils.units` and represents the width rather than area. +c, color, colors, mc, markercolor, markercolors, fc, facecolor, facecolors : array-like or color-spec, optional + The marker color(s). If this is an array matching the shape of `x` and `y`, + the colors are generated using `cmap`, `norm`, `vmin`, and `vmax`. Otherwise, + this should be a valid matplotlib color. To pass explicit RGB(A) colors, + use an ``N x 3`` or ``N x 4`` array, or pass a single color with `color=`. + One-dimensional numeric arrays matching the point count are interpreted as + scalar values for colormapping. +smin, smax : float, optional + The minimum and maximum marker size area in units ``points ** 2``. Ignored + if `absolute_size` is ``True``. Default value for `smin` is ``1`` and for + `smax` is the square of :rc:`lines.markersize`. +area_size : bool, default: True + Whether the marker sizes `s` are scaled by area or by radius. The default + ``True`` is consistent with matplotlib. When `absolute_size` is ``True``, + the `s` units are ``points ** 2`` if `area_size` is ``True`` and ``points`` + if `area_size` is ``False``. +absolute_size : bool, default: True or False + Whether `s` should be taken to represent "absolute" marker sizes in units + ``points`` or ``points ** 2`` or "relative" marker sizes scaled by `smin` + and `smax`. Default is ``True`` if `s` is scalar and ``False`` if `s` is + array-like or `smin` or `smax` were passed. +vmin, vmax : float, optional + The minimum and maximum color scale values used with the `norm` normalizer. + If `discrete` is ``False`` these are the absolute limits, and if `discrete` + is ``True`` these are the approximate limits used to automatically determine + `levels` or `values` lists at "nice" intervals. If `levels` or `values` were + already passed as lists, these are ignored, and `vmin` and `vmax` are set to + the minimum and maximum of the lists. If `robust` was passed, the default `vmin` + and `vmax` are some percentile range of the data values. Otherwise, the default + `vmin` and `vmax` are the minimum and maximum of the data values. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` + The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor + function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization + range contains negative and positive values then :rcraw:`cmap.diverging` is used. + Otherwise :rcraw:`cmap.sequential` is used. +cmap_kw : dict-like, optional + Passed to :class:`~ultraplot.constructor.Colormap`. +c, color, colors : color-spec or sequence of color-spec, optional + The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + If not passed, `cmap` is used. +norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` + The data value normalizer, passed to the `~ultraplot.constructor.Norm` + constructor function. If `discrete` is ``True`` then 1) this affects the default + level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and + 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they + are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). + If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains + negative and positive values then `~ultraplot.colors.DivergingNorm` is used. + Otherwise `~matplotlib.colors.Normalize` is used. +norm_kw : dict-like, optional + Passed to `~ultraplot.constructor.Norm`. +extend : {'neither', 'both', 'min', 'max'}, default: 'neither' + Direction for drawing colorbar "extensions" indicating + out-of-bounds data on the end of the colorbar. +discrete : bool, default: :rc:`cmap.discrete` + If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the + colormap. Instead, for non-contour plots, the number of levels will be + roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + using `levels=large_number` but it may improve rendering speed. Default is + ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` + and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. +sequential, diverging, cyclic, qualitative : bool, default: None + Boolean arguments used if `cmap` is not passed. Set these to ``True`` + to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, + :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. + The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + as the default continuous normalizer. +N + Shorthand for `levels`. +levels : int or sequence of float, default: :rc:`cmap.levels` + The number of level edges or a sequence of level edges. If the former, `locator` + is used to generate this many level edges at "nice" intervals. If the latter, + the levels should be monotonically increasing or decreasing (note decreasing + levels fail with ``contour`` plots). +values : int or sequence of float, default: None + The number of level centers or a sequence of level centers. If the former, + `locator` is used to generate this many level centers at "nice" intervals. + If the latter, levels are inferred using `~ultraplot.utils.edges`. + This will override any `levels` input. +center_levels : bool, default False + If set to true, the discrete color bar bins will be centered on the level values + instead of using the level values as the edges of the discrete bins. This option + can be used for diverging, discrete color bars with both positive and negative + data to ensure data near zero is properly represented. +robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` + If ``True`` and `vmin` or `vmax` were not provided, they are + determined from the 2nd and 98th data percentiles rather than the + minimum and maximum. If float, this percentile range is used (for example, + ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, + these specific percentiles should be used. This feature is useful + when your data has large outliers. +inbounds : bool, default: :rc:`cmap.inbounds` + If ``True`` and `vmin` or `vmax` were not provided, when axis limits + have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` + or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. + See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. +locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + The locator used to determine level locations if `levels` or `values` were not + already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. + Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. +locator_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Locator` class. +symmetric : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + symmetric about zero. +positive : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + positive with a minimum at zero. +negative : bool, default: False + If ``True``, the normaliation range or discrete colormap levels are + negative with a minimum at zero. +nozero : bool, default: False + If ``True``, ``0`` is removed from the level list. This is mainly useful for + single-color `~matplotlib.axes.Axes.contour` plots. +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +lw, linewidth, linewidths, mew, markeredgewidth, markeredgewidths : float or sequence, optional + The marker edge width(s). +edgecolors, markeredgecolor, markeredgecolors : color-spec or sequence, optional + The marker edge color(s). +mean, means : bool, default: False + Whether to plot the means of each column for 2D `x` coordinates. Means + are calculated with `numpy.nanmean`. If no other arguments are specified, + this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). +median, medians : bool, default: False + Whether to plot the medians of each column for 2D `x` coordinates. Medians + are calculated with `numpy.nanmedian`. If no other arguments arguments are + specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). +bars : bool, default: None + Shorthand for `barstd`, `barstds`. +barstd, barstds : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. Standard deviation multiples for + *thin error bars* with optional whiskers (i.e., caps). If scalar, then +/- that + multiple is used. If ``True``, the default standard deviation range of +/-3 is used. +barpctile, barpctiles : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. As with `barstd`, but instead + using percentiles for the error bars. If scalar, that percentile range is + used (e.g., ``90`` shows the 5th to 95th percentiles). If ``True``, the default + percentile range of 0 to 100 is used. +bardata : array-like, optional + Valid only if `mean` and `median` are ``False``. If shape is 2 x N, these + are the lower and upper bounds for the thin error bars. If shape is N, these + are the absolute, symmetric deviations from the central points. +boxes : bool, default: None + Shorthand for `boxstd`, `boxstds`. +boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional + As with `barstd`, `barpctile`, and `bardata`, but for *thicker error bars* + representing a smaller interval than the thin error bars. If `boxstds` is + ``True``, the default standard deviation range of +/-1 is used. If `boxpctiles` + is ``True``, the default percentile range of 25 to 75 is used (i.e., the + interquartile range). When "boxes" and "bars" are combined, this has the + effect of drawing miniature box-and-whisker plots. +capsize : float, default: :rc:`errorbar.capsize` + The cap size for thin error bars in points. +barz, barzorder, boxz, boxzorder : float, default: 2.5 + The "zorder" for the thin and thick error bars. +barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` + Colors for the thin and thick error bars. +barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` + Line widths for the thin and thick error bars, in points. The default for boxes + is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. +boxm, boxmarker : bool or marker-spec, default: 'o' + Whether to draw a small marker in the middle of the box denoting + the mean or median position. Ignored if `boxes` is ``False``. +boxms, boxmarkersize : size-spec, default: ``(2 * boxlinewidth) ** 2`` + The marker size for the `boxmarker` marker in points ** 2. +boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor : color-spec, default: 'w' + Color, face color, and edge color for the `boxmarker` marker. +shade : bool, default: None + Shorthand for `shadestd`. +shadestd, shadestds, shadepctile, shadepctiles, shadedata : optional + As with `barstd`, `barpctile`, and `bardata`, but using *shading* to indicate + the error range. If `shadestds` is ``True``, the default standard deviation + range of +/-2 is used. If `shadepctiles` is ``True``, the default + percentile range of 10 to 90 is used. +fade : bool, default: None + Shorthand for `fadestd`. +fadestd, fadestds, fadepctile, fadepctiles, fadedata : optional + As with `shadestd`, `shadepctile`, and `shadedata`, but for an additional, + more faded, *secondary* shaded region. If `fadestds` is ``True``, the default + standard deviation range of +/-3 is used. If `fadepctiles` is ``True``, + the default percentile range of 0 to 100 is used. +shadec, shadecolor, fadec, fadecolor : color-spec, default: None + Colors for the different shaded regions. The parent artist color is used by default. +shadez, shadezorder, fadez, fadezorder : float, default: 1.5 + The "zorder" for the different shaded regions. +shadea, shadealpha, fadea, fadealpha : float, default: 0.4, 0.2 + The opacity for the different shaded regions. +shadelw, shadelinewidth, fadelw, fadelinewidth : float, default: :rc:`patch.linewidth`. + The edge line width for the shading patches. +shdeec, shadeedgecolor, fadeec, fadeedgecolor : float, default: 'none' + The edge color for the shading patches. +shadelabel, fadelabel : bool or str, optional + Labels for the shaded regions to be used as separate legend entries. To toggle + labels "on" and apply a *default* label, use e.g. ``shadelabel=True``. To apply + a *custom* label, use e.g. ``shadelabel='label'``. Otherwise, the shading is + drawn underneath the line and/or marker in the legend entry. +inbounds : bool, default: :rc:`axes.inbounds` + Whether to restrict the default `y` (`x`) axis limits to account for only + in-bounds data when the `x` (`y`) axis limits have been locked. + See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `~matplotlib.axes.Axes.scatter`. + +See also +-------- +PlotAxes.scatter +PlotAxes.scatterx +matplotlib.axes.Axes.scatter""" + ... + + def _apply_fill(self, xs: Incomplete, ys1: Incomplete, ys2: Incomplete, where: Incomplete, *, vert: Incomplete=True, negpos: Incomplete=None, stack: Incomplete=None, stacked: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Apply area shading using `fill_between` or `fill_betweenx`. + +This is the internal implementation for `fill_between`, `fill_betweenx`, +`area`, and `areax`. + +Parameters +---------- +xs, ys1, ys2 : array-like + The x and y coordinates for the shaded regions. +where : array-like, optional + A boolean mask for the points that should be shaded. +vert : bool, optional + The orientation of the shading. If `True` (default), `fill_between` + is used. If `False`, `fill_betweenx` is used. +negpos : bool, optional + Whether to use different colors for positive and negative shades. +stack : bool, optional + Whether to stack shaded regions. +**kwargs + Additional keyword arguments passed to the matplotlib fill function. + +Notes +----- +Special handling for plots from external packages (e.g., seaborn): + +When this method is used in a context where plots are generated by +an external library like seaborn, it tags the resulting polygons +(e.g., confidence intervals) as "synthetic". This is done unless a +user explicitly provides a label. + +Synthetic artists are marked with `_ultraplot_synthetic=True` and given +a label starting with an underscore (e.g., `_ultraplot_fill`). This +prevents them from being automatically included in legends, keeping the +legend clean and focused on user-specified elements. + +Seaborn internally generates tags like "y", "ymin", and "ymax" for +vertical fills, and "x", "xmin", "xmax" for horizontal fills. UltraPlot +recognizes these and treats them as synthetic unless a different label +is provided.""" + ... + + def area(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot individual, grouped, or overlaid shading patches. + +Parameters +---------- +*args : y2 or x, y2, or x, y1, y2 + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `y` coordinates are passed, try to infer the `x` coordinates from + the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the :class:`~xarray.DataArray` + coordinates. Otherwise, the `x` coordinates are ``np.arange(0, y2.shape[0])``. + * If only `x` and `y2` coordinates are passed, set the `y1` coordinates + to zero. This draws elements originating from the zero line. + * If both `y1` and `y2` are provided, draw elements between these points. If + either are 2D, draw elements by iterating over each column. + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +stack, stacked : bool, default: False + Whether to "stack" area patches from successive columns of y + data or plot area patches on top of each other. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +where : ndarray, optional + A boolean mask for the points that should be shaded. + See `this matplotlib example `__. +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +linewidth : unit-spec, default: :rc:`patch.linewidth` + The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyle : str, default: '-' + The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. +edgecolor : color-spec, default: 'none' + The edge color of the patch(es). Aliases: ``ec``, ``edgecolors``. +facecolor : color-spec, optional + The face color of the patch(es). The property `cycle` is used by default. Aliases: ``fc``, ``facecolors``, ``fillcolor``, ``fillcolors``. +alpha : float, optional + The opacity of the patch(es). Inferred from `facecolor` and `edgecolor` by default. Aliases: ``a``, ``alphas``. +negpos : bool, default: False + Whether to shade patches where ``y2 >= y1`` with `poscolor` + and where ``y2 < y1`` with `negcolor`. If ``True`` this + function will return a length-2 silent list of handles. +negcolor, poscolor : color-spec, default: :rc:`negcolor`, :rc:`poscolor` + Colors to use for the negative and positive patches. Ignored if + `negpos` is ``False``. +edgefix : bool or float, default: :rc:`edgefix` + Whether to fix the common issue where white lines appear between adjacent + patches in saved vector graphics (this can slow down figure rendering). + See this `github repo `__ for a + demonstration of the problem. If ``True``, a small default linewidth of + ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), + this specific linewidth is used to cover up the white lines. This feature is + automatically disabled when the patches have transparency. +inbounds : bool, default: :rc:`axes.inbounds` + Whether to restrict the default `y` (`x`) axis limits to account for only + in-bounds data when the `x` (`y`) axis limits have been locked. + See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `~matplotlib.axes.Axes.fill_between`. + +See also +-------- +PlotAxes.area +PlotAxes.areax +PlotAxes.fill_between +PlotAxes.fill_betweenx +matplotlib.axes.Axes.fill_between +matplotlib.axes.Axes.fill_betweenx""" + ... + + def areax(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot individual, grouped, or overlaid shading patches. + +Parameters +---------- +*args : x2 or y, x2, or y, x1, x2 + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `x` coordinates are passed, try to infer the `y` coordinates from + the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the :class:`~xarray.DataArray` + coordinates. Otherwise, the `y` coordinates are ``np.arange(0, x2.shape[0])``. + * If only `y` and `x2` coordinates are passed, set the `x1` coordinates + to zero. This draws elements originating from the zero line. + * If both `x1` and `x2` are provided, draw elements between these points. If + either are 2D, draw elements by iterating over each column. + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +stack, stacked : bool, default: False + Whether to "stack" area patches from successive columns of x + data or plot area patches on top of each other. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +where : ndarray, optional + A boolean mask for the points that should be shaded. + See `this matplotlib example `__. +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +linewidth : unit-spec, default: :rc:`patch.linewidth` + The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyle : str, default: '-' + The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. +edgecolor : color-spec, default: 'none' + The edge color of the patch(es). Aliases: ``ec``, ``edgecolors``. +facecolor : color-spec, optional + The face color of the patch(es). The property `cycle` is used by default. Aliases: ``fc``, ``facecolors``, ``fillcolor``, ``fillcolors``. +alpha : float, optional + The opacity of the patch(es). Inferred from `facecolor` and `edgecolor` by default. Aliases: ``a``, ``alphas``. +negpos : bool, default: False + Whether to shade patches where ``y2 >= y1`` with `poscolor` + and where ``y2 < y1`` with `negcolor`. If ``True`` this + function will return a length-2 silent list of handles. +negcolor, poscolor : color-spec, default: :rc:`negcolor`, :rc:`poscolor` + Colors to use for the negative and positive patches. Ignored if + `negpos` is ``False``. +edgefix : bool or float, default: :rc:`edgefix` + Whether to fix the common issue where white lines appear between adjacent + patches in saved vector graphics (this can slow down figure rendering). + See this `github repo `__ for a + demonstration of the problem. If ``True``, a small default linewidth of + ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), + this specific linewidth is used to cover up the white lines. This feature is + automatically disabled when the patches have transparency. +inbounds : bool, default: :rc:`axes.inbounds` + Whether to restrict the default `y` (`x`) axis limits to account for only + in-bounds data when the `x` (`y`) axis limits have been locked. + See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `~matplotlib.axes.Axes.fill_betweenx`. + +See also +-------- +PlotAxes.area +PlotAxes.areax +PlotAxes.fill_between +PlotAxes.fill_betweenx +matplotlib.axes.Axes.fill_between +matplotlib.axes.Axes.fill_betweenx""" + ... + + def fill_between(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot individual, grouped, or overlaid shading patches. + +Parameters +---------- +*args : y2 or x, y2, or x, y1, y2 + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `y` coordinates are passed, try to infer the `x` coordinates from + the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the :class:`~xarray.DataArray` + coordinates. Otherwise, the `x` coordinates are ``np.arange(0, y2.shape[0])``. + * If only `x` and `y2` coordinates are passed, set the `y1` coordinates + to zero. This draws elements originating from the zero line. + * If both `y1` and `y2` are provided, draw elements between these points. If + either are 2D, draw elements by iterating over each column. + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +stack, stacked : bool, default: False + Whether to "stack" area patches from successive columns of y + data or plot area patches on top of each other. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +where : ndarray, optional + A boolean mask for the points that should be shaded. + See `this matplotlib example `__. +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +linewidth : unit-spec, default: :rc:`patch.linewidth` + The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyle : str, default: '-' + The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. +edgecolor : color-spec, default: 'none' + The edge color of the patch(es). Aliases: ``ec``, ``edgecolors``. +facecolor : color-spec, optional + The face color of the patch(es). The property `cycle` is used by default. Aliases: ``fc``, ``facecolors``, ``fillcolor``, ``fillcolors``. +alpha : float, optional + The opacity of the patch(es). Inferred from `facecolor` and `edgecolor` by default. Aliases: ``a``, ``alphas``. +negpos : bool, default: False + Whether to shade patches where ``y2 >= y1`` with `poscolor` + and where ``y2 < y1`` with `negcolor`. If ``True`` this + function will return a length-2 silent list of handles. +negcolor, poscolor : color-spec, default: :rc:`negcolor`, :rc:`poscolor` + Colors to use for the negative and positive patches. Ignored if + `negpos` is ``False``. +edgefix : bool or float, default: :rc:`edgefix` + Whether to fix the common issue where white lines appear between adjacent + patches in saved vector graphics (this can slow down figure rendering). + See this `github repo `__ for a + demonstration of the problem. If ``True``, a small default linewidth of + ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), + this specific linewidth is used to cover up the white lines. This feature is + automatically disabled when the patches have transparency. +inbounds : bool, default: :rc:`axes.inbounds` + Whether to restrict the default `y` (`x`) axis limits to account for only + in-bounds data when the `x` (`y`) axis limits have been locked. + See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `~matplotlib.axes.Axes.fill_between`. + +See also +-------- +PlotAxes.area +PlotAxes.areax +PlotAxes.fill_between +PlotAxes.fill_betweenx +matplotlib.axes.Axes.fill_between +matplotlib.axes.Axes.fill_betweenx""" + ... + + def fill_betweenx(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot individual, grouped, or overlaid shading patches. + +Parameters +---------- +*args : x2 or y, x2, or y, x1, x2 + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `x` coordinates are passed, try to infer the `y` coordinates from + the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the :class:`~xarray.DataArray` + coordinates. Otherwise, the `y` coordinates are ``np.arange(0, x2.shape[0])``. + * If only `y` and `x2` coordinates are passed, set the `x1` coordinates + to zero. This draws elements originating from the zero line. + * If both `x1` and `x2` are provided, draw elements between these points. If + either are 2D, draw elements by iterating over each column. + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +stack, stacked : bool, default: False + Whether to "stack" area patches from successive columns of x + data or plot area patches on top of each other. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +where : ndarray, optional + A boolean mask for the points that should be shaded. + See `this matplotlib example `__. +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +linewidth : unit-spec, default: :rc:`patch.linewidth` + The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyle : str, default: '-' + The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. +edgecolor : color-spec, default: 'none' + The edge color of the patch(es). Aliases: ``ec``, ``edgecolors``. +facecolor : color-spec, optional + The face color of the patch(es). The property `cycle` is used by default. Aliases: ``fc``, ``facecolors``, ``fillcolor``, ``fillcolors``. +alpha : float, optional + The opacity of the patch(es). Inferred from `facecolor` and `edgecolor` by default. Aliases: ``a``, ``alphas``. +negpos : bool, default: False + Whether to shade patches where ``y2 >= y1`` with `poscolor` + and where ``y2 < y1`` with `negcolor`. If ``True`` this + function will return a length-2 silent list of handles. +negcolor, poscolor : color-spec, default: :rc:`negcolor`, :rc:`poscolor` + Colors to use for the negative and positive patches. Ignored if + `negpos` is ``False``. +edgefix : bool or float, default: :rc:`edgefix` + Whether to fix the common issue where white lines appear between adjacent + patches in saved vector graphics (this can slow down figure rendering). + See this `github repo `__ for a + demonstration of the problem. If ``True``, a small default linewidth of + ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), + this specific linewidth is used to cover up the white lines. This feature is + automatically disabled when the patches have transparency. +inbounds : bool, default: :rc:`axes.inbounds` + Whether to restrict the default `y` (`x`) axis limits to account for only + in-bounds data when the `x` (`y`) axis limits have been locked. + See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `~matplotlib.axes.Axes.fill_betweenx`. + +See also +-------- +PlotAxes.area +PlotAxes.areax +PlotAxes.fill_between +PlotAxes.fill_betweenx +matplotlib.axes.Axes.fill_between +matplotlib.axes.Axes.fill_betweenx""" + ... + + def graph(self, g: Incomplete, layout: Union[str, dict, Callable]=None, nodes: Union[None, bool, Iterable]=None, edges: Union[None, bool, Iterable]=None, labels: Union[None, bool, Iterable]=None, layout_kw: Optional[dict]=None, node_kw: Optional[dict]=None, edge_kw: Optional[dict]=None, label_kw: Optional[dict]=None, rescale: Union[None, bool]=None) -> Incomplete: + """Plot a networkx graph with flexible node, edge, and label options. + +Parameters +---------- +g : networkx.Graph + The graph object to be plotted. Can be any subclass of :class:`~networkx.Graph`, such as + :class:`~networkx.DiGraph` or :class:`~networkx.MultiGraph`. +layout : callable or dict, optional + A layout function or a precomputed dict mapping nodes to 2D positions. If a function + is given, it is called as ``layout(g, **layout_kw)`` to compute positions. See :func:`networkx.drawing.nx_pylab.draw` for more information. +nodes : bool or iterable, default: rc["graph.draw_nodes"] + Which nodes to draw. If `True`, all nodes are drawn. If an iterable is provided, only + the specified nodes are included. This effectively acts as `nodelist` in :func:`networkx.drawing.nx_pylab.draw_networkx_nodes`. +edges : bool or iterable, default: rc["graph.draw_edges"] + Which edges to draw. If `True`, all edges are drawn. If an iterable of edge tuples is + provided, only those edges are included. This effectively acts as `edgelist` in :func:`networkx.drawing.nx_pylab.draw_networkx_edges`. +labels : bool or iterable, default: `rc["graph.draw_labels`] + Whether to show node labels. If `True`, labels are drawn using node names. If an + iterable is given, only those nodes are labeled. +layout_kw : dict, default: {} + Keyword arguments passed to the layout function, if `layout` is callable, see `networkx's drawing functions `_ for more information. +node_kw : dict, default: {} + Additional keyword arguments passed to the node drawing function (see :func:`networkx.drawing.nx_pylab.draw_networkx_nodes`). These can include + size, color, edgecolor, cmap, alpha, etc., depending on the backend used, see :func:`networkx.drawing.nx_pylab.draw_networkx_nodes`. +edge_kw : dict, default: {} + Additional keyword arguments passed to the edge drawing function. These can include + width, color, style, alpha, arrows, etc (see :func:`networkx.drawing.nx_pylab.draw_networkx_edges`). +label_kw : dict, default: {} + Additional keyword arguments passed to the label drawing function, such as font size, + font color, background color, alignment, etc (see :func:`networkx.drawing.nx_pylab.draw_networkx_labels`). +rescale : bool, None, default: None. + When set to none it checks for `rc["graph.rescale"]` which defaults to `True`. This performs a rescale such that the node position is within a [0, 1] x [0, 1] box. +Returns +------- +Nodes, edges, labels output from the networkx drawing functions. + +See also +-------- +networkx.draw +networkx.draw_networkx +networkx.draw_networkx_nodes +networkx.draw_networkx_edges +networkx.draw_networkx_labels""" + ... + + @staticmethod + def _convert_bar_width(x: Incomplete, width: Incomplete=1) -> Incomplete: + """Convert bar plot widths from relative to coordinate spacing. Relative +widths are much more convenient for users.""" + ... + + def _apply_bar(self, xs: Incomplete, hs: Incomplete, ws: Incomplete, bs: Incomplete, *, absolute_width: Incomplete=None, stack: Incomplete=None, stacked: Incomplete=None, negpos: Incomplete=False, orientation: Incomplete='vertical', **kwargs: Incomplete) -> Incomplete: + """Apply bar or barh command. Support default "minima" at zero.""" + ... + + def _add_bar_labels(self, container: Incomplete, *, orientation: Incomplete='horizontal', **kwargs: Incomplete) -> Incomplete: + """Automatically add bar labels and rescale the +limits to produce a striking visual image.""" + ... + + def bar(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot individual, grouped, or stacked bars. + +Parameters +---------- +*args : y or x, y + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `y` coordinates are passed, try to infer the `x` coordinates + from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the + :class:`~xarray.DataArray` coordinates. Otherwise, the `x` coordinates + are ``np.arange(0, y.shape[0])``. + * If the `y` coordinates are a 2D array, plot each column of data in succession + (except where each column of data represents a statistical distribution, as with + ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +width : float or array-like, default: 0.8 + The width(s) of the bars. Can be passed as a third positional argument. If + `absolute_width` is ``True`` (the default) these are in units relative to the + x coordinate step size. Otherwise these are in x coordinate units. +bottom : float or array-like, default: 0 + The coordinate(s) of the bottom edge of the bars. + Can be passed as a fourth positional argument. +absolute_width : bool, default: False + Whether to make the `width` units *absolute*. If ``True``, + this restores the default matplotlib behavior. +stack, stacked : bool, default: False + Whether to "stack" bars from successive columns of y + data or plot bars side-by-side in groups. +bar_labels : bool, default rc["bar.bar_labels"] + Whether to show the height values for vertical bars or width values for horizontal bars. +bar_labels_kw : dict, default None + Keywords to format the bar_labels, see :func:`~matplotlib.pyplot.bar_label`. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +linewidth : unit-spec, default: :rc:`patch.linewidth` + The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyle : str, default: '-' + The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. +edgecolor : color-spec, default: 'none' + The edge color of the patch(es). Aliases: ``ec``, ``edgecolors``. +facecolor : color-spec, optional + The face color of the patch(es). The property `cycle` is used by default. Aliases: ``fc``, ``facecolors``, ``fillcolor``, ``fillcolors``. +alpha : float, optional + The opacity of the patch(es). Inferred from `facecolor` and `edgecolor` by default. Aliases: ``a``, ``alphas``. +negpos : bool, default: False + Whether to shade bars where ``height >= 0`` with `poscolor` + and where ``height < 0`` with `negcolor`. If ``True`` this + function will return a length-2 silent list of handles. +negcolor, poscolor : color-spec, default: :rc:`negcolor`, :rc:`poscolor` + Colors to use for the negative and positive bars. Ignored if + `negpos` is ``False``. +edgefix : bool or float, default: :rc:`edgefix` + Whether to fix the common issue where white lines appear between adjacent + patches in saved vector graphics (this can slow down figure rendering). + See this `github repo `__ for a + demonstration of the problem. If ``True``, a small default linewidth of + ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), + this specific linewidth is used to cover up the white lines. This feature is + automatically disabled when the patches have transparency. +mean, means : bool, default: False + Whether to plot the means of each column for 2D `y` coordinates. Means + are calculated with `numpy.nanmean`. If no other arguments are specified, + this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). +median, medians : bool, default: False + Whether to plot the medians of each column for 2D `y` coordinates. Medians + are calculated with `numpy.nanmedian`. If no other arguments arguments are + specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). +bars : bool, default: None + Shorthand for `barstd`, `barstds`. +barstd, barstds : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. Standard deviation multiples for + *thin error bars* with optional whiskers (i.e., caps). If scalar, then +/- that + multiple is used. If ``True``, the default standard deviation range of +/-3 is used. +barpctile, barpctiles : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. As with `barstd`, but instead + using percentiles for the error bars. If scalar, that percentile range is + used (e.g., ``90`` shows the 5th to 95th percentiles). If ``True``, the default + percentile range of 0 to 100 is used. +bardata : array-like, optional + Valid only if `mean` and `median` are ``False``. If shape is 2 x N, these + are the lower and upper bounds for the thin error bars. If shape is N, these + are the absolute, symmetric deviations from the central points. +boxes : bool, default: None + Shorthand for `boxstd`, `boxstds`. +boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional + As with `barstd`, `barpctile`, and `bardata`, but for *thicker error bars* + representing a smaller interval than the thin error bars. If `boxstds` is + ``True``, the default standard deviation range of +/-1 is used. If `boxpctiles` + is ``True``, the default percentile range of 25 to 75 is used (i.e., the + interquartile range). When "boxes" and "bars" are combined, this has the + effect of drawing miniature box-and-whisker plots. +capsize : float, default: :rc:`errorbar.capsize` + The cap size for thin error bars in points. +barz, barzorder, boxz, boxzorder : float, default: 2.5 + The "zorder" for the thin and thick error bars. +barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` + Colors for the thin and thick error bars. +barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` + Line widths for the thin and thick error bars, in points. The default for boxes + is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. +boxm, boxmarker : bool or marker-spec, default: 'o' + Whether to draw a small marker in the middle of the box denoting + the mean or median position. Ignored if `boxes` is ``False``. +boxms, boxmarkersize : size-spec, default: ``(2 * boxlinewidth) ** 2`` + The marker size for the `boxmarker` marker in points ** 2. +boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor : color-spec, default: 'w' + Color, face color, and edge color for the `boxmarker` marker. +inbounds : bool, default: :rc:`axes.inbounds` + Whether to restrict the default `y` (`x`) axis limits to account for only + in-bounds data when the `x` (`y`) axis limits have been locked. + See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `~matplotlib.axes.Axes.bar`. + +See also +-------- +PlotAxes.bar +PlotAxes.barh +matplotlib.axes.Axes.bar +matplotlib.axes.Axes.barh""" + ... + + def barh(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot individual, grouped, or stacked bars. + +Parameters +---------- +*args : x or y, x + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `x` coordinates are passed, try to infer the `y` coordinates + from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the + :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + are ``np.arange(0, x.shape[0])``. + * If the `x` coordinates are a 2D array, plot each column of data in succession + (except where each column of data represents a statistical distribution, as with + ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +width : float or array-like, default: 0.8 + The width(s) of the bars. Can be passed as a third positional argument. If + `absolute_width` is ``True`` (the default) these are in units relative to the + y coordinate step size. Otherwise these are in y coordinate units. +left : float or array-like, default: 0 + The coordinate(s) of the left edge of the bars. + Can be passed as a fourth positional argument. +absolute_width : bool, default: False + Whether to make the `width` units *absolute*. If ``True``, + this restores the default matplotlib behavior. +stack, stacked : bool, default: False + Whether to "stack" bars from successive columns of x + data or plot bars side-by-side in groups. +bar_labels : bool, default rc["bar.bar_labels"] + Whether to show the height values for vertical bars or width values for horizontal bars. +bar_labels_kw : dict, default None + Keywords to format the bar_labels, see :func:`~matplotlib.pyplot.bar_label`. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +linewidth : unit-spec, default: :rc:`patch.linewidth` + The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyle : str, default: '-' + The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. +edgecolor : color-spec, default: 'none' + The edge color of the patch(es). Aliases: ``ec``, ``edgecolors``. +facecolor : color-spec, optional + The face color of the patch(es). The property `cycle` is used by default. Aliases: ``fc``, ``facecolors``, ``fillcolor``, ``fillcolors``. +alpha : float, optional + The opacity of the patch(es). Inferred from `facecolor` and `edgecolor` by default. Aliases: ``a``, ``alphas``. +negpos : bool, default: False + Whether to shade bars where ``height >= 0`` with `poscolor` + and where ``height < 0`` with `negcolor`. If ``True`` this + function will return a length-2 silent list of handles. +negcolor, poscolor : color-spec, default: :rc:`negcolor`, :rc:`poscolor` + Colors to use for the negative and positive bars. Ignored if + `negpos` is ``False``. +edgefix : bool or float, default: :rc:`edgefix` + Whether to fix the common issue where white lines appear between adjacent + patches in saved vector graphics (this can slow down figure rendering). + See this `github repo `__ for a + demonstration of the problem. If ``True``, a small default linewidth of + ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), + this specific linewidth is used to cover up the white lines. This feature is + automatically disabled when the patches have transparency. +mean, means : bool, default: False + Whether to plot the means of each column for 2D `x` coordinates. Means + are calculated with `numpy.nanmean`. If no other arguments are specified, + this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). +median, medians : bool, default: False + Whether to plot the medians of each column for 2D `x` coordinates. Medians + are calculated with `numpy.nanmedian`. If no other arguments arguments are + specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). +bars : bool, default: None + Shorthand for `barstd`, `barstds`. +barstd, barstds : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. Standard deviation multiples for + *thin error bars* with optional whiskers (i.e., caps). If scalar, then +/- that + multiple is used. If ``True``, the default standard deviation range of +/-3 is used. +barpctile, barpctiles : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. As with `barstd`, but instead + using percentiles for the error bars. If scalar, that percentile range is + used (e.g., ``90`` shows the 5th to 95th percentiles). If ``True``, the default + percentile range of 0 to 100 is used. +bardata : array-like, optional + Valid only if `mean` and `median` are ``False``. If shape is 2 x N, these + are the lower and upper bounds for the thin error bars. If shape is N, these + are the absolute, symmetric deviations from the central points. +boxes : bool, default: None + Shorthand for `boxstd`, `boxstds`. +boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional + As with `barstd`, `barpctile`, and `bardata`, but for *thicker error bars* + representing a smaller interval than the thin error bars. If `boxstds` is + ``True``, the default standard deviation range of +/-1 is used. If `boxpctiles` + is ``True``, the default percentile range of 25 to 75 is used (i.e., the + interquartile range). When "boxes" and "bars" are combined, this has the + effect of drawing miniature box-and-whisker plots. +capsize : float, default: :rc:`errorbar.capsize` + The cap size for thin error bars in points. +barz, barzorder, boxz, boxzorder : float, default: 2.5 + The "zorder" for the thin and thick error bars. +barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` + Colors for the thin and thick error bars. +barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` + Line widths for the thin and thick error bars, in points. The default for boxes + is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. +boxm, boxmarker : bool or marker-spec, default: 'o' + Whether to draw a small marker in the middle of the box denoting + the mean or median position. Ignored if `boxes` is ``False``. +boxms, boxmarkersize : size-spec, default: ``(2 * boxlinewidth) ** 2`` + The marker size for the `boxmarker` marker in points ** 2. +boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor : color-spec, default: 'w' + Color, face color, and edge color for the `boxmarker` marker. +inbounds : bool, default: :rc:`axes.inbounds` + Whether to restrict the default `y` (`x`) axis limits to account for only + in-bounds data when the `x` (`y`) axis limits have been locked. + See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `~matplotlib.axes.Axes.barh`. + +See also +-------- +PlotAxes.bar +PlotAxes.barh +matplotlib.axes.Axes.bar +matplotlib.axes.Axes.barh""" + ... + + def pie(self, x: Incomplete, explode: Incomplete, *, labelpad: Incomplete=None, labeldistance: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Plot a pie chart. + +Parameters +---------- +*args : y or x, y + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `y` coordinates are passed, try to infer the `x` coordinates + from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the + :class:`~xarray.DataArray` coordinates. Otherwise, the `x` coordinates + are ``np.arange(0, y.shape[0])``. + * If the `y` coordinates are a 2D array, plot each column of data in succession + (except where each column of data represents a statistical distribution, as with + ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +linewidth : unit-spec, default: :rc:`patch.linewidth` + The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyle : str, default: '-' + The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. +edgecolor : color-spec, default: 'none' + The edge color of the patch(es). Aliases: ``ec``, ``edgecolors``. +facecolor : color-spec, optional + The face color of the patch(es). The property `cycle` is used by default. Aliases: ``fc``, ``facecolors``, ``fillcolor``, ``fillcolors``. +alpha : float, optional + The opacity of the patch(es). Inferred from `facecolor` and `edgecolor` by default. Aliases: ``a``, ``alphas``. +edgefix : bool or float, default: :rc:`edgefix` + Whether to fix the common issue where white lines appear between adjacent + patches in saved vector graphics (this can slow down figure rendering). + See this `github repo `__ for a + demonstration of the problem. If ``True``, a small default linewidth of + ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), + this specific linewidth is used to cover up the white lines. This feature is + automatically disabled when the patches have transparency. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. +labelpad, labeldistance : float, optional + The distance at which labels are drawn in radial coordinates. + +See also +-------- +matplotlib.axes.Axes.pie""" + ... + + @staticmethod + def _parse_box_violin(fillcolor: Incomplete, fillalpha: Incomplete, edgecolor: Incomplete, **kw: Incomplete) -> Incomplete: + """Parse common boxplot and violinplot arguments.""" + ... + + def _boxplot_has_shared_tick_axis(self, axis_name: str) -> bool: + """Return whether the boxplot tick axis is shared with sibling axes.""" + ... + + def _apply_boxplot_tick_manager(self, axis_name: str, positions: Iterable[Any], tick_labels: Optional[Iterable[Any]]=None) -> None: + """Apply fixed tick locations/labels without appending duplicates on shared axes.""" + ... + + def _apply_boxplot(self, x: Incomplete, y: Incomplete, *, mean: Incomplete=None, means: Incomplete=None, vert: Incomplete=True, fill: Incomplete=None, filled: Incomplete=None, marker: Incomplete=None, markersize: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Apply the box plot.""" + ... + + def box(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot vertical boxes and whiskers with a nice default style. + +Parameters +---------- +*args : y or x, y + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `y` coordinates are passed, try to infer the `x` coordinates + from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the + :class:`~xarray.DataArray` coordinates. Otherwise, the `x` coordinates + are ``np.arange(0, y.shape[0])``. + * If the `y` coordinates are a 2D array, plot each column of data in succession + (except where each column of data represents a statistical distribution, as with + ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +fill : bool, default: True + Whether to fill the box with a color. +mean, means : bool, default: False + If ``True``, this passes ``showmeans=True`` and ``meanline=True`` to + `matplotlib.axes.Axes.boxplot`. Adds mean lines alongside the median. +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +linewidth : unit-spec, default: :rc:`patch.linewidth` + The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyle : str, default: '-' + The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. +edgecolor : color-spec, default: 'black' + The edge color of the patch(es). Aliases: ``ec``, ``edgecolors``. +facecolor : color-spec, optional + The face color of the patch(es). The property `cycle` is used by default. Aliases: ``fc``, ``facecolors``, ``fillcolor``, ``fillcolors``. +alpha : float, optional + The opacity of the patch(es). Inferred from `facecolor` and `edgecolor` by default. Aliases: ``a``, ``alphas``. +m, marker, ms, markersize : float or str, optional + Marker style and size for the 'fliers', i.e. outliers. See the + ``boxplot.flierprops`` `~matplotlib.rcParams` settings. +meanls, medianls, meanlinestyle, medianlinestyle, meanlinestyles, medianlinestyles : str, optional + Line style for the mean and median lines drawn across the box. + See the ``boxplot.meanprops`` and ``boxplot.medianprops`` + `~matplotlib.rcParams` settings. +boxc, capc, whiskerc, flierc, meanc, medianc, boxcolor, capcolor, whiskercolor, fliercolor, meancolor, mediancolor boxcolors, capcolors, whiskercolors, fliercolors, meancolors, mediancolors : color-spec or sequence, optional + Color of various boxplot components. If a sequence, should be the same length as + the number of boxes. These are shorthands so you don't have to pass e.g. a + `boxprops` dictionary keyword. See the ``boxplot.boxprops``, ``boxplot.capprops``, + ``boxplot.whiskerprops``, ``boxplot.flierprops``, ``boxplot.meanprops``, and + ``boxplot.medianprops`` `~matplotlib.rcParams` settings. +boxlw, caplw, whiskerlw, flierlw, meanlw, medianlw, boxlinewidth, caplinewidth, meanlinewidth, medianlinewidth, whiskerlinewidth, flierlinewidth, boxlinewidths, caplinewidths, meanlinewidths, medianlinewidths, whiskerlinewidths, flierlinewidths : float, optional + Line width of various boxplot components. These are shorthands so + you don't have to pass e.g. a `boxprops` dictionary keyword. + See the ``boxplot.boxprops``, ``boxplot.capprops``, ``boxplot.whiskerprops``, + ``boxplot.flierprops``, ``boxplot.meanprops``, and ``boxplot.medianprops`` + `~matplotlib.rcParams` settings. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. +**kwargs + Passed to `matplotlib.axes.Axes.boxplot`. + +See also +-------- +PlotAxes.boxes +PlotAxes.boxesh +PlotAxes.boxplot +PlotAxes.boxploth +matplotlib.axes.Axes.boxplot""" + ... + + def boxh(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot horizontal boxes and whiskers with a nice default style. + +Parameters +---------- +*args : x or y, x + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `x` coordinates are passed, try to infer the `y` coordinates + from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the + :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + are ``np.arange(0, x.shape[0])``. + * If the `x` coordinates are a 2D array, plot each column of data in succession + (except where each column of data represents a statistical distribution, as with + ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +fill : bool, default: True + Whether to fill the box with a color. +mean, means : bool, default: False + If ``True``, this passes ``showmeans=True`` and ``meanline=True`` to + `matplotlib.axes.Axes.boxplot`. Adds mean lines alongside the median. +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +linewidth : unit-spec, default: :rc:`patch.linewidth` + The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyle : str, default: '-' + The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. +edgecolor : color-spec, default: 'black' + The edge color of the patch(es). Aliases: ``ec``, ``edgecolors``. +facecolor : color-spec, optional + The face color of the patch(es). The property `cycle` is used by default. Aliases: ``fc``, ``facecolors``, ``fillcolor``, ``fillcolors``. +alpha : float, optional + The opacity of the patch(es). Inferred from `facecolor` and `edgecolor` by default. Aliases: ``a``, ``alphas``. +m, marker, ms, markersize : float or str, optional + Marker style and size for the 'fliers', i.e. outliers. See the + ``boxplot.flierprops`` `~matplotlib.rcParams` settings. +meanls, medianls, meanlinestyle, medianlinestyle, meanlinestyles, medianlinestyles : str, optional + Line style for the mean and median lines drawn across the box. + See the ``boxplot.meanprops`` and ``boxplot.medianprops`` + `~matplotlib.rcParams` settings. +boxc, capc, whiskerc, flierc, meanc, medianc, boxcolor, capcolor, whiskercolor, fliercolor, meancolor, mediancolor boxcolors, capcolors, whiskercolors, fliercolors, meancolors, mediancolors : color-spec or sequence, optional + Color of various boxplot components. If a sequence, should be the same length as + the number of boxes. These are shorthands so you don't have to pass e.g. a + `boxprops` dictionary keyword. See the ``boxplot.boxprops``, ``boxplot.capprops``, + ``boxplot.whiskerprops``, ``boxplot.flierprops``, ``boxplot.meanprops``, and + ``boxplot.medianprops`` `~matplotlib.rcParams` settings. +boxlw, caplw, whiskerlw, flierlw, meanlw, medianlw, boxlinewidth, caplinewidth, meanlinewidth, medianlinewidth, whiskerlinewidth, flierlinewidth, boxlinewidths, caplinewidths, meanlinewidths, medianlinewidths, whiskerlinewidths, flierlinewidths : float, optional + Line width of various boxplot components. These are shorthands so + you don't have to pass e.g. a `boxprops` dictionary keyword. + See the ``boxplot.boxprops``, ``boxplot.capprops``, ``boxplot.whiskerprops``, + ``boxplot.flierprops``, ``boxplot.meanprops``, and ``boxplot.medianprops`` + `~matplotlib.rcParams` settings. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. +**kwargs + Passed to `matplotlib.axes.Axes.boxplot`. + +See also +-------- +PlotAxes.boxes +PlotAxes.boxesh +PlotAxes.boxplot +PlotAxes.boxploth +matplotlib.axes.Axes.boxplot""" + ... + + def boxplot(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot vertical boxes and whiskers with a nice default style. + +Parameters +---------- +*args : y or x, y + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `y` coordinates are passed, try to infer the `x` coordinates + from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the + :class:`~xarray.DataArray` coordinates. Otherwise, the `x` coordinates + are ``np.arange(0, y.shape[0])``. + * If the `y` coordinates are a 2D array, plot each column of data in succession + (except where each column of data represents a statistical distribution, as with + ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +fill : bool, default: True + Whether to fill the box with a color. +mean, means : bool, default: False + If ``True``, this passes ``showmeans=True`` and ``meanline=True`` to + `matplotlib.axes.Axes.boxplot`. Adds mean lines alongside the median. +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +linewidth : unit-spec, default: :rc:`patch.linewidth` + The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyle : str, default: '-' + The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. +edgecolor : color-spec, default: 'black' + The edge color of the patch(es). Aliases: ``ec``, ``edgecolors``. +facecolor : color-spec, optional + The face color of the patch(es). The property `cycle` is used by default. Aliases: ``fc``, ``facecolors``, ``fillcolor``, ``fillcolors``. +alpha : float, optional + The opacity of the patch(es). Inferred from `facecolor` and `edgecolor` by default. Aliases: ``a``, ``alphas``. +m, marker, ms, markersize : float or str, optional + Marker style and size for the 'fliers', i.e. outliers. See the + ``boxplot.flierprops`` `~matplotlib.rcParams` settings. +meanls, medianls, meanlinestyle, medianlinestyle, meanlinestyles, medianlinestyles : str, optional + Line style for the mean and median lines drawn across the box. + See the ``boxplot.meanprops`` and ``boxplot.medianprops`` + `~matplotlib.rcParams` settings. +boxc, capc, whiskerc, flierc, meanc, medianc, boxcolor, capcolor, whiskercolor, fliercolor, meancolor, mediancolor boxcolors, capcolors, whiskercolors, fliercolors, meancolors, mediancolors : color-spec or sequence, optional + Color of various boxplot components. If a sequence, should be the same length as + the number of boxes. These are shorthands so you don't have to pass e.g. a + `boxprops` dictionary keyword. See the ``boxplot.boxprops``, ``boxplot.capprops``, + ``boxplot.whiskerprops``, ``boxplot.flierprops``, ``boxplot.meanprops``, and + ``boxplot.medianprops`` `~matplotlib.rcParams` settings. +boxlw, caplw, whiskerlw, flierlw, meanlw, medianlw, boxlinewidth, caplinewidth, meanlinewidth, medianlinewidth, whiskerlinewidth, flierlinewidth, boxlinewidths, caplinewidths, meanlinewidths, medianlinewidths, whiskerlinewidths, flierlinewidths : float, optional + Line width of various boxplot components. These are shorthands so + you don't have to pass e.g. a `boxprops` dictionary keyword. + See the ``boxplot.boxprops``, ``boxplot.capprops``, ``boxplot.whiskerprops``, + ``boxplot.flierprops``, ``boxplot.meanprops``, and ``boxplot.medianprops`` + `~matplotlib.rcParams` settings. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. +**kwargs + Passed to `matplotlib.axes.Axes.boxplot`. + +See also +-------- +PlotAxes.boxes +PlotAxes.boxesh +PlotAxes.boxplot +PlotAxes.boxploth +matplotlib.axes.Axes.boxplot""" + ... + + def boxploth(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot horizontal boxes and whiskers with a nice default style. + +Parameters +---------- +*args : x or y, x + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `x` coordinates are passed, try to infer the `y` coordinates + from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the + :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + are ``np.arange(0, x.shape[0])``. + * If the `x` coordinates are a 2D array, plot each column of data in succession + (except where each column of data represents a statistical distribution, as with + ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +fill : bool, default: True + Whether to fill the box with a color. +mean, means : bool, default: False + If ``True``, this passes ``showmeans=True`` and ``meanline=True`` to + `matplotlib.axes.Axes.boxplot`. Adds mean lines alongside the median. +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +linewidth : unit-spec, default: :rc:`patch.linewidth` + The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyle : str, default: '-' + The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. +edgecolor : color-spec, default: 'black' + The edge color of the patch(es). Aliases: ``ec``, ``edgecolors``. +facecolor : color-spec, optional + The face color of the patch(es). The property `cycle` is used by default. Aliases: ``fc``, ``facecolors``, ``fillcolor``, ``fillcolors``. +alpha : float, optional + The opacity of the patch(es). Inferred from `facecolor` and `edgecolor` by default. Aliases: ``a``, ``alphas``. +m, marker, ms, markersize : float or str, optional + Marker style and size for the 'fliers', i.e. outliers. See the + ``boxplot.flierprops`` `~matplotlib.rcParams` settings. +meanls, medianls, meanlinestyle, medianlinestyle, meanlinestyles, medianlinestyles : str, optional + Line style for the mean and median lines drawn across the box. + See the ``boxplot.meanprops`` and ``boxplot.medianprops`` + `~matplotlib.rcParams` settings. +boxc, capc, whiskerc, flierc, meanc, medianc, boxcolor, capcolor, whiskercolor, fliercolor, meancolor, mediancolor boxcolors, capcolors, whiskercolors, fliercolors, meancolors, mediancolors : color-spec or sequence, optional + Color of various boxplot components. If a sequence, should be the same length as + the number of boxes. These are shorthands so you don't have to pass e.g. a + `boxprops` dictionary keyword. See the ``boxplot.boxprops``, ``boxplot.capprops``, + ``boxplot.whiskerprops``, ``boxplot.flierprops``, ``boxplot.meanprops``, and + ``boxplot.medianprops`` `~matplotlib.rcParams` settings. +boxlw, caplw, whiskerlw, flierlw, meanlw, medianlw, boxlinewidth, caplinewidth, meanlinewidth, medianlinewidth, whiskerlinewidth, flierlinewidth, boxlinewidths, caplinewidths, meanlinewidths, medianlinewidths, whiskerlinewidths, flierlinewidths : float, optional + Line width of various boxplot components. These are shorthands so + you don't have to pass e.g. a `boxprops` dictionary keyword. + See the ``boxplot.boxprops``, ``boxplot.capprops``, ``boxplot.whiskerprops``, + ``boxplot.flierprops``, ``boxplot.meanprops``, and ``boxplot.medianprops`` + `~matplotlib.rcParams` settings. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. +**kwargs + Passed to `matplotlib.axes.Axes.boxplot`. + +See also +-------- +PlotAxes.boxes +PlotAxes.boxesh +PlotAxes.boxplot +PlotAxes.boxploth +matplotlib.axes.Axes.boxplot""" + ... + + def _apply_violinplot(self, x: Incomplete, y: Incomplete, vert: Incomplete=True, mean: Incomplete=None, means: Incomplete=None, median: Incomplete=None, medians: Incomplete=None, showmeans: Incomplete=None, showmedians: Incomplete=None, showextrema: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Apply the violinplot.""" + ... + + def violin(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot vertical violins with a nice default style matching +`this matplotlib example `__. + +Parameters +---------- +*args : y or x, y + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `y` coordinates are passed, try to infer the `x` coordinates + from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the + :class:`~xarray.DataArray` coordinates. Otherwise, the `x` coordinates + are ``np.arange(0, y.shape[0])``. + * If the `y` coordinates are a 2D array, plot each column of data in succession + (except where each column of data represents a statistical distribution, as with + ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +linewidth : unit-spec, default: :rc:`patch.linewidth` + The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyle : str, default: '-' + The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. +edgecolor : color-spec, default: 'black' + The edge color of the patch(es). Aliases: ``ec``, ``edgecolors``. +facecolor : color-spec, optional + The face color of the patch(es). The property `cycle` is used by default. Aliases: ``fc``, ``facecolors``, ``fillcolor``, ``fillcolors``. +alpha : float, optional + The opacity of the patch(es). Inferred from `facecolor` and `edgecolor` by default. Aliases: ``a``, ``alphas``. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. +showmeans, showmedians : bool, optional + Interpreted as ``means=True`` and ``medians=True`` when passed. +showextrema : bool, optional + Interpreted as ``barpctiles=True`` when passed (i.e. shows minima and maxima). +bars : bool, default: None + Shorthand for `barstd`, `barstds`. +barstd, barstds : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. Standard deviation multiples for + *thin error bars* with optional whiskers (i.e., caps). If scalar, then +/- that + multiple is used. If ``True``, the default standard deviation range of +/-3 is used. +barpctile, barpctiles : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. As with `barstd`, but instead + using percentiles for the error bars. If scalar, that percentile range is + used (e.g., ``90`` shows the 5th to 95th percentiles). If ``True``, the default + percentile range of 0 to 100 is used. +bardata : array-like, optional + Valid only if `mean` and `median` are ``False``. If shape is 2 x N, these + are the lower and upper bounds for the thin error bars. If shape is N, these + are the absolute, symmetric deviations from the central points. +boxes : bool, default: None + Shorthand for `boxstd`, `boxstds`. +boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional + As with `barstd`, `barpctile`, and `bardata`, but for *thicker error bars* + representing a smaller interval than the thin error bars. If `boxstds` is + ``True``, the default standard deviation range of +/-1 is used. If `boxpctiles` + is ``True``, the default percentile range of 25 to 75 is used (i.e., the + interquartile range). When "boxes" and "bars" are combined, this has the + effect of drawing miniature box-and-whisker plots. +capsize : float, default: :rc:`errorbar.capsize` + The cap size for thin error bars in points. +barz, barzorder, boxz, boxzorder : float, default: 2.5 + The "zorder" for the thin and thick error bars. +barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` + Colors for the thin and thick error bars. +barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` + Line widths for the thin and thick error bars, in points. The default for boxes + is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. +boxm, boxmarker : bool or marker-spec, default: 'o' + Whether to draw a small marker in the middle of the box denoting + the mean or median position. Ignored if `boxes` is ``False``. +boxms, boxmarkersize : size-spec, default: ``(2 * boxlinewidth) ** 2`` + The marker size for the `boxmarker` marker in points ** 2. +boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor : color-spec, default: 'w' + Color, face color, and edge color for the `boxmarker` marker. +**kwargs + Passed to `matplotlib.axes.Axes.violinplot`. + +See also +-------- +PlotAxes.violin +PlotAxes.violinh +PlotAxes.violinplot +PlotAxes.violinploth +matplotlib.axes.Axes.violinplot""" + ... + + def violinh(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot horizontal violins with a nice default style matching +`this matplotlib example `__. + +Parameters +---------- +*args : x or y, x + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `x` coordinates are passed, try to infer the `y` coordinates + from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the + :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + are ``np.arange(0, x.shape[0])``. + * If the `x` coordinates are a 2D array, plot each column of data in succession + (except where each column of data represents a statistical distribution, as with + ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +linewidth : unit-spec, default: :rc:`patch.linewidth` + The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyle : str, default: '-' + The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. +edgecolor : color-spec, default: 'black' + The edge color of the patch(es). Aliases: ``ec``, ``edgecolors``. +facecolor : color-spec, optional + The face color of the patch(es). The property `cycle` is used by default. Aliases: ``fc``, ``facecolors``, ``fillcolor``, ``fillcolors``. +alpha : float, optional + The opacity of the patch(es). Inferred from `facecolor` and `edgecolor` by default. Aliases: ``a``, ``alphas``. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. +showmeans, showmedians : bool, optional + Interpreted as ``means=True`` and ``medians=True`` when passed. +showextrema : bool, optional + Interpreted as ``barpctiles=True`` when passed (i.e. shows minima and maxima). +bars : bool, default: None + Shorthand for `barstd`, `barstds`. +barstd, barstds : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. Standard deviation multiples for + *thin error bars* with optional whiskers (i.e., caps). If scalar, then +/- that + multiple is used. If ``True``, the default standard deviation range of +/-3 is used. +barpctile, barpctiles : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. As with `barstd`, but instead + using percentiles for the error bars. If scalar, that percentile range is + used (e.g., ``90`` shows the 5th to 95th percentiles). If ``True``, the default + percentile range of 0 to 100 is used. +bardata : array-like, optional + Valid only if `mean` and `median` are ``False``. If shape is 2 x N, these + are the lower and upper bounds for the thin error bars. If shape is N, these + are the absolute, symmetric deviations from the central points. +boxes : bool, default: None + Shorthand for `boxstd`, `boxstds`. +boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional + As with `barstd`, `barpctile`, and `bardata`, but for *thicker error bars* + representing a smaller interval than the thin error bars. If `boxstds` is + ``True``, the default standard deviation range of +/-1 is used. If `boxpctiles` + is ``True``, the default percentile range of 25 to 75 is used (i.e., the + interquartile range). When "boxes" and "bars" are combined, this has the + effect of drawing miniature box-and-whisker plots. +capsize : float, default: :rc:`errorbar.capsize` + The cap size for thin error bars in points. +barz, barzorder, boxz, boxzorder : float, default: 2.5 + The "zorder" for the thin and thick error bars. +barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` + Colors for the thin and thick error bars. +barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` + Line widths for the thin and thick error bars, in points. The default for boxes + is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. +boxm, boxmarker : bool or marker-spec, default: 'o' + Whether to draw a small marker in the middle of the box denoting + the mean or median position. Ignored if `boxes` is ``False``. +boxms, boxmarkersize : size-spec, default: ``(2 * boxlinewidth) ** 2`` + The marker size for the `boxmarker` marker in points ** 2. +boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor : color-spec, default: 'w' + Color, face color, and edge color for the `boxmarker` marker. +**kwargs + Passed to `matplotlib.axes.Axes.violinplot`. + +See also +-------- +PlotAxes.violin +PlotAxes.violinh +PlotAxes.violinplot +PlotAxes.violinploth +matplotlib.axes.Axes.violinplot""" + ... + + def violinplot(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot vertical violins with a nice default style matching +`this matplotlib example `__. + +Parameters +---------- +*args : y or x, y + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `y` coordinates are passed, try to infer the `x` coordinates + from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the + :class:`~xarray.DataArray` coordinates. Otherwise, the `x` coordinates + are ``np.arange(0, y.shape[0])``. + * If the `y` coordinates are a 2D array, plot each column of data in succession + (except where each column of data represents a statistical distribution, as with + ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +linewidth : unit-spec, default: :rc:`patch.linewidth` + The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyle : str, default: '-' + The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. +edgecolor : color-spec, default: 'black' + The edge color of the patch(es). Aliases: ``ec``, ``edgecolors``. +facecolor : color-spec, optional + The face color of the patch(es). The property `cycle` is used by default. Aliases: ``fc``, ``facecolors``, ``fillcolor``, ``fillcolors``. +alpha : float, optional + The opacity of the patch(es). Inferred from `facecolor` and `edgecolor` by default. Aliases: ``a``, ``alphas``. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. +showmeans, showmedians : bool, optional + Interpreted as ``means=True`` and ``medians=True`` when passed. +showextrema : bool, optional + Interpreted as ``barpctiles=True`` when passed (i.e. shows minima and maxima). +bars : bool, default: None + Shorthand for `barstd`, `barstds`. +barstd, barstds : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. Standard deviation multiples for + *thin error bars* with optional whiskers (i.e., caps). If scalar, then +/- that + multiple is used. If ``True``, the default standard deviation range of +/-3 is used. +barpctile, barpctiles : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. As with `barstd`, but instead + using percentiles for the error bars. If scalar, that percentile range is + used (e.g., ``90`` shows the 5th to 95th percentiles). If ``True``, the default + percentile range of 0 to 100 is used. +bardata : array-like, optional + Valid only if `mean` and `median` are ``False``. If shape is 2 x N, these + are the lower and upper bounds for the thin error bars. If shape is N, these + are the absolute, symmetric deviations from the central points. +boxes : bool, default: None + Shorthand for `boxstd`, `boxstds`. +boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional + As with `barstd`, `barpctile`, and `bardata`, but for *thicker error bars* + representing a smaller interval than the thin error bars. If `boxstds` is + ``True``, the default standard deviation range of +/-1 is used. If `boxpctiles` + is ``True``, the default percentile range of 25 to 75 is used (i.e., the + interquartile range). When "boxes" and "bars" are combined, this has the + effect of drawing miniature box-and-whisker plots. +capsize : float, default: :rc:`errorbar.capsize` + The cap size for thin error bars in points. +barz, barzorder, boxz, boxzorder : float, default: 2.5 + The "zorder" for the thin and thick error bars. +barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` + Colors for the thin and thick error bars. +barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` + Line widths for the thin and thick error bars, in points. The default for boxes + is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. +boxm, boxmarker : bool or marker-spec, default: 'o' + Whether to draw a small marker in the middle of the box denoting + the mean or median position. Ignored if `boxes` is ``False``. +boxms, boxmarkersize : size-spec, default: ``(2 * boxlinewidth) ** 2`` + The marker size for the `boxmarker` marker in points ** 2. +boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor : color-spec, default: 'w' + Color, face color, and edge color for the `boxmarker` marker. +**kwargs + Passed to `matplotlib.axes.Axes.violinplot`. + +See also +-------- +PlotAxes.violin +PlotAxes.violinh +PlotAxes.violinplot +PlotAxes.violinploth +matplotlib.axes.Axes.violinplot""" + ... + + def violinploth(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot horizontal violins with a nice default style matching +`this matplotlib example `__. + +Parameters +---------- +*args : x or y, x + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `x` coordinates are passed, try to infer the `y` coordinates + from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the + :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + are ``np.arange(0, x.shape[0])``. + * If the `x` coordinates are a 2D array, plot each column of data in succession + (except where each column of data represents a statistical distribution, as with + ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +linewidth : unit-spec, default: :rc:`patch.linewidth` + The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyle : str, default: '-' + The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. +edgecolor : color-spec, default: 'black' + The edge color of the patch(es). Aliases: ``ec``, ``edgecolors``. +facecolor : color-spec, optional + The face color of the patch(es). The property `cycle` is used by default. Aliases: ``fc``, ``facecolors``, ``fillcolor``, ``fillcolors``. +alpha : float, optional + The opacity of the patch(es). Inferred from `facecolor` and `edgecolor` by default. Aliases: ``a``, ``alphas``. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. +showmeans, showmedians : bool, optional + Interpreted as ``means=True`` and ``medians=True`` when passed. +showextrema : bool, optional + Interpreted as ``barpctiles=True`` when passed (i.e. shows minima and maxima). +bars : bool, default: None + Shorthand for `barstd`, `barstds`. +barstd, barstds : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. Standard deviation multiples for + *thin error bars* with optional whiskers (i.e., caps). If scalar, then +/- that + multiple is used. If ``True``, the default standard deviation range of +/-3 is used. +barpctile, barpctiles : bool, float, or 2-tuple of float, optional + Valid only if `mean` or `median` is ``True``. As with `barstd`, but instead + using percentiles for the error bars. If scalar, that percentile range is + used (e.g., ``90`` shows the 5th to 95th percentiles). If ``True``, the default + percentile range of 0 to 100 is used. +bardata : array-like, optional + Valid only if `mean` and `median` are ``False``. If shape is 2 x N, these + are the lower and upper bounds for the thin error bars. If shape is N, these + are the absolute, symmetric deviations from the central points. +boxes : bool, default: None + Shorthand for `boxstd`, `boxstds`. +boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional + As with `barstd`, `barpctile`, and `bardata`, but for *thicker error bars* + representing a smaller interval than the thin error bars. If `boxstds` is + ``True``, the default standard deviation range of +/-1 is used. If `boxpctiles` + is ``True``, the default percentile range of 25 to 75 is used (i.e., the + interquartile range). When "boxes" and "bars" are combined, this has the + effect of drawing miniature box-and-whisker plots. +capsize : float, default: :rc:`errorbar.capsize` + The cap size for thin error bars in points. +barz, barzorder, boxz, boxzorder : float, default: 2.5 + The "zorder" for the thin and thick error bars. +barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` + Colors for the thin and thick error bars. +barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` + Line widths for the thin and thick error bars, in points. The default for boxes + is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. +boxm, boxmarker : bool or marker-spec, default: 'o' + Whether to draw a small marker in the middle of the box denoting + the mean or median position. Ignored if `boxes` is ``False``. +boxms, boxmarkersize : size-spec, default: ``(2 * boxlinewidth) ** 2`` + The marker size for the `boxmarker` marker in points ** 2. +boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor : color-spec, default: 'w' + Color, face color, and edge color for the `boxmarker` marker. +**kwargs + Passed to `matplotlib.axes.Axes.violinplot`. + +See also +-------- +PlotAxes.violin +PlotAxes.violinh +PlotAxes.violinplot +PlotAxes.violinploth +matplotlib.axes.Axes.violinplot""" + ... + + def _apply_ridgeline(self, data: Incomplete, labels: Incomplete=None, positions: Incomplete=None, height: Incomplete=None, overlap: Incomplete=0.5, kde_kw: Incomplete=None, points: Incomplete=None, hist: Incomplete=False, bins: Incomplete='auto', histtype: Incomplete=None, fill: Incomplete=True, alpha: Incomplete=1.0, linewidth: Incomplete=1.5, edgecolor: Incomplete='black', facecolor: Incomplete=None, cmap: Incomplete=None, vert: Incomplete=True, **kwargs: Incomplete) -> Incomplete: + """Apply ridgeline plot (joyplot). + +Parameters +---------- +data : list of array-like + List of distributions to plot as ridges. +labels : list of str, optional + Labels for each distribution. +positions : array-like, optional + Y-coordinates for continuous positioning mode. If provided, ridges are + anchored to these coordinates along the Y-axis. +height : float or array-like, optional + Height of each ridge in Y-axis units (continuous mode only). +overlap : float, default: 0.5 + Amount of overlap between ridges (0-1). Higher values create more overlap. + Only used in categorical mode. +kde_kw : dict, optional + Settings for the kernel density estimate. The ``bw_method``, + ``weights``, and ``points`` keys (``stepsize`` is an accepted alias + for the latter) control the estimate and the remaining keys style + the resulting curve, e.g. ``color``, ``linestyle``, ``linewidth``. + Only used when hist=False. +points : int, default: :rc:`kde.points` + Number of points to evaluate the KDE at. Higher values create smoother curves + but take longer to compute. Only used when hist=False. +hist : bool, default: False + If True, use histograms instead of kernel density estimation. +bins : int or sequence or str, default: 'auto' + Bin specification for histograms. Passed to numpy.histogram. + Only used when hist=True. +histtype : {'fill', 'bar', 'step', 'stepfilled'}, optional + Rendering style for histogram ridgelines. Defaults to ``'fill'``, + which uses a filled ridge curve. ``'bar'`` draws histogram bars. + Only used when hist=True. +fill : bool, default: True + Whether to fill the area under each curve. +alpha : float, default: 1.0 + Transparency of filled areas. +linewidth : float, default: 1.5 + Width of the ridge lines. +edgecolor : color, default: 'black' + Color of the ridge lines. +facecolor : color or list of colors, optional + Fill color(s). If None, uses current color cycle or colormap. +cmap : str or Colormap, optional + Colormap to use for coloring ridges. +vert : bool, default: True + If True, ridges are horizontal (traditional ridgeline plot). + If False, ridges are vertical. +**kwargs + Additional keyword arguments passed to fill_between or fill_betweenx. + +Returns +------- +list + List of PolyCollection objects for each ridge.""" + ... + + def ridgeline(self, data: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Create a vertical ridgeline plot (also known as a joyplot). + +Ridgeline plots visualize distributions of multiple datasets as stacked, +overlapping density curves. They are useful for comparing distributions +across categories or over time. + +Parameters +---------- +data : list of array-like + List of distributions to plot. Each element should be an array-like + object containing the data points for one distribution. +labels : list of str, optional + Labels for each distribution. If not provided, generates default labels. +positions : array-like, optional + Y-coordinates for positioning each ridge. If provided, enables continuous + (coordinate-based) positioning mode where ridges are anchored to specific + numerical coordinates along the Y-axis. If None (default), uses categorical + positioning with evenly-spaced ridges. +height : float or array-like, optional + Height of each ridge in Y-axis units. Only used in continuous positioning mode + (when positions is provided). Can be a single value applied to all ridges or + an array of values (one per ridge). If None, defaults to the minimum spacing + between positions divided by 2. +overlap : float, default: 0.5 + Amount of overlap between ridges, from 0 (no overlap) to 1 (full overlap). + Higher values create more dramatic visual overlapping. Only used in categorical + positioning mode (when positions is None). +kde_kw : dict, optional + Settings for the kernel density estimate. The following keys control the + estimate itself and are passed to `scipy.stats.gaussian_kde`: + + * ``bw_method`` : Bandwidth selection method (scalar, 'scott', 'silverman', or callable) + * ``weights`` : Array of weights for each data point + * ``points`` : Number of evaluation points, overriding `points` + (``stepsize`` is accepted as an alias) + + The remaining keys style the resulting curve and are passed to + `matplotlib.axes.Axes.plot`, e.g. ``color``, ``linestyle``, ``linewidth``. + Only used when hist=False. +points : int, default: :rc:`kde.points` + Number of evaluation points for KDE curves. Higher values create smoother + curves but take longer to compute. Only used when hist=False. +hist : bool, default: False + If True, uses histograms instead of kernel density estimation. +bins : int or sequence or str, default: 'auto' + Bin specification for histograms. Can be an integer (number of bins), + a sequence defining bin edges, or a string method ('auto', 'sturges', etc.). + Only used when hist=True. +fill : bool, default: True + Whether to fill the area under each density curve. +alpha : float, default: 0.7 + Transparency level for filled areas (0=transparent, 1=opaque). +linewidth : float, default: 1.5 + Width of the outline for each ridge. +edgecolor : color, default: 'black' + Color of the ridge outlines. +facecolor : color or list of colors, optional + Fill color(s) for the ridges. If a single color, applies to all ridges. + If a list, must match the number of distributions. If None, uses the + current color cycle or colormap. +cmap : str or Colormap, optional + Colormap name or object to use for coloring ridges. Overridden by facecolor. + +Returns +------- +list + List of artist objects for each ridge (PolyCollection or Line2D). + +Examples +-------- +>>> import ultraplot as uplt +>>> import numpy as np +>>> fig, ax = uplt.subplots() +>>> data = [np.random.normal(i, 1, 1000) for i in range(5)] +>>> ax.ridgeline(data, labels=[f'Group {i+1}' for i in range(5)]) + +>>> # With colormap +>>> fig, ax = uplt.subplots() +>>> ax.ridgeline(data, cmap='viridis', overlap=0.7) + +>>> # With histograms instead of KDE +>>> fig, ax = uplt.subplots() +>>> ax.ridgeline(data, hist=True, bins=20) + +>>> # Continuous positioning (e.g., at specific depths) +>>> fig, ax = uplt.subplots() +>>> depths = [0, 10, 25, 50, 100] # meters +>>> ax.ridgeline(data, positions=depths, height=8, labels=['Surface', '10m', '25m', '50m', '100m']) +>>> ax.format(ylabel='Depth (m)', xlabel='Temperature (°C)') + +See Also +-------- +violinplot : Violin plots for distribution visualization +hist : Histogram for single distribution""" + ... + + def ridgelineh(self, data: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Create a horizontal ridgeline plot (also known as a joyplot). + +Ridgeline plots visualize distributions of multiple datasets as stacked, +overlapping density curves. They are useful for comparing distributions +across categories or over time. + +Parameters +---------- +data : list of array-like + List of distributions to plot. Each element should be an array-like + object containing the data points for one distribution. +labels : list of str, optional + Labels for each distribution. If not provided, generates default labels. +positions : array-like, optional + Y-coordinates for positioning each ridge. If provided, enables continuous + (coordinate-based) positioning mode where ridges are anchored to specific + numerical coordinates along the Y-axis. If None (default), uses categorical + positioning with evenly-spaced ridges. +height : float or array-like, optional + Height of each ridge in Y-axis units. Only used in continuous positioning mode + (when positions is provided). Can be a single value applied to all ridges or + an array of values (one per ridge). If None, defaults to the minimum spacing + between positions divided by 2. +overlap : float, default: 0.5 + Amount of overlap between ridges, from 0 (no overlap) to 1 (full overlap). + Higher values create more dramatic visual overlapping. Only used in categorical + positioning mode (when positions is None). +kde_kw : dict, optional + Settings for the kernel density estimate. The following keys control the + estimate itself and are passed to `scipy.stats.gaussian_kde`: + + * ``bw_method`` : Bandwidth selection method (scalar, 'scott', 'silverman', or callable) + * ``weights`` : Array of weights for each data point + * ``points`` : Number of evaluation points, overriding `points` + (``stepsize`` is accepted as an alias) + + The remaining keys style the resulting curve and are passed to + `matplotlib.axes.Axes.plot`, e.g. ``color``, ``linestyle``, ``linewidth``. + Only used when hist=False. +points : int, default: :rc:`kde.points` + Number of evaluation points for KDE curves. Higher values create smoother + curves but take longer to compute. Only used when hist=False. +hist : bool, default: False + If True, uses histograms instead of kernel density estimation. +bins : int or sequence or str, default: 'auto' + Bin specification for histograms. Can be an integer (number of bins), + a sequence defining bin edges, or a string method ('auto', 'sturges', etc.). + Only used when hist=True. +fill : bool, default: True + Whether to fill the area under each density curve. +alpha : float, default: 0.7 + Transparency level for filled areas (0=transparent, 1=opaque). +linewidth : float, default: 1.5 + Width of the outline for each ridge. +edgecolor : color, default: 'black' + Color of the ridge outlines. +facecolor : color or list of colors, optional + Fill color(s) for the ridges. If a single color, applies to all ridges. + If a list, must match the number of distributions. If None, uses the + current color cycle or colormap. +cmap : str or Colormap, optional + Colormap name or object to use for coloring ridges. Overridden by facecolor. + +Returns +------- +list + List of artist objects for each ridge (PolyCollection or Line2D). + +Examples +-------- +>>> import ultraplot as uplt +>>> import numpy as np +>>> fig, ax = uplt.subplots() +>>> data = [np.random.normal(i, 1, 1000) for i in range(5)] +>>> ax.ridgeline(data, labels=[f'Group {i+1}' for i in range(5)]) + +>>> # With colormap +>>> fig, ax = uplt.subplots() +>>> ax.ridgeline(data, cmap='viridis', overlap=0.7) + +>>> # With histograms instead of KDE +>>> fig, ax = uplt.subplots() +>>> ax.ridgeline(data, hist=True, bins=20) + +>>> # Continuous positioning (e.g., at specific depths) +>>> fig, ax = uplt.subplots() +>>> depths = [0, 10, 25, 50, 100] # meters +>>> ax.ridgeline(data, positions=depths, height=8, labels=['Surface', '10m', '25m', '50m', '100m']) +>>> ax.format(ylabel='Depth (m)', xlabel='Temperature (°C)') + +See Also +-------- +violinplot : Violin plots for distribution visualization +hist : Histogram for single distribution""" + ... + + def _apply_hist(self, xs: Incomplete, bins: Incomplete, *, width: Incomplete=None, rwidth: Incomplete=None, stack: Incomplete=None, stacked: Incomplete=None, fill: Incomplete=None, filled: Incomplete=None, histtype: Incomplete=None, orientation: Incomplete='vertical', kde: Incomplete=False, kde_kw: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Apply the histogram.""" + ... + + def hist(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot vertical histograms. + +Parameters +---------- +*args : x or y, x + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `x` coordinates are passed, try to infer the `y` coordinates + from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the + :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + are ``np.arange(0, x.shape[0])``. + * If the `x` coordinates are a 2D array, plot each column of data in succession + (except where each column of data represents a statistical distribution, as with + ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +bins : int or sequence of float, optional + The bin count or exact bin edges. +weights : array-like, optional + The weights associated with each point. If string this + can be retrieved from `data` (see below). +histtype : {'bar', 'barstacked', 'step', 'stepfilled'}, optional + The histogram type. See `matplotlib.axes.Axes.hist` for details. +width, rwidth : float, default: 0.8 or 1 + The bar width(s) for bar-type histograms relative to the bin size. Default + is ``0.8`` for multiple columns of unstacked data and ``1`` otherwise. +stack, stacked : bool, optional + Whether to "stack" successive columns of x data for bar-type histograms + or show side-by-side in groups. Setting this to ``False`` is equivalent to + ``histtype='bar'`` and to ``True`` is equivalent to ``histtype='barstacked'``. +kde : bool, default: False + Whether to overlay a gaussian kernel density estimate of each column of + data. The curve tracks the histogram, i.e. it is scaled to the bin counts + unless ``density=True`` and accumulated when the histogram is stacked. + Requires `scipy `__. +kde_kw : dict, optional + Settings for the kernel density estimate. The following keys control the + estimate itself and are passed to `scipy.stats.gaussian_kde`: + + * ``bw_method`` : Bandwidth selection method (scalar, 'scott', 'silverman', or callable) + * ``weights`` : Array of weights for each data point, defaults to `weights` + * ``points`` : Number of evaluation points, default :rc:`kde.points` + (``stepsize`` is accepted as an alias) + + The remaining keys style the resulting curve and are passed to + `matplotlib.axes.Axes.plot`, e.g. ``color``, ``linestyle``, ``linewidth``. + By default each curve takes the color of its histogram. +fill, filled : bool, optional + Whether to "fill" step-type histograms or just plot the edges. Setting + this to ``False`` is equivalent to ``histtype='step'`` and to ``True`` + is equivalent to ``histtype='stepfilled'``. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +linewidth : unit-spec, default: :rc:`patch.linewidth` + The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyle : str, default: '-' + The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. +edgecolor : color-spec, default: 'none' + The edge color of the patch(es). Aliases: ``ec``, ``edgecolors``. +facecolor : color-spec, optional + The face color of the patch(es). The property `cycle` is used by default. Aliases: ``fc``, ``facecolors``, ``fillcolor``, ``fillcolors``. +alpha : float, optional + The opacity of the patch(es). Inferred from `facecolor` and `edgecolor` by default. Aliases: ``a``, ``alphas``. +edgefix : bool or float, default: :rc:`edgefix` + Whether to fix the common issue where white lines appear between adjacent + patches in saved vector graphics (this can slow down figure rendering). + See this `github repo `__ for a + demonstration of the problem. If ``True``, a small default linewidth of + ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), + this specific linewidth is used to cover up the white lines. This feature is + automatically disabled when the patches have transparency. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `~matplotlib.axes.Axes.hist`. + +See also +-------- +PlotAxes.hist +PlotAxes.histh +matplotlib.axes.Axes.hist""" + ... + + def histh(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot horizontal histograms. + +Parameters +---------- +*args : x or y, x + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `x` coordinates are passed, try to infer the `y` coordinates + from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the + :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + are ``np.arange(0, x.shape[0])``. + * If the `x` coordinates are a 2D array, plot each column of data in succession + (except where each column of data represents a statistical distribution, as with + ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +bins : int or sequence of float, optional + The bin count or exact bin edges. +weights : array-like, optional + The weights associated with each point. If string this + can be retrieved from `data` (see below). +histtype : {'bar', 'barstacked', 'step', 'stepfilled'}, optional + The histogram type. See `matplotlib.axes.Axes.hist` for details. +width, rwidth : float, default: 0.8 or 1 + The bar width(s) for bar-type histograms relative to the bin size. Default + is ``0.8`` for multiple columns of unstacked data and ``1`` otherwise. +stack, stacked : bool, optional + Whether to "stack" successive columns of x data for bar-type histograms + or show side-by-side in groups. Setting this to ``False`` is equivalent to + ``histtype='bar'`` and to ``True`` is equivalent to ``histtype='barstacked'``. +kde : bool, default: False + Whether to overlay a gaussian kernel density estimate of each column of + data. The curve tracks the histogram, i.e. it is scaled to the bin counts + unless ``density=True`` and accumulated when the histogram is stacked. + Requires `scipy `__. +kde_kw : dict, optional + Settings for the kernel density estimate. The following keys control the + estimate itself and are passed to `scipy.stats.gaussian_kde`: + + * ``bw_method`` : Bandwidth selection method (scalar, 'scott', 'silverman', or callable) + * ``weights`` : Array of weights for each data point, defaults to `weights` + * ``points`` : Number of evaluation points, default :rc:`kde.points` + (``stepsize`` is accepted as an alias) + + The remaining keys style the resulting curve and are passed to + `matplotlib.axes.Axes.plot`, e.g. ``color``, ``linestyle``, ``linewidth``. + By default each curve takes the color of its histogram. +fill, filled : bool, optional + Whether to "fill" step-type histograms or just plot the edges. Setting + this to ``False`` is equivalent to ``histtype='step'`` and to ``True`` + is equivalent to ``histtype='stepfilled'``. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, + or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). + To restore the default property cycler, use ``cycle=True``. +cycle_kw : dict-like, optional + Passed to `~ultraplot.constructor.Cycle`. +linewidth : unit-spec, default: :rc:`patch.linewidth` + The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyle : str, default: '-' + The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. +edgecolor : color-spec, default: 'none' + The edge color of the patch(es). Aliases: ``ec``, ``edgecolors``. +facecolor : color-spec, optional + The face color of the patch(es). The property `cycle` is used by default. Aliases: ``fc``, ``facecolors``, ``fillcolor``, ``fillcolors``. +alpha : float, optional + The opacity of the patch(es). Inferred from `facecolor` and `edgecolor` by default. Aliases: ``a``, ``alphas``. +edgefix : bool or float, default: :rc:`edgefix` + Whether to fix the common issue where white lines appear between adjacent + patches in saved vector graphics (this can slow down figure rendering). + See this `github repo `__ for a + demonstration of the problem. If ``True``, a small default linewidth of + ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), + this specific linewidth is used to cover up the white lines. This feature is + automatically disabled when the patches have transparency. +label, value : float or str, optional + The single legend label or colorbar coordinate to be used for + this plotted element. Can be numeric or string. This is generally + used with 1D positional arguments. +labels, values : sequence of float or sequence of str, optional + The legend labels or colorbar coordinates used for each plotted element. + Can be numeric or string, and must match the number of plotted elements. + This is generally used with 2D positional arguments. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `~matplotlib.axes.Axes.hist`. + +See also +-------- +PlotAxes.hist +PlotAxes.histh +matplotlib.axes.Axes.hist""" + ... + + def hist2d(self, x: Incomplete, y: Incomplete, bins: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot a standard 2D histogram. +standard 2D histogram. + +Parameters +---------- +*args : y or x, y + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `y` coordinates are passed, try to infer the `x` coordinates + from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the + :class:`~xarray.DataArray` coordinates. Otherwise, the `x` coordinates + are ``np.arange(0, y.shape[0])``. + * If the `y` coordinates are a 2D array, plot each column of data in succession + (except where each column of data represents a statistical distribution, as with + ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +bins : int or 2-tuple of int, or array-like or 2-tuple of array-like, optional + The bin count or exact bin edges for each dimension or both dimensions. +weights : array-like, optional + The weights associated with each point. If string this + can be retrieved from `data` (see below). +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` + The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor + function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization + range contains negative and positive values then :rcraw:`cmap.diverging` is used. + Otherwise :rcraw:`cmap.sequential` is used. +cmap_kw : dict-like, optional + Passed to :class:`~ultraplot.constructor.Colormap`. +c, color, colors : color-spec or sequence of color-spec, optional + The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + If not passed, `cmap` is used. +norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` + The data value normalizer, passed to the `~ultraplot.constructor.Norm` + constructor function. If `discrete` is ``True`` then 1) this affects the default + level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and + 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they + are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). + If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains + negative and positive values then `~ultraplot.colors.DivergingNorm` is used. + Otherwise `~matplotlib.colors.Normalize` is used. +norm_kw : dict-like, optional + Passed to `~ultraplot.constructor.Norm`. +extend : {'neither', 'both', 'min', 'max'}, default: 'neither' + Direction for drawing colorbar "extensions" indicating + out-of-bounds data on the end of the colorbar. +discrete : bool, default: :rc:`cmap.discrete` + If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the + colormap. Instead, for non-contour plots, the number of levels will be + roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + using `levels=large_number` but it may improve rendering speed. Default is + ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` + and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. +sequential, diverging, cyclic, qualitative : bool, default: None + Boolean arguments used if `cmap` is not passed. Set these to ``True`` + to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, + :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. + The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + as the default continuous normalizer. +vmin, vmax : float, optional + The minimum and maximum color scale values used with the `norm` normalizer. + If `discrete` is ``False`` these are the absolute limits, and if `discrete` + is ``True`` these are the approximate limits used to automatically determine + `levels` or `values` lists at "nice" intervals. If `levels` or `values` were + already passed as lists, these are ignored, and `vmin` and `vmax` are set to + the minimum and maximum of the lists. If `robust` was passed, the default `vmin` + and `vmax` are some percentile range of the data values. Otherwise, the default + `vmin` and `vmax` are the minimum and maximum of the data values. +N + Shorthand for `levels`. +levels : int or sequence of float, default: :rc:`cmap.levels` + The number of level edges or a sequence of level edges. If the former, `locator` + is used to generate this many level edges at "nice" intervals. If the latter, + the levels should be monotonically increasing or decreasing (note decreasing + levels fail with ``contour`` plots). +values : int or sequence of float, default: None + The number of level centers or a sequence of level centers. If the former, + `locator` is used to generate this many level centers at "nice" intervals. + If the latter, levels are inferred using `~ultraplot.utils.edges`. + This will override any `levels` input. +center_levels : bool, default False + If set to true, the discrete color bar bins will be centered on the level values + instead of using the level values as the edges of the discrete bins. This option + can be used for diverging, discrete color bars with both positive and negative + data to ensure data near zero is properly represented. +robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` + If ``True`` and `vmin` or `vmax` were not provided, they are + determined from the 2nd and 98th data percentiles rather than the + minimum and maximum. If float, this percentile range is used (for example, + ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, + these specific percentiles should be used. This feature is useful + when your data has large outliers. +inbounds : bool, default: :rc:`cmap.inbounds` + If ``True`` and `vmin` or `vmax` were not provided, when axis limits + have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` + or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. + See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. +locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + The locator used to determine level locations if `levels` or `values` were not + already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. + Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. +locator_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Locator` class. +symmetric : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + symmetric about zero. +positive : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + positive with a minimum at zero. +negative : bool, default: False + If ``True``, the normaliation range or discrete colormap levels are + negative with a minimum at zero. +nozero : bool, default: False + If ``True``, ``0`` is removed from the level list. This is mainly useful for + single-color `~matplotlib.axes.Axes.contour` plots. +label : str, optional + The legend label to be used for this object. In the case of + contours, this is paired with the the central artist in the artist + list returned by `matplotlib.contour.ContourSet.legend_elements`. +labels : bool, optional + Whether to apply labels to contours and grid boxes. The text will be + white when the luminance of the underlying filled contour or grid box + is less than 50 and black otherwise. +labels_kw : dict-like, optional + Ignored if `labels` is ``False``. Extra keyword args for the labels. + For contour plots, this is passed to `~matplotlib.axes.Axes.clabel`. + Otherwise, this is passed to `~matplotlib.axes.Axes.text`. +formatter, fmt : formatter-spec, optional + The `~matplotlib.ticker.Formatter` used to format number labels. + Passed to the `~ultraplot.constructor.Formatter` constructor. +formatter_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Formatter` class. +precision : int, optional + The maximum number of decimal places for number labels generated + with the default formatter `~ultraplot.ticker.Simpleformatter`. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `~matplotlib.axes.Axes.hist2d`. + +See also +-------- +PlotAxes.hist2d +PlotAxes.hexbin +matplotlib.axes.Axes.hist2d""" + ... + + def hexbin(self, x: Incomplete, y: Incomplete, weights: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot a 2D hexagonally binned histogram. +standard 2D histogram. + +Parameters +---------- +*args : y or x, y + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `y` coordinates are passed, try to infer the `x` coordinates + from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the + :class:`~xarray.DataArray` coordinates. Otherwise, the `x` coordinates + are ``np.arange(0, y.shape[0])``. + * If the `y` coordinates are a 2D array, plot each column of data in succession + (except where each column of data represents a statistical distribution, as with + ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +weights : array-like, optional + The weights associated with each point. If string this + can be retrieved from `data` (see below). +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` + The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor + function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization + range contains negative and positive values then :rcraw:`cmap.diverging` is used. + Otherwise :rcraw:`cmap.sequential` is used. +cmap_kw : dict-like, optional + Passed to :class:`~ultraplot.constructor.Colormap`. +c, color, colors : color-spec or sequence of color-spec, optional + The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + If not passed, `cmap` is used. +norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` + The data value normalizer, passed to the `~ultraplot.constructor.Norm` + constructor function. If `discrete` is ``True`` then 1) this affects the default + level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and + 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they + are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). + If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains + negative and positive values then `~ultraplot.colors.DivergingNorm` is used. + Otherwise `~matplotlib.colors.Normalize` is used. +norm_kw : dict-like, optional + Passed to `~ultraplot.constructor.Norm`. +extend : {'neither', 'both', 'min', 'max'}, default: 'neither' + Direction for drawing colorbar "extensions" indicating + out-of-bounds data on the end of the colorbar. +discrete : bool, default: :rc:`cmap.discrete` + If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the + colormap. Instead, for non-contour plots, the number of levels will be + roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + using `levels=large_number` but it may improve rendering speed. Default is + ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` + and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. +sequential, diverging, cyclic, qualitative : bool, default: None + Boolean arguments used if `cmap` is not passed. Set these to ``True`` + to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, + :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. + The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + as the default continuous normalizer. +vmin, vmax : float, optional + The minimum and maximum color scale values used with the `norm` normalizer. + If `discrete` is ``False`` these are the absolute limits, and if `discrete` + is ``True`` these are the approximate limits used to automatically determine + `levels` or `values` lists at "nice" intervals. If `levels` or `values` were + already passed as lists, these are ignored, and `vmin` and `vmax` are set to + the minimum and maximum of the lists. If `robust` was passed, the default `vmin` + and `vmax` are some percentile range of the data values. Otherwise, the default + `vmin` and `vmax` are the minimum and maximum of the data values. +N + Shorthand for `levels`. +levels : int or sequence of float, default: :rc:`cmap.levels` + The number of level edges or a sequence of level edges. If the former, `locator` + is used to generate this many level edges at "nice" intervals. If the latter, + the levels should be monotonically increasing or decreasing (note decreasing + levels fail with ``contour`` plots). +values : int or sequence of float, default: None + The number of level centers or a sequence of level centers. If the former, + `locator` is used to generate this many level centers at "nice" intervals. + If the latter, levels are inferred using `~ultraplot.utils.edges`. + This will override any `levels` input. +center_levels : bool, default False + If set to true, the discrete color bar bins will be centered on the level values + instead of using the level values as the edges of the discrete bins. This option + can be used for diverging, discrete color bars with both positive and negative + data to ensure data near zero is properly represented. +robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` + If ``True`` and `vmin` or `vmax` were not provided, they are + determined from the 2nd and 98th data percentiles rather than the + minimum and maximum. If float, this percentile range is used (for example, + ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, + these specific percentiles should be used. This feature is useful + when your data has large outliers. +inbounds : bool, default: :rc:`cmap.inbounds` + If ``True`` and `vmin` or `vmax` were not provided, when axis limits + have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` + or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. + See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. +locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + The locator used to determine level locations if `levels` or `values` were not + already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. + Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. +locator_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Locator` class. +symmetric : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + symmetric about zero. +positive : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + positive with a minimum at zero. +negative : bool, default: False + If ``True``, the normaliation range or discrete colormap levels are + negative with a minimum at zero. +nozero : bool, default: False + If ``True``, ``0`` is removed from the level list. This is mainly useful for + single-color `~matplotlib.axes.Axes.contour` plots. +label : str, optional + The legend label to be used for this object. In the case of + contours, this is paired with the the central artist in the artist + list returned by `matplotlib.contour.ContourSet.legend_elements`. +labels : bool, optional + Whether to apply labels to contours and grid boxes. The text will be + white when the luminance of the underlying filled contour or grid box + is less than 50 and black otherwise. +labels_kw : dict-like, optional + Ignored if `labels` is ``False``. Extra keyword args for the labels. + For contour plots, this is passed to `~matplotlib.axes.Axes.clabel`. + Otherwise, this is passed to `~matplotlib.axes.Axes.text`. +formatter, fmt : formatter-spec, optional + The `~matplotlib.ticker.Formatter` used to format number labels. + Passed to the `~ultraplot.constructor.Formatter` constructor. +formatter_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Formatter` class. +precision : int, optional + The maximum number of decimal places for number labels generated + with the default formatter `~ultraplot.ticker.Simpleformatter`. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `~matplotlib.axes.Axes.hexbin`. + +See also +-------- +PlotAxes.hist2d +PlotAxes.hexbin +matplotlib.axes.Axes.hexbin""" + ... + + def contour(self, x: Incomplete, y: Incomplete, z: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot contour lines. + +Parameters +---------- +*args : z or x, y, z + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `z` coordinates are passed, try to infer the `x` and `y` coordinates + from the :class:`~pandas.DataFrame` indices and columns or the :class:`~xarray.DataArray` + coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` + and the `x` coordinates are ``np.arange(0, y.shape[1])``. + * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using + `~ultraplot.utils.edges` or `:func:`~ultraplot.utils.edges2d`` if *centers* were provided. + For all other methods, calculate coordinate *centers* if *edges* were provided. + * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the + `z` coordinates are `pint.Quantity`, pass the magnitude to the plotting + command. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. +transpose : bool, default: False + Whether to transpose the input data. This should be used when + passing datasets with column-major dimension order ``(x, y)``. + Otherwise row-major dimension order ``(y, x)`` is expected. +order : {'C', 'F'}, default: 'C' + Alternative to `transpose`. ``'C'`` corresponds to the default C-cyle + row-major ordering (equivalent to ``transpose=False``). ``'F'`` corresponds + to Fortran-style column-major ordering (equivalent to ``transpose=True``). +globe : bool, default: False + For `ultraplot.axes.GeoAxes` only. Whether to enforce global + coverage. When set to ``True`` this does the following: + + #. Interpolates input data to the North and South poles by setting the data + values at the poles to the mean from latitudes nearest each pole. + #. Makes meridional coverage "circular", i.e. the last longitude coordinate + equals the first longitude coordinate plus 360°. + #. When basemap is the backend, cycles 1D longitude vectors to fit within + the map edges. For example, if the central longitude is 90°, + the data is shifted so that it spans -90° to 270°. + +Other parameters +---------------- +cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` + The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor + function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization + range contains negative and positive values then :rcraw:`cmap.diverging` is used. + Otherwise :rcraw:`cmap.sequential` is used. +cmap_kw : dict-like, optional + Passed to :class:`~ultraplot.constructor.Colormap`. +c, color, colors : color-spec or sequence of color-spec, optional + The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + If not passed, `cmap` is used. +norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` + The data value normalizer, passed to the `~ultraplot.constructor.Norm` + constructor function. If `discrete` is ``True`` then 1) this affects the default + level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and + 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they + are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). + If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains + negative and positive values then `~ultraplot.colors.DivergingNorm` is used. + Otherwise `~matplotlib.colors.Normalize` is used. +norm_kw : dict-like, optional + Passed to `~ultraplot.constructor.Norm`. +extend : {'neither', 'both', 'min', 'max'}, default: 'neither' + Direction for drawing colorbar "extensions" indicating + out-of-bounds data on the end of the colorbar. +discrete : bool, default: :rc:`cmap.discrete` + If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the + colormap. Instead, for non-contour plots, the number of levels will be + roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + using `levels=large_number` but it may improve rendering speed. Default is + ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` + and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. +sequential, diverging, cyclic, qualitative : bool, default: None + Boolean arguments used if `cmap` is not passed. Set these to ``True`` + to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, + :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. + The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + as the default continuous normalizer. +vmin, vmax : float, optional + The minimum and maximum color scale values used with the `norm` normalizer. + If `discrete` is ``False`` these are the absolute limits, and if `discrete` + is ``True`` these are the approximate limits used to automatically determine + `levels` or `values` lists at "nice" intervals. If `levels` or `values` were + already passed as lists, these are ignored, and `vmin` and `vmax` are set to + the minimum and maximum of the lists. If `robust` was passed, the default `vmin` + and `vmax` are some percentile range of the data values. Otherwise, the default + `vmin` and `vmax` are the minimum and maximum of the data values. +N + Shorthand for `levels`. +levels : int or sequence of float, default: :rc:`cmap.levels` + The number of level edges or a sequence of level edges. If the former, `locator` + is used to generate this many level edges at "nice" intervals. If the latter, + the levels should be monotonically increasing or decreasing (note decreasing + levels fail with ``contour`` plots). +values : int or sequence of float, default: None + The number of level centers or a sequence of level centers. If the former, + `locator` is used to generate this many level centers at "nice" intervals. + If the latter, levels are inferred using `~ultraplot.utils.edges`. + This will override any `levels` input. +center_levels : bool, default False + If set to true, the discrete color bar bins will be centered on the level values + instead of using the level values as the edges of the discrete bins. This option + can be used for diverging, discrete color bars with both positive and negative + data to ensure data near zero is properly represented. +robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` + If ``True`` and `vmin` or `vmax` were not provided, they are + determined from the 2nd and 98th data percentiles rather than the + minimum and maximum. If float, this percentile range is used (for example, + ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, + these specific percentiles should be used. This feature is useful + when your data has large outliers. +inbounds : bool, default: :rc:`cmap.inbounds` + If ``True`` and `vmin` or `vmax` were not provided, when axis limits + have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` + or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. + See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. +locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + The locator used to determine level locations if `levels` or `values` were not + already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. + Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. +locator_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Locator` class. +symmetric : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + symmetric about zero. +positive : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + positive with a minimum at zero. +negative : bool, default: False + If ``True``, the normaliation range or discrete colormap levels are + negative with a minimum at zero. +nozero : bool, default: False + If ``True``, ``0`` is removed from the level list. This is mainly useful for + single-color `~matplotlib.axes.Axes.contour` plots. +linewidths : unit-spec, default: 0.3 or :rc:`lines.linewidth` + The width of the line contours. Default is ``0.3`` when adding to filled contours + or :rc:`lines.linewidth` otherwise. Aliases: ``lw``, ``linewidth``. If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyles : str, default: '-' or :rc:`contour.negative_linestyle` + The style of the line contours. Default is ``'-'`` for positive contours and + :rcraw:`contour.negative_linestyle` for negative contours. Aliases: ``ls``, ``linestyle``. +edgecolors : color-spec, default: 'k' or inferred + The color of the line contours. Default is ``'k'`` when adding to filled contours + or inferred from `color` or `cmap` otherwise. Aliases: ``ec``, ``edgecolor``. +alpha : float, optional + The opacity of the contours. Inferred from `edgecolors` by default. Aliases: ``a``, ``alphas``. +label : str, optional + The legend label to be used for this object. In the case of + contours, this is paired with the the central artist in the artist + list returned by `matplotlib.contour.ContourSet.legend_elements`. +labels : bool, optional + Whether to apply labels to contours and grid boxes. The text will be + white when the luminance of the underlying filled contour or grid box + is less than 50 and black otherwise. +labels_kw : dict-like, optional + Ignored if `labels` is ``False``. Extra keyword args for the labels. + For contour plots, this is passed to `~matplotlib.axes.Axes.clabel`. + Otherwise, this is passed to `~matplotlib.axes.Axes.text`. +formatter, fmt : formatter-spec, optional + The `~matplotlib.ticker.Formatter` used to format number labels. + Passed to the `~ultraplot.constructor.Formatter` constructor. +formatter_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Formatter` class. +precision : int, optional + The maximum number of decimal places for number labels generated + with the default formatter `~ultraplot.ticker.Simpleformatter`. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `matplotlib.axes.Axes.contour`. + +See also +-------- +PlotAxes.contour +PlotAxes.contourf +PlotAxes.tricontour +PlotAxes.tricontourf +matplotlib.axes.Axes.contour""" + ... + + def contourf(self, x: Incomplete, y: Incomplete, z: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot filled contours. + +Parameters +---------- +*args : z or x, y, z + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `z` coordinates are passed, try to infer the `x` and `y` coordinates + from the :class:`~pandas.DataFrame` indices and columns or the :class:`~xarray.DataArray` + coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` + and the `x` coordinates are ``np.arange(0, y.shape[1])``. + * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using + `~ultraplot.utils.edges` or `:func:`~ultraplot.utils.edges2d`` if *centers* were provided. + For all other methods, calculate coordinate *centers* if *edges* were provided. + * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the + `z` coordinates are `pint.Quantity`, pass the magnitude to the plotting + command. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. +transpose : bool, default: False + Whether to transpose the input data. This should be used when + passing datasets with column-major dimension order ``(x, y)``. + Otherwise row-major dimension order ``(y, x)`` is expected. +order : {'C', 'F'}, default: 'C' + Alternative to `transpose`. ``'C'`` corresponds to the default C-cyle + row-major ordering (equivalent to ``transpose=False``). ``'F'`` corresponds + to Fortran-style column-major ordering (equivalent to ``transpose=True``). +globe : bool, default: False + For `ultraplot.axes.GeoAxes` only. Whether to enforce global + coverage. When set to ``True`` this does the following: + + #. Interpolates input data to the North and South poles by setting the data + values at the poles to the mean from latitudes nearest each pole. + #. Makes meridional coverage "circular", i.e. the last longitude coordinate + equals the first longitude coordinate plus 360°. + #. When basemap is the backend, cycles 1D longitude vectors to fit within + the map edges. For example, if the central longitude is 90°, + the data is shifted so that it spans -90° to 270°. + +Other parameters +---------------- +cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` + The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor + function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization + range contains negative and positive values then :rcraw:`cmap.diverging` is used. + Otherwise :rcraw:`cmap.sequential` is used. +cmap_kw : dict-like, optional + Passed to :class:`~ultraplot.constructor.Colormap`. +c, color, colors : color-spec or sequence of color-spec, optional + The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + If not passed, `cmap` is used. +norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` + The data value normalizer, passed to the `~ultraplot.constructor.Norm` + constructor function. If `discrete` is ``True`` then 1) this affects the default + level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and + 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they + are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). + If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains + negative and positive values then `~ultraplot.colors.DivergingNorm` is used. + Otherwise `~matplotlib.colors.Normalize` is used. +norm_kw : dict-like, optional + Passed to `~ultraplot.constructor.Norm`. +extend : {'neither', 'both', 'min', 'max'}, default: 'neither' + Direction for drawing colorbar "extensions" indicating + out-of-bounds data on the end of the colorbar. +discrete : bool, default: :rc:`cmap.discrete` + If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the + colormap. Instead, for non-contour plots, the number of levels will be + roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + using `levels=large_number` but it may improve rendering speed. Default is + ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` + and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. +sequential, diverging, cyclic, qualitative : bool, default: None + Boolean arguments used if `cmap` is not passed. Set these to ``True`` + to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, + :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. + The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + as the default continuous normalizer. +vmin, vmax : float, optional + The minimum and maximum color scale values used with the `norm` normalizer. + If `discrete` is ``False`` these are the absolute limits, and if `discrete` + is ``True`` these are the approximate limits used to automatically determine + `levels` or `values` lists at "nice" intervals. If `levels` or `values` were + already passed as lists, these are ignored, and `vmin` and `vmax` are set to + the minimum and maximum of the lists. If `robust` was passed, the default `vmin` + and `vmax` are some percentile range of the data values. Otherwise, the default + `vmin` and `vmax` are the minimum and maximum of the data values. +N + Shorthand for `levels`. +levels : int or sequence of float, default: :rc:`cmap.levels` + The number of level edges or a sequence of level edges. If the former, `locator` + is used to generate this many level edges at "nice" intervals. If the latter, + the levels should be monotonically increasing or decreasing (note decreasing + levels fail with ``contour`` plots). +values : int or sequence of float, default: None + The number of level centers or a sequence of level centers. If the former, + `locator` is used to generate this many level centers at "nice" intervals. + If the latter, levels are inferred using `~ultraplot.utils.edges`. + This will override any `levels` input. +center_levels : bool, default False + If set to true, the discrete color bar bins will be centered on the level values + instead of using the level values as the edges of the discrete bins. This option + can be used for diverging, discrete color bars with both positive and negative + data to ensure data near zero is properly represented. +robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` + If ``True`` and `vmin` or `vmax` were not provided, they are + determined from the 2nd and 98th data percentiles rather than the + minimum and maximum. If float, this percentile range is used (for example, + ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, + these specific percentiles should be used. This feature is useful + when your data has large outliers. +inbounds : bool, default: :rc:`cmap.inbounds` + If ``True`` and `vmin` or `vmax` were not provided, when axis limits + have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` + or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. + See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. +locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + The locator used to determine level locations if `levels` or `values` were not + already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. + Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. +locator_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Locator` class. +symmetric : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + symmetric about zero. +positive : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + positive with a minimum at zero. +negative : bool, default: False + If ``True``, the normaliation range or discrete colormap levels are + negative with a minimum at zero. +nozero : bool, default: False + If ``True``, ``0`` is removed from the level list. This is mainly useful for + single-color `~matplotlib.axes.Axes.contour` plots. +linewidths : unit-spec, default: 0.3 or :rc:`lines.linewidth` + The width of the line contours. Default is ``0.3`` when adding to filled contours + or :rc:`lines.linewidth` otherwise. Aliases: ``lw``, ``linewidth``. If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyles : str, default: '-' or :rc:`contour.negative_linestyle` + The style of the line contours. Default is ``'-'`` for positive contours and + :rcraw:`contour.negative_linestyle` for negative contours. Aliases: ``ls``, ``linestyle``. +edgecolors : color-spec, default: 'k' or inferred + The color of the line contours. Default is ``'k'`` when adding to filled contours + or inferred from `color` or `cmap` otherwise. Aliases: ``ec``, ``edgecolor``. +alpha : float, optional + The opacity of the contours. Inferred from `edgecolors` by default. Aliases: ``a``, ``alphas``.edgefix : bool or float, default: :rc:`edgefix` + Whether to fix the common issue where white lines appear between adjacent + patches in saved vector graphics (this can slow down figure rendering). + See this `github repo `__ for a + demonstration of the problem. If ``True``, a small default linewidth of + ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), + this specific linewidth is used to cover up the white lines. This feature is + automatically disabled when the patches have transparency. + +label : str, optional + The legend label to be used for this object. In the case of + contours, this is paired with the the central artist in the artist + list returned by `matplotlib.contour.ContourSet.legend_elements`. +labels : bool, optional + Whether to apply labels to contours and grid boxes. The text will be + white when the luminance of the underlying filled contour or grid box + is less than 50 and black otherwise. +labels_kw : dict-like, optional + Ignored if `labels` is ``False``. Extra keyword args for the labels. + For contour plots, this is passed to `~matplotlib.axes.Axes.clabel`. + Otherwise, this is passed to `~matplotlib.axes.Axes.text`. +formatter, fmt : formatter-spec, optional + The `~matplotlib.ticker.Formatter` used to format number labels. + Passed to the `~ultraplot.constructor.Formatter` constructor. +formatter_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Formatter` class. +precision : int, optional + The maximum number of decimal places for number labels generated + with the default formatter `~ultraplot.ticker.Simpleformatter`. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `matplotlib.axes.Axes.contourf`. + +See also +-------- +PlotAxes.contour +PlotAxes.contourf +PlotAxes.tricontour +PlotAxes.tricontourf +matplotlib.axes.Axes.contourf""" + ... + + def pcolor(self, x: Incomplete, y: Incomplete, z: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot irregular grid boxes. + +Parameters +---------- +*args : z or x, y, z + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `z` coordinates are passed, try to infer the `x` and `y` coordinates + from the :class:`~pandas.DataFrame` indices and columns or the :class:`~xarray.DataArray` + coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` + and the `x` coordinates are ``np.arange(0, y.shape[1])``. + * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using + `~ultraplot.utils.edges` or `:func:`~ultraplot.utils.edges2d`` if *centers* were provided. + For all other methods, calculate coordinate *centers* if *edges* were provided. + * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the + `z` coordinates are `pint.Quantity`, pass the magnitude to the plotting + command. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. +transpose : bool, default: False + Whether to transpose the input data. This should be used when + passing datasets with column-major dimension order ``(x, y)``. + Otherwise row-major dimension order ``(y, x)`` is expected. +order : {'C', 'F'}, default: 'C' + Alternative to `transpose`. ``'C'`` corresponds to the default C-cyle + row-major ordering (equivalent to ``transpose=False``). ``'F'`` corresponds + to Fortran-style column-major ordering (equivalent to ``transpose=True``). +globe : bool, default: False + For `ultraplot.axes.GeoAxes` only. Whether to enforce global + coverage. When set to ``True`` this does the following: + + #. Interpolates input data to the North and South poles by setting the data + values at the poles to the mean from latitudes nearest each pole. + #. Makes meridional coverage "circular", i.e. the last longitude coordinate + equals the first longitude coordinate plus 360°. + #. When basemap is the backend, cycles 1D longitude vectors to fit within + the map edges. For example, if the central longitude is 90°, + the data is shifted so that it spans -90° to 270°. + +Other parameters +---------------- +cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` + The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor + function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization + range contains negative and positive values then :rcraw:`cmap.diverging` is used. + Otherwise :rcraw:`cmap.sequential` is used. +cmap_kw : dict-like, optional + Passed to :class:`~ultraplot.constructor.Colormap`. +c, color, colors : color-spec or sequence of color-spec, optional + The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + If not passed, `cmap` is used. +norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` + The data value normalizer, passed to the `~ultraplot.constructor.Norm` + constructor function. If `discrete` is ``True`` then 1) this affects the default + level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and + 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they + are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). + If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains + negative and positive values then `~ultraplot.colors.DivergingNorm` is used. + Otherwise `~matplotlib.colors.Normalize` is used. +norm_kw : dict-like, optional + Passed to `~ultraplot.constructor.Norm`. +extend : {'neither', 'both', 'min', 'max'}, default: 'neither' + Direction for drawing colorbar "extensions" indicating + out-of-bounds data on the end of the colorbar. +discrete : bool, default: :rc:`cmap.discrete` + If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the + colormap. Instead, for non-contour plots, the number of levels will be + roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + using `levels=large_number` but it may improve rendering speed. Default is + ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` + and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. +sequential, diverging, cyclic, qualitative : bool, default: None + Boolean arguments used if `cmap` is not passed. Set these to ``True`` + to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, + :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. + The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + as the default continuous normalizer. +vmin, vmax : float, optional + The minimum and maximum color scale values used with the `norm` normalizer. + If `discrete` is ``False`` these are the absolute limits, and if `discrete` + is ``True`` these are the approximate limits used to automatically determine + `levels` or `values` lists at "nice" intervals. If `levels` or `values` were + already passed as lists, these are ignored, and `vmin` and `vmax` are set to + the minimum and maximum of the lists. If `robust` was passed, the default `vmin` + and `vmax` are some percentile range of the data values. Otherwise, the default + `vmin` and `vmax` are the minimum and maximum of the data values. +N + Shorthand for `levels`. +levels : int or sequence of float, default: :rc:`cmap.levels` + The number of level edges or a sequence of level edges. If the former, `locator` + is used to generate this many level edges at "nice" intervals. If the latter, + the levels should be monotonically increasing or decreasing (note decreasing + levels fail with ``contour`` plots). +values : int or sequence of float, default: None + The number of level centers or a sequence of level centers. If the former, + `locator` is used to generate this many level centers at "nice" intervals. + If the latter, levels are inferred using `~ultraplot.utils.edges`. + This will override any `levels` input. +center_levels : bool, default False + If set to true, the discrete color bar bins will be centered on the level values + instead of using the level values as the edges of the discrete bins. This option + can be used for diverging, discrete color bars with both positive and negative + data to ensure data near zero is properly represented. +robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` + If ``True`` and `vmin` or `vmax` were not provided, they are + determined from the 2nd and 98th data percentiles rather than the + minimum and maximum. If float, this percentile range is used (for example, + ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, + these specific percentiles should be used. This feature is useful + when your data has large outliers. +inbounds : bool, default: :rc:`cmap.inbounds` + If ``True`` and `vmin` or `vmax` were not provided, when axis limits + have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` + or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. + See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. +locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + The locator used to determine level locations if `levels` or `values` were not + already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. + Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. +locator_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Locator` class. +symmetric : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + symmetric about zero. +positive : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + positive with a minimum at zero. +negative : bool, default: False + If ``True``, the normaliation range or discrete colormap levels are + negative with a minimum at zero. +nozero : bool, default: False + If ``True``, ``0`` is removed from the level list. This is mainly useful for + single-color `~matplotlib.axes.Axes.contour` plots. +linewidths : unit-spec, default: 0.3 + The width of lines between grid boxes. Aliases: ``lw``, ``linewidth``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyles : str, default: '-' + The style of lines between grid boxes. Aliases: ``ls``, ``linestyle``. +edgecolors : color-spec, default: 'k' + The color of lines between grid boxes. Aliases: ``ec``, ``edgecolor``. +alpha : float, optional + The opacity of the grid boxes. Inferred from `cmap` by default. Aliases: ``a``, ``alphas``. +edgefix : bool or float, default: :rc:`edgefix` + Whether to fix the common issue where white lines appear between adjacent + patches in saved vector graphics (this can slow down figure rendering). + See this `github repo `__ for a + demonstration of the problem. If ``True``, a small default linewidth of + ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), + this specific linewidth is used to cover up the white lines. This feature is + automatically disabled when the patches have transparency. +label : str, optional + The legend label to be used for this object. In the case of + contours, this is paired with the the central artist in the artist + list returned by `matplotlib.contour.ContourSet.legend_elements`. +labels : bool, optional + Whether to apply labels to contours and grid boxes. The text will be + white when the luminance of the underlying filled contour or grid box + is less than 50 and black otherwise. +labels_kw : dict-like, optional + Ignored if `labels` is ``False``. Extra keyword args for the labels. + For contour plots, this is passed to `~matplotlib.axes.Axes.clabel`. + Otherwise, this is passed to `~matplotlib.axes.Axes.text`. +formatter, fmt : formatter-spec, optional + The `~matplotlib.ticker.Formatter` used to format number labels. + Passed to the `~ultraplot.constructor.Formatter` constructor. +formatter_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Formatter` class. +precision : int, optional + The maximum number of decimal places for number labels generated + with the default formatter `~ultraplot.ticker.Simpleformatter`. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `matplotlib.axes.Axes.pcolor`. + +See also +-------- +PlotAxes.pcolor +PlotAxes.pcolormesh +PlotAxes.pcolorfast +PlotAxes.heatmap +PlotAxes.tripcolor +matplotlib.axes.Axes.pcolor""" + ... + + def pcolormesh(self, x: Incomplete, y: Incomplete, z: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot regular grid boxes. + +Parameters +---------- +*args : z or x, y, z + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `z` coordinates are passed, try to infer the `x` and `y` coordinates + from the :class:`~pandas.DataFrame` indices and columns or the :class:`~xarray.DataArray` + coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` + and the `x` coordinates are ``np.arange(0, y.shape[1])``. + * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using + `~ultraplot.utils.edges` or `:func:`~ultraplot.utils.edges2d`` if *centers* were provided. + For all other methods, calculate coordinate *centers* if *edges* were provided. + * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the + `z` coordinates are `pint.Quantity`, pass the magnitude to the plotting + command. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. +transpose : bool, default: False + Whether to transpose the input data. This should be used when + passing datasets with column-major dimension order ``(x, y)``. + Otherwise row-major dimension order ``(y, x)`` is expected. +order : {'C', 'F'}, default: 'C' + Alternative to `transpose`. ``'C'`` corresponds to the default C-cyle + row-major ordering (equivalent to ``transpose=False``). ``'F'`` corresponds + to Fortran-style column-major ordering (equivalent to ``transpose=True``). +globe : bool, default: False + For `ultraplot.axes.GeoAxes` only. Whether to enforce global + coverage. When set to ``True`` this does the following: + + #. Interpolates input data to the North and South poles by setting the data + values at the poles to the mean from latitudes nearest each pole. + #. Makes meridional coverage "circular", i.e. the last longitude coordinate + equals the first longitude coordinate plus 360°. + #. When basemap is the backend, cycles 1D longitude vectors to fit within + the map edges. For example, if the central longitude is 90°, + the data is shifted so that it spans -90° to 270°. + +Other parameters +---------------- +cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` + The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor + function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization + range contains negative and positive values then :rcraw:`cmap.diverging` is used. + Otherwise :rcraw:`cmap.sequential` is used. +cmap_kw : dict-like, optional + Passed to :class:`~ultraplot.constructor.Colormap`. +c, color, colors : color-spec or sequence of color-spec, optional + The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + If not passed, `cmap` is used. +norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` + The data value normalizer, passed to the `~ultraplot.constructor.Norm` + constructor function. If `discrete` is ``True`` then 1) this affects the default + level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and + 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they + are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). + If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains + negative and positive values then `~ultraplot.colors.DivergingNorm` is used. + Otherwise `~matplotlib.colors.Normalize` is used. +norm_kw : dict-like, optional + Passed to `~ultraplot.constructor.Norm`. +extend : {'neither', 'both', 'min', 'max'}, default: 'neither' + Direction for drawing colorbar "extensions" indicating + out-of-bounds data on the end of the colorbar. +discrete : bool, default: :rc:`cmap.discrete` + If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the + colormap. Instead, for non-contour plots, the number of levels will be + roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + using `levels=large_number` but it may improve rendering speed. Default is + ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` + and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. +sequential, diverging, cyclic, qualitative : bool, default: None + Boolean arguments used if `cmap` is not passed. Set these to ``True`` + to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, + :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. + The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + as the default continuous normalizer. +vmin, vmax : float, optional + The minimum and maximum color scale values used with the `norm` normalizer. + If `discrete` is ``False`` these are the absolute limits, and if `discrete` + is ``True`` these are the approximate limits used to automatically determine + `levels` or `values` lists at "nice" intervals. If `levels` or `values` were + already passed as lists, these are ignored, and `vmin` and `vmax` are set to + the minimum and maximum of the lists. If `robust` was passed, the default `vmin` + and `vmax` are some percentile range of the data values. Otherwise, the default + `vmin` and `vmax` are the minimum and maximum of the data values. +N + Shorthand for `levels`. +levels : int or sequence of float, default: :rc:`cmap.levels` + The number of level edges or a sequence of level edges. If the former, `locator` + is used to generate this many level edges at "nice" intervals. If the latter, + the levels should be monotonically increasing or decreasing (note decreasing + levels fail with ``contour`` plots). +values : int or sequence of float, default: None + The number of level centers or a sequence of level centers. If the former, + `locator` is used to generate this many level centers at "nice" intervals. + If the latter, levels are inferred using `~ultraplot.utils.edges`. + This will override any `levels` input. +center_levels : bool, default False + If set to true, the discrete color bar bins will be centered on the level values + instead of using the level values as the edges of the discrete bins. This option + can be used for diverging, discrete color bars with both positive and negative + data to ensure data near zero is properly represented. +robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` + If ``True`` and `vmin` or `vmax` were not provided, they are + determined from the 2nd and 98th data percentiles rather than the + minimum and maximum. If float, this percentile range is used (for example, + ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, + these specific percentiles should be used. This feature is useful + when your data has large outliers. +inbounds : bool, default: :rc:`cmap.inbounds` + If ``True`` and `vmin` or `vmax` were not provided, when axis limits + have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` + or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. + See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. +locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + The locator used to determine level locations if `levels` or `values` were not + already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. + Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. +locator_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Locator` class. +symmetric : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + symmetric about zero. +positive : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + positive with a minimum at zero. +negative : bool, default: False + If ``True``, the normaliation range or discrete colormap levels are + negative with a minimum at zero. +nozero : bool, default: False + If ``True``, ``0`` is removed from the level list. This is mainly useful for + single-color `~matplotlib.axes.Axes.contour` plots. +linewidths : unit-spec, default: 0.3 + The width of lines between grid boxes. Aliases: ``lw``, ``linewidth``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyles : str, default: '-' + The style of lines between grid boxes. Aliases: ``ls``, ``linestyle``. +edgecolors : color-spec, default: 'k' + The color of lines between grid boxes. Aliases: ``ec``, ``edgecolor``. +alpha : float, optional + The opacity of the grid boxes. Inferred from `cmap` by default. Aliases: ``a``, ``alphas``. +edgefix : bool or float, default: :rc:`edgefix` + Whether to fix the common issue where white lines appear between adjacent + patches in saved vector graphics (this can slow down figure rendering). + See this `github repo `__ for a + demonstration of the problem. If ``True``, a small default linewidth of + ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), + this specific linewidth is used to cover up the white lines. This feature is + automatically disabled when the patches have transparency. +label : str, optional + The legend label to be used for this object. In the case of + contours, this is paired with the the central artist in the artist + list returned by `matplotlib.contour.ContourSet.legend_elements`. +labels : bool, optional + Whether to apply labels to contours and grid boxes. The text will be + white when the luminance of the underlying filled contour or grid box + is less than 50 and black otherwise. +labels_kw : dict-like, optional + Ignored if `labels` is ``False``. Extra keyword args for the labels. + For contour plots, this is passed to `~matplotlib.axes.Axes.clabel`. + Otherwise, this is passed to `~matplotlib.axes.Axes.text`. +formatter, fmt : formatter-spec, optional + The `~matplotlib.ticker.Formatter` used to format number labels. + Passed to the `~ultraplot.constructor.Formatter` constructor. +formatter_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Formatter` class. +precision : int, optional + The maximum number of decimal places for number labels generated + with the default formatter `~ultraplot.ticker.Simpleformatter`. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `matplotlib.axes.Axes.pcolormesh`. + +See also +-------- +PlotAxes.pcolor +PlotAxes.pcolormesh +PlotAxes.pcolorfast +PlotAxes.heatmap +PlotAxes.tripcolor +matplotlib.axes.Axes.pcolormesh""" + ... + + def pcolorfast(self, x: Incomplete, y: Incomplete, z: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot grid boxes quickly. + +Parameters +---------- +*args : z or x, y, z + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `z` coordinates are passed, try to infer the `x` and `y` coordinates + from the :class:`~pandas.DataFrame` indices and columns or the :class:`~xarray.DataArray` + coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` + and the `x` coordinates are ``np.arange(0, y.shape[1])``. + * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using + `~ultraplot.utils.edges` or `:func:`~ultraplot.utils.edges2d`` if *centers* were provided. + For all other methods, calculate coordinate *centers* if *edges* were provided. + * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the + `z` coordinates are `pint.Quantity`, pass the magnitude to the plotting + command. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. +transpose : bool, default: False + Whether to transpose the input data. This should be used when + passing datasets with column-major dimension order ``(x, y)``. + Otherwise row-major dimension order ``(y, x)`` is expected. +order : {'C', 'F'}, default: 'C' + Alternative to `transpose`. ``'C'`` corresponds to the default C-cyle + row-major ordering (equivalent to ``transpose=False``). ``'F'`` corresponds + to Fortran-style column-major ordering (equivalent to ``transpose=True``). +globe : bool, default: False + For `ultraplot.axes.GeoAxes` only. Whether to enforce global + coverage. When set to ``True`` this does the following: + + #. Interpolates input data to the North and South poles by setting the data + values at the poles to the mean from latitudes nearest each pole. + #. Makes meridional coverage "circular", i.e. the last longitude coordinate + equals the first longitude coordinate plus 360°. + #. When basemap is the backend, cycles 1D longitude vectors to fit within + the map edges. For example, if the central longitude is 90°, + the data is shifted so that it spans -90° to 270°. + +Other parameters +---------------- +cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` + The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor + function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization + range contains negative and positive values then :rcraw:`cmap.diverging` is used. + Otherwise :rcraw:`cmap.sequential` is used. +cmap_kw : dict-like, optional + Passed to :class:`~ultraplot.constructor.Colormap`. +c, color, colors : color-spec or sequence of color-spec, optional + The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + If not passed, `cmap` is used. +norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` + The data value normalizer, passed to the `~ultraplot.constructor.Norm` + constructor function. If `discrete` is ``True`` then 1) this affects the default + level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and + 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they + are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). + If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains + negative and positive values then `~ultraplot.colors.DivergingNorm` is used. + Otherwise `~matplotlib.colors.Normalize` is used. +norm_kw : dict-like, optional + Passed to `~ultraplot.constructor.Norm`. +extend : {'neither', 'both', 'min', 'max'}, default: 'neither' + Direction for drawing colorbar "extensions" indicating + out-of-bounds data on the end of the colorbar. +discrete : bool, default: :rc:`cmap.discrete` + If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the + colormap. Instead, for non-contour plots, the number of levels will be + roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + using `levels=large_number` but it may improve rendering speed. Default is + ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` + and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. +sequential, diverging, cyclic, qualitative : bool, default: None + Boolean arguments used if `cmap` is not passed. Set these to ``True`` + to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, + :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. + The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + as the default continuous normalizer. +vmin, vmax : float, optional + The minimum and maximum color scale values used with the `norm` normalizer. + If `discrete` is ``False`` these are the absolute limits, and if `discrete` + is ``True`` these are the approximate limits used to automatically determine + `levels` or `values` lists at "nice" intervals. If `levels` or `values` were + already passed as lists, these are ignored, and `vmin` and `vmax` are set to + the minimum and maximum of the lists. If `robust` was passed, the default `vmin` + and `vmax` are some percentile range of the data values. Otherwise, the default + `vmin` and `vmax` are the minimum and maximum of the data values. +N + Shorthand for `levels`. +levels : int or sequence of float, default: :rc:`cmap.levels` + The number of level edges or a sequence of level edges. If the former, `locator` + is used to generate this many level edges at "nice" intervals. If the latter, + the levels should be monotonically increasing or decreasing (note decreasing + levels fail with ``contour`` plots). +values : int or sequence of float, default: None + The number of level centers or a sequence of level centers. If the former, + `locator` is used to generate this many level centers at "nice" intervals. + If the latter, levels are inferred using `~ultraplot.utils.edges`. + This will override any `levels` input. +center_levels : bool, default False + If set to true, the discrete color bar bins will be centered on the level values + instead of using the level values as the edges of the discrete bins. This option + can be used for diverging, discrete color bars with both positive and negative + data to ensure data near zero is properly represented. +robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` + If ``True`` and `vmin` or `vmax` were not provided, they are + determined from the 2nd and 98th data percentiles rather than the + minimum and maximum. If float, this percentile range is used (for example, + ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, + these specific percentiles should be used. This feature is useful + when your data has large outliers. +inbounds : bool, default: :rc:`cmap.inbounds` + If ``True`` and `vmin` or `vmax` were not provided, when axis limits + have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` + or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. + See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. +locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + The locator used to determine level locations if `levels` or `values` were not + already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. + Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. +locator_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Locator` class. +symmetric : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + symmetric about zero. +positive : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + positive with a minimum at zero. +negative : bool, default: False + If ``True``, the normaliation range or discrete colormap levels are + negative with a minimum at zero. +nozero : bool, default: False + If ``True``, ``0`` is removed from the level list. This is mainly useful for + single-color `~matplotlib.axes.Axes.contour` plots. +linewidths : unit-spec, default: 0.3 + The width of lines between grid boxes. Aliases: ``lw``, ``linewidth``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyles : str, default: '-' + The style of lines between grid boxes. Aliases: ``ls``, ``linestyle``. +edgecolors : color-spec, default: 'k' + The color of lines between grid boxes. Aliases: ``ec``, ``edgecolor``. +alpha : float, optional + The opacity of the grid boxes. Inferred from `cmap` by default. Aliases: ``a``, ``alphas``. +edgefix : bool or float, default: :rc:`edgefix` + Whether to fix the common issue where white lines appear between adjacent + patches in saved vector graphics (this can slow down figure rendering). + See this `github repo `__ for a + demonstration of the problem. If ``True``, a small default linewidth of + ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), + this specific linewidth is used to cover up the white lines. This feature is + automatically disabled when the patches have transparency. +label : str, optional + The legend label to be used for this object. In the case of + contours, this is paired with the the central artist in the artist + list returned by `matplotlib.contour.ContourSet.legend_elements`. +labels : bool, optional + Whether to apply labels to contours and grid boxes. The text will be + white when the luminance of the underlying filled contour or grid box + is less than 50 and black otherwise. +labels_kw : dict-like, optional + Ignored if `labels` is ``False``. Extra keyword args for the labels. + For contour plots, this is passed to `~matplotlib.axes.Axes.clabel`. + Otherwise, this is passed to `~matplotlib.axes.Axes.text`. +formatter, fmt : formatter-spec, optional + The `~matplotlib.ticker.Formatter` used to format number labels. + Passed to the `~ultraplot.constructor.Formatter` constructor. +formatter_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Formatter` class. +precision : int, optional + The maximum number of decimal places for number labels generated + with the default formatter `~ultraplot.ticker.Simpleformatter`. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `matplotlib.axes.Axes.pcolorfast`. + +See also +-------- +PlotAxes.pcolor +PlotAxes.pcolormesh +PlotAxes.pcolorfast +PlotAxes.heatmap +PlotAxes.tripcolor +matplotlib.axes.Axes.pcolorfast""" + ... + + def heatmap(self, *args: Incomplete, aspect: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Plot grid boxes with formatting suitable for heatmaps. Ensures square grid +boxes, adds major ticks to the center of each grid box, disables minor +ticks and gridlines, and sets :rcraw:`cmap.discrete` to ``False`` by default. + +Parameters +---------- +*args : z or x, y, z + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `z` coordinates are passed, try to infer the `x` and `y` coordinates + from the :class:`~pandas.DataFrame` indices and columns or the :class:`~xarray.DataArray` + coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` + and the `x` coordinates are ``np.arange(0, y.shape[1])``. + * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using + `~ultraplot.utils.edges` or `:func:`~ultraplot.utils.edges2d`` if *centers* were provided. + For all other methods, calculate coordinate *centers* if *edges* were provided. + * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the + `z` coordinates are `pint.Quantity`, pass the magnitude to the plotting + command. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. +transpose : bool, default: False + Whether to transpose the input data. This should be used when + passing datasets with column-major dimension order ``(x, y)``. + Otherwise row-major dimension order ``(y, x)`` is expected. +order : {'C', 'F'}, default: 'C' + Alternative to `transpose`. ``'C'`` corresponds to the default C-cyle + row-major ordering (equivalent to ``transpose=False``). ``'F'`` corresponds + to Fortran-style column-major ordering (equivalent to ``transpose=True``). +globe : bool, default: False + For `ultraplot.axes.GeoAxes` only. Whether to enforce global + coverage. When set to ``True`` this does the following: + + #. Interpolates input data to the North and South poles by setting the data + values at the poles to the mean from latitudes nearest each pole. + #. Makes meridional coverage "circular", i.e. the last longitude coordinate + equals the first longitude coordinate plus 360°. + #. When basemap is the backend, cycles 1D longitude vectors to fit within + the map edges. For example, if the central longitude is 90°, + the data is shifted so that it spans -90° to 270°. +aspect : {'equal', 'auto'} or float, default: :rc:`image.aspet` + Modify the axes aspect ratio. The aspect ratio is of particular relevance for + heatmaps since it may lead to non-square grid boxes. This parameter is a shortcut + for calling `~matplotlib.axes.set_aspect`. The options are as follows: + + * Number: The data aspect ratio. + * ``'equal'``: A data aspect ratio of 1. + * ``'auto'``: Allows the data aspect ratio to change depending on + the layout. In general this results in non-square grid boxes. + +Other parameters +---------------- +cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` + The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor + function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization + range contains negative and positive values then :rcraw:`cmap.diverging` is used. + Otherwise :rcraw:`cmap.sequential` is used. +cmap_kw : dict-like, optional + Passed to :class:`~ultraplot.constructor.Colormap`. +c, color, colors : color-spec or sequence of color-spec, optional + The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + If not passed, `cmap` is used. +norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` + The data value normalizer, passed to the `~ultraplot.constructor.Norm` + constructor function. If `discrete` is ``True`` then 1) this affects the default + level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and + 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they + are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). + If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains + negative and positive values then `~ultraplot.colors.DivergingNorm` is used. + Otherwise `~matplotlib.colors.Normalize` is used. +norm_kw : dict-like, optional + Passed to `~ultraplot.constructor.Norm`. +extend : {'neither', 'both', 'min', 'max'}, default: 'neither' + Direction for drawing colorbar "extensions" indicating + out-of-bounds data on the end of the colorbar. +discrete : bool, default: :rc:`cmap.discrete` + If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the + colormap. Instead, for non-contour plots, the number of levels will be + roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + using `levels=large_number` but it may improve rendering speed. Default is + ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` + and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. +sequential, diverging, cyclic, qualitative : bool, default: None + Boolean arguments used if `cmap` is not passed. Set these to ``True`` + to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, + :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. + The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + as the default continuous normalizer. +vmin, vmax : float, optional + The minimum and maximum color scale values used with the `norm` normalizer. + If `discrete` is ``False`` these are the absolute limits, and if `discrete` + is ``True`` these are the approximate limits used to automatically determine + `levels` or `values` lists at "nice" intervals. If `levels` or `values` were + already passed as lists, these are ignored, and `vmin` and `vmax` are set to + the minimum and maximum of the lists. If `robust` was passed, the default `vmin` + and `vmax` are some percentile range of the data values. Otherwise, the default + `vmin` and `vmax` are the minimum and maximum of the data values. +N + Shorthand for `levels`. +levels : int or sequence of float, default: :rc:`cmap.levels` + The number of level edges or a sequence of level edges. If the former, `locator` + is used to generate this many level edges at "nice" intervals. If the latter, + the levels should be monotonically increasing or decreasing (note decreasing + levels fail with ``contour`` plots). +values : int or sequence of float, default: None + The number of level centers or a sequence of level centers. If the former, + `locator` is used to generate this many level centers at "nice" intervals. + If the latter, levels are inferred using `~ultraplot.utils.edges`. + This will override any `levels` input. +center_levels : bool, default False + If set to true, the discrete color bar bins will be centered on the level values + instead of using the level values as the edges of the discrete bins. This option + can be used for diverging, discrete color bars with both positive and negative + data to ensure data near zero is properly represented. +robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` + If ``True`` and `vmin` or `vmax` were not provided, they are + determined from the 2nd and 98th data percentiles rather than the + minimum and maximum. If float, this percentile range is used (for example, + ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, + these specific percentiles should be used. This feature is useful + when your data has large outliers. +inbounds : bool, default: :rc:`cmap.inbounds` + If ``True`` and `vmin` or `vmax` were not provided, when axis limits + have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` + or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. + See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. +locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + The locator used to determine level locations if `levels` or `values` were not + already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. + Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. +locator_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Locator` class. +symmetric : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + symmetric about zero. +positive : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + positive with a minimum at zero. +negative : bool, default: False + If ``True``, the normaliation range or discrete colormap levels are + negative with a minimum at zero. +nozero : bool, default: False + If ``True``, ``0`` is removed from the level list. This is mainly useful for + single-color `~matplotlib.axes.Axes.contour` plots. +linewidths : unit-spec, default: 0.3 + The width of lines between grid boxes. Aliases: ``lw``, ``linewidth``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyles : str, default: '-' + The style of lines between grid boxes. Aliases: ``ls``, ``linestyle``. +edgecolors : color-spec, default: 'k' + The color of lines between grid boxes. Aliases: ``ec``, ``edgecolor``. +alpha : float, optional + The opacity of the grid boxes. Inferred from `cmap` by default. Aliases: ``a``, ``alphas``. +edgefix : bool or float, default: :rc:`edgefix` + Whether to fix the common issue where white lines appear between adjacent + patches in saved vector graphics (this can slow down figure rendering). + See this `github repo `__ for a + demonstration of the problem. If ``True``, a small default linewidth of + ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), + this specific linewidth is used to cover up the white lines. This feature is + automatically disabled when the patches have transparency. +label : str, optional + The legend label to be used for this object. In the case of + contours, this is paired with the the central artist in the artist + list returned by `matplotlib.contour.ContourSet.legend_elements`. +labels : bool, optional + Whether to apply labels to contours and grid boxes. The text will be + white when the luminance of the underlying filled contour or grid box + is less than 50 and black otherwise. +labels_kw : dict-like, optional + Ignored if `labels` is ``False``. Extra keyword args for the labels. + For contour plots, this is passed to `~matplotlib.axes.Axes.clabel`. + Otherwise, this is passed to `~matplotlib.axes.Axes.text`. +formatter, fmt : formatter-spec, optional + The `~matplotlib.ticker.Formatter` used to format number labels. + Passed to the `~ultraplot.constructor.Formatter` constructor. +formatter_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Formatter` class. +precision : int, optional + The maximum number of decimal places for number labels generated + with the default formatter `~ultraplot.ticker.Simpleformatter`. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `matplotlib.axes.Axes.pcolormesh`. + +See also +-------- +PlotAxes.pcolor +PlotAxes.pcolormesh +PlotAxes.pcolorfast +PlotAxes.heatmap +PlotAxes.tripcolor +matplotlib.axes.Axes.pcolormesh""" + ... + + def barbs(self, x: Incomplete, y: Incomplete, u: Incomplete, v: Incomplete, c: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot wind barbs. + +Parameters +---------- +*args : u, v or x, y, u, v + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `u` and `v` coordinates are passed, try to infer the `x` and `y` coordinates + from the :class:`~pandas.DataFrame` indices and columns or the :class:`~xarray.DataArray` + coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` + and the `x` coordinates are ``np.arange(0, y.shape[1])``. + * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using + `~ultraplot.utils.edges` or `:func:`~ultraplot.utils.edges2d`` if *centers* were provided. + For all other methods, calculate coordinate *centers* if *edges* were provided. + * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the + `u` and `v` coordinates are `pint.Quantity`, pass the magnitude to the plotting + command. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + +c, color, colors : array-like or color-spec, optional + The colors of the wind barbs passed as either a keyword argument + or a fifth positional argument. This can be a single color or + a color array to be scaled by `cmap` and `norm`. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. +transpose : bool, default: False + Whether to transpose the input data. This should be used when + passing datasets with column-major dimension order ``(x, y)``. + Otherwise row-major dimension order ``(y, x)`` is expected. +order : {'C', 'F'}, default: 'C' + Alternative to `transpose`. ``'C'`` corresponds to the default C-cyle + row-major ordering (equivalent to ``transpose=False``). ``'F'`` corresponds + to Fortran-style column-major ordering (equivalent to ``transpose=True``). +globe : bool, default: False + For `ultraplot.axes.GeoAxes` only. Whether to enforce global + coverage. When set to ``True`` this does the following: + + #. Interpolates input data to the North and South poles by setting the data + values at the poles to the mean from latitudes nearest each pole. + #. Makes meridional coverage "circular", i.e. the last longitude coordinate + equals the first longitude coordinate plus 360°. + #. When basemap is the backend, cycles 1D longitude vectors to fit within + the map edges. For example, if the central longitude is 90°, + the data is shifted so that it spans -90° to 270°. + +Other parameters +---------------- +cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` + The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor + function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization + range contains negative and positive values then :rcraw:`cmap.diverging` is used. + Otherwise :rcraw:`cmap.sequential` is used. +cmap_kw : dict-like, optional + Passed to :class:`~ultraplot.constructor.Colormap`. +c, color, colors : color-spec or sequence of color-spec, optional + The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + If not passed, `cmap` is used. +norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` + The data value normalizer, passed to the `~ultraplot.constructor.Norm` + constructor function. If `discrete` is ``True`` then 1) this affects the default + level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and + 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they + are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). + If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains + negative and positive values then `~ultraplot.colors.DivergingNorm` is used. + Otherwise `~matplotlib.colors.Normalize` is used. +norm_kw : dict-like, optional + Passed to `~ultraplot.constructor.Norm`. +extend : {'neither', 'both', 'min', 'max'}, default: 'neither' + Direction for drawing colorbar "extensions" indicating + out-of-bounds data on the end of the colorbar. +discrete : bool, default: :rc:`cmap.discrete` + If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the + colormap. Instead, for non-contour plots, the number of levels will be + roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + using `levels=large_number` but it may improve rendering speed. Default is + ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` + and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. +sequential, diverging, cyclic, qualitative : bool, default: None + Boolean arguments used if `cmap` is not passed. Set these to ``True`` + to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, + :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. + The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + as the default continuous normalizer. +vmin, vmax : float, optional + The minimum and maximum color scale values used with the `norm` normalizer. + If `discrete` is ``False`` these are the absolute limits, and if `discrete` + is ``True`` these are the approximate limits used to automatically determine + `levels` or `values` lists at "nice" intervals. If `levels` or `values` were + already passed as lists, these are ignored, and `vmin` and `vmax` are set to + the minimum and maximum of the lists. If `robust` was passed, the default `vmin` + and `vmax` are some percentile range of the data values. Otherwise, the default + `vmin` and `vmax` are the minimum and maximum of the data values. +N + Shorthand for `levels`. +levels : int or sequence of float, default: :rc:`cmap.levels` + The number of level edges or a sequence of level edges. If the former, `locator` + is used to generate this many level edges at "nice" intervals. If the latter, + the levels should be monotonically increasing or decreasing (note decreasing + levels fail with ``contour`` plots). +values : int or sequence of float, default: None + The number of level centers or a sequence of level centers. If the former, + `locator` is used to generate this many level centers at "nice" intervals. + If the latter, levels are inferred using `~ultraplot.utils.edges`. + This will override any `levels` input. +center_levels : bool, default False + If set to true, the discrete color bar bins will be centered on the level values + instead of using the level values as the edges of the discrete bins. This option + can be used for diverging, discrete color bars with both positive and negative + data to ensure data near zero is properly represented. +robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` + If ``True`` and `vmin` or `vmax` were not provided, they are + determined from the 2nd and 98th data percentiles rather than the + minimum and maximum. If float, this percentile range is used (for example, + ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, + these specific percentiles should be used. This feature is useful + when your data has large outliers. +inbounds : bool, default: :rc:`cmap.inbounds` + If ``True`` and `vmin` or `vmax` were not provided, when axis limits + have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` + or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. + See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. +locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + The locator used to determine level locations if `levels` or `values` were not + already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. + Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. +locator_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Locator` class. +symmetric : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + symmetric about zero. +positive : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + positive with a minimum at zero. +negative : bool, default: False + If ``True``, the normaliation range or discrete colormap levels are + negative with a minimum at zero. +nozero : bool, default: False + If ``True``, ``0`` is removed from the level list. This is mainly useful for + single-color `~matplotlib.axes.Axes.contour` plots. +**kwargs + Passed to `matplotlib.axes.Axes.barbs` + +See also +-------- +PlotAxes.barbs +PlotAxes.quiver +PlotAxes.stream +PlotAxes.streamplot +matplotlib.axes.Axes.barbs""" + ... + + def quiver(self, x: Incomplete, y: Incomplete, u: Incomplete, v: Incomplete, c: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot quiver arrows. + +Parameters +---------- +*args : u, v or x, y, u, v + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `u` and `v` coordinates are passed, try to infer the `x` and `y` coordinates + from the :class:`~pandas.DataFrame` indices and columns or the :class:`~xarray.DataArray` + coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` + and the `x` coordinates are ``np.arange(0, y.shape[1])``. + * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using + `~ultraplot.utils.edges` or `:func:`~ultraplot.utils.edges2d`` if *centers* were provided. + For all other methods, calculate coordinate *centers* if *edges* were provided. + * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the + `u` and `v` coordinates are `pint.Quantity`, pass the magnitude to the plotting + command. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + +c, color, colors : array-like or color-spec, optional + The colors of the quiver arrows passed as either a keyword argument + or a fifth positional argument. This can be a single color or + a color array to be scaled by `cmap` and `norm`. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. +transpose : bool, default: False + Whether to transpose the input data. This should be used when + passing datasets with column-major dimension order ``(x, y)``. + Otherwise row-major dimension order ``(y, x)`` is expected. +order : {'C', 'F'}, default: 'C' + Alternative to `transpose`. ``'C'`` corresponds to the default C-cyle + row-major ordering (equivalent to ``transpose=False``). ``'F'`` corresponds + to Fortran-style column-major ordering (equivalent to ``transpose=True``). +globe : bool, default: False + For `ultraplot.axes.GeoAxes` only. Whether to enforce global + coverage. When set to ``True`` this does the following: + + #. Interpolates input data to the North and South poles by setting the data + values at the poles to the mean from latitudes nearest each pole. + #. Makes meridional coverage "circular", i.e. the last longitude coordinate + equals the first longitude coordinate plus 360°. + #. When basemap is the backend, cycles 1D longitude vectors to fit within + the map edges. For example, if the central longitude is 90°, + the data is shifted so that it spans -90° to 270°. + +Other parameters +---------------- +cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` + The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor + function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization + range contains negative and positive values then :rcraw:`cmap.diverging` is used. + Otherwise :rcraw:`cmap.sequential` is used. +cmap_kw : dict-like, optional + Passed to :class:`~ultraplot.constructor.Colormap`. +c, color, colors : color-spec or sequence of color-spec, optional + The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + If not passed, `cmap` is used. +norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` + The data value normalizer, passed to the `~ultraplot.constructor.Norm` + constructor function. If `discrete` is ``True`` then 1) this affects the default + level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and + 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they + are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). + If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains + negative and positive values then `~ultraplot.colors.DivergingNorm` is used. + Otherwise `~matplotlib.colors.Normalize` is used. +norm_kw : dict-like, optional + Passed to `~ultraplot.constructor.Norm`. +extend : {'neither', 'both', 'min', 'max'}, default: 'neither' + Direction for drawing colorbar "extensions" indicating + out-of-bounds data on the end of the colorbar. +discrete : bool, default: :rc:`cmap.discrete` + If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the + colormap. Instead, for non-contour plots, the number of levels will be + roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + using `levels=large_number` but it may improve rendering speed. Default is + ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` + and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. +sequential, diverging, cyclic, qualitative : bool, default: None + Boolean arguments used if `cmap` is not passed. Set these to ``True`` + to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, + :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. + The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + as the default continuous normalizer. +vmin, vmax : float, optional + The minimum and maximum color scale values used with the `norm` normalizer. + If `discrete` is ``False`` these are the absolute limits, and if `discrete` + is ``True`` these are the approximate limits used to automatically determine + `levels` or `values` lists at "nice" intervals. If `levels` or `values` were + already passed as lists, these are ignored, and `vmin` and `vmax` are set to + the minimum and maximum of the lists. If `robust` was passed, the default `vmin` + and `vmax` are some percentile range of the data values. Otherwise, the default + `vmin` and `vmax` are the minimum and maximum of the data values. +N + Shorthand for `levels`. +levels : int or sequence of float, default: :rc:`cmap.levels` + The number of level edges or a sequence of level edges. If the former, `locator` + is used to generate this many level edges at "nice" intervals. If the latter, + the levels should be monotonically increasing or decreasing (note decreasing + levels fail with ``contour`` plots). +values : int or sequence of float, default: None + The number of level centers or a sequence of level centers. If the former, + `locator` is used to generate this many level centers at "nice" intervals. + If the latter, levels are inferred using `~ultraplot.utils.edges`. + This will override any `levels` input. +center_levels : bool, default False + If set to true, the discrete color bar bins will be centered on the level values + instead of using the level values as the edges of the discrete bins. This option + can be used for diverging, discrete color bars with both positive and negative + data to ensure data near zero is properly represented. +robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` + If ``True`` and `vmin` or `vmax` were not provided, they are + determined from the 2nd and 98th data percentiles rather than the + minimum and maximum. If float, this percentile range is used (for example, + ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, + these specific percentiles should be used. This feature is useful + when your data has large outliers. +inbounds : bool, default: :rc:`cmap.inbounds` + If ``True`` and `vmin` or `vmax` were not provided, when axis limits + have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` + or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. + See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. +locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + The locator used to determine level locations if `levels` or `values` were not + already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. + Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. +locator_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Locator` class. +symmetric : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + symmetric about zero. +positive : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + positive with a minimum at zero. +negative : bool, default: False + If ``True``, the normaliation range or discrete colormap levels are + negative with a minimum at zero. +nozero : bool, default: False + If ``True``, ``0`` is removed from the level list. This is mainly useful for + single-color `~matplotlib.axes.Axes.contour` plots. +**kwargs + Passed to `matplotlib.axes.Axes.quiver` + +See also +-------- +PlotAxes.barbs +PlotAxes.quiver +PlotAxes.stream +PlotAxes.streamplot +matplotlib.axes.Axes.quiver""" + ... + + def stream(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot streamlines. + +Parameters +---------- +*args : u, v or x, y, u, v + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `u` and `v` coordinates are passed, try to infer the `x` and `y` coordinates + from the :class:`~pandas.DataFrame` indices and columns or the :class:`~xarray.DataArray` + coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` + and the `x` coordinates are ``np.arange(0, y.shape[1])``. + * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using + `~ultraplot.utils.edges` or `:func:`~ultraplot.utils.edges2d`` if *centers* were provided. + For all other methods, calculate coordinate *centers* if *edges* were provided. + * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the + `u` and `v` coordinates are `pint.Quantity`, pass the magnitude to the plotting + command. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + +c, color, colors : array-like or color-spec, optional + The colors of the streamlines passed as either a keyword argument + or a fifth positional argument. This can be a single color or + a color array to be scaled by `cmap` and `norm`. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. +transpose : bool, default: False + Whether to transpose the input data. This should be used when + passing datasets with column-major dimension order ``(x, y)``. + Otherwise row-major dimension order ``(y, x)`` is expected. +order : {'C', 'F'}, default: 'C' + Alternative to `transpose`. ``'C'`` corresponds to the default C-cyle + row-major ordering (equivalent to ``transpose=False``). ``'F'`` corresponds + to Fortran-style column-major ordering (equivalent to ``transpose=True``). +globe : bool, default: False + For `ultraplot.axes.GeoAxes` only. Whether to enforce global + coverage. When set to ``True`` this does the following: + + #. Interpolates input data to the North and South poles by setting the data + values at the poles to the mean from latitudes nearest each pole. + #. Makes meridional coverage "circular", i.e. the last longitude coordinate + equals the first longitude coordinate plus 360°. + #. When basemap is the backend, cycles 1D longitude vectors to fit within + the map edges. For example, if the central longitude is 90°, + the data is shifted so that it spans -90° to 270°. + +Other parameters +---------------- +cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` + The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor + function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization + range contains negative and positive values then :rcraw:`cmap.diverging` is used. + Otherwise :rcraw:`cmap.sequential` is used. +cmap_kw : dict-like, optional + Passed to :class:`~ultraplot.constructor.Colormap`. +c, color, colors : color-spec or sequence of color-spec, optional + The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + If not passed, `cmap` is used. +norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` + The data value normalizer, passed to the `~ultraplot.constructor.Norm` + constructor function. If `discrete` is ``True`` then 1) this affects the default + level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and + 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they + are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). + If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains + negative and positive values then `~ultraplot.colors.DivergingNorm` is used. + Otherwise `~matplotlib.colors.Normalize` is used. +norm_kw : dict-like, optional + Passed to `~ultraplot.constructor.Norm`. +extend : {'neither', 'both', 'min', 'max'}, default: 'neither' + Direction for drawing colorbar "extensions" indicating + out-of-bounds data on the end of the colorbar. +discrete : bool, default: :rc:`cmap.discrete` + If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the + colormap. Instead, for non-contour plots, the number of levels will be + roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + using `levels=large_number` but it may improve rendering speed. Default is + ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` + and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. +sequential, diverging, cyclic, qualitative : bool, default: None + Boolean arguments used if `cmap` is not passed. Set these to ``True`` + to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, + :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. + The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + as the default continuous normalizer. +vmin, vmax : float, optional + The minimum and maximum color scale values used with the `norm` normalizer. + If `discrete` is ``False`` these are the absolute limits, and if `discrete` + is ``True`` these are the approximate limits used to automatically determine + `levels` or `values` lists at "nice" intervals. If `levels` or `values` were + already passed as lists, these are ignored, and `vmin` and `vmax` are set to + the minimum and maximum of the lists. If `robust` was passed, the default `vmin` + and `vmax` are some percentile range of the data values. Otherwise, the default + `vmin` and `vmax` are the minimum and maximum of the data values. +N + Shorthand for `levels`. +levels : int or sequence of float, default: :rc:`cmap.levels` + The number of level edges or a sequence of level edges. If the former, `locator` + is used to generate this many level edges at "nice" intervals. If the latter, + the levels should be monotonically increasing or decreasing (note decreasing + levels fail with ``contour`` plots). +values : int or sequence of float, default: None + The number of level centers or a sequence of level centers. If the former, + `locator` is used to generate this many level centers at "nice" intervals. + If the latter, levels are inferred using `~ultraplot.utils.edges`. + This will override any `levels` input. +center_levels : bool, default False + If set to true, the discrete color bar bins will be centered on the level values + instead of using the level values as the edges of the discrete bins. This option + can be used for diverging, discrete color bars with both positive and negative + data to ensure data near zero is properly represented. +robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` + If ``True`` and `vmin` or `vmax` were not provided, they are + determined from the 2nd and 98th data percentiles rather than the + minimum and maximum. If float, this percentile range is used (for example, + ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, + these specific percentiles should be used. This feature is useful + when your data has large outliers. +inbounds : bool, default: :rc:`cmap.inbounds` + If ``True`` and `vmin` or `vmax` were not provided, when axis limits + have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` + or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. + See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. +locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + The locator used to determine level locations if `levels` or `values` were not + already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. + Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. +locator_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Locator` class. +symmetric : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + symmetric about zero. +positive : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + positive with a minimum at zero. +negative : bool, default: False + If ``True``, the normaliation range or discrete colormap levels are + negative with a minimum at zero. +nozero : bool, default: False + If ``True``, ``0`` is removed from the level list. This is mainly useful for + single-color `~matplotlib.axes.Axes.contour` plots. +**kwargs + Passed to `matplotlib.axes.Axes.streamplot` + +See also +-------- +PlotAxes.barbs +PlotAxes.quiver +PlotAxes.stream +PlotAxes.streamplot +matplotlib.axes.Axes.streamplot""" + ... + + def streamplot(self, x: Incomplete, y: Incomplete, u: Incomplete, v: Incomplete, c: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot streamlines. + +Parameters +---------- +*args : u, v or x, y, u, v + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `u` and `v` coordinates are passed, try to infer the `x` and `y` coordinates + from the :class:`~pandas.DataFrame` indices and columns or the :class:`~xarray.DataArray` + coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` + and the `x` coordinates are ``np.arange(0, y.shape[1])``. + * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using + `~ultraplot.utils.edges` or `:func:`~ultraplot.utils.edges2d`` if *centers* were provided. + For all other methods, calculate coordinate *centers* if *edges* were provided. + * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the + `u` and `v` coordinates are `pint.Quantity`, pass the magnitude to the plotting + command. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + +c, color, colors : array-like or color-spec, optional + The colors of the streamlines passed as either a keyword argument + or a fifth positional argument. This can be a single color or + a color array to be scaled by `cmap` and `norm`. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. +transpose : bool, default: False + Whether to transpose the input data. This should be used when + passing datasets with column-major dimension order ``(x, y)``. + Otherwise row-major dimension order ``(y, x)`` is expected. +order : {'C', 'F'}, default: 'C' + Alternative to `transpose`. ``'C'`` corresponds to the default C-cyle + row-major ordering (equivalent to ``transpose=False``). ``'F'`` corresponds + to Fortran-style column-major ordering (equivalent to ``transpose=True``). +globe : bool, default: False + For `ultraplot.axes.GeoAxes` only. Whether to enforce global + coverage. When set to ``True`` this does the following: + + #. Interpolates input data to the North and South poles by setting the data + values at the poles to the mean from latitudes nearest each pole. + #. Makes meridional coverage "circular", i.e. the last longitude coordinate + equals the first longitude coordinate plus 360°. + #. When basemap is the backend, cycles 1D longitude vectors to fit within + the map edges. For example, if the central longitude is 90°, + the data is shifted so that it spans -90° to 270°. + +Other parameters +---------------- +cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` + The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor + function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization + range contains negative and positive values then :rcraw:`cmap.diverging` is used. + Otherwise :rcraw:`cmap.sequential` is used. +cmap_kw : dict-like, optional + Passed to :class:`~ultraplot.constructor.Colormap`. +c, color, colors : color-spec or sequence of color-spec, optional + The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + If not passed, `cmap` is used. +norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` + The data value normalizer, passed to the `~ultraplot.constructor.Norm` + constructor function. If `discrete` is ``True`` then 1) this affects the default + level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and + 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they + are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). + If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains + negative and positive values then `~ultraplot.colors.DivergingNorm` is used. + Otherwise `~matplotlib.colors.Normalize` is used. +norm_kw : dict-like, optional + Passed to `~ultraplot.constructor.Norm`. +extend : {'neither', 'both', 'min', 'max'}, default: 'neither' + Direction for drawing colorbar "extensions" indicating + out-of-bounds data on the end of the colorbar. +discrete : bool, default: :rc:`cmap.discrete` + If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the + colormap. Instead, for non-contour plots, the number of levels will be + roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + using `levels=large_number` but it may improve rendering speed. Default is + ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` + and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. +sequential, diverging, cyclic, qualitative : bool, default: None + Boolean arguments used if `cmap` is not passed. Set these to ``True`` + to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, + :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. + The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + as the default continuous normalizer. +vmin, vmax : float, optional + The minimum and maximum color scale values used with the `norm` normalizer. + If `discrete` is ``False`` these are the absolute limits, and if `discrete` + is ``True`` these are the approximate limits used to automatically determine + `levels` or `values` lists at "nice" intervals. If `levels` or `values` were + already passed as lists, these are ignored, and `vmin` and `vmax` are set to + the minimum and maximum of the lists. If `robust` was passed, the default `vmin` + and `vmax` are some percentile range of the data values. Otherwise, the default + `vmin` and `vmax` are the minimum and maximum of the data values. +N + Shorthand for `levels`. +levels : int or sequence of float, default: :rc:`cmap.levels` + The number of level edges or a sequence of level edges. If the former, `locator` + is used to generate this many level edges at "nice" intervals. If the latter, + the levels should be monotonically increasing or decreasing (note decreasing + levels fail with ``contour`` plots). +values : int or sequence of float, default: None + The number of level centers or a sequence of level centers. If the former, + `locator` is used to generate this many level centers at "nice" intervals. + If the latter, levels are inferred using `~ultraplot.utils.edges`. + This will override any `levels` input. +center_levels : bool, default False + If set to true, the discrete color bar bins will be centered on the level values + instead of using the level values as the edges of the discrete bins. This option + can be used for diverging, discrete color bars with both positive and negative + data to ensure data near zero is properly represented. +robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` + If ``True`` and `vmin` or `vmax` were not provided, they are + determined from the 2nd and 98th data percentiles rather than the + minimum and maximum. If float, this percentile range is used (for example, + ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, + these specific percentiles should be used. This feature is useful + when your data has large outliers. +inbounds : bool, default: :rc:`cmap.inbounds` + If ``True`` and `vmin` or `vmax` were not provided, when axis limits + have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` + or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. + See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. +locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + The locator used to determine level locations if `levels` or `values` were not + already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. + Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. +locator_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Locator` class. +symmetric : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + symmetric about zero. +positive : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + positive with a minimum at zero. +negative : bool, default: False + If ``True``, the normaliation range or discrete colormap levels are + negative with a minimum at zero. +nozero : bool, default: False + If ``True``, ``0`` is removed from the level list. This is mainly useful for + single-color `~matplotlib.axes.Axes.contour` plots. +**kwargs + Passed to `matplotlib.axes.Axes.streamplot` + +See also +-------- +PlotAxes.barbs +PlotAxes.quiver +PlotAxes.stream +PlotAxes.streamplot +matplotlib.axes.Axes.streamplot""" + ... + + def tricontour(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot contour lines on a triangular grid. + +Parameters +---------- +*args : z or x, y, z + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `z` coordinates are passed, try to infer the `x` and `y` coordinates + from the :class:`~pandas.DataFrame` indices and columns or the :class:`~xarray.DataArray` + coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` + and the `x` coordinates are ``np.arange(0, y.shape[1])``. + * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using + `~ultraplot.utils.edges` or `:func:`~ultraplot.utils.edges2d`` if *centers* were provided. + For all other methods, calculate coordinate *centers* if *edges* were provided. + * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the + `z` coordinates are `pint.Quantity`, pass the magnitude to the plotting + command. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. +transpose : bool, default: False + Whether to transpose the input data. This should be used when + passing datasets with column-major dimension order ``(x, y)``. + Otherwise row-major dimension order ``(y, x)`` is expected. +order : {'C', 'F'}, default: 'C' + Alternative to `transpose`. ``'C'`` corresponds to the default C-cyle + row-major ordering (equivalent to ``transpose=False``). ``'F'`` corresponds + to Fortran-style column-major ordering (equivalent to ``transpose=True``). +globe : bool, default: False + For `ultraplot.axes.GeoAxes` only. Whether to enforce global + coverage. When set to ``True`` this does the following: + + #. Interpolates input data to the North and South poles by setting the data + values at the poles to the mean from latitudes nearest each pole. + #. Makes meridional coverage "circular", i.e. the last longitude coordinate + equals the first longitude coordinate plus 360°. + #. When basemap is the backend, cycles 1D longitude vectors to fit within + the map edges. For example, if the central longitude is 90°, + the data is shifted so that it spans -90° to 270°. + +Other parameters +---------------- +cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` + The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor + function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization + range contains negative and positive values then :rcraw:`cmap.diverging` is used. + Otherwise :rcraw:`cmap.sequential` is used. +cmap_kw : dict-like, optional + Passed to :class:`~ultraplot.constructor.Colormap`. +c, color, colors : color-spec or sequence of color-spec, optional + The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + If not passed, `cmap` is used. +norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` + The data value normalizer, passed to the `~ultraplot.constructor.Norm` + constructor function. If `discrete` is ``True`` then 1) this affects the default + level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and + 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they + are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). + If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains + negative and positive values then `~ultraplot.colors.DivergingNorm` is used. + Otherwise `~matplotlib.colors.Normalize` is used. +norm_kw : dict-like, optional + Passed to `~ultraplot.constructor.Norm`. +extend : {'neither', 'both', 'min', 'max'}, default: 'neither' + Direction for drawing colorbar "extensions" indicating + out-of-bounds data on the end of the colorbar. +discrete : bool, default: :rc:`cmap.discrete` + If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the + colormap. Instead, for non-contour plots, the number of levels will be + roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + using `levels=large_number` but it may improve rendering speed. Default is + ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` + and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. +sequential, diverging, cyclic, qualitative : bool, default: None + Boolean arguments used if `cmap` is not passed. Set these to ``True`` + to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, + :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. + The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + as the default continuous normalizer. +vmin, vmax : float, optional + The minimum and maximum color scale values used with the `norm` normalizer. + If `discrete` is ``False`` these are the absolute limits, and if `discrete` + is ``True`` these are the approximate limits used to automatically determine + `levels` or `values` lists at "nice" intervals. If `levels` or `values` were + already passed as lists, these are ignored, and `vmin` and `vmax` are set to + the minimum and maximum of the lists. If `robust` was passed, the default `vmin` + and `vmax` are some percentile range of the data values. Otherwise, the default + `vmin` and `vmax` are the minimum and maximum of the data values. +N + Shorthand for `levels`. +levels : int or sequence of float, default: :rc:`cmap.levels` + The number of level edges or a sequence of level edges. If the former, `locator` + is used to generate this many level edges at "nice" intervals. If the latter, + the levels should be monotonically increasing or decreasing (note decreasing + levels fail with ``contour`` plots). +values : int or sequence of float, default: None + The number of level centers or a sequence of level centers. If the former, + `locator` is used to generate this many level centers at "nice" intervals. + If the latter, levels are inferred using `~ultraplot.utils.edges`. + This will override any `levels` input. +center_levels : bool, default False + If set to true, the discrete color bar bins will be centered on the level values + instead of using the level values as the edges of the discrete bins. This option + can be used for diverging, discrete color bars with both positive and negative + data to ensure data near zero is properly represented. +robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` + If ``True`` and `vmin` or `vmax` were not provided, they are + determined from the 2nd and 98th data percentiles rather than the + minimum and maximum. If float, this percentile range is used (for example, + ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, + these specific percentiles should be used. This feature is useful + when your data has large outliers. +inbounds : bool, default: :rc:`cmap.inbounds` + If ``True`` and `vmin` or `vmax` were not provided, when axis limits + have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` + or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. + See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. +locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + The locator used to determine level locations if `levels` or `values` were not + already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. + Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. +locator_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Locator` class. +symmetric : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + symmetric about zero. +positive : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + positive with a minimum at zero. +negative : bool, default: False + If ``True``, the normaliation range or discrete colormap levels are + negative with a minimum at zero. +nozero : bool, default: False + If ``True``, ``0`` is removed from the level list. This is mainly useful for + single-color `~matplotlib.axes.Axes.contour` plots. +linewidths : unit-spec, default: 0.3 or :rc:`lines.linewidth` + The width of the line contours. Default is ``0.3`` when adding to filled contours + or :rc:`lines.linewidth` otherwise. Aliases: ``lw``, ``linewidth``. If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyles : str, default: '-' or :rc:`contour.negative_linestyle` + The style of the line contours. Default is ``'-'`` for positive contours and + :rcraw:`contour.negative_linestyle` for negative contours. Aliases: ``ls``, ``linestyle``. +edgecolors : color-spec, default: 'k' or inferred + The color of the line contours. Default is ``'k'`` when adding to filled contours + or inferred from `color` or `cmap` otherwise. Aliases: ``ec``, ``edgecolor``. +alpha : float, optional + The opacity of the contours. Inferred from `edgecolors` by default. Aliases: ``a``, ``alphas``. +label : str, optional + The legend label to be used for this object. In the case of + contours, this is paired with the the central artist in the artist + list returned by `matplotlib.contour.ContourSet.legend_elements`. +labels : bool, optional + Whether to apply labels to contours and grid boxes. The text will be + white when the luminance of the underlying filled contour or grid box + is less than 50 and black otherwise. +labels_kw : dict-like, optional + Ignored if `labels` is ``False``. Extra keyword args for the labels. + For contour plots, this is passed to `~matplotlib.axes.Axes.clabel`. + Otherwise, this is passed to `~matplotlib.axes.Axes.text`. +formatter, fmt : formatter-spec, optional + The `~matplotlib.ticker.Formatter` used to format number labels. + Passed to the `~ultraplot.constructor.Formatter` constructor. +formatter_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Formatter` class. +precision : int, optional + The maximum number of decimal places for number labels generated + with the default formatter `~ultraplot.ticker.Simpleformatter`. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `matplotlib.axes.Axes.tricontour`. + +See also +-------- +PlotAxes.contour +PlotAxes.contourf +PlotAxes.tricontour +PlotAxes.tricontourf +matplotlib.axes.Axes.tricontour""" + ... + + def tricontourf(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot filled contours on a triangular grid. + +Parameters +---------- +*args : z or x, y, z + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `z` coordinates are passed, try to infer the `x` and `y` coordinates + from the :class:`~pandas.DataFrame` indices and columns or the :class:`~xarray.DataArray` + coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` + and the `x` coordinates are ``np.arange(0, y.shape[1])``. + * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using + `~ultraplot.utils.edges` or `:func:`~ultraplot.utils.edges2d`` if *centers* were provided. + For all other methods, calculate coordinate *centers* if *edges* were provided. + * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the + `z` coordinates are `pint.Quantity`, pass the magnitude to the plotting + command. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. +transpose : bool, default: False + Whether to transpose the input data. This should be used when + passing datasets with column-major dimension order ``(x, y)``. + Otherwise row-major dimension order ``(y, x)`` is expected. +order : {'C', 'F'}, default: 'C' + Alternative to `transpose`. ``'C'`` corresponds to the default C-cyle + row-major ordering (equivalent to ``transpose=False``). ``'F'`` corresponds + to Fortran-style column-major ordering (equivalent to ``transpose=True``). +globe : bool, default: False + For `ultraplot.axes.GeoAxes` only. Whether to enforce global + coverage. When set to ``True`` this does the following: + + #. Interpolates input data to the North and South poles by setting the data + values at the poles to the mean from latitudes nearest each pole. + #. Makes meridional coverage "circular", i.e. the last longitude coordinate + equals the first longitude coordinate plus 360°. + #. When basemap is the backend, cycles 1D longitude vectors to fit within + the map edges. For example, if the central longitude is 90°, + the data is shifted so that it spans -90° to 270°. + +Other parameters +---------------- +cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` + The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor + function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization + range contains negative and positive values then :rcraw:`cmap.diverging` is used. + Otherwise :rcraw:`cmap.sequential` is used. +cmap_kw : dict-like, optional + Passed to :class:`~ultraplot.constructor.Colormap`. +c, color, colors : color-spec or sequence of color-spec, optional + The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + If not passed, `cmap` is used. +norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` + The data value normalizer, passed to the `~ultraplot.constructor.Norm` + constructor function. If `discrete` is ``True`` then 1) this affects the default + level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and + 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they + are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). + If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains + negative and positive values then `~ultraplot.colors.DivergingNorm` is used. + Otherwise `~matplotlib.colors.Normalize` is used. +norm_kw : dict-like, optional + Passed to `~ultraplot.constructor.Norm`. +extend : {'neither', 'both', 'min', 'max'}, default: 'neither' + Direction for drawing colorbar "extensions" indicating + out-of-bounds data on the end of the colorbar. +discrete : bool, default: :rc:`cmap.discrete` + If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the + colormap. Instead, for non-contour plots, the number of levels will be + roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + using `levels=large_number` but it may improve rendering speed. Default is + ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` + and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. +sequential, diverging, cyclic, qualitative : bool, default: None + Boolean arguments used if `cmap` is not passed. Set these to ``True`` + to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, + :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. + The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + as the default continuous normalizer. +vmin, vmax : float, optional + The minimum and maximum color scale values used with the `norm` normalizer. + If `discrete` is ``False`` these are the absolute limits, and if `discrete` + is ``True`` these are the approximate limits used to automatically determine + `levels` or `values` lists at "nice" intervals. If `levels` or `values` were + already passed as lists, these are ignored, and `vmin` and `vmax` are set to + the minimum and maximum of the lists. If `robust` was passed, the default `vmin` + and `vmax` are some percentile range of the data values. Otherwise, the default + `vmin` and `vmax` are the minimum and maximum of the data values. +N + Shorthand for `levels`. +levels : int or sequence of float, default: :rc:`cmap.levels` + The number of level edges or a sequence of level edges. If the former, `locator` + is used to generate this many level edges at "nice" intervals. If the latter, + the levels should be monotonically increasing or decreasing (note decreasing + levels fail with ``contour`` plots). +values : int or sequence of float, default: None + The number of level centers or a sequence of level centers. If the former, + `locator` is used to generate this many level centers at "nice" intervals. + If the latter, levels are inferred using `~ultraplot.utils.edges`. + This will override any `levels` input. +center_levels : bool, default False + If set to true, the discrete color bar bins will be centered on the level values + instead of using the level values as the edges of the discrete bins. This option + can be used for diverging, discrete color bars with both positive and negative + data to ensure data near zero is properly represented. +robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` + If ``True`` and `vmin` or `vmax` were not provided, they are + determined from the 2nd and 98th data percentiles rather than the + minimum and maximum. If float, this percentile range is used (for example, + ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, + these specific percentiles should be used. This feature is useful + when your data has large outliers. +inbounds : bool, default: :rc:`cmap.inbounds` + If ``True`` and `vmin` or `vmax` were not provided, when axis limits + have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` + or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. + See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. +locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + The locator used to determine level locations if `levels` or `values` were not + already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. + Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. +locator_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Locator` class. +symmetric : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + symmetric about zero. +positive : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + positive with a minimum at zero. +negative : bool, default: False + If ``True``, the normaliation range or discrete colormap levels are + negative with a minimum at zero. +nozero : bool, default: False + If ``True``, ``0`` is removed from the level list. This is mainly useful for + single-color `~matplotlib.axes.Axes.contour` plots. +linewidths : unit-spec, default: 0.3 or :rc:`lines.linewidth` + The width of the line contours. Default is ``0.3`` when adding to filled contours + or :rc:`lines.linewidth` otherwise. Aliases: ``lw``, ``linewidth``. If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyles : str, default: '-' or :rc:`contour.negative_linestyle` + The style of the line contours. Default is ``'-'`` for positive contours and + :rcraw:`contour.negative_linestyle` for negative contours. Aliases: ``ls``, ``linestyle``. +edgecolors : color-spec, default: 'k' or inferred + The color of the line contours. Default is ``'k'`` when adding to filled contours + or inferred from `color` or `cmap` otherwise. Aliases: ``ec``, ``edgecolor``. +alpha : float, optional + The opacity of the contours. Inferred from `edgecolors` by default. Aliases: ``a``, ``alphas``. +edgefix : bool or float, default: :rc:`edgefix` + Whether to fix the common issue where white lines appear between adjacent + patches in saved vector graphics (this can slow down figure rendering). + See this `github repo `__ for a + demonstration of the problem. If ``True``, a small default linewidth of + ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), + this specific linewidth is used to cover up the white lines. This feature is + automatically disabled when the patches have transparency. +label : str, optional + The legend label to be used for this object. In the case of + contours, this is paired with the the central artist in the artist + list returned by `matplotlib.contour.ContourSet.legend_elements`. +labels : bool, optional + Whether to apply labels to contours and grid boxes. The text will be + white when the luminance of the underlying filled contour or grid box + is less than 50 and black otherwise. +labels_kw : dict-like, optional + Ignored if `labels` is ``False``. Extra keyword args for the labels. + For contour plots, this is passed to `~matplotlib.axes.Axes.clabel`. + Otherwise, this is passed to `~matplotlib.axes.Axes.text`. +formatter, fmt : formatter-spec, optional + The `~matplotlib.ticker.Formatter` used to format number labels. + Passed to the `~ultraplot.constructor.Formatter` constructor. +formatter_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Formatter` class. +precision : int, optional + The maximum number of decimal places for number labels generated + with the default formatter `~ultraplot.ticker.Simpleformatter`. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `matplotlib.axes.Axes.tricontourf`. + +See also +-------- +PlotAxes.contour +PlotAxes.contourf +PlotAxes.tricontour +PlotAxes.tricontourf +matplotlib.axes.Axes.tricontourf""" + ... + + def tripcolor(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot triangular grid boxes. + +Parameters +---------- +*args : z or x, y, z + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `z` coordinates are passed, try to infer the `x` and `y` coordinates + from the :class:`~pandas.DataFrame` indices and columns or the :class:`~xarray.DataArray` + coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` + and the `x` coordinates are ``np.arange(0, y.shape[1])``. + * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using + `~ultraplot.utils.edges` or `:func:`~ultraplot.utils.edges2d`` if *centers* were provided. + For all other methods, calculate coordinate *centers* if *edges* were provided. + * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the + `z` coordinates are `pint.Quantity`, pass the magnitude to the plotting + command. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. +transpose : bool, default: False + Whether to transpose the input data. This should be used when + passing datasets with column-major dimension order ``(x, y)``. + Otherwise row-major dimension order ``(y, x)`` is expected. +order : {'C', 'F'}, default: 'C' + Alternative to `transpose`. ``'C'`` corresponds to the default C-cyle + row-major ordering (equivalent to ``transpose=False``). ``'F'`` corresponds + to Fortran-style column-major ordering (equivalent to ``transpose=True``). +globe : bool, default: False + For `ultraplot.axes.GeoAxes` only. Whether to enforce global + coverage. When set to ``True`` this does the following: + + #. Interpolates input data to the North and South poles by setting the data + values at the poles to the mean from latitudes nearest each pole. + #. Makes meridional coverage "circular", i.e. the last longitude coordinate + equals the first longitude coordinate plus 360°. + #. When basemap is the backend, cycles 1D longitude vectors to fit within + the map edges. For example, if the central longitude is 90°, + the data is shifted so that it spans -90° to 270°. + +Other parameters +---------------- +cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` + The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor + function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization + range contains negative and positive values then :rcraw:`cmap.diverging` is used. + Otherwise :rcraw:`cmap.sequential` is used. +cmap_kw : dict-like, optional + Passed to :class:`~ultraplot.constructor.Colormap`. +c, color, colors : color-spec or sequence of color-spec, optional + The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + If not passed, `cmap` is used. +norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` + The data value normalizer, passed to the `~ultraplot.constructor.Norm` + constructor function. If `discrete` is ``True`` then 1) this affects the default + level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and + 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they + are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). + If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains + negative and positive values then `~ultraplot.colors.DivergingNorm` is used. + Otherwise `~matplotlib.colors.Normalize` is used. +norm_kw : dict-like, optional + Passed to `~ultraplot.constructor.Norm`. +extend : {'neither', 'both', 'min', 'max'}, default: 'neither' + Direction for drawing colorbar "extensions" indicating + out-of-bounds data on the end of the colorbar. +discrete : bool, default: :rc:`cmap.discrete` + If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the + colormap. Instead, for non-contour plots, the number of levels will be + roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + using `levels=large_number` but it may improve rendering speed. Default is + ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` + and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. +sequential, diverging, cyclic, qualitative : bool, default: None + Boolean arguments used if `cmap` is not passed. Set these to ``True`` + to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, + :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. + The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + as the default continuous normalizer. +vmin, vmax : float, optional + The minimum and maximum color scale values used with the `norm` normalizer. + If `discrete` is ``False`` these are the absolute limits, and if `discrete` + is ``True`` these are the approximate limits used to automatically determine + `levels` or `values` lists at "nice" intervals. If `levels` or `values` were + already passed as lists, these are ignored, and `vmin` and `vmax` are set to + the minimum and maximum of the lists. If `robust` was passed, the default `vmin` + and `vmax` are some percentile range of the data values. Otherwise, the default + `vmin` and `vmax` are the minimum and maximum of the data values. +N + Shorthand for `levels`. +levels : int or sequence of float, default: :rc:`cmap.levels` + The number of level edges or a sequence of level edges. If the former, `locator` + is used to generate this many level edges at "nice" intervals. If the latter, + the levels should be monotonically increasing or decreasing (note decreasing + levels fail with ``contour`` plots). +values : int or sequence of float, default: None + The number of level centers or a sequence of level centers. If the former, + `locator` is used to generate this many level centers at "nice" intervals. + If the latter, levels are inferred using `~ultraplot.utils.edges`. + This will override any `levels` input. +center_levels : bool, default False + If set to true, the discrete color bar bins will be centered on the level values + instead of using the level values as the edges of the discrete bins. This option + can be used for diverging, discrete color bars with both positive and negative + data to ensure data near zero is properly represented. +robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` + If ``True`` and `vmin` or `vmax` were not provided, they are + determined from the 2nd and 98th data percentiles rather than the + minimum and maximum. If float, this percentile range is used (for example, + ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, + these specific percentiles should be used. This feature is useful + when your data has large outliers. +inbounds : bool, default: :rc:`cmap.inbounds` + If ``True`` and `vmin` or `vmax` were not provided, when axis limits + have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` + or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. + See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. +locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + The locator used to determine level locations if `levels` or `values` were not + already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. + Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. +locator_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Locator` class. +symmetric : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + symmetric about zero. +positive : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + positive with a minimum at zero. +negative : bool, default: False + If ``True``, the normaliation range or discrete colormap levels are + negative with a minimum at zero. +nozero : bool, default: False + If ``True``, ``0`` is removed from the level list. This is mainly useful for + single-color `~matplotlib.axes.Axes.contour` plots. +linewidths : unit-spec, default: 0.3 + The width of lines between grid boxes. Aliases: ``lw``, ``linewidth``. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +linestyles : str, default: '-' + The style of lines between grid boxes. Aliases: ``ls``, ``linestyle``. +edgecolors : color-spec, default: 'k' + The color of lines between grid boxes. Aliases: ``ec``, ``edgecolor``. +alpha : float, optional + The opacity of the grid boxes. Inferred from `cmap` by default. Aliases: ``a``, ``alphas``. +edgefix : bool or float, default: :rc:`edgefix` + Whether to fix the common issue where white lines appear between adjacent + patches in saved vector graphics (this can slow down figure rendering). + See this `github repo `__ for a + demonstration of the problem. If ``True``, a small default linewidth of + ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), + this specific linewidth is used to cover up the white lines. This feature is + automatically disabled when the patches have transparency. +label : str, optional + The legend label to be used for this object. In the case of + contours, this is paired with the the central artist in the artist + list returned by `matplotlib.contour.ContourSet.legend_elements`. +labels : bool, optional + Whether to apply labels to contours and grid boxes. The text will be + white when the luminance of the underlying filled contour or grid box + is less than 50 and black otherwise. +labels_kw : dict-like, optional + Ignored if `labels` is ``False``. Extra keyword args for the labels. + For contour plots, this is passed to `~matplotlib.axes.Axes.clabel`. + Otherwise, this is passed to `~matplotlib.axes.Axes.text`. +formatter, fmt : formatter-spec, optional + The `~matplotlib.ticker.Formatter` used to format number labels. + Passed to the `~ultraplot.constructor.Formatter` constructor. +formatter_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Formatter` class. +precision : int, optional + The maximum number of decimal places for number labels generated + with the default formatter `~ultraplot.ticker.Simpleformatter`. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `matplotlib.axes.Axes.tripcolor`. + +See also +-------- +PlotAxes.pcolor +PlotAxes.pcolormesh +PlotAxes.pcolorfast +PlotAxes.heatmap +PlotAxes.tripcolor +matplotlib.axes.Axes.tripcolor""" + ... + + def imshow(self, z: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot an image. + +Parameters +---------- +z : array-like + The data passed as a positional argument or keyword argument. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` + The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor + function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization + range contains negative and positive values then :rcraw:`cmap.diverging` is used. + Otherwise :rcraw:`cmap.sequential` is used. +cmap_kw : dict-like, optional + Passed to :class:`~ultraplot.constructor.Colormap`. +c, color, colors : color-spec or sequence of color-spec, optional + The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + If not passed, `cmap` is used. +norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` + The data value normalizer, passed to the `~ultraplot.constructor.Norm` + constructor function. If `discrete` is ``True`` then 1) this affects the default + level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and + 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they + are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). + If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains + negative and positive values then `~ultraplot.colors.DivergingNorm` is used. + Otherwise `~matplotlib.colors.Normalize` is used. +norm_kw : dict-like, optional + Passed to `~ultraplot.constructor.Norm`. +extend : {'neither', 'both', 'min', 'max'}, default: 'neither' + Direction for drawing colorbar "extensions" indicating + out-of-bounds data on the end of the colorbar. +discrete : bool, default: :rc:`cmap.discrete` + If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the + colormap. Instead, for non-contour plots, the number of levels will be + roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + using `levels=large_number` but it may improve rendering speed. Default is + ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` + and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. +sequential, diverging, cyclic, qualitative : bool, default: None + Boolean arguments used if `cmap` is not passed. Set these to ``True`` + to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, + :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. + The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + as the default continuous normalizer. +vmin, vmax : float, optional + The minimum and maximum color scale values used with the `norm` normalizer. + If `discrete` is ``False`` these are the absolute limits, and if `discrete` + is ``True`` these are the approximate limits used to automatically determine + `levels` or `values` lists at "nice" intervals. If `levels` or `values` were + already passed as lists, these are ignored, and `vmin` and `vmax` are set to + the minimum and maximum of the lists. If `robust` was passed, the default `vmin` + and `vmax` are some percentile range of the data values. Otherwise, the default + `vmin` and `vmax` are the minimum and maximum of the data values. +N + Shorthand for `levels`. +levels : int or sequence of float, default: :rc:`cmap.levels` + The number of level edges or a sequence of level edges. If the former, `locator` + is used to generate this many level edges at "nice" intervals. If the latter, + the levels should be monotonically increasing or decreasing (note decreasing + levels fail with ``contour`` plots). +values : int or sequence of float, default: None + The number of level centers or a sequence of level centers. If the former, + `locator` is used to generate this many level centers at "nice" intervals. + If the latter, levels are inferred using `~ultraplot.utils.edges`. + This will override any `levels` input. +center_levels : bool, default False + If set to true, the discrete color bar bins will be centered on the level values + instead of using the level values as the edges of the discrete bins. This option + can be used for diverging, discrete color bars with both positive and negative + data to ensure data near zero is properly represented. +robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` + If ``True`` and `vmin` or `vmax` were not provided, they are + determined from the 2nd and 98th data percentiles rather than the + minimum and maximum. If float, this percentile range is used (for example, + ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, + these specific percentiles should be used. This feature is useful + when your data has large outliers. +inbounds : bool, default: :rc:`cmap.inbounds` + If ``True`` and `vmin` or `vmax` were not provided, when axis limits + have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` + or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. + See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. +locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + The locator used to determine level locations if `levels` or `values` were not + already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. + Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. +locator_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Locator` class. +symmetric : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + symmetric about zero. +positive : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + positive with a minimum at zero. +negative : bool, default: False + If ``True``, the normaliation range or discrete colormap levels are + negative with a minimum at zero. +nozero : bool, default: False + If ``True``, ``0`` is removed from the level list. This is mainly useful for + single-color `~matplotlib.axes.Axes.contour` plots. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `matplotlib.axes.Axes.imshow`. + +See also +-------- +ultraplot.axes.PlotAxes +matplotlib.axes.Axes.imshow""" + ... + + def matshow(self, z: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot a matrix. + +Parameters +---------- +z : array-like + The data passed as a positional argument or keyword argument. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` + The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor + function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization + range contains negative and positive values then :rcraw:`cmap.diverging` is used. + Otherwise :rcraw:`cmap.sequential` is used. +cmap_kw : dict-like, optional + Passed to :class:`~ultraplot.constructor.Colormap`. +c, color, colors : color-spec or sequence of color-spec, optional + The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + If not passed, `cmap` is used. +norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` + The data value normalizer, passed to the `~ultraplot.constructor.Norm` + constructor function. If `discrete` is ``True`` then 1) this affects the default + level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and + 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they + are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). + If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains + negative and positive values then `~ultraplot.colors.DivergingNorm` is used. + Otherwise `~matplotlib.colors.Normalize` is used. +norm_kw : dict-like, optional + Passed to `~ultraplot.constructor.Norm`. +extend : {'neither', 'both', 'min', 'max'}, default: 'neither' + Direction for drawing colorbar "extensions" indicating + out-of-bounds data on the end of the colorbar. +discrete : bool, default: :rc:`cmap.discrete` + If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the + colormap. Instead, for non-contour plots, the number of levels will be + roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + using `levels=large_number` but it may improve rendering speed. Default is + ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` + and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. +sequential, diverging, cyclic, qualitative : bool, default: None + Boolean arguments used if `cmap` is not passed. Set these to ``True`` + to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, + :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. + The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + as the default continuous normalizer. +vmin, vmax : float, optional + The minimum and maximum color scale values used with the `norm` normalizer. + If `discrete` is ``False`` these are the absolute limits, and if `discrete` + is ``True`` these are the approximate limits used to automatically determine + `levels` or `values` lists at "nice" intervals. If `levels` or `values` were + already passed as lists, these are ignored, and `vmin` and `vmax` are set to + the minimum and maximum of the lists. If `robust` was passed, the default `vmin` + and `vmax` are some percentile range of the data values. Otherwise, the default + `vmin` and `vmax` are the minimum and maximum of the data values. +N + Shorthand for `levels`. +levels : int or sequence of float, default: :rc:`cmap.levels` + The number of level edges or a sequence of level edges. If the former, `locator` + is used to generate this many level edges at "nice" intervals. If the latter, + the levels should be monotonically increasing or decreasing (note decreasing + levels fail with ``contour`` plots). +values : int or sequence of float, default: None + The number of level centers or a sequence of level centers. If the former, + `locator` is used to generate this many level centers at "nice" intervals. + If the latter, levels are inferred using `~ultraplot.utils.edges`. + This will override any `levels` input. +center_levels : bool, default False + If set to true, the discrete color bar bins will be centered on the level values + instead of using the level values as the edges of the discrete bins. This option + can be used for diverging, discrete color bars with both positive and negative + data to ensure data near zero is properly represented. +robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` + If ``True`` and `vmin` or `vmax` were not provided, they are + determined from the 2nd and 98th data percentiles rather than the + minimum and maximum. If float, this percentile range is used (for example, + ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, + these specific percentiles should be used. This feature is useful + when your data has large outliers. +inbounds : bool, default: :rc:`cmap.inbounds` + If ``True`` and `vmin` or `vmax` were not provided, when axis limits + have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` + or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. + See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. +locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + The locator used to determine level locations if `levels` or `values` were not + already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. + Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. +locator_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Locator` class. +symmetric : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + symmetric about zero. +positive : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + positive with a minimum at zero. +negative : bool, default: False + If ``True``, the normaliation range or discrete colormap levels are + negative with a minimum at zero. +nozero : bool, default: False + If ``True``, ``0`` is removed from the level list. This is mainly useful for + single-color `~matplotlib.axes.Axes.contour` plots. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `matplotlib.axes.Axes.matshow`. + +See also +-------- +ultraplot.axes.PlotAxes +matplotlib.axes.Axes.matshow""" + ... + + def spy(self, z: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot a sparcity pattern. + +Parameters +---------- +z : array-like + The data passed as a positional argument or keyword argument. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` + The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor + function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization + range contains negative and positive values then :rcraw:`cmap.diverging` is used. + Otherwise :rcraw:`cmap.sequential` is used. +cmap_kw : dict-like, optional + Passed to :class:`~ultraplot.constructor.Colormap`. +c, color, colors : color-spec or sequence of color-spec, optional + The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + If not passed, `cmap` is used. +norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` + The data value normalizer, passed to the `~ultraplot.constructor.Norm` + constructor function. If `discrete` is ``True`` then 1) this affects the default + level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and + 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they + are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). + If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains + negative and positive values then `~ultraplot.colors.DivergingNorm` is used. + Otherwise `~matplotlib.colors.Normalize` is used. +norm_kw : dict-like, optional + Passed to `~ultraplot.constructor.Norm`. +extend : {'neither', 'both', 'min', 'max'}, default: 'neither' + Direction for drawing colorbar "extensions" indicating + out-of-bounds data on the end of the colorbar. +discrete : bool, default: :rc:`cmap.discrete` + If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the + colormap. Instead, for non-contour plots, the number of levels will be + roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + using `levels=large_number` but it may improve rendering speed. Default is + ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` + and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. +sequential, diverging, cyclic, qualitative : bool, default: None + Boolean arguments used if `cmap` is not passed. Set these to ``True`` + to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, + :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. + The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + as the default continuous normalizer. +vmin, vmax : float, optional + The minimum and maximum color scale values used with the `norm` normalizer. + If `discrete` is ``False`` these are the absolute limits, and if `discrete` + is ``True`` these are the approximate limits used to automatically determine + `levels` or `values` lists at "nice" intervals. If `levels` or `values` were + already passed as lists, these are ignored, and `vmin` and `vmax` are set to + the minimum and maximum of the lists. If `robust` was passed, the default `vmin` + and `vmax` are some percentile range of the data values. Otherwise, the default + `vmin` and `vmax` are the minimum and maximum of the data values. +N + Shorthand for `levels`. +levels : int or sequence of float, default: :rc:`cmap.levels` + The number of level edges or a sequence of level edges. If the former, `locator` + is used to generate this many level edges at "nice" intervals. If the latter, + the levels should be monotonically increasing or decreasing (note decreasing + levels fail with ``contour`` plots). +values : int or sequence of float, default: None + The number of level centers or a sequence of level centers. If the former, + `locator` is used to generate this many level centers at "nice" intervals. + If the latter, levels are inferred using `~ultraplot.utils.edges`. + This will override any `levels` input. +center_levels : bool, default False + If set to true, the discrete color bar bins will be centered on the level values + instead of using the level values as the edges of the discrete bins. This option + can be used for diverging, discrete color bars with both positive and negative + data to ensure data near zero is properly represented. +robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` + If ``True`` and `vmin` or `vmax` were not provided, they are + determined from the 2nd and 98th data percentiles rather than the + minimum and maximum. If float, this percentile range is used (for example, + ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, + these specific percentiles should be used. This feature is useful + when your data has large outliers. +inbounds : bool, default: :rc:`cmap.inbounds` + If ``True`` and `vmin` or `vmax` were not provided, when axis limits + have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` + or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. + See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. +locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + The locator used to determine level locations if `levels` or `values` were not + already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. + Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. +locator_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Locator` class. +symmetric : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + symmetric about zero. +positive : bool, default: False + If ``True``, the normalization range or discrete colormap levels are + positive with a minimum at zero. +negative : bool, default: False + If ``True``, the normaliation range or discrete colormap levels are + negative with a minimum at zero. +nozero : bool, default: False + If ``True``, ``0`` is removed from the level list. This is mainly useful for + single-color `~matplotlib.axes.Axes.contour` plots. +colorbar : bool, int, or str, optional + If not ``None``, this is a location specifying where to draw an + *inset* or *outer* colorbar from the resulting object(s). If ``True``, + the default :rc:`colorbar.loc` is used. If the same location is + used in successive plotting calls, object(s) will be added to the + existing colorbar in that location (valid for colorbars built from lists + of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. +colorbar_kw : dict-like, optional + Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. +legend : bool, int, or str, optional + Location specifying where to draw an *inset* or *outer* legend from the + resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + If the same location is used in successive plotting calls, object(s) + will be added to existing legend in that location. Valid locations + are shown in :meth:`~ultraplot.axes.Axes.legend`. +legend_kw : dict-like, optional + Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. +**kwargs + Passed to `matplotlib.axes.Axes.spy`. + +See also +-------- +ultraplot.axes.PlotAxes +matplotlib.axes.Axes.spy""" + ... + + def _iter_arg_pairs(self, *args: Incomplete) -> Incomplete: + """Iterate over ``[x1,] y1, [fmt1,] [x2,] y2, [fmt2,] ...`` input.""" + ... + + def _iter_arg_cols(self, *args: Incomplete, label: Incomplete=None, labels: Incomplete=None, values: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Iterate over columns of positional arguments.""" + ... + _level_parsers = (_parse_level_vals, _parse_level_num, _parse_level_lim) diff --git a/ultraplot/axes/plot_types/__init__.pyi b/ultraplot/axes/plot_types/__init__.pyi new file mode 100644 index 000000000..9d22fbe63 --- /dev/null +++ b/ultraplot/axes/plot_types/__init__.pyi @@ -0,0 +1,3 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +from _typeshed import Incomplete diff --git a/ultraplot/axes/plot_types/circlize.pyi b/ultraplot/axes/plot_types/circlize.pyi new file mode 100644 index 000000000..847567905 --- /dev/null +++ b/ultraplot/axes/plot_types/circlize.pyi @@ -0,0 +1,51 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Helpers for pyCirclize-backed circular plots. +""" +from _typeshed import Incomplete +import itertools +import sys +from pathlib import Path +from typing import Any, Callable, Mapping, Optional, Sequence, Union +from matplotlib.projections.polar import PolarAxes as MplPolarAxes +from ... import constructor +from ...config import rc + +def _import_pycirclize() -> Incomplete: + ... + +def _unwrap_axes(ax: Incomplete, label: str) -> Incomplete: + ... + +def _ensure_polar(ax: Incomplete, label: str) -> Incomplete: + ... + +def _cycle_colors(n: int) -> list[str]: + ... + +def _resolve_chord_defaults(matrix: Any, cmap: Any) -> Incomplete: + ... + +def _resolve_radar_defaults(table: Any, cmap: Any) -> Incomplete: + ... + +def circos(ax: Incomplete, sectors: Mapping[str, Any], *, start: float=0, end: float=360, space: float | Sequence[float]=0, endspace: bool=True, sector2clockwise: Mapping[str, bool] | None=None, show_axis_for_debug: bool=False, plot: bool=False, tooltip: bool=False) -> Incomplete: + """Create a pyCirclize Circos instance (optionally plot immediately).""" + ... + +def chord_diagram(ax: Incomplete, matrix: Any, *, start: Optional[float]=None, end: Optional[float]=None, space: Optional[Union[float, Sequence[float]]]=None, endspace: Optional[bool]=None, r_lim: Optional[tuple[float, float]]=None, cmap: Any=None, link_cmap: Optional[list[tuple[str, str, str]]]=None, ticks_interval: Optional[int]=None, order: Optional[Union[str, list[str]]]=None, label_kw: Optional[Mapping[str, Any]]=None, ticks_kw: Optional[Mapping[str, Any]]=None, link_kw: Optional[Mapping[str, Any]]=None, link_kw_handler: Incomplete=None, tooltip: bool=False) -> Incomplete: + """Render a chord diagram using pyCirclize on the provided polar axes.""" + ... + +def radar_chart(ax: Incomplete, table: Any, *, r_lim: Optional[tuple[float, float]]=None, vmin: Optional[float]=None, vmax: Optional[float]=None, fill: Optional[bool]=None, marker_size: Optional[int]=None, bg_color: Optional[str]=None, circular: Optional[bool]=None, cmap: Any=None, show_grid_label: Optional[bool]=None, grid_interval_ratio: Optional[float]=None, grid_line_kw: Optional[Mapping[str, Any]]=None, grid_label_kw: Optional[Mapping[str, Any]]=None, grid_label_formatter: Incomplete=None, label_kw_handler: Incomplete=None, line_kw_handler: Incomplete=None, marker_kw_handler: Incomplete=None) -> Incomplete: + """Render a radar chart using pyCirclize on the provided polar axes.""" + ... + +def phylogeny(ax: Incomplete, tree_data: Any, *, start: Optional[float]=None, end: Optional[float]=None, r_lim: Optional[tuple[float, float]]=None, format: Optional[str]=None, outer: Optional[bool]=None, align_leaf_label: Optional[bool]=None, ignore_branch_length: Optional[bool]=None, leaf_label_size: Optional[float]=None, leaf_label_rmargin: Optional[float]=None, reverse: Optional[bool]=None, ladderize: Optional[bool]=None, line_kw: Optional[Mapping[str, Any]]=None, label_formatter: Incomplete=None, align_line_kw: Optional[Mapping[str, Any]]=None, tooltip: bool=False) -> Incomplete: + """Render a phylogenetic tree using pyCirclize on the provided polar axes.""" + ... + +def circos_bed(ax: Incomplete, bed_file: Any, *, start: float=0, end: float=360, space: float | Sequence[float]=0, endspace: bool=True, sector2clockwise: Mapping[str, bool] | None=None, plot: bool=False, tooltip: bool=False) -> Incomplete: + """Create a Circos instance from a BED file (optionally plot immediately).""" + ... diff --git a/ultraplot/axes/plot_types/curved_quiver.pyi b/ultraplot/axes/plot_types/curved_quiver.pyi new file mode 100644 index 000000000..a9da2ba94 --- /dev/null +++ b/ultraplot/axes/plot_types/curved_quiver.pyi @@ -0,0 +1,158 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +from _typeshed import Incomplete +__all__ = ['CurvedQuiverSolver', 'CurvedQuiverSet'] +from typing import Callable +from dataclasses import dataclass +from matplotlib.streamplot import StreamplotSet +import numpy as np + +@dataclass +class CurvedQuiverSet(StreamplotSet): + lines: object + arrows: object + +@dataclass +class _CurvedQuiverTrajectory: + x: list[float] + y: list[float] + hit_edge: bool + end_direction: tuple[float, float] | None + +class _DomainMap(object): + """Map representing different coordinate systems. + + Coordinate definitions: + * axes-coordinates goes from 0 to 1 in the domain. + * data-coordinates are specified by the input x-y coordinates. + * grid-coordinates goes from 0 to N and 0 to M for an N x M grid, + where N and M match the shape of the input data. + * mask-coordinates goes from 0 to N and 0 to M for an N x M mask, + where N and M are user-specified to control the density of + streamlines. + + This class also has methods for adding trajectories to the + StreamMask. Before adding a trajectory, run `start_trajectory` to + keep track of regions crossed by a given trajectory. Later, if you + decide the trajectory is bad (e.g., if the trajectory is very + short) just call `undo_trajectory`. + """ + + def __init__(self, grid: Incomplete, mask: Incomplete) -> None: + ... + + def grid2mask(self, xi: float, yi: float) -> tuple[int, int]: + """Return nearest space in mask-coords from given grid-coords.""" + ... + + def mask2grid(self, xm: int, ym: int) -> tuple[float, float]: + ... + + def data2grid(self, xd: float, yd: float) -> tuple[float, float]: + ... + + def grid2data(self, xg: float, yg: float) -> tuple[float, float]: + ... + + def start_trajectory(self, xg: float, yg: float) -> None: + ... + + def reset_start_point(self, xg: float, yg: float) -> None: + ... + + def update_trajectory(self, xg: float, yg: float) -> None: + ... + + def undo_trajectory(self) -> None: + ... + +class _CurvedQuiverGrid(object): + """Grid of data.""" + + def __init__(self, x: np.ndarray, y: np.ndarray) -> None: + ... + + @property + def shape(self) -> tuple[int, int]: + ... + + def within_grid(self, xi: float, yi: float) -> bool: + """Return True if point is a valid index of grid.""" + ... + +class _StreamMask(object): + """Mask to keep track of discrete regions crossed by streamlines. + + The resolution of this grid determines the approximate spacing + between trajectories. Streamlines are only allowed to pass through + zeroed cells: When a streamline enters a cell, that cell is set to + 1, and no new streamlines are allowed to enter. + """ + + def __init__(self, density: float | int) -> None: + ... + + def __getitem__(self, *args: Incomplete) -> Incomplete: + ... + + def _start_trajectory(self, xm: int, ym: int) -> Incomplete: + """Start recording streamline trajectory""" + ... + + def _undo_trajectory(self) -> Incomplete: + """Remove current trajectory from mask""" + ... + + def _update_trajectory(self, xm: int, ym: int) -> None: + """Update current trajectory position in mask. + +If the new position has already been filled, raise +`InvalidIndexError`.""" + ... + +class _CurvedQuiverTerminateTrajectory(Exception): + pass + +class CurvedQuiverSolver: + + def __init__(self, x: np.ndarray, y: np.ndarray, density: float | tuple[float, float]) -> None: + ... + + def get_integrator(self, u: np.ndarray, v: np.ndarray, minlength: float, resolution: float, magnitude: np.ndarray) -> Callable[[float, float], _CurvedQuiverTrajectory | None]: + ... + + def integrate_rk12(self, x0: float, y0: float, f: Callable[[float, float], tuple[float, float]], resolution: float, magnitude: np.ndarray) -> tuple[list[float], list[float], bool]: + """2nd-order Runge-Kutta algorithm with adaptive step size. + +This method is also referred to as the improved Euler's method, or +Heun's method. This method is favored over higher-order methods +because: + +1. To get decent looking trajectories and to sample every mask cell +on the trajectory we need a small timestep, so a lower order +solver doesn't hurt us unless the data is *very* high +resolution. In fact, for cases where the user inputs data +smaller or of similar grid size to the mask grid, the higher +order corrections are negligible because of the very fast linear +interpolation used in `interpgrid`. + +2. For high resolution input data (i.e. beyond the mask +resolution), we must reduce the timestep. Therefore, an +adaptive timestep is more suited to the problem as this would be +very hard to judge automatically otherwise. + +This integrator is about 1.5 - 2x as fast as both the RK4 and RK45 +solvers in most setups on my machine. I would recommend removing +the other two to keep things simple.""" + ... + + def euler_step(self, xf_traj: Incomplete, yf_traj: Incomplete, f: Incomplete) -> Incomplete: + """Simple Euler integration step that extends streamline to boundary.""" + ... + + def interpgrid(self, a: Incomplete, xi: Incomplete, yi: Incomplete) -> Incomplete: + """Fast 2D, linear interpolation on an integer grid""" + ... + + def gen_starting_points(self, x: Incomplete, y: Incomplete, grains: Incomplete) -> Incomplete: + ... diff --git a/ultraplot/axes/plot_types/ribbon.pyi b/ultraplot/axes/plot_types/ribbon.pyi new file mode 100644 index 000000000..0dbd7e3a7 --- /dev/null +++ b/ultraplot/axes/plot_types/ribbon.pyi @@ -0,0 +1,20 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Top-aligned ribbon flow diagram helper. +""" +from _typeshed import Incomplete +from collections import Counter, defaultdict +from collections.abc import Mapping, Sequence +from typing import Any +import numpy as np +import pandas as pd +from matplotlib import patches as mpatches +from matplotlib import path as mpath + +def _ribbon_path(x0: float, y0: float, x1: float, y1: float, thickness: float, curvature: float) -> mpath.Path: + ... + +def ribbon_diagram(ax: Any, data: Any, *, id_col: str, period_col: str, topic_col: str, value_col: str | None=None, period_order: Sequence[Any] | None=None, topic_order: Sequence[Any] | None=None, group_map: Mapping[Any, Any] | None=None, group_order: Sequence[Any] | None=None, group_colors: Mapping[Any, Any] | None=None, xmargin: float, ymargin: float, row_height_ratio: float, node_width: float, flow_curvature: float, flow_alpha: float, show_topic_labels: bool, topic_label_offset: float, topic_label_size: float, topic_label_box: bool) -> dict[str, Any]: + """Build a fixed-row, top-aligned ribbon flow diagram from long-form assignments.""" + ... diff --git a/ultraplot/axes/plot_types/sankey.pyi b/ultraplot/axes/plot_types/sankey.pyi new file mode 100644 index 000000000..232764d7f --- /dev/null +++ b/ultraplot/axes/plot_types/sankey.pyi @@ -0,0 +1,105 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +from _typeshed import Incomplete +from dataclasses import dataclass +from typing import Any, Callable, Mapping, Optional, Sequence, Union +from matplotlib import colors as mcolors +from matplotlib import patches as mpatches +from matplotlib import path as mpath +from ...config import rc +from ...internals import _not_none + +@dataclass +class SankeyDiagram: + nodes: dict[Any, mpatches.Patch] + flows: list[mpatches.PathPatch] + labels: dict[Any, Any] + layout: dict[str, Any] + +def _tint(color: Any, amount: float) -> tuple[float, float, float]: + """Return a lightened version of a base color.""" + ... + +def _normalize_nodes(nodes: Any, flows: Sequence[Mapping[str, Any]]) -> tuple[dict[Any, dict[str, Any]], list[Any]]: + """Normalize node definitions into a map and stable order list.""" + ... + +def _normalize_flows(flows: Any) -> list[dict[str, Any]]: + """Normalize flow definitions into a list of dicts.""" + ... + +def _assign_layers(flows: Sequence[Mapping[str, Any]], nodes: Sequence[Any], layers: Mapping[Any, int] | None) -> dict[Any, int]: + """Assign layer indices for nodes using a DAG topological pass.""" + ... + +def _compute_layout(nodes: Sequence[Any], flows: Sequence[Mapping[str, Any]], *, node_pad: float, node_width: float, align: str, layers: Mapping[Any, int] | None, margin: float, layer_order: Sequence[int] | None=None) -> tuple[dict[str, Any], dict[Any, list[dict[str, Any]]], dict[Any, list[dict[str, Any]]], dict[Any, float]]: + """Compute node and flow layout geometry in axes-relative coordinates.""" + ... + +def _ribbon_path(x0: float, y0: float, x1: float, y1: float, thickness: float, curvature: float) -> mpath.Path: + """Build a closed Bezier path for a ribbon segment.""" + ... + +def _bezier_point(p0: float, p1: float, p2: float, p3: float, t: float) -> float: + """Evaluate a cubic Bezier coordinate at t in [0, 1].""" + ... + +def _flow_label_point(x0: float, y0: float, x1: float, y1: float, thickness: float, curvature: float, frac: float) -> tuple[float, float]: + """Return a point along the flow centerline for label placement.""" + ... + +def _apply_style(style: str | None, *, flow_cycle: Sequence[Any] | None, node_facecolor: Any, flow_alpha: float, flow_curvature: float, node_label_box: bool | Mapping[str, Any] | None, node_label_kw: Mapping[str, Any]) -> dict[str, Any]: + """Apply a named style preset and merge overrides.""" + ... + +def _apply_flow_other(flows: list[dict[str, Any]], flow_other: float | None, other_label: str) -> list[dict[str, Any]]: + """Aggregate small flows into a single 'Other' target per source.""" + ... + +def _ensure_nodes(nodes: Any, flows: Sequence[Mapping[str, Any]], node_order: Sequence[Any] | None) -> tuple[dict[Any, dict[str, Any]], list[Any]]: + """Ensure all flow endpoints exist in nodes and validate ordering.""" + ... + +def _assign_flow_colors(flows: Sequence[Mapping[str, Any]], flow_cycle: Sequence[Any] | None, group_cycle: Sequence[Any] | None) -> dict[Any, Any]: + """Assign colors to flows by group or source.""" + ... + +def _sort_flows(flows: Sequence[Mapping[str, Any]], node_order: Sequence[Any], layout: Mapping[str, Any]) -> list[dict[str, Any]]: + """Sort flows by target position to reduce crossings.""" + ... + +def _flow_label_text(flow: Mapping[str, Any], value_format: str | Callable[[float], str] | None) -> str: + """Resolve the text for a flow label.""" + ... + +def _flow_label_frac(idx: int, count: int, base: float) -> float: + """Return alternating label positions around the midpoint.""" + ... + +def _prepare_inputs(*, nodes: Any, flows: Any, flow_other: float | None, other_label: str, node_order: Sequence[Any] | None, style: str | None, flow_cycle: Sequence[Any] | None, node_facecolor: Any, flow_alpha: float, flow_curvature: float, node_label_box: bool | Mapping[str, Any] | None, node_label_kw: Mapping[str, Any], group_cycle: Sequence[Any] | None) -> tuple[list[dict[str, Any]], dict[Any, dict[str, Any]], list[Any], dict[str, Any], dict[Any, Any]]: + """Normalize inputs, apply style, and assign colors.""" + ... + +def _validate_layer_order(layer_order: Sequence[int] | None, flows: Sequence[Mapping[str, Any]], node_order: Sequence[Any], layers: Mapping[Any, int] | None) -> None: + """Validate that layer_order is consistent with computed layers.""" + ... + +def _layer_positions(layout: Mapping[str, Any], layer_order: Sequence[int] | None) -> tuple[dict[Any, int], dict[int, int]]: + """Return layer maps and positions for label placement.""" + ... + +def _label_box(node_label_box: bool | Mapping[str, Any] | None) -> dict[str, Any] | None: + """Return a bbox dict for node labels, if requested.""" + ... + +def _draw_flows(ax: Incomplete, *, flows: Sequence[Mapping[str, Any]], node_order: Sequence[Any], layout: Mapping[str, Any], flow_color_map: Mapping[Any, Any], flow_kw: Mapping[str, Any], label_kw: Mapping[str, Any], flow_label_kw: Mapping[str, Any], flow_labels: bool, value_format: str | Callable[[float], str] | None, flow_label_pos: float, flow_alpha: float, flow_curvature: float) -> tuple[list[mpatches.PathPatch], dict[Any, Any]]: + """Draw flow ribbons and optional labels.""" + ... + +def _draw_nodes(ax: Incomplete, *, node_order: Sequence[Any], node_map: Mapping[Any, Mapping[str, Any]], layout: Mapping[str, Any], layer_map: Mapping[Any, int], layer_position: Mapping[int, int], node_facecolor: Any, node_kw: Mapping[str, Any], label_kw: Mapping[str, Any], node_label_kw: Mapping[str, Any], node_label_box: bool | Mapping[str, Any] | None, node_labels: bool, node_label_outside: bool | str, node_label_offset: float) -> tuple[dict[Any, mpatches.Patch], dict[Any, Any]]: + """Draw node rectangles and optional labels.""" + ... + +def sankey_diagram(ax: Incomplete, *, nodes: Any=None, flows: Any=None, layers: Optional[Mapping[Any, int]]=None, flow_cycle: Optional[Sequence[Any]]=None, group_cycle: Optional[Sequence[Any]]=None, node_order: Optional[Sequence[Any]]=None, layer_order: Optional[Sequence[int]]=None, style: Optional[str]=None, flow_other: Optional[float]=None, other_label: Optional[str]=None, value_format: Optional[Union[str, Callable[[float], str]]]=None, node_pad: Optional[float]=None, node_width: Optional[float]=None, node_kw: Optional[Mapping[str, Any]]=None, flow_kw: Optional[Mapping[str, Any]]=None, label_kw: Optional[Mapping[str, Any]]=None, node_label_kw: Optional[Mapping[str, Any]]=None, flow_label_kw: Optional[Mapping[str, Any]]=None, node_label_box: Optional[Union[bool, Mapping[str, Any]]]=None, node_labels: Optional[bool]=None, flow_labels: Optional[bool]=None, flow_sort: Optional[bool]=None, flow_label_pos: Optional[float]=None, node_label_outside: Optional[Union[bool, str]]=None, node_label_offset: Optional[float]=None, align: Optional[str]=None, margin: Optional[float]=None, flow_alpha: Optional[float]=None, flow_curvature: Optional[float]=None, node_facecolor: Optional[Any]=None) -> SankeyDiagram: + """Render a layered Sankey diagram with optional labels.""" + ... diff --git a/ultraplot/axes/polar.pyi b/ultraplot/axes/polar.pyi new file mode 100644 index 000000000..d1ea27b18 --- /dev/null +++ b/ultraplot/axes/polar.pyi @@ -0,0 +1,541 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Polar axes using azimuth and radius instead of *x* and *y*. +""" +from _typeshed import Incomplete +import inspect +try: + from typing import override +except: + from typing_extensions import override +import matplotlib.projections.polar as mpolar +import matplotlib.transforms as mtransforms +import numpy as np +from matplotlib.font_manager import FontProperties +from .. import constructor +from .. import ticker as pticker +from ..config import rc +from ..internals import _not_none, _pop_rc, docstring, ic +from . import plot, shared +__all__ = ['PolarAxes'] +_POLAR_LABEL_NPOINTS = 50 +_POLAR_LABEL_FULL_HALFSPAN_DEG = 15.0 +_POLAR_LABEL_SECTOR_FRAC = 0.8 +_format_docstring = ... + +class PolarAxes(shared._SharedAxes, plot.PlotAxes, mpolar.PolarAxes): + """ + Axes subclass for plotting in polar coordinates. Adds the `~PolarAxes.format` + method and overrides several existing methods. + + Important + --------- + This axes subclass can be used by passing ``proj='polar'`` + to axes-creation commands like `~ultraplot.figure.Figure.add_axes`, + `~ultraplot.figure.Figure.add_subplot`, and `~ultraplot.figure.Figure.subplots`. + """ + _name = 'polar' + + def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: + """Parameters +---------- +*args + Passed to `matplotlib.axes.Axes`. +r0 : float, default: 0 + The radial origin. +theta0 : {'N', 'NW', 'W', 'SW', 'S', 'SE', 'E', 'NE'}, optional + The zero azimuth location. +thetadir : {1, -1, 'anticlockwise', 'counterclockwise', 'clockwise'}, optional + The positive azimuth direction. Clockwise corresponds to + ``-1`` and anticlockwise corresponds to ``1``. +thetamin, thetamax : float, optional + The lower and upper azimuthal bounds in degrees. If + ``thetamax != thetamin + 360``, this produces a sector plot. +thetalim : 2-tuple of float or None, optional + Specifies `thetamin` and `thetamax` at once. +rmin, rmax : float, optional + The inner and outer radial limits. If ``r0 != rmin``, this + produces an annular plot. +rlim : 2-tuple of float or None, optional + Specifies `rmin` and `rmax` at once. +rborder : bool, optional + Whether to draw the polar axes border. Visibility of the "inner" + radial spine and "start" and "end" azimuthal spines is controlled + automatically by matplotlib. +thetagrid, rgrid, grid : bool, optional + Whether to draw major gridlines for the azimuthal and radial axis. + Use the keyword `grid` to toggle both. +thetagridminor, rgridminor, gridminor : bool, optional + Whether to draw minor gridlines for the azimuthal and radial axis. + Use the keyword `gridminor` to toggle both. +thetagridcolor, rgridcolor, gridcolor : color-spec, optional + Color for the major and minor azimuthal and radial gridlines. + Use the keyword `gridcolor` to set both at once. +thetalocator, rlocator : locator-spec, optional + Used to determine the azimuthal and radial gridline positions. + Passed to the `~ultraplot.constructor.Locator` constructor. Can be + float, list of float, string, or `matplotlib.ticker.Locator` instance. +thetalines, rlines + Aliases for `thetalocator`, `rlocator`. +thetalocator_kw, rlocator_kw : dict-like, optional + The azimuthal and radial locator settings. Passed to + `~ultraplot.constructor.Locator`. +thetaminorlocator, rminorlocator : optional + As for `thetalocator`, `rlocator`, but for the minor gridlines. +thetaminorticks, rminorticks : optional + Aliases for `thetaminorlocator`, `rminorlocator`. +thetaminorlocator_kw, rminorlocator_kw + As for `thetalocator_kw`, `rlocator_kw`, but for the minor locator. +rlabelpos : float, optional + The azimuth at which radial coordinates are labeled. Also used as the + spoke angle for ``rlabel`` when you want an explicit radial-label + position. +thetaformatter, rformatter : formatter-spec, optional + Used to determine the azimuthal and radial label format. + Passed to the `~ultraplot.constructor.Formatter` constructor. + Can be string, list of string, or `matplotlib.ticker.Formatter` + instance. Use ``[]``, ``'null'``, or ``'none'`` for no labels. +thetalabels, rlabels : optional + Aliases for `thetaformatter`, `rformatter`. +thetaformatter_kw, rformatter_kw : dict-like, optional + The azimuthal and radial label formatter settings. Passed to + `~ultraplot.constructor.Formatter`. +thetalabel, rlabel : str, optional + Polar-aware axis labels rendered via `~ultraplot.text.CurvedText`. + ``thetalabel`` follows the outer arc just beyond ``r=rmax``. + ``rlabel`` follows a radial spoke, centered between ``rmin`` and + ``rmax``. On a full circle it uses ``get_rlabel_position()`` unless + ``rlabelpos`` is explicit; on a sector it uses the spoke selected by + ``rlabelloc`` unless ``rlabelpos`` is explicit. Both labels include a + built-in tick-clearance offset, and ``labelpad`` adds extra padding in + points on top of that offset. Pass ``""`` to clear a previously set + label. +thetalabelloc : float, optional + Center theta angle (in degrees) for ``thetalabel``. Defaults to the + midpoint of the directed ``thetalim`` interval (or ``0`` for a full + circle). +rlabelloc : {'right', 'left'}, default: 'right' + Where to place ``rlabel``. When the spoke angle is fixed by a full + circle or by explicit ``rlabelpos``, ``rlabelloc`` selects the + perpendicular side of that spoke and ``'left'`` flips the default + side. On a sector with no explicit ``rlabelpos``, ``'right'`` + (default) anchors to ``thetamin`` and ``'left'`` anchors to + ``thetamax``; the label is then offset outward from the sector. +thetalabel_kw, rlabel_kw : dict-like, optional + Additional `~ultraplot.text.CurvedText` settings for the polar-aware + labels (e.g. ``border``, ``bbox``, or rendering hints like + ``min_advance``). See also `labelpad`, `labelcolor`, `labelsize`, + and `labelweight`. +color : color-spec, default: :rc:`meta.color` + Color for the axes edge. Propagates to `labelcolor` unless specified + otherwise (similar to :func:`~ultraplot.axes.CartesianAxes.format`). +labelcolor, gridlabelcolor : color-spec, default: `color` or :rc:`grid.labelcolor` + Color for the gridline labels. +labelpad, gridlabelpad : unit-spec, default: :rc:`grid.labelpad` + The padding between the axes edge and the radial and azimuthal labels. + For ``thetalabel`` and ``rlabel``, this is added on top of the built-in + tick-clearance offset. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +labelsize, gridlabelsize : unit-spec or str, default: :rc:`grid.labelsize` + Font size for the gridline labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +labelweight, gridlabelweight : str, default: :rc:`grid.labelweight` + Font weight for the gridline labels. + +Other parameters +---------------- +title : str or sequence, optional + The axes title. Can optionally be a sequence strings, in which case + the title will be selected from the sequence according to `~Axes.number`. +abc : bool or str or sequence, default: :rc:`abc` + The "a-b-c" subplot label style. Must contain the character `a` or `A`, + for example ``'a.'``, or ``'A'``. If ``True`` then the default style of + ``'a'`` is used. The `a` or ``A`` is replaced with the alphabetic character + matching the `~Axes.number`. If `~Axes.number` is greater than 26, the + characters loop around to a, ..., z, aa, ..., zz, aaa, ..., zzz, etc. + Can also be a sequence of strings, in which case the "a-b-c" label will be selected sequentially from the list. For example `axs.format(abc = ["X", "Y"])` for a two-panel figure, and `axes[3:5].format(abc = ["X", "Y"])` for a two-panel subset of a larger figure. +abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` + Strings indicating the location for the a-b-c label and main title. + The following locations are valid: + + .. _title_table: + + ======================== ============================ + Location Valid keys + ======================== ============================ + center above axes ``'center'``, ``'c'`` + left above axes ``'left'``, ``'l'`` + right above axes ``'right'``, ``'r'`` + lower center inside axes ``'lower center'``, ``'lc'`` + upper center inside axes ``'upper center'``, ``'uc'`` + upper right inside axes ``'upper right'``, ``'ur'`` + upper left inside axes ``'upper left'``, ``'ul'`` + lower left inside axes ``'lower left'``, ``'ll'`` + lower right inside axes ``'lower right'``, ``'lr'`` + left of y axis ``'outer left'``, ``'ol'`` + right of y axis ``'outer right'``, ``'or'`` + ======================== ============================ + +abcborder, titleborder : bool, default: :rc:`abc.border` and :rc:`title.border` + Whether to draw a white border around titles and a-b-c labels positioned + inside the axes. This can help them stand out on top of artists + plotted inside the axes. +abcbbox, titlebbox : bool, default: :rc:`abc.bbox` and :rc:`title.bbox` + Whether to draw a white bbox around titles and a-b-c labels positioned + inside the axes. This can help them stand out on top of artists plotted + inside the axes. +abcpad : float or unit-spec, default: :rc:`abc.pad` + Horizontal offset to shift the a-b-c label position. Positive values move + the label right, negative values move it left. This is separate from + `abctitlepad`, which controls spacing between abc and title when co-located. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +abc_kw, title_kw : dict-like, optional + Additional settings used to update the a-b-c label and title + with ``text.update()``. +titlepad : float, default: :rc:`title.pad` + The padding for the inner and outer titles and a-b-c labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +titleabove : bool, default: :rc:`title.above` + Whether to try to put outer titles and a-b-c labels above panels, + colorbars, or legends that are above the axes. +abctitlepad : float, default: :rc:`abc.titlepad` + The horizontal padding between a-b-c labels and titles in the same location. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle : str or sequence, optional + Shorthands for the below keywords. + lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle : str or sequence, optional +lowerlefttitle, lowercentertitle, lowerrighttitle : str or sequence, optional + Additional titles in specific positions (see `title` for details). This works as + an alternative to the ``ax.format(title='Title', titleloc=loc)`` workflow and + permits adding more than one title-like label for a single axes. +a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle : default: + :rc:`axes.alpha` (default: 1.0), :rc:`axes.facecolor` (default: white), :rc:`axes.edgecolor` (default: black), :rc:`axes.linewidth` (default: 0.6), - + Additional settings applied to the background patch, and their + shorthands. Their defaults values are the ``'axes'`` properties. +rc_mode : int, optional + The context mode passed to `~ultraplot.config.Configurator.context`. +rc_kw : dict-like, optional + An alternative to passing extra keyword arguments. See below. +**kwargs + Remaining keyword arguments are passed to `matplotlib.axes.Axes`.\\n Keyword arguments that match the name of an `~ultraplot.config.rc` setting are + passed to `ultraplot.config.Configurator.context` and used to update the axes. + If the setting name has "dots" you can simply omit the dots. For example, + ``abc='A.'`` modifies the :rcraw:`abc` setting, ``titleloc='left'`` modifies the + :rcraw:`title.loc` setting, ``gridminor=True`` modifies the :rcraw:`gridminor` + setting, and ``gridbelow=True`` modifies the :rcraw:`grid.below` setting. Many + of the keyword arguments documented above are internally applied by retrieving + settings passed to `~ultraplot.config.Configurator.context`. + +See also +-------- +PolarAxes.format +ultraplot.axes.Axes +ultraplot.axes.PlotAxes +matplotlib.projections.PolarAxes +ultraplot.figure.Figure.subplot +ultraplot.figure.Figure.add_subplot""" + ... + + @override + def _apply_axis_sharing(self) -> Incomplete: + ... + + def _update_formatter(self, x: Incomplete, *, formatter: Incomplete=None, formatter_kw: Incomplete=None) -> None: + """Update the gridline label formatter.""" + ... + + def _update_limits(self, x: Incomplete, *, min_: Incomplete=None, max_: Incomplete=None, lim: Incomplete=None) -> None: + """Update the limits.""" + ... + + def _update_locators(self, x: Incomplete, *, locator: Incomplete=None, locator_kw: Incomplete=None, minorlocator: Incomplete=None, minorlocator_kw: Incomplete=None) -> None: + """Update the gridline locator.""" + ... + + def _get_directed_thetalim(self) -> tuple[float, float]: + """Return the directed theta interval in degrees from the raw x-limits.""" + ... + + @staticmethod + def _is_full_circle_thetalim(thetamin: Incomplete, thetamax: Incomplete) -> Incomplete: + """Return whether the directed theta interval spans a full circle.""" + ... + + def _polar_tick_clearance_in(self, axis: Incomplete) -> Incomplete: + """Tick mark + tick pad + ~font height(s), in inches.""" + ... + + def _build_thetalabel_curve(self, loc: Incomplete, total_pad_in: Incomplete) -> Incomplete: + """Curve along the outer arc at r = rmax + delta_r (data coords). The +radial offset is computed in data space so clearance is angle- +independent — figure-space ScaledTranslation undershoots when the +outward direction points toward a tight bbox edge (e.g. 180–230°).""" + ... + + def _get_sector_rlabel_outside_sign(self, rpos: Incomplete) -> float: + """Return the sign that offsets a sector rlabel outside the wedge.""" + ... + + def _resolve_rlabel_geometry(self, loc: Incomplete, rlabelpos: Incomplete) -> tuple[float, float]: + """Resolve ``(rpos, sign)`` for the radial label given ``rlabelloc`` and +an optional explicit ``rlabelpos``. On a full circle, ``loc`` flips +the perpendicular offset; on a sector with no explicit ``rlabelpos``, +``loc`` instead selects the spoke (``thetamin`` vs ``thetamax``) and +the perpendicular sign is auto-chosen to fall outside the wedge.""" + ... + + def _get_rlabel_right_normal(self, rad: Incomplete) -> Incomplete: + """Return the display-space right normal for the radial spoke at ``rad``.""" + ... + + def _build_rlabel_curve(self, loc: Incomplete, pad_in: Incomplete, rlabelpos: Incomplete) -> Incomplete: + """Curve along the radial spoke from rmin to rmax with a perpendicular +ScaledTranslation offset so the label clears the r-tick labels.""" + ... + + def _refresh_polar_label_geometry(self, kind: Incomplete) -> None: + """Refresh the stored curve and transform for an existing polar label.""" + ... + + def _update_polar_label(self, kind: Incomplete, text: Incomplete, *, loc: Incomplete=None, labelpad: Incomplete=None, rlabelpos: Incomplete=None, **kwargs: Incomplete) -> None: + """Apply a polar-aware axis label along the outer arc (`thetalabel`) or +along the radial spoke (`rlabel`), both via CurvedText.""" + ... + + @override + def draw(self, renderer: Incomplete=None, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + ... + + @override + def get_tightbbox(self, renderer: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + ... + + def format(self, *, r0: Incomplete=None, theta0: Incomplete=None, thetadir: Incomplete=None, thetamin: Incomplete=None, thetamax: Incomplete=None, thetalim: Incomplete=None, rmin: Incomplete=None, rmax: Incomplete=None, rlim: Incomplete=None, thetagrid: Incomplete=None, rgrid: Incomplete=None, thetagridminor: Incomplete=None, rgridminor: Incomplete=None, thetagridcolor: Incomplete=None, rgridcolor: Incomplete=None, rlabelpos: Incomplete=None, rscale: Incomplete=None, rborder: Incomplete=None, thetalocator: Incomplete=None, rlocator: Incomplete=None, thetalines: Incomplete=None, rlines: Incomplete=None, thetalocator_kw: Incomplete=None, rlocator_kw: Incomplete=None, thetaminorlocator: Incomplete=None, rminorlocator: Incomplete=None, thetaminorlines: Incomplete=None, rminorlines: Incomplete=None, thetaminorlocator_kw: Incomplete=None, rminorlocator_kw: Incomplete=None, thetaformatter: Incomplete=None, rformatter: Incomplete=None, thetalabels: Incomplete=None, rlabels: Incomplete=None, thetaformatter_kw: Incomplete=None, rformatter_kw: Incomplete=None, labelpad: Incomplete=None, labelsize: Incomplete=None, labelcolor: Incomplete=None, labelweight: Incomplete=None, thetalabel: Incomplete=None, rlabel: Incomplete=None, thetalabelloc: Incomplete=None, rlabelloc: Incomplete=None, thetalabel_kw: Incomplete=None, rlabel_kw: Incomplete=None, **kwargs: Incomplete) -> None: + """Modify axes limits, radial and azimuthal gridlines, and more. Note that +all of the ``theta`` arguments are specified in degrees, not radians. + +Parameters +---------- +r0 : float, default: 0 + The radial origin. +theta0 : {'N', 'NW', 'W', 'SW', 'S', 'SE', 'E', 'NE'}, optional + The zero azimuth location. +thetadir : {1, -1, 'anticlockwise', 'counterclockwise', 'clockwise'}, optional + The positive azimuth direction. Clockwise corresponds to + ``-1`` and anticlockwise corresponds to ``1``. +thetamin, thetamax : float, optional + The lower and upper azimuthal bounds in degrees. If + ``thetamax != thetamin + 360``, this produces a sector plot. +thetalim : 2-tuple of float or None, optional + Specifies `thetamin` and `thetamax` at once. +rmin, rmax : float, optional + The inner and outer radial limits. If ``r0 != rmin``, this + produces an annular plot. +rlim : 2-tuple of float or None, optional + Specifies `rmin` and `rmax` at once. +rborder : bool, optional + Whether to draw the polar axes border. Visibility of the "inner" + radial spine and "start" and "end" azimuthal spines is controlled + automatically by matplotlib. +thetagrid, rgrid, grid : bool, optional + Whether to draw major gridlines for the azimuthal and radial axis. + Use the keyword `grid` to toggle both. +thetagridminor, rgridminor, gridminor : bool, optional + Whether to draw minor gridlines for the azimuthal and radial axis. + Use the keyword `gridminor` to toggle both. +thetagridcolor, rgridcolor, gridcolor : color-spec, optional + Color for the major and minor azimuthal and radial gridlines. + Use the keyword `gridcolor` to set both at once. +thetalocator, rlocator : locator-spec, optional + Used to determine the azimuthal and radial gridline positions. + Passed to the `~ultraplot.constructor.Locator` constructor. Can be + float, list of float, string, or `matplotlib.ticker.Locator` instance. +thetalines, rlines + Aliases for `thetalocator`, `rlocator`. +thetalocator_kw, rlocator_kw : dict-like, optional + The azimuthal and radial locator settings. Passed to + `~ultraplot.constructor.Locator`. +thetaminorlocator, rminorlocator : optional + As for `thetalocator`, `rlocator`, but for the minor gridlines. +thetaminorticks, rminorticks : optional + Aliases for `thetaminorlocator`, `rminorlocator`. +thetaminorlocator_kw, rminorlocator_kw + As for `thetalocator_kw`, `rlocator_kw`, but for the minor locator. +rlabelpos : float, optional + The azimuth at which radial coordinates are labeled. Also used as the + spoke angle for ``rlabel`` when you want an explicit radial-label + position. +thetaformatter, rformatter : formatter-spec, optional + Used to determine the azimuthal and radial label format. + Passed to the `~ultraplot.constructor.Formatter` constructor. + Can be string, list of string, or `matplotlib.ticker.Formatter` + instance. Use ``[]``, ``'null'``, or ``'none'`` for no labels. +thetalabels, rlabels : optional + Aliases for `thetaformatter`, `rformatter`. +thetaformatter_kw, rformatter_kw : dict-like, optional + The azimuthal and radial label formatter settings. Passed to + `~ultraplot.constructor.Formatter`. +thetalabel, rlabel : str, optional + Polar-aware axis labels rendered via `~ultraplot.text.CurvedText`. + ``thetalabel`` follows the outer arc just beyond ``r=rmax``. + ``rlabel`` follows a radial spoke, centered between ``rmin`` and + ``rmax``. On a full circle it uses ``get_rlabel_position()`` unless + ``rlabelpos`` is explicit; on a sector it uses the spoke selected by + ``rlabelloc`` unless ``rlabelpos`` is explicit. Both labels include a + built-in tick-clearance offset, and ``labelpad`` adds extra padding in + points on top of that offset. Pass ``""`` to clear a previously set + label. +thetalabelloc : float, optional + Center theta angle (in degrees) for ``thetalabel``. Defaults to the + midpoint of the directed ``thetalim`` interval (or ``0`` for a full + circle). +rlabelloc : {'right', 'left'}, default: 'right' + Where to place ``rlabel``. When the spoke angle is fixed by a full + circle or by explicit ``rlabelpos``, ``rlabelloc`` selects the + perpendicular side of that spoke and ``'left'`` flips the default + side. On a sector with no explicit ``rlabelpos``, ``'right'`` + (default) anchors to ``thetamin`` and ``'left'`` anchors to + ``thetamax``; the label is then offset outward from the sector. +thetalabel_kw, rlabel_kw : dict-like, optional + Additional `~ultraplot.text.CurvedText` settings for the polar-aware + labels (e.g. ``border``, ``bbox``, or rendering hints like + ``min_advance``). See also `labelpad`, `labelcolor`, `labelsize`, + and `labelweight`. +color : color-spec, default: :rc:`meta.color` + Color for the axes edge. Propagates to `labelcolor` unless specified + otherwise (similar to :func:`~ultraplot.axes.CartesianAxes.format`). +labelcolor, gridlabelcolor : color-spec, default: `color` or :rc:`grid.labelcolor` + Color for the gridline labels. +labelpad, gridlabelpad : unit-spec, default: :rc:`grid.labelpad` + The padding between the axes edge and the radial and azimuthal labels. + For ``thetalabel`` and ``rlabel``, this is added on top of the built-in + tick-clearance offset. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +labelsize, gridlabelsize : unit-spec or str, default: :rc:`grid.labelsize` + Font size for the gridline labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +labelweight, gridlabelweight : str, default: :rc:`grid.labelweight` + Font weight for the gridline labels. + +Other parameters +---------------- +title : str or sequence, optional + The axes title. Can optionally be a sequence strings, in which case + the title will be selected from the sequence according to `~Axes.number`. +abc : bool or str or sequence, default: :rc:`abc` + The "a-b-c" subplot label style. Must contain the character `a` or `A`, + for example ``'a.'``, or ``'A'``. If ``True`` then the default style of + ``'a'`` is used. The `a` or ``A`` is replaced with the alphabetic character + matching the `~Axes.number`. If `~Axes.number` is greater than 26, the + characters loop around to a, ..., z, aa, ..., zz, aaa, ..., zzz, etc. + Can also be a sequence of strings, in which case the "a-b-c" label will be selected sequentially from the list. For example `axs.format(abc = ["X", "Y"])` for a two-panel figure, and `axes[3:5].format(abc = ["X", "Y"])` for a two-panel subset of a larger figure. +abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` + Strings indicating the location for the a-b-c label and main title. + The following locations are valid: + + .. _title_table: + + ======================== ============================ + Location Valid keys + ======================== ============================ + center above axes ``'center'``, ``'c'`` + left above axes ``'left'``, ``'l'`` + right above axes ``'right'``, ``'r'`` + lower center inside axes ``'lower center'``, ``'lc'`` + upper center inside axes ``'upper center'``, ``'uc'`` + upper right inside axes ``'upper right'``, ``'ur'`` + upper left inside axes ``'upper left'``, ``'ul'`` + lower left inside axes ``'lower left'``, ``'ll'`` + lower right inside axes ``'lower right'``, ``'lr'`` + left of y axis ``'outer left'``, ``'ol'`` + right of y axis ``'outer right'``, ``'or'`` + ======================== ============================ + +abcborder, titleborder : bool, default: :rc:`abc.border` and :rc:`title.border` + Whether to draw a white border around titles and a-b-c labels positioned + inside the axes. This can help them stand out on top of artists + plotted inside the axes. +abcbbox, titlebbox : bool, default: :rc:`abc.bbox` and :rc:`title.bbox` + Whether to draw a white bbox around titles and a-b-c labels positioned + inside the axes. This can help them stand out on top of artists plotted + inside the axes. +abcpad : float or unit-spec, default: :rc:`abc.pad` + Horizontal offset to shift the a-b-c label position. Positive values move + the label right, negative values move it left. This is separate from + `abctitlepad`, which controls spacing between abc and title when co-located. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +abc_kw, title_kw : dict-like, optional + Additional settings used to update the a-b-c label and title + with ``text.update()``. +titlepad : float, default: :rc:`title.pad` + The padding for the inner and outer titles and a-b-c labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +titleabove : bool, default: :rc:`title.above` + Whether to try to put outer titles and a-b-c labels above panels, + colorbars, or legends that are above the axes. +abctitlepad : float, default: :rc:`abc.titlepad` + The horizontal padding between a-b-c labels and titles in the same location. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle : str or sequence, optional + Shorthands for the below keywords. + lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle : str or sequence, optional +lowerlefttitle, lowercentertitle, lowerrighttitle : str or sequence, optional + Additional titles in specific positions (see `title` for details). This works as + an alternative to the ``ax.format(title='Title', titleloc=loc)`` workflow and + permits adding more than one title-like label for a single axes. +a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle : default: + :rc:`axes.alpha` (default: 1.0), :rc:`axes.facecolor` (default: white), :rc:`axes.edgecolor` (default: black), :rc:`axes.linewidth` (default: 0.6), - + Additional settings applied to the background patch, and their + shorthands. Their defaults values are the ``'axes'`` properties. +rowlabels, collabels, llabels, tlabels, rlabels, blabels + Aliases for `leftlabels` and `toplabels`, and for `leftlabels`, + `toplabels`, `rightlabels`, and `bottomlabels`, respectively. +leftlabels, toplabels, rightlabels, bottomlabels : sequence of str, optional + Labels for the subplots lying along the left, top, right, and + bottom edges of the figure. The length of each list must match + the number of subplots along the corresponding edge. +leftlabelpad, toplabelpad, rightlabelpad, bottomlabelpad : float or unit-spec, default +: :rc:`leftlabel.pad`, :rc:`toplabel.pad`, :rc:`rightlabel.pad`, :rc:`bottomlabel.pad` + The padding between the labels and the axes content. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +leftlabelsharedpad, toplabelsharedpad, rightlabelsharedpad, bottomlabelsharedpad : float or unit-spec, default +: :rc:`leftlabel.sharedpad`, :rc:`toplabel.sharedpad`, :rc:`rightlabel.sharedpad`, :rc:`bottomlabel.sharedpad` + The padding between side labels and a shared spanning axis label on the + same side. The spanning label is placed outside the side labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +leftlabels_kw, toplabels_kw, rightlabels_kw, bottomlabels_kw : dict-like, optional + Additional settings used to update the labels with ``text.update()``. +figtitle + Alias for `suptitle`. +suptitle : str, optional + The figure "super" title, centered between the left edge of the leftmost + subplot and the right edge of the rightmost subplot. +suptitlepad : float, default: :rc:`suptitle.pad` + The padding between the super title and the axes content. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +suptitle_kw : optional + Additional settings used to update the super title with ``text.update()``. +includepanels : bool, default: False + Whether to include panels when aligning figure "super titles" along the top + of the subplot grid and when aligning the `spanx` *x* axis labels and + `spany` *y* axis labels along the sides of the subplot grid. +rc_mode : int, optional + The context mode passed to `~ultraplot.config.Configurator.context`. +rc_kw : dict-like, optional + An alternative to passing extra keyword arguments. See below. +**kwargs + Keyword arguments that match the name of an `~ultraplot.config.rc` setting are + passed to `ultraplot.config.Configurator.context` and used to update the axes. + If the setting name has "dots" you can simply omit the dots. For example, + ``abc='A.'`` modifies the :rcraw:`abc` setting, ``titleloc='left'`` modifies the + :rcraw:`title.loc` setting, ``gridminor=True`` modifies the :rcraw:`gridminor` + setting, and ``gridbelow=True`` modifies the :rcraw:`grid.below` setting. Many + of the keyword arguments documented above are internally applied by retrieving + settings passed to `~ultraplot.config.Configurator.context`. + +See also +-------- +ultraplot.axes.Axes.format +ultraplot.config.Configurator.context""" + ... diff --git a/ultraplot/axes/shared.pyi b/ultraplot/axes/shared.pyi new file mode 100644 index 000000000..5851fa129 --- /dev/null +++ b/ultraplot/axes/shared.pyi @@ -0,0 +1,50 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +An axes used to jointly format Cartesian and polar axes. +""" +from _typeshed import Incomplete +import numpy as np +from ..config import rc +from ..internals import ic +from ..internals import _pop_kwargs +from ..utils import _fontsize_to_pt, _not_none, units +from ..axes import Axes +try: + from typing import override +except ImportError: + from typing_extensions import override + +class _SharedAxes(object): + """ + Mix-in class with methods shared between `~ultraplot.axes.CartesianAxes` + and :class:`~ultraplot.axes.PolarAxes`. + """ + + @staticmethod + def _min_max_lim(key: Incomplete, min_: Incomplete=None, max_: Incomplete=None, lim: Incomplete=None) -> Incomplete: + """Translate and standardize minimum, maximum, and limit keyword arguments.""" + ... + + def _update_background(self, **kwargs: Incomplete) -> Incomplete: + """Update the background patch.""" + ... + + def _update_frame(self, x: Incomplete, *, edgecolor: Incomplete=None, linewidth: Incomplete=None, tickcolor: Incomplete=None, tickwidth: Incomplete=None, tickwidthratio: Incomplete=None) -> None: + """Update the axis frame, including spines and tick line appearance.""" + ... + + def _update_ticks(self, x: Incomplete, *, grid: Incomplete=None, gridminor: Incomplete=None, gridpad: Incomplete=None, gridcolor: Incomplete=None, ticklen: Incomplete=None, ticklenratio: Incomplete=None, tickdir: Incomplete=None, tickcolor: Incomplete=None, labeldir: Incomplete=None, labelpad: Incomplete=None, labelcolor: Incomplete=None, labelsize: Incomplete=None, labelweight: Incomplete=None) -> None: + """Update the gridlines and labels. Set `gridpad` to ``True`` to use grid padding.""" + ... + + @override + def sharex(self, other: Incomplete) -> Incomplete: + ... + + @override + def sharey(self, other: Incomplete) -> Incomplete: + ... + + def _share_axis_with(self, other: 'Axes', *, which: str) -> TypeError | None: + ... diff --git a/ultraplot/axes/taylor.pyi b/ultraplot/axes/taylor.pyi new file mode 100644 index 000000000..f33c1a575 --- /dev/null +++ b/ultraplot/axes/taylor.pyi @@ -0,0 +1,561 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Taylor diagram axes. +""" +from _typeshed import Incomplete +import inspect +import matplotlib.projections.polar as mpolar +import matplotlib.ticker as mticker +import matplotlib.transforms as mtransforms +import numpy as np +from ..config import rc +from ..internals import _not_none, _pop_rc, docstring +from .polar import PolarAxes +__all__ = ['TaylorAxes'] +_format_docstring = ... + +class TaylorAxes(PolarAxes): + """ + Axes subclass for Taylor diagrams. + + Important + --------- + This axes subclass can be used by passing ``proj='taylor'`` to + axes-creation commands like `~ultraplot.figure.Figure.add_axes`, + `~ultraplot.figure.Figure.add_subplot`, and + `~ultraplot.figure.Figure.subplots`. + """ + _name = 'taylor' + _name_aliases = () + _default_corrs = np.array((1.0, 0.95, 0.9, 0.8, 0.6, 0.4, 0.2, 0.0)) + _quadrant_aliases = {'1': 1, 'i': 1, 'ur': 1, 'upper right': 1, 'upright': 1, '2': 2, 'ii': 2, 'ul': 2, 'upper left': 2, 'upleft': 2, '3': 3, 'iii': 3, 'll': 3, 'lower left': 3, 'lowleft': 3, '4': 4, 'iv': 4, 'lr': 4, 'lower right': 4, 'lowright': 4, 'upside down': 4} + + def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: + """Parameters +---------- +*args + Passed to `matplotlib.axes.Axes`. +xlabel, ylabel : str, optional + Labels for the standard-deviation axes. These are drawn as Taylor-specific + text artists while the native polar axis labels are kept hidden. +corrlabel : str, default: 'Correlation' + Label for the correlation-coefficient grid. +thetaunit : {'corr', 'deg', 'rad'}, default: 'corr' + Units used for the angular grid labels. The default labels angular ticks + as correlation coefficients. +quadrant : {1, 2, 3, 4} or str, default: 1 + The quadrant used for the Taylor diagram. Quadrants follow the Cartesian + convention: ``1`` is upper right and ``4`` is lower right. +corrlocator, corrlines, corrticks : float or sequence of float, optional + Correlation coefficients used for the angular gridlines. +labelcolor, labelsize, labelweight : optional + Label text properties. +r0 : float, default: 0 + The radial origin. +theta0 : {'N', 'NW', 'W', 'SW', 'S', 'SE', 'E', 'NE'}, optional + The zero azimuth location. +thetadir : {1, -1, 'anticlockwise', 'counterclockwise', 'clockwise'}, optional + The positive azimuth direction. Clockwise corresponds to + ``-1`` and anticlockwise corresponds to ``1``. +thetamin, thetamax : float, optional + The lower and upper azimuthal bounds in degrees. If + ``thetamax != thetamin + 360``, this produces a sector plot. +thetalim : 2-tuple of float or None, optional + Specifies `thetamin` and `thetamax` at once. +rmin, rmax : float, optional + The inner and outer radial limits. If ``r0 != rmin``, this + produces an annular plot. +rlim : 2-tuple of float or None, optional + Specifies `rmin` and `rmax` at once. +rborder : bool, optional + Whether to draw the polar axes border. Visibility of the "inner" + radial spine and "start" and "end" azimuthal spines is controlled + automatically by matplotlib. +thetagrid, rgrid, grid : bool, optional + Whether to draw major gridlines for the azimuthal and radial axis. + Use the keyword `grid` to toggle both. +thetagridminor, rgridminor, gridminor : bool, optional + Whether to draw minor gridlines for the azimuthal and radial axis. + Use the keyword `gridminor` to toggle both. +thetagridcolor, rgridcolor, gridcolor : color-spec, optional + Color for the major and minor azimuthal and radial gridlines. + Use the keyword `gridcolor` to set both at once. +thetalocator, rlocator : locator-spec, optional + Used to determine the azimuthal and radial gridline positions. + Passed to the `~ultraplot.constructor.Locator` constructor. Can be + float, list of float, string, or `matplotlib.ticker.Locator` instance. +thetalines, rlines + Aliases for `thetalocator`, `rlocator`. +thetalocator_kw, rlocator_kw : dict-like, optional + The azimuthal and radial locator settings. Passed to + `~ultraplot.constructor.Locator`. +thetaminorlocator, rminorlocator : optional + As for `thetalocator`, `rlocator`, but for the minor gridlines. +thetaminorticks, rminorticks : optional + Aliases for `thetaminorlocator`, `rminorlocator`. +thetaminorlocator_kw, rminorlocator_kw + As for `thetalocator_kw`, `rlocator_kw`, but for the minor locator. +rlabelpos : float, optional + The azimuth at which radial coordinates are labeled. Also used as the + spoke angle for ``rlabel`` when you want an explicit radial-label + position. +thetaformatter, rformatter : formatter-spec, optional + Used to determine the azimuthal and radial label format. + Passed to the `~ultraplot.constructor.Formatter` constructor. + Can be string, list of string, or `matplotlib.ticker.Formatter` + instance. Use ``[]``, ``'null'``, or ``'none'`` for no labels. +thetalabels, rlabels : optional + Aliases for `thetaformatter`, `rformatter`. +thetaformatter_kw, rformatter_kw : dict-like, optional + The azimuthal and radial label formatter settings. Passed to + `~ultraplot.constructor.Formatter`. +thetalabel, rlabel : str, optional + Polar-aware axis labels rendered via `~ultraplot.text.CurvedText`. + ``thetalabel`` follows the outer arc just beyond ``r=rmax``. + ``rlabel`` follows a radial spoke, centered between ``rmin`` and + ``rmax``. On a full circle it uses ``get_rlabel_position()`` unless + ``rlabelpos`` is explicit; on a sector it uses the spoke selected by + ``rlabelloc`` unless ``rlabelpos`` is explicit. Both labels include a + built-in tick-clearance offset, and ``labelpad`` adds extra padding in + points on top of that offset. Pass ``""`` to clear a previously set + label. +thetalabelloc : float, optional + Center theta angle (in degrees) for ``thetalabel``. Defaults to the + midpoint of the directed ``thetalim`` interval (or ``0`` for a full + circle). +rlabelloc : {'right', 'left'}, default: 'right' + Where to place ``rlabel``. When the spoke angle is fixed by a full + circle or by explicit ``rlabelpos``, ``rlabelloc`` selects the + perpendicular side of that spoke and ``'left'`` flips the default + side. On a sector with no explicit ``rlabelpos``, ``'right'`` + (default) anchors to ``thetamin`` and ``'left'`` anchors to + ``thetamax``; the label is then offset outward from the sector. +thetalabel_kw, rlabel_kw : dict-like, optional + Additional `~ultraplot.text.CurvedText` settings for the polar-aware + labels (e.g. ``border``, ``bbox``, or rendering hints like + ``min_advance``). See also `labelpad`, `labelcolor`, `labelsize`, + and `labelweight`. +color : color-spec, default: :rc:`meta.color` + Color for the axes edge. Propagates to `labelcolor` unless specified + otherwise (similar to :func:`~ultraplot.axes.CartesianAxes.format`). +labelcolor, gridlabelcolor : color-spec, default: `color` or :rc:`grid.labelcolor` + Color for the gridline labels. +labelpad, gridlabelpad : unit-spec, default: :rc:`grid.labelpad` + The padding between the axes edge and the radial and azimuthal labels. + For ``thetalabel`` and ``rlabel``, this is added on top of the built-in + tick-clearance offset. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +labelsize, gridlabelsize : unit-spec or str, default: :rc:`grid.labelsize` + Font size for the gridline labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +labelweight, gridlabelweight : str, default: :rc:`grid.labelweight` + Font weight for the gridline labels. + +Other parameters +---------------- +title : str or sequence, optional + The axes title. Can optionally be a sequence strings, in which case + the title will be selected from the sequence according to `~Axes.number`. +abc : bool or str or sequence, default: :rc:`abc` + The "a-b-c" subplot label style. Must contain the character `a` or `A`, + for example ``'a.'``, or ``'A'``. If ``True`` then the default style of + ``'a'`` is used. The `a` or ``A`` is replaced with the alphabetic character + matching the `~Axes.number`. If `~Axes.number` is greater than 26, the + characters loop around to a, ..., z, aa, ..., zz, aaa, ..., zzz, etc. + Can also be a sequence of strings, in which case the "a-b-c" label will be selected sequentially from the list. For example `axs.format(abc = ["X", "Y"])` for a two-panel figure, and `axes[3:5].format(abc = ["X", "Y"])` for a two-panel subset of a larger figure. +abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` + Strings indicating the location for the a-b-c label and main title. + The following locations are valid: + + .. _title_table: + + ======================== ============================ + Location Valid keys + ======================== ============================ + center above axes ``'center'``, ``'c'`` + left above axes ``'left'``, ``'l'`` + right above axes ``'right'``, ``'r'`` + lower center inside axes ``'lower center'``, ``'lc'`` + upper center inside axes ``'upper center'``, ``'uc'`` + upper right inside axes ``'upper right'``, ``'ur'`` + upper left inside axes ``'upper left'``, ``'ul'`` + lower left inside axes ``'lower left'``, ``'ll'`` + lower right inside axes ``'lower right'``, ``'lr'`` + left of y axis ``'outer left'``, ``'ol'`` + right of y axis ``'outer right'``, ``'or'`` + ======================== ============================ + +abcborder, titleborder : bool, default: :rc:`abc.border` and :rc:`title.border` + Whether to draw a white border around titles and a-b-c labels positioned + inside the axes. This can help them stand out on top of artists + plotted inside the axes. +abcbbox, titlebbox : bool, default: :rc:`abc.bbox` and :rc:`title.bbox` + Whether to draw a white bbox around titles and a-b-c labels positioned + inside the axes. This can help them stand out on top of artists plotted + inside the axes. +abcpad : float or unit-spec, default: :rc:`abc.pad` + Horizontal offset to shift the a-b-c label position. Positive values move + the label right, negative values move it left. This is separate from + `abctitlepad`, which controls spacing between abc and title when co-located. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +abc_kw, title_kw : dict-like, optional + Additional settings used to update the a-b-c label and title + with ``text.update()``. +titlepad : float, default: :rc:`title.pad` + The padding for the inner and outer titles and a-b-c labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +titleabove : bool, default: :rc:`title.above` + Whether to try to put outer titles and a-b-c labels above panels, + colorbars, or legends that are above the axes. +abctitlepad : float, default: :rc:`abc.titlepad` + The horizontal padding between a-b-c labels and titles in the same location. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle : str or sequence, optional + Shorthands for the below keywords. + lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle : str or sequence, optional +lowerlefttitle, lowercentertitle, lowerrighttitle : str or sequence, optional + Additional titles in specific positions (see `title` for details). This works as + an alternative to the ``ax.format(title='Title', titleloc=loc)`` workflow and + permits adding more than one title-like label for a single axes. +a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle : default: + :rc:`axes.alpha` (default: 1.0), :rc:`axes.facecolor` (default: white), :rc:`axes.edgecolor` (default: black), :rc:`axes.linewidth` (default: 0.6), - + Additional settings applied to the background patch, and their + shorthands. Their defaults values are the ``'axes'`` properties. +rc_mode : int, optional + The context mode passed to `~ultraplot.config.Configurator.context`. +rc_kw : dict-like, optional + An alternative to passing extra keyword arguments. See below. +**kwargs + Remaining keyword arguments are passed to `matplotlib.axes.Axes`.\\n Keyword arguments that match the name of an `~ultraplot.config.rc` setting are + passed to `ultraplot.config.Configurator.context` and used to update the axes. + If the setting name has "dots" you can simply omit the dots. For example, + ``abc='A.'`` modifies the :rcraw:`abc` setting, ``titleloc='left'`` modifies the + :rcraw:`title.loc` setting, ``gridminor=True`` modifies the :rcraw:`gridminor` + setting, and ``gridbelow=True`` modifies the :rcraw:`grid.below` setting. Many + of the keyword arguments documented above are internally applied by retrieving + settings passed to `~ultraplot.config.Configurator.context`. + +See also +-------- +TaylorAxes.format +ultraplot.axes.PolarAxes""" + ... + + @staticmethod + def correlation_to_angle(correlation: Incomplete) -> Incomplete: + """Convert correlation coefficients to Taylor-diagram polar angles.""" + ... + + @classmethod + def _parse_quadrant(cls, quadrant: Incomplete) -> int | None: + """Normalize Taylor quadrant input.""" + ... + + @staticmethod + def _quadrant_bounds(quadrant: Incomplete) -> tuple[int, int]: + """Return theta bounds in degrees for a Taylor quadrant.""" + ... + + def _correlation_to_theta(self, correlation: Incomplete) -> Incomplete: + """Convert correlation coefficients to displayed polar angles.""" + ... + + def plot_corr(self, correlation: Incomplete, stddev: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot values specified as correlation coefficient and standard deviation.""" + ... + + def scatter_corr(self, correlation: Incomplete, stddev: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Scatter values specified as correlation coefficient and standard deviation.""" + ... + + def get_tightbbox(self, renderer: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Return a stable tight bbox before the first draw. + +Matplotlib's polar radial axis can report a spurious far-left bbox for +Taylor's quarter-sector view before the first draw. This feeds back into +UltraPlot's reference-width autosizing and creates excessive left margin.""" + ... + + def set_xlabel(self, xlabel: Incomplete, fontdict: Incomplete=None, labelpad: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Set the Taylor x label while keeping the native polar label hidden.""" + ... + + def set_ylabel(self, ylabel: Incomplete, fontdict: Incomplete=None, labelpad: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Set the Taylor y label while keeping the native polar label hidden.""" + ... + + def _apply_taylor_defaults(self) -> None: + """Apply the fixed quarter-polar Taylor diagram defaults.""" + ... + + def _ensure_taylor_artists(self) -> None: + """Create Taylor-specific label artists on demand.""" + ... + + def _format_correlation(self, value: Incomplete) -> str: + """Format one angular tick according to the active Taylor theta unit.""" + ... + + def _update_taylor_label_positions(self, labelpad: Incomplete=None) -> None: + """Update fixed Taylor label locations.""" + ... + + def _update_taylor_labels(self, *, xlabel: Incomplete=None, ylabel: Incomplete=None, corrlabel: Incomplete=None, labelpad: Incomplete=None, labelcolor: Incomplete=None, labelsize: Incomplete=None, labelweight: Incomplete=None, xlabel_kw: Incomplete=None, ylabel_kw: Incomplete=None, corrlabel_kw: Incomplete=None) -> None: + """Update Taylor-specific axis labels.""" + ... + + def _update_taylor_ticks(self, corrs: Incomplete=None) -> None: + """Update angular grid labels from correlation coefficients.""" + ... + + def _update_taylor_std_ticklabels(self) -> None: + """Duplicate radial tick labels onto the vertical standard-deviation axis.""" + ... + + def draw(self, renderer: Incomplete=None, *args: Incomplete, **kwargs: Incomplete) -> None: + """Draw after refreshing Taylor-specific standard-deviation tick labels.""" + ... + + def format(self, *, xlabel: Incomplete=None, ylabel: Incomplete=None, corrlabel: Incomplete=None, thetaunit: Incomplete=None, quadrant: Incomplete=None, corrlocator: Incomplete=None, corrlines: Incomplete=None, corrticks: Incomplete=None, xlabel_kw: Incomplete=None, ylabel_kw: Incomplete=None, corrlabel_kw: Incomplete=None, labelpad: Incomplete=None, labelcolor: Incomplete=None, labelsize: Incomplete=None, labelweight: Incomplete=None, **kwargs: Incomplete) -> None: + """Modify Taylor diagram labels, correlation gridlines, and polar settings. + +Parameters +---------- +xlabel, ylabel : str, optional + Labels for the standard-deviation axes. These are drawn as Taylor-specific + text artists while the native polar axis labels are kept hidden. +corrlabel : str, default: 'Correlation' + Label for the correlation-coefficient grid. +thetaunit : {'corr', 'deg', 'rad'}, default: 'corr' + Units used for the angular grid labels. The default labels angular ticks + as correlation coefficients. +quadrant : {1, 2, 3, 4} or str, default: 1 + The quadrant used for the Taylor diagram. Quadrants follow the Cartesian + convention: ``1`` is upper right and ``4`` is lower right. +corrlocator, corrlines, corrticks : float or sequence of float, optional + Correlation coefficients used for the angular gridlines. +labelcolor, labelsize, labelweight : optional + Label text properties. + +Other parameters +---------------- +r0 : float, default: 0 + The radial origin. +theta0 : {'N', 'NW', 'W', 'SW', 'S', 'SE', 'E', 'NE'}, optional + The zero azimuth location. +thetadir : {1, -1, 'anticlockwise', 'counterclockwise', 'clockwise'}, optional + The positive azimuth direction. Clockwise corresponds to + ``-1`` and anticlockwise corresponds to ``1``. +thetamin, thetamax : float, optional + The lower and upper azimuthal bounds in degrees. If + ``thetamax != thetamin + 360``, this produces a sector plot. +thetalim : 2-tuple of float or None, optional + Specifies `thetamin` and `thetamax` at once. +rmin, rmax : float, optional + The inner and outer radial limits. If ``r0 != rmin``, this + produces an annular plot. +rlim : 2-tuple of float or None, optional + Specifies `rmin` and `rmax` at once. +rborder : bool, optional + Whether to draw the polar axes border. Visibility of the "inner" + radial spine and "start" and "end" azimuthal spines is controlled + automatically by matplotlib. +thetagrid, rgrid, grid : bool, optional + Whether to draw major gridlines for the azimuthal and radial axis. + Use the keyword `grid` to toggle both. +thetagridminor, rgridminor, gridminor : bool, optional + Whether to draw minor gridlines for the azimuthal and radial axis. + Use the keyword `gridminor` to toggle both. +thetagridcolor, rgridcolor, gridcolor : color-spec, optional + Color for the major and minor azimuthal and radial gridlines. + Use the keyword `gridcolor` to set both at once. +thetalocator, rlocator : locator-spec, optional + Used to determine the azimuthal and radial gridline positions. + Passed to the `~ultraplot.constructor.Locator` constructor. Can be + float, list of float, string, or `matplotlib.ticker.Locator` instance. +thetalines, rlines + Aliases for `thetalocator`, `rlocator`. +thetalocator_kw, rlocator_kw : dict-like, optional + The azimuthal and radial locator settings. Passed to + `~ultraplot.constructor.Locator`. +thetaminorlocator, rminorlocator : optional + As for `thetalocator`, `rlocator`, but for the minor gridlines. +thetaminorticks, rminorticks : optional + Aliases for `thetaminorlocator`, `rminorlocator`. +thetaminorlocator_kw, rminorlocator_kw + As for `thetalocator_kw`, `rlocator_kw`, but for the minor locator. +rlabelpos : float, optional + The azimuth at which radial coordinates are labeled. Also used as the + spoke angle for ``rlabel`` when you want an explicit radial-label + position. +thetaformatter, rformatter : formatter-spec, optional + Used to determine the azimuthal and radial label format. + Passed to the `~ultraplot.constructor.Formatter` constructor. + Can be string, list of string, or `matplotlib.ticker.Formatter` + instance. Use ``[]``, ``'null'``, or ``'none'`` for no labels. +thetalabels, rlabels : optional + Aliases for `thetaformatter`, `rformatter`. +thetaformatter_kw, rformatter_kw : dict-like, optional + The azimuthal and radial label formatter settings. Passed to + `~ultraplot.constructor.Formatter`. +thetalabel, rlabel : str, optional + Polar-aware axis labels rendered via `~ultraplot.text.CurvedText`. + ``thetalabel`` follows the outer arc just beyond ``r=rmax``. + ``rlabel`` follows a radial spoke, centered between ``rmin`` and + ``rmax``. On a full circle it uses ``get_rlabel_position()`` unless + ``rlabelpos`` is explicit; on a sector it uses the spoke selected by + ``rlabelloc`` unless ``rlabelpos`` is explicit. Both labels include a + built-in tick-clearance offset, and ``labelpad`` adds extra padding in + points on top of that offset. Pass ``""`` to clear a previously set + label. +thetalabelloc : float, optional + Center theta angle (in degrees) for ``thetalabel``. Defaults to the + midpoint of the directed ``thetalim`` interval (or ``0`` for a full + circle). +rlabelloc : {'right', 'left'}, default: 'right' + Where to place ``rlabel``. When the spoke angle is fixed by a full + circle or by explicit ``rlabelpos``, ``rlabelloc`` selects the + perpendicular side of that spoke and ``'left'`` flips the default + side. On a sector with no explicit ``rlabelpos``, ``'right'`` + (default) anchors to ``thetamin`` and ``'left'`` anchors to + ``thetamax``; the label is then offset outward from the sector. +thetalabel_kw, rlabel_kw : dict-like, optional + Additional `~ultraplot.text.CurvedText` settings for the polar-aware + labels (e.g. ``border``, ``bbox``, or rendering hints like + ``min_advance``). See also `labelpad`, `labelcolor`, `labelsize`, + and `labelweight`. +color : color-spec, default: :rc:`meta.color` + Color for the axes edge. Propagates to `labelcolor` unless specified + otherwise (similar to :func:`~ultraplot.axes.CartesianAxes.format`). +labelcolor, gridlabelcolor : color-spec, default: `color` or :rc:`grid.labelcolor` + Color for the gridline labels. +labelpad, gridlabelpad : unit-spec, default: :rc:`grid.labelpad` + The padding between the axes edge and the radial and azimuthal labels. + For ``thetalabel`` and ``rlabel``, this is added on top of the built-in + tick-clearance offset. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +labelsize, gridlabelsize : unit-spec or str, default: :rc:`grid.labelsize` + Font size for the gridline labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +labelweight, gridlabelweight : str, default: :rc:`grid.labelweight` + Font weight for the gridline labels. +title : str or sequence, optional + The axes title. Can optionally be a sequence strings, in which case + the title will be selected from the sequence according to `~Axes.number`. +abc : bool or str or sequence, default: :rc:`abc` + The "a-b-c" subplot label style. Must contain the character `a` or `A`, + for example ``'a.'``, or ``'A'``. If ``True`` then the default style of + ``'a'`` is used. The `a` or ``A`` is replaced with the alphabetic character + matching the `~Axes.number`. If `~Axes.number` is greater than 26, the + characters loop around to a, ..., z, aa, ..., zz, aaa, ..., zzz, etc. + Can also be a sequence of strings, in which case the "a-b-c" label will be selected sequentially from the list. For example `axs.format(abc = ["X", "Y"])` for a two-panel figure, and `axes[3:5].format(abc = ["X", "Y"])` for a two-panel subset of a larger figure. +abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` + Strings indicating the location for the a-b-c label and main title. + The following locations are valid: + + .. _title_table: + + ======================== ============================ + Location Valid keys + ======================== ============================ + center above axes ``'center'``, ``'c'`` + left above axes ``'left'``, ``'l'`` + right above axes ``'right'``, ``'r'`` + lower center inside axes ``'lower center'``, ``'lc'`` + upper center inside axes ``'upper center'``, ``'uc'`` + upper right inside axes ``'upper right'``, ``'ur'`` + upper left inside axes ``'upper left'``, ``'ul'`` + lower left inside axes ``'lower left'``, ``'ll'`` + lower right inside axes ``'lower right'``, ``'lr'`` + left of y axis ``'outer left'``, ``'ol'`` + right of y axis ``'outer right'``, ``'or'`` + ======================== ============================ + +abcborder, titleborder : bool, default: :rc:`abc.border` and :rc:`title.border` + Whether to draw a white border around titles and a-b-c labels positioned + inside the axes. This can help them stand out on top of artists + plotted inside the axes. +abcbbox, titlebbox : bool, default: :rc:`abc.bbox` and :rc:`title.bbox` + Whether to draw a white bbox around titles and a-b-c labels positioned + inside the axes. This can help them stand out on top of artists plotted + inside the axes. +abcpad : float or unit-spec, default: :rc:`abc.pad` + Horizontal offset to shift the a-b-c label position. Positive values move + the label right, negative values move it left. This is separate from + `abctitlepad`, which controls spacing between abc and title when co-located. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +abc_kw, title_kw : dict-like, optional + Additional settings used to update the a-b-c label and title + with ``text.update()``. +titlepad : float, default: :rc:`title.pad` + The padding for the inner and outer titles and a-b-c labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +titleabove : bool, default: :rc:`title.above` + Whether to try to put outer titles and a-b-c labels above panels, + colorbars, or legends that are above the axes. +abctitlepad : float, default: :rc:`abc.titlepad` + The horizontal padding between a-b-c labels and titles in the same location. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle : str or sequence, optional + Shorthands for the below keywords. + lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle : str or sequence, optional +lowerlefttitle, lowercentertitle, lowerrighttitle : str or sequence, optional + Additional titles in specific positions (see `title` for details). This works as + an alternative to the ``ax.format(title='Title', titleloc=loc)`` workflow and + permits adding more than one title-like label for a single axes. +a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle : default: + :rc:`axes.alpha` (default: 1.0), :rc:`axes.facecolor` (default: white), :rc:`axes.edgecolor` (default: black), :rc:`axes.linewidth` (default: 0.6), - + Additional settings applied to the background patch, and their + shorthands. Their defaults values are the ``'axes'`` properties. +rowlabels, collabels, llabels, tlabels, rlabels, blabels + Aliases for `leftlabels` and `toplabels`, and for `leftlabels`, + `toplabels`, `rightlabels`, and `bottomlabels`, respectively. +leftlabels, toplabels, rightlabels, bottomlabels : sequence of str, optional + Labels for the subplots lying along the left, top, right, and + bottom edges of the figure. The length of each list must match + the number of subplots along the corresponding edge. +leftlabelpad, toplabelpad, rightlabelpad, bottomlabelpad : float or unit-spec, default +: :rc:`leftlabel.pad`, :rc:`toplabel.pad`, :rc:`rightlabel.pad`, :rc:`bottomlabel.pad` + The padding between the labels and the axes content. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +leftlabelsharedpad, toplabelsharedpad, rightlabelsharedpad, bottomlabelsharedpad : float or unit-spec, default +: :rc:`leftlabel.sharedpad`, :rc:`toplabel.sharedpad`, :rc:`rightlabel.sharedpad`, :rc:`bottomlabel.sharedpad` + The padding between side labels and a shared spanning axis label on the + same side. The spanning label is placed outside the side labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +leftlabels_kw, toplabels_kw, rightlabels_kw, bottomlabels_kw : dict-like, optional + Additional settings used to update the labels with ``text.update()``. +figtitle + Alias for `suptitle`. +suptitle : str, optional + The figure "super" title, centered between the left edge of the leftmost + subplot and the right edge of the rightmost subplot. +suptitlepad : float, default: :rc:`suptitle.pad` + The padding between the super title and the axes content. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +suptitle_kw : optional + Additional settings used to update the super title with ``text.update()``. +includepanels : bool, default: False + Whether to include panels when aligning figure "super titles" along the top + of the subplot grid and when aligning the `spanx` *x* axis labels and + `spany` *y* axis labels along the sides of the subplot grid. +rc_mode : int, optional + The context mode passed to `~ultraplot.config.Configurator.context`. +rc_kw : dict-like, optional + An alternative to passing extra keyword arguments. See below. +**kwargs + Keyword arguments that match the name of an `~ultraplot.config.rc` setting are + passed to `ultraplot.config.Configurator.context` and used to update the axes. + If the setting name has "dots" you can simply omit the dots. For example, + ``abc='A.'`` modifies the :rcraw:`abc` setting, ``titleloc='left'`` modifies the + :rcraw:`title.loc` setting, ``gridminor=True`` modifies the :rcraw:`gridminor` + setting, and ``gridbelow=True`` modifies the :rcraw:`grid.below` setting. Many + of the keyword arguments documented above are internally applied by retrieving + settings passed to `~ultraplot.config.Configurator.context`. + +See also +-------- +ultraplot.axes.PolarAxes.format +ultraplot.axes.Axes.format""" + ... diff --git a/ultraplot/axes/three.pyi b/ultraplot/axes/three.pyi new file mode 100644 index 000000000..8c6de8291 --- /dev/null +++ b/ultraplot/axes/three.pyi @@ -0,0 +1,40 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +The "3D" axes class. +""" +from _typeshed import Incomplete +from . import base, shared +try: + from mpl_toolkits.mplot3d import Axes3D +except ImportError: + Axes3D = object + +class ThreeAxes(shared._SharedAxes, base.Axes, Axes3D): + """ + Simple mix-in of `ultraplot.axes.Axes` with `~mpl_toolkits.mplot3d.axes3d.Axes3D`. + + Important + --------- + Note that this subclass does *not* implement the :class:`~ultraplot.axes.PlotAxes` + plotting overrides. This axes subclass can be used by passing ``proj='3d'`` or + ``proj='three'`` to axes-creation commands like `~ultraplot.figure.Figure.add_axes`, + `~ultraplot.figure.Figure.add_subplot`, and `~ultraplot.figure.Figure.subplots`. + """ + _name = 'three' + _name_aliases = ('3d',) + + def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: + ... + + def graph(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Draw network graphs on 3D projections.""" + ... + + def draw(self, renderer: Incomplete) -> None: + """Draw while suppressing exact surfaces replaced by navigation proxies.""" + ... + + def plot_surface(self, X: Incomplete, Y: Incomplete, Z: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot a surface and register a lazy private interaction preview.""" + ... diff --git a/ultraplot/colorbar.pyi b/ultraplot/colorbar.pyi new file mode 100644 index 000000000..06ad52294 --- /dev/null +++ b/ultraplot/colorbar.pyi @@ -0,0 +1,101 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +from _typeshed import Incomplete +from dataclasses import dataclass +from typing import Any, Iterable, MutableMapping, Optional, Tuple, Union +from numbers import Number +import numpy as np +import matplotlib.axes as maxes +import matplotlib.cm as mcm +import matplotlib.colorbar as mcolorbar +import matplotlib.colors as mcolors +import matplotlib.contour as mcontour +import matplotlib.figure as mfigure +import matplotlib.ticker as mticker +import matplotlib.offsetbox as moffsetbox +import matplotlib.patches as mpatches +import matplotlib.transforms as mtransforms +import matplotlib.text as mtext +from packaging import version +from . import constructor, colors as pcolors +from .internals import _not_none, _pop_params, guides, warnings +from .config import rc, _version_mpl +from .ultralayout import KIWI_AVAILABLE, ColorbarLayoutSolver +from . import ticker as pticker +from .utils import units +ColorbarLabelKw = dict[str, Any] +ColorbarTickKw = dict[str, Any] + +@dataclass(frozen=True) +class _TextKw: + kw_label: ColorbarLabelKw + kw_ticklabels: ColorbarTickKw + +class UltraColorbar: + """ + Centralized colorbar builder for axes. + """ + + def __init__(self, axes: maxes.Axes) -> None: + ... + + def add(self, mappable: Any, values: Optional[Iterable[float]]=None, *, loc: Optional[str]=None, align: Optional[str]=None, space: Optional[Union[float, str]]=None, pad: Optional[Union[float, str]]=None, width: Optional[Union[float, str]]=None, length: Optional[Union[float, str]]=None, span: Optional[Union[int, Tuple[int, int]]]=None, row: Optional[int]=None, col: Optional[int]=None, rows: Optional[Union[int, Tuple[int, int]]]=None, cols: Optional[Union[int, Tuple[int, int]]]=None, shrink: Optional[Union[float, str]]=None, label: Optional[str]=None, title: Optional[str]=None, reverse: bool=False, rotation: Optional[float]=None, grid: Optional[bool]=None, edges: Optional[bool]=None, drawedges: Optional[bool]=None, extend: Optional[str]=None, extendsize: Optional[Union[float, str]]=None, extendfrac: Optional[float]=None, ticks: Optional[Iterable[float]]=None, locator: Optional[Any]=None, locator_kw: Optional[dict[str, Any]]=None, format: Optional[str]=None, formatter: Optional[Any]=None, ticklabels: Optional[Iterable[str]]=None, formatter_kw: Optional[dict[str, Any]]=None, minorticks: Optional[bool]=None, minorlocator: Optional[Any]=None, minorlocator_kw: Optional[dict[str, Any]]=None, tickminor: Optional[bool]=None, ticklen: Optional[Union[float, str]]=None, ticklenratio: Optional[float]=None, tickdir: Optional[str]=None, tickdirection: Optional[str]=None, tickwidth: Optional[Union[float, str]]=None, tickwidthratio: Optional[float]=None, ticklabelsize: Optional[float]=None, ticklabelweight: Optional[str]=None, ticklabelcolor: Optional[str]=None, labelloc: Optional[str]=None, labellocation: Optional[str]=None, labelsize: Optional[float]=None, labelweight: Optional[str]=None, labelcolor: Optional[str]=None, c: Optional[str]=None, color: Optional[str]=None, lw: Optional[Union[float, str]]=None, linewidth: Optional[Union[float, str]]=None, edgefix: Optional[bool]=None, rasterized: Optional[bool]=None, frame: Optional[bool]=None, frameon: Optional[bool]=None, outline: Union[bool, None]=None, labelrotation: Optional[Union[str, float]]=None, center_levels: Optional[bool]=None, **kwargs: Incomplete) -> mcolorbar.Colorbar: + """The driver function for adding axes colorbars.""" + ... + +def _build_label_tick_kwargs(*, labelsize: Optional[float], labelweight: Optional[str], labelcolor: Optional[str], ticklabelsize: Optional[float], ticklabelweight: Optional[str], ticklabelcolor: Optional[str], rotation: Optional[float]) -> _TextKw: + ... + +def _resolve_mappable(mappable: Any, values: Optional[Iterable[float]], cax: maxes.Axes, kwargs: dict[str, Any]) -> tuple[mcm.ScalarMappable, dict[str, Any]]: + ... + +def _resolve_extendfrac(*, extendsize: Optional[Union[float, str]], extendfrac: Optional[float], cax: maxes.Axes, vertical: bool) -> float: + ... + +def _resolve_locators(*, mappable: mcm.ScalarMappable, formatter: Optional[Any], formatter_kw: dict[str, Any], locator: Optional[Any], locator_kw: dict[str, Any], minorlocator: Optional[Any], minorlocator_kw: dict[str, Any], tickminor: Optional[bool], vertical: bool) -> tuple[mcolors.Normalize, mticker.Formatter, Optional[Any], Optional[Any], bool]: + ... + +def _get_axis_for(labelloc: Optional[str], loc: Optional[str], *, ax: maxes.Axes, orientation: Optional[str]) -> maxes.Axes: + """Helper function to determine the axis for a label. +Particularly used for colorbars but can be used for other purposes""" + ... + +def _determine_label_rotation(labelrotation: Union[str, Number], labelloc: str, orientation: str, kw_label: MutableMapping) -> None: + """Note we update kw_label in place.""" + ... + +def _resolve_label_rotation(labelrotation: str | Number, *, labelloc: str, orientation: str) -> float: + ... + +def _measure_label_points(label: str, rotation: float, fontsize: float, figure: Incomplete) -> Optional[Tuple[float, float]]: + ... + +def _measure_text_artist_points(text: mtext.Text, figure: Incomplete) -> Optional[Tuple[float, float]]: + ... + +def _measure_ticklabel_extent_points(axis: Incomplete, figure: Incomplete) -> Optional[Tuple[float, float]]: + ... + +def _measure_text_overhang_axes(text: mtext.Text, axes: Incomplete) -> Optional[Tuple[float, float, float, float]]: + ... + +def _measure_ticklabel_overhang_axes(axis: Incomplete, axes: Incomplete) -> Optional[Tuple[float, float, float, float]]: + ... + +def _get_colorbar_long_axis(colorbar: mcolorbar.Colorbar) -> Incomplete: + ... + +def _register_inset_colorbar_reflow(fig: mfigure.Figure) -> None: + ... + +def _solve_inset_colorbar_bounds(*, axes: maxes.Axes, loc: str, orientation: str, length: float, width: float, xpad: float, ypad: float, ticklocation: str, labelloc: Optional[str], label: Optional[str], labelrotation: Optional[Union[str, float]], tick_fontsize: float, label_fontsize: float) -> Tuple[list[float], list[float]]: + ... + +def _legacy_inset_colorbar_bounds(*, axes: maxes.Axes, loc: str, orientation: str, length: float, width: float, xpad: float, ypad: float, ticklocation: str, labelloc: Optional[str], label: Optional[str], labelrotation: Optional[Union[str, float]], tick_fontsize: float, label_fontsize: float) -> Tuple[list[float], list[float]]: + ... + +def _apply_inset_colorbar_layout(axes: maxes.Axes, *, bounds_inset: list[float], bounds_frame: list[float], frame: Optional[mpatches.FancyBboxPatch]) -> None: + ... + +def _reflow_inset_colorbar_frame(colorbar: mcolorbar.Colorbar, *, labelloc: Optional[str], ticklen: float, renderer: Incomplete=None) -> None: + ... diff --git a/ultraplot/colors.pyi b/ultraplot/colors.pyi new file mode 100644 index 000000000..0bd6157b7 --- /dev/null +++ b/ultraplot/colors.pyi @@ -0,0 +1,1385 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Various colormap classes and colormap normalization classes. +""" +from _typeshed import Incomplete +import functools +import itertools +import json +import os +import re +from collections.abc import MutableMapping +from numbers import Integral, Number +from xml.etree import ElementTree +import matplotlib as mpl +import matplotlib.cm as mcm +import matplotlib.colors as mcolors +import numpy as np +import numpy.ma as ma +from .config import rc + +def _cycle_handler(value: Incomplete) -> Incomplete: + """Handler for the 'cycle' rc setting.""" + ... +from .internals import _kwargs_to_args, _not_none, _pop_props, docstring, ic, inputs, warnings +from .utils import set_alpha, to_hex, to_rgb, to_rgba, to_xyz, to_xyza +try: + from typing import override +except: + from typing_extensions import override +__all__ = ['DiscreteColormap', 'ContinuousColormap', 'PerceptualColormap', 'DiscreteNorm', 'DivergingNorm', 'SegmentedNorm', 'ColorDatabase', 'ColormapDatabase'] +DEFAULT_NAME = '_no_name' +DEFAULT_SPACE = 'hsl' +_regex_hex = '#(?:[0-9a-fA-F]{3,4}){2}' +REGEX_HEX_MULTI = re.compile(_regex_hex) +REGEX_HEX_SINGLE = ... +REGEX_ADJUST = re.compile('\\A(light|dark|medium|pale|charcoal)?\\s*(gr[ea]y[0-9]?)?\\Z') +CMAPS_CYCLIC = ... +CMAPS_DIVERGING = ... +CMAPS_REMOVED = {'Blue0': '0.6.0', 'Cool': '0.6.0', 'Warm': '0.6.0', 'Hot': '0.6.0', 'Floral': '0.6.0', 'Contrast': '0.6.0', 'Sharp': '0.6.0', 'Viz': '0.6.0'} +CMAPS_RENAMED = {'GrayCycle': ('MonoCycle', '0.6.0'), 'Blue1': ('Blues1', '0.7.0'), 'Blue2': ('Blues2', '0.7.0'), 'Blue3': ('Blues3', '0.7.0'), 'Blue4': ('Blues4', '0.7.0'), 'Blue5': ('Blues5', '0.7.0'), 'Blue6': ('Blues6', '0.7.0'), 'Blue7': ('Blues7', '0.7.0'), 'Blue8': ('Blues8', '0.7.0'), 'Blue9': ('Blues9', '0.7.0'), 'Green1': ('Greens1', '0.7.0'), 'Green2': ('Greens2', '0.7.0'), 'Green3': ('Greens3', '0.7.0'), 'Green4': ('Greens4', '0.7.0'), 'Green5': ('Greens5', '0.7.0'), 'Green6': ('Greens6', '0.7.0'), 'Green7': ('Greens7', '0.7.0'), 'Green8': ('Greens8', '0.7.0'), 'Orange1': ('Yellows1', '0.7.0'), 'Orange2': ('Yellows2', '0.7.0'), 'Orange3': ('Yellows3', '0.7.0'), 'Orange4': ('Oranges2', '0.7.0'), 'Orange5': ('Oranges1', '0.7.0'), 'Orange6': ('Oranges3', '0.7.0'), 'Orange7': ('Oranges4', '0.7.0'), 'Orange8': ('Yellows4', '0.7.0'), 'Brown1': ('Browns1', '0.7.0'), 'Brown2': ('Browns2', '0.7.0'), 'Brown3': ('Browns3', '0.7.0'), 'Brown4': ('Browns4', '0.7.0'), 'Brown5': ('Browns5', '0.7.0'), 'Brown6': ('Browns6', '0.7.0'), 'Brown7': ('Browns7', '0.7.0'), 'Brown8': ('Browns8', '0.7.0'), 'Brown9': ('Browns9', '0.7.0'), 'RedPurple1': ('Reds1', '0.7.0'), 'RedPurple2': ('Reds2', '0.7.0'), 'RedPurple3': ('Reds3', '0.7.0'), 'RedPurple4': ('Reds4', '0.7.0'), 'RedPurple5': ('Reds5', '0.7.0'), 'RedPurple6': ('Purples1', '0.7.0'), 'RedPurple7': ('Purples2', '0.7.0'), 'RedPurple8': ('Purples3', '0.7.0')} +COLORS_OPEN = {} +COLORS_XKCD = {} +COLORS_KEEP = ... +COLORS_REMOVE = ('shit', 'poop', 'poo', 'pee', 'piss', 'puke', 'vomit', 'snot', 'booger', 'bile', 'diarrhea', 'icky', 'sickly') +COLORS_REPLACE = (('/', ' '), ("'s", 's'), ('egg blue', 'egg'), ('grey', 'gray'), ('ochre', 'ocher'), ('forrest', 'forest'), ('ocre', 'ocher'), ('kelley', 'kelly'), ('reddish', 'red'), ('purplish', 'purple'), ('pinkish', 'pink'), ('yellowish', 'yellow'), ('bluish', 'blue'), ('greyish', 'grey'), ('ish', ''), ('bluey', 'blue'), ('greeny', 'green'), ('reddy', 'red'), ('pinky', 'pink'), ('purply', 'purple'), ('purpley', 'purple'), ('yellowy', 'yellow'), ('orangey', 'orange'), ('browny', 'brown'), ('minty', 'mint'), ('grassy', 'grass'), ('mossy', 'moss'), ('dusky', 'dusk'), ('rusty', 'rust'), ('muddy', 'mud'), ('sandy', 'sand'), ('leafy', 'leaf'), ('dusty', 'dust'), ('dirty', 'dirt'), ('peachy', 'peach'), ('stormy', 'storm'), ('cloudy', 'cloud'), ('grayblue', 'gray blue'), ('bluegray', 'gray blue'), ('lightblue', 'light blue'), ('yellowgreen', 'yellow green'), ('yelloworange', 'yellow orange')) +_N_docstring = ... +_alpha_docstring = ... +_cyclic_docstring = ... +_gamma_docstring = ... +_space_docstring = ... +_name_docstring = ... +_ratios_docstring = ... +_from_list_docstring = ... + +def _clip_colors(colors: Incomplete, clip: Incomplete=True, gray: Incomplete=0.2, warn: Incomplete=False) -> Incomplete: + """Clip impossible colors rendered in an HSL-to-RGB colorspace +conversion. Used by `PerceptualColormap`. + +Parameters +---------- +colors : sequence of 3-tuple + The RGB colors. +clip : bool, optional + If `clip` is ``True`` (the default), RGB channel values >1 are + clipped to 1. Otherwise, the color is masked out as gray. +gray : float, optional + The identical RGB channel values (gray color) to be used if + `clip` is ``True``. +warn : bool, optional + Whether to issue warning when colors are clipped.""" + ... + +def _get_channel(color: Incomplete, channel: Incomplete, space: Incomplete='hcl') -> Incomplete: + """Get the hue, saturation, or luminance channel value from the input color. The +color name `color` can optionally be a string with the format ``'color+x'`` +or ``'color-x'``, where `x` is the offset from the channel value. + +Parameters +---------- +color : color-spec + The color. Sanitized with `to_rgba`. +channel : optional + The HCL channel to be retrieved. +space : optional + The colorspace for the corresponding channel value. + +Returns +------- +value : float + The channel value.""" + ... + +def _make_segment_data(values: Incomplete, coords: Incomplete=None, ratios: Incomplete=None) -> Incomplete: + """Return a segmentdata array or callable given the input colors +and coordinates. + +Parameters +---------- +values : sequence of float + The channel values. +coords : sequence of float, optional + The segment coordinates. +ratios : sequence of float, optional + The relative length of each segment transition.""" + ... + +def _make_lookup_table(N: Incomplete, data: Incomplete, gamma: Incomplete=1.0, inverse: Incomplete=False) -> Incomplete: + """Generate lookup tables of HSL values given specified gradations. Similar to +`~matplotlib.colors.makeMappingArray` but permits *circular* hue gradations, +disables clipping of out-of-bounds values, and uses fancier "gamma" scaling. + +Parameters +---------- +N : int + Number of points in the colormap lookup table. +data : array-like + Sequence of `(x, y_0, y_1)` tuples specifying channel jumps + (from `y_0` to `y_1`) and `x` coordinate of those jumps + (ranges between 0 and 1). See `~matplotlib.colors.LinearSegmentedColormap`. +gamma : float or sequence of float, optional + To obtain channel values between coordinates `x_i` and `x_{i+1}` + in rows `i` and `i+1` of `data` we use the formula: + + .. math:: + + y = y_{1,i} + w_i^{\\gamma_i}*(y_{0,i+1} - y_{1,i}) + + where `\\gamma_i` corresponds to `gamma` and the weight `w_i` ranges from + 0 to 1 between rows `i` and ``i+1``. If `gamma` is float, it applies + to every transition. Otherwise, its length must equal ``data.shape[0]-1``. + + This is similar to the `matplotlib.colors.makeMappingArray` `gamma` except + it controls the weighting for transitions *between* each segment data + coordinate rather than the coordinates themselves. This makes more sense + for `PerceptualColormap`\\ s because they usually contain just a + handful of transitions representing chained segments. +inverse : bool, optional + If ``True``, `w_i^{\\gamma_i}` is replaced with `1 - (1 - w_i)^{\\gamma_i}` -- + that is, when `gamma` is greater than 1, this weights colors toward *higher* + channel values instead of lower channel values. + + This is implemented in case we want to apply *equal* "gamma scaling" + to different HSL channels in different directions. Usually, this + is done to weight low data values with higher luminance *and* lower + saturation, thereby emphasizing "extreme" data values.""" + ... + +def _load_colors(path: Incomplete, warn_on_failure: Incomplete=True) -> Incomplete: + """Read colors from the input file. + +Parameters +---------- +warn_on_failure : bool, optional + If ``True``, issue a warning when loading fails instead of raising an error.""" + ... + +def _standardize_colors(input: Incomplete, space: Incomplete, margin: Incomplete) -> Incomplete: + """Standardize the input colors. + +Parameters +---------- +input : dict + The colors. +space : optional + The colorspace used to filter colors. +margin : optional + The proportional margin required for unique colors (e.g. 0.1 + is 36 hue units, 10 saturation units, 10 luminance units).""" + ... + +class _Colormap(object): + """ + Mixin class used to add some helper methods. + """ + + def _get_data(self, ext: Incomplete, alpha: Incomplete=True) -> Incomplete: + """Return a string containing the colormap colors for saving. + +Parameters +---------- +ext : {'hex', 'txt', 'rgb'} + The filename extension. +alpha : bool, optional + Whether to include an opacity column.""" + ... + + def _make_name(self, suffix: Incomplete=None) -> Incomplete: + """Generate a default colormap name. Do not append more than one +leading underscore or more than one identical suffix.""" + ... + + def _parse_path(self, path: Incomplete, ext: Incomplete=None, subfolder: Incomplete=None) -> Incomplete: + """Parse the user input path. + +Parameters +---------- +path : path-like, optional + The file path. +ext : str + The default extension. +subfolder : str, optional + The subfolder.""" + ... + + @staticmethod + def _pop_args(*args: Incomplete, names: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Pop the name as a first positional argument or keyword argument. +Supports matplotlib-style ``Colormap(name, data, N)`` input +algongside more intuitive ``Colormap(data, name, N)`` input.""" + ... + + @classmethod + def _from_file(cls, path: Incomplete, warn_on_failure: Incomplete=False) -> Incomplete: + """Read generalized colormap and color cycle files.""" + ... + +class ContinuousColormap(mcolors.LinearSegmentedColormap, _Colormap): + """ + Replacement for `~matplotlib.colors.LinearSegmentedColormap`. + """ + + def __str__(self) -> str: + ... + + def __repr__(self) -> str: + ... + + def __init__(self, *args: Incomplete, gamma: Incomplete=1, alpha: Incomplete=None, cyclic: Incomplete=False, **kwargs: Incomplete) -> None: + """Parameters +---------- +segmentdata : dict-like + Dictionary containing the keys ``'red'``, ``'green'``, ``'blue'``, and + (optionally) ``'alpha'``. The shorthands ``'r'``, ``'g'``, ``'b'``, + and ``'a'`` are also acceptable. The key values can be callable + functions that return channel values given a colormap index, or + 3-column arrays indicating the coordinates and channel transitions. See + `matplotlib.colors.LinearSegmentedColormap` for a detailed explanation. +name : str, default: '_no_name' + The colormap name. This can also be passed as the first + positional string argument. +N : int, default: :rc:`image.lut` + Number of points in the colormap lookup table. +gamma : float, optional + Gamma scaling used for the *x* coordinates. +alpha : float, optional + The opacity for the entire colormap. This overrides + the input opacities. +cyclic : bool, optional + Whether the colormap is cyclic. If ``True``, this changes how the leftmost + and rightmost color levels are selected, and `extend` can only be + ``'neither'`` (a warning will be issued otherwise). + +Other parameters +---------------- +**kwargs + Passed to `matplotlib.colors.LinearSegmentedColormap`. + +See also +-------- +DiscreteColormap +matplotlib.colors.LinearSegmentedColormap +ultraplot.constructor.Colormap""" + ... + + def append(self, *args: Incomplete, ratios: Incomplete=None, name: Incomplete=None, N: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Return the concatenation of this colormap with the +input colormaps. + +Parameters +---------- +*args + Instances of `ContinuousColormap`. +ratios : sequence of float, optional + Relative extent of each component colormap in the + merged colormap. Length must equal ``len(args) + 1``. + For example, ``cmap1.append(cmap2, ratios=(2, 1))`` generates + a colormap with the left two-thrids containing colors from + ``cmap1`` and the right one-third containing colors from ``cmap2``. +name : str, optional + The colormap name. Default is to merge each name with underscores and + prepend a leading underscore, for example ``_name1_name2``. +N : int, optional + The number of points in the colormap lookup table. Default is + to sum the length of each lookup table. + +Other parameters +---------------- +**kwargs + Passed to `ContinuousColormap.copy` + or `PerceptualColormap.copy`. + +Returns +------- +ContinuousColormap + The colormap. + +See also +-------- +DiscreteColormap.append""" + ... + + def cut(self, cut: Incomplete=None, name: Incomplete=None, left: Incomplete=None, right: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Return a version of the colormap with the center "cut out". +This is great for making the transition from "negative" to "positive" +in a diverging colormap more distinct. + +Parameters +---------- +cut : float, optional + The proportion to cut from the center of the colormap. For example, + ``cut=0.1`` cuts the central 10%%, or ``cut=-0.1`` fills the central 10%% + of the colormap with the current central color (usually white). +name : str, default: '_name_copy' + The new colormap name. +left, right : float, default: 0, 1 + The colormap indices for the "leftmost" and "rightmost" + colors. See `~ContinuousColormap.truncate` for details. +right : float, optional + The colormap index for the new "rightmost" color. Must fall between + +Other parameters +---------------- +**kwargs + Passed to `ContinuousColormap.copy` or `PerceptualColormap.copy`. + +Returns +------- +ContinuousColormap + The colormap. + +See also +-------- +ContinuousColormap.truncate +DiscreteColormap.truncate""" + ... + + def reversed(self, name: Incomplete=None, **kwargs: Incomplete) -> ContinuousColormap: + """Return a reversed copy of the colormap. + +Parameters +---------- +name : str, default: '_name_r' + The new colormap name. + +Other parameters +---------------- +**kwargs + Passed to `ContinuousColormap.copy` + or `PerceptualColormap.copy`. + +See also +-------- +matplotlib.colors.LinearSegmentedColormap.reversed""" + ... + + def save(self, path: Incomplete=None, alpha: Incomplete=True) -> None: + """Save the colormap data to a file. + +Parameters +---------- +path : path-like, optional + The output filename. If not provided, the colormap is saved in the + ``cmaps`` subfolder in :func:`~ultraplot.config.Configurator.user_folder` + under the filename ``name.json`` (where ``name`` is the colormap + name). Valid extensions are shown in the below table. + + =================== ========================================== + Extension Description + =================== ========================================== + ``.json`` JSON database of the channel segment data. + ``.hex`` Comma-delimited list of HEX strings. + ``.rgb``, ``.txt`` 3-4 column table of channel values. + =================== ========================================== + +alpha : bool, optional + Whether to include an opacity column for ``.rgb`` + and ``.txt`` files. + +See also +-------- +DiscreteColormap.save""" + ... + + def set_alpha(self, alpha: Incomplete, coords: Incomplete=None, ratios: Incomplete=None) -> None: + """Set the opacity for the entire colormap or set up an opacity gradation. + +Parameters +---------- +alpha : float or sequence of float + If float, this is the opacity for the entire colormap. If sequence of + float, the colormap traverses these opacity values. +coords : sequence of float, optional + Colormap coordinates for the opacity values. The first and last + coordinates must be ``0`` and ``1``. If `alpha` is not scalar, the + default coordinates are ``np.linspace(0, 1, len(alpha))``. +ratios : sequence of float, optional + Relative extent of each opacity transition segment. Length should + equal ``len(alpha) + 1``. For example + ``cmap.set_alpha((1, 1, 0), ratios=(2, 1))`` creates a transtion from + 100 percent to 0 percent opacity in the right *third* of the colormap. + +See also +-------- +DiscreteColormap.set_alpha""" + ... + + def set_cyclic(self, b: Incomplete) -> None: + """Set whether this colormap is "cyclic". See `ContinuousColormap` for details.""" + ... + + def shifted(self, shift: Incomplete=180, name: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Return a cyclicaly shifted version of the colormap. If the colormap +cyclic property is set to ``False`` a warning will be raised. + +Parameters +---------- +shift : float, default: 180 + The number of degrees to shift, out of 360 degrees. +name : str, default: '_name_s' + The new colormap name. + +Other parameters +---------------- +**kwargs + Passed to `ContinuousColormap.copy` or `PerceptualColormap.copy`. + +See also +-------- +DiscreteColormap.shifted""" + ... + + def truncate(self, left: Incomplete=None, right: Incomplete=None, name: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Return a truncated version of the colormap. + +Parameters +---------- +left : float, default: 0 + The colormap index for the new "leftmost" color. Must fall between ``0`` + and ``1``. For example, ``left=0.1`` cuts the leftmost 10%% of the colors. +right : float, default: 1 + The colormap index for the new "rightmost" color. Must fall between ``0`` + and ``1``. For example, ``right=0.9`` cuts the leftmost 10%% of the colors. +name : str, default: '_name_copy' + The new colormap name. + +Other parameters +---------------- +**kwargs + Passed to `ContinuousColormap.copy` + or `PerceptualColormap.copy`. + +See also +-------- +DiscreteColormap.truncate""" + ... + + def copy(self, name: Incomplete=None, segmentdata: Incomplete=None, N: Incomplete=None, *, alpha: Incomplete=None, gamma: Incomplete=None, cyclic: Incomplete=None) -> ContinuousColormap: + """Return a new colormap with relevant properties copied from this one +if they were not provided as keyword arguments. + +Parameters +---------- +name : str, default: '_name_copy' + The new colormap name. +segmentdata, N, alpha, gamma, cyclic : optional + See `ContinuousColormap`. If not provided, these are copied + from the current colormap. + +See also +-------- +DiscreteColormap.copy +PerceptualColormap.copy""" + ... + + def to_discrete(self, samples: Incomplete=10, name: Incomplete=None, **kwargs: Incomplete) -> DiscreteColormap: + """Convert the `ContinuousColormap` to a `DiscreteColormap` by drawing +samples from the colormap. + +Parameters +---------- +samples : int or sequence of float, optional + If integer, draw samples at the colormap coordinates + ``np.linspace(0, 1, samples)``. If sequence of float, + draw samples at the specified points. +name : str, default: '_name_copy' + The new colormap name. + +Other parameters +---------------- +**kwargs + Passed to `DiscreteColormap`. + +See also +-------- +PerceptualColormap.to_continuous""" + ... + + @classmethod + def from_file(cls, path: Incomplete, *, warn_on_failure: Incomplete=False) -> Incomplete: + """Load colormap from a file. + +Parameters +---------- +path : path-like + The file path. Valid file extensions are shown in the below table. + + =================== ========================================== + Extension Description + =================== ========================================== + ``.json`` JSON database of the channel segment data. + ``.hex`` Comma-delimited list of HEX strings. + ``.rgb``, ``.txt`` 3-4 column table of channel values. + =================== ========================================== + +warn_on_failure : bool, optional + If ``True``, issue a warning when loading fails instead of + raising an error. + +See also +-------- +DiscreteColormap.from_file""" + ... + + @classmethod + def from_list(cls, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Make a `ContinuousColormap` from a sequence of colors. + +Parameters +---------- +colors : sequence of color-spec or tuple + If a sequence of RGB[A] tuples or color strings, the colormap + transitions evenly from ``colors[0]`` at the left-hand side + to ``colors[-1]`` at the right-hand side. + + If a sequence of (float, color-spec) tuples, the float values are the + coordinate of each transition and must range from 0 to 1. This + can be used to divide the colormap range unevenly. +name : str, default: '_no_name' + The colormap name. This can also be passed as the first + positional string argument. +ratios : sequence of float, optional + Relative extents of each color transition. Must have length + ``len(colors) - 1``. Larger numbers indicate a slower + transition, smaller numbers indicate a faster transition. + For example, ``('red', 'blue', 'green')`` with ``ratios=(2, 1)`` + creates a colormap with the transition from red to blue taking + *twice as long* as the transition from blue to green. + +Other parameters +---------------- +**kwargs + Passed to `ContinuousColormap`. + +Returns +------- +ContinuousColormap + The colormap. + +See also +-------- +matplotlib.colors.LinearSegmentedColormap.from_list +PerceptualColormap.from_list""" + ... + +class DiscreteColormap(mcolors.ListedColormap, _Colormap): + """ + Replacement for `~matplotlib.colors.ListedColormap`. + """ + + def __str__(self) -> str: + ... + + def __repr__(self) -> str: + ... + + @property + def monochrome(self) -> bool: + """Whether every color is identical, normalized to a Python boolean.""" + ... + + @monochrome.setter + def monochrome(self, value: Incomplete) -> None: + ... + + def __init__(self, colors: Incomplete, name: Incomplete=None, N: Incomplete=None, alpha: Incomplete=None, **kwargs: Incomplete) -> None: + """Parameters +---------- +colors : sequence of color-spec, optional + The colormap colors. +name : str, default: '_no_name' + The colormap name. +N : int, default: ``len(colors)`` + The number of levels. The color list is truncated or wrapped + to match this length. +alpha : float, optional + The opacity for the colormap colors. This overrides the + input color opacities. + +Other parameters +---------------- +**kwargs + Passed to `~matplotlib.colors.ListedColormap`. + +See also +-------- +ContinuousColormap +matplotlib.colors.ListedColormap +ultraplot.constructor.Colormap""" + ... + + def append(self, *args: Incomplete, name: Incomplete=None, N: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Append arbitrary colormaps onto this colormap. + +Parameters +---------- +*args + Instances of `DiscreteColormap`. +name : str, optional + The new colormap name. Default is to merge each name with underscores and + prepend a leading underscore, for example ``_name1_name2``. +N : int, optional + The number of points in the colormap lookup table. Default is + the number of colors in the concatenated lists. + +Other parameters +---------------- +**kwargs + Passed to `~DiscreteColormap.copy`. + +See also +-------- +ContinuousColormap.append""" + ... + + def save(self, path: Incomplete=None, alpha: Incomplete=True) -> None: + """Save the colormap data to a file. + +Parameters +---------- +path : path-like, optional + The output filename. If not provided, the colormap is saved in the + ``cycles`` subfolder in :func:`~ultraplot.config.Configurator.user_folder` + under the filename ``name.hex`` (where ``name`` is the color cycle + name). Valid extensions are described in the below table. + + ================== ========================================== + Extension Description + ================== ========================================== + ``.hex`` Comma-delimited list of HEX strings. + ``.rgb``, ``.txt`` 3-4 column table of channel values. + ================== ========================================== + +alpha : bool, optional + Whether to include an opacity column for ``.rgb`` + and ``.txt`` files. + +See also +-------- +ContinuousColormap.save""" + ... + + def set_alpha(self, alpha: Incomplete) -> None: + """Set the opacity for the entire colormap. + +Parameters +---------- +alpha : float + The opacity. + +See also +-------- +ContinuousColormap.set_alpha""" + ... + + def reversed(self, name: Incomplete=None, **kwargs: Incomplete) -> DiscreteColormap: + """Return a reversed version of the colormap. + +Parameters +---------- +name : str, default: '_name_r' + The new colormap name. + +Other parameters +---------------- +**kwargs + Passed to `DiscreteColormap.copy` + +See also +-------- +matplotlib.colors.ListedColormap.reversed""" + ... + + def shifted(self, shift: Incomplete=1, name: Incomplete=None) -> Incomplete: + """Return a cyclically shifted version of the colormap. + +Parameters +---------- +shift : float, default: 1 + The number of list indices to shift. +name : str, eefault: '_name_s' + The new colormap name. + +See also +-------- +ContinuousColormap.shifted""" + ... + + def truncate(self, left: Incomplete=None, right: Incomplete=None, name: Incomplete=None) -> Incomplete: + """Return a truncated version of the colormap. + +Parameters +---------- +left : float, default: None + The colormap index for the new "leftmost" color. Must fall between ``0`` + and ``self.N``. For example, ``left=2`` drops the first two colors. +right : float, default: None + The colormap index for the new "rightmost" color. Must fall between ``0`` + and ``self.N``. For example, ``right=4`` keeps the first four colors. +name : str, default: '_name_copy' + The new colormap name. + +See also +-------- +ContinuousColormap.truncate""" + ... + + def copy(self, colors: Incomplete=None, name: Incomplete=None, N: Incomplete=None, *, alpha: Incomplete=None) -> DiscreteColormap: + """Return a new colormap with relevant properties copied from this one +if they were not provided as keyword arguments. + +Parameters +---------- +name : str, default: '_name_copy' + The new colormap name. +colors, N, alpha : optional + See `DiscreteColormap`. If not provided, + these are copied from the current colormap. + +See also +-------- +ContinuousColormap.copy +PerceptualColormap.copy""" + ... + + @classmethod + def from_file(cls, path: Incomplete, *, warn_on_failure: Incomplete=False) -> Incomplete: + """Load color cycle from a file. + +Parameters +---------- +path : path-like + The file path. Valid file extensions are shown in the below table. + + ================== ========================================== + Extension Description + ================== ========================================== + ``.hex`` Comma-delimited list of HEX strings. + ``.rgb``, ``.txt`` 3-4 column table of channel values. + ================== ========================================== + +warn_on_failure : bool, optional + If ``True``, issue a warning when loading fails instead of + raising an error. + +See also +-------- +ContinuousColormap.from_file""" + ... + +class PerceptualColormap(ContinuousColormap): + """ + A `ContinuousColormap` with linear transitions across hue, saturation, + and luminance rather than red, blue, and green. + """ + + def __init__(self, *args: Incomplete, space: Incomplete=None, clip: Incomplete=True, gamma: Incomplete=None, gamma1: Incomplete=None, gamma2: Incomplete=None, **kwargs: Incomplete) -> None: + """Parameters +---------- +segmentdata : dict-like + Dictionary containing the keys ``'hue'``, ``'saturation'``, + ``'luminance'``, and (optionally) ``'alpha'``. The key ``'chroma'`` is + treated as a synonym for ``'saturation'``. The shorthands ``'h'``, + ``'s'``, ``'l'``, ``'a'``, and ``'c'`` are also acceptable. The key + values can be callable functions that return channel values given a + colormap index, or 3-column arrays indicating the coordinates and + channel transitions. See `~matplotlib.colors.LinearSegmentedColormap` + for a more detailed explanation. +name : str, default: '_no_name' + The colormap name. This can also be passed as the first + positional string argument. +N : int, default: :rc:`image.lut` + Number of points in the colormap lookup table. +space : {'hsl', 'hpl', 'hcl', 'hsv'}, optional + The hue, saturation, luminance-style colorspace to use for interpreting + the channels. See `this page `__ for + a full description. +clip : bool, optional + Whether to "clip" impossible colors (i.e. truncate HCL colors with + RGB channels with values greater than 1) or mask them out as gray. +gamma : float, optional + Set `gamma1` and `gamma2` to this identical value. +gamma1 : float, optional + If greater than 1, make low saturation colors more prominent. If + less than 1, make high saturation colors more prominent. Similar to + the `HCLWizard `_ option. +gamma2 : float, optional + If greater than 1, make high luminance colors more prominent. If + less than 1, make low luminance colors more prominent. Similar to + the `HCLWizard `_ option. +alpha : float, optional + The opacity for the entire colormap. This overrides + the input opacities. +cyclic : bool, optional + Whether the colormap is cyclic. If ``True``, this changes how the leftmost + and rightmost color levels are selected, and `extend` can only be + ``'neither'`` (a warning will be issued otherwise). + +Other parameters +---------------- +**kwargs + Passed to `matploitlib.colors.LinearSegmentedColormap`. + +Example +------- +The below example generates a `PerceptualColormap` from a +`segmentdata` dictionary that uses color names for the hue data, +instead of channel values between ``0`` and ``360``. + +>>> import ultraplot as uplt +>>> data = { +>>> 'h': [[0, 'red', 'red'], [1, 'blue', 'blue']], +>>> 's': [[0, 100, 100], [1, 100, 100]], +>>> 'l': [[0, 100, 100], [1, 20, 20]], +>>> } +>>> cmap = uplt.PerceptualColormap(data) + +See also +-------- +ContinuousColormap +ultraplot.constructor.Colormap""" + ... + + def _init(self) -> None: + """As with `~matplotlib.colors.LinearSegmentedColormap`, but convert +each value in the lookup table from ``self._space`` to RGB.""" + ... + + def set_gamma(self, gamma: Incomplete=None, gamma1: Incomplete=None, gamma2: Incomplete=None) -> None: + """Set the gamma value(s) for the luminance and saturation transitions. + +Parameters +---------- +gamma : float, optional + Set `gamma1` and `gamma2` to this identical value. +gamma1 : float, optional + If greater than 1, make low saturation colors more prominent. If + less than 1, make high saturation colors more prominent. Similar to + the `HCLWizard `_ option. +gamma2 : float, optional + If greater than 1, make high luminance colors more prominent. If + less than 1, make low luminance colors more prominent. Similar to + the `HCLWizard `_ option.""" + ... + + def copy(self, name: Incomplete=None, segmentdata: Incomplete=None, N: Incomplete=None, *, alpha: Incomplete=None, gamma: Incomplete=None, cyclic: Incomplete=None, clip: Incomplete=None, gamma1: Incomplete=None, gamma2: Incomplete=None, space: Incomplete=None) -> PerceptualColormap: + """Return a new colormap with relevant properties copied from this one +if they were not provided as keyword arguments. + +Parameters +---------- +name : str, default: '_name_copy' + The new colormap name. +segmentdata, N, alpha, clip, cyclic, gamma, gamma1, gamma2, space : optional + See `PerceptualColormap`. If not provided, + these are copied from the current colormap. + +See also +-------- +DiscreteColormap.copy +ContinuousColormap.copy""" + ... + + def to_continuous(self, name: Incomplete=None, **kwargs: Incomplete) -> ContinuousColormap: + """Convert the `PerceptualColormap` to a standard `ContinuousColormap`. +This is used to merge such colormaps. + +Parameters +---------- +name : str, default: '_name_copy' + The new colormap name. + +Other parameters +---------------- +**kwargs + Passed to `ContinuousColormap`. + +See also +-------- +ContinuousColormap.to_discrete""" + ... + + @classmethod + def from_color(cls, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Return a simple monochromatic "sequential" colormap that blends from white +or near-white to the input color. + +Parameters +---------- +color : color-spec + RGB tuple, hex string, or named color string. +name : str, default: '_no_name' + The colormap name. This can also be passed as the first + positional string argument. +space : {'hsl', 'hpl', 'hcl', 'hsv'}, optional + The hue, saturation, luminance-style colorspace to use for interpreting + the channels. See `this page `__ for + a full description. +l, s, a, c + Shorthands for `luminance`, `saturation`, `alpha`, and `chroma`. +luminance : float or color-spec, default: 100 + If float, this is the luminance channel strength on the left-hand + side of the colormap. If RGB[A] tuple, hex string, or named color + string, the luminance is inferred from the color. +saturation, alpha : float or color-spec, optional + As with `luminance`, except the default `saturation` and the default + `alpha` are the channel values taken from `color`. +chroma + Alias for `saturation`. + +Other parameters +---------------- +**kwargs + Passed to `PerceptualColormap.from_hsl`. + +Returns +------- +PerceptualColormap + The colormap. + +See also +-------- +PerceptualColormap.from_hsl +PerceptualColormap.from_list""" + ... + + @classmethod + def from_hsl(cls, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Make a `~PerceptualColormap` by specifying the hue, +saturation, and luminance transitions individually. + +Parameters +---------- +space : {'hsl', 'hpl', 'hcl', 'hsv'}, optional + The hue, saturation, luminance-style colorspace to use for interpreting + the channels. See `this page `__ for + a full description. +name : str, default: '_no_name' + The colormap name. This can also be passed as the first + positional string argument. +ratios : sequence of float, optional + Relative extents of each color transition. Must have length + ``len(colors) - 1``. Larger numbers indicate a slower + transition, smaller numbers indicate a faster transition. + For example, ``luminance=(100, 50, 0)`` with ``ratios=(2, 1)`` results + in a colormap with the transition from luminance ``100`` to ``50`` taking + *twice as long* as the transition from luminance ``50`` to ``0``. +h, s, l, a, c + Shorthands for `hue`, `saturation`, `luminance`, `alpha`, and `chroma`. +hue : float or color-spec or sequence, default: 0 + Hue channel value or sequence of values. The shorthand keyword `h` is also + acceptable. Values can be any of the following. + + 1. Numbers, within the range 0 to 360 for hue and 0 to 100 for + saturation and luminance. + 2. Color string names or hex strings, in which case the channel + value for that color is looked up. +saturation : float or color-spec or sequence, default: 50 + As with `hue`, but for the saturation channel. +luminance : float or color-spec or sequence, default: ``(100, 20)`` + As with `hue`, but for the luminance channel. +alpha : float or color-spec or sequence, default: 1 + As with `hue`, but for the alpha (opacity) channel. +chroma + Alias for `saturation`. + +Other parameters +---------------- +**kwargs + Passed to `PerceptualColormap`. + +Returns +------- +PerceptualColormap + The colormap. + +See also +-------- +PerceptualColormap.from_color +PerceptualColormap.from_list""" + ... + + @classmethod + def from_list(cls, *args: Incomplete, adjust_grays: Incomplete=True, **kwargs: Incomplete) -> Incomplete: + """Make a `PerceptualColormap` from a sequence of colors. + +Parameters +---------- +colors : sequence of color-spec or tuple + If a sequence of RGB[A] tuples or color strings, the colormap + transitions evenly from ``colors[0]`` at the left-hand side + to ``colors[-1]`` at the right-hand side. + + If a sequence of (float, color-spec) tuples, the float values are the + coordinate of each transition and must range from 0 to 1. This + can be used to divide the colormap range unevenly. +name : str, default: '_no_name' + The colormap name. This can also be passed as the first + positional string argument. +ratios : sequence of float, optional + Relative extents of each color transition. Must have length + ``len(colors) - 1``. Larger numbers indicate a slower + transition, smaller numbers indicate a faster transition. + For example, ``('red', 'blue', 'green')`` with ``ratios=(2, 1)`` + creates a colormap with the transition from red to blue taking + *twice as long* as the transition from blue to green. +adjust_grays : bool, optional + Whether to adjust the hues of grayscale colors (including ``'white'``, + ``'black'``, and the ``'grayN'`` open-color colors) to the hues of the + preceding and subsequent colors in the sequence. This facilitates the + construction of diverging colormaps with monochromatic segments using + e.g. ``PerceptualColormap.from_list(['blue', 'white', 'red'])``. + +Other parameters +---------------- +**kwargs + Passed to `PerceptualColormap`. + +Returns +------- +PerceptualColormap + The colormap. + +See also +-------- +matplotlib.colors.LinearSegmentedColormap.from_list +ContinuousColormap.from_list +PerceptualColormap.from_color +PerceptualColormap.from_hsl""" + ... + +def _interpolate_scalar(x: Incomplete, x0: Incomplete, x1: Incomplete, y0: Incomplete, y1: Incomplete) -> Incomplete: + """Interpolate between two points.""" + ... + +def _interpolate_extrapolate_vector(xq: Incomplete, x: Incomplete, y: Incomplete) -> Incomplete: + """Interpolate between two vectors. Similar to `numpy.interp` except this +does not truncate out-of-bounds values (i.e. this is reversible).""" + ... + +def _sanitize_levels(levels: Incomplete, minsize: Incomplete=2) -> Incomplete: + """Ensure the levels are monotonic. If they are descending, reverse them.""" + ... + +class DiscreteNorm(mcolors.BoundaryNorm): + """ + Meta-normalizer that discretizes the possible color values returned by + arbitrary continuous normalizers given a sequence of level boundaries. + """ + + def __init__(self, levels: Incomplete, norm: Incomplete=None, unique: Incomplete=None, step: Incomplete=None, clip: Incomplete=False, ticks: Incomplete=None, labels: Incomplete=None) -> None: + """Parameters +---------- +levels : sequence of float + The level boundaries. Must be monotonically increasing or decreasing. + If the latter then `~DiscreteNorm.descending` is set to ``True`` and the + colorbar axis drawn with this normalizer will be reversed. +norm : `~matplotlib.colors.Normalize`, optional + The normalizer used to transform `levels` and data values passed to + `~DiscreteNorm.__call__` before discretization. The ``vmin`` and ``vmax`` + of the normalizer are set to the minimum and maximum values in `levels`. +unique : {'neither', 'both', 'min', 'max'}, optional + Which out-of-bounds regions should be assigned unique colormap colors. + Possible values are equivalent to the `extend` values. Internally, ultraplot + sets this depending on the user-input `extend`, whether the colormap is + cyclic, and whether `~matplotlib.colors.Colormap.set_under` + or `~matplotlib.colors.Colormap.set_over` were called for the colormap. +step : float, optional + The intensity of the transition to out-of-bounds colors as a fraction + of the adjacent step between in-bounds colors. Internally, ultraplot sets + this to ``0.5`` for cyclic colormaps and ``1`` for all other colormaps. + This only has an effect on lower colors when `unique` is ``'min'`` or + ``'both'``, and on upper colors when `unique` is ``'max'`` or ``'both'``. +clip : bool, optional + Whether to clip values falling outside of the level bins. This only + has an effect on lower colors when `unique` is ``'min'`` or ``'both'``, + and on upper colors when `unique` is ``'max'`` or ``'both'``. + +Other parameters +---------------- +ticks : array-like, default: `levels` + Default tick values to use for colorbars drawn with this normalizer. This + is set to the level centers when `values` is passed to a plotting command. +labels : array-like, optional + Default tick labels to use for colorbars drawn with this normalizer. This + is set to values when drawing on-the-fly colorbars. + +Note +---- +This normalizer makes sure that levels always span the full range of +colors in the colormap, whether `extend` is set to ``'min'``, ``'max'``, +``'neither'``, or ``'both'``. In matplotlib, when `extend` is not ``'both'``, +the most intense colors are cut off (reserved for "out of bounds" data), +even though they are not being used. + +See also +-------- +ultraplot.constructor.Norm +ultraplot.colors.SegmentedNorm +ultraplot.ticker.DiscreteLocator""" + ... + + def __call__(self, value: Incomplete, clip: Incomplete=None) -> Incomplete: + """Normalize data values to 0-1. + +Parameters +---------- +value : numeric + The data to be normalized. +clip : bool, default: ``self.clip`` + Whether to clip values falling outside of the level bins.""" + ... + + def inverse(self, value: Incomplete) -> Incomplete: + """Raise an error. + +Raises +------ +ValueError + Inversion after discretization is impossible.""" + ... + + @property + def descending(self) -> bool: + """Boolean indicating whether the levels are descending.""" + ... + +class SegmentedNorm(mcolors.Normalize): + """ + Normalizer that scales data linearly with respect to the + interpolated index in an arbitrary monotonic level sequence. + """ + + def __init__(self, levels: Incomplete, vmin: Incomplete=None, vmax: Incomplete=None, clip: Incomplete=False) -> None: + """Parameters +---------- +levels : sequence of float + The level boundaries. Must be monotonically increasing + or decreasing. +vmin : float, optional + Ignored but included for consistency with other normalizers. + Set to the minimum of `levels`. +vmax : float, optional + Ignored but included for consistency with other normalizers. + Set to the minimum of `levels`. +clip : bool, optional + Whether to clip values falling outside of the minimum + and maximum of `levels`. + +See also +-------- +ultraplot.constructor.Norm +ultraplot.colors.DiscreteNorm + +Note +---- +The algorithm this normalizer uses to select normalized values +in-between level list indices is adapted from the algorithm +`~matplotlib.colors.LinearSegmentedColormap` uses to select channel +values in-between segment data points (hence the name `SegmentedNorm`). + +Example +------- +In the below example, unevenly spaced levels are passed to +`~matplotlib.axes.Axes.contourf`, resulting in the automatic +application of `SegmentedNorm`. + +>>> import ultraplot as uplt +>>> import numpy as np +>>> levels = [1, 2, 5, 10, 20, 50, 100, 200, 500, 1000] +>>> data = 10 ** (3 * np.random.rand(10, 10)) +>>> fig, ax = uplt.subplots() +>>> ax.contourf(data, levels=levels)""" + ... + + def __call__(self, value: Incomplete, clip: Incomplete=None) -> Incomplete: + """Normalize the data values to 0-1. Inverse of `~SegmentedNorm.inverse`. + +Parameters +---------- +value : numeric + The data to be normalized. +clip : bool, default: ``self.clip`` + Whether to clip values falling outside of the minimum and maximum levels.""" + ... + + def inverse(self, value: Incomplete) -> Incomplete: + """Inverse of `~SegmentedNorm.__call__`. + +Parameters +---------- +value : numeric + The data to be un-normalized.""" + ... + +class DivergingNorm(mcolors.Normalize): + """ + Normalizer that ensures some central data value lies at the central + colormap color. The default central value is ``0``. + """ + + def __str__(self) -> str: + ... + + def __init__(self, vcenter: Incomplete=0, vmin: Incomplete=None, vmax: Incomplete=None, fair: Incomplete=True, clip: Incomplete=None) -> None: + """Parameters +---------- +vcenter : float, default: 0 + The data value corresponding to the central colormap position. +vmin : float, optional + The minimum data value. +vmax : float, optional + The maximum data value. +fair : bool, optional + If ``True`` (default), the speeds of the color gradations on either side + of the center point are equal, but colormap colors may be omitted. If + ``False``, all colormap colors are included, but the color gradations on + one side may be faster than the other side. ``False`` should be used with + great care, as it may result in a misleading interpretation of your data. +clip : bool, optional + Whether to clip values falling outside of `vmin` and `vmax`. + +See also +-------- +ultraplot.constructor.Norm""" + ... + + def __call__(self, value: Incomplete, clip: Incomplete=None) -> Incomplete: + """Normalize the data values to 0-1. + +Parameters +---------- +value : numeric + The data to be normalized. +clip : bool, default: ``self.clip`` + Whether to clip values falling outside of `vmin` and `vmax`.""" + ... + + def autoscale_None(self, z: Incomplete) -> None: + """Get vmin and vmax, and then clip at vcenter.""" + ... + +def _init_color_database() -> Incomplete: + """Initialize the subclassed database.""" + ... + +def _init_cmap_database() -> Incomplete: + """Initialize the subclassed database.""" + ... + +def _get_cmap_subtype(name: Incomplete, subtype: Incomplete) -> Incomplete: + """Get a colormap belonging to a particular class. If none are found then raise +a useful error message that omits colormaps from other classes.""" + ... + +def _translate_cmap(cmap: Incomplete, lut: Incomplete=None, cyclic: Incomplete=None, listedthresh: Incomplete=None) -> Incomplete: + """Translate the input argument to a ultraplot colormap subclass. Auto-detect +cyclic colormaps based on names and re-apply default lookup table size.""" + ... + +class _ColorCache(dict): + """ + Replacement for the native color cache. + """ + + def __getitem__(self, key: Incomplete) -> Incomplete: + """Get the standard color, colormap color, or color cycle color.""" + ... + + def _get_rgba(self, arg: Incomplete, alpha: Incomplete) -> Incomplete: + """Try to get the color from the registered colormap or color cycle.""" + ... + +class ColorDatabase(MutableMapping, dict): + """ + Dictionary subclass used to replace the builtin matplotlib color database. + See `~ColorDatabase.__getitem__` for details. + """ + _colors_replace = (('grey', 'gray'), ('ochre', 'ocher'), ('kelley', 'kelly')) + + def __delitem__(self, key: Incomplete) -> None: + ... + + def __init__(self, mapping: Incomplete=None) -> None: + """Parameters +---------- +mapping : dict-like, optional + The colors.""" + ... + + def __getitem__(self, key: Incomplete) -> Incomplete: + """Get a color. Translates ``grey`` into ``gray`` and supports retrieving +colors "on-the-fly" from registered colormaps and color cycles. + +* For a colormap, use e.g. ``color=('Blues', 0.8)``. + The number is the colormap index, and must be between 0 and 1. +* For a color cycle, use e.g. ``color=('colorblind', 2)``. + The number is the color list index. + +This works everywhere that colors are used in matplotlib, for +example as `color`, `edgecolor`, or `facecolor` keyword arguments +passed to :class:`~ultraplot.axes.PlotAxes` commands.""" + ... + + def __setitem__(self, key: Incomplete, value: Incomplete) -> None: + """Add a color. Translates ``grey`` into ``gray`` and clears the +cache. The color must be a string.""" + ... + + def _parse_key(self, key: Incomplete) -> str: + """Parse the color key. Currently this just translates grays.""" + ... + + @property + def cache(self) -> _ColorCache: + ... + +class ColormapDatabase(mcm.ColormapRegistry): + """ + Dictionary subclass used to replace the matplotlib + colormap registry. See `~ColormapDatabase.__getitem__` and + `~ColormapDatabase.__setitem__` for details. + """ + _regex_grays = re.compile('\\A(grays)(_r|_s)*\\Z', flags=re.IGNORECASE) + _regex_suffix = re.compile('(_r|_s)*\\Z', flags=re.IGNORECASE) + + def __init__(self, kwargs: Incomplete) -> None: + """Parameters +---------- +kwargs : dict-like + The source dictionary.""" + ... + + def _translate_deprecated(self, key: Incomplete) -> Incomplete: + """Check if a colormap has been deprecated.""" + ... + + def _translate_key(self, original_key: Incomplete, mirror: Incomplete=True) -> str: + """Return the sanitized colormap name. Used for lookups and assignments.""" + ... + + def _has_item(self, key: Incomplete) -> Incomplete: + ... + + def _load_and_register_cmap(self, key: Incomplete, value: Incomplete) -> Incomplete: + """Load a colormap from a file and register it.""" + ... + + def get_cmap(self, cmap: Incomplete) -> Incomplete: + ... + + def __getitem__(self, key: Incomplete) -> Incomplete: + """Get the colormap with flexible input keys.""" + ... + + @override + def register(self, cmap: Incomplete, *, name: Incomplete=None, force: Incomplete=False) -> Incomplete: + """Add the colormap after validating and converting.""" + ... + + def register_lazy(self, name: Incomplete, path: Incomplete, type: Incomplete, is_default: Incomplete=False) -> None: + """Register a colormap to be loaded lazily from a file.""" + ... +_cmap_database = _init_cmap_database() +_color_database = _init_color_database() diff --git a/ultraplot/config.py b/ultraplot/config.py index af66ed6f9..e8a5faef8 100644 --- a/ultraplot/config.py +++ b/ultraplot/config.py @@ -838,6 +838,7 @@ def __init__(self, local=True, user=True, default=True, **kwargs): self._setting_handlers = {} self._init(local=local, user=user, default=default, **kwargs) + @docstring._snippet_manager def register_handler( self, name: str, func: Callable[[Any], Dict[str, Any]] ) -> None: diff --git a/ultraplot/config.pyi b/ultraplot/config.pyi new file mode 100644 index 000000000..06be2c244 --- /dev/null +++ b/ultraplot/config.pyi @@ -0,0 +1,710 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Tools for setting up ultraplot and configuring global settings. +See the :ref:`configuration guide ` for details. +""" +from _typeshed import Incomplete +import logging +import os +import re +import sys +from collections import namedtuple +from collections.abc import MutableMapping +from numbers import Real +from typing import Any, Callable, Dict +import cycler +import matplotlib as mpl +import matplotlib.colors as mcolors +import matplotlib.font_manager as mfonts +import matplotlib.mathtext +import matplotlib.style.core as mstyle +import numpy as np +from matplotlib import RcParams +from .internals import _not_none, _pop_kwargs, _pop_props, _translate_grid, _version_mpl, docstring, ic, rcsetup, warnings +__all__ = ['Configurator', 'rc', 'rc_ultraplot', 'rc_matplotlib', 'use_style', 'config_inline_backend', 'register_cmaps', 'register_cycles', 'register_colors', 'register_fonts'] +COLORS_KEEP = ('red', 'green', 'blue', 'cyan', 'yellow', 'magenta', 'white', 'black') +_ULTRAPLOT_STYLES = {'poster': {'font.size': 14, 'axes.titlesize': 18, 'axes.labelsize': 16, 'xtick.labelsize': 13, 'ytick.labelsize': 13, 'legend.fontsize': 13, 'figure.titlesize': 20, 'lines.linewidth': 2.0, 'lines.markersize': 6, 'figure.facecolor': 'none', 'savefig.facecolor': 'none', 'savefig.edgecolor': 'none'}, 'dark_background': {'figure.facecolor': '#000000', 'figure.edgecolor': '#000000', 'axes.facecolor': '#000000', 'axes.edgecolor': '#cbd5e1', 'axes.labelcolor': '#f8fafc', 'text.color': '#f8fafc', 'xtick.color': '#cbd5e1', 'ytick.color': '#cbd5e1', 'grid.color': '#475569', 'grid.alpha': 0.35, 'legend.facecolor': '#000000', 'legend.edgecolor': '#475569', 'savefig.facecolor': '#000000', 'savefig.edgecolor': '#000000', 'axes.prop_cycle': cycler.cycler(color=('#60a5fa', '#f59e0b', '#34d399', '#f472b6', '#a78bfa', '#f87171'))}} +_rc_docstring = ... +_shared_docstring = ... +_cmap_exts_docstring = ... +_cycle_exts_docstring = ... +_color_docstring = ... +_font_docstring = ... +_register_docstring = ... +_rc_register_handler_docstring = ... + +def _init_user_file() -> Incomplete: + """Initialize .ultraplotrc file.""" + ... + +def _init_user_folders() -> Incomplete: + """Initialize .ultraplot folder.""" + ... + +def _get_data_folders(folder: Incomplete, user: Incomplete=True, local: Incomplete=True, default: Incomplete=True, reverse: Incomplete=False) -> Incomplete: + """Return data folder paths in reverse order of precedence.""" + ... + +def _iter_data_objects(folder: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Iterate over input objects and files in the data folders that should be +registered. Also yield an index indicating whether these are user files.""" + ... + +def _filter_style_dict(rcdict: Incomplete, warn: Incomplete=True) -> Incomplete: + """Filter out blacklisted style parameters.""" + ... + +def _get_default_style_dict() -> Incomplete: + """Get the default rc parameters dictionary with deprecated parameters filtered.""" + ... + +def _get_style_dict(style: Incomplete, filter: Incomplete=True) -> Incomplete: + """Return a dictionary of settings belonging to the requested style(s). If `filter` +is ``True``, invalid style parameters like `backend` are filtered out.""" + ... + +def _infer_ultraplot_dict(kw_params: Incomplete) -> Incomplete: + """Infer values for ultraplot's "added" parameters from stylesheet parameters.""" + ... + +def config_inline_backend(fmt: Incomplete=None) -> None: + """Set up the ipython `inline backend display format `__ +and ensure that inline figures always look the same as saved figures. +This runs the following ipython magic commands: + +.. code-block:: ipython + + %%config InlineBackend.figure_formats = rc['inlineformat'] + %%config InlineBackend.rc = {} # never override rc settings + %%config InlineBackend.close_figures = True # cells start with no active figures + %%config InlineBackend.print_figure_kwargs = {'bbox_inches': None} + +When the inline backend is inactive or unavailable, this has no effect. +This function is called when you modify the :rcraw:`inlineformat` property. + +Parameters +---------- +fmt : str or sequence, default: :rc:`inlineformat` + The inline backend file format or a list thereof. Valid formats + include ``'jpg'``, ``'png'``, ``'svg'``, ``'pdf'``, and ``'retina'``. + +See also +-------- +Configurator""" + ... + +def use_style(style: Incomplete) -> None: + """Apply the `matplotlib style(s) `__ +with `matplotlib.style.use`. This function is +called when you modify the :rcraw:`style` property. + +Parameters +---------- +style : str or sequence or dict-like + The matplotlib style name(s) or stylesheet filename(s), or dictionary(s) + of settings. Use ``'default'`` to apply matplotlib default settings and + ``'original'`` to include settings from your user ``matplotlibrc`` file. + +See also +-------- +Configurator +matplotlib.style.use""" + ... + +def register_cmaps(*args: Incomplete, user: Incomplete=None, local: Incomplete=None, default: Incomplete=False) -> None: + """Register named colormaps. This is called on import. + +Parameters +---------- +*args : path-spec or `~ultraplot.colors.ContinuousColormap`, optional + The colormaps to register. These can be file paths containing + RGB data or `~ultraplot.colors.ContinuousColormap` instances. By default, + if positional arguments are passed, then `user` is set to ``False``. + + Valid file extensions are listed in the below table. Note that colormaps + are registered according to their filenames -- for example, ``name.xyz`` + will be registered as ``'name'``. + + =================== ========================================== + Extension Description + =================== ========================================== + ``.json`` JSON database of the channel segment data. + ``.hex`` Comma-delimited list of HEX strings. + ``.rgb``, ``.txt`` 3-4 column table of channel values. + =================== ========================================== + +user : bool, optional + Whether to reload colormaps from `~Configurator.user_folder`. Default is + ``False`` if positional arguments were passed and ``True`` otherwise. +local : bool, optional + Whether to reload colormaps from `~Configurator.local_folders`. Default is + ``False`` if positional arguments were passed and ``True`` otherwise. +default : bool, default: False + Whether to reload the default colormaps packaged with ultraplot. + Default is always ``False``. + +See also +-------- +register_cycles +register_colors +register_fonts +ultraplot.demos.show_cmaps""" + ... + +def register_cycles(*args: Incomplete, user: Incomplete=None, local: Incomplete=None, default: Incomplete=False) -> None: + """Register named color cycles. This is called on import. + +Parameters +---------- +*args : path-spec or `~ultraplot.colors.DiscreteColormap`, optional + The color cycles to register. These can be file paths containing + RGB data or `~ultraplot.colors.DiscreteColormap` instances. By default, + if positional arguments are passed, then `user` is set to ``False``. + + Valid file extensions are listed in the below table. Note that color cycles + are registered according to their filenames -- for example, ``name.xyz`` + will be registered as ``'name'``. + + ================== ========================================== + Extension Description + ================== ========================================== + ``.hex`` Comma-delimited list of HEX strings. + ``.rgb``, ``.txt`` 3-4 column table of channel values. + ================== ========================================== + +user : bool, optional + Whether to reload color cycles from `~Configurator.user_folder`. Default is + ``False`` if positional arguments were passed and ``True`` otherwise. +local : bool, optional + Whether to reload color cycles from `~Configurator.local_folders`. Default is + ``False`` if positional arguments were passed and ``True`` otherwise. +default : bool, default: False + Whether to reload the default color cycles packaged with ultraplot. + Default is always ``False``. + +See also +-------- +register_cmaps +register_colors +register_fonts +ultraplot.demos.show_cycles""" + ... + +def register_colors(*args: Incomplete, user: Incomplete=None, local: Incomplete=None, default: Incomplete=False, space: Incomplete=None, margin: Incomplete=None, **kwargs: Incomplete) -> None: + """Register named colors. This is called on import. + +Parameters +---------- +*args : path-like or dict, optional + The colors to register. These can be file paths containing RGB data or + dictionary mappings of names to RGB values. By default, if positional + arguments are passed, then `user` is set to ``False``. Files must have + the extension ``.txt`` and should contain one line per color in the + format ``name : hex``. Whitespace is ignored. +user : bool, optional + Whether to reload colors from `~Configurator.user_folder`. Default is + ``False`` if positional arguments were passed and ``True`` otherwise. +local : bool, optional + Whether to reload colors from `~Configurator.local_folders`. Default is + ``False`` if positional arguments were passed and ``True`` otherwise. +default : bool, default: False + Whether to reload the default colors packaged with ultraplot. + Default is always ``False``. +space : {'hcl', 'hsl', 'hpl'}, optional + The colorspace used to pick "perceptually distinct" colors from + the `XKCD color survey `__. + If passed then `default` is set to ``True``. +margin : float, default: 0.1 + The margin used to pick "perceptually distinct" colors from the + `XKCD color survey `__. The normalized hue, + saturation, and luminance of each color must differ from the channel + values of the prededing colors by `margin` in order to be registered. + Must fall between ``0`` and ``1`` (``0`` will register all colors). + If passed then `default` is set to ``True``. +**kwargs + Additional color name specifications passed as keyword arguments rather + than positional argument dictionaries. + +See also +-------- +register_cmaps +register_cycles +register_fonts +ultraplot.demos.show_colors""" + ... + +def register_fonts(*args: Incomplete, user: Incomplete=True, local: Incomplete=True, default: Incomplete=False) -> None: + """Register font families. This is called on import. + +Parameters +---------- +*args : path-like, optional + The font files to add. By default, if positional arguments are passed, then + `user` is set to ``False``. Files must have the extensions ``.ttf`` or ``.otf``. + See `this link `__ + for a guide on converting other font files to ``.ttf`` and ``.otf``. +user : bool, optional + Whether to reload fonts from `~Configurator.user_folder`. Default is + ``False`` if positional arguments were passed and ``True`` otherwise. +local : bool, optional + Whether to reload fonts from `~Configurator.local_folders`. Default is + ``False`` if positional arguments were passed and ``True`` otherwise. +default : bool, default: False + Whether to reload the default fonts packaged with ultraplot. + Default is always ``False``. + +See also +-------- +register_cmaps +register_cycles +register_colors +ultraplot.demos.show_fonts""" + ... + +class Configurator(MutableMapping, dict): + """ + A dictionary-like class for managing `matplotlib settings + `__ + stored in `rc_matplotlib` and :ref:`ultraplot settings ` + stored in `rc_ultraplot`. This class is instantiated as the `rc` object + on import. See the :ref:`user guide ` for details. + """ + + def __repr__(self) -> str: + ... + + def __str__(self) -> str: + ... + + def __iter__(self) -> Incomplete: + ... + + def __len__(self) -> int: + ... + + def __delitem__(self, key: Incomplete) -> Incomplete: + ... + + def __delattr__(self, attr: Incomplete) -> Incomplete: + ... + + def __init__(self, local: Incomplete=True, user: Incomplete=True, default: Incomplete=True, **kwargs: Incomplete) -> None: + """Parameters +---------- +local : bool, default: True + Whether to load settings from the `~Configurator.local_files` file. +user : bool, default: True + Whether to load settings from the `~Configurator.user_file` file. +default : bool, default: True + Whether to reload built-in default ultraplot settings.""" + ... + + def register_handler(self, name: str, func: Callable[[Any], Dict[str, Any]]) -> None: + """ Register a callback function to be executed when a setting is modified. + + This is an extension point for "special" settings that require complex + logic or have side-effects, such as updating other matplotlib settings. + It is used internally to decouple the configuration system from other + subsystems and avoid circular imports. + + Parameters + ---------- + name : str + The name of the setting (e.g., ``'cycle'``). + func : callable + The handler function to be executed. The function must accept a + single positional argument, which is the new `value` of the + setting, and must return a dictionary. The keys of the dictionary + should be valid ``matplotlib`` rc setting names, and the values + will be applied to the ``rc_matplotlib`` object. + + Example + ------- + >>> def _cycle_handler(value): + ... # ... logic to create a cycler object from the value ... + ... return {'axes.prop_cycle': new_cycler} + >>> rc.register_handler('cycle', _cycle_handler) + """ + ... + + def __getitem__(self, key: Incomplete) -> Incomplete: + """Return an `rc_matplotlib` or `rc_ultraplot` setting using dictionary notation +(e.g., ``value = uplt.rc[name]``).""" + ... + + def __setitem__(self, key: Incomplete, value: Incomplete) -> None: + """Modify an `rc_matplotlib` or `rc_ultraplot` setting using dictionary notation +(e.g., ``uplt.rc[name] = value``).""" + ... + + def __getattr__(self, attr: Incomplete) -> Incomplete: + """Return an `rc_matplotlib` or `rc_ultraplot` setting using "dot" notation +(e.g., ``value = uplt.rc.name``).""" + ... + + def __setattr__(self, attr: Incomplete, value: Incomplete) -> None: + """Modify an `rc_matplotlib` or `rc_ultraplot` setting using "dot" notation +(e.g., ``uplt.rc.name = value``).""" + ... + + def __enter__(self) -> None: + """Apply settings from the most recent context block.""" + ... + + def __exit__(self, *args: Incomplete) -> None: + """Restore settings from the most recent context block.""" + ... + + def _init(self, *, local: Incomplete, user: Incomplete, default: Incomplete) -> None: + """Initialize the configurator.""" + ... + + @staticmethod + def _validate_key(key: Incomplete, value: Incomplete=None) -> Incomplete: + """Validate setting names and handle `rc_ultraplot` deprecations.""" + ... + + @staticmethod + def _validate_value(key: Incomplete, value: Incomplete) -> Incomplete: + """Validate setting values and convert numpy ndarray to list if possible.""" + ... + + def _get_item_context(self, key: Incomplete, mode: Incomplete=None) -> Incomplete: + """As with `~Configurator.__getitem__` but the search is limited based +on the context mode and ``None`` is returned if the key is not found.""" + ... + + def _get_item_dicts(self, key: Incomplete, value: Incomplete) -> Incomplete: + """Return dictionaries for updating the `rc_ultraplot` and `rc_matplotlib` +properties associated with this key. Used when setting items, entering +context blocks, or loading files.""" + ... + + @staticmethod + def _get_axisbelow_zorder(axisbelow: Incomplete) -> float: + """Convert the `axisbelow` string to its corresponding `zorder`.""" + ... + + def _get_background_props(self, patch_kw: Incomplete=None, native: Incomplete=True, **kwargs: Incomplete) -> Incomplete: + """Return background properties, optionally filtering the output dictionary +based on the context.""" + ... + + def _get_gridline_bool(self, grid: Incomplete=None, axis: Incomplete=None, which: Incomplete='major', native: Incomplete=True) -> Incomplete: + """Return major and minor gridline toggles from ``axes.grid``, ``axes.grid.which``, +and ``axes.grid.axis``, optionally returning `None` based on the context.""" + ... + + def _get_gridline_props(self, which: Incomplete='major', native: Incomplete=True, rebuild: Incomplete=False) -> Incomplete: + """Return gridline properties, optionally filtering the output dictionary +based on the context.""" + ... + + def _get_label_props(self, native: Incomplete=True, **kwargs: Incomplete) -> Incomplete: + """Return the axis label properties, optionally filtering the output dictionary +based on the context.""" + ... + + def _get_loc_string(self, string: Incomplete, axis: Incomplete=None, native: Incomplete=True) -> Incomplete: + """Return `tickloc` and `spineloc` location strings from the `rc` boolean toggles, +optionally returning `None` based on the context.""" + ... + + def _get_tickline_props(self, axis: Incomplete=None, which: Incomplete='major', native: Incomplete=True, rebuild: Incomplete=False) -> Incomplete: + """Return the tick line properties, optionally filtering the output dictionary +based on the context.""" + ... + + def _get_ticklabel_props(self, axis: Incomplete=None, native: Incomplete=True, rebuild: Incomplete=False) -> Incomplete: + """Return the tick label properties, optionally filtering the output dictionary +based on the context.""" + ... + + @staticmethod + def local_files() -> Incomplete: + """Return locations of files named ``ultraplotrc`` in this directory and in parent +directories. "Hidden" files with a leading dot are also recognized. These are +automatically loaded when ultraplot is imported. + +See also +-------- +Configurator.user_file +Configurator.local_folders""" + ... + + @staticmethod + def local_folders(subfolder: Incomplete=None) -> Incomplete: + """Return locations of folders named ``ultraplot_cmaps``, ``ultraplot_cycles``, +``ultraplot_colors``, and ``ultraplot_fonts`` in this directory and in parent +directories. "Hidden" folders with a leading dot are also recognized. Files +in these directories are automatically loaded when ultraplot is imported. + +See also +-------- +Configurator.user_folder +Configurator.local_files""" + ... + + @staticmethod + def _config_folder() -> str: + """Get the XDG ultraplot folder.""" + ... + + @staticmethod + def user_file() -> str: + """Return location of the default ultraplotrc file. On Linux, this is either +``$XDG_CONFIG_HOME/ultraplot/ultraplotrc`` or ``~/.config/ultraplot/ultraplotrc`` +if the `XDG directory `__ +is unset. On other operating systems, this is ``~/.ultraplot/ultraplotrc``. The +location ``~/.ultraplotrc`` or ``~/.ultraplot/ultraplotrc`` is always returned if the +file exists, regardless of the operating system. If multiple valid locations +are found, a warning is raised. + +See also +-------- +Configurator.user_folder +Configurator.local_files""" + ... + + @staticmethod + def user_folder(subfolder: Incomplete=None) -> str: + """Return location of the default ultraplot folder. On Linux, this +is either ``$XDG_CONFIG_HOME/ultraplot`` or ``~/.config/ultraplot`` +if the `XDG directory `__ +is unset. On other operating systems, this is ``~/.ultraplot``. The location +``~/.ultraplot`` is always returned if the folder exists, regardless of the +operating system. If multiple valid locations are found, a warning is raised. + +See also +-------- +Configurator.user_file +Configurator.local_folders""" + ... + + def context(self, *args: Incomplete, mode: Incomplete=0, file: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Temporarily modify the rc settings in a "with as" block. + +Parameters +---------- +*args + Dictionaries of `rc` keys and values. +file : path-like, optional + Filename from which settings should be loaded. +**kwargs + `rc` names and values passed as keyword arguments. + If the name has dots, simply omit them. + +Other parameters +---------------- +mode : {0, 1, 2}, optional + The context mode. Dictates the behavior of `~Configurator.find`, + `~Configurator.fill`, and `~Configurator.category` within a + "with as" block when called with ``context=True``. + + The options are as follows: + + * ``mode=0``: Matplotlib's `rc_matplotlib` settings + and ultraplot's `rc_ultraplot` settings are all returned, + whether or not they are local to the "with as" block. + * ``mode=1``: Matplotlib's `rc_matplotlib` settings are only + returned if they are local to the "with as" block. For example, + if :rcraw:`axes.titlesize` was passed to `~Configurator.context`, + then ``uplt.rc.find('axes.titlesize', context=True)`` will return + this value, but ``uplt.rc.find('axes.titleweight', context=True)`` will + return ``None``. This is used internally when instantiating axes. + * ``mode=2``: Matplotlib's `rc_matplotlib` settings and ultraplot's + `rc_ultraplot` settings are only returned if they are local to the + "with as" block. This is used internally when formatting axes. + +Note +---- +Context "modes" are primarily used internally but may also be useful for power +users. Mode ``1`` is used when `~ultraplot.axes.Axes.format` is called during +axes instantiation, and mode ``2`` is used when `~ultraplot.axes.Axes.format` +is manually called by users. The latter prevents successive calls to +`~ultraplot.axes.Axes.format` from constantly looking up and re-applying +unchanged settings and significantly increasing the runtime. + +Example +------- +The below applies settings to axes in a specific figure using +`~Configurator.context`. + +>>> import ultraplot as uplt +>>> with uplt.rc.context(ticklen=5, metalinewidth=2): +>>> fig, ax = uplt.subplots() +>>> ax.plot(data) + +The below applies settings to a specific axes using +`~ultraplot.axes.Axes.format`, which uses `~Configurator.context` +internally. + +>>> import ultraplot as uplt +>>> fig, ax = uplt.subplots() +>>> ax.format(ticklen=5, metalinewidth=2)""" + ... + + def category(self, cat: Incomplete, *, trimcat: Incomplete=True, context: Incomplete=False) -> Incomplete: + """Return a dictionary of settings beginning with the substring ``cat + '.'``. +Optionally limit the search to the context level. + +Parameters +---------- +cat : str, optional + The `rc` setting category. +trimcat : bool, default: True + Whether to trim ``cat`` from the key names in the output dictionary. +context : bool, default: False + If ``True``, then settings not found in the context dictionaries + are omitted from the output dictionary. See `~Configurator.context`. + +See also +-------- +Configurator.find +Configurator.fill""" + ... + + def fill(self, props: Incomplete, *, context: Incomplete=False) -> Incomplete: + """Return a dictionary filled with settings whose names match the string values +in the input dictionary. Optionally limit the search to the context level. + +Parameters +---------- +props : dict-like + Dictionary whose values are setting names -- for example + ``rc.fill({'edgecolor': 'axes.edgecolor', 'facecolor': 'axes.facecolor'})``. +context : bool, default: False + If ``True``, then settings not found in the context dictionaries + are omitted from the output dictionary. See `~Configurator.context`. + +See also +-------- +Configurator.category +Configurator.find""" + ... + + def find(self, key: Incomplete, *, context: Incomplete=False) -> Incomplete: + """Return a single setting. Optionally limit the search to the context level. + +Parameters +---------- +key : str + The single setting name. +context : bool, default: False + If ``True``, then ``None`` is returned if the setting is not found + in the context dictionaries. See `~Configurator.context`. + +See also +-------- +Configurator.category +Configurator.fill""" + ... + + def update(self, *args: Incomplete, **kwargs: Incomplete) -> None: + """Update several settings at once. + +Parameters +---------- +*args : str or dict-like, optional + A dictionary containing `rc` keys and values. You can also pass + a "category" name as the first argument, in which case all + settings are prepended with ``'category.'``. For example, + ``rc.update('axes', labelsize=20, titlesize=20)`` changes the + :rcraw:`axes.labelsize` and :rcraw:`axes.titlesize` settings. +**kwargs + `rc` keys and values passed as keyword arguments. + If the name has dots, simply omit them. + +See also +-------- +Configurator.category +Configurator.fill""" + ... + + def reset(self, local: Incomplete=True, user: Incomplete=True, default: Incomplete=True, **kwargs: Incomplete) -> None: + """Reset the configurator to its initial state. + +Parameters +---------- +local : bool, default: True + Whether to load settings from the `~Configurator.local_files` file. +user : bool, default: True + Whether to load settings from the `~Configurator.user_file` file. +default : bool, default: True + Whether to reload built-in default ultraplot settings.""" + ... + + def _load_file(self, path: Incomplete) -> Incomplete: + """Return dictionaries of ultraplot and matplotlib settings loaded from the file.""" + ... + + def load(self, path: Incomplete) -> None: + """Load settings from the specified file. + +Parameters +---------- +path : path-like + The file path. + +See also +-------- +Configurator.save""" + ... + + @staticmethod + def _save_rst(path: Incomplete) -> None: + """Create an RST table file. Used for online docs.""" + ... + + @staticmethod + def _save_yaml(path: Incomplete, user_dict: Incomplete=None, *, comment: Incomplete=False, description: Incomplete=False) -> None: + """Create a YAML file. Used for online docs and default and user-generated +ultraplotrc files. Extra settings can be passed with the input dictionary.""" + ... + + def save(self, path: Incomplete=None, user: Incomplete=True, comment: Incomplete=None, backup: Incomplete=True, description: Incomplete=False) -> None: + """Save the current settings to a ``ultraplotrc`` file. This writes +the default values commented out plus the values that *differ* +from the defaults at the top of the file. + +Parameters +---------- +path : path-like, default: 'ultraplotrc' + The file name and/or directory. The default file name is ``ultraplotrc`` + and the default directory is the current directory. +user : bool, default: True + If ``True`` then settings that have been `~Configurator.changed` from + the ultraplot defaults are shown uncommented at the top of the file. +backup : bool, default: True + Whether to "backup" an existing file by renaming with the suffix ``.bak`` + or overwrite an existing file. +comment : bool, optional + Whether to comment out the default settings. If not passed + this takes the same value as `user`. +description : bool, default: False + Whether to include descriptions of each setting (as seen in the + :ref:`user guide table `) as comments. + +See also +-------- +Configurator.load +Configurator.changed""" + ... + + @property + def _context_mode(self) -> Incomplete: + """Return the highest (least permissive) context mode.""" + ... + + @property + def changed(self) -> Incomplete: + """A dictionary of settings that have changed from the ultraplot defaults. + +See also +-------- +Configurator.save""" + ... +rc_matplotlib = mpl.rcParams +rc_ultraplot = rcsetup._rc_ultraplot_default.copy() +rc = Configurator() diff --git a/ultraplot/constructor.pyi b/ultraplot/constructor.pyi new file mode 100644 index 000000000..95b071ea6 --- /dev/null +++ b/ultraplot/constructor.pyi @@ -0,0 +1,855 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +The constructor functions used to build class instances from simple shorthand arguments. +""" +from _typeshed import Incomplete +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.font_manager as mfonts +import matplotlib.projections.polar as mpolar +import matplotlib.scale as mscale +import matplotlib.ticker as mticker +from matplotlib.ft2font import FT2Font +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, warnings +from .utils import 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'] +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: + ... + + def _refresh(self) -> None: + ... + + def __contains__(self, key: object) -> bool: + ... + + def __getitem__(self, key: str) -> _RegistryValue: + ... + + def __iter__(self) -> Iterator[str]: + ... + + def __len__(self) -> int: + ... + + def get(self, key: str, default: _RegistryValue | None=None) -> _RegistryValue | None: + ... + + def items(self) -> Incomplete: + ... + + def keys(self) -> Incomplete: + ... + + def values(self) -> Incomplete: + ... + + def copy(self) -> dict[str, _RegistryValue]: + ... + +def _build_norm_registry() -> dict[str, type[mcolors.Normalize]]: + ... + +def _build_locator_registry() -> dict[str, object]: + ... + +def _get_dms_symbol_kwargs() -> dict[str, str]: + """Return ASCII DMS symbols when the active font lacks prime glyphs.""" + ... + +def _build_formatter_registry() -> dict[str, object]: + ... +NORMS = _RefreshingRegistry(_build_norm_registry) +LOCATORS = _RefreshingRegistry(_build_locator_registry) +FORMATTERS = _RefreshingRegistry(_build_formatter_registry) +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)} +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': 15000000.0, 'height': 15000000.0}, 'eqdc': {'lon_0': 0, 'lat_0': 90, 'width': 15000000.0, 'height': 15000000.0}, 'cass': {'lon_0': 0, 'lat_0': 90, 'width': 15000000.0, 'height': 15000000.0}, 'gnom': {'lon_0': 0, 'lat_0': 90, 'width': 15000000.0, 'height': 15000000.0}, 'poly': {'lon_0': 0, 'lat_0': 0, 'width': 10000000.0, 'height': 10000000.0}, 'npaeqd': {'lon_0': 0, 'boundinglat': 10}, 'nplaea': {'lon_0': 0, 'boundinglat': 10}, '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, 'width': 20000000.0, 'height': 15000000.0}, 'tmerc': {'lon_0': 0, 'lat_0': 0, 'width': 10000000.0, 'height': 10000000.0}, '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': 10000000.0, 'height': 10000000.0}} +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', 'eck1': 'EckertI', 'eck2': 'EckertII', 'eck3': 'EckertIII', 'eck4': 'EckertIV', 'eck5': 'EckertV', 'eck6': 'EckertVI', 'eqc': 'PlateCarree', 'eqdc': 'EquidistantConic', 'eqearth': 'EqualEarth', 'euro': 'EuroPP', 'geos': 'Geostationary', 'gnom': 'Gnomonic', 'igh': 'InterruptedGoodeHomolosine', 'laea': 'LambertAzimuthalEqualArea', 'lcc': 'LambertConformal', 'lcyl': 'LambertCylindrical', 'merc': 'Mercator', 'mill': 'Miller', 'moll': 'Mollweide', 'npstere': 'NorthPolarStereo', 'nsper': 'NearsidePerspective', 'ortho': 'Orthographic', 'osgb': 'OSGB', 'osni': 'OSNI', 'pcarree': 'PlateCarree', 'robin': 'Robinson', 'rotpole': 'RotatedPole', 'sinu': 'Sinusoidal', 'spstere': 'SouthPolarStereo', 'stere': 'Stereographic', 'tmerc': 'TransverseMercator', 'utm': 'UTM'} + PROJS_TABLE = ... +FEATURES_CARTOPY = {'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 = {'land': 'fillcontinents', 'coast': 'drawcoastlines', 'rivers': 'drawrivers', 'borders': 'drawcountries', 'innerborders': 'drawstates'} +RESOS_CARTOPY = {'lo': '110m', 'med': '50m', 'hi': '10m', 'x-hi': '10m', 'xx-hi': '10m'} +RESOS_BASEMAP = {'lo': 'c', 'med': 'l', 'hi': 'i', 'x-hi': 'h', 'xx-hi': 'f'} + +def _modify_colormap(cmap: Incomplete, *, cut: Incomplete, left: Incomplete, right: Incomplete, reverse: Incomplete, shift: Incomplete, alpha: Incomplete, samples: Incomplete) -> Incomplete: + """Modify colormap using a variety of methods.""" + ... + +def Colormap(*args: Incomplete, name: Incomplete=None, listmode: Incomplete='perceptual', filemode: Incomplete='continuous', discrete: Incomplete=False, cycle: Incomplete=None, save: Incomplete=False, save_kw: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """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""" + ... + +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 `__, + the `marker reference `__, + and the `custom dashes reference `__. + 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: Incomplete, N: Incomplete=None, samples: Incomplete=None, name: Incomplete=None, **kwargs: Incomplete) -> None: + ... + + def _parse_basic_properties(self, kwargs: Incomplete) -> Incomplete: + """Parse and validate basic properties from kwargs.""" + ... + + def _handle_empty_args(self, props: Incomplete, kwargs: Incomplete) -> None: + """Handle case when no positional arguments are provided.""" + ... + + def _handle_cycler_args(self, args: Incomplete, props: Incomplete, kwargs: Incomplete) -> None: + """Handle case when arguments are cycler objects.""" + ... + + def _handle_colormap_args(self, args: Incomplete, props: Incomplete, kwargs: Incomplete, samples: Incomplete, name: Incomplete) -> None: + """Handle case when arguments are for creating a colormap.""" + ... + + def _create_colormap(self, args: Incomplete, name: Incomplete, samples: Incomplete, kwargs: Incomplete) -> Incomplete: + """Create a colormap from the given arguments.""" + ... + + def _is_all_cyclers(self, args: Incomplete) -> bool: + """Check if all arguments are Cycler objects.""" + ... + + def _build_cycler(self, dicts: Incomplete) -> None: + """Build the final cycler from the given dictionaries.""" + ... + + def __eq__(self, other: Incomplete) -> bool: + ... + + def get_next(self) -> Incomplete: + ... + +def Norm(norm: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Return an arbitrary `~matplotlib.colors.Normalize` instance. See this +`tutorial `__ +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'`` `~ultraplot.colors.DivergingNorm` + ``'segmented'``, ``'segments'`` `~ultraplot.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 +ultraplot.colors.DiscreteNorm +ultraplot.constructor.Colormap""" + ... + +def Locator(locator: Incomplete, *args: Incomplete, discrete: Incomplete=False, **kwargs: Incomplete) -> Incomplete: + """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 + `~ultraplot.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, ``uplt.Locator(('multiple', 5))`` is + equivalent to ``uplt.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'`` `~ultraplot.ticker.DiscreteLocator` Major ticks restricted to these locations but subsampled depending on the axis length + ``'discreteminor'`` `~ultraplot.ticker.DiscreteLocator` Minor ticks restricted to these locations but subsampled depending on the axis length + ``'index'`` :class:`~ultraplot.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'`` `~ultraplot.ticker.LongitudeLocator` Longitude gridlines at sensible decimal locations + ``'lat'``, ``'deglat'`` `~ultraplot.ticker.LatitudeLocator` Latitude gridlines at sensible decimal locations + ``'dms'`` `~ultraplot.ticker.DegreeLocator` Gridlines on nice minute and second intervals + ``'dmslon'`` `~ultraplot.ticker.LongitudeLocator` Longitude gridlines on nice minute and second intervals + ``'dmslat'`` `~ultraplot.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 +ultraplot.axes.CartesianAxes.format +ultraplot.axes.PolarAxes.format +ultraplot.axes.GeoAxes.format +ultraplot.axes.Axes.colorbar +ultraplot.constructor.Formatter""" + ... + +def Formatter(formatter: Incomplete, *args: Incomplete, date: Incomplete=False, index: Incomplete=False, **kwargs: Incomplete) -> Incomplete: + """Return a `~matplotlib.ticker.Formatter` instance. + +Parameters +---------- +formatter : `~matplotlib.ticker.Formatter`, str, bool, callable, or sequence + The formatter specification, interpreted as follows: + + * If a `~matplotlib.ticker.Formatter` instance already, + a `copy.copy` of the instance is returned. + * If ``False``, a `~matplotlib.ticker.NullFormatter` is used, and if + ``True``, the default `~ultraplot.ticker.AutoFormatter` is used. + * If a function, the labels will be generated using this function. + Returns a `~matplotlib.ticker.FuncFormatter`. + * If sequence of strings, the ticks are labeled with these strings. + Returns a `~matplotlib.ticker.FixedFormatter` by default or + an :class:`~ultraplot.ticker.IndexFormatter` if `index` is ``True``. + * If a string containing ``{x}`` or ``{x:...}``, ticks will be + formatted by calling ``string.format(x=number)``. Returns + a `~matplotlib.ticker.StrMethodFormatter`. + * If a string containing ``'%%'`` and `date` is ``False``, ticks + will be formatted using the C-style ``string %% number`` method. See + `this page `__ + for a review. Returns a `~matplotlib.ticker.FormatStrFormatter`. + * If a string containing ``'%%'`` and `date` is ``True``, ticks + will be formatted using `~datetime.datetime.strfrtime`. See + `this page `__ + for a review. Returns a `~matplotlib.dates.DateFormatter`. + + Otherwise, `formatter` should be a string corresponding to one of the + "registered" formatters or formatter presets (see below table). If + `formatter` is a list or tuple and the first element is a "registered" + formatter name, subsequent elements are passed to the formatter class + as positional arguments. For example, ``uplt.Formatter(('sigfig', 3))`` is + equivalent to ``Formatter('sigfig', 3)``. + + + .. _tau: https://tauday.com/tau-manifesto + + .. _formatter_table: + + ====================== ============================================== ================================================================= + Key Class Description + ====================== ============================================== ================================================================= + ``'null'``, ``'none'`` `~matplotlib.ticker.NullFormatter` No tick labels + ``'auto'`` `~ultraplot.ticker.AutoFormatter` New default tick labels for axes + ``'sci'`` `~ultraplot.ticker.SciFormatter` Format ticks with scientific notation + ``'simple'`` `~ultraplot.ticker.SimpleFormatter` New default tick labels for e.g. contour labels + ``'sigfig'`` `~ultraplot.ticker.SigFigFormatter` Format labels using the first ``N`` significant digits + ``'frac'`` `~ultraplot.ticker.FracFormatter` Rational fractions + ``'date'`` `~matplotlib.dates.AutoDateFormatter` Default tick labels for datetime axes + ``'concise'`` `~matplotlib.dates.ConciseDateFormatter` More concise date labels introduced in matplotlib 3.1 + ``'datestr'`` `~matplotlib.dates.DateFormatter` Date formatting with C-style ``string %% format`` notation + ``'eng'`` `~matplotlib.ticker.EngFormatter` Engineering notation + ``'fixed'`` `~matplotlib.ticker.FixedFormatter` List of strings + ``'formatstr'`` `~matplotlib.ticker.FormatStrFormatter` From C-style ``string %% format`` notation + ``'func'`` `~matplotlib.ticker.FuncFormatter` Use an arbitrary function + ``'index'`` :class:`~ultraplot.ticker.IndexFormatter` List of strings corresponding to non-negative integer positions + ``'log'`` `~matplotlib.ticker.LogFormatterSciNotation` For log-scale axes with scientific notation + ``'logit'`` `~matplotlib.ticker.LogitFormatter` For logistic-scale axes + ``'percent'`` `~matplotlib.ticker.PercentFormatter` Trailing percent sign + ``'scalar'`` `~matplotlib.ticker.ScalarFormatter` The default matplotlib formatter + ``'strmethod'`` `~matplotlib.ticker.StrMethodFormatter` From the ``string.format`` method + ``'theta'`` `~matplotlib.projections.polar.ThetaFormatter` Formats radians as degrees, with a degree symbol + ``'e'`` `~ultraplot.ticker.FracFormatter` preset Fractions of *e* + ``'pi'`` `~ultraplot.ticker.FracFormatter` preset Fractions of :math:`\\pi` + ``'tau'`` `~ultraplot.ticker.FracFormatter` preset Fractions of the `one true circle constant `_ :math:`\\tau` + ``'lat'`` `~ultraplot.ticker.AutoFormatter` preset Cardinal "SN" indicator + ``'lon'`` `~ultraplot.ticker.AutoFormatter` preset Cardinal "WE" indicator + ``'deg'`` `~ultraplot.ticker.AutoFormatter` preset Trailing degree symbol + ``'deglat'`` `~ultraplot.ticker.AutoFormatter` preset Trailing degree symbol and cardinal "SN" indicator + ``'deglon'`` `~ultraplot.ticker.AutoFormatter` preset Trailing degree symbol and cardinal "WE" indicator + ``'dms'`` `~ultraplot.ticker.DegreeFormatter` Labels with degree/minute/second support + ``'dmslon'`` `~ultraplot.ticker.LongitudeFormatter` Longitude labels with degree/minute/second support + ``'dmslat'`` `~ultraplot.ticker.LatitudeFormatter` Latitude labels with degree/minute/second support + ====================== ============================================== ================================================================= + +date : bool, optional + Toggles the behavior when `formatter` contains a ``'%%'`` sign + (see above). +index : bool, optional + Controls the behavior when `formatter` is a sequence of strings + (see above). + +Other parameters +---------------- +*args, **kwargs + Passed to the `~matplotlib.ticker.Formatter` class. + +Returns +------- +matplotlib.ticker.Formatter + A `~matplotlib.ticker.Formatter` instance. + +See also +-------- +matplotlib.ticker.Formatter +ultraplot.axes.CartesianAxes.format +ultraplot.axes.PolarAxes.format +ultraplot.axes.GeoAxes.format +ultraplot.axes.Axes.colorbar +ultraplot.constructor.Locator""" + ... + +def Scale(scale: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Return a `~matplotlib.scale.ScaleBase` instance. + +Parameters +---------- +scale : `~matplotlib.scale.ScaleBase`, str, or tuple + The axis scale specification. If a `~matplotlib.scale.ScaleBase` instance + already, a `copy.copy` of the instance is returned. Otherwise, `scale` + should be a string corresponding to one of the "registered" axis scales + or axis scale presets (see below table). + + If `scale` is a list or tuple and the first element is a + "registered" scale name, subsequent elements are passed to the + scale class as positional arguments. + + .. _scale_table: + + ================= ====================================== =============================================== + Key Class Description + ================= ====================================== =============================================== + ``'linear'`` `~ultraplot.scale.LinearScale` Linear + ``'log'`` `~ultraplot.scale.LogScale` Logarithmic + ``'symlog'`` `~ultraplot.scale.SymmetricalLogScale` Logarithmic beyond finite space around zero + ``'logit'`` `~ultraplot.scale.LogitScale` Logistic + ``'inverse'`` `~ultraplot.scale.InverseScale` Inverse + ``'function'`` `~ultraplot.scale.FuncScale` Arbitrary forward and backwards transformations + ``'sine'`` `~ultraplot.scale.SineLatitudeScale` Sine function (in degrees) + ``'mercator'`` `~ultraplot.scale.MercatorLatitudeScale` Mercator latitude function (in degrees) + ``'exp'`` `~ultraplot.scale.ExpScale` Arbitrary exponential function + ``'power'`` `~ultraplot.scale.PowerScale` Arbitrary power function + ``'cutoff'`` `~ultraplot.scale.CutoffScale` Arbitrary piecewise linear transformations + ``'quadratic'`` `~ultraplot.scale.PowerScale` (preset) Quadratic function + ``'cubic'`` `~ultraplot.scale.PowerScale` (preset) Cubic function + ``'quartic'`` `~ultraplot.scale.PowerScale` (preset) Quartic function + ``'db'`` `~ultraplot.scale.ExpScale` (preset) Ratio expressed as `decibels `_ + ``'np'`` `~ultraplot.scale.ExpScale` (preset) Ratio expressed as `nepers `_ + ``'idb'`` `~ultraplot.scale.ExpScale` (preset) `Decibels `_ expressed as ratio + ``'inp'`` `~ultraplot.scale.ExpScale` (preset) `Nepers `_ expressed as ratio + ``'pressure'`` `~ultraplot.scale.ExpScale` (preset) Height (in km) expressed linear in pressure + ``'height'`` `~ultraplot.scale.ExpScale` (preset) Pressure (in hPa) expressed linear in height + ================= ====================================== =============================================== + + .. _db: https://en.wikipedia.org/wiki/Decibel + .. _np: https://en.wikipedia.org/wiki/Neper + +Other parameters +---------------- +*args, **kwargs + Passed to the `~matplotlib.scale.ScaleBase` class. + +Returns +------- +matplotlib.scale.ScaleBase + A `~matplotlib.scale.ScaleBase` instance. + +See also +-------- +matplotlib.scale.ScaleBase +ultraplot.scale.LinearScale +ultraplot.axes.CartesianAxes.format +ultraplot.axes.CartesianAxes.dualx +ultraplot.axes.CartesianAxes.dualy""" + ... + +def _warn_basemap_deprecated() -> Incomplete: + """Warn that the basemap backend is deprecated.""" + ... + +def Proj(name: Incomplete, backend: Incomplete=None, lon0: Incomplete=None, lon_0: Incomplete=None, lat0: Incomplete=None, lat_0: Incomplete=None, lonlim: Incomplete=None, latlim: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Return a `cartopy.crs.Projection` or `~mpl_toolkits.basemap.Basemap` instance. + +Parameters +---------- +name : str, `cartopy.crs.Projection`, or `~mpl_toolkits.basemap.Basemap` + The projection name or projection class instance. If the latter, it + is simply returned. If the former, it must correspond to one of the + `PROJ `__ projection name shorthands, like in + basemap. + + The following table lists the valid projection name shorthands, + their full names (with links to the relevant `PROJ documentation + `__), + and whether they are available in the cartopy and basemap packages. + (added) indicates a projection class that ultraplot has "added" to + cartopy using the cartopy API. + + .. _proj_table: + + ============= =============================================== ========= ======= + Key Name Cartopy Basemap + ============= =============================================== ========= ======= + ``'aea'`` `Albers Equal Area `_ ✓ ✓ + ``'aeqd'`` `Azimuthal Equidistant `_ ✓ ✓ + ``'aitoff'`` `Aitoff `_ ✓ (added) ✗ + ``'cass'`` `Cassini-Soldner `_ ✗ ✓ + ``'cea'`` `Cylindrical Equal Area `_ ✗ ✓ + ``'cyl'`` `Cylindrical Equidistant `_ ✓ ✓ + ``'eck1'`` `Eckert I `_ ✓ ✗ + ``'eck2'`` `Eckert II `_ ✓ ✗ + ``'eck3'`` `Eckert III `_ ✓ ✗ + ``'eck4'`` `Eckert IV `_ ✓ ✓ + ``'eck5'`` `Eckert V `_ ✓ ✗ + ``'eck6'`` `Eckert VI `_ ✓ ✗ + ``'eqdc'`` `Equidistant Conic `_ ✓ ✓ + ``'eqc'`` `Cylindrical Equidistant `_ ✓ ✓ + ``'eqearth'`` `Equal Earth `_ ✓ ✗ + ``'europp'`` Euro PP (Europe) ✓ ✗ + ``'gall'`` `Gall Stereographic Cylindrical `_ ✗ ✓ + ``'geos'`` `Geostationary `_ ✓ ✓ + ``'gnom'`` `Gnomonic `_ ✓ ✓ + ``'hammer'`` `Hammer `_ ✓ (added) ✓ + ``'igh'`` `Interrupted Goode Homolosine `_ ✓ ✗ + ``'kav7'`` `Kavrayskiy VII `_ ✓ (added) ✓ + ``'laea'`` `Lambert Azimuthal Equal Area `_ ✓ ✓ + ``'lcc'`` `Lambert Conformal `_ ✓ ✓ + ``'lcyl'`` Lambert Cylindrical ✓ ✗ + ``'mbtfpq'`` `McBryde-Thomas Flat-Polar Quartic `_ ✗ ✓ + ``'merc'`` `Mercator `_ ✓ ✓ + ``'mill'`` `Miller Cylindrical `_ ✓ ✓ + ``'moll'`` `Mollweide `_ ✓ ✓ + ``'npaeqd'`` North-Polar Azimuthal Equidistant ✓ (added) ✓ + ``'npgnom'`` North-Polar Gnomonic ✓ (added) ✗ + ``'nplaea'`` North-Polar Lambert Azimuthal ✓ (added) ✓ + ``'npstere'`` North-Polar Stereographic ✓ ✓ + ``'nsper'`` `Near-Sided Perspective `_ ✓ ✓ + ``'osni'`` OSNI (Ireland) ✓ ✗ + ``'osgb'`` OSGB (UK) ✓ ✗ + ``'omerc'`` `Oblique Mercator `_ ✗ ✓ + ``'ortho'`` `Orthographic `_ ✓ ✓ + ``'pcarree'`` `Cylindrical Equidistant `_ ✓ ✓ + ``'poly'`` `Polyconic `_ ✗ ✓ + ``'rotpole'`` Rotated Pole ✓ ✓ + ``'sinu'`` `Sinusoidal `_ ✓ ✓ + ``'spaeqd'`` South-Polar Azimuthal Equidistant ✓ (added) ✓ + ``'spgnom'`` South-Polar Gnomonic ✓ (added) ✗ + ``'splaea'`` South-Polar Lambert Azimuthal ✓ (added) ✓ + ``'spstere'`` South-Polar Stereographic ✓ ✓ + ``'stere'`` `Stereographic `_ ✓ ✓ + ``'tmerc'`` `Transverse Mercator `_ ✓ ✓ + ``'utm'`` `Universal Transverse Mercator `_ ✓ ✗ + ``'vandg'`` `van der Grinten `_ ✗ ✓ + ``'wintri'`` `Winkel tripel `_ ✓ (added) ✗ + ============= =============================================== ========= ======= + +backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` + Whether to return a cartopy `~cartopy.crs.Projection` instance + or a basemap `~mpl_toolkits.basemap.Basemap` instance. + + .. deprecated:: 3.0.0 + The ``'basemap'`` backend is deprecated and may be removed in a + future release. Please use the ``'cartopy'`` backend instead. +lon0, lat0 : float, optional + The central projection longitude and latitude. These are translated to + `central_longitude`, `central_latitude` for cartopy projections. +lon_0, lat_0 : float, optional + Aliases for `lon0`, `lat0`. +lonlim : 2-tuple of float, optional + The longitude limits. Translated to `min_longitude` and `max_longitude` for + cartopy projections and `llcrnrlon` and `urcrnrlon` for basemap projections. +latlim : 2-tuple of float, optional + The latitude limits. Translated to `min_latitude` and `max_latitude` for + cartopy projections and `llcrnrlon` and `urcrnrlon` for basemap projections. + +Other parameters +---------------- +**kwargs + Passed to the cartopy `~cartopy.crs.Projection` or + basemap `~mpl_toolkits.basemap.Basemap` class. + +Returns +------- +proj : mpl_toolkits.basemap.Basemap or cartopy.crs.Projection + A cartopy or basemap projection instance. + +See also +-------- +mpl_toolkits.basemap.Basemap +cartopy.crs.Projection +ultraplot.ui.subplots +ultraplot.axes.GeoAxes + +References +---------- +For more information on map projections, see the +`wikipedia page `__ and the +`PROJ `__ documentation. + +.. _aea: https://proj.org/operations/projections/aea.html +.. _aeqd: https://proj.org/operations/projections/aeqd.html +.. _aitoff: https://proj.org/operations/projections/aitoff.html +.. _cass: https://proj.org/operations/projections/cass.html +.. _cea: https://proj.org/operations/projections/cea.html +.. _eqc: https://proj.org/operations/projections/eqc.html +.. _eck1: https://proj.org/operations/projections/eck1.html +.. _eck2: https://proj.org/operations/projections/eck2.html +.. _eck3: https://proj.org/operations/projections/eck3.html +.. _eck4: https://proj.org/operations/projections/eck4.html +.. _eck5: https://proj.org/operations/projections/eck5.html +.. _eck6: https://proj.org/operations/projections/eck6.html +.. _eqdc: https://proj.org/operations/projections/eqdc.html +.. _eqc: https://proj.org/operations/projections/eqc.html +.. _eqearth: https://proj.org/operations/projections/eqearth.html +.. _gall: https://proj.org/operations/projections/gall.html +.. _geos: https://proj.org/operations/projections/geos.html +.. _gnom: https://proj.org/operations/projections/gnom.html +.. _hammer: https://proj.org/operations/projections/hammer.html +.. _igh: https://proj.org/operations/projections/igh.html +.. _kav7: https://proj.org/operations/projections/kav7.html +.. _laea: https://proj.org/operations/projections/laea.html +.. _lcc: https://proj.org/operations/projections/lcc.html +.. _mbtfpq: https://proj.org/operations/projections/mbtfpq.html +.. _merc: https://proj.org/operations/projections/merc.html +.. _mill: https://proj.org/operations/projections/mill.html +.. _moll: https://proj.org/operations/projections/moll.html +.. _nsper: https://proj.org/operations/projections/nsper.html +.. _omerc: https://proj.org/operations/projections/omerc.html +.. _ortho: https://proj.org/operations/projections/ortho.html +.. _eqc: https://proj.org/operations/projections/eqc.html +.. _poly: https://proj.org/operations/projections/poly.html +.. _sinu: https://proj.org/operations/projections/sinu.html +.. _stere: https://proj.org/operations/projections/stere.html +.. _tmerc: https://proj.org/operations/projections/tmerc.html +.. _utm: https://proj.org/operations/projections/utm.html +.. _vandg: https://proj.org/operations/projections/vandg.html +.. _wintri: https://proj.org/operations/projections/wintri.html""" + ... diff --git a/ultraplot/demos.pyi b/ultraplot/demos.pyi new file mode 100644 index 000000000..8cf3d2b73 --- /dev/null +++ b/ultraplot/demos.pyi @@ -0,0 +1,294 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Functions for displaying colors and fonts. +""" +from _typeshed import Incomplete +import os +import re +import cycler +import matplotlib.colors as mcolors +import matplotlib.font_manager as mfonts +import numpy as np +from . import colors as pcolors +from . import constructor, ui +from .config import _get_data_folders, rc +from .internals import ic +from .internals import _not_none, _version_mpl, docstring, warnings +from .utils import to_rgb, to_xyz +__all__ = ['show_cmaps', 'show_channels', 'show_colors', 'show_colorspaces', 'show_cycles', 'show_fonts'] +FAMILY_TEXGYRE = ('TeX Gyre Heros', 'TeX Gyre Schola', 'TeX Gyre Bonum', 'TeX Gyre Termes', 'TeX Gyre Pagella', 'TeX Gyre Chorus', 'TeX Gyre Adventor', 'TeX Gyre Cursor') +COLOR_TABLE = {'base': mcolors.BASE_COLORS, 'css4': mcolors.CSS4_COLORS, 'opencolor': pcolors.COLORS_OPEN, 'xkcd': pcolors.COLORS_XKCD} +CYCLE_TABLE = {'Matplotlib defaults': ('default', 'classic'), 'Matplotlib stylesheets': ('colorblind', 'colorblind10', 'tableau', 'ggplot', '538', 'seaborn', 'bmh'), 'ColorBrewer2.0 qualitative': ('Accent', 'Dark2', 'Paired', 'Pastel1', 'Pastel2', 'Set1', 'Set2', 'Set3', 'tab10', 'tab20', 'tab20b', 'tab20c'), 'Other qualitative': ('FlatUI', 'Qual1', 'Qual2')} +CMAP_TABLE = {'Grayscale': ('Greys', 'Mono', 'MonoCycle'), 'Matplotlib sequential': ('viridis', 'plasma', 'inferno', 'magma', 'cividis'), 'Matplotlib cyclic': ('twilight',), 'Seaborn sequential': ('Rocket', 'Flare', 'Mako', 'Crest'), 'Seaborn diverging': ('IceFire', 'Vlag'), 'UltraPlot sequential': ('Fire', 'Stellar', 'Glacial', 'Dusk', 'Marine', 'Boreal', 'Sunrise', 'Sunset'), 'UltraPlot diverging': ('Div', 'NegPos', 'DryWet'), 'Other sequential': ('cubehelix', 'turbo'), 'Other diverging': ('BR', 'ColdHot', 'CoolWarm'), 'cmOcean sequential': ('Oxy', 'Thermal', 'Dense', 'Ice', 'Haline', 'Deep', 'Algae', 'Tempo', 'Speed', 'Turbid', 'Solar', 'Matter', 'Amp'), 'cmOcean diverging': ('Balance', 'Delta', 'Curl'), 'cmOcean cyclic': ('Phase',), 'Scientific colour maps sequential': ('batlow', 'batlowK', 'batlowW', 'devon', 'davos', 'oslo', 'lapaz', 'acton', 'lajolla', 'bilbao', 'tokyo', 'turku', 'bamako', 'nuuk', 'hawaii', 'buda', 'imola', 'oleron', 'bukavu', 'fes'), 'Scientific colour maps diverging': ('roma', 'broc', 'cork', 'vik', 'bam', 'lisbon', 'tofino', 'berlin', 'vanimo'), 'Scientific colour maps cyclic': ('romaO', 'brocO', 'corkO', 'vikO', 'bamO'), 'ColorBrewer2.0 sequential': ('Purples', 'Blues', 'Greens', 'Oranges', 'Reds', 'YlOrBr', 'YlOrRd', 'OrRd', 'PuRd', 'RdPu', 'BuPu', 'PuBu', 'PuBuGn', 'BuGn', 'GnBu', 'YlGnBu', 'YlGn'), 'ColorBrewer2.0 diverging': ('Spectral', 'PiYG', 'PRGn', 'BrBG', 'PuOr', 'RdGY', 'RdBu', 'RdYlBu', 'RdYlGn'), 'SciVisColor blues': ('Blues1', 'Blues2', 'Blues3', 'Blues4', 'Blues5', 'Blues6', 'Blues7', 'Blues8', 'Blues9', 'Blues10', 'Blues11'), 'SciVisColor greens': ('Greens1', 'Greens2', 'Greens3', 'Greens4', 'Greens5', 'Greens6', 'Greens7', 'Greens8'), 'SciVisColor yellows': ('Yellows1', 'Yellows2', 'Yellows3', 'Yellows4'), 'SciVisColor oranges': ('Oranges1', 'Oranges2', 'Oranges3', 'Oranges4'), 'SciVisColor browns': ('Browns1', 'Browns2', 'Browns3', 'Browns4', 'Browns5', 'Browns6', 'Browns7', 'Browns8', 'Browns9'), 'SciVisColor reds': ('Reds1', 'Reds2', 'Reds3', 'Reds4', 'Reds5'), 'SciVisColor purples': ('Purples1', 'Purples2', 'Purples3'), 'MATLAB': ('bone', 'cool', 'copper', 'autumn', 'flag', 'prism', 'jet', 'hsv', 'hot', 'spring', 'summer', 'winter', 'pink', 'gray'), 'GNUplot': ('gnuplot', 'gnuplot2', 'ocean', 'afmhot', 'rainbow'), 'GIST': ('gist_earth', 'gist_gray', 'gist_heat', 'gist_ncar', 'gist_rainbow', 'gist_stern', 'gist_yarg'), 'Other': ('binary', 'bwr', 'brg', 'Wistia', 'CMRmap', 'seismic', 'terrain', 'nipy_spectral', 'tab10', 'tab20', 'tab20b', 'tab20c')} +_colorbar_docstring = ... + +def show_channels(*args: Incomplete, N: Incomplete=100, rgb: Incomplete=False, saturation: Incomplete=True, minhue: Incomplete=0, maxsat: Incomplete=500, width: Incomplete=100, refwidth: Incomplete=1.7) -> Incomplete: + """Show how arbitrary colormap(s) vary with respect to the hue, chroma, +luminance, HSL saturation, and HPL saturation channels, and optionally +the red, blue and green channels. Adapted from `this example `__. + +Parameters +---------- +*args : colormap-spec, default: :rc:`image.cmap` + Positional arguments are colormap names or objects. +N : int, optional + The number of markers to draw for each colormap. +rgb : bool, optional + Whether to also show the red, green, and blue channels in the bottom row. +saturation : bool, optional + Whether to show the HSL and HPL saturation channels alongside the raw chroma. +minhue : float, optional + The minimum hue. This lets you rotate the hue plot cyclically. +maxsat : float, optional + The maximum saturation. Use this to truncate large saturation values. +width : int, optional + The width of each colormap line in points. +refwidth : int or str, optional + The width of each subplot. Passed to `~ultraplot.ui.subplots`. + +Returns +------- +ultraplot.figure.Figure + The figure. +ultraplot.gridspec.SubplotGrid + The subplot grid. + +See also +-------- +show_cmaps +show_colorspaces""" + ... + +def show_colorspaces(*, luminance: Incomplete=None, saturation: Incomplete=None, hue: Incomplete=None, refwidth: Incomplete=2) -> Incomplete: + """Generate hue-saturation, hue-luminance, and luminance-saturation +cross-sections for the HCL, HSL, and HPL colorspaces. + +Parameters +---------- +luminance : float, default: 50 + If passed, saturation-hue cross-sections are drawn for + this luminance. Must be between ``0`` and ``100``. +saturation : float, optional + If passed, luminance-hue cross-sections are drawn for this + saturation. Must be between ``0`` and ``100``. +hue : float, optional + If passed, luminance-saturation cross-sections + are drawn for this hue. Must be between ``0`` and ``360``. +refwidth : str or float, optional + Average width of each subplot. Units are interpreted by + `~ultraplot.utils.units`. + +Returns +------- +ultraplot.figure.Figure + The figure. +ultraplot.gridspec.SubplotGrid + The subplot grid. + +See also +-------- +show_cmaps +show_channels""" + ... + +def _draw_bars(cmaps: Incomplete, *, source: Incomplete, unknown: Incomplete='User', include: Incomplete=None, ignore: Incomplete=None, length: Incomplete=4.0, width: Incomplete=0.2, N: Incomplete=None, rasterized: Incomplete=None) -> Incomplete: + """Draw colorbars for "colormaps" and "color cycles". This is called by +`show_cycles` and `show_cmaps`.""" + ... + +def show_cmaps(*args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Generate a table of the registered colormaps or the input colormaps +categorized by source. Adapted from `this example `__. + +Parameters +---------- +*args : colormap-spec, optional + Colormap names or objects. +N : int, default: :rc:`image.lut` + The number of levels in each colorbar. +unknown : str, default: 'User' + Category name for colormaps that are unknown to ultraplot. + Set this to ``False`` to hide unknown colormaps. +include : str or sequence of str, default: None + Category names to be shown in the table. Use this to limit + the table to a subset of categories. Valid categories are + ``'Grayscale'``, ``'Matplotlib sequential'``, ``'Matplotlib cyclic'``, ``'Seaborn sequential'``, ``'Seaborn diverging'``, ``'UltraPlot sequential'``, ``'UltraPlot diverging'``, ``'Other sequential'``, ``'Other diverging'``, ``'cmOcean sequential'``, ``'cmOcean diverging'``, ``'cmOcean cyclic'``, ``'Scientific colour maps sequential'``, ``'Scientific colour maps diverging'``, ``'Scientific colour maps cyclic'``, ``'ColorBrewer2.0 sequential'``, ``'ColorBrewer2.0 diverging'``, ``'SciVisColor blues'``, ``'SciVisColor greens'``, ``'SciVisColor yellows'``, ``'SciVisColor oranges'``, ``'SciVisColor browns'``, ``'SciVisColor reds'``, ``'SciVisColor purples'``, ``'MATLAB'``, ``'GNUplot'``, ``'GIST'``, ``'Other'``. +ignore : str or sequence of str, default: 'MATLAB', 'GNUplot', 'GIST', 'Other' + Used only if `include` was not passed. Category names to be removed from the + table. Use of the default ignored colormaps is discouraged because they contain + non-uniform color transitions (see the :ref:`user guide `). +length : unit-spec, optional + The length of each colorbar. + If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. +width : float or str, optional + The width of each colorbar. + If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. +rasterized : bool, default: :rc:`colorbar.rasterized` + Whether to rasterize the colorbar solids. This increases rendering + time and decreases file sizes for vector graphics. + +Returns +------- +ultraplot.figure.Figure + The figure. +ultraplot.gridspec.SubplotGrid + The subplot grid. + +See also +-------- +show_colorspaces +show_channels +show_cycles +show_colors +show_fonts""" + ... + +def show_cycles(*args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Generate a table of registered color cycles or the input color cycles +categorized by source. Adapted from `this example `__. + +Parameters +---------- +*args : colormap-spec, optional + Cycle names or objects. +unknown : str, default: 'User' + Category name for cycles that are unknown to ultraplot. + Set this to ``False`` to hide unknown colormaps. +include : str or sequence of str, default: None + Category names to be shown in the table. Use this to limit + the table to a subset of categories. Valid categories are + ``'Matplotlib defaults'``, ``'Matplotlib stylesheets'``, ``'ColorBrewer2.0 qualitative'``, ``'Other qualitative'``. +ignore : str or sequence of str, default: None + Used only if `include` was not passed. Category names to be removed + from the table. +length : unit-spec, optional + The length of each colorbar. + If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. +width : float or str, optional + The width of each colorbar. + If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. +rasterized : bool, default: :rc:`colorbar.rasterized` + Whether to rasterize the colorbar solids. This increases rendering + time and decreases file sizes for vector graphics. + +Returns +------- +ultraplot.figure.Figure + The figure. +ultraplot.gridspec.SubplotGrid + The subplot grid. + +See also +-------- +show_cmaps +show_colors +show_fonts""" + ... + +def _filter_colors(hcl: Incomplete, ihue: Incomplete, nhues: Incomplete, minsat: Incomplete) -> Incomplete: + """Filter colors into categories. + +Parameters +---------- +hcl : tuple + The data. +ihue : int + The hue column. +nhues : int + The total number of hues. +minsat : float + The minimum saturation used for the "grays" column.""" + ... + +def show_colors(*, nhues: Incomplete=17, minsat: Incomplete=10, unknown: Incomplete='User', include: Incomplete=None, ignore: Incomplete=None) -> Incomplete: + """Generate tables of the registered color names. Adapted from +`this example `__. + +Parameters +---------- +nhues : int, optional + The number of breaks between hues for grouping "like colors" in the + color table. +minsat : float, optional + The threshold saturation, between ``0`` and ``100``, for designating + "gray colors" in the color table. +unknown : str, default: 'User' + Category name for color names that are unknown to ultraplot. + Set this to ``False`` to hide unknown color names. +include : str or sequence of str, default: None + Category names to be shown in the table. Use this to limit + the table to a subset of categories. Valid categories are + ``'base'``, ``'css4'``, ``'opencolor'``, ``'xkcd'``. +ignore : str or sequence of str, default: 'CSS4' + Used only if `include` was not passed. Category names to be removed + from the colormap table. + +Returns +------- +ultraplot.figure.Figure + The figure. +ultraplot.gridspec.SubplotGrid + The subplot grid.""" + ... + +def show_fonts(*args: Incomplete, family: Incomplete=None, user: Incomplete=None, text: Incomplete=None, math: Incomplete=False, fallback: Incomplete=False, **kwargs: Incomplete) -> Incomplete: + """Generate a table of fonts. If a glyph for a particular font is unavailable, +it is replaced with the "¤" dummy character. + +Parameters +---------- +*args : str or `~matplotlib.font_manager.FontProperties` + The font specs, font names, or `~matplotlib.font_manager.FontProperties`\\ s + to show. If no positional arguments are passed and the `family` argument is + not passed, then the fonts found in :func:`~ultraplot.config.Configurator.user_folder` + and `~ultraplot.config.Configurator.local_folders` and the *available* + :rcraw:`font.sans-serif` fonts are shown. +family : {'tex-gyre', 'sans-serif', 'serif', 'monospace', 'cursive', 'fantasy'}, optional + The family from which *available* fonts are shown. Default is ``'sans-serif'`` + if no arguments were provided. Otherwise the default is to not show family + fonts. The fonts belonging to each family are listed under :rcraw:`font.serif`, + :rcraw:`font.sans-serif`, :rcraw:`font.monospace`, :rcraw:`font.cursive`, and + :rcraw:`font.fantasy`. The special family ``'tex-gyre'`` includes the + `TeX Gyre `__ fonts. +user : bool, optional + Whether to include fonts in :func:`~ultraplot.config.Configurator.user_folder` and + `~ultraplot.config.Configurator.local_folders` at the top of the table. Default + is ``True`` if called without any arguments and ``False`` otherwise. +text : str, optional + The sample text shown for each font. If not passed then default math or + non-math sample text is used. +math : bool, default: False + Whether the default sample text should show non-math Latin characters or + or math equations and Greek letters. +fallback : bool, default: False + Whether to use the fallback font :rcraw:`mathtext.fallback` for unavailable + characters. If ``False`` the dummy glyph "¤" is shown for missing characters. +**kwargs + Additional font properties passed to `~matplotlib.font_manager.FontProperties`. + Default size is ``12`` and default weight, style, and strength are ``'normal'``. + +Other parameters +---------------- +size : float, default: 12 + The font size. +weight : str, default: 'normal' + The font weight. +style : str, default: 'normal' + The font style. +stretch : str, default: 'normal' + The font stretch. + +Returns +------- +ultraplot.figure.Figure + The figure. +ultraplot.gridspec.SubplotGrid + The subplot grid. + +See also +-------- +show_cmaps +show_cycles +show_colors""" + ... diff --git a/ultraplot/externals/__init__.pyi b/ultraplot/externals/__init__.pyi new file mode 100644 index 000000000..a144a6951 --- /dev/null +++ b/ultraplot/externals/__init__.pyi @@ -0,0 +1,7 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +External utilities adapted for ultraplot. +""" +from _typeshed import Incomplete +from . import hsluv diff --git a/ultraplot/externals/hsluv.pyi b/ultraplot/externals/hsluv.pyi new file mode 100644 index 000000000..8f4823517 --- /dev/null +++ b/ultraplot/externals/hsluv.pyi @@ -0,0 +1,144 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Utilities for converting between colorspaces. Includes the following: + +* `rgb_to_hsl` (same as `matplotlib.colors.rgb_to_hsv`) +* `hsl_to_rgb` (same as `matplotlib.colors.hsv_to_rgb`) +* `hcl_to_rgb` +* `rgb_to_hcl` +* `hsluv_to_rgb` +* `rgb_to_hsluv` +* `hpluv_to_rgb` +* `rgb_to_hpluv` + +Note +---- +This file is adapted from `seaborn +`__ +and `hsluv-python +`__. +For more information on colorspaces see the +`CIULUV specification `__, the +`CIE 1931 colorspace `__, +the `HCL colorspace `__, +and the `HSLuv system `__. +""" +from _typeshed import Incomplete +import math +from colorsys import hls_to_rgb, rgb_to_hls +m = [[3.2406, -1.5372, -0.4986], [-0.9689, 1.8758, 0.0415], [0.0557, -0.204, 1.057]] +m_inv = [[0.4124, 0.3576, 0.1805], [0.2126, 0.7152, 0.0722], [0.0193, 0.1192, 0.9505]] +refX = 0.95047 +refY = 1.0 +refZ = 1.08883 +refU = 0.19784 +refV = 0.46834 +lab_e = 0.008856 +lab_k = 903.3 + +def hsluv_to_rgb(h: Incomplete, s: Incomplete, l: Incomplete) -> Incomplete: + ... + +def hsluv_to_hex(h: Incomplete, s: Incomplete, l: Incomplete) -> Incomplete: + ... + +def rgb_to_hsluv(r: Incomplete, g: Incomplete, b: Incomplete) -> Incomplete: + ... + +def hex_to_hsluv(color: Incomplete) -> Incomplete: + ... + +def hpluv_to_rgb(h: Incomplete, s: Incomplete, l: Incomplete) -> Incomplete: + ... + +def hpluv_to_hex(h: Incomplete, s: Incomplete, l: Incomplete) -> Incomplete: + ... + +def rgb_to_hpluv(r: Incomplete, g: Incomplete, b: Incomplete) -> Incomplete: + ... + +def hex_to_hpluv(color: Incomplete) -> Incomplete: + ... + +def lchuv_to_rgb(l: Incomplete, c: Incomplete, h: Incomplete) -> Incomplete: + ... + +def rgb_to_lchuv(r: Incomplete, g: Incomplete, b: Incomplete) -> Incomplete: + ... + +def hsl_to_rgb(h: Incomplete, s: Incomplete, l: Incomplete) -> tuple[float, float, float]: + ... + +def rgb_to_hsl(r: Incomplete, g: Incomplete, b: Incomplete) -> tuple[float, float, float]: + ... + +def hcl_to_rgb(h: Incomplete, c: Incomplete, l: Incomplete) -> Incomplete: + ... + +def rgb_to_hcl(r: Incomplete, g: Incomplete, b: Incomplete) -> Incomplete: + ... + +def rgb_prepare(triple: Incomplete) -> Incomplete: + ... + +def rgb_to_hex(triple: Incomplete) -> Incomplete: + ... + +def hex_to_rgb(color: Incomplete) -> list[float]: + ... + +def max_chroma(L: Incomplete, H: Incomplete) -> Incomplete: + ... + +def hrad_extremum(L: Incomplete) -> float | None: + ... + +def max_chroma_pastel(L: Incomplete) -> Incomplete: + ... + +def hsluv_to_lchuv(triple: Incomplete) -> Incomplete: + ... + +def lchuv_to_hsluv(triple: Incomplete) -> Incomplete: + ... + +def hpluv_to_lchuv(triple: Incomplete) -> Incomplete: + ... + +def lchuv_to_hpluv(triple: Incomplete) -> Incomplete: + ... + +def dot_product(a: Incomplete, b: Incomplete) -> int: + ... + +def from_linear(c: Incomplete) -> Incomplete: + ... + +def to_linear(c: Incomplete) -> Incomplete: + ... + +def CIExyz_to_rgb(triple: Incomplete) -> Incomplete: + ... + +def rgb_to_CIExyz(triple: Incomplete) -> list[int]: + ... + +def CIEluv_to_lchuv(triple: Incomplete) -> Incomplete: + ... + +def lchuv_to_CIEluv(triple: Incomplete) -> Incomplete: + ... +gamma = 3.0 + +def CIEfunc(t: Incomplete) -> Incomplete: + ... + +def CIEfunc_inverse(t: Incomplete) -> Incomplete: + ... + +def CIExyz_to_CIEluv(triple: Incomplete) -> Incomplete: + ... + +def CIEluv_to_CIExyz(triple: Incomplete) -> Incomplete: + ... diff --git a/ultraplot/figure.pyi b/ultraplot/figure.pyi new file mode 100644 index 000000000..f38fe9294 --- /dev/null +++ b/ultraplot/figure.pyi @@ -0,0 +1,2536 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +The figure class used for all ultraplot figures. +""" +from _typeshed import Incomplete +import functools +import inspect +import os +from contextlib import ExitStack +from typing import Callable, TypeVar, cast +try: + from typing import Any, Iterable, List, Optional, Tuple, Union +except ImportError: + from typing_extensions import Any, Iterable, List, Optional, Tuple, Union +import matplotlib.axes as maxes +import matplotlib.figure as mfigure +import matplotlib.text as mtext +import matplotlib.transforms as mtransforms +import numpy as np +try: + from typing import override +except: + from typing_extensions import override +from . import axes as paxes +from .axes._formatting import axis_format_requires_layout, pop_axis_format_kwargs +from . import constructor +from . import gridspec as pgridspec +from . import legend as plegend +from .config import rc, rc_matplotlib +from .internals import _alias_kwargs, _not_none, _pop_params, _pop_rc, _translate_loc, context, docstring, ic, labels, warnings +from ._layout import _LayoutTransaction +from ._subplots import SubplotManager +from .utils import _Crawler, units +__all__ = ['Figure'] +_F = TypeVar('_F', bound=Callable[..., Any]) + +def _any_not_none(*values: Incomplete) -> Incomplete: + """Return whether at least one value is not ``None``.""" + ... +JOURNAL_SIZES = {'aaas1': '5.5cm', 'aaas2': '12cm', 'agu1': ('95mm', '115mm'), 'agu2': ('190mm', '115mm'), 'agu3': ('95mm', '230mm'), 'agu4': ('190mm', '230mm'), 'ams1': 3.2, 'ams2': 4.5, 'ams3': 5.5, 'ams4': 6.5, 'cop1': '8.3cm', 'cop2': '12cm', 'nat1': '89mm', 'nat2': '183mm', 'pnas1': '8.7cm', 'pnas2': '11.4cm', 'pnas3': '17.8cm'} +_figure_docstring = ... +_subplots_params_docstring = ... +_axes_params_docstring = ... +_subplots_docstring = ... +_subplot_docstring = ... +_axes_docstring = ... +_space_docstring = ... +_figure_semantic_legend_common_docstring = ... +_figure_entrylegend_docstring = ... +_figure_catlegend_docstring = ... +_figure_sizelegend_docstring = ... +_figure_numlegend_docstring = ... +_figure_geolegend_docstring = ... +_save_docstring = ... + +def _get_journal_size(preset: Incomplete) -> Incomplete: + """Return the width and height corresponding to the given preset.""" + ... + +def _add_canvas_preprocessor(canvas: Incomplete, method: Incomplete, cache: Incomplete=False) -> Incomplete: + """Return a pre-processer that can be used to override instance-level +canvas draw() and print_figure() methods. This applies tight layout +and aspect ratio-conserving adjustments and aligns labels. Required +so canvas methods instantiate renderers with the correct dimensions.""" + ... + +def _clear_border_cache(func: _F) -> _F: + """Decorator that clears the border cache after function execution.""" + ... + +class Figure(mfigure.Figure): + """ + The `~matplotlib.figure.Figure` subclass used by ultraplot. + """ + _share_message = "Axis sharing level can be 0 or False (share nothing), 1 or 'labels' or 'labs' (share axis labels), 2 or 'limits' or 'lims' (share axis limits and axis labels), 3 or True (share axis limits, axis labels, and tick labels), 4 or 'all' (share axis labels and tick labels in the same gridspec rows and columns and share axis limits across all subplots), or 'auto' (start unshared and share only compatible axes)." + _space_message = 'To set the left, right, bottom, top, wspace, or hspace gridspec values, pass them as keyword arguments to uplt.figure() or uplt.subplots(). Please note they are now specified in physical units, with strings interpreted by uplt.units() and floats interpreted as font size-widths.' + _tight_message = "ultraplot uses its own tight layout algorithm that is activated by default. To disable it, set uplt.rc['subplots.tight'] to False or pass tight=False to uplt.subplots(). For details, see fig.auto_layout()." + _warn_interactive = True + + def __repr__(self) -> str: + ... + + def __init__(self, *, refnum: Incomplete=None, refaspect: Incomplete=None, refwidth: Incomplete=None, refheight: Incomplete=None, figwidth: Incomplete=None, figheight: Incomplete=None, journal: Incomplete=None, sharex: Incomplete=None, sharey: Incomplete=None, share: Incomplete=None, spanx: Incomplete=None, spany: Incomplete=None, span: Incomplete=None, alignx: Incomplete=None, aligny: Incomplete=None, align: Incomplete=None, left: Incomplete=None, right: Incomplete=None, top: Incomplete=None, bottom: Incomplete=None, wspace: Incomplete=None, hspace: Incomplete=None, space: Incomplete=None, tight: Incomplete=None, outerpad: Incomplete=None, innerpad: Incomplete=None, panelpad: Incomplete=None, wpad: Incomplete=None, hpad: Incomplete=None, pad: Incomplete=None, wequal: Incomplete=None, hequal: Incomplete=None, equal: Incomplete=None, wgroup: Incomplete=None, hgroup: Incomplete=None, group: Incomplete=None, **kwargs: Incomplete) -> None: + """Parameters +---------- +refnum : int, optional + The reference subplot number. The `refwidth`, `refheight`, and `refaspect` + keyword args are applied to this subplot, and the aspect ratio is conserved + for this subplot in the `~Figure.auto_layout`. The default is the first + subplot created in the figure. +refaspect : float or 2-tuple of float, optional + The reference subplot aspect ratio. If scalar, this indicates the width + divided by height. If 2-tuple, this indicates the (width, height). Ignored + if both `figwidth` *and* `figheight` or both `refwidth` *and* `refheight` were + passed. The default value is ``1`` or the "data aspect ratio" if the latter + is explicitly fixed (as with `~ultraplot.axes.PlotAxes.imshow` plots and + `~ultraplot.axes.Axes.GeoAxes` projections; see :func:`~matplotlib.axes.Axes.set_aspect`). +refwidth, refheight : unit-spec, default: :rc:`subplots.refwidth` + The width, height of the reference subplot. + If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + Ignored if `figwidth`, `figheight`, or `figsize` was passed. If you + specify just one, `refaspect` will be respected. +ref, aspect, axwidth, axheight + Aliases for `refnum`, `refaspect`, `refwidth`, `refheight`. + *These may be deprecated in a future release.* +figwidth, figheight : unit-spec, optional + The figure width and height. Default behavior is to use `refwidth`. + If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + If you specify just one, `refaspect` will be respected. +width, height + Aliases for `figwidth`, `figheight`. +figsize : 2-tuple, optional + Tuple specifying the figure ``(width, height)``. +sharex, sharey, share : {0, False, 1, 'labels', 'labs', 2, 'limits', 'lims', 3, True, 4, 'all', 'auto'}, default: :rc:`subplots.share` + The axis sharing "level" for the *x* axis, *y* axis, or both + axes. Options are as follows: + + * ``0`` or ``False``: No axis sharing. This also sets the default `spanx` + and `spany` values to ``False``. + * ``1`` or ``'labels'`` or ``'labs'``: Only draw axis labels on the bottommost + row or leftmost column of subplots. Tick labels still appear on every subplot. + * ``2`` or ``'limits'`` or ``'lims'``: As above but force the axis limits, scales, + and tick locations to be identical. Tick labels still appear on every subplot. + * ``3`` or ``True``: As above but only show the tick labels on the bottommost + row and leftmost column of subplots. + * ``4`` or ``'all'``: As above but also share the axis limits, scales, and + tick locations between subplots not in the same row or column. + * ``'auto'``: Start from level ``3`` and only share axes that are compatible + (for example, mixed cartesian and polar axes are kept unshared). + + Explicit sharing levels (``0`` to ``4`` and aliases) still force sharing + attempts and can emit warnings for incompatible axes. + +spanx, spany, span : bool or {0, 1}, default: :rc:`subplots.span` + Whether to use "spanning" axis labels for the *x* axis, *y* axis, or both + axes. Default is ``False`` if `sharex`, `sharey`, or `share` are ``0`` or + ``False``. When ``True``, a single, centered axis label is used for all axes + with bottom and left edges in the same row or column. This can considerably + redundancy in your figure. "Spanning" labels integrate with "shared" axes. For + example, for a 3-row, 3-column figure, with ``sharey > 1`` and ``spany == True``, + your figure will have 1 y axis label instead of 9 y axis labels. +alignx, aligny, align : bool or {0, 1}, default: :rc:`subplots.align` + Whether to `"align" axis labels `__ + for the *x* axis, *y* axis, or both axes. Aligned labels always appear in the same + row or column. This is ignored if `spanx`, `spany`, or `span` are ``True``. +left, right, top, bottom : unit-spec, default: None + The fixed space between the subplots and the figure edge. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If ``None``, the space is determined automatically based on the tick and + label settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + passed to the figure, the space is determined by the tight layout algorithm. +wspace, hspace, space : unit-spec, default: None + The fixed space between grid columns, rows, or both. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If ``None``, the space is determined automatically based on the font size and axis + sharing settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + passed to the figure, the space is determined by the tight layout algorithm. +tight : bool, default: :rc`subplots.tight` + Whether automatic calls to `~Figure.auto_layout` should include + :ref:`tight layout adjustments `. If you manually specified a spacing + in the call to `~ultraplot.ui.subplots`, it will be used to override the tight + layout spacing. For example, with ``left=1``, the left margin is set to 1 + em-width, while the remaining margin widths are calculated automatically. +wequal, hequal, equal : bool, default: :rc:`subplots.equalspace` + Whether to make the tight layout algorithm apply equal spacing + between columns, rows, or both. +wgroup, hgroup, group : bool, default: :rc:`subplots.groupspace` + Whether to make the tight layout algorithm just consider spaces between + adjacent subplots instead of entire columns and rows of subplots. +outerpad : unit-spec, default: :rc:`subplots.outerpad` + The scalar tight layout padding around the left, right, top, bottom figure edges. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +innerpad : unit-spec, default: :rc:`subplots.innerpad` + The scalar tight layout padding between columns and rows. Synonymous with `pad`. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +panelpad : unit-spec, default: :rc:`subplots.panelpad` + The scalar tight layout padding between subplots and their panels, + colorbars, and legends and between "stacks" of these objects. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +journal : str, optional + String corresponding to an academic journal standard used to control the figure + width `figwidth` and, if specified, the figure height `figheight`. See the below + table. Feel free to add to this table by submitting a pull request. + + .. _journal_table: + + =========== ==================== =============================================================================== + Key Size description Organization + =========== ==================== =============================================================================== + ``'aaas1'`` 1-column `American Association for the Advancement of Science `_ (e.g. *Science*) + ``'aaas2'`` 2-column ” + ``'agu1'`` 1-column `American Geophysical Union `_ + ``'agu2'`` 2-column ” + ``'agu3'`` full height 1-column ” + ``'agu4'`` full height 2-column ” + ``'ams1'`` 1-column `American Meteorological Society `_ + ``'ams2'`` small 2-column ” + ``'ams3'`` medium 2-column ” + ``'ams4'`` full 2-column ” + ``'cop1'`` 1-column `Copernicus Publications `_ (e.g. *The Cryosphere*, *Geoscientific Model Development*) + ``'cop2'`` 2-column ” + ``'nat1'`` 1-column `Nature Research `_ + ``'nat2'`` 2-column ” + ``'pnas1'`` 1-column `Proceedings of the National Academy of Sciences `_ + ``'pnas2'`` 2-column ” + ``'pnas3'`` landscape page ” + =========== ==================== =============================================================================== + + .. _aaas: https://www.sciencemag.org/authors/instructions-preparing-initial-manuscript + .. _agu: https://www.agu.org/Publish-with-AGU/Publish/Author-Resources/Graphic-Requirements + .. _ams: https://www.ametsoc.org/ams/index.cfm/publications/authors/journal-and-bams-authors/figure-information-for-authors/ + .. _cop: https://publications.copernicus.org/for_authors/manuscript_preparation.html#figurestables + .. _nat: https://www.nature.com/nature/for-authors/formatting-guide + .. _pnas: https://www.pnas.org/page/authors/format + +Other parameters +---------------- +rowlabels, collabels, llabels, tlabels, rlabels, blabels + Aliases for `leftlabels` and `toplabels`, and for `leftlabels`, + `toplabels`, `rightlabels`, and `bottomlabels`, respectively. +leftlabels, toplabels, rightlabels, bottomlabels : sequence of str, optional + Labels for the subplots lying along the left, top, right, and + bottom edges of the figure. The length of each list must match + the number of subplots along the corresponding edge. +leftlabelpad, toplabelpad, rightlabelpad, bottomlabelpad : float or unit-spec, default +: :rc:`leftlabel.pad`, :rc:`toplabel.pad`, :rc:`rightlabel.pad`, :rc:`bottomlabel.pad` + The padding between the labels and the axes content. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +leftlabelsharedpad, toplabelsharedpad, rightlabelsharedpad, bottomlabelsharedpad : float or unit-spec, default +: :rc:`leftlabel.sharedpad`, :rc:`toplabel.sharedpad`, :rc:`rightlabel.sharedpad`, :rc:`bottomlabel.sharedpad` + The padding between side labels and a shared spanning axis label on the + same side. The spanning label is placed outside the side labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +leftlabels_kw, toplabels_kw, rightlabels_kw, bottomlabels_kw : dict-like, optional + Additional settings used to update the labels with ``text.update()``. +figtitle + Alias for `suptitle`. +suptitle : str, optional + The figure "super" title, centered between the left edge of the leftmost + subplot and the right edge of the rightmost subplot. +suptitlepad : float, default: :rc:`suptitle.pad` + The padding between the super title and the axes content. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +suptitle_kw : optional + Additional settings used to update the super title with ``text.update()``. +includepanels : bool, default: False + Whether to include panels when aligning figure "super titles" along the top + of the subplot grid and when aligning the `spanx` *x* axis labels and + `spany` *y* axis labels along the sides of the subplot grid. +**kwargs + Passed to `matplotlib.figure.Figure`. + +See also +-------- +Figure.format +ultraplot.ui.figure +ultraplot.ui.subplots +matplotlib.figure.Figure""" + ... + + def _init_figure_size(self, refnum: Incomplete, refaspect: Incomplete, refwidth: Incomplete, refheight: Incomplete, figwidth: Incomplete, figheight: Incomplete, journal: Incomplete) -> Incomplete: + """Resolve figure sizing from reference dimensions, journal presets, +and explicit figure dimensions. Sets sizing attributes on self and +returns the resolved (figwidth, figheight).""" + ... + + def _init_gridspec_params(self, **params: Incomplete) -> None: + """Validate and store gridspec spacing parameters.""" + ... + + def _init_tight_layout(self, tight: Incomplete, kwargs: Incomplete) -> None: + """Configure tight layout, suppressing native matplotlib layout engines.""" + ... + + @staticmethod + def _normalize_share(value: Incomplete) -> Incomplete: + """Normalize a share setting to an integer level and auto flag.""" + ... + + def _init_sharing(self, *, sharex: Incomplete, sharey: Incomplete, share: Incomplete, spanx: Incomplete, spany: Incomplete, span: Incomplete, alignx: Incomplete, aligny: Incomplete, align: Incomplete) -> None: + """Resolve share, span, and align settings.""" + ... + + def _init_figure_state(self, figwidth: Incomplete, figheight: Incomplete, kwargs: Incomplete) -> None: + """Initialize internal state, call matplotlib's Figure.__init__, +set up super labels, and apply initial formatting.""" + ... + + def _init_super_labels(self) -> None: + """Create the figure-level label artists and their style state. + +NOTE: Also called by `clear`, which discards every artist on the figure and +sets ``_suptitle`` to None. The labels must be rebuilt there or the next +``format(suptitle=...)`` raises on the missing artist.""" + ... + + def _invalidate_layout(self, *, reset: Incomplete=False) -> None: + """Mark automatic layout stale, optionally discarding persistent state.""" + ... + + def clear(self, keep_observers: Incomplete=False) -> None: + """Clear the figure, discarding all subplots, panels, and figure-level labels. + +Parameters +---------- +keep_observers : bool, default: False + Whether to retain the figure's observers, e.g. a GUI widget tracking + the axes. + +See also +-------- +matplotlib.figure.Figure.clear""" + ... + + @override + def draw(self, renderer: Incomplete) -> Incomplete: + ... + + @override + def draw_without_rendering(self) -> Incomplete: + """Draw without output while preserving figure dpi state.""" + ... + + def _blit_manager(self, *artists: Incomplete, bbox: Incomplete=None) -> Incomplete: + """Return a manager for efficient updates of changing artists. + +Parameters +---------- +*artists : `~matplotlib.artist.Artist` + Artists that will change between updates. +bbox : `~matplotlib.transforms.Bbox` or object with a ``bbox`` attribute, optional + Region to cache and blit. By default, the union of the artists' + axes bounding boxes is used. + +Returns +------- +`~ultraplot._animation._BlitManager` + Manager that restores the cached static background and redraws only + the supplied artists.""" + ... + + def _is_auto_share_mode(self, which: str) -> bool: + """Return whether a given axis uses auto-share mode.""" + ... + + def _axis_unit_signature(self, ax: Incomplete, which: str) -> tuple[str | None, bytes | str | None] | None: + """Return a lightweight signature for axis unit/converter compatibility.""" + ... + + def _share_axes_compatible(self, ref: Incomplete, other: Incomplete, which: str) -> Incomplete: + """Check whether two axes are compatible for sharing along one axis.""" + ... + + def _warn_incompatible_share(self, which: str, ref: Incomplete, other: Incomplete, reason: str) -> None: + """Warn once per figure for explicit incompatible sharing.""" + ... + + def _partition_share_axes(self, axes: Incomplete, which: str) -> Incomplete: + """Partition a candidate share list into compatible sub-groups.""" + ... + + def _iter_shared_groups(self, which: str, *, panels: bool=True) -> Incomplete: + """Yield unique shared groups for one axis direction.""" + ... + + def _join_shared_group(self, which: str, ref: Incomplete, other: Incomplete) -> None: + """Join an axis to a shared group and copy the shared axis state.""" + ... + + def _refresh_auto_share(self, which: Optional[str]=None) -> None: + """Recompute auto-sharing groups after local axis-state changes.""" + ... + + def _autoscale_shared_limits(self, which: str) -> None: + """Recompute shared data limits for each compatible shared-axis group.""" + ... + + def _snap_axes_to_pixel_grid(self, renderer: Incomplete) -> None: + """Snap visible axes bounds to the renderer pixel grid.""" + ... + + def _find_misaligned_spans(self, axes: List[paxes.Axes], *, tol: float=1e-09) -> List[Tuple[str, int, int, mtransforms.Bbox, mtransforms.Bbox, paxes.Axes]]: + """Identify spanning axes whose actual position differs from their +gridspec slot (e.g. because of an aspect constraint). + +Returns a list of ``(axis, start, stop, slot, pos, ref_ax)`` tuples +where *axis* is ``'y'`` for row-spanning or ``'x'`` for column-spanning.""" + ... + + def _remap_axes_to_span(self, axes: List[paxes.Axes], spans: List[Tuple[str, int, int, mtransforms.Bbox, mtransforms.Bbox, paxes.Axes]], *, tol: float=1e-09) -> None: + """Remap sibling axes so they align with the actual bounds of +spanning axes described by *spans*. Siblings with their own +fixed aspect are skipped since they have independent constraints.""" + ... + + def _align_spanning_axes(self, *, tol: float=1e-09) -> None: + """Align sibling subplots to spanning axes whose actual position +differs from their gridspec slot. + +When a subplot spans multiple rows or columns and is shrunk inside +its slot (e.g. by a fixed aspect ratio), the adjacent subplots keep +their full extent and visibly stick out. This method detects the +mismatch and remaps the sibling positions proportionally.""" + ... + + def _share_ticklabels(self, *, axis: str) -> None: + """Tick label sharing is determined at the figure level. While +each subplot controls the limits, we are dealing with the ticklabels +here as the complexity is easier to deal with. + axis: str 'x' or 'y', row or columns to update""" + ... + + def _label_key_map(self) -> Incomplete: + """Return a mapping for version-dependent label keys for Matplotlib tick params.""" + ... + + def _group_axes_by_axis(self, axes: Incomplete, axis: str) -> Incomplete: + """Group axes by row (x) or column (y). Panels included; invalid subplotspec skipped.""" + ... + + def _compute_baseline_tick_state(self, group_axes: Incomplete, axis: str, label_keys: Incomplete) -> Incomplete: + """Build a baseline ticklabel visibility dict from MAIN axes (panels excluded). +Returns (baseline_dict, skip_group: bool). Emits warnings when encountering +unsupported or mixed subplot types.""" + ... + + def _apply_border_mask(self, axi: Incomplete, baseline: dict, sides: tuple[str, str], outer_axes: Incomplete) -> Incomplete: + """Apply figure-border constraints and panel opposite-side suppression. +Keeps label key mapping per-axis for cartesian.""" + ... + + def _effective_share_level(self, axi: Incomplete, axis: str, sides: tuple[str, str]) -> int: + """Compute the effective share level for an axes, considering panel groups and +adjacent panels. Fixes the original variable leak by checking any relevant side.""" + ... + + def _set_ticklabel_state(self, axi: Incomplete, axis: str, state: dict) -> None: + """Apply the computed ticklabel state to cartesian or geo axes.""" + ... + + def _context_adjusting(self, cache: Incomplete=True) -> Incomplete: + """Prevent re-running auto layout steps due to draws triggered by figure +resizes. Otherwise can get infinite loops.""" + ... + + def _context_authorized(self) -> Incomplete: + """Prevent warning message when internally calling no-op methods. Otherwise +emit warnings to help new users.""" + ... + + @staticmethod + def _parse_backend(backend: Incomplete=None, basemap: Incomplete=None) -> Incomplete: + """Delegate to SubplotManager.""" + ... + + def _parse_proj(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Delegate to SubplotManager.""" + ... + + def _get_align_axes(self, side: Incomplete) -> Incomplete: + """Return the main axes along the edge of the figure. + +For 'left'/'right': select one extreme axis per row (leftmost/rightmost). +For 'top'/'bottom': select one extreme axis per column (topmost/bottommost).""" + ... + + def _get_border_axes(self, *, same_type: Incomplete=False, force_recalculate: Incomplete=False) -> dict[str, list[paxes.Axes]]: + """Identifies axes located on the outer boundaries of the GridSpec layout. + +Returns a dictionary with keys 'top', 'bottom', 'left', 'right', each +containing a list of axes on that border.""" + ... + + def _get_align_coord(self, side: Incomplete, axs: Incomplete, align: Incomplete='center', includepanels: Incomplete=False) -> Incomplete: + """Return the figure coordinate for positioning spanning axis labels or super titles. + +Parameters +---------- +side : str + Side of the figure ('top', 'bottom', 'left', 'right'). +axs : list + List of axes to align across. +align : str, default 'center' + Horizontal alignment for x-axis positioning: 'left', 'center', or 'right'. + For y-axis positioning, always centers regardless of this parameter. +includepanels : bool, default False + Whether to include panel axes in the alignment calculation.""" + ... + + def _get_offset_coord(self, side: Incomplete, axs: Incomplete, renderer: Incomplete, *, pad: Incomplete=None, extra: Incomplete=None, include_subset_titles: Incomplete=True, exclude_spanning_axis_labels: Incomplete=False) -> Incomplete: + """Return the figure coordinate for offsetting super labels and super titles.""" + ... + + def _get_layout_axes_bbox(self, axes: Incomplete, renderer: Incomplete, *, include_subset_titles: Incomplete=True, use_cache: Incomplete=True) -> Incomplete: + """Return an axes bbox using the active relative-outset store.""" + ... + + def _get_layout_tightbbox(self, renderer: Incomplete) -> Incomplete: + """Return the figure tight bbox while reusing relative axes outsets. + +This mirrors matplotlib's ``Figure.get_tightbbox`` but routes axes +measurements through the active relative-outset store.""" + ... + + def _get_renderer(self) -> Incomplete: + """Get a renderer at all costs. See matplotlib's tight_layout.py.""" + ... + + def _add_axes_panel(self, ax: 'paxes.Axes', side: Optional[str]=None, span: Optional[Union[int, Tuple[int, int]]]=None, row: Optional[int]=None, col: Optional[int]=None, rows: Optional[Union[int, Tuple[int, int]]]=None, cols: Optional[Union[int, Tuple[int, int]]]=None, **kwargs: Incomplete) -> 'paxes.Axes': + """Add an axes panel.""" + ... + + def _add_figure_panel(self, side: Optional[str]=None, span: Optional[Union[int, Tuple[int, int]]]=None, row: Optional[int]=None, col: Optional[int]=None, rows: Optional[Union[int, Tuple[int, int]]]=None, cols: Optional[Union[int, Tuple[int, int]]]=None, **kwargs: Incomplete) -> 'paxes.Axes': + """Add a figure panel.""" + ... + + def _add_subplot(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Delegate to SubplotManager.""" + ... + + def _unshare_axes(self) -> None: + ... + + def _toggle_axis_sharing(self, *, which: Incomplete='y', share: Incomplete=True, panels: Incomplete=False, children: Incomplete=False, hidden: Incomplete=False) -> None: + """Share or unshare axes in the figure along a given direction. + +Parameters: +- which: 'x', 'y', 'z', or 'view'. +- share: int indicating the levels (see above) +- panels: Whether to include panel axes. +- children: Whether to include child axes. +- hidden: Whether to include hidden axes.""" + ... + + def _add_subplots(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Delegate to SubplotManager.""" + ... + + def _align_axis_label(self, x: Incomplete) -> None: + """Align *x* and *y* axis labels in the perpendicular and parallel directions.""" + ... + + def _register_share_label_group(self, axes: Incomplete, *, target: Incomplete, source: Incomplete=None) -> None: + """Register an explicit label-sharing group for a subset of axes.""" + ... + + def _register_share_label_group_for_side(self, axes: Incomplete, *, target: Incomplete, side: Incomplete, source: Incomplete=None) -> None: + """Register a single label-sharing group for a given label side.""" + ... + + def _is_share_label_group_member(self, ax: Incomplete, axis: Incomplete) -> bool: + """Return True if the axes belongs to any explicit label-sharing group.""" + ... + + def _has_share_label_groups(self, axis: Incomplete) -> bool: + """Return True if there are any explicit label-sharing groups for an axis.""" + ... + + def _clear_share_label_groups(self, axes: Incomplete=None, *, target: Incomplete=None) -> None: + """Clear explicit label-sharing groups, optionally filtered by axes.""" + ... + + def _apply_share_label_groups(self, axis: Incomplete=None) -> None: + """Apply explicit label-sharing groups, overriding default label sharing.""" + ... + + def _align_super_labels(self, side: Incomplete, renderer: Incomplete) -> None: + """Adjust the position of super labels.""" + ... + + def _align_spanning_axis_labels(self, side: Incomplete, renderer: Incomplete, side_labels: Incomplete) -> None: + """Place spanning axis labels outside figure-level labels on the same side. + +Figure-level side labels describe individual rows or columns, while a +spanning axis label describes the whole group. The latter therefore has +lower visual priority and belongs farther from the axes.""" + ... + + def _align_super_title(self, renderer: Incomplete) -> None: + """Adjust the position of the super title based on user alignment preferences. + +Respects horizontal and vertical alignment settings from suptitle_kw parameters, +while applying sensible defaults when no custom alignment is provided.""" + ... + + @staticmethod + def _deduplicate_axes(axes: Iterable[paxes.Axes]) -> List[paxes.Axes]: + """Resolve panel parents and remove duplicates, preserving order.""" + ... + + @staticmethod + def _normalize_title_alignment(loc: str) -> str: + """Convert a *loc* string to a horizontal alignment for ``Text.set_ha``.""" + ... + + @staticmethod + def _resolve_title_props(fontdict: dict[str, Any] | None, kwargs: dict[str, Any]) -> dict[str, Any]: + """Build the property dict for a title from rc defaults, *fontdict*, +and extra *kwargs*.""" + ... + + def _update_subset_title(self, axes: Iterable[paxes.Axes], title: str | None, *, fontdict: dict[str, Any] | None=None, loc: str | None=None, pad: float | str | None=None, y: float | None=None, **kwargs: Any) -> mtext.Text: + """Create or update a title spanning a subset of subplots.""" + ... + + def _visible_subset_group_axes(self, group: dict[str, Any]) -> List[paxes.Axes]: + """Return visible axes from a subset-title group that belong to this figure.""" + ... + + def _get_subset_title_bbox(self, ax: paxes.Axes, renderer: Incomplete) -> mtransforms.Bbox | None: + """Return the union bbox for shared titles covering the given axes. + +Shared subset titles live above the subset's top edge, so they should +only contribute to the tight bounding boxes for axes that actually touch +that top boundary. Otherwise, multi-row subsets can incorrectly claim +the title as extra inter-row spacing.""" + ... + + def _align_subset_titles(self, renderer: Any) -> None: + """Update the positions of titles spanning subplot subsets.""" + ... + + def _update_axis_label(self, side: Incomplete, axs: Incomplete) -> None: + """Update the aligned axis label for the input axes.""" + ... + + def _update_super_labels(self, side: Incomplete, labels: Incomplete, **kwargs: Incomplete) -> None: + """Assign the figure super labels and update settings.""" + ... + + def _update_super_title(self, title: Incomplete, **kwargs: Incomplete) -> None: + """Assign the figure super title and update settings.""" + ... + + @staticmethod + def _iter_semantic_legend_axes(candidate: Incomplete) -> Incomplete: + """Yield axes objects from nested axis containers.""" + ... + + def _semantic_legend_axes(self, ax: Incomplete=None, ref: Incomplete=None) -> Incomplete: + """Pick an axes instance for semantic legend handle generation.""" + ... + + def entrylegend(self, entries: Incomplete, *, line: Incomplete=None, marker: Incomplete=None, color: Incomplete=None, linestyle: Incomplete=None, linewidth: Incomplete=None, markersize: Incomplete=None, alpha: Incomplete=None, markeredgecolor: Incomplete=None, markeredgewidth: Incomplete=None, markerfacecolor: Incomplete=None, handle_kw: Incomplete=None, add: Incomplete=True, **legend_kwargs: Incomplete) -> Incomplete: + """Build generic semantic legend entries and optionally add a figure legend. + +Parameters +---------- +entries + Entry specifications as handles, style dictionaries, or ``(label, spec)`` + pairs. + +Other parameters +---------------- +**legend_kwargs + Placement and legend styling keywords forwarded to + `~ultraplot.figure.Figure.legend` when ``add=True``. This includes figure legend + placement keywords like ``loc=``, ``ref=``, ``ax=``, ``rows=``, ``cols=``, and + ``span=``. Pass ``add=False`` to return ``(handles, labels)`` without drawing. + +Notes +----- +Handle generation currently reuses the semantic legend builder used by +`~ultraplot.axes.Axes.entrylegend`, then routes the final draw step through +`~ultraplot.figure.Figure.legend`.""" + ... + + def catlegend(self, categories: Incomplete, *, colors: Incomplete=None, markers: Incomplete=None, line: Incomplete=None, linestyle: Incomplete=None, linewidth: Incomplete=None, markersize: Incomplete=None, alpha: Incomplete=None, markeredgecolor: Incomplete=None, markeredgewidth: Incomplete=None, markerfacecolor: Incomplete=None, handle_kw: Incomplete=None, add: Incomplete=True, **legend_kwargs: Incomplete) -> Incomplete: + """Build categorical legend entries and optionally add a figure legend. + +Parameters +---------- +categories + Category labels used to generate legend handles. + +Other parameters +---------------- +**legend_kwargs + Placement and legend styling keywords forwarded to + `~ultraplot.figure.Figure.legend` when ``add=True``. This includes figure legend + placement keywords like ``loc=``, ``ref=``, ``ax=``, ``rows=``, ``cols=``, and + ``span=``. Pass ``add=False`` to return ``(handles, labels)`` without drawing. + +Notes +----- +Handle generation currently reuses the semantic legend builder used by +`~ultraplot.axes.Axes.catlegend`, then routes the final draw step through +`~ultraplot.figure.Figure.legend`.""" + ... + + def sizelegend(self, levels: Incomplete, *, labels: Incomplete=None, color: Incomplete=None, marker: Incomplete=None, area: Incomplete=None, values: Incomplete=None, vmin: Incomplete=None, vmax: Incomplete=None, smin: Incomplete=None, smax: Incomplete=None, area_size: Incomplete=None, absolute_size: Incomplete=None, scale: Incomplete=None, minsize: Incomplete=None, fmt: Incomplete=None, alpha: Incomplete=None, markeredgecolor: Incomplete=None, markeredgewidth: Incomplete=None, markerfacecolor: Incomplete=None, handle_kw: Incomplete=None, add: Incomplete=True, **legend_kwargs: Incomplete) -> Incomplete: + """Build size legend entries and optionally add a figure legend. + +Parameters +---------- +levels + Numeric levels used to generate marker-size entries. +values, vmin, vmax, smin, smax, area_size, absolute_size + Optional scatter-style size scaling controls forwarded to + `~ultraplot.axes.Axes.sizelegend`. When omitted, a compatible UltraPlot + scatter artist can be used to infer the size scale automatically. + +Other parameters +---------------- +**legend_kwargs + Placement and legend styling keywords forwarded to + `~ultraplot.figure.Figure.legend` when ``add=True``. This includes figure legend + placement keywords like ``loc=``, ``ref=``, ``ax=``, ``rows=``, ``cols=``, and + ``span=``. Pass ``add=False`` to return ``(handles, labels)`` without drawing. + +Notes +----- +Handle generation currently reuses the semantic legend builder used by +`~ultraplot.axes.Axes.sizelegend`, then routes the final draw step through +`~ultraplot.figure.Figure.legend`. + +Pass ``labels=[...]`` or ``labels={level: label}`` to override the generated labels.""" + ... + + def numlegend(self, levels: Incomplete=None, *, vmin: Incomplete=None, vmax: Incomplete=None, n: Incomplete=None, cmap: Incomplete=None, norm: Incomplete=None, fmt: Incomplete=None, facecolor: Incomplete=None, edgecolor: Incomplete=None, linewidth: Incomplete=None, linestyle: Incomplete=None, alpha: Incomplete=None, handle_kw: Incomplete=None, add: Incomplete=True, **legend_kwargs: Incomplete) -> Incomplete: + """Build numeric-color legend entries and optionally add a figure legend. + +Parameters +---------- +levels + Numeric levels or number of levels. + +Other parameters +---------------- +**legend_kwargs + Placement and legend styling keywords forwarded to + `~ultraplot.figure.Figure.legend` when ``add=True``. This includes figure legend + placement keywords like ``loc=``, ``ref=``, ``ax=``, ``rows=``, ``cols=``, and + ``span=``. Pass ``add=False`` to return ``(handles, labels)`` without drawing. + +Notes +----- +Handle generation currently reuses the semantic legend builder used by +`~ultraplot.axes.Axes.numlegend`, then routes the final draw step through +`~ultraplot.figure.Figure.legend`.""" + ... + + def geolegend(self, entries: Incomplete, labels: Incomplete=None, *, country_reso: Incomplete=None, country_territories: Incomplete=None, country_proj: Incomplete=None, handlesize: Incomplete=None, facecolor: Incomplete=None, edgecolor: Incomplete=None, linewidth: Incomplete=None, alpha: Incomplete=None, fill: Incomplete=None, add: Incomplete=True, **legend_kwargs: Incomplete) -> Incomplete: + """Build geometry legend entries and optionally add a figure legend. + +Parameters +---------- +entries + Geometry entries (mapping, ``(label, geometry)`` pairs, or geometries). +labels + Optional labels for geometry sequences. + +Other parameters +---------------- +**legend_kwargs + Placement and legend styling keywords forwarded to + `~ultraplot.figure.Figure.legend` when ``add=True``. This includes figure legend + placement keywords like ``loc=``, ``ref=``, ``ax=``, ``rows=``, ``cols=``, and + ``span=``. Pass ``add=False`` to return ``(handles, labels)`` without drawing. + +Notes +----- +Handle generation currently reuses the semantic legend builder used by +`~ultraplot.axes.Axes.geolegend`, then routes the final draw step through +`~ultraplot.figure.Figure.legend`.""" + ... + + def add_axes(self, rect: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Add a non-subplot axes to the figure. + +Parameters +---------- +rect : 4-tuple of float + The (left, bottom, width, height) dimensions of the axes in + figure-relative coordinates. +proj, projection : +str, `cartopy.crs.Projection`, or `~mpl_toolkits.basemap.Basemap`, optional + The map projection specification(s). If ``'cart'`` or ``'cartesian'`` + (the default), a `~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, + a :class:`~ultraplot.axes.PolarAxes` is created. Otherwise, the argument is + interpreted by `~ultraplot.constructor.Proj`, and the result is used + to make a `~ultraplot.axes.GeoAxes` (in this case the argument can be + a `cartopy.crs.Projection` instance, a `~mpl_toolkits.basemap.Basemap` + instance, or a projection name listed in :ref:`this table `). +proj_kw, projection_kw : dict-like, optional + Keyword arguments passed to `~mpl_toolkits.basemap.Basemap` or + cartopy `~cartopy.crs.Projection` classes on instantiation. +backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` + Whether to use `~mpl_toolkits.basemap.Basemap` or + `~cartopy.crs.Projection` for map projections. + + .. deprecated:: 3.0.0 + The ``'basemap'`` backend is deprecated and may be removed in a + future release. Please use the ``'cartopy'`` backend instead. + +Other parameters +---------------- +**kwargs + Passed to the ultraplot class `ultraplot.axes.CartesianAxes`, `ultraplot.axes.PolarAxes`, + `ultraplot.axes.GeoAxes`, or `ultraplot.axes.ThreeAxes`. This can include keyword + arguments for projection-specific ``format`` commands. + +See also +-------- +ultraplot.figure.Figure.subplot +ultraplot.figure.Figure.add_subplot +ultraplot.figure.Figure.subplots +ultraplot.figure.Figure.add_subplots""" + ... + + def add_subplot(self, *args: Incomplete, **kwargs: Incomplete) -> paxes.Axes: + """Add a subplot axes to the figure. + +Parameters +---------- +*args : int, tuple, or `~matplotlib.gridspec.SubplotSpec`, optional + The subplot location specifier. Your options are: + + * A single 3-digit integer argument specifying the number of rows, + number of columns, and gridspec number (using row-major indexing). + * Three positional arguments specifying the number of rows, number of + columns, and gridspec number (int) or number range (2-tuple of int). + * A `~matplotlib.gridspec.SubplotSpec` instance generated by indexing + a ultraplot :class:`~ultraplot.gridspec.GridSpec`. + + For integer input, the implied geometry must be compatible with the implied + geometry from previous calls -- for example, ``fig.add_subplot(331)`` followed + by ``fig.add_subplot(132)`` is valid because the 1 row of the second input can + be tiled into the 3 rows of the the first input, but ``fig.add_subplot(232)`` + will raise an error because 2 rows cannot be tiled into 3 rows. For + `~matplotlib.gridspec.SubplotSpec` input, the `~matplotlig.gridspec.SubplotSpec` + must be derived from the :class:`~ultraplot.gridspec.GridSpec` used in previous calls. + + These restrictions arise because we allocate a single, + unique `~Figure.gridspec` for each figure. +number : int, optional + The axes number used for a-b-c labeling. See `~ultraplot.axes.Axes.format` for + details. By default this is incremented automatically based on the other subplots + in the figure. Use e.g. ``number=None`` or ``number=False`` to ensure the subplot + has no a-b-c label. Note the number corresponding to `a` is ``1``, not ``0``. +autoshare : bool, default: True + Whether to automatically share the *x* and *y* axes with subplots spanning the + same rows and columns based on the figure-wide `sharex` and `sharey` settings. + This has no effect if :rcraw:`subplots.share` is ``False`` or if ``sharex=False`` + or ``sharey=False`` were passed to the figure. +proj, projection : +str, `cartopy.crs.Projection`, or `~mpl_toolkits.basemap.Basemap`, optional + The map projection specification(s). If ``'cart'`` or ``'cartesian'`` + (the default), a `~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, + a :class:`~ultraplot.axes.PolarAxes` is created. Otherwise, the argument is + interpreted by `~ultraplot.constructor.Proj`, and the result is used + to make a `~ultraplot.axes.GeoAxes` (in this case the argument can be + a `cartopy.crs.Projection` instance, a `~mpl_toolkits.basemap.Basemap` + instance, or a projection name listed in :ref:`this table `). +proj_kw, projection_kw : dict-like, optional + Keyword arguments passed to `~mpl_toolkits.basemap.Basemap` or + cartopy `~cartopy.crs.Projection` classes on instantiation. +backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` + Whether to use `~mpl_toolkits.basemap.Basemap` or + `~cartopy.crs.Projection` for map projections. + + .. deprecated:: 3.0.0 + The ``'basemap'`` backend is deprecated and may be removed in a + future release. Please use the ``'cartopy'`` backend instead. + +Other parameters +---------------- +**kwargs + Passed to the ultraplot class `ultraplot.axes.CartesianAxes`, `ultraplot.axes.PolarAxes`, + `ultraplot.axes.GeoAxes`, or `ultraplot.axes.ThreeAxes`. This can include keyword + arguments for projection-specific ``format`` commands. + +See also +-------- +ultraplot.figure.Figure.add_axes +ultraplot.figure.Figure.subplots +ultraplot.figure.Figure.add_subplots""" + ... + + def subplot(self, *args: Incomplete, **kwargs: Incomplete) -> paxes.Axes: + """Add a subplot axes to the figure. + +Parameters +---------- +*args : int, tuple, or `~matplotlib.gridspec.SubplotSpec`, optional + The subplot location specifier. Your options are: + + * A single 3-digit integer argument specifying the number of rows, + number of columns, and gridspec number (using row-major indexing). + * Three positional arguments specifying the number of rows, number of + columns, and gridspec number (int) or number range (2-tuple of int). + * A `~matplotlib.gridspec.SubplotSpec` instance generated by indexing + a ultraplot :class:`~ultraplot.gridspec.GridSpec`. + + For integer input, the implied geometry must be compatible with the implied + geometry from previous calls -- for example, ``fig.add_subplot(331)`` followed + by ``fig.add_subplot(132)`` is valid because the 1 row of the second input can + be tiled into the 3 rows of the the first input, but ``fig.add_subplot(232)`` + will raise an error because 2 rows cannot be tiled into 3 rows. For + `~matplotlib.gridspec.SubplotSpec` input, the `~matplotlig.gridspec.SubplotSpec` + must be derived from the :class:`~ultraplot.gridspec.GridSpec` used in previous calls. + + These restrictions arise because we allocate a single, + unique `~Figure.gridspec` for each figure. +number : int, optional + The axes number used for a-b-c labeling. See `~ultraplot.axes.Axes.format` for + details. By default this is incremented automatically based on the other subplots + in the figure. Use e.g. ``number=None`` or ``number=False`` to ensure the subplot + has no a-b-c label. Note the number corresponding to `a` is ``1``, not ``0``. +autoshare : bool, default: True + Whether to automatically share the *x* and *y* axes with subplots spanning the + same rows and columns based on the figure-wide `sharex` and `sharey` settings. + This has no effect if :rcraw:`subplots.share` is ``False`` or if ``sharex=False`` + or ``sharey=False`` were passed to the figure. +proj, projection : +str, `cartopy.crs.Projection`, or `~mpl_toolkits.basemap.Basemap`, optional + The map projection specification(s). If ``'cart'`` or ``'cartesian'`` + (the default), a `~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, + a :class:`~ultraplot.axes.PolarAxes` is created. Otherwise, the argument is + interpreted by `~ultraplot.constructor.Proj`, and the result is used + to make a `~ultraplot.axes.GeoAxes` (in this case the argument can be + a `cartopy.crs.Projection` instance, a `~mpl_toolkits.basemap.Basemap` + instance, or a projection name listed in :ref:`this table `). +proj_kw, projection_kw : dict-like, optional + Keyword arguments passed to `~mpl_toolkits.basemap.Basemap` or + cartopy `~cartopy.crs.Projection` classes on instantiation. +backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` + Whether to use `~mpl_toolkits.basemap.Basemap` or + `~cartopy.crs.Projection` for map projections. + + .. deprecated:: 3.0.0 + The ``'basemap'`` backend is deprecated and may be removed in a + future release. Please use the ``'cartopy'`` backend instead. + +Other parameters +---------------- +**kwargs + Passed to the ultraplot class `ultraplot.axes.CartesianAxes`, `ultraplot.axes.PolarAxes`, + `ultraplot.axes.GeoAxes`, or `ultraplot.axes.ThreeAxes`. This can include keyword + arguments for projection-specific ``format`` commands. + +See also +-------- +ultraplot.figure.Figure.add_axes +ultraplot.figure.Figure.subplots +ultraplot.figure.Figure.add_subplots""" + ... + + def add_subplots(self, *args: Incomplete, **kwargs: Incomplete) -> pgridspec.SubplotGrid: + """Add an arbitrary grid of subplots to the figure. + +Parameters +---------- +array : `ultraplot.gridspec.GridSpec` or array-like of int, optional + The subplot grid specifier. If a :class:`~ultraplot.gridspec.GridSpec`, one subplot is + drawn for each unique :class:`~ultraplot.gridspec.GridSpec` slot. If a 2D array of integers, + one subplot is drawn for each unique integer in the array. Think of this array as + a "picture" of the subplot grid -- for example, the array ``[[1, 1], [2, 3]]`` + creates one long subplot in the top row, two smaller subplots in the bottom row. + Integers must range from 1 to the number of plots, and ``0`` indicates an + empty space -- for example, ``[[1, 1, 1], [2, 0, 3]]`` creates one long subplot + in the top row with two subplots in the bottom row separated by a space. +nrows, ncols : int, default: 1 + The number of rows and columns in the subplot grid. Ignored + if `array` was passed. Use these arguments for simple subplot grids. +order : {'C', 'F'}, default: 'C' + Whether subplots are numbered in column-major (``'C'``) or row-major (``'F'``) + order. Analogous to `numpy.array` ordering. This controls the order that + subplots appear in the `SubplotGrid` returned by this function, and the order + of subplot a-b-c labels (see `~ultraplot.axes.Axes.format`). +proj, projection : +str, `cartopy.crs.Projection`, or `~mpl_toolkits.basemap.Basemap`, optional + The map projection specification(s). If ``'cart'`` or ``'cartesian'`` + (the default), a `~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, + a :class:`~ultraplot.axes.PolarAxes` is created. Otherwise, the argument is + interpreted by `~ultraplot.constructor.Proj`, and the result is used + to make a `~ultraplot.axes.GeoAxes` (in this case the argument can be + a `cartopy.crs.Projection` instance, a `~mpl_toolkits.basemap.Basemap` + instance, or a projection name listed in :ref:`this table `). + + To use different projections for different subplots, you have + two options: + + * Pass a *list* of projection specifications, one for each subplot. + For example, ``uplt.subplots(ncols=2, proj=('cart', 'robin'))``. + * Pass a *dictionary* of projection specifications, where the + keys are integers or tuples of integers that indicate the projection + to use for the corresponding subplot number(s). If a key is not + provided, the default projection ``'cartesian'`` is used. For example, + ``uplt.subplots(ncols=4, proj={2: 'cyl', (3, 4): 'stere'})`` creates + a figure with a default Cartesian axes for the first subplot, a Mercator + projection for the second subplot, and a Stereographic projection + for the third and fourth subplots. + +proj_kw, projection_kw : dict-like, optional + Keyword arguments passed to `~mpl_toolkits.basemap.Basemap` or + cartopy `~cartopy.crs.Projection` classes on instantiation. + If dictionary of properties, applies globally. If list or dictionary of + dictionaries, applies to specific subplots, as with `proj`. For example, + ``uplt.subplots(ncols=2, proj='cyl', proj_kw=({'lon_0': 0}, {'lon_0': 180})`` + centers the projection in the left subplot on the prime meridian and in the + right subplot on the international dateline. +backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` + Whether to use `~mpl_toolkits.basemap.Basemap` or + `~cartopy.crs.Projection` for map projections. + + .. deprecated:: 3.0.0 + The ``'basemap'`` backend is deprecated and may be removed in a + future release. Please use the ``'cartopy'`` backend instead. + If string, applies to all subplots. If list or dict, applies to specific + subplots, as with `proj`. +left, right, top, bottom : unit-spec, default: None + The fixed space between the subplots and the figure edge. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If ``None``, the space is determined automatically based on the tick and + label settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + passed to the figure, the space is determined by the tight layout algorithm. +wspace, hspace, space : unit-spec or sequence, default: None + The fixed space between grid columns, rows, and both, respectively. If + float, string, or ``None``, this value is expanded into lists of length + ``ncols - 1`` (for `wspace`) or length ``nrows - 1`` (for `hspace`). If + a sequence, its length must match these lengths. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + + For elements equal to ``None``, the space is determined automatically based + on the tick and label settings. If :rcraw:`subplots.tight` is ``True`` or + ``tight=True`` was passed to the figure, the space is determined by the tight + layout algorithm. For example, ``subplots(ncols=3, tight=True, wspace=(2, None))`` + fixes the space between columns 1 and 2 but lets the tight layout algorithm + determine the space between columns 2 and 3. +wratios, hratios : float or sequence, optional + Passed to :class:`~ultraplot.gridspec.GridSpec`, denotes the width and height + ratios for the subplot grid. Length of `wratios` must match the number + of columns, and length of `hratios` must match the number of rows. +width_ratios, height_ratios + Aliases for `wratios`, `hratios`. Included for + consistency with `matplotlib.gridspec.GridSpec`. +wpad, hpad, pad : unit-spec or sequence, optional + The tight layout padding between columns, rows, and both, respectively. + Unlike ``space``, these control the padding between subplot content + (including text, ticks, etc.) rather than subplot edges. As with + ``space``, these can be scalars or arrays optionally containing ``None``. + For elements equal to ``None``, the default is `innerpad`. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +wequal, hequal, equal : bool, default: :rc:`subplots.equalspace` + Whether to make the tight layout algorithm apply equal spacing + between columns, rows, or both. +wgroup, hgroup, group : bool, default: :rc:`subplots.groupspace` + Whether to make the tight layout algorithm just consider spaces between + adjacent subplots instead of entire columns and rows of subplots. +outerpad : unit-spec, default: :rc:`subplots.outerpad` + The scalar tight layout padding around the left, right, top, bottom figure edges. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +innerpad : unit-spec, default: :rc:`subplots.innerpad` + The scalar tight layout padding between columns and rows. Synonymous with `pad`. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +panelpad : unit-spec, default: :rc:`subplots.panelpad` + The scalar tight layout padding between subplots and their panels, + colorbars, and legends and between "stacks" of these objects. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + +Other parameters +---------------- +refnum : int, optional + The reference subplot number. The `refwidth`, `refheight`, and `refaspect` + keyword args are applied to this subplot, and the aspect ratio is conserved + for this subplot in the `~Figure.auto_layout`. The default is the first + subplot created in the figure. +refaspect : float or 2-tuple of float, optional + The reference subplot aspect ratio. If scalar, this indicates the width + divided by height. If 2-tuple, this indicates the (width, height). Ignored + if both `figwidth` *and* `figheight` or both `refwidth` *and* `refheight` were + passed. The default value is ``1`` or the "data aspect ratio" if the latter + is explicitly fixed (as with `~ultraplot.axes.PlotAxes.imshow` plots and + `~ultraplot.axes.Axes.GeoAxes` projections; see :func:`~matplotlib.axes.Axes.set_aspect`). +refwidth, refheight : unit-spec, default: :rc:`subplots.refwidth` + The width, height of the reference subplot. + If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + Ignored if `figwidth`, `figheight`, or `figsize` was passed. If you + specify just one, `refaspect` will be respected. +ref, aspect, axwidth, axheight + Aliases for `refnum`, `refaspect`, `refwidth`, `refheight`. + *These may be deprecated in a future release.* +figwidth, figheight : unit-spec, optional + The figure width and height. Default behavior is to use `refwidth`. + If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + If you specify just one, `refaspect` will be respected. +width, height + Aliases for `figwidth`, `figheight`. +figsize : 2-tuple, optional + Tuple specifying the figure ``(width, height)``. +sharex, sharey, share : {0, False, 1, 'labels', 'labs', 2, 'limits', 'lims', 3, True, 4, 'all', 'auto'}, default: :rc:`subplots.share` + The axis sharing "level" for the *x* axis, *y* axis, or both + axes. Options are as follows: + + * ``0`` or ``False``: No axis sharing. This also sets the default `spanx` + and `spany` values to ``False``. + * ``1`` or ``'labels'`` or ``'labs'``: Only draw axis labels on the bottommost + row or leftmost column of subplots. Tick labels still appear on every subplot. + * ``2`` or ``'limits'`` or ``'lims'``: As above but force the axis limits, scales, + and tick locations to be identical. Tick labels still appear on every subplot. + * ``3`` or ``True``: As above but only show the tick labels on the bottommost + row and leftmost column of subplots. + * ``4`` or ``'all'``: As above but also share the axis limits, scales, and + tick locations between subplots not in the same row or column. + * ``'auto'``: Start from level ``3`` and only share axes that are compatible + (for example, mixed cartesian and polar axes are kept unshared). + + Explicit sharing levels (``0`` to ``4`` and aliases) still force sharing + attempts and can emit warnings for incompatible axes. + +spanx, spany, span : bool or {0, 1}, default: :rc:`subplots.span` + Whether to use "spanning" axis labels for the *x* axis, *y* axis, or both + axes. Default is ``False`` if `sharex`, `sharey`, or `share` are ``0`` or + ``False``. When ``True``, a single, centered axis label is used for all axes + with bottom and left edges in the same row or column. This can considerably + redundancy in your figure. "Spanning" labels integrate with "shared" axes. For + example, for a 3-row, 3-column figure, with ``sharey > 1`` and ``spany == True``, + your figure will have 1 y axis label instead of 9 y axis labels. +alignx, aligny, align : bool or {0, 1}, default: :rc:`subplots.align` + Whether to `"align" axis labels `__ + for the *x* axis, *y* axis, or both axes. Aligned labels always appear in the same + row or column. This is ignored if `spanx`, `spany`, or `span` are ``True``. +left, right, top, bottom : unit-spec, default: None + The fixed space between the subplots and the figure edge. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If ``None``, the space is determined automatically based on the tick and + label settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + passed to the figure, the space is determined by the tight layout algorithm. +wspace, hspace, space : unit-spec, default: None + The fixed space between grid columns, rows, or both. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If ``None``, the space is determined automatically based on the font size and axis + sharing settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + passed to the figure, the space is determined by the tight layout algorithm. +tight : bool, default: :rc`subplots.tight` + Whether automatic calls to `~Figure.auto_layout` should include + :ref:`tight layout adjustments `. If you manually specified a spacing + in the call to `~ultraplot.ui.subplots`, it will be used to override the tight + layout spacing. For example, with ``left=1``, the left margin is set to 1 + em-width, while the remaining margin widths are calculated automatically. +wequal, hequal, equal : bool, default: :rc:`subplots.equalspace` + Whether to make the tight layout algorithm apply equal spacing + between columns, rows, or both. +wgroup, hgroup, group : bool, default: :rc:`subplots.groupspace` + Whether to make the tight layout algorithm just consider spaces between + adjacent subplots instead of entire columns and rows of subplots. +outerpad : unit-spec, default: :rc:`subplots.outerpad` + The scalar tight layout padding around the left, right, top, bottom figure edges. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +innerpad : unit-spec, default: :rc:`subplots.innerpad` + The scalar tight layout padding between columns and rows. Synonymous with `pad`. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +panelpad : unit-spec, default: :rc:`subplots.panelpad` + The scalar tight layout padding between subplots and their panels, + colorbars, and legends and between "stacks" of these objects. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +journal : str, optional + String corresponding to an academic journal standard used to control the figure + width `figwidth` and, if specified, the figure height `figheight`. See the below + table. Feel free to add to this table by submitting a pull request. + + .. _journal_table: + + =========== ==================== =============================================================================== + Key Size description Organization + =========== ==================== =============================================================================== + ``'aaas1'`` 1-column `American Association for the Advancement of Science `_ (e.g. *Science*) + ``'aaas2'`` 2-column ” + ``'agu1'`` 1-column `American Geophysical Union `_ + ``'agu2'`` 2-column ” + ``'agu3'`` full height 1-column ” + ``'agu4'`` full height 2-column ” + ``'ams1'`` 1-column `American Meteorological Society `_ + ``'ams2'`` small 2-column ” + ``'ams3'`` medium 2-column ” + ``'ams4'`` full 2-column ” + ``'cop1'`` 1-column `Copernicus Publications `_ (e.g. *The Cryosphere*, *Geoscientific Model Development*) + ``'cop2'`` 2-column ” + ``'nat1'`` 1-column `Nature Research `_ + ``'nat2'`` 2-column ” + ``'pnas1'`` 1-column `Proceedings of the National Academy of Sciences `_ + ``'pnas2'`` 2-column ” + ``'pnas3'`` landscape page ” + =========== ==================== =============================================================================== + + .. _aaas: https://www.sciencemag.org/authors/instructions-preparing-initial-manuscript + .. _agu: https://www.agu.org/Publish-with-AGU/Publish/Author-Resources/Graphic-Requirements + .. _ams: https://www.ametsoc.org/ams/index.cfm/publications/authors/journal-and-bams-authors/figure-information-for-authors/ + .. _cop: https://publications.copernicus.org/for_authors/manuscript_preparation.html#figurestables + .. _nat: https://www.nature.com/nature/for-authors/formatting-guide + .. _pnas: https://www.pnas.org/page/authors/format +**kwargs + Passed to the ultraplot class `ultraplot.axes.CartesianAxes`, `ultraplot.axes.PolarAxes`, + `ultraplot.axes.GeoAxes`, or `ultraplot.axes.ThreeAxes`. This can include keyword + arguments for projection-specific ``format`` commands. + +Returns +------- +axs : SubplotGrid + The axes instances stored in a `SubplotGrid`. + +See also +-------- +ultraplot.ui.figure +ultraplot.ui.subplots +ultraplot.figure.Figure.subplot +ultraplot.figure.Figure.add_subplot +ultraplot.gridspec.SubplotGrid +ultraplot.axes.Axes""" + ... + + def subplots(self, *args: Incomplete, **kwargs: Incomplete) -> pgridspec.SubplotGrid: + """Add an arbitrary grid of subplots to the figure. + +Parameters +---------- +array : `ultraplot.gridspec.GridSpec` or array-like of int, optional + The subplot grid specifier. If a :class:`~ultraplot.gridspec.GridSpec`, one subplot is + drawn for each unique :class:`~ultraplot.gridspec.GridSpec` slot. If a 2D array of integers, + one subplot is drawn for each unique integer in the array. Think of this array as + a "picture" of the subplot grid -- for example, the array ``[[1, 1], [2, 3]]`` + creates one long subplot in the top row, two smaller subplots in the bottom row. + Integers must range from 1 to the number of plots, and ``0`` indicates an + empty space -- for example, ``[[1, 1, 1], [2, 0, 3]]`` creates one long subplot + in the top row with two subplots in the bottom row separated by a space. +nrows, ncols : int, default: 1 + The number of rows and columns in the subplot grid. Ignored + if `array` was passed. Use these arguments for simple subplot grids. +order : {'C', 'F'}, default: 'C' + Whether subplots are numbered in column-major (``'C'``) or row-major (``'F'``) + order. Analogous to `numpy.array` ordering. This controls the order that + subplots appear in the `SubplotGrid` returned by this function, and the order + of subplot a-b-c labels (see `~ultraplot.axes.Axes.format`). +proj, projection : +str, `cartopy.crs.Projection`, or `~mpl_toolkits.basemap.Basemap`, optional + The map projection specification(s). If ``'cart'`` or ``'cartesian'`` + (the default), a `~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, + a :class:`~ultraplot.axes.PolarAxes` is created. Otherwise, the argument is + interpreted by `~ultraplot.constructor.Proj`, and the result is used + to make a `~ultraplot.axes.GeoAxes` (in this case the argument can be + a `cartopy.crs.Projection` instance, a `~mpl_toolkits.basemap.Basemap` + instance, or a projection name listed in :ref:`this table `). + + To use different projections for different subplots, you have + two options: + + * Pass a *list* of projection specifications, one for each subplot. + For example, ``uplt.subplots(ncols=2, proj=('cart', 'robin'))``. + * Pass a *dictionary* of projection specifications, where the + keys are integers or tuples of integers that indicate the projection + to use for the corresponding subplot number(s). If a key is not + provided, the default projection ``'cartesian'`` is used. For example, + ``uplt.subplots(ncols=4, proj={2: 'cyl', (3, 4): 'stere'})`` creates + a figure with a default Cartesian axes for the first subplot, a Mercator + projection for the second subplot, and a Stereographic projection + for the third and fourth subplots. + +proj_kw, projection_kw : dict-like, optional + Keyword arguments passed to `~mpl_toolkits.basemap.Basemap` or + cartopy `~cartopy.crs.Projection` classes on instantiation. + If dictionary of properties, applies globally. If list or dictionary of + dictionaries, applies to specific subplots, as with `proj`. For example, + ``uplt.subplots(ncols=2, proj='cyl', proj_kw=({'lon_0': 0}, {'lon_0': 180})`` + centers the projection in the left subplot on the prime meridian and in the + right subplot on the international dateline. +backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` + Whether to use `~mpl_toolkits.basemap.Basemap` or + `~cartopy.crs.Projection` for map projections. + + .. deprecated:: 3.0.0 + The ``'basemap'`` backend is deprecated and may be removed in a + future release. Please use the ``'cartopy'`` backend instead. + If string, applies to all subplots. If list or dict, applies to specific + subplots, as with `proj`. +left, right, top, bottom : unit-spec, default: None + The fixed space between the subplots and the figure edge. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If ``None``, the space is determined automatically based on the tick and + label settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + passed to the figure, the space is determined by the tight layout algorithm. +wspace, hspace, space : unit-spec or sequence, default: None + The fixed space between grid columns, rows, and both, respectively. If + float, string, or ``None``, this value is expanded into lists of length + ``ncols - 1`` (for `wspace`) or length ``nrows - 1`` (for `hspace`). If + a sequence, its length must match these lengths. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + + For elements equal to ``None``, the space is determined automatically based + on the tick and label settings. If :rcraw:`subplots.tight` is ``True`` or + ``tight=True`` was passed to the figure, the space is determined by the tight + layout algorithm. For example, ``subplots(ncols=3, tight=True, wspace=(2, None))`` + fixes the space between columns 1 and 2 but lets the tight layout algorithm + determine the space between columns 2 and 3. +wratios, hratios : float or sequence, optional + Passed to :class:`~ultraplot.gridspec.GridSpec`, denotes the width and height + ratios for the subplot grid. Length of `wratios` must match the number + of columns, and length of `hratios` must match the number of rows. +width_ratios, height_ratios + Aliases for `wratios`, `hratios`. Included for + consistency with `matplotlib.gridspec.GridSpec`. +wpad, hpad, pad : unit-spec or sequence, optional + The tight layout padding between columns, rows, and both, respectively. + Unlike ``space``, these control the padding between subplot content + (including text, ticks, etc.) rather than subplot edges. As with + ``space``, these can be scalars or arrays optionally containing ``None``. + For elements equal to ``None``, the default is `innerpad`. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +wequal, hequal, equal : bool, default: :rc:`subplots.equalspace` + Whether to make the tight layout algorithm apply equal spacing + between columns, rows, or both. +wgroup, hgroup, group : bool, default: :rc:`subplots.groupspace` + Whether to make the tight layout algorithm just consider spaces between + adjacent subplots instead of entire columns and rows of subplots. +outerpad : unit-spec, default: :rc:`subplots.outerpad` + The scalar tight layout padding around the left, right, top, bottom figure edges. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +innerpad : unit-spec, default: :rc:`subplots.innerpad` + The scalar tight layout padding between columns and rows. Synonymous with `pad`. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +panelpad : unit-spec, default: :rc:`subplots.panelpad` + The scalar tight layout padding between subplots and their panels, + colorbars, and legends and between "stacks" of these objects. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + +Other parameters +---------------- +refnum : int, optional + The reference subplot number. The `refwidth`, `refheight`, and `refaspect` + keyword args are applied to this subplot, and the aspect ratio is conserved + for this subplot in the `~Figure.auto_layout`. The default is the first + subplot created in the figure. +refaspect : float or 2-tuple of float, optional + The reference subplot aspect ratio. If scalar, this indicates the width + divided by height. If 2-tuple, this indicates the (width, height). Ignored + if both `figwidth` *and* `figheight` or both `refwidth` *and* `refheight` were + passed. The default value is ``1`` or the "data aspect ratio" if the latter + is explicitly fixed (as with `~ultraplot.axes.PlotAxes.imshow` plots and + `~ultraplot.axes.Axes.GeoAxes` projections; see :func:`~matplotlib.axes.Axes.set_aspect`). +refwidth, refheight : unit-spec, default: :rc:`subplots.refwidth` + The width, height of the reference subplot. + If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + Ignored if `figwidth`, `figheight`, or `figsize` was passed. If you + specify just one, `refaspect` will be respected. +ref, aspect, axwidth, axheight + Aliases for `refnum`, `refaspect`, `refwidth`, `refheight`. + *These may be deprecated in a future release.* +figwidth, figheight : unit-spec, optional + The figure width and height. Default behavior is to use `refwidth`. + If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + If you specify just one, `refaspect` will be respected. +width, height + Aliases for `figwidth`, `figheight`. +figsize : 2-tuple, optional + Tuple specifying the figure ``(width, height)``. +sharex, sharey, share : {0, False, 1, 'labels', 'labs', 2, 'limits', 'lims', 3, True, 4, 'all', 'auto'}, default: :rc:`subplots.share` + The axis sharing "level" for the *x* axis, *y* axis, or both + axes. Options are as follows: + + * ``0`` or ``False``: No axis sharing. This also sets the default `spanx` + and `spany` values to ``False``. + * ``1`` or ``'labels'`` or ``'labs'``: Only draw axis labels on the bottommost + row or leftmost column of subplots. Tick labels still appear on every subplot. + * ``2`` or ``'limits'`` or ``'lims'``: As above but force the axis limits, scales, + and tick locations to be identical. Tick labels still appear on every subplot. + * ``3`` or ``True``: As above but only show the tick labels on the bottommost + row and leftmost column of subplots. + * ``4`` or ``'all'``: As above but also share the axis limits, scales, and + tick locations between subplots not in the same row or column. + * ``'auto'``: Start from level ``3`` and only share axes that are compatible + (for example, mixed cartesian and polar axes are kept unshared). + + Explicit sharing levels (``0`` to ``4`` and aliases) still force sharing + attempts and can emit warnings for incompatible axes. + +spanx, spany, span : bool or {0, 1}, default: :rc:`subplots.span` + Whether to use "spanning" axis labels for the *x* axis, *y* axis, or both + axes. Default is ``False`` if `sharex`, `sharey`, or `share` are ``0`` or + ``False``. When ``True``, a single, centered axis label is used for all axes + with bottom and left edges in the same row or column. This can considerably + redundancy in your figure. "Spanning" labels integrate with "shared" axes. For + example, for a 3-row, 3-column figure, with ``sharey > 1`` and ``spany == True``, + your figure will have 1 y axis label instead of 9 y axis labels. +alignx, aligny, align : bool or {0, 1}, default: :rc:`subplots.align` + Whether to `"align" axis labels `__ + for the *x* axis, *y* axis, or both axes. Aligned labels always appear in the same + row or column. This is ignored if `spanx`, `spany`, or `span` are ``True``. +left, right, top, bottom : unit-spec, default: None + The fixed space between the subplots and the figure edge. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If ``None``, the space is determined automatically based on the tick and + label settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + passed to the figure, the space is determined by the tight layout algorithm. +wspace, hspace, space : unit-spec, default: None + The fixed space between grid columns, rows, or both. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If ``None``, the space is determined automatically based on the font size and axis + sharing settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + passed to the figure, the space is determined by the tight layout algorithm. +tight : bool, default: :rc`subplots.tight` + Whether automatic calls to `~Figure.auto_layout` should include + :ref:`tight layout adjustments `. If you manually specified a spacing + in the call to `~ultraplot.ui.subplots`, it will be used to override the tight + layout spacing. For example, with ``left=1``, the left margin is set to 1 + em-width, while the remaining margin widths are calculated automatically. +wequal, hequal, equal : bool, default: :rc:`subplots.equalspace` + Whether to make the tight layout algorithm apply equal spacing + between columns, rows, or both. +wgroup, hgroup, group : bool, default: :rc:`subplots.groupspace` + Whether to make the tight layout algorithm just consider spaces between + adjacent subplots instead of entire columns and rows of subplots. +outerpad : unit-spec, default: :rc:`subplots.outerpad` + The scalar tight layout padding around the left, right, top, bottom figure edges. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +innerpad : unit-spec, default: :rc:`subplots.innerpad` + The scalar tight layout padding between columns and rows. Synonymous with `pad`. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +panelpad : unit-spec, default: :rc:`subplots.panelpad` + The scalar tight layout padding between subplots and their panels, + colorbars, and legends and between "stacks" of these objects. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +journal : str, optional + String corresponding to an academic journal standard used to control the figure + width `figwidth` and, if specified, the figure height `figheight`. See the below + table. Feel free to add to this table by submitting a pull request. + + .. _journal_table: + + =========== ==================== =============================================================================== + Key Size description Organization + =========== ==================== =============================================================================== + ``'aaas1'`` 1-column `American Association for the Advancement of Science `_ (e.g. *Science*) + ``'aaas2'`` 2-column ” + ``'agu1'`` 1-column `American Geophysical Union `_ + ``'agu2'`` 2-column ” + ``'agu3'`` full height 1-column ” + ``'agu4'`` full height 2-column ” + ``'ams1'`` 1-column `American Meteorological Society `_ + ``'ams2'`` small 2-column ” + ``'ams3'`` medium 2-column ” + ``'ams4'`` full 2-column ” + ``'cop1'`` 1-column `Copernicus Publications `_ (e.g. *The Cryosphere*, *Geoscientific Model Development*) + ``'cop2'`` 2-column ” + ``'nat1'`` 1-column `Nature Research `_ + ``'nat2'`` 2-column ” + ``'pnas1'`` 1-column `Proceedings of the National Academy of Sciences `_ + ``'pnas2'`` 2-column ” + ``'pnas3'`` landscape page ” + =========== ==================== =============================================================================== + + .. _aaas: https://www.sciencemag.org/authors/instructions-preparing-initial-manuscript + .. _agu: https://www.agu.org/Publish-with-AGU/Publish/Author-Resources/Graphic-Requirements + .. _ams: https://www.ametsoc.org/ams/index.cfm/publications/authors/journal-and-bams-authors/figure-information-for-authors/ + .. _cop: https://publications.copernicus.org/for_authors/manuscript_preparation.html#figurestables + .. _nat: https://www.nature.com/nature/for-authors/formatting-guide + .. _pnas: https://www.pnas.org/page/authors/format +**kwargs + Passed to the ultraplot class `ultraplot.axes.CartesianAxes`, `ultraplot.axes.PolarAxes`, + `ultraplot.axes.GeoAxes`, or `ultraplot.axes.ThreeAxes`. This can include keyword + arguments for projection-specific ``format`` commands. + +Returns +------- +axs : SubplotGrid + The axes instances stored in a `SubplotGrid`. + +See also +-------- +ultraplot.ui.figure +ultraplot.ui.subplots +ultraplot.figure.Figure.subplot +ultraplot.figure.Figure.add_subplot +ultraplot.gridspec.SubplotGrid +ultraplot.axes.Axes""" + ... + + def auto_layout(self, renderer: Incomplete=None, aspect: Incomplete=None, tight: Incomplete=None, resize: Incomplete=None) -> None: + """Automatically adjust the figure size and subplot positions. This is +triggered automatically whenever the figure is drawn. + +Parameters +---------- +renderer : `~matplotlib.backend_bases.RendererBase`, optional + The renderer. If ``None`` a default renderer will be produced. +aspect : bool, optional + Whether to update the figure size based on the reference subplot aspect + ratio. By default, this is ``True``. This only has an effect if the + aspect ratio is fixed (e.g., due to an image plot or geographic projection). +tight : bool, optional + Whether to update the figuer size and subplot positions according to + a "tight layout". By default, this takes on the value of `tight` passed + to `Figure`. If nothing was passed, it is :rc:`subplots.tight`. +resize : bool, optional + If ``False``, the current figure dimensions are fixed and automatic + figure resizing is disabled. By default, the figure size may change + unless both `figwidth` and `figheight` or `figsize` were passed + to `~Figure.subplots`, `~Figure.set_size_inches` was called manually, + or the figure was resized manually with an interactive backend.""" + ... + + def format(self, axs: Incomplete=None, *, figtitle: Incomplete=None, suptitle: Incomplete=None, suptitle_kw: Incomplete=None, llabels: Incomplete=None, leftlabels: Incomplete=None, leftlabels_kw: Incomplete=None, rlabels: Incomplete=None, rightlabels: Incomplete=None, rightlabels_kw: Incomplete=None, blabels: Incomplete=None, bottomlabels: Incomplete=None, bottomlabels_kw: Incomplete=None, tlabels: Incomplete=None, toplabels: Incomplete=None, toplabels_kw: Incomplete=None, rowlabels: Incomplete=None, collabels: Incomplete=None, includepanels: Incomplete=None, **kwargs: Incomplete) -> None: + """Modify figure-wide labels and call ``format`` for the +input axes. By default the numbered subplots are used. + +Parameters +---------- +axs : sequence of `~ultraplot.axes.Axes`, optional + The axes to format. Default is the numbered subplots. +rowlabels, collabels, llabels, tlabels, rlabels, blabels + Aliases for `leftlabels` and `toplabels`, and for `leftlabels`, + `toplabels`, `rightlabels`, and `bottomlabels`, respectively. +leftlabels, toplabels, rightlabels, bottomlabels : sequence of str, optional + Labels for the subplots lying along the left, top, right, and + bottom edges of the figure. The length of each list must match + the number of subplots along the corresponding edge. +leftlabelpad, toplabelpad, rightlabelpad, bottomlabelpad : float or unit-spec, default +: :rc:`leftlabel.pad`, :rc:`toplabel.pad`, :rc:`rightlabel.pad`, :rc:`bottomlabel.pad` + The padding between the labels and the axes content. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +leftlabelsharedpad, toplabelsharedpad, rightlabelsharedpad, bottomlabelsharedpad : float or unit-spec, default +: :rc:`leftlabel.sharedpad`, :rc:`toplabel.sharedpad`, :rc:`rightlabel.sharedpad`, :rc:`bottomlabel.sharedpad` + The padding between side labels and a shared spanning axis label on the + same side. The spanning label is placed outside the side labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +leftlabels_kw, toplabels_kw, rightlabels_kw, bottomlabels_kw : dict-like, optional + Additional settings used to update the labels with ``text.update()``. +figtitle + Alias for `suptitle`. +suptitle : str, optional + The figure "super" title, centered between the left edge of the leftmost + subplot and the right edge of the rightmost subplot. +suptitlepad : float, default: :rc:`suptitle.pad` + The padding between the super title and the axes content. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +suptitle_kw : optional + Additional settings used to update the super title with ``text.update()``. +includepanels : bool, default: False + Whether to include panels when aligning figure "super titles" along the top + of the subplot grid and when aligning the `spanx` *x* axis labels and + `spany` *y* axis labels along the sides of the subplot grid. + +Important +--------- +`leftlabelpad`, `leftlabelsharedpad`, `toplabelpad`, +`toplabelsharedpad`, `rightlabelpad`, `rightlabelsharedpad`, +`bottomlabelpad`, and `bottomlabelsharedpad` keywords are actually +:ref:`configuration settings `. +We explicitly document these arguments here because it is common to +change them for specific figures. But many :ref:`other configuration +settings ` can be passed to ``format`` too. + +Other parameters +---------------- +title : str or sequence, optional + The axes title. Can optionally be a sequence strings, in which case + the title will be selected from the sequence according to `~Axes.number`. +abc : bool or str or sequence, default: :rc:`abc` + The "a-b-c" subplot label style. Must contain the character `a` or `A`, + for example ``'a.'``, or ``'A'``. If ``True`` then the default style of + ``'a'`` is used. The `a` or ``A`` is replaced with the alphabetic character + matching the `~Axes.number`. If `~Axes.number` is greater than 26, the + characters loop around to a, ..., z, aa, ..., zz, aaa, ..., zzz, etc. + Can also be a sequence of strings, in which case the "a-b-c" label will be selected sequentially from the list. For example `axs.format(abc = ["X", "Y"])` for a two-panel figure, and `axes[3:5].format(abc = ["X", "Y"])` for a two-panel subset of a larger figure. +abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` + Strings indicating the location for the a-b-c label and main title. + The following locations are valid: + + .. _title_table: + + ======================== ============================ + Location Valid keys + ======================== ============================ + center above axes ``'center'``, ``'c'`` + left above axes ``'left'``, ``'l'`` + right above axes ``'right'``, ``'r'`` + lower center inside axes ``'lower center'``, ``'lc'`` + upper center inside axes ``'upper center'``, ``'uc'`` + upper right inside axes ``'upper right'``, ``'ur'`` + upper left inside axes ``'upper left'``, ``'ul'`` + lower left inside axes ``'lower left'``, ``'ll'`` + lower right inside axes ``'lower right'``, ``'lr'`` + left of y axis ``'outer left'``, ``'ol'`` + right of y axis ``'outer right'``, ``'or'`` + ======================== ============================ + +abcborder, titleborder : bool, default: :rc:`abc.border` and :rc:`title.border` + Whether to draw a white border around titles and a-b-c labels positioned + inside the axes. This can help them stand out on top of artists + plotted inside the axes. +abcbbox, titlebbox : bool, default: :rc:`abc.bbox` and :rc:`title.bbox` + Whether to draw a white bbox around titles and a-b-c labels positioned + inside the axes. This can help them stand out on top of artists plotted + inside the axes. +abcpad : float or unit-spec, default: :rc:`abc.pad` + Horizontal offset to shift the a-b-c label position. Positive values move + the label right, negative values move it left. This is separate from + `abctitlepad`, which controls spacing between abc and title when co-located. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +abc_kw, title_kw : dict-like, optional + Additional settings used to update the a-b-c label and title + with ``text.update()``. +titlepad : float, default: :rc:`title.pad` + The padding for the inner and outer titles and a-b-c labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +titleabove : bool, default: :rc:`title.above` + Whether to try to put outer titles and a-b-c labels above panels, + colorbars, or legends that are above the axes. +abctitlepad : float, default: :rc:`abc.titlepad` + The horizontal padding between a-b-c labels and titles in the same location. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle : str or sequence, optional + Shorthands for the below keywords. + lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle : str or sequence, optional +lowerlefttitle, lowercentertitle, lowerrighttitle : str or sequence, optional + Additional titles in specific positions (see `title` for details). This works as + an alternative to the ``ax.format(title='Title', titleloc=loc)`` workflow and + permits adding more than one title-like label for a single axes. +a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle : default: + :rc:`axes.alpha` (default: 1.0), :rc:`axes.facecolor` (default: white), :rc:`axes.edgecolor` (default: black), :rc:`axes.linewidth` (default: 0.6), - + Additional settings applied to the background patch, and their + shorthands. Their defaults values are the ``'axes'`` properties. +aspect : {'auto', 'equal'} or float, optional + The data aspect ratio. See :func:`~matplotlib.axes.Axes.set_aspect` + for details. +xlabel, ylabel : str, optional + The x and y axis labels. Applied with `~matplotlib.axes.Axes.set_xlabel` + and `~matplotlib.axes.Axes.set_ylabel`. +xlabel_kw, ylabel_kw : dict-like, optional + Additional axis label settings applied with `~matplotlib.axes.Axes.set_xlabel` + and `~matplotlib.axes.Axes.set_ylabel`. See also `labelpad`, `labelcolor`, + `labelsize`, and `labelweight` below. +xlim, ylim : 2-tuple of floats or None, optional + The x and y axis data limits. Applied with :func:`~matplotlib.axes.Axes.set_xlim` + and :func:`~matplotlib.axes.Axes.set_ylim`. +xmin, ymin : float, optional + The x and y minimum data limits. Useful if you do not want + to set the maximum limits. +xmax, ymax : float, optional + The x and y maximum data limits. Useful if you do not want + to set the minimum limits. +xreverse, yreverse : bool, optional + Whether to "reverse" the x and y axis direction. Makes the x and + y axes ascend left-to-right and top-to-bottom, respectively. +xscale, yscale : scale-spec, optional + The x and y axis scales. Passed to the `~ultraplot.scale.Scale` constructor. + For example, ``xscale='log'`` applies logarithmic scaling, and + ``xscale=('cutoff', 100, 2)`` applies a `~ultraplot.scale.CutoffScale`. +xscale_kw, yscale_kw : dict-like, optional + The x and y axis scale settings. Passed to `~ultraplot.scale.Scale`. +xmargin, ymargin, margin : float, default: :rc:`margin` + The default margin between plotted content and the x and y axis spines in + axes-relative coordinates. This is useful if you don't witch to explicitly set + axis limits. Use the keyword `margin` to set both at once. +xbounds, ybounds : 2-tuple of float, optional + The x and y axis data bounds within which to draw the spines. For example, + ``xlim=(0, 4)`` combined with ``xbounds=(2, 4)`` will prevent the spines + from meeting at the origin. This also applies ``xspineloc='bottom'`` and + ``yspineloc='left'`` by default if both spines are currently visible. +xtickrange, ytickrange : 2-tuple of float, optional + The x and y axis data ranges within which major tick marks are labelled. + For example, ``xlim=(-5, 5)`` combined with ``xtickrange=(-1, 1)`` and a + tick interval of 1 will only label the ticks marks at -1, 0, and 1. See + `~ultraplot.ticker.AutoFormatter` for details. +xwraprange, ywraprange : 2-tuple of float, optional + The x and y axis data ranges with which major tick mark values are wrapped. For + example, ``xwraprange=(0, 3)`` causes the values 0 through 9 to be formatted as + 0, 1, 2, 0, 1, 2, 0, 1, 2, 0. See `~ultraplot.ticker.AutoFormatter` for details. This + can be combined with `xtickrange` and `ytickrange` to make "stacked" line plots. +xloc, yloc : optional + Shorthands for `xspineloc`, `yspineloc`. +xspineloc, yspineloc : {'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right', 'both', 'neither', 'none', 'zero', 'center'} or 2-tuple, optional + The x and y spine locations. Applied with `~matplotlib.spines.Spine.set_position`. + Propagates to `tickloc` unless specified otherwise. +xtickloc, ytickloc : {'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right', 'both', 'neither', 'none'}, optional + Which x and y axis spines should have major and minor tick marks. Inherits from + `spineloc` by default and propagates to `ticklabelloc` unless specified otherwise. +xticklabelloc, yticklabelloc : {'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right', 'both', 'neither', 'none'}, optional + Which x and y axis spines should have major tick labels. Inherits from `tickloc` + by default and propagates to `labelloc` and `offsetloc` unless specified otherwise. +xlabelloc, ylabelloc : {'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right'}, optional + Which x and y axis spines should have axis labels. Inherits from + `ticklabelloc` by default (if `ticklabelloc` is a single side). +xoffsetloc, yoffsetloc : {'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right'}, optional + Which x and y axis spines should have the axis offset indicator. Inherits from + `ticklabelloc` by default (if `ticklabelloc` is a single side). +xtickdir, ytickdir, tickdir : {'out', 'in', 'inout'}, optional + Direction that major and minor tick marks point for the x and y axis. + Use the keyword `tickdir` to control both. +xticklabeldir, yticklabeldir : {'in', 'out'}, optional + Whether to place x and y axis tick label text inside or outside the axes. + Propagates to `xtickdir` and `ytickdir` unless specified otherwise. +xrotation, yrotation : float, default: 0 + The rotation for x and y axis tick labels. + for normal axes, :rc:`formatter.timerotation` for time x axes. +xgrid, ygrid, grid : bool, default: :rc:`grid` + Whether to draw major gridlines on the x and y axis. + Use the keyword `grid` to toggle both. +xgridminor, ygridminor, gridminor : bool, default: :rc:`gridminor` + Whether to draw minor gridlines for the x and y axis. + Use the keyword `gridminor` to toggle both. +xtickminor, ytickminor, tickminor : bool, default: :rc:`tick.minor` + Whether to draw minor ticks on the x and y axes. + Use the keyword `tickminor` to toggle both. +xticks, yticks : optional + Aliases for `xlocator`, `ylocator`. +xlocator, ylocator : locator-spec, optional + Used to determine the x and y axis tick mark positions. Passed + to the `~ultraplot.constructor.Locator` constructor. Can be float, + list of float, string, or `matplotlib.ticker.Locator` instance. + Use ``[]``, ``'null'``, or ``'none'`` for no ticks. +xlocator_kw, ylocator_kw : dict-like, optional + Keyword arguments passed to the `matplotlib.ticker.Locator` class. +xminorticks, yminorticks : optional + Aliases for `xminorlocator`, `yminorlocator`. +xminorlocator, yminorlocator : optional + As for `xlocator`, `ylocator`, but for the minor ticks. +xminorlocator_kw, yminorlocator_kw + As for `xlocator_kw`, `ylocator_kw`, but for the minor locator. +xticklabels, yticklabels : optional + Aliases for `xformatter`, `yformatter`. +xformatter, yformatter : formatter-spec, optional + Used to determine the x and y axis tick label string format. + Passed to the `~ultraplot.constructor.Formatter` constructor. + Can be string, list of strings, or `matplotlib.ticker.Formatter` instance. + Use ``[]``, ``'null'``, or ``'none'`` for no labels. +xformatter_kw, yformatter_kw : dict-like, optional + Keyword arguments passed to the `matplotlib.ticker.Formatter` class. +xcolor, ycolor, color : color-spec, default: :rc:`meta.color` + Color for the x and y axis spines, ticks, tick labels, and axis labels. + Use the keyword `color` to set both at once. +xgridcolor, ygridcolor, gridcolor : color-spec, default: :rc:`grid.color` + Color for the x and y axis major and minor gridlines. + Use the keyword `gridcolor` to set both at once. +xlinewidth, ylinewidth, linewidth : color-spec, default: :rc:`meta.width` + Line width for the x and y axis spines and major ticks. Propagates to `tickwidth` + unless specified otherwise. Use the keyword `linewidth` to set both at once. +xtickcolor, ytickcolor, tickcolor : color-spec, default: :rc:`tick.color` + Color for the x and y axis ticks. Defaults are `xcolor`, `ycolor`, and `color` + if they were passed. Use the keyword `tickcolor` to set both at once. +xticklen, yticklen, ticklen : unit-spec, default: :rc:`tick.len` + Major tick lengths for the x and y axis. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + Use the keyword `ticklen` to set both at once. +xticklenratio, yticklenratio, ticklenratio : float, default: :rc:`tick.lenratio` + Relative scaling of `xticklen` and `yticklen` used to determine minor + tick lengths. Use the keyword `ticklenratio` to set both at once. +xtickwidth, ytickwidth, tickwidth, : unit-spec, default: :rc:`tick.width` + Major tick widths for the x ans y axis. Default is `linewidth` if it was passed. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + Use the keyword `tickwidth` to set both at once. +xtickwidthratio, ytickwidthratio, tickwidthratio : float, default: :rc:`tick.widthratio` + Relative scaling of `xtickwidth` and `ytickwidth` used to determine + minor tick widths. Use the keyword `tickwidthratio` to set both at once. +xticklabelpad, yticklabelpad, ticklabelpad : unit-spec, default: :rc:`tick.labelpad` + The padding between the x and y axis ticks and tick labels. Use the + keyword `ticklabelpad` to set both at once. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +xticklabelcolor, yticklabelcolor, ticklabelcolor : color-spec, default: :rc:`tick.labelcolor` + Color for the x and y tick labels. Defaults are `xcolor`, `ycolor`, and `color` + if they were passed. Use the keyword `ticklabelcolor` to set both at once. +xticklabelsize, yticklabelsize, ticklabelsize : unit-spec or str, default: :rc:`tick.labelsize` + Font size for the x and y tick labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + Use the keyword `ticklabelsize` to set both at once. +xticklabelweight, yticklabelweight, ticklabelweight : str, default: :rc:`tick.labelweight` + Font weight for the x and y tick labels. + Use the keyword `ticklabelweight` to set both at once. +xlabelpad, ylabelpad : unit-spec, default: :rc:`label.pad` + The padding between the x and y axis bounding box and the x and y axis labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +xlabelcolor, ylabelcolor, labelcolor : color-spec, default: :rc:`label.color` + Color for the x and y axis labels. Defaults are `xcolor`, `ycolor`, and `color` + if they were passed. Use the keyword `labelcolor` to set both at once. +xlabelsize, ylabelsize, labelsize : unit-spec or str, default: :rc:`label.size` + Font size for the x and y axis labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + Use the keyword `labelsize` to set both at once. +xlabelweight, ylabelweight, labelweight : str, default: :rc:`label.weight` + Font weight for the x and y axis labels. + Use the keyword `labelweight` to set both at once. +fixticks : bool, default: False + Whether to transform the tick locators to a `~matplotlib.ticker.FixedLocator`. + If your axis ticks are doing weird things (for example, ticks are drawn + outside of the axis spine) you can try setting this to ``True``. +r0 : float, default: 0 + The radial origin. +theta0 : {'N', 'NW', 'W', 'SW', 'S', 'SE', 'E', 'NE'}, optional + The zero azimuth location. +thetadir : {1, -1, 'anticlockwise', 'counterclockwise', 'clockwise'}, optional + The positive azimuth direction. Clockwise corresponds to + ``-1`` and anticlockwise corresponds to ``1``. +thetamin, thetamax : float, optional + The lower and upper azimuthal bounds in degrees. If + ``thetamax != thetamin + 360``, this produces a sector plot. +thetalim : 2-tuple of float or None, optional + Specifies `thetamin` and `thetamax` at once. +rmin, rmax : float, optional + The inner and outer radial limits. If ``r0 != rmin``, this + produces an annular plot. +rlim : 2-tuple of float or None, optional + Specifies `rmin` and `rmax` at once. +rborder : bool, optional + Whether to draw the polar axes border. Visibility of the "inner" + radial spine and "start" and "end" azimuthal spines is controlled + automatically by matplotlib. +thetagrid, rgrid, grid : bool, optional + Whether to draw major gridlines for the azimuthal and radial axis. + Use the keyword `grid` to toggle both. +thetagridminor, rgridminor, gridminor : bool, optional + Whether to draw minor gridlines for the azimuthal and radial axis. + Use the keyword `gridminor` to toggle both. +thetagridcolor, rgridcolor, gridcolor : color-spec, optional + Color for the major and minor azimuthal and radial gridlines. + Use the keyword `gridcolor` to set both at once. +thetalocator, rlocator : locator-spec, optional + Used to determine the azimuthal and radial gridline positions. + Passed to the `~ultraplot.constructor.Locator` constructor. Can be + float, list of float, string, or `matplotlib.ticker.Locator` instance. +thetalines, rlines + Aliases for `thetalocator`, `rlocator`. +thetalocator_kw, rlocator_kw : dict-like, optional + The azimuthal and radial locator settings. Passed to + `~ultraplot.constructor.Locator`. +thetaminorlocator, rminorlocator : optional + As for `thetalocator`, `rlocator`, but for the minor gridlines. +thetaminorticks, rminorticks : optional + Aliases for `thetaminorlocator`, `rminorlocator`. +thetaminorlocator_kw, rminorlocator_kw + As for `thetalocator_kw`, `rlocator_kw`, but for the minor locator. +rlabelpos : float, optional + The azimuth at which radial coordinates are labeled. Also used as the + spoke angle for ``rlabel`` when you want an explicit radial-label + position. +thetaformatter, rformatter : formatter-spec, optional + Used to determine the azimuthal and radial label format. + Passed to the `~ultraplot.constructor.Formatter` constructor. + Can be string, list of string, or `matplotlib.ticker.Formatter` + instance. Use ``[]``, ``'null'``, or ``'none'`` for no labels. +thetalabels, rlabels : optional + Aliases for `thetaformatter`, `rformatter`. +thetaformatter_kw, rformatter_kw : dict-like, optional + The azimuthal and radial label formatter settings. Passed to + `~ultraplot.constructor.Formatter`. +thetalabel, rlabel : str, optional + Polar-aware axis labels rendered via `~ultraplot.text.CurvedText`. + ``thetalabel`` follows the outer arc just beyond ``r=rmax``. + ``rlabel`` follows a radial spoke, centered between ``rmin`` and + ``rmax``. On a full circle it uses ``get_rlabel_position()`` unless + ``rlabelpos`` is explicit; on a sector it uses the spoke selected by + ``rlabelloc`` unless ``rlabelpos`` is explicit. Both labels include a + built-in tick-clearance offset, and ``labelpad`` adds extra padding in + points on top of that offset. Pass ``""`` to clear a previously set + label. +thetalabelloc : float, optional + Center theta angle (in degrees) for ``thetalabel``. Defaults to the + midpoint of the directed ``thetalim`` interval (or ``0`` for a full + circle). +rlabelloc : {'right', 'left'}, default: 'right' + Where to place ``rlabel``. When the spoke angle is fixed by a full + circle or by explicit ``rlabelpos``, ``rlabelloc`` selects the + perpendicular side of that spoke and ``'left'`` flips the default + side. On a sector with no explicit ``rlabelpos``, ``'right'`` + (default) anchors to ``thetamin`` and ``'left'`` anchors to + ``thetamax``; the label is then offset outward from the sector. +thetalabel_kw, rlabel_kw : dict-like, optional + Additional `~ultraplot.text.CurvedText` settings for the polar-aware + labels (e.g. ``border``, ``bbox``, or rendering hints like + ``min_advance``). See also `labelpad`, `labelcolor`, `labelsize`, + and `labelweight`. +color : color-spec, default: :rc:`meta.color` + Color for the axes edge. Propagates to `labelcolor` unless specified + otherwise (similar to :func:`~ultraplot.axes.CartesianAxes.format`). +labelcolor, gridlabelcolor : color-spec, default: `color` or :rc:`grid.labelcolor` + Color for the gridline labels. +labelpad, gridlabelpad : unit-spec, default: :rc:`grid.labelpad` + The padding between the axes edge and the radial and azimuthal labels. + For ``thetalabel`` and ``rlabel``, this is added on top of the built-in + tick-clearance offset. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +labelsize, gridlabelsize : unit-spec or str, default: :rc:`grid.labelsize` + Font size for the gridline labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +labelweight, gridlabelweight : str, default: :rc:`grid.labelweight` + Font weight for the gridline labels. +aspect : {'auto', 'equal'} or float, optional + The map aspect ratio. ``'auto'`` makes the map fill its subplot slot, which + can be useful for aligning it with neighboring Cartesian axes but distorts + the projection. See :func:`~matplotlib.axes.Axes.set_aspect` for details. +abcanchor : {'axes', 'slot'}, default: 'axes' + The coordinate box used for the a-b-c label. ``'axes'`` attaches it to the + visible map boundary. ``'slot'`` attaches it to the unadjusted GridSpec + slot, keeping labels aligned with neighboring subplots when fixed map + aspect leaves empty space inside a slot. +round : bool, default: :rc:`geo.round` + *For polar cartopy axes only*. + Whether to bound polar projections with circles rather than squares. Note that outer + gridline labels cannot be added to circle-bounded polar projections. When basemap + is the backend this argument must be passed to `~ultraplot.constructor.Proj` instead. +extent : {'globe', 'auto'}, default: :rc:`geo.extent` + *For cartopy axes only*. + Whether to auto adjust the map bounds based on plotted content. If ``'globe'`` then + non-polar projections are fixed with `~cartopy.mpl.geoaxes.GeoAxes.set_global`, + non-Gnomonic polar projections are bounded at the equator, and Gnomonic polar + projections are bounded at 30 degrees latitude. If ``'auto'`` nothing is done. +lonlim, latlim : 2-tuple of float, optional + *For cartopy axes only.* + The approximate longitude and latitude boundaries of the map, applied + with `~cartopy.mpl.geoaxes.GeoAxes.set_extent`. When basemap is the backend + this argument must be passed to `~ultraplot.constructor.Proj` instead. +boundinglat : float, optional + *For cartopy axes only.* + The edge latitude for the circle bounding North Pole and South Pole-centered + projections. When basemap is the backend this argument must be passed to + `~ultraplot.constructor.Proj` instead. +longrid, latgrid, grid : bool, default: :rc:`grid` + Whether to draw longitude and latitude gridlines. + Use the keyword `grid` to toggle both at once. +longridminor, latgridminor, gridminor : bool, default: :rc:`gridminor` + Whether to draw "minor" longitude and latitude lines. + Use the keyword `gridminor` to toggle both at once. +lonticklen, latticklen, ticklen : unit-spec, default: :rc:`tick.len` + Major tick lengths for the longitudinal (x) and latitude (y) axis. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + Use the keyword `ticklen` to set both at once. +latmax : float, default: 80 + The maximum absolute latitude for gridlines. Longitude gridlines are cut off + poleward of this value (note this feature does not work in cartopy 0.18). +nsteps : int, default: :rc:`grid.nsteps` + *For cartopy axes only.* + The number of interpolation steps used to draw gridlines. +lonlocator, latlocator : locator-spec, optional + Used to determine the longitude and latitude gridline locations. + Aliases: ``lonlines`` and ``latlines``, respectively. + Passed to the `~ultraplot.constructor.Locator` constructor. Can be + string, float, list of float, or `matplotlib.ticker.Locator` instance. + + For basemap or cartopy < 0.18, the defaults are ``'deglon'`` and + ``'deglat'``, which correspond to the `~ultraplot.ticker.LongitudeLocator` + and `~ultraplot.ticker.LatitudeLocator` locators (adapted from cartopy). + For cartopy >= 0.18, the defaults are ``'dmslon'`` and ``'dmslat'``, + which uses the same locators with ``dms=True``. This selects gridlines + at nice degree-minute-second intervals when the map extent is very small. +lonlocator_kw, latlocator_kw : dict-like, optional + Keyword arguments passed to the `matplotlib.ticker.Locator` class. + Aliases: ``lonlines_kw`` and ``latlines_kw``, respectively. +lonminorlocator, latminorlocator : optional + As with `lonlocator` and `latlocator` but for the "minor" gridlines. + Aliases: ``lonminorlines`` and ``latminorlines``, respectively. +lonminorlocator_kw, latminorlocator_kw : optional + As with `lonlocator_kw`, and `latlocator_kw` but for the "minor" gridlines. + Aliases: ``lonminorlines_kw`` and ``latminorlines_kw``, respectively. +lonlabels, latlabels, labels : str, bool, or sequence, :rc:`grid.labels` + Whether to add non-inline longitude and latitude gridline labels, and on + which sides of the map. Use the keyword `labels` to set both at once. The + argument must conform to one of the following options: + + * A boolean. ``True`` indicates the bottom side for longitudes and + the left side for latitudes, and ``False`` disables all labels. + * A string or sequence of strings indicating the side names, e.g. + ``'top'`` for longitudes or ``('left', 'right')`` for latitudes. + * A string indicating the side names with single characters, e.g. + ``'bt'`` for longitudes or ``'lr'`` for latitudes. + * A string matching ``'neither'`` (no labels), ``'both'`` (equivalent + to ``'bt'`` for longitudes and ``'lr'`` for latitudes), or ``'all'`` + (equivalent to ``'lrbt'``, i.e. all sides). + * A boolean 2-tuple indicating whether to draw labels + on the ``(bottom, top)`` sides for longitudes, + and the ``(left, right)`` sides for latitudes. + * A boolean 4-tuple indicating whether to draw labels on the + ``(left, right, bottom, top)`` sides, as with the basemap + :func:`~mpl_toolkits.basemap.Basemap.drawmeridians` and + :func:`~mpl_toolkits.basemap.Basemap.drawparallels` `labels` keyword. + +loninline, latinline, inlinelabels : bool, default: :rc:`grid.inlinelabels` + *For cartopy axes only.* + Whether to add inline longitude and latitude gridline labels. Use + the keyword `inlinelabels` to set both at once. +rotatelabels : bool, default: :rc:`grid.rotatelabels` + *For cartopy axes only.* + Whether to rotate non-inline gridline labels so that they automatically + follow the map boundary curvature. +labelrotation : float, optional + The rotation angle in degrees for both longitude and latitude tick labels. + Use `lonlabelrotation` and `latlabelrotation` to set them separately. +lonlabelrotation : float, optional + The rotation angle in degrees for longitude tick labels. + Works for both cartopy and basemap backends. +latlabelrotation : float, optional + The rotation angle in degrees for latitude tick labels. + Works for both cartopy and basemap backends. +labelpad : unit-spec, default: :rc:`grid.labelpad` + *For cartopy axes only.* + The padding between non-inline gridline labels and the map boundary. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +dms : bool, default: :rc:`grid.dmslabels` + *For cartopy axes only.* + Whether the default locators and formatters should use "minutes" and "seconds" + for gridline labels on small scales rather than decimal degrees. Setting this to + ``False`` is equivalent to ``ax.format(lonlocator='deglon', latlocator='deglat')`` + and ``ax.format(lonformatter='deglon', latformatter='deglat')``. +lonformatter, latformatter : formatter-spec, optional + Formatter used to style longitude and latitude gridline labels. + Passed to the `~ultraplot.constructor.Formatter` constructor. Can be + string, list of string, or `matplotlib.ticker.Formatter` instance. + + For basemap or cartopy < 0.18, the defaults are ``'deglon'`` and + ``'deglat'``, which correspond to `~ultraplot.ticker.SimpleFormatter` + presets with degree symbols and cardinal direction suffixes. + For cartopy >= 0.18, the defaults are ``'dmslon'`` and ``'dmslat'``, + which uses cartopy's `~cartopy.mpl.ticker.LongitudeFormatter` and + `~cartopy.mpl.ticker.LatitudeFormatter` formatters with ``dms=True``. + This formats gridlines that do not fall on whole degrees as "minutes" and + "seconds" rather than decimal degrees. Use ``dms=False`` to disable this. +lonformatter_kw, latformatter_kw : dict-like, optional + Keyword arguments passed to the `matplotlib.ticker.Formatter` class. +land, ocean, coast, rivers, lakes, borders, innerborders : bool, optional + Toggles various geographic features. These are actually the + :rcraw:`land`, :rcraw:`ocean`, :rcraw:`coast`, :rcraw:`rivers`, + :rcraw:`lakes`, :rcraw:`borders`, and :rcraw:`innerborders` + settings passed to `~ultraplot.config.Configurator.context`. + The style can be modified using additional `rc` settings. + + For example, to change :rcraw:`land.color`, use + ``ax.format(landcolor='green')``, and to change + :rcraw:`land.zorder`, use ``ax.format(landzorder=4)``. +reso : {'lo', 'med', 'hi', 'x-hi', 'xx-hi'}, optional + *For cartopy axes only.* + The resolution of geographic features. When basemap is the backend this + must be passed to `~ultraplot.constructor.Proj` instead. +color : color-spec, default: :rc:`meta.color` + The color for the axes edge. Propagates to `labelcolor` unless specified + otherwise (similar to :func:`~ultraplot.axes.CartesianAxes.format`). +gridcolor : color-spec, default: :rc:`grid.color` + The color for the gridline labels. +labelcolor : color-spec, default: `color` or :rc:`grid.labelcolor` + The color for the gridline labels (`gridlabelcolor` is also allowed). +labelsize : unit-spec or str, default: :rc:`grid.labelsize` + The font size for the gridline labels (`gridlabelsize` is also allowed). + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +labelweight : str, default: :rc:`grid.labelweight` + The font weight for the gridline labels (`gridlabelweight` is also allowed). +rc_mode : int, optional + The context mode passed to `~ultraplot.config.Configurator.context`. +rc_kw : dict-like, optional + An alternative to passing extra keyword arguments. See below. +**kwargs + Keyword arguments that match the name of an `~ultraplot.config.rc` setting are + passed to `ultraplot.config.Configurator.context` and used to update the axes. + If the setting name has "dots" you can simply omit the dots. For example, + ``abc='A.'`` modifies the :rcraw:`abc` setting, ``titleloc='left'`` modifies the + :rcraw:`title.loc` setting, ``gridminor=True`` modifies the :rcraw:`gridminor` + setting, and ``gridbelow=True`` modifies the :rcraw:`grid.below` setting. Many + of the keyword arguments documented above are internally applied by retrieving + settings passed to `~ultraplot.config.Configurator.context`. + +See also +-------- +ultraplot.axes.Axes.format +ultraplot.axes.CartesianAxes.format +ultraplot.axes.PolarAxes.format +ultraplot.axes.GeoAxes.format +ultraplot.gridspec.SubplotGrid.format +ultraplot.config.Configurator.context""" + ... + + def colorbar(self, mappable: Incomplete, values: Incomplete=None, loc: Optional[str]=None, location: Optional[str]=None, row: Optional[int]=None, col: Optional[int]=None, rows: Optional[Union[int, Tuple[int, int]]]=None, cols: Optional[Union[int, Tuple[int, int]]]=None, span: Optional[Union[int, Tuple[int, int]]]=None, space: Optional[Union[float, str]]=None, pad: Optional[Union[float, str]]=None, width: Optional[Union[float, str]]=None, **kwargs: Incomplete) -> Incomplete: + """Add a colorbar along the side of the figure. + +Parameters +---------- + mappable : mappable, colormap-spec, sequence of color-spec, + or sequence of :class:`~matplotlib.artist.Artist` + There are four options here: + + 1. A `~matplotlib.cm.ScalarMappable` (e.g., an object returned by + `~ultraplot.axes.PlotAxes.contourf` or `~ultraplot.axes.PlotAxes.pcolormesh`). + 2. A `~matplotlib.colors.Colormap` or registered colormap name used to build a + `~matplotlib.cm.ScalarMappable` on-the-fly. The colorbar range and ticks depend + on the arguments `values`, `vmin`, `vmax`, and `norm`. The default for a + :class:`~ultraplot.colors.ContinuousColormap` is ``vmin=0`` and ``vmax=1`` (note that + passing `values` will "discretize" the colormap). The default for a + :class:`~ultraplot.colors.DiscreteColormap` is ``values=np.arange(0, cmap.N)``. + 3. A sequence of hex strings, color names, or RGB[A] tuples. A + :class:`~ultraplot.colors.DiscreteColormap` will be generated from these colors and + used to build a `~matplotlib.cm.ScalarMappable` on-the-fly. The colorbar + range and ticks depend on the arguments `values`, `norm`, and + `norm_kw`. The default is ``values=np.arange(0, len(mappable))``. + 4. A sequence of `matplotlib.artist.Artist` instances (e.g., a list of + `~matplotlib.lines.Line2D` instances returned by `~ultraplot.axes.PlotAxes.plot`). + A colormap will be generated from the colors of these objects (where the + color is determined by ``get_color``, if available, or ``get_facecolor``). + The colorbar range and ticks depend on the arguments `values`, `norm`, and + `norm_kw`. The default is to infer colorbar ticks and tick labels + by calling `~matplotlib.artist.Artist.get_label` on each artist. + + values : sequence of float or str, optional + Ignored if `mappable` is a `~matplotlib.cm.ScalarMappable`. This maps the colormap + colors to numeric values using `~ultraplot.colors.DiscreteNorm`. If the colormap is + a :class:`~ultraplot.colors.ContinuousColormap` then its colors will be "discretized". + These These can also be strings, in which case the list indices are used for + tick locations and the strings are applied as tick labels. +length : float, default: :rc:`colorbar.length` + The colorbar length. Units are relative to the span of the rows and + columns of subplots. +shrink : float, optional + Alias for `length`. This is included for consistency with + `matplotlib.figure.Figure.colorbar`. +width : unit-spec, default: :rc:`colorbar.width` + The colorbar width. + If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. +loc : str, optional + The colorbar location. Valid location keys are as follows. + + ========== ===================== + Location Valid keys + ========== ===================== + left ``'left'``, ``'l'`` + right ``'right'``, ``'r'`` + bottom ``'bottom'``, ``'b'`` + top ``'top'``, ``'t'`` + ========== ===================== + +space : float or str, default: None + The fixed space between the colorbar and the subplot grid edge. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + When the :ref:`tight layout algorithm ` is active for the figure, + `space` is computed automatically (see `pad`). Otherwise, `space` is set to + a suitable default. +pad : float or str, default: :rc:`subplots.innerpad` or :rc:`subplots.panelpad` + The :ref:`tight layout padding ` between the colorbar and the + subplot grid. Default is :rcraw:`subplots.innerpad` for the first colorbar + and :rcraw:`subplots.panelpad` for subsequently "stacked" colorbars. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +row, rows + Aliases for `span` for colorbars on the left or right side. +col, cols + Aliases for `span` for colorbars on the top or bottom side. +span : int or 2-tuple of int, default: None + Integer(s) indicating the span of the colorbar across rows and columns of + subplots. For example, ``fig.colorbar(loc='b', col=1)`` draws a colorbar beneath + the leftmost column of subplots, and ``fig.colorbar(loc='b', cols=(1, 2))`` + draws a colorbar beneath the left two columns of subplots. By default + the colorbar will span every subplot row and column. +align : {'center', 'top', 't', 'bottom', 'b', 'left', 'l', 'right', 'r'}, optional + For outer colorbars only. How to align the colorbar against the + subplot edge. The values ``'top'`` and ``'bottom'`` are valid for left and + right colorbars and ``'left'`` and ``'right'`` are valid for top and bottom + colorbars. The default is always ``'center'``. + Has no visible effect if `length` is ``1``. + +Other parameters +---------------- +orientation : {None, 'horizontal', 'vertical'}, optional + The colorbar orientation. By default this depends on the "side" of the subplot + or figure where the colorbar is drawn. Inset colorbars are always horizontal. +norm : norm-spec, optional + Ignored if `mappable` is a `~matplotlib.cm.ScalarMappable`. This is the continuous + normalizer used to scale the :class:`~ultraplot.colors.ContinuousColormap` (or passed + to `~ultraplot.colors.DiscreteNorm` if `values` was passed). Passed to the + `~ultraplot.constructor.Norm` constructor function. +norm_kw : dict-like, optional + Ignored if `mappable` is a `~matplotlib.cm.ScalarMappable`. These are the + normalizer keyword arguments. Passed to `~ultraplot.constructor.Norm`. +vmin, vmax : float, optional + Ignored if `mappable` is a `~matplotlib.cm.ScalarMappable`. These are the minimum + and maximum colorbar values. Passed to `~ultraplot.constructor.Norm`. +label, title : str, optional + The colorbar label. The `title` keyword is also accepted for + consistency with `~matplotlib.axes.Axes.legend`. +reverse : bool, optional + Whether to reverse the direction of the colorbar. This is done automatically + when descending levels are used with `~ultraplot.colors.DiscreteNorm`. +rotation : float, default: 0 + The tick label rotation. +grid, edges, drawedges : bool, default: :rc:`colorbar.grid` + Whether to draw "grid" dividers between each distinct color. +extend : {'neither', 'both', 'min', 'max'}, optional + Direction for drawing colorbar "extensions" (i.e. color keys for out-of-bounds + data on the end of the colorbar). Default behavior is to use the value of `extend` + passed to the plotting command or use ``'neither'`` if the value is unknown. +extendfrac : float, optional + The length of the colorbar "extensions" relative to the length of the colorbar. + This is a native matplotlib `~matplotlib.figure.Figure.colorbar` keyword. +extendsize : unit-spec, default: :rc:`colorbar.extend` or :rc:`colorbar.insetextend` + The length of the colorbar "extensions" in physical units. Default is + :rcraw:`colorbar.extend` for outer colorbars and :rcraw:`colorbar.insetextend` + for inset colorbars. If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +extendrect : bool, default: False + Whether to draw colorbar "extensions" as rectangles. If ``False`` then + the extensions are drawn as triangles. +locator, ticks : locator-spec, optional + Used to determine the colorbar tick positions. Passed to the + `~ultraplot.constructor.Locator` constructor function. By default + `~matplotlib.ticker.AutoLocator` is used for continuous color levels + and `~ultraplot.ticker.DiscreteLocator` is used for discrete color levels. +locator_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Locator` class. +minorlocator, minorticks + As with `locator`, `ticks` but for the minor ticks. By default + `~matplotlib.ticker.AutoMinorLocator` is used for continuous color levels + and `~ultraplot.ticker.DiscreteLocator` is used for discrete color levels. +minorlocator_kw + As with `locator_kw`, but for the minor ticks. +format, formatter, ticklabels : formatter-spec, optional + The tick label format. Passed to the `~ultraplot.constructor.Formatter` + constructor function. +formatter_kw : dict-like, optional + Keyword arguments passed to `matplotlib.ticker.Formatter` class. +frame, frameon : bool, optional + For inset colorbars, indicates whether to draw a background "frame", + just like `~matplotlib.axes.Axes.legend`. Defaults to + :rc:`colorbar.frameon` for inset colorbars. For outer colorbars, this is a + backwards-compatible alias for `outline`; when omitted, outer colorbars + still default to :rc:`colorbar.outline`. +tickminor : bool, optional + Whether to add minor ticks using `~matplotlib.colorbar.ColorbarBase.minorticks_on`. +tickloc, ticklocation : {'bottom', 'top', 'left', 'right'}, optional + Where to draw tick marks on the colorbar. Default is toward the outside + of the subplot for outer colorbars and ``'bottom'`` for inset colorbars. +tickdir, tickdirection : {'out', 'in', 'inout'}, default: :rc:`tick.dir` + Direction of major and minor colorbar ticks. +ticklen : unit-spec, default: :rc:`tick.len` + Major tick lengths for the colorbar ticks. +ticklenratio : float, default: :rc:`tick.lenratio` + Relative scaling of `ticklen` used to determine minor tick lengths. +tickwidth : unit-spec, default: `linewidth` + Major tick widths for the colorbar ticks. + or :rc:`tick.width` if `linewidth` was not passed. +tickwidthratio : float, default: :rc:`tick.widthratio` + Relative scaling of `tickwidth` used to determine minor tick widths. +ticklabelcolor, ticklabelsize, ticklabelweight: default: :rc:`tick.labelcolor`, :rc:`tick.labelsize`, :rc:`tick.labelweight`. + The font color, size, and weight for colorbar tick labels +labelloc, labellocation : {'bottom', 'top', 'left', 'right'} + The colorbar label location. Inherits from `tickloc` by default. Default is toward + the outside of the subplot for outer colorbars and ``'bottom'`` for inset colorbars. +labelcolor, labelsize, labelweight: default: :rc:`label.color`, :rc:`label.size`, and :rc:`label.weight`. + The font color, size, and weight for the colorbar label. +a, alpha, framealpha, fc, facecolor, framecolor, ec, edgecolor, ew, edgewidth : default: :rc:`colorbar.framealpha`, :rc:`colorbar.framecolor` + For inset colorbars only. Controls the transparency and color of + the background frame. +lw, linewidth, c, color : optional + Controls the line width and edge color for both the colorbar + outline and the level dividers. +edgefix : bool or float, default: :rc:`edgefix` + Whether to fix the common issue where white lines appear between adjacent + patches in saved vector graphics (this can slow down figure rendering). + See this `github repo `__ for a + demonstration of the problem. If ``True``, a small default linewidth of + ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), + this specific linewidth is used to cover up the white lines. This feature is + automatically disabled when the patches have transparency. +rasterize : bool, default: :rc:`colorbar.rasterized` + Whether to rasterize the colorbar solids. The matplotlib default was ``True`` + but ultraplot changes this to ``False`` since rasterization can cause misalignment + between the color patches and the colorbar outline. +outline : bool, None default : None + Controls the visibility of the outer colorbar outline. When set to False, + the spines of the colorbar are hidden. If set to `None` it uses the + `rc['colorbar.outline']` value. +labelrotation : str, float, default: None + Controls the rotation of the colorbar label. When set to None it takes on the value of `rc["colorbar.labelrotation"]`. When set to auto it produces a sensible default where the rotation is adjusted to where the colorbar is located. For example, a horizontal colorbar with a label to the left or right will match the horizontal alignment and rotate the label to 0 degrees. Users can provide a float to rotate to any arbitrary angle. + + + +**kwargs + Passed to `~matplotlib.figure.Figure.colorbar`. + +See also +-------- +ultraplot.axes.Axes.colorbar +matplotlib.figure.Figure.colorbar""" + ... + + def legend(self, handles: Incomplete=None, labels: Incomplete=None, loc: Incomplete=None, location: Incomplete=None, row: Incomplete=None, col: Incomplete=None, rows: Incomplete=None, cols: Incomplete=None, span: Incomplete=None, space: Incomplete=None, pad: Incomplete=None, width: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Add a legend along the side of the figure. + +Parameters +---------- +handles : list of artist, optional + List of matplotlib artists, or a list of lists of artist instances (see the `center` + keyword). If not passed, artists with valid labels (applied by passing `label` or + `labels` to a plotting command or calling `~matplotlib.artist.Artist.set_label`) + are retrieved automatically. If the object is a `~matplotlib.contour.ContourSet`, + `~matplotlib.contour.ContourSet.legend_elements` is used to select the central + artist in the list (generally useful for single-color contour plots). Note that + ultraplot's `~ultraplot.axes.PlotAxes.contour` and `~ultraplot.axes.PlotAxes.contourf` + accept a legend `label` keyword argument. +labels : list of str, optional + A matching list of string labels or ``None`` placeholders, or a matching list of + lists (see the `center` keyword). Wherever ``None`` appears in the list (or + if no labels were passed at all), labels are retrieved by calling + `~matplotlib.artist.Artist.get_label` on each `~matplotlib.artist.Artist` in the + handle list. If a handle consists of a tuple group of artists, labels are inferred + from the artists in the tuple (if there are multiple unique labels in the tuple + group of artists, the tuple group is expanded into unique legend entries -- + otherwise, the tuple group elements are drawn on top of eachother). For details + on matplotlib legend handlers and tuple groups, see the matplotlib `legend guide +-`__. +loc : str, optional + The legend location. Valid location keys are as follows. + + ========== ===================== + Location Valid keys + ========== ===================== + left ``'left'``, ``'l'`` + right ``'right'``, ``'r'`` + bottom ``'bottom'``, ``'b'`` + top ``'top'``, ``'t'`` + ========== ===================== + +space : float or str, default: None + The fixed space between the legend and the subplot grid edge. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + When the :ref:`tight layout algorithm ` is active for the figure, + `space` is computed automatically (see `pad`). Otherwise, `space` is set to + a suitable default. +pad : float or str, default: :rc:`subplots.innerpad` or :rc:`subplots.panelpad` + The :ref:`tight layout padding ` between the legend and the + subplot grid. Default is :rcraw:`subplots.innerpad` for the first legend + and :rcraw:`subplots.panelpad` for subsequently "stacked" legends. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +row, rows + Aliases for `span` for legends on the left or right side. +col, cols + Aliases for `span` for legends on the top or bottom side. +span : int or 2-tuple of int, default: None + Integer(s) indicating the span of the legend across rows and columns of + subplots. For example, ``fig.legend(loc='b', col=1)`` draws a legend beneath + the leftmost column of subplots, and ``fig.legend(loc='b', cols=(1, 2))`` + draws a legend beneath the left two columns of subplots. By default + the legend will span every subplot row and column. +align : {'center', 'top', 't', 'bottom', 'b', 'left', 'l', 'right', 'r'}, optional + For outer legends only. How to align the legend against the + subplot edge. The values ``'top'`` and ``'bottom'`` are valid for left and + right legends and ``'left'`` and ``'right'`` are valid for top and bottom + legends. The default is always ``'center'``. +width : unit-spec, optional + The space allocated for the legend box. This does nothing if + the :ref:`tight layout algorithm ` is active for the figure. + If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + +Other parameters +---------------- +frame, frameon : bool, optional + Toggles the legend frame. For centered-row legends, a frame + independent from matplotlib's built-in legend frame is created. +ncol, ncols : int, optional + The number of columns. `ncols` is an alias, added + for consistency with `~matplotlib.pyplot.subplots`. +order : {'C', 'F'}, optional + Whether legend handles are drawn in row-major (``'C'``) or column-major + (``'F'``) order. Analagous to `numpy.array` ordering. The matplotlib + default was ``'F'`` but ultraplot changes this to ``'C'``. +center : bool, optional + Whether to center each legend row individually. If ``True``, we draw + successive single-row legends "stacked" on top of each other. If ``None``, + we infer this setting from `handles`. By default, `center` is set to ``True`` + if `handles` is a list of lists (each sublist is used as a row in the legend). +alphabetize : bool, default: False + Whether to alphabetize the legend entries according to + the legend labels. +title, label : str, optional + The legend title. The `label` keyword is also accepted, for consistency + with `~matplotlib.figure.Figure.colorbar`. +fontsize, fontweight, fontcolor : optional + The font size, weight, and color for the legend text. Font size is interpreted + by `~ultraplot.utils.units`. The default font size is :rcraw:`legend.fontsize`. +titlefontsize, titlefontweight, titlefontcolor : optional + The font size, weight, and color for the legend title. Font size is interpreted + by `~ultraplot.utils.units`. The default size is `fontsize`. +borderpad, borderaxespad, handlelength, handleheight, handletextpad, labelspacing, columnspacing : unit-spec, optional + Various matplotlib `~matplotlib.axes.Axes.legend` spacing arguments. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +a, alpha, framealpha, fc, facecolor, framecolor, ec, edgecolor, ew, edgewidth: default: :rc:`legend.framealpha`, :rc:`legend.facecolor`, :rc:`legend.edgecolor`, :rc:`axes.linewidth` The opacity, face color, edge color, and edge width for the legend frame. +c, color, lw, linewidth, m, marker, ls, linestyle, dashes, ms, markersize : optional + Properties used to override the legend handles. For example, for a + legend describing variations in line style ignoring variations + in color, you might want to use ``color='black'``. +handle_kw : dict-like, optional + Additional properties used to override legend handles, e.g. + ``handle_kw={'edgecolor': 'black'}``. Only line properties + can be passed as keyword arguments. +handler_map : dict-like, optional + A dictionary mapping instances or types to a legend handler. + This `handler_map` updates the default handler map found at + `matplotlib.legend.Legend.get_legend_handler_map`. +**kwargs + Passed to `~matplotlib.axes.Axes.legend`. + +See also +-------- +ultraplot.axes.Axes.legend +matplotlib.axes.Axes.legend""" + ... + + def save(self, filename: Incomplete, **kwargs: Incomplete) -> None: + """Save the figure. + +Parameters +---------- +path : path-like, optional + The file path. User paths are expanded with `os.path.expanduser`. +**kwargs + Passed to `~matplotlib.figure.Figure.savefig` + +See also +-------- +Figure.save +Figure.savefig +matplotlib.figure.Figure.savefig""" + ... + + def savefig(self, filename: Incomplete, **kwargs: Incomplete) -> None: + """Save the figure. + +Parameters +---------- +path : path-like, optional + The file path. User paths are expanded with `os.path.expanduser`. +**kwargs + Passed to `~matplotlib.figure.Figure.savefig` + +See also +-------- +Figure.save +Figure.savefig +matplotlib.figure.Figure.savefig""" + ... + + def set_canvas(self, canvas: Incomplete) -> None: + """Set the figure canvas. Add monkey patches for the instance-level +`~matplotlib.backend_bases.FigureCanvasBase.draw` and +`~matplotlib.backend_bases.FigureCanvasBase.print_figure` methods. + +Parameters +---------- +canvas : `~matplotlib.backend_bases.FigureCanvasBase` + The figure canvas. + +See also +-------- +matplotlib.figure.Figure.set_canvas""" + ... + + def _is_same_size(self, figsize: Incomplete, eps: Incomplete=None) -> Incomplete: + """Test if the figure size is unchanged up to some tolerance in inches.""" + ... + + def set_size_inches(self, w: Incomplete, h: Incomplete=None, *, forward: Incomplete=True, internal: Incomplete=False, eps: Incomplete=None) -> None: + """Set the figure size. If this is being called manually or from an interactive +backend, update the default layout with this fixed size. If the figure size is +unchanged or this is an internal call, do not update the default layout. + +Parameters +---------- +*args : float + The width and height passed as positional arguments or a 2-tuple. +forward : bool, optional + Whether to update the canvas. +internal : bool, optional + Whether this is an internal resize. +eps : float, optional + The deviation from the current size in inches required to treat this + as a user-triggered figure resize that fixes the layout. + +See also +-------- +matplotlib.figure.Figure.set_size_inches""" + ... + + def _iter_axes(self, hidden: Incomplete=False, children: Incomplete=False, panels: Incomplete=True) -> Incomplete: + """Iterate over all axes and panels in the figure belonging to the +`~ultraplot.axes.Axes` class. Exclude inset and twin axes. + +Parameters +---------- +hidden : bool, optional + Whether to include "hidden" panels. +children : bool, optional + Whether to include child axes. Note this now includes "twin" axes. +panels : bool or str or sequence of str, optional + Whether to include panels or the panels to include.""" + ... + + @property + def gridspec(self) -> Incomplete: + """The single :class:`~ultraplot.gridspec.GridSpec` instance used for all +subplots in the figure. + +See also +-------- +ultraplot.figure.Figure.subplotgrid +ultraplot.gridspec.GridSpec.figure +ultraplot.gridspec.SubplotGrid.gridspec""" + ... + + @gridspec.setter + def gridspec(self, gs: Incomplete) -> None: + ... + + def _get_subplot(self, number: int) -> Incomplete: + """Return the subplot with the given *number*, or ``None``.""" + ... + + def _iter_subplots(self) -> Incomplete: + """Iterate over all numbered subplots.""" + ... + + @property + def subplotgrid(self) -> Incomplete: + """A :class:`~ultraplot.gridspec.SubplotGrid` containing the numbered subplots in the +figure. The subplots are ordered by increasing `~ultraplot.axes.Axes.number`. + +See also +-------- +ultraplot.figure.Figure.gridspec +ultraplot.gridspec.SubplotGrid.figure""" + ... + + @property + def tight(self) -> Incomplete: + """Whether the :ref:`tight layout algorithm ` is active for the +figure. This value is passed to `~ultraplot.figure.Figure.auto_layout` +every time the figure is drawn. Can be changed e.g. ``fig.tight = False``. + +See also +-------- +ultraplot.figure.Figure.auto_layout""" + ... + + @tight.setter + def tight(self, b: Incomplete) -> None: + ... + _format_signature = inspect.signature(format) + format = docstring._obfuscate_kwargs(format) diff --git a/ultraplot/gridspec.pyi b/ultraplot/gridspec.pyi new file mode 100644 index 000000000..e03cad427 --- /dev/null +++ b/ultraplot/gridspec.pyi @@ -0,0 +1,1287 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +The gridspec and subplot grid classes used throughout ultraplot. +""" +from _typeshed import Incomplete +import inspect +import itertools +import re +from collections.abc import MutableSequence +from functools import wraps +from numbers import Integral +from typing import Callable, List, Optional, Tuple, TypeVar, Union, cast, overload +import matplotlib.axes as maxes +import matplotlib.gridspec as mgridspec +import matplotlib.transforms as mtransforms +import numpy as np +from . import axes as paxes +from .axes._formatting import pop_axis_format_kwargs +from .config import rc +from .internals import _not_none, _pop_rc, docstring, ic, warnings +from .utils import _fontsize_to_pt, units +try: + from . import ultralayout + ULTRA_AVAILABLE = True +except ImportError: + ultralayout = None + ULTRA_AVAILABLE = False +__all__ = ['GridSpec', 'SubplotGrid'] +_shared_docstring = ... +_scalar_docstring = ... +_vector_docstring = ... +_tight_docstring = ... + +def _disable_method(attr: Incomplete) -> Incomplete: + """Disable the inherited method.""" + ... +_F = TypeVar('_F', bound=Callable[..., object]) + +@overload +def _apply_to_all(func: _F, *, doc_key: Optional[str]=None) -> _F: + ... + +@overload +def _apply_to_all(func: None=None, *, doc_key: Optional[str]=None) -> Callable[[_F], _F]: + ... + +class _SubplotSpec(mgridspec.SubplotSpec): + """ + A thin `~matplotlib.gridspec.SubplotSpec` subclass with a nice string + representation and a few helper methods. + """ + + def __repr__(self) -> Incomplete: + ... + + def _get_geometry(self) -> Incomplete: + """Return the geometry and scalar indices relative to the "unhidden" non-panel +geometry. May trigger error if this is in a "hidden" panel slot.""" + ... + + def _get_rows_columns(self, ncols: Incomplete=None) -> Incomplete: + """Return the row and column indices. The resulting indices include +"hidden" panel rows and columns. See `GridSpec.get_grid_positions`.""" + ... + + def _get_grid_span(self, hidden: Incomplete=False) -> Incomplete: + """Retrieve the location of the subplot within the +gridspec. When hidden is False we only consider +the main plots, not the panels or colorbars.""" + ... + + def get_position(self, figure: Incomplete, return_all: Incomplete=False) -> Incomplete: + ... + +class GridSpec(mgridspec.GridSpec): + """ + A `~matplotlib.gridspec.GridSpec` subclass that permits variable spacing + between successive rows and columns and hides "panel slots" from indexing. + """ + + def __repr__(self) -> str: + ... + + def __getattr__(self, attr: Incomplete) -> None: + ... + + def __init__(self, nrows: Incomplete=1, ncols: Incomplete=1, layout_array: Incomplete=None, ultra_layout: Optional[bool]=None, **kwargs: Incomplete) -> None: + """Parameters +---------- +nrows : int, optional + The number of rows in the subplot grid. +ncols : int, optional + The number of columns in the subplot grid. +layout_array : array-like, optional + 2D array specifying the subplot layout, where each unique integer + represents a subplot and 0 represents empty space. When provided, + enables UltraLayout constraint-based positioning (requires + kiwisolver package). +ultra_layout : bool, optional + Whether to use the UltraLayout constraint solver. Defaults to True + when kiwisolver is available. Set to False to use the legacy solver. + +Other parameters +---------------- +left, right, top, bottom : unit-spec, default: None + The fixed space between the subplots and the figure edge. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If ``None``, the space is determined automatically based on the tick and + label settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + passed to the figure, the space is determined by the tight layout algorithm. +wspace, hspace, space : unit-spec or sequence, default: None + The fixed space between grid columns, rows, and both, respectively. If + float, string, or ``None``, this value is expanded into lists of length + ``ncols - 1`` (for `wspace`) or length ``nrows - 1`` (for `hspace`). If + a sequence, its length must match these lengths. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + + For elements equal to ``None``, the space is determined automatically based + on the tick and label settings. If :rcraw:`subplots.tight` is ``True`` or + ``tight=True`` was passed to the figure, the space is determined by the tight + layout algorithm. For example, ``subplots(ncols=3, tight=True, wspace=(2, None))`` + fixes the space between columns 1 and 2 but lets the tight layout algorithm + determine the space between columns 2 and 3. +wratios, hratios : float or sequence, optional + Passed to :class:`~ultraplot.gridspec.GridSpec`, denotes the width and height + ratios for the subplot grid. Length of `wratios` must match the number + of columns, and length of `hratios` must match the number of rows. +width_ratios, height_ratios + Aliases for `wratios`, `hratios`. Included for + consistency with `matplotlib.gridspec.GridSpec`. +wpad, hpad, pad : unit-spec or sequence, optional + The tight layout padding between columns, rows, and both, respectively. + Unlike ``space``, these control the padding between subplot content + (including text, ticks, etc.) rather than subplot edges. As with + ``space``, these can be scalars or arrays optionally containing ``None``. + For elements equal to ``None``, the default is `innerpad`. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +wequal, hequal, equal : bool, default: :rc:`subplots.equalspace` + Whether to make the tight layout algorithm apply equal spacing + between columns, rows, or both. +wgroup, hgroup, group : bool, default: :rc:`subplots.groupspace` + Whether to make the tight layout algorithm just consider spaces between + adjacent subplots instead of entire columns and rows of subplots. +outerpad : unit-spec, default: :rc:`subplots.outerpad` + The scalar tight layout padding around the left, right, top, bottom figure edges. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +innerpad : unit-spec, default: :rc:`subplots.innerpad` + The scalar tight layout padding between columns and rows. Synonymous with `pad`. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +panelpad : unit-spec, default: :rc:`subplots.panelpad` + The scalar tight layout padding between subplots and their panels, + colorbars, and legends and between "stacks" of these objects. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + +See also +-------- +ultraplot.ui.figure +ultraplot.figure.Figure +ultraplot.ui.subplots +ultraplot.figure.Figure.subplots +ultraplot.figure.Figure.add_subplots +matplotlib.gridspec.GridSpec + +Important +--------- +Adding axes panels, axes or figure colorbars, and axes or figure legends +quietly augments the gridspec geometry by inserting "panel slots". However, +subsequently indexing the gridspec with ``gs[num]`` or ``gs[row, col]`` will +ignore the "panel slots". This permits adding new subplots by passing +``gs[num]`` or ``gs[row, col]`` to `~ultraplot.figure.Figure.add_subplot` +even in the presence of panels (see `~GridSpec.__getitem__` for details). +This also means that each `GridSpec` is `~ultraplot.figure.Figure`-specific, +i.e. it can only be used once (if you are working with `GridSpec` instances +manually and want the same geometry for multiple figures, you must create +a copy with `GridSpec.copy` before working on the subsequent figure).""" + ... + + def _get_ultra_position(self, subplot_num: Incomplete, figure: Incomplete) -> Incomplete: + """Get the position of a subplot using UltraLayout constraint-based positioning. + +Parameters +---------- +subplot_num : int + The subplot number (in total geometry indexing) +figure : Figure + The matplotlib figure instance + +Returns +------- +bbox : Bbox or None + The bounding box for the subplot, or None if kiwi layout fails""" + ... + + def _compute_ultra_positions(self) -> None: + """Compute subplot positions using UltraLayout and cache them.""" + ... + + def _get_ultra_layout_array(self) -> Incomplete: + """Return the layout array expanded to total geometry to include panels.""" + ... + + def __getitem__(self, key: Incomplete) -> _SubplotSpec: + """Get a `~matplotlib.gridspec.SubplotSpec`. "Hidden" slots allocated for axes +panels, colorbars, and legends are ignored. For example, given a gridspec with +2 subplot rows, 3 subplot columns, and a "panel" row between the subplot rows, +calling ``gs[1, 1]`` returns a `~matplotlib.gridspec.SubplotSpec` corresponding +to the central subplot on the second row rather than a "panel" slot.""" + ... + + def _make_subplot_spec(self, key: Incomplete, includepanels: Incomplete=False) -> _SubplotSpec: + """Generate a subplotspec either ignoring panels or including panels.""" + ... + + def _encode_indices(self, *args: Incomplete, which: Incomplete=None, panel: Incomplete=False) -> Incomplete: + """Convert indices from the selected gridspec geometry into indices for the +total geometry. If `which` is not passed these should be flattened indices. +When `panel` is True, indices are interpreted relative to panel slots +along the specified axis; otherwise they refer to non-panel slots.""" + ... + + def _decode_indices(self, *args: Incomplete, which: Incomplete=None, panel: Incomplete=False) -> Incomplete: + """Convert indices from the total geometry into the selected gridspec +geometry. If `which` is not passed these should be flattened indices. +When `panel` is True, indices are interpreted relative to panel slots +along the specified axis; otherwise they refer to non-panel slots.""" + ... + + def _filter_indices(self, key: Incomplete, panel: Incomplete=False) -> Incomplete: + """Filter the vector attribute for "unhidden" or "hidden" slots.""" + ... + + def _get_indices(self, which: Incomplete=None, space: Incomplete=False, panel: Incomplete=False) -> list[int]: + """Get the indices associated with "unhidden" or "hidden" slots.""" + ... + + def _modify_subplot_geometry(self, newrow: Incomplete=None, newcol: Incomplete=None) -> None: + """Update the axes subplot specs by inserting rows and columns as specified.""" + ... + + def _parse_panel_arg(self, side: Incomplete, arg: Incomplete) -> Incomplete: + """Return the indices associated with a new figure panel on the specified side. +Try to find room in the current mosaic of figure panels.""" + ... + + def _parse_panel_arg_with_span(self, side: str, ax: 'paxes.Axes', span_override: Optional[Union[int, Tuple[int, int]]]) -> Tuple[str, int, slice]: + """Parse panel arg with span override. Uses ax for position, span for extent. + +Parameters +---------- +side : str + Panel side ('left', 'right', 'top', 'bottom') +ax : Axes + The axes to position the panel relative to +span_override : int or tuple + The span extent (1-indexed like subplot numbers) + +Returns +------- +slot : str + Panel slot identifier +iratio : int + Panel position index +span : slice + Encoded span slice for the panel extent""" + ... + + def _insert_panel_slot(self, side: str, arg: Incomplete, *, share: Optional[bool]=None, width: Optional[Union[float, str]]=None, space: Optional[Union[float, str]]=None, pad: Optional[Union[float, str]]=None, filled: bool=False, span_override: Optional[Union[int, Tuple[int, int]]]=None) -> tuple[_SubplotSpec, bool]: + """Insert a panel slot into the existing gridspec. The `side` is the panel side +and the `arg` is either an axes instance or the figure row-column span.""" + ... + + def _get_space(self, key: Incomplete) -> Incomplete: + """Return the currently active vector inner space or scalar outer space +accounting for both default values and explicit user overrides.""" + ... + + def _get_default_space(self, key: Incomplete, pad: Incomplete=None, share: Incomplete=None, title: Incomplete=True) -> Incomplete: + """Return suitable default scalar inner or outer space given a shared axes +setting. This is only relevant when "tight layout" is disabled.""" + ... + + def _get_tight_space(self, w: Incomplete) -> Incomplete: + """Get tight layout spaces between the input subplot rows or columns.""" + ... + + def _auto_layout_aspect(self) -> None: + """Update the underlying default aspect ratio.""" + ... + + def _auto_layout_tight(self, renderer: Incomplete) -> None: + """Update the underlying spaces with tight layout values. If `resize` is +``True`` and the auto figure size has changed then update the figure +size. Either way always update the subplot positions.""" + ... + + def _update_figsize(self) -> Incomplete: + """Return an updated auto layout figure size accounting for the +gridspec and figure parameters. May or may not need to be applied.""" + ... + + def _update_params(self, *, ultra_layout: Incomplete=None, left: Incomplete=None, bottom: Incomplete=None, right: Incomplete=None, top: Incomplete=None, wspace: Incomplete=None, hspace: Incomplete=None, space: Incomplete=None, wpad: Incomplete=None, hpad: Incomplete=None, pad: Incomplete=None, wequal: Incomplete=None, hequal: Incomplete=None, equal: Incomplete=None, wgroup: Incomplete=None, hgroup: Incomplete=None, group: Incomplete=None, outerpad: Incomplete=None, innerpad: Incomplete=None, panelpad: Incomplete=None, hratios: Incomplete=None, wratios: Incomplete=None, width_ratios: Incomplete=None, height_ratios: Incomplete=None) -> None: + """Update the user-specified properties.""" + ... + + def copy(self, **kwargs: Incomplete) -> GridSpec: + """Return a copy of the `GridSpec` with the `~ultraplot.figure.Figure`-specific +"panel slots" removed. This can be useful if you want to draw multiple +figures with the same geometry. Properties are inherited from this +`GridSpec` by default but can be changed by passing keyword arguments. + +Parameters +---------- +left, right, top, bottom : unit-spec, default: None + The fixed space between the subplots and the figure edge. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If ``None``, the space is determined automatically based on the tick and + label settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + passed to the figure, the space is determined by the tight layout algorithm. +wspace, hspace, space : unit-spec or sequence, default: None + The fixed space between grid columns, rows, and both, respectively. If + float, string, or ``None``, this value is expanded into lists of length + ``ncols - 1`` (for `wspace`) or length ``nrows - 1`` (for `hspace`). If + a sequence, its length must match these lengths. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + + For elements equal to ``None``, the space is determined automatically based + on the tick and label settings. If :rcraw:`subplots.tight` is ``True`` or + ``tight=True`` was passed to the figure, the space is determined by the tight + layout algorithm. For example, ``subplots(ncols=3, tight=True, wspace=(2, None))`` + fixes the space between columns 1 and 2 but lets the tight layout algorithm + determine the space between columns 2 and 3. +wratios, hratios : float or sequence, optional + Passed to :class:`~ultraplot.gridspec.GridSpec`, denotes the width and height + ratios for the subplot grid. Length of `wratios` must match the number + of columns, and length of `hratios` must match the number of rows. +width_ratios, height_ratios + Aliases for `wratios`, `hratios`. Included for + consistency with `matplotlib.gridspec.GridSpec`. +wpad, hpad, pad : unit-spec or sequence, optional + The tight layout padding between columns, rows, and both, respectively. + Unlike ``space``, these control the padding between subplot content + (including text, ticks, etc.) rather than subplot edges. As with + ``space``, these can be scalars or arrays optionally containing ``None``. + For elements equal to ``None``, the default is `innerpad`. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +wequal, hequal, equal : bool, default: :rc:`subplots.equalspace` + Whether to make the tight layout algorithm apply equal spacing + between columns, rows, or both. +wgroup, hgroup, group : bool, default: :rc:`subplots.groupspace` + Whether to make the tight layout algorithm just consider spaces between + adjacent subplots instead of entire columns and rows of subplots. +outerpad : unit-spec, default: :rc:`subplots.outerpad` + The scalar tight layout padding around the left, right, top, bottom figure edges. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +innerpad : unit-spec, default: :rc:`subplots.innerpad` + The scalar tight layout padding between columns and rows. Synonymous with `pad`. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +panelpad : unit-spec, default: :rc:`subplots.panelpad` + The scalar tight layout padding between subplots and their panels, + colorbars, and legends and between "stacks" of these objects. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + +See also +-------- +GridSpec.update""" + ... + + def get_geometry(self) -> Incomplete: + """Return the number of "unhidden" non-panel rows and columns in the grid +(see `GridSpec` for details). + +See also +-------- +GridSpec.get_panel_geometry +GridSpec.get_total_geometry""" + ... + + def get_panel_geometry(self) -> tuple[int, int]: + """Return the number of "hidden" panel rows and columns in the grid +(see `GridSpec` for details). + +See also +-------- +GridSpec.get_geometry +GridSpec.get_total_geometry""" + ... + + def get_total_geometry(self) -> Incomplete: + """Return the total number of "unhidden" and "hidden" rows and columns +in the grid (see `GridSpec` for details). + +See also +-------- +GridSpec.get_geometry +GridSpec.get_panel_geometry +GridSpec.get_grid_positions""" + ... + + def get_grid_positions(self, figure: Incomplete=None) -> Incomplete: + """Return the subplot grid positions allowing for variable inter-subplot +spacing and using physical units for the spacing terms. The resulting +positions include "hidden" panel rows and columns. + +Note +---- +The physical units for positioning grid cells are converted from em-widths to +inches when the `GridSpec` is instantiated. This means that subsequent changes +to :rcraw:`font.size` will have no effect on the spaces. This is consistent +with :rcraw:`font.size` having no effect on already-instantiated figures. + +See also +-------- +GridSpec.get_total_geometry""" + ... + + def update(self, **kwargs: Incomplete) -> None: + """Update the gridspec with arbitrary initialization keyword arguments +and update the subplot positions. + +Parameters +---------- +left, right, top, bottom : unit-spec, default: None + The fixed space between the subplots and the figure edge. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If ``None``, the space is determined automatically based on the tick and + label settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + passed to the figure, the space is determined by the tight layout algorithm. +wspace, hspace, space : unit-spec or sequence, default: None + The fixed space between grid columns, rows, and both, respectively. If + float, string, or ``None``, this value is expanded into lists of length + ``ncols - 1`` (for `wspace`) or length ``nrows - 1`` (for `hspace`). If + a sequence, its length must match these lengths. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + + For elements equal to ``None``, the space is determined automatically based + on the tick and label settings. If :rcraw:`subplots.tight` is ``True`` or + ``tight=True`` was passed to the figure, the space is determined by the tight + layout algorithm. For example, ``subplots(ncols=3, tight=True, wspace=(2, None))`` + fixes the space between columns 1 and 2 but lets the tight layout algorithm + determine the space between columns 2 and 3. +wratios, hratios : float or sequence, optional + Passed to :class:`~ultraplot.gridspec.GridSpec`, denotes the width and height + ratios for the subplot grid. Length of `wratios` must match the number + of columns, and length of `hratios` must match the number of rows. +width_ratios, height_ratios + Aliases for `wratios`, `hratios`. Included for + consistency with `matplotlib.gridspec.GridSpec`. +wpad, hpad, pad : unit-spec or sequence, optional + The tight layout padding between columns, rows, and both, respectively. + Unlike ``space``, these control the padding between subplot content + (including text, ticks, etc.) rather than subplot edges. As with + ``space``, these can be scalars or arrays optionally containing ``None``. + For elements equal to ``None``, the default is `innerpad`. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +wequal, hequal, equal : bool, default: :rc:`subplots.equalspace` + Whether to make the tight layout algorithm apply equal spacing + between columns, rows, or both. +wgroup, hgroup, group : bool, default: :rc:`subplots.groupspace` + Whether to make the tight layout algorithm just consider spaces between + adjacent subplots instead of entire columns and rows of subplots. +outerpad : unit-spec, default: :rc:`subplots.outerpad` + The scalar tight layout padding around the left, right, top, bottom figure edges. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +innerpad : unit-spec, default: :rc:`subplots.innerpad` + The scalar tight layout padding between columns and rows. Synonymous with `pad`. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +panelpad : unit-spec, default: :rc:`subplots.panelpad` + The scalar tight layout padding between subplots and their panels, + colorbars, and legends and between "stacks" of these objects. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + +See also +-------- +GridSpec.copy""" + ... + + @property + def figure(self) -> Incomplete: + """The `ultraplot.figure.Figure` uniquely associated with this `GridSpec`. +On assignment the gridspec parameters and figure size are updated. + +See also +-------- +ultraplot.gridspec.SubplotGrid.figure +ultraplot.figure.Figure.gridspec""" + ... + + @figure.setter + def figure(self, fig: Incomplete) -> None: + ... + tight_layout = _disable_method('tight_layout') + subgridspec = _disable_method('subgridspec') + get_width_ratios = _disable_method('get_width_ratios') + get_height_ratios = _disable_method('get_height_ratios') + set_width_ratios = _disable_method('set_width_ratios') + set_height_ratios = _disable_method('set_height_ratios') + + def get_subplot_params(self, figure: Incomplete=None) -> Incomplete: + ... + + def locally_modified_subplot_params(self) -> Incomplete: + ... + gridheight = ... + gridwidth = ... + panelheight = ... + panelwidth = ... + spaceheight = ... + spacewidth = ... + nrows = ... + ncols = ... + nrows_panel = ... + ncols_panel = ... + nrows_total = ... + ncols_total = ... + left = ... + bottom = ... + right = ... + top = ... + hratios = ... + wratios = ... + hratios_panel = ... + wratios_panel = ... + hratios_total = ... + wratios_total = ... + hspace = ... + wspace = ... + hspace_panel = ... + wspace_panel = ... + hspace_total = ... + wspace_total = ... + hpad = ... + wpad = ... + hpad_panel = ... + wpad_panel = ... + hpad_total = ... + wpad_total = ... + +class SubplotGrid(MutableSequence, list): + """ + List-like, array-like object used to store subplots returned by + `~ultraplot.figure.Figure.subplots`. 1D indexing uses the underlying list of + `~ultraplot.axes.Axes` while 2D indexing uses the `~SubplotGrid.gridspec`. + See `~SubplotGrid.__getitem__` for details. + """ + + def __repr__(self) -> str: + ... + + def __str__(self) -> str: + ... + + def __len__(self) -> int: + ... + + def insert(self, key: Incomplete, value: Incomplete) -> None: + ... + + def __init__(self, sequence: Incomplete=None, **kwargs: Incomplete) -> None: + """Parameters +---------- +sequence : sequence + A sequence of `ultraplot.axes.Axes` subplots or their children. + +See also +-------- +ultraplot.ui.subplots +ultraplot.figure.Figure.subplots +ultraplot.figure.Figure.add_subplots""" + ... + + def __getattr__(self, attr: Incomplete) -> Incomplete: + """Get a missing attribute. Simply redirects to the axes if the `SubplotGrid` +is singleton and raises an error otherwise. This can be convenient for +single-axes figures generated with `~ultraplot.figure.Figure.subplots`.""" + ... + + def __getitem__(self, key: Incomplete) -> Incomplete: + """Get an axes. + +Parameters +---------- +key : int, slice, or 2-tuple + The index. If 1D then the axes in the corresponding + sublist are returned. If 2D then the axes that intersect + the corresponding `~SubplotGrid.gridspec` slots are returned. + +Returns +------- +axs : ultraplot.axes.Axes or SubplotGrid + The axes. If the index included slices then + another `SubplotGrid` is returned. + +Example +------- +>>> import ultraplot as uplt +>>> fig, axs = uplt.subplots(nrows=3, ncols=3) +>>> axs[5] # the subplot in the second row, third column +>>> axs[1, 2] # the subplot in the second row, third column +>>> axs[:, 0] # a SubplotGrid containing the subplots in the first column""" + ... + + def __setitem__(self, key: Incomplete, value: Incomplete) -> Incomplete: + """Add an axes. + +Parameters +---------- +key : int or slice + The 1D index. +value : `ultraplot.axes.Axes` + The ultraplot subplot or its child or panel axes, + or a sequence thereof if the index was a slice.""" + ... + + def _validate_item(self, items: Incomplete, scalar: Incomplete=False) -> Incomplete: + """Validate assignments. Accept diverse iterable inputs.""" + ... + + def format(self, **kwargs: Incomplete) -> None: + """Call the ``format`` command for the `~SubplotGrid.figure` +and every axes in the grid. + +Parameters +---------- +title : str or sequence, optional + The axes title. Can optionally be a sequence strings, in which case + the title will be selected from the sequence according to `~Axes.number`. +abc : bool or str or sequence, default: :rc:`abc` + The "a-b-c" subplot label style. Must contain the character `a` or `A`, + for example ``'a.'``, or ``'A'``. If ``True`` then the default style of + ``'a'`` is used. The `a` or ``A`` is replaced with the alphabetic character + matching the `~Axes.number`. If `~Axes.number` is greater than 26, the + characters loop around to a, ..., z, aa, ..., zz, aaa, ..., zzz, etc. + Can also be a sequence of strings, in which case the "a-b-c" label will be selected sequentially from the list. For example `axs.format(abc = ["X", "Y"])` for a two-panel figure, and `axes[3:5].format(abc = ["X", "Y"])` for a two-panel subset of a larger figure. +abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` + Strings indicating the location for the a-b-c label and main title. + The following locations are valid: + + .. _title_table: + + ======================== ============================ + Location Valid keys + ======================== ============================ + center above axes ``'center'``, ``'c'`` + left above axes ``'left'``, ``'l'`` + right above axes ``'right'``, ``'r'`` + lower center inside axes ``'lower center'``, ``'lc'`` + upper center inside axes ``'upper center'``, ``'uc'`` + upper right inside axes ``'upper right'``, ``'ur'`` + upper left inside axes ``'upper left'``, ``'ul'`` + lower left inside axes ``'lower left'``, ``'ll'`` + lower right inside axes ``'lower right'``, ``'lr'`` + left of y axis ``'outer left'``, ``'ol'`` + right of y axis ``'outer right'``, ``'or'`` + ======================== ============================ + +abcborder, titleborder : bool, default: :rc:`abc.border` and :rc:`title.border` + Whether to draw a white border around titles and a-b-c labels positioned + inside the axes. This can help them stand out on top of artists + plotted inside the axes. +abcbbox, titlebbox : bool, default: :rc:`abc.bbox` and :rc:`title.bbox` + Whether to draw a white bbox around titles and a-b-c labels positioned + inside the axes. This can help them stand out on top of artists plotted + inside the axes. +abcpad : float or unit-spec, default: :rc:`abc.pad` + Horizontal offset to shift the a-b-c label position. Positive values move + the label right, negative values move it left. This is separate from + `abctitlepad`, which controls spacing between abc and title when co-located. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +abc_kw, title_kw : dict-like, optional + Additional settings used to update the a-b-c label and title + with ``text.update()``. +titlepad : float, default: :rc:`title.pad` + The padding for the inner and outer titles and a-b-c labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +titleabove : bool, default: :rc:`title.above` + Whether to try to put outer titles and a-b-c labels above panels, + colorbars, or legends that are above the axes. +abctitlepad : float, default: :rc:`abc.titlepad` + The horizontal padding between a-b-c labels and titles in the same location. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle : str or sequence, optional + Shorthands for the below keywords. + lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle : str or sequence, optional +lowerlefttitle, lowercentertitle, lowerrighttitle : str or sequence, optional + Additional titles in specific positions (see `title` for details). This works as + an alternative to the ``ax.format(title='Title', titleloc=loc)`` workflow and + permits adding more than one title-like label for a single axes. +a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle : default: + :rc:`axes.alpha` (default: 1.0), :rc:`axes.facecolor` (default: white), :rc:`axes.edgecolor` (default: black), :rc:`axes.linewidth` (default: 0.6), - + Additional settings applied to the background patch, and their + shorthands. Their defaults values are the ``'axes'`` properties. +**kwargs + Passed to the projection-specific ``format`` command for each axes. + Valid only if every axes in the grid belongs to the same class. + +Other parameters +---------------- +rowlabels, collabels, llabels, tlabels, rlabels, blabels + Aliases for `leftlabels` and `toplabels`, and for `leftlabels`, + `toplabels`, `rightlabels`, and `bottomlabels`, respectively. +leftlabels, toplabels, rightlabels, bottomlabels : sequence of str, optional + Labels for the subplots lying along the left, top, right, and + bottom edges of the figure. The length of each list must match + the number of subplots along the corresponding edge. +leftlabelpad, toplabelpad, rightlabelpad, bottomlabelpad : float or unit-spec, default +: :rc:`leftlabel.pad`, :rc:`toplabel.pad`, :rc:`rightlabel.pad`, :rc:`bottomlabel.pad` + The padding between the labels and the axes content. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +leftlabelsharedpad, toplabelsharedpad, rightlabelsharedpad, bottomlabelsharedpad : float or unit-spec, default +: :rc:`leftlabel.sharedpad`, :rc:`toplabel.sharedpad`, :rc:`rightlabel.sharedpad`, :rc:`bottomlabel.sharedpad` + The padding between side labels and a shared spanning axis label on the + same side. The spanning label is placed outside the side labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +leftlabels_kw, toplabels_kw, rightlabels_kw, bottomlabels_kw : dict-like, optional + Additional settings used to update the labels with ``text.update()``. +figtitle + Alias for `suptitle`. +suptitle : str, optional + The figure "super" title, centered between the left edge of the leftmost + subplot and the right edge of the rightmost subplot. +suptitlepad : float, default: :rc:`suptitle.pad` + The padding between the super title and the axes content. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +suptitle_kw : optional + Additional settings used to update the super title with ``text.update()``. +includepanels : bool, default: False + Whether to include panels when aligning figure "super titles" along the top + of the subplot grid and when aligning the `spanx` *x* axis labels and + `spany` *y* axis labels along the sides of the subplot grid. +aspect : {'auto', 'equal'} or float, optional + The data aspect ratio. See :func:`~matplotlib.axes.Axes.set_aspect` + for details. +xlabel, ylabel : str, optional + The x and y axis labels. Applied with `~matplotlib.axes.Axes.set_xlabel` + and `~matplotlib.axes.Axes.set_ylabel`. +xlabel_kw, ylabel_kw : dict-like, optional + Additional axis label settings applied with `~matplotlib.axes.Axes.set_xlabel` + and `~matplotlib.axes.Axes.set_ylabel`. See also `labelpad`, `labelcolor`, + `labelsize`, and `labelweight` below. +xlim, ylim : 2-tuple of floats or None, optional + The x and y axis data limits. Applied with :func:`~matplotlib.axes.Axes.set_xlim` + and :func:`~matplotlib.axes.Axes.set_ylim`. +xmin, ymin : float, optional + The x and y minimum data limits. Useful if you do not want + to set the maximum limits. +xmax, ymax : float, optional + The x and y maximum data limits. Useful if you do not want + to set the minimum limits. +xreverse, yreverse : bool, optional + Whether to "reverse" the x and y axis direction. Makes the x and + y axes ascend left-to-right and top-to-bottom, respectively. +xscale, yscale : scale-spec, optional + The x and y axis scales. Passed to the `~ultraplot.scale.Scale` constructor. + For example, ``xscale='log'`` applies logarithmic scaling, and + ``xscale=('cutoff', 100, 2)`` applies a `~ultraplot.scale.CutoffScale`. +xscale_kw, yscale_kw : dict-like, optional + The x and y axis scale settings. Passed to `~ultraplot.scale.Scale`. +xmargin, ymargin, margin : float, default: :rc:`margin` + The default margin between plotted content and the x and y axis spines in + axes-relative coordinates. This is useful if you don't witch to explicitly set + axis limits. Use the keyword `margin` to set both at once. +xbounds, ybounds : 2-tuple of float, optional + The x and y axis data bounds within which to draw the spines. For example, + ``xlim=(0, 4)`` combined with ``xbounds=(2, 4)`` will prevent the spines + from meeting at the origin. This also applies ``xspineloc='bottom'`` and + ``yspineloc='left'`` by default if both spines are currently visible. +xtickrange, ytickrange : 2-tuple of float, optional + The x and y axis data ranges within which major tick marks are labelled. + For example, ``xlim=(-5, 5)`` combined with ``xtickrange=(-1, 1)`` and a + tick interval of 1 will only label the ticks marks at -1, 0, and 1. See + `~ultraplot.ticker.AutoFormatter` for details. +xwraprange, ywraprange : 2-tuple of float, optional + The x and y axis data ranges with which major tick mark values are wrapped. For + example, ``xwraprange=(0, 3)`` causes the values 0 through 9 to be formatted as + 0, 1, 2, 0, 1, 2, 0, 1, 2, 0. See `~ultraplot.ticker.AutoFormatter` for details. This + can be combined with `xtickrange` and `ytickrange` to make "stacked" line plots. +xloc, yloc : optional + Shorthands for `xspineloc`, `yspineloc`. +xspineloc, yspineloc : {'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right', 'both', 'neither', 'none', 'zero', 'center'} or 2-tuple, optional + The x and y spine locations. Applied with `~matplotlib.spines.Spine.set_position`. + Propagates to `tickloc` unless specified otherwise. +xtickloc, ytickloc : {'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right', 'both', 'neither', 'none'}, optional + Which x and y axis spines should have major and minor tick marks. Inherits from + `spineloc` by default and propagates to `ticklabelloc` unless specified otherwise. +xticklabelloc, yticklabelloc : {'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right', 'both', 'neither', 'none'}, optional + Which x and y axis spines should have major tick labels. Inherits from `tickloc` + by default and propagates to `labelloc` and `offsetloc` unless specified otherwise. +xlabelloc, ylabelloc : {'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right'}, optional + Which x and y axis spines should have axis labels. Inherits from + `ticklabelloc` by default (if `ticklabelloc` is a single side). +xoffsetloc, yoffsetloc : {'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right'}, optional + Which x and y axis spines should have the axis offset indicator. Inherits from + `ticklabelloc` by default (if `ticklabelloc` is a single side). +xtickdir, ytickdir, tickdir : {'out', 'in', 'inout'}, optional + Direction that major and minor tick marks point for the x and y axis. + Use the keyword `tickdir` to control both. +xticklabeldir, yticklabeldir : {'in', 'out'}, optional + Whether to place x and y axis tick label text inside or outside the axes. + Propagates to `xtickdir` and `ytickdir` unless specified otherwise. +xrotation, yrotation : float, default: 0 + The rotation for x and y axis tick labels. + for normal axes, :rc:`formatter.timerotation` for time x axes. +xgrid, ygrid, grid : bool, default: :rc:`grid` + Whether to draw major gridlines on the x and y axis. + Use the keyword `grid` to toggle both. +xgridminor, ygridminor, gridminor : bool, default: :rc:`gridminor` + Whether to draw minor gridlines for the x and y axis. + Use the keyword `gridminor` to toggle both. +xtickminor, ytickminor, tickminor : bool, default: :rc:`tick.minor` + Whether to draw minor ticks on the x and y axes. + Use the keyword `tickminor` to toggle both. +xticks, yticks : optional + Aliases for `xlocator`, `ylocator`. +xlocator, ylocator : locator-spec, optional + Used to determine the x and y axis tick mark positions. Passed + to the `~ultraplot.constructor.Locator` constructor. Can be float, + list of float, string, or `matplotlib.ticker.Locator` instance. + Use ``[]``, ``'null'``, or ``'none'`` for no ticks. +xlocator_kw, ylocator_kw : dict-like, optional + Keyword arguments passed to the `matplotlib.ticker.Locator` class. +xminorticks, yminorticks : optional + Aliases for `xminorlocator`, `yminorlocator`. +xminorlocator, yminorlocator : optional + As for `xlocator`, `ylocator`, but for the minor ticks. +xminorlocator_kw, yminorlocator_kw + As for `xlocator_kw`, `ylocator_kw`, but for the minor locator. +xticklabels, yticklabels : optional + Aliases for `xformatter`, `yformatter`. +xformatter, yformatter : formatter-spec, optional + Used to determine the x and y axis tick label string format. + Passed to the `~ultraplot.constructor.Formatter` constructor. + Can be string, list of strings, or `matplotlib.ticker.Formatter` instance. + Use ``[]``, ``'null'``, or ``'none'`` for no labels. +xformatter_kw, yformatter_kw : dict-like, optional + Keyword arguments passed to the `matplotlib.ticker.Formatter` class. +xcolor, ycolor, color : color-spec, default: :rc:`meta.color` + Color for the x and y axis spines, ticks, tick labels, and axis labels. + Use the keyword `color` to set both at once. +xgridcolor, ygridcolor, gridcolor : color-spec, default: :rc:`grid.color` + Color for the x and y axis major and minor gridlines. + Use the keyword `gridcolor` to set both at once. +xlinewidth, ylinewidth, linewidth : color-spec, default: :rc:`meta.width` + Line width for the x and y axis spines and major ticks. Propagates to `tickwidth` + unless specified otherwise. Use the keyword `linewidth` to set both at once. +xtickcolor, ytickcolor, tickcolor : color-spec, default: :rc:`tick.color` + Color for the x and y axis ticks. Defaults are `xcolor`, `ycolor`, and `color` + if they were passed. Use the keyword `tickcolor` to set both at once. +xticklen, yticklen, ticklen : unit-spec, default: :rc:`tick.len` + Major tick lengths for the x and y axis. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + Use the keyword `ticklen` to set both at once. +xticklenratio, yticklenratio, ticklenratio : float, default: :rc:`tick.lenratio` + Relative scaling of `xticklen` and `yticklen` used to determine minor + tick lengths. Use the keyword `ticklenratio` to set both at once. +xtickwidth, ytickwidth, tickwidth, : unit-spec, default: :rc:`tick.width` + Major tick widths for the x ans y axis. Default is `linewidth` if it was passed. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + Use the keyword `tickwidth` to set both at once. +xtickwidthratio, ytickwidthratio, tickwidthratio : float, default: :rc:`tick.widthratio` + Relative scaling of `xtickwidth` and `ytickwidth` used to determine + minor tick widths. Use the keyword `tickwidthratio` to set both at once. +xticklabelpad, yticklabelpad, ticklabelpad : unit-spec, default: :rc:`tick.labelpad` + The padding between the x and y axis ticks and tick labels. Use the + keyword `ticklabelpad` to set both at once. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +xticklabelcolor, yticklabelcolor, ticklabelcolor : color-spec, default: :rc:`tick.labelcolor` + Color for the x and y tick labels. Defaults are `xcolor`, `ycolor`, and `color` + if they were passed. Use the keyword `ticklabelcolor` to set both at once. +xticklabelsize, yticklabelsize, ticklabelsize : unit-spec or str, default: :rc:`tick.labelsize` + Font size for the x and y tick labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + Use the keyword `ticklabelsize` to set both at once. +xticklabelweight, yticklabelweight, ticklabelweight : str, default: :rc:`tick.labelweight` + Font weight for the x and y tick labels. + Use the keyword `ticklabelweight` to set both at once. +xlabelpad, ylabelpad : unit-spec, default: :rc:`label.pad` + The padding between the x and y axis bounding box and the x and y axis labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +xlabelcolor, ylabelcolor, labelcolor : color-spec, default: :rc:`label.color` + Color for the x and y axis labels. Defaults are `xcolor`, `ycolor`, and `color` + if they were passed. Use the keyword `labelcolor` to set both at once. +xlabelsize, ylabelsize, labelsize : unit-spec or str, default: :rc:`label.size` + Font size for the x and y axis labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + Use the keyword `labelsize` to set both at once. +xlabelweight, ylabelweight, labelweight : str, default: :rc:`label.weight` + Font weight for the x and y axis labels. + Use the keyword `labelweight` to set both at once. +fixticks : bool, default: False + Whether to transform the tick locators to a `~matplotlib.ticker.FixedLocator`. + If your axis ticks are doing weird things (for example, ticks are drawn + outside of the axis spine) you can try setting this to ``True``. +r0 : float, default: 0 + The radial origin. +theta0 : {'N', 'NW', 'W', 'SW', 'S', 'SE', 'E', 'NE'}, optional + The zero azimuth location. +thetadir : {1, -1, 'anticlockwise', 'counterclockwise', 'clockwise'}, optional + The positive azimuth direction. Clockwise corresponds to + ``-1`` and anticlockwise corresponds to ``1``. +thetamin, thetamax : float, optional + The lower and upper azimuthal bounds in degrees. If + ``thetamax != thetamin + 360``, this produces a sector plot. +thetalim : 2-tuple of float or None, optional + Specifies `thetamin` and `thetamax` at once. +rmin, rmax : float, optional + The inner and outer radial limits. If ``r0 != rmin``, this + produces an annular plot. +rlim : 2-tuple of float or None, optional + Specifies `rmin` and `rmax` at once. +rborder : bool, optional + Whether to draw the polar axes border. Visibility of the "inner" + radial spine and "start" and "end" azimuthal spines is controlled + automatically by matplotlib. +thetagrid, rgrid, grid : bool, optional + Whether to draw major gridlines for the azimuthal and radial axis. + Use the keyword `grid` to toggle both. +thetagridminor, rgridminor, gridminor : bool, optional + Whether to draw minor gridlines for the azimuthal and radial axis. + Use the keyword `gridminor` to toggle both. +thetagridcolor, rgridcolor, gridcolor : color-spec, optional + Color for the major and minor azimuthal and radial gridlines. + Use the keyword `gridcolor` to set both at once. +thetalocator, rlocator : locator-spec, optional + Used to determine the azimuthal and radial gridline positions. + Passed to the `~ultraplot.constructor.Locator` constructor. Can be + float, list of float, string, or `matplotlib.ticker.Locator` instance. +thetalines, rlines + Aliases for `thetalocator`, `rlocator`. +thetalocator_kw, rlocator_kw : dict-like, optional + The azimuthal and radial locator settings. Passed to + `~ultraplot.constructor.Locator`. +thetaminorlocator, rminorlocator : optional + As for `thetalocator`, `rlocator`, but for the minor gridlines. +thetaminorticks, rminorticks : optional + Aliases for `thetaminorlocator`, `rminorlocator`. +thetaminorlocator_kw, rminorlocator_kw + As for `thetalocator_kw`, `rlocator_kw`, but for the minor locator. +rlabelpos : float, optional + The azimuth at which radial coordinates are labeled. Also used as the + spoke angle for ``rlabel`` when you want an explicit radial-label + position. +thetaformatter, rformatter : formatter-spec, optional + Used to determine the azimuthal and radial label format. + Passed to the `~ultraplot.constructor.Formatter` constructor. + Can be string, list of string, or `matplotlib.ticker.Formatter` + instance. Use ``[]``, ``'null'``, or ``'none'`` for no labels. +thetalabels, rlabels : optional + Aliases for `thetaformatter`, `rformatter`. +thetaformatter_kw, rformatter_kw : dict-like, optional + The azimuthal and radial label formatter settings. Passed to + `~ultraplot.constructor.Formatter`. +thetalabel, rlabel : str, optional + Polar-aware axis labels rendered via `~ultraplot.text.CurvedText`. + ``thetalabel`` follows the outer arc just beyond ``r=rmax``. + ``rlabel`` follows a radial spoke, centered between ``rmin`` and + ``rmax``. On a full circle it uses ``get_rlabel_position()`` unless + ``rlabelpos`` is explicit; on a sector it uses the spoke selected by + ``rlabelloc`` unless ``rlabelpos`` is explicit. Both labels include a + built-in tick-clearance offset, and ``labelpad`` adds extra padding in + points on top of that offset. Pass ``""`` to clear a previously set + label. +thetalabelloc : float, optional + Center theta angle (in degrees) for ``thetalabel``. Defaults to the + midpoint of the directed ``thetalim`` interval (or ``0`` for a full + circle). +rlabelloc : {'right', 'left'}, default: 'right' + Where to place ``rlabel``. When the spoke angle is fixed by a full + circle or by explicit ``rlabelpos``, ``rlabelloc`` selects the + perpendicular side of that spoke and ``'left'`` flips the default + side. On a sector with no explicit ``rlabelpos``, ``'right'`` + (default) anchors to ``thetamin`` and ``'left'`` anchors to + ``thetamax``; the label is then offset outward from the sector. +thetalabel_kw, rlabel_kw : dict-like, optional + Additional `~ultraplot.text.CurvedText` settings for the polar-aware + labels (e.g. ``border``, ``bbox``, or rendering hints like + ``min_advance``). See also `labelpad`, `labelcolor`, `labelsize`, + and `labelweight`. +color : color-spec, default: :rc:`meta.color` + Color for the axes edge. Propagates to `labelcolor` unless specified + otherwise (similar to :func:`~ultraplot.axes.CartesianAxes.format`). +labelcolor, gridlabelcolor : color-spec, default: `color` or :rc:`grid.labelcolor` + Color for the gridline labels. +labelpad, gridlabelpad : unit-spec, default: :rc:`grid.labelpad` + The padding between the axes edge and the radial and azimuthal labels. + For ``thetalabel`` and ``rlabel``, this is added on top of the built-in + tick-clearance offset. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +labelsize, gridlabelsize : unit-spec or str, default: :rc:`grid.labelsize` + Font size for the gridline labels. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +labelweight, gridlabelweight : str, default: :rc:`grid.labelweight` + Font weight for the gridline labels. +aspect : {'auto', 'equal'} or float, optional + The map aspect ratio. ``'auto'`` makes the map fill its subplot slot, which + can be useful for aligning it with neighboring Cartesian axes but distorts + the projection. See :func:`~matplotlib.axes.Axes.set_aspect` for details. +abcanchor : {'axes', 'slot'}, default: 'axes' + The coordinate box used for the a-b-c label. ``'axes'`` attaches it to the + visible map boundary. ``'slot'`` attaches it to the unadjusted GridSpec + slot, keeping labels aligned with neighboring subplots when fixed map + aspect leaves empty space inside a slot. +round : bool, default: :rc:`geo.round` + *For polar cartopy axes only*. + Whether to bound polar projections with circles rather than squares. Note that outer + gridline labels cannot be added to circle-bounded polar projections. When basemap + is the backend this argument must be passed to `~ultraplot.constructor.Proj` instead. +extent : {'globe', 'auto'}, default: :rc:`geo.extent` + *For cartopy axes only*. + Whether to auto adjust the map bounds based on plotted content. If ``'globe'`` then + non-polar projections are fixed with `~cartopy.mpl.geoaxes.GeoAxes.set_global`, + non-Gnomonic polar projections are bounded at the equator, and Gnomonic polar + projections are bounded at 30 degrees latitude. If ``'auto'`` nothing is done. +lonlim, latlim : 2-tuple of float, optional + *For cartopy axes only.* + The approximate longitude and latitude boundaries of the map, applied + with `~cartopy.mpl.geoaxes.GeoAxes.set_extent`. When basemap is the backend + this argument must be passed to `~ultraplot.constructor.Proj` instead. +boundinglat : float, optional + *For cartopy axes only.* + The edge latitude for the circle bounding North Pole and South Pole-centered + projections. When basemap is the backend this argument must be passed to + `~ultraplot.constructor.Proj` instead. +longrid, latgrid, grid : bool, default: :rc:`grid` + Whether to draw longitude and latitude gridlines. + Use the keyword `grid` to toggle both at once. +longridminor, latgridminor, gridminor : bool, default: :rc:`gridminor` + Whether to draw "minor" longitude and latitude lines. + Use the keyword `gridminor` to toggle both at once. +lonticklen, latticklen, ticklen : unit-spec, default: :rc:`tick.len` + Major tick lengths for the longitudinal (x) and latitude (y) axis. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + Use the keyword `ticklen` to set both at once. +latmax : float, default: 80 + The maximum absolute latitude for gridlines. Longitude gridlines are cut off + poleward of this value (note this feature does not work in cartopy 0.18). +nsteps : int, default: :rc:`grid.nsteps` + *For cartopy axes only.* + The number of interpolation steps used to draw gridlines. +lonlocator, latlocator : locator-spec, optional + Used to determine the longitude and latitude gridline locations. + Aliases: ``lonlines`` and ``latlines``, respectively. + Passed to the `~ultraplot.constructor.Locator` constructor. Can be + string, float, list of float, or `matplotlib.ticker.Locator` instance. + + For basemap or cartopy < 0.18, the defaults are ``'deglon'`` and + ``'deglat'``, which correspond to the `~ultraplot.ticker.LongitudeLocator` + and `~ultraplot.ticker.LatitudeLocator` locators (adapted from cartopy). + For cartopy >= 0.18, the defaults are ``'dmslon'`` and ``'dmslat'``, + which uses the same locators with ``dms=True``. This selects gridlines + at nice degree-minute-second intervals when the map extent is very small. +lonlocator_kw, latlocator_kw : dict-like, optional + Keyword arguments passed to the `matplotlib.ticker.Locator` class. + Aliases: ``lonlines_kw`` and ``latlines_kw``, respectively. +lonminorlocator, latminorlocator : optional + As with `lonlocator` and `latlocator` but for the "minor" gridlines. + Aliases: ``lonminorlines`` and ``latminorlines``, respectively. +lonminorlocator_kw, latminorlocator_kw : optional + As with `lonlocator_kw`, and `latlocator_kw` but for the "minor" gridlines. + Aliases: ``lonminorlines_kw`` and ``latminorlines_kw``, respectively. +lonlabels, latlabels, labels : str, bool, or sequence, :rc:`grid.labels` + Whether to add non-inline longitude and latitude gridline labels, and on + which sides of the map. Use the keyword `labels` to set both at once. The + argument must conform to one of the following options: + + * A boolean. ``True`` indicates the bottom side for longitudes and + the left side for latitudes, and ``False`` disables all labels. + * A string or sequence of strings indicating the side names, e.g. + ``'top'`` for longitudes or ``('left', 'right')`` for latitudes. + * A string indicating the side names with single characters, e.g. + ``'bt'`` for longitudes or ``'lr'`` for latitudes. + * A string matching ``'neither'`` (no labels), ``'both'`` (equivalent + to ``'bt'`` for longitudes and ``'lr'`` for latitudes), or ``'all'`` + (equivalent to ``'lrbt'``, i.e. all sides). + * A boolean 2-tuple indicating whether to draw labels + on the ``(bottom, top)`` sides for longitudes, + and the ``(left, right)`` sides for latitudes. + * A boolean 4-tuple indicating whether to draw labels on the + ``(left, right, bottom, top)`` sides, as with the basemap + :func:`~mpl_toolkits.basemap.Basemap.drawmeridians` and + :func:`~mpl_toolkits.basemap.Basemap.drawparallels` `labels` keyword. + +loninline, latinline, inlinelabels : bool, default: :rc:`grid.inlinelabels` + *For cartopy axes only.* + Whether to add inline longitude and latitude gridline labels. Use + the keyword `inlinelabels` to set both at once. +rotatelabels : bool, default: :rc:`grid.rotatelabels` + *For cartopy axes only.* + Whether to rotate non-inline gridline labels so that they automatically + follow the map boundary curvature. +labelrotation : float, optional + The rotation angle in degrees for both longitude and latitude tick labels. + Use `lonlabelrotation` and `latlabelrotation` to set them separately. +lonlabelrotation : float, optional + The rotation angle in degrees for longitude tick labels. + Works for both cartopy and basemap backends. +latlabelrotation : float, optional + The rotation angle in degrees for latitude tick labels. + Works for both cartopy and basemap backends. +labelpad : unit-spec, default: :rc:`grid.labelpad` + *For cartopy axes only.* + The padding between non-inline gridline labels and the map boundary. + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +dms : bool, default: :rc:`grid.dmslabels` + *For cartopy axes only.* + Whether the default locators and formatters should use "minutes" and "seconds" + for gridline labels on small scales rather than decimal degrees. Setting this to + ``False`` is equivalent to ``ax.format(lonlocator='deglon', latlocator='deglat')`` + and ``ax.format(lonformatter='deglon', latformatter='deglat')``. +lonformatter, latformatter : formatter-spec, optional + Formatter used to style longitude and latitude gridline labels. + Passed to the `~ultraplot.constructor.Formatter` constructor. Can be + string, list of string, or `matplotlib.ticker.Formatter` instance. + + For basemap or cartopy < 0.18, the defaults are ``'deglon'`` and + ``'deglat'``, which correspond to `~ultraplot.ticker.SimpleFormatter` + presets with degree symbols and cardinal direction suffixes. + For cartopy >= 0.18, the defaults are ``'dmslon'`` and ``'dmslat'``, + which uses cartopy's `~cartopy.mpl.ticker.LongitudeFormatter` and + `~cartopy.mpl.ticker.LatitudeFormatter` formatters with ``dms=True``. + This formats gridlines that do not fall on whole degrees as "minutes" and + "seconds" rather than decimal degrees. Use ``dms=False`` to disable this. +lonformatter_kw, latformatter_kw : dict-like, optional + Keyword arguments passed to the `matplotlib.ticker.Formatter` class. +land, ocean, coast, rivers, lakes, borders, innerborders : bool, optional + Toggles various geographic features. These are actually the + :rcraw:`land`, :rcraw:`ocean`, :rcraw:`coast`, :rcraw:`rivers`, + :rcraw:`lakes`, :rcraw:`borders`, and :rcraw:`innerborders` + settings passed to `~ultraplot.config.Configurator.context`. + The style can be modified using additional `rc` settings. + + For example, to change :rcraw:`land.color`, use + ``ax.format(landcolor='green')``, and to change + :rcraw:`land.zorder`, use ``ax.format(landzorder=4)``. +reso : {'lo', 'med', 'hi', 'x-hi', 'xx-hi'}, optional + *For cartopy axes only.* + The resolution of geographic features. When basemap is the backend this + must be passed to `~ultraplot.constructor.Proj` instead. +color : color-spec, default: :rc:`meta.color` + The color for the axes edge. Propagates to `labelcolor` unless specified + otherwise (similar to :func:`~ultraplot.axes.CartesianAxes.format`). +gridcolor : color-spec, default: :rc:`grid.color` + The color for the gridline labels. +labelcolor : color-spec, default: `color` or :rc:`grid.labelcolor` + The color for the gridline labels (`gridlabelcolor` is also allowed). +labelsize : unit-spec or str, default: :rc:`grid.labelsize` + The font size for the gridline labels (`gridlabelsize` is also allowed). + If float, units are points. If string, interpreted by `~ultraplot.utils.units`. +labelweight : str, default: :rc:`grid.labelweight` + The font weight for the gridline labels (`gridlabelweight` is also allowed). +rc_mode : int, optional + The context mode passed to `~ultraplot.config.Configurator.context`. +rc_kw : dict-like, optional + An alternative to passing extra keyword arguments. See below. +**kwargs + Keyword arguments that match the name of an `~ultraplot.config.rc` setting are + passed to `ultraplot.config.Configurator.context` and used to update the axes. + If the setting name has "dots" you can simply omit the dots. For example, + ``abc='A.'`` modifies the :rcraw:`abc` setting, ``titleloc='left'`` modifies the + :rcraw:`title.loc` setting, ``gridminor=True`` modifies the :rcraw:`gridminor` + setting, and ``gridbelow=True`` modifies the :rcraw:`grid.below` setting. Many + of the keyword arguments documented above are internally applied by retrieving + settings passed to `~ultraplot.config.Configurator.context`. + +See also +-------- +ultraplot.axes.Axes.format +ultraplot.axes.CartesianAxes.format +ultraplot.axes.PolarAxes.format +ultraplot.axes.GeoAxes.format +ultraplot.figure.Figure.format +ultraplot.config.Configurator.context""" + ... + + def share_labels(self, *, axis: Incomplete='x') -> Incomplete: + """Register an explicit label-sharing group for this subset.""" + ... + + @property + def figure(self) -> Incomplete: + """The `ultraplot.figure.Figure` uniquely associated with this `SubplotGrid`. +This is used with the `SubplotGrid.format` command. + +See also +-------- +ultraplot.gridspec.GridSpec.figure +ultraplot.gridspec.SubplotGrid.gridspec +ultraplot.figure.Figure.subplotgrid""" + ... + + @property + def gridspec(self) -> Incomplete: + """The :class:`~ultraplot.gridspec.GridSpec` uniquely associated with this `SubplotGrid`. +This is used to resolve 2D indexing. See `~SubplotGrid.__getitem__` for details. + +See also +-------- +ultraplot.figure.Figure.gridspec +ultraplot.gridspec.SubplotGrid.figure +ultraplot.gridspec.SubplotGrid.shape""" + ... + + @property + def shape(self) -> Incomplete: + """The shape of the :class:`~ultraplot.gridspec.GridSpec` associated with the grid. +See `~SubplotGrid.__getitem__` for details. + +See also +-------- +ultraplot.gridspec.SubplotGrid.gridspec""" + ... + + def _apply_command(self, name: Incomplete, *args: Incomplete, warn_on_skip: Incomplete=True, **kwargs: Incomplete) -> List[paxes.Axes]: + """Apply a command to all axes that support it. + +Parameters +---------- +name : str + The method name to call on each axes. +warn_on_skip : bool, optional + Whether to warn if some axes do not support the command. Default True. + +Returns +------- +list + List of results from axes where the command was applied.""" + ... + + def altx(self, *args: Incomplete, **kwargs: Incomplete) -> 'SubplotGrid': + """Call `altx()` for every axes in the grid. + +Returns +------- +SubplotGrid + A grid of the resulting axes.""" + ... + + def dualx(self, *args: Incomplete, **kwargs: Incomplete) -> 'SubplotGrid': + """Call `dualx()` for every axes in the grid. + +Returns +------- +SubplotGrid + A grid of the resulting axes.""" + ... + + def twinx(self, *args: Incomplete, **kwargs: Incomplete) -> 'SubplotGrid': + """Call `twinx()` for every axes in the grid. + +Returns +------- +SubplotGrid + A grid of the resulting axes.""" + ... + + def alty(self, *args: Incomplete, **kwargs: Incomplete) -> 'SubplotGrid': + """Call `alty()` for every axes in the grid. + +Returns +------- +SubplotGrid + A grid of the resulting axes.""" + ... + + def dualy(self, *args: Incomplete, **kwargs: Incomplete) -> 'SubplotGrid': + """Call `dualy()` for every axes in the grid. + +Returns +------- +SubplotGrid + A grid of the resulting axes.""" + ... + + def twiny(self, *args: Incomplete, **kwargs: Incomplete) -> 'SubplotGrid': + ... + + def panel(self, *args: Incomplete, **kwargs: Incomplete) -> 'SubplotGrid': + ... + + def panel_axes(self, *args: Incomplete, **kwargs: Incomplete) -> 'SubplotGrid': + ... + + def inset(self, *args: Incomplete, **kwargs: Incomplete) -> 'SubplotGrid': + ... + + def inset_axes(self, *args: Incomplete, **kwargs: Incomplete) -> 'SubplotGrid': + ... diff --git a/ultraplot/internals/__init__.pyi b/ultraplot/internals/__init__.pyi new file mode 100644 index 000000000..78c0f97d9 --- /dev/null +++ b/ultraplot/internals/__init__.pyi @@ -0,0 +1,43 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Internal utilities. +""" +from _typeshed import Incomplete +from importlib import import_module +from numbers import Integral, Real +import numpy as np +try: + from icecream import ic +except ImportError: + ic = ... +from . import warnings +from .kwargs import _alias_kwargs, _alias_maps, _get_aliases, _get_signature, _kwargs_to_args, _not_none, _pop_kwargs, _pop_params, _pop_props, _signature_cached, _INTERNAL_POP_PARAMS + +def _get_rc_matplotlib() -> Incomplete: + ... +_LAZY_ATTRS = {'benchmarks': ('benchmarks', None), 'context': ('context', None), 'docstring': ('docstring', None), 'fonts': ('fonts', None), 'guides': ('guides', None), 'inputs': ('inputs', None), 'labels': ('labels', None), 'rcsetup': ('rcsetup', None), 'versions': ('versions', None), 'warnings': ('warnings', None), '_version_mpl': ('versions', '_version_mpl'), '_version_cartopy': ('versions', '_version_cartopy'), 'UltraPlotWarning': ('warnings', 'UltraPlotWarning')} + +def _pop_rc(src: Incomplete, *, ignore_conflicts: Incomplete=True) -> Incomplete: + """Pop the rc setting names and mode for a `~Configurator.context` block.""" + ... + +def _translate_loc(loc: Incomplete, mode: Incomplete, *, default: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Translate the location string `loc` into a standardized form. The `mode` +must be a string for which there is a :rcraw:`mode.loc` setting. Additional +options can be added with keyword arguments.""" + ... + +def _translate_grid(b: Incomplete, key: Incomplete) -> Incomplete: + """Translate an instruction to turn either major or minor gridlines on or off into a +boolean and string applied to :rcraw:`axes.grid` and :rcraw:`axes.grid.which`.""" + ... + +def _resolve_lazy(name: Incomplete) -> Incomplete: + ... + +def __getattr__(name: Incomplete) -> Incomplete: + ... + +def __dir__() -> list[str]: + ... diff --git a/ultraplot/internals/benchmarks.pyi b/ultraplot/internals/benchmarks.pyi new file mode 100644 index 000000000..fa75c4195 --- /dev/null +++ b/ultraplot/internals/benchmarks.pyi @@ -0,0 +1,23 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Utilities for benchmarking ultraplot performance. +""" +from _typeshed import Incomplete +import time +from . import ic +BENCHMARK = False + +class _benchmark(object): + """ + Context object for timing arbitrary blocks of code. + """ + + def __init__(self, message: Incomplete) -> None: + ... + + def __enter__(self) -> None: + ... + + def __exit__(self, *args: Incomplete) -> None: + ... diff --git a/ultraplot/internals/context.pyi b/ultraplot/internals/context.pyi new file mode 100644 index 000000000..3e973d5d2 --- /dev/null +++ b/ultraplot/internals/context.pyi @@ -0,0 +1,35 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Utilities for manging context. +""" +from _typeshed import Incomplete +from . import ic + +class _empty_context(object): + """ + A dummy context manager. + """ + + def __init__(self) -> None: + ... + + def __enter__(self) -> None: + ... + + def __exit__(self, *args: Incomplete) -> None: + ... + +class _state_context(object): + """ + Temporarily modify attribute(s) for an arbitrary object. + """ + + def __init__(self, obj: Incomplete, **kwargs: Incomplete) -> None: + ... + + def __enter__(self) -> None: + ... + + def __exit__(self, *args: Incomplete) -> None: + ... diff --git a/ultraplot/internals/docstring.pyi b/ultraplot/internals/docstring.pyi new file mode 100644 index 000000000..94284fe52 --- /dev/null +++ b/ultraplot/internals/docstring.pyi @@ -0,0 +1,68 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Utilities for modifying ultraplot docstrings. +""" +from _typeshed import Incomplete +import inspect +import re +from typing import Any, Callable, TypeVar, cast, overload +from . import ic +_F = TypeVar('_F', bound=Callable[..., Any]) +_T = TypeVar('_T') + +def _obfuscate_kwargs(func: _F) -> _F: + """Mark keyword arguments as compact in generated API documentation.""" + ... + +def _obfuscate_params(func: _F) -> _F: + """Mark all parameters as compact in generated API documentation.""" + ... + +def _obfuscate_signature(func: _F, dummy: Callable[..., Any]) -> _F: + """Mark a misleading or incomplete signature as compact in generated docs. + +The callable's actual signature remains available to Python and language +servers; Sphinx reads the marker below when rendering API headings.""" + ... + +def _concatenate_inherited(func: _F, prepend_summary: bool=False) -> _F: + """Concatenate docstrings from a matplotlib axes method with a ultraplot +axes method and mark its generated-documentation signature as compact.""" + ... + +class _SnippetManager(dict): + """ + A simple database for handling documentation snippets. + """ + _lazy_modules = {'axes': 'ultraplot.axes.base', 'cartesian': 'ultraplot.axes.cartesian', 'polar': 'ultraplot.axes.polar', 'geo': 'ultraplot.axes.geo', 'plot': 'ultraplot.axes.plot', 'figure': 'ultraplot.figure', 'gridspec': 'ultraplot.gridspec', 'legend': 'ultraplot.legend', 'ticker': 'ultraplot.ticker', 'proj': 'ultraplot.proj', 'colors': 'ultraplot.colors', 'utils': 'ultraplot.utils', 'config': 'ultraplot.config', 'demos': 'ultraplot.demos', 'rc': 'ultraplot.axes.base'} + + def __missing__(self, key: Incomplete) -> Incomplete: + """Attempt to import modules that populate missing snippet keys.""" + ... + + @overload + def __call__(self, obj: str) -> str: + ... + + @overload + def __call__(self, obj: _T) -> _T: + ... + + def __setitem__(self, key: Incomplete, value: Incomplete) -> None: + """Populate input strings with other snippets and strip newlines. Developers +should take care to import modules in the correct order.""" + ... +_snippet_manager = _SnippetManager() +_units_docstring = ... + +def _aliases_note(*names: Incomplete) -> str: + """Render a compact ``Aliases: ...`` note for a style parameter. The canonical +name leads the numpydoc field; the common documented synonyms go here so the +parameter reads cleanly instead of opening with a pile of alias names.""" + ... +_line_docstring = ... +_patch_docstring = ... +_pcolor_collection_docstring = ... +_contour_collection_docstring = ... +_text_docstring = ... diff --git a/ultraplot/internals/fonts.pyi b/ultraplot/internals/fonts.pyi new file mode 100644 index 000000000..cad696f3c --- /dev/null +++ b/ultraplot/internals/fonts.pyi @@ -0,0 +1,64 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Overrides related to math fonts. +""" +from _typeshed import Incomplete +import matplotlib as mpl +from matplotlib.font_manager import findfont, ttfFontProperty +from matplotlib.mathtext import MathTextParser +from . import warnings +try: + from matplotlib._mathtext import BakomaFonts, UnicodeFonts +except ImportError: + from matplotlib.mathtext import UnicodeFonts + BakomaFonts = None +WARN_MATHPARSER = True +WARN_BAKOMA = True +_CM_SYMBOLS = frozenset(('\\sum', '\\prod', '\\coprod', '\\int', '\\oint', '\\bigcup', '\\bigcap', '\\bigvee', '\\bigwedge', '\\biguplus', '\\bigoplus', '\\bigotimes', '\\bigodot')) + +def _is_cm_mathtext_enabled() -> bool: + ... + +def _clear_math_parse_cache() -> None: + ... + +class _UnicodeFonts(UnicodeFonts): + """ + A simple `~matplotlib._mathtext.UnicodeFonts` subclass that + interprets ``rc['mathtext.default'] != 'regular'`` in the presence of + ``rc['mathtext.fontset'] == 'custom'`` as possibly modifying the active font. + + Works by permitting the ``rc['mathtext.rm']``, ``rc['mathtext.it']``, + etc. settings to have the dummy value ``'regular'`` instead of a valid family + name, e.g. ``rc['mathtext.it'] == 'regular:italic'`` (permitted through an + override of the `~matplotlib.rcsetup.validate_font_properties` validator). + When this dummy value is detected then the font properties passed to + `~matplotlib._mathtext.TrueTypeFont` are taken by replacing ``'regular'`` + in the "math" fontset with the active font name. + """ + + def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: + ... + + def _init_computer_modern_fonts(self, *args: Incomplete, **kwargs: Incomplete) -> None: + ... + + def _collect_replacements(self) -> tuple[dict, dict]: + ... + + def _replace_fonts(self, regular: dict) -> None: + ... + + def _uses_cm_symbol(self, sym: str) -> bool: + ... + + def _get_glyph(self, fontname: str, font_class: str, sym: str) -> Incomplete: + ... + + def get_sized_alternatives_for_symbol(self, fontname: str, sym: str) -> Incomplete: + ... +try: + mapping = MathTextParser._font_type_mapping +except (KeyError, AttributeError): + WARN_MATHPARSER = False diff --git a/ultraplot/internals/guides.pyi b/ultraplot/internals/guides.pyi new file mode 100644 index 000000000..cb432a99a --- /dev/null +++ b/ultraplot/internals/guides.pyi @@ -0,0 +1,55 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Utilties related to legends and colorbars. +""" +from _typeshed import Incomplete +import matplotlib.artist as martist +import matplotlib.colorbar as mcolorbar +import matplotlib.legend as mlegend +import matplotlib.ticker as mticker +import numpy as np +from . import ic +from . import warnings +REMOVE_AFTER_FLUSH = ('pad', 'space', 'width', 'length', 'shrink', 'align', 'queue') +GUIDE_ALIASES = (('title', 'label'), ('locator', 'ticks'), ('format', 'formatter', 'ticklabels')) + +def _add_guide_kw(name: Incomplete, kwargs: Incomplete, **opts: Incomplete) -> None: + """Add to the `colorbar_kw` or `legend_kw` dict if there are no conflicts.""" + ... + +def _cache_guide_kw(obj: Incomplete, name: Incomplete, kwargs: Incomplete) -> None: + """Cache settings on the object from the input keyword arguments.""" + ... + +def _flush_guide_kw(obj: Incomplete, name: Incomplete, kwargs: Incomplete) -> Incomplete: + """Flux settings cached on the object into the keyword arguments.""" + ... + +def _update_kw(kwargs: Incomplete, overwrite: Incomplete=False, **opts: Incomplete) -> None: + """Add the keyword arguments to the dictionary if not already present.""" + ... + +def _iter_children(*args: Incomplete) -> Incomplete: + """Iterate through `_children` of `HPacker`, `VPacker`, and `DrawingArea`. +This is used to update legend handle properties.""" + ... + +def _iter_iterables(*args: Incomplete) -> Incomplete: + """Iterate over arbitrary nested lists of iterables. Used for deciphering legend input. +Things can get complicated with e.g. bar colunns plus negative-positive colors.""" + ... + +def _update_ticks(self, manual_only: Incomplete=False) -> None: + """Refined colorbar tick updater without subclassing.""" + ... + +class _InsetColorbar(martist.Artist): + """ + Legend-like class for managing inset colorbars. + """ + +class _CenteredLegend(martist.Artist): + """ + Legend-like class for managing centered-row legends. + """ diff --git a/ultraplot/internals/inputs.pyi b/ultraplot/internals/inputs.pyi new file mode 100644 index 000000000..40cf8ff5c --- /dev/null +++ b/ultraplot/internals/inputs.pyi @@ -0,0 +1,194 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Utilities for processing input data passed to plotting commands. +""" +from _typeshed import Incomplete +import functools +import sys +from typing import Any, Callable, TypeVar, cast +import numpy as np +import numpy.ma as ma +from . import ic +from . import _not_none, warnings +try: + from cartopy.crs import PlateCarree +except ModuleNotFoundError: + PlateCarree = object +try: + from matplotlib.tri import Triangulation +except ModuleNotFoundError: + Triangulation = object +_F = TypeVar('_F', bound=Callable[..., Any]) +BASEMAP_FUNCS = ('barbs', 'contour', 'contourf', 'hexbin', 'imshow', 'pcolor', 'pcolormesh', 'plot', 'quiver', 'scatter', 'streamplot', 'step') +CARTOPY_FUNCS = ('barbs', 'contour', 'contourf', 'fill', 'fill_between', 'fill_betweenx', 'imshow', 'pcolor', 'pcolormesh', 'plot', 'quiver', 'scatter', 'streamplot', 'step', 'tricontour', 'tricontourf', 'tripcolor') + +def _load_objects() -> None: + """Load array-like objects.""" + ... + +def _is_numeric(data: Incomplete) -> Incomplete: + """Test whether input is numeric array rather than datetime or strings.""" + ... + +def _is_categorical(data: Incomplete) -> Incomplete: + """Test whether input is array of strings.""" + ... + +def _is_descending(data: Incomplete) -> bool: + """Test whether the input data is descending. This is used for auto axis reversal.""" + ... + +def _to_duck_array(data: Incomplete, strip_units: Incomplete=False) -> Incomplete: + """Convert arbitrary input to duck array. Preserve array containers with metadata.""" + ... + +def _to_numpy_array(data: Incomplete, strip_units: Incomplete=False) -> Incomplete: + """Convert arbitrary input to numpy array. Preserve masked arrays and unit arrays.""" + ... + +def _to_masked_array(data: Incomplete, *, copy: Incomplete=False) -> Incomplete: + """Convert numpy array to masked array with consideration for datetimes and quantities.""" + ... + +def _to_edges(x: Incomplete, y: Incomplete, z: Incomplete) -> Incomplete: + """Enforce that coordinates are edges. Convert from centers if possible.""" + ... + +def _to_centers(x: Incomplete, y: Incomplete, z: Incomplete) -> Incomplete: + """Enforce that coordinates are centers. Convert from edges if possible.""" + ... + +def _from_data(data: Incomplete, *args: Incomplete) -> Incomplete: + """Try to convert positional `key` arguments to `data[key]`. If argument is string +it could be a valid positional argument like `fmt` so do not raise error.""" + ... + +def _parse_triangulation_inputs(*args: Incomplete, **kwargs: Incomplete) -> tuple[Triangulation, Any, tuple[Any, ...], dict[str, Any]]: + """Parse inputs using Matplotlib's `get_from_args_and_kwargs` method. +Returns a Triangulation object, z values, and updated args/kwargs.""" + ... + +def _parse_triangulation_with_preprocess(*keys: Incomplete, keywords: Incomplete=None, allow_extra: Incomplete=True) -> Callable[[_F], _F]: + """Combines _parse_triangulation with _preprocess_or_redirect for backwards compatibility.""" + ... + +def _preprocess_or_redirect(*keys: Incomplete, keywords: Incomplete=None, allow_extra: Incomplete=True, cartopy_default_transform: Incomplete=True) -> Callable[[_F], _F]: + """Redirect internal plotting calls to native matplotlib methods. Also convert +keyword args to positional and pass arguments through 'data' dictionary.""" + ... + +def _dist_finite(distribution: Incomplete, weights: Incomplete=None) -> Incomplete: + """Return the finite subset of the distribution together with the matching +subset of the weights. Used to sanitize input for `_dist_kde`.""" + ... + +def _dist_kde(distribution: Incomplete, *, coords: Incomplete=None, points: Incomplete=None, margin: Incomplete=0.0, bw_method: Incomplete=None, weights: Incomplete=None) -> Incomplete: + """Return the coordinates and gaussian kernel density estimate of the input +distribution. This is the single entry point for the kernel density +estimates drawn by `~ultraplot.axes.PlotAxes.hist` and +`~ultraplot.axes.PlotAxes.ridgeline`. + +Parameters +---------- +distribution : array-like + The sample. Flattened to 1D and stripped of non-finite values. +coords : array-like, optional + The coordinates to evaluate the estimate on. If ``None`` an evenly + spaced grid is built from the data range (see `points` and `margin`). +points : int, default: :rc:`kde.points` + The number of evenly spaced evaluation coordinates. Larger values give + smoother curves at the cost of speed. Ignored if `coords` was passed. +margin : float, default: 0 + The fraction of the data range used to pad either side of the + evaluation grid. Ignored if `coords` was passed. +bw_method : str, float, or callable, optional + The bandwidth selector passed to `scipy.stats.gaussian_kde`. Can be + ``'scott'``, ``'silverman'``, a scalar, or a callable. +weights : array-like, optional + The per-sample weights passed to `scipy.stats.gaussian_kde`. + +Returns +------- +coords : ndarray + The evaluation coordinates. +density : ndarray + The probability density evaluated on `coords`. Integrates to ``1``.""" + ... + +def _dist_clean(distribution: Incomplete) -> Incomplete: + """Clean the distribution data for processing by `boxplot` or `violinplot`. +Handles np.ndarrays where the ndarray is a list of lists of variable sizes.""" + ... + +def _dist_reduce(data: Incomplete, *, mean: Incomplete=None, means: Incomplete=None, median: Incomplete=None, medians: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Reduce statistical distributions to means and medians. Tack on a +distribution keyword argument for processing down the line.""" + ... + +def _dist_range(data: Incomplete, distribution: Incomplete, *, errdata: Incomplete=None, absolute: Incomplete=False, label: Incomplete=False, stds: Incomplete=None, pctiles: Incomplete=None, stds_default: Incomplete=None, pctiles_default: Incomplete=None) -> Incomplete: + """Return a plottable characteristic range for the statistical distribution +relative to the input coordinate (generally a mean or median).""" + ... + +def _safe_mask(mask: Incomplete, *args: Incomplete) -> Incomplete: + """Safely apply the mask to the input arrays, accounting for existing masked +or invalid values. Values matching ``False`` are set to `np.nan`.""" + ... + +def _safe_range(data: Incomplete, lo: Incomplete=0, hi: Incomplete=100) -> Incomplete: + """Safely return the minimum and maximum (default) or percentile range accounting +for masked values. Use min and max functions when possible for speed. Return +``None`` if we fail to get a valid range.""" + ... + +def _meta_coords(*args: Incomplete, which: Incomplete='x', **kwargs: Incomplete) -> Incomplete: + """Return the index arrays associated with string coordinates and +keyword arguments updated with index locators and formatters.""" + ... + +def _meta_labels(data: Incomplete, axis: Incomplete=0, always: Incomplete=True) -> Incomplete: + """Return the array-like "labels" along axis `axis`. If `always` is ``False`` +we return ``None`` for simple ndarray input.""" + ... + +def _meta_title(data: Incomplete, include_units: Incomplete=True) -> str | None: + """Return the "title" of an array-like object with metadata. +Include units in the title if `include_units` is ``True``.""" + ... + +def _meta_units(data: Incomplete) -> Incomplete: + """Get the unit string from the `xarray.DataArray` attributes or the +`pint.Quantity`. Format the latter with :rcraw:`unitformat`.""" + ... + +def _geo_basemap_1d(x: Incomplete, *ys: Incomplete, xmin: Incomplete=-180, xmax: Incomplete=180) -> Incomplete: + """Fix basemap geographic 1D data arrays.""" + ... + +def _geo_basemap_2d(x: Incomplete, y: Incomplete, *zs: Incomplete, xmin: Incomplete=-180, xmax: Incomplete=180, globe: Incomplete=False) -> Incomplete: + """Fix basemap geographic 2D data arrays.""" + ... + +def _geo_cartopy_1d(x: Incomplete, *ys: Incomplete) -> Incomplete: + """Fix cartopy geographic 1D data arrays.""" + ... + +def _geo_cartopy_2d(x: Incomplete, y: Incomplete, *zs: Incomplete, globe: Incomplete=False) -> Incomplete: + """Fix cartopy geographic 2D data arrays.""" + ... + +def _geo_clip(*ys: Incomplete) -> Incomplete: + """Ensure latitudes fall within ``-90`` to ``90``. Important if we +add graticule edges with `edges`.""" + ... + +def _geo_inbounds(x: Incomplete, y: Incomplete, xmin: Incomplete=-180, xmax: Incomplete=180) -> Incomplete: + """Fix conflicts with map coordinates by rolling the data to fall between the +minimum and maximum longitudes and masking out-of-bounds data points.""" + ... + +def _geo_globe(x: Incomplete, y: Incomplete, z: Incomplete, xmin: Incomplete=-180, modulo: Incomplete=False) -> Incomplete: + """Ensure global coverage by fixing gaps over poles and across +longitude seams. Increases the size of the arrays.""" + ... diff --git a/ultraplot/internals/kwargs.pyi b/ultraplot/internals/kwargs.pyi new file mode 100644 index 000000000..08cc9e62b --- /dev/null +++ b/ultraplot/internals/kwargs.pyi @@ -0,0 +1,68 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Keyword-argument and alias resolution utilities. + +These helpers centralize how ultraplot resolves keyword aliases, folds synonym +keywords into canonical names, and pops parameters/properties out of ``**kwargs``. +They live in their own module (rather than the ``internals`` grab-bag) because +they form a single cohesive concern and are imported throughout the package. +""" +from _typeshed import Incomplete +import functools +import inspect +from typing import Any, Callable, TypeVar, cast +from . import warnings +_F = TypeVar('_F', bound=Callable[..., Any]) +__all__ = ['_not_none', '_alias_kwargs', '_alias_maps', '_get_aliases', '_kwargs_to_args', '_pop_kwargs', '_pop_params', '_pop_props'] + +def _not_none(*args: Incomplete, default: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Return the first non-``None`` value. This is used with keyword arg aliases and +for setting default values. Use `kwargs` to issue warnings when multiple passed.""" + ... + +def _alias_kwargs(**aliases: Incomplete) -> Callable[[_F], _F]: + """Fold keyword-argument aliases into their canonical names before a call. + +Each keyword maps a canonical parameter name to a tuple of accepted synonyms, +e.g. ``@_alias_kwargs(figwidth=("width",), refnum=("ref",))``. A synonym passed +by the caller is renamed to its canonical name. Passing a canonical together +with a synonym (or two synonyms) warns and keeps the canonical / first value, +matching the precedence and warning of `_not_none`. This replaces the repetitive +``x = _not_none(x=x, y=y)`` boilerplate at the top of aliased functions. + +This handles keyword aliases only: a canonical argument passed *positionally* +is not deduplicated against its synonyms, and a synonym must not shadow a +different real parameter of the wrapped function.""" + ... +_alias_maps = {'rgba': {'red': ('r',), 'green': ('g',), 'blue': ('b',), 'alpha': ('a',)}, 'hsla': {'hue': ('h',), 'saturation': ('s', 'c', 'chroma'), 'luminance': ('l',), 'alpha': ('a',)}, 'patch': {'alpha': ('a', 'alphas', 'fa', 'facealpha', 'facealphas', 'fillalpha', 'fillalphas'), 'color': ('c', 'colors'), 'edgecolor': ('ec', 'edgecolors'), 'facecolor': ('fc', 'facecolors', 'fillcolor', 'fillcolors'), 'hatch': ('h', 'hatching'), 'linestyle': ('ls', 'linestyles'), 'linewidth': ('lw', 'linewidths', 'ew', 'edgewidth', 'edgewidths'), 'zorder': ('z', 'zorders')}, 'line': {'alpha': ('a', 'alphas'), 'color': ('c', 'colors'), 'dashes': ('d', 'dash'), 'drawstyle': ('ds', 'drawstyles'), 'fillstyle': ('fs', 'fillstyles', 'mfs', 'markerfillstyle', 'markerfillstyles'), 'linestyle': ('ls', 'linestyles'), 'linewidth': ('lw', 'linewidths'), 'marker': ('m', 'markers'), 'markersize': ('s', 'ms', 'markersizes'), 'markeredgewidth': ('ew', 'edgewidth', 'edgewidths', 'mew', 'markeredgewidths'), 'markeredgecolor': ('ec', 'edgecolor', 'edgecolors', 'mec', 'markeredgecolors'), 'markerfacecolor': ('fc', 'facecolor', 'facecolors', 'fillcolor', 'fillcolors', 'mc', 'markercolor', 'markercolors', 'mfc', 'markerfacecolors'), 'zorder': ('z', 'zorders')}, 'collection': {'alpha': ('a', 'alphas'), 'colors': ('c', 'color'), 'edgecolors': ('ec', 'edgecolor', 'mec', 'markeredgecolor', 'markeredgecolors'), 'facecolors': ('fc', 'facecolor', 'fillcolor', 'fillcolors', 'mc', 'markercolor', 'markercolors', 'mfc', 'markerfacecolor', 'markerfacecolors'), 'linestyles': ('ls', 'linestyle'), 'linewidths': ('lw', 'linewidth', 'ew', 'edgewidth', 'edgewidths', 'mew', 'markeredgewidth', 'markeredgewidths'), 'marker': ('m', 'markers'), 'sizes': ('s', 'ms', 'markersize', 'markersizes'), 'zorder': ('z', 'zorders')}, 'text': {'color': ('c', 'fontcolor'), 'fontfamily': ('family', 'name', 'fontname'), 'fontsize': ('size',), 'fontstretch': ('stretch',), 'fontstyle': ('style',), 'fontvariant': ('variant',), 'fontweight': ('weight',), 'fontproperties': ('fp', 'font', 'font_properties'), 'zorder': ('z', 'zorders')}} +_INTERNAL_POP_PARAMS = frozenset({'default_cmap', 'default_discrete', 'inbounds', 'plot_contours', 'plot_lines', 'skip_autolev', 'to_centers'}) + +def _signature_cached(func: Incomplete) -> Incomplete: + """Cache inspect.signature lookups for hot utility paths.""" + ... + +def _get_signature(func: Incomplete) -> Incomplete: + """Return a signature, normalizing bound methods to their underlying function.""" + ... + +def _get_aliases(category: Incomplete, *keys: Incomplete) -> Incomplete: + """Get all available aliases.""" + ... + +def _kwargs_to_args(options: Incomplete, *args: Incomplete, allow_extra: Incomplete=False, **kwargs: Incomplete) -> Incomplete: + """Translate keyword arguments to positional arguments. Permit omitted +arguments so that plotting functions can infer values.""" + ... + +def _pop_kwargs(kwargs: Incomplete, *keys: Incomplete, **aliases: Incomplete) -> Incomplete: + """Pop the input properties and return them in a new dictionary.""" + ... + +def _pop_params(kwargs: Incomplete, *funcs: Incomplete, ignore_internal: Incomplete=False) -> Incomplete: + """Pop parameters of the input functions or methods.""" + ... + +def _pop_props(input: Incomplete, *categories: Incomplete, prefix: Incomplete=None, ignore: Incomplete=None, skip: Incomplete=None) -> Incomplete: + """Pop the registered properties and return them in a new dictionary.""" + ... diff --git a/ultraplot/internals/labels.pyi b/ultraplot/internals/labels.pyi new file mode 100644 index 000000000..6024e4713 --- /dev/null +++ b/ultraplot/internals/labels.pyi @@ -0,0 +1,30 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Utilities related to matplotlib text labels. +""" +from _typeshed import Incomplete +import matplotlib.patheffects as mpatheffects +import matplotlib.text as mtext +from matplotlib.font_manager import FontProperties +from ..config import rc +from . import ic +LABEL_PSEUDO_PROPS = frozenset({'border', 'bordercolor', 'borderinvert', 'borderwidth', 'borderstyle', 'bbox', 'bboxcolor', 'bboxstyle', 'bboxalpha', 'bboxpad'}) + +def _split_label_props(kwargs: Incomplete) -> Incomplete: + """Split a kwargs dict into (label_props, text_kwargs) so the latter can be +passed to `mtext.Text(...)` and the former applied via `_update_label`.""" + ... + +def merge_font_properties(dest_fp: FontProperties, src_fp: FontProperties) -> FontProperties: + ... + +def _transfer_label(src: mtext.Text, dest: mtext.Text) -> None: + """Transfer the input text object properties and content to the destination +text object. Then clear the input object text.""" + ... + +def _update_label(text: Incomplete, props: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Add a monkey patch for ``Text.update`` with pseudo "border" and "bbox" +properties without wrapping the entire class. This facillitates inset titles.""" + ... diff --git a/ultraplot/internals/rcsetup.pyi b/ultraplot/internals/rcsetup.pyi new file mode 100644 index 000000000..29c400bcb --- /dev/null +++ b/ultraplot/internals/rcsetup.pyi @@ -0,0 +1,222 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Utilities for global configuration. +""" +from _typeshed import Incomplete +import functools +import re +import sys +from collections.abc import MutableMapping +from numbers import Integral, Real +import matplotlib as mpl +import matplotlib.rcsetup as msetup +import numpy as np +from cycler import Cycler +from matplotlib import RcParams +from matplotlib import rcParamsDefault as _rc_matplotlib_native +from matplotlib.colors import Colormap +from matplotlib.font_manager import font_scalings +if hasattr(mpl, '_fontconfig_pattern'): + from matplotlib._fontconfig_pattern import parse_fontconfig_pattern +else: + from matplotlib.fontconfig_pattern import parse_fontconfig_pattern +from . import ic, warnings +from .versions import _version_mpl +REGEX_NAMED_COLOR = re.compile('\\A[a-zA-Z0-9:_ -]*\\Z') +VALIDATE_REGISTERED_CMAPS = False +VALIDATE_REGISTERED_COLORS = False +BLACK = 'black' +CYCLE = 'colorblind' +CMAPCYC = 'twilight' +CMAPDIV = 'BuRd' +CMAPSEQ = 'Fire' +CMAPCAT = 'colorblind10' +DIVERGING = 'div' +FRAMEALPHA = 0.8 +FONTNAME = 'sans-serif' +FONTSIZE = 9.0 +GRIDALPHA = 0.1 +GRIDBELOW = 'line' +GRIDPAD = 3.0 +GRIDRATIO = 0.5 +GRIDSTYLE = '-' +LABELPAD = 4.0 +LARGESIZE = 'med-large' +LINEWIDTH = 0.6 +MARGIN = 0.05 +MATHTEXT = False +SMALLSIZE = 'medium' +TICKDIR = 'out' +TICKLEN = 4.0 +TICKLENRATIO = 0.5 +TICKMINOR = True +TICKPAD = 2.0 +TICKWIDTHRATIO = 0.8 +TITLEPAD = 5.0 +WHITE = 'white' +ZLINES = 2 +ZPATCHES = 1 +LEGEND_LOCS = {'fill': 'fill', 'inset': 'best', 'i': 'best', 0: 'best', 1: 'upper right', 2: 'upper left', 3: 'lower left', 4: 'lower right', 5: 'center left', 6: 'center right', 7: 'lower center', 8: 'upper center', 9: 'center', 'l': 'left', 'r': 'right', 'b': 'bottom', 't': 'top', 'c': 'center', 'ur': 'upper right', 'ul': 'upper left', 'll': 'lower left', 'lr': 'lower right', 'cr': 'center right', 'cl': 'center left', 'uc': 'upper center', 'lc': 'lower center', 'ol': 'outer left', 'or': 'outer right'} +TEXT_LOCS = ... +COLORBAR_LOCS = ... +PANEL_LOCS = ... +ALIGN_LOCS = ... +EM_KEYS = ('legend.borderpad', 'legend.labelspacing', 'legend.handlelength', 'legend.handleheight', 'legend.handletextpad', 'legend.borderaxespad', 'legend.columnspacing') +PT_KEYS = ('font.size', 'xtick.major.size', 'xtick.minor.size', 'ytick.major.size', 'ytick.minor.size', 'xtick.major.pad', 'xtick.minor.pad', 'ytick.major.pad', 'ytick.minor.pad', 'xtick.major.width', 'xtick.minor.width', 'ytick.major.width', 'ytick.minor.width', 'axes.labelpad', 'axes.titlepad', 'axes.linewidth', 'grid.linewidth', 'patch.linewidth', 'hatch.linewidth', 'lines.linewidth', 'contour.linewidth') +FONT_KEYS = set() + +def _get_default_param(key: Incomplete) -> Incomplete: + """Get the default parameter from one of three places. This is used for +the :rc: role when compiling docs and when saving ultraplotrc files.""" + ... + +def _validate_abc(value: Incomplete) -> Incomplete: + """Validate a-b-c setting.""" + ... + +def _validate_belongs(*options: Incomplete) -> Incomplete: + """Return a validator ensuring the item belongs in the list.""" + ... +_CFTIME_RESOLUTIONS = ('SECONDLY', 'MINUTELY', 'HOURLY', 'DAILY', 'MONTHLY', 'YEARLY') + +def _validate_cftime_resolution_format(units: dict) -> dict: + ... + +def _validate_cftime_resolution(unit: str) -> str: + ... + +def _validate_cmap(subtype: Incomplete, cycle: Incomplete=False) -> Incomplete: + """Validate the colormap or cycle. Possibly skip name registration check +and assign the colormap name rather than a colormap instance.""" + ... + +def _validate_color(value: Incomplete, alternative: Incomplete=None) -> Incomplete: + """Validate the color. Possibly skip name registration check.""" + ... + +def _validate_bool_or_iterable(value: Incomplete) -> Incomplete: + ... + +def _validate_bool_or_string(value: Incomplete) -> Incomplete: + ... + +def _validate_fontprops(s: Incomplete) -> Incomplete: + """Parse font property with support for ``'regular'`` placeholder.""" + ... + +def _validate_fontsize(value: Incomplete) -> Incomplete: + """Validate font size with new scalings and permitting other units.""" + ... + +def _validate_labels(labels: Incomplete, lon: Incomplete=True) -> Incomplete: + """Convert labels argument to length-4 boolean array.""" + ... + +def _validate_or_none(validator: Incomplete) -> Incomplete: + """Allow none otherwise pass to the input validator.""" + ... + +def _validate_float_or_iterable(value: Incomplete) -> Incomplete: + ... + +def _validate_string_or_iterable(value: Incomplete) -> Incomplete: + ... + +def _validate_rotation(value: Incomplete) -> Incomplete: + """Valid rotation arguments.""" + ... + +def _validate_units(dest: Incomplete) -> Incomplete: + """Validate the input using the units function.""" + ... + +def _validate_float_or_auto(value: Incomplete) -> Incomplete: + ... + +def _validate_tuple_int_2(value: Incomplete) -> Incomplete: + ... + +def _validate_tuple_float_2(value: Incomplete) -> Incomplete: + ... + +def _rst_table() -> Incomplete: + """Return the setting names and descriptions in an RST-style table.""" + ... + +def _to_string(value: Incomplete) -> Incomplete: + """Translate setting to a string suitable for saving.""" + ... + +def _yaml_table(rcdict: Incomplete, comment: Incomplete=True, description: Incomplete=False) -> Incomplete: + """Return the settings as a nicely tabulated YAML-style table.""" + ... + +class _RcParams(MutableMapping, dict): + """ + A simple dictionary with locked inputs and validated assignments. + """ + + def __init__(self, source: Incomplete, validate: Incomplete) -> None: + ... + + def __repr__(self) -> Incomplete: + ... + + def __str__(self) -> Incomplete: + ... + + def __len__(self) -> Incomplete: + ... + + def __iter__(self) -> Incomplete: + ... + + def __getitem__(self, key: Incomplete) -> Incomplete: + ... + + def __setitem__(self, key: Incomplete, value: Incomplete) -> Incomplete: + ... + + @staticmethod + def _check_key(key: Incomplete, value: Incomplete=None) -> Incomplete: + ... + + def copy(self) -> Incomplete: + ... +_validate_pt = _validate_units('pt') +_validate_em = _validate_units('em') +_validate_in = _validate_units('in') +_validate_bool = msetup.validate_bool +_validate_int = msetup.validate_int +_validate_float = msetup.validate_float +_validate_string = msetup.validate_string +_validate_fontname = msetup.validate_stringlist +_validate_fontweight = getattr(msetup, 'validate_fontweight', _validate_string) +_validate_boxstyle = _validate_belongs('square', 'circle', 'round', 'round4', 'sawtooth', 'roundtooth') +_validate_joinstyle = _validate_belongs('miter', 'round', 'bevel') +if hasattr(msetup, '_validate_linestyle'): + _validate_linestyle = msetup._validate_linestyle +else: + _validate_linestyle = _validate_belongs('-', ':', '--', '-.', 'solid', 'dashed', 'dashdot', 'dotted', 'none', ' ', '') + +def _validator_accepts(validator: Incomplete, value: Incomplete) -> Incomplete: + ... +_validate = RcParams.validate +_rc_matplotlib_default = {'axes.axisbelow': GRIDBELOW, 'axes.formatter.use_mathtext': MATHTEXT, 'axes.grid': True, 'axes.grid.which': 'major', 'axes.edgecolor': BLACK, 'axes.labelcolor': BLACK, 'axes.labelpad': LABELPAD, 'axes.labelsize': SMALLSIZE, 'axes.labelweight': 'normal', 'axes.linewidth': LINEWIDTH, 'axes.titlepad': TITLEPAD, 'axes.titlesize': LARGESIZE, 'axes.titleweight': 'normal', 'axes.xmargin': MARGIN, 'axes.ymargin': MARGIN, 'errorbar.capsize': 3.0, 'figure.autolayout': False, 'figure.figsize': (4.0, 4.0), 'figure.dpi': 100, 'figure.facecolor': '#f4f4f4', 'figure.titlesize': LARGESIZE, 'figure.titleweight': 'bold', 'font.serif': ['TeX Gyre Schola', 'TeX Gyre Bonum', 'TeX Gyre Termes', 'TeX Gyre Pagella', 'DejaVu Serif', 'Bitstream Vera Serif', 'Computer Modern Roman', 'Bookman', 'Century Schoolbook L', 'Charter', 'ITC Bookman', 'New Century Schoolbook', 'Nimbus Roman No9 L', 'Noto Serif', 'Palatino', 'Source Serif Pro', 'Times New Roman', 'Times', 'Utopia', 'serif'], 'font.sans-serif': ['TeX Gyre Heros', 'DejaVu Sans', 'Bitstream Vera Sans', 'Computer Modern Sans Serif', 'Arial', 'Avenir', 'Fira Math', 'Fira Sans', 'Frutiger', 'Geneva', 'Gill Sans', 'Helvetica', 'Lucid', 'Lucida Grande', 'Myriad Pro', 'Noto Sans', 'Roboto', 'Source Sans Pro', 'Tahoma', 'Trebuchet MS', 'Ubuntu', 'Univers', 'Verdana', 'sans-serif'], 'font.cursive': ['TeX Gyre Chorus', 'Apple Chancery', 'Felipa', 'Sand', 'Script MT', 'Textile', 'Zapf Chancery', 'cursive'], 'font.fantasy': ['TeX Gyre Adventor', 'Avant Garde', 'Charcoal', 'Chicago', 'Comic Sans MS', 'Futura', 'Humor Sans', 'Impact', 'Optima', 'Western', 'xkcd', 'fantasy'], 'font.monospace': ['TeX Gyre Cursor', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', 'Computer Modern Typewriter', 'Andale Mono', 'Courier New', 'Courier', 'Fixed', 'Nimbus Mono L', 'Terminal', 'monospace'], 'font.family': FONTNAME, 'font.size': FONTSIZE, 'grid.alpha': GRIDALPHA, 'grid.color': BLACK, 'grid.linestyle': GRIDSTYLE, 'grid.linewidth': LINEWIDTH, 'hatch.color': BLACK, 'hatch.linewidth': LINEWIDTH, 'image.cmap': CMAPSEQ, 'image.interpolation': 'none', 'lines.linestyle': '-', 'lines.linewidth': 1.5, 'lines.markersize': 6.0, 'legend.borderaxespad': 0, 'legend.borderpad': 0.5, 'legend.columnspacing': 1.5, 'legend.edgecolor': BLACK, 'legend.facecolor': WHITE, 'legend.fancybox': False, 'legend.fontsize': SMALLSIZE, 'legend.framealpha': FRAMEALPHA, 'legend.handleheight': 1.0, 'legend.handlelength': 2.0, 'legend.handletextpad': 0.5, 'mathtext.default': 'it', 'mathtext.fontset': 'custom', 'mathtext.bf': 'regular:bold', 'mathtext.cal': 'cursive', 'mathtext.it': 'regular:italic', 'mathtext.rm': 'regular', 'mathtext.sf': 'regular', 'mathtext.tt': 'monospace', 'patch.linewidth': LINEWIDTH, 'savefig.bbox': None, 'savefig.directory': '', 'savefig.dpi': 1000, 'savefig.facecolor': WHITE, 'savefig.format': 'pdf', 'savefig.transparent': False, 'xtick.color': BLACK, 'xtick.direction': TICKDIR, 'xtick.labelsize': SMALLSIZE, 'xtick.major.pad': TICKPAD, 'xtick.major.size': TICKLEN, 'xtick.major.width': LINEWIDTH, 'xtick.minor.pad': TICKPAD, 'xtick.minor.size': TICKLEN * TICKLENRATIO, 'xtick.minor.width': LINEWIDTH * TICKWIDTHRATIO, 'xtick.minor.visible': TICKMINOR, 'ytick.color': BLACK, 'ytick.direction': TICKDIR, 'ytick.labelsize': SMALLSIZE, 'ytick.major.pad': TICKPAD, 'ytick.major.size': TICKLEN, 'ytick.major.width': LINEWIDTH, 'ytick.minor.pad': TICKPAD, 'ytick.minor.size': TICKLEN * TICKLENRATIO, 'ytick.minor.width': LINEWIDTH * TICKWIDTHRATIO, 'ytick.minor.visible': TICKMINOR} +_addendum_rotation = " Must be 'vertical', 'horizontal', or a float indicating degrees." +_addendum_em = ' Interpreted by `~ultraplot.utils.units`. Numeric units are em-widths.' +_addendum_in = ' Interpreted by `~ultraplot.utils.units`. Numeric units are inches.' +_addendum_pt = ' Interpreted by `~ultraplot.utils.units`. Numeric units are points.' +_addendum_font = ' Must be a :ref:`relative font size ` or unit string interpreted by `~ultraplot.utils.units`. Numeric units are points.' +_rc_ultraplot_table = {'navigation.preview': (True, _validate_bool, 'Whether to simplify dense artists and ticks while interactively panning or rotating. Disable for exact rendering during navigation.'), 'curved_quiver.arrowsize': (1.0, _validate_float, 'Default size scaling for arrows in curved quiver plots.'), 'curved_quiver.arrowstyle': ('-|>', _validate_string, 'Default arrow style for curved quiver plots.'), 'curved_quiver.scale': (1.0, _validate_float, 'Default scale factor for curved quiver plots.'), 'curved_quiver.grains': (15, _validate_int, 'Default number of grains (segments) for curved quiver arrows.'), 'curved_quiver.density': (10, _validate_int, 'Default density of arrows for curved quiver plots.'), 'curved_quiver.arrows_at_end': (True, _validate_bool, 'Whether to draw arrows at the end of curved quiver lines by default.'), 'external.shrink': (0.9, _validate_float, 'Default shrink factor for external axes containers.'), 'sankey.nodepad': (0.02, _validate_float, 'Vertical padding between nodes in layered sankey diagrams.'), 'sankey.nodewidth': (0.03, _validate_float, 'Node width for layered sankey diagrams (axes-relative units).'), 'sankey.margin': (0.05, _validate_float, 'Margin around layered sankey diagrams (axes-relative units).'), 'sankey.flow.alpha': (0.75, _validate_float, 'Flow transparency for layered sankey diagrams.'), 'sankey.flow.curvature': (0.5, _validate_float, 'Flow curvature for layered sankey diagrams.'), 'sankey.node.facecolor': ('0.75', _validate_color, 'Default node facecolor for layered sankey diagrams.'), 'ribbon.xmargin': (0.12, _validate_float, 'Horizontal margin around ribbon diagrams (axes-relative units).'), 'ribbon.ymargin': (0.08, _validate_float, 'Vertical margin around ribbon diagrams (axes-relative units).'), 'ribbon.rowheightratio': (2.2, _validate_float, 'Height scale factor controlling ribbon row occupancy.'), 'ribbon.nodewidth': (0.018, _validate_float, 'Node width for ribbon diagrams (axes-relative units).'), 'ribbon.flow.curvature': (0.45, _validate_float, 'Flow curvature for ribbon diagrams.'), 'ribbon.flow.alpha': (0.58, _validate_float, 'Flow transparency for ribbon diagrams.'), 'ribbon.topic_labels': (True, _validate_bool, 'Whether to draw topic labels on the right side of ribbon diagrams.'), 'ribbon.topic_label_offset': (0.028, _validate_float, 'Offset for right-side ribbon topic labels.'), 'ribbon.topic_label_size': (7.4, _validate_float, 'Font size for ribbon topic labels.'), 'ribbon.topic_label_box': (True, _validate_bool, 'Whether to draw backing boxes behind ribbon topic labels.'), 'style': (None, _validate_or_none(_validate_string), "The default matplotlib `stylesheet `__ name. If ``None``, a custom ultraplot style is used. If ``'default'``, the default matplotlib style is used."), 'abc': (False, _validate_abc, "If ``False`` then a-b-c labels are disabled. If ``True`` the default label style `a` is used. If string this indicates the style and must contain the character `a` or ``A``, for example ``'a.'`` or ``'(A)'``."), 'abc.border': (True, _validate_bool, 'Whether to draw a white border around a-b-c labels when :rcraw:`abc.loc` is inside the axes.'), 'abc.borderwidth': (1.5, _validate_pt, 'Width of the white border around a-b-c labels.'), 'text.borderstyle': ('bevel', _validate_joinstyle, "Join style for text border strokes. Must be one of ``'miter'``, ``'round'``, or ``'bevel'``."), 'text.align': (False, _validate_bool, 'Whether text and annotations avoid overlapping each other and the data by default. Set to ``True`` to opt every label into the solver used by `~ultraplot.axes.Axes.auto_align_text`.'), 'text.align.pad': (2.0, _validate_pt, 'Padding in points kept around auto-aligned text.'), 'text.align.maxiter': (60, _validate_int, 'Maximum number of relaxation iterations used to auto-align text.'), 'text.align.arrows': (False, _validate_bool, 'Whether auto-aligned text draws a connector back to the point it labels.'), 'text.curved.upright': (True, _validate_bool, 'Whether curved text is flipped to remain upright by default.'), 'text.curved.ellipsis': (False, _validate_bool, 'Whether to show ellipses when curved text exceeds path length.'), 'text.curved.avoid_overlap': (True, _validate_bool, 'Whether curved text hides overlapping glyphs by default.'), 'text.curved.overlap_tol': (0.1, _validate_float, 'Overlap threshold used when hiding curved-text glyphs.'), 'text.curved.curvature_pad': (2.0, _validate_float, 'Extra curved-text glyph spacing per radian of local curvature.'), 'text.curved.min_advance': (1.0, _validate_float, 'Minimum extra curved-text glyph spacing in pixels.'), 'abc.bbox': (False, _validate_bool, 'Whether to draw semi-transparent bounding boxes around a-b-c labels when :rcraw:`abc.loc` is inside the axes.'), 'abc.bboxcolor': (WHITE, _validate_color, 'a-b-c label bounding box color.'), 'abc.bboxstyle': ('square', _validate_boxstyle, 'a-b-c label bounding box style.'), 'abc.bboxalpha': (0.5, _validate_float, 'a-b-c label bounding box opacity.'), 'abc.bboxpad': (None, _validate_or_none(_validate_pt), 'Padding for the a-b-c label bounding box. By default this is scaled to make the box flush against the subplot edge.' + _addendum_pt), 'abc.color': (BLACK, _validate_color, 'a-b-c label color.'), 'abc.loc': ('left', _validate_belongs(*TEXT_LOCS), 'a-b-c label position. For options see the :ref:`location table `.'), 'abc.size': (LARGESIZE, _validate_fontsize, 'a-b-c label font size.' + _addendum_font), 'abc.titlepad': (LABELPAD, _validate_pt, 'Padding separating the title and a-b-c label when in the same location.' + _addendum_pt), 'abc.weight': ('bold', _validate_fontweight, 'a-b-c label font weight.'), 'autoformat': (True, _validate_bool, 'Whether to automatically apply labels from `pandas.Series`, `pandas.DataFrame`, and `xarray.DataArray` objects passed to plotting functions. See also :rcraw:`unitformat`.'), 'axes.alpha': (None, _validate_or_none(_validate_float), 'Opacity of the background axes patch.'), 'axes.inbounds': (True, _validate_bool, 'Whether to exclude out-of-bounds data when determining the default *y* (*x*) axis limits and the *x* (*y*) axis limits have been locked.'), 'axes.margin': (MARGIN, _validate_float, 'The fractional *x* and *y* axis margins when limits are unset.'), 'axes.sticky_edges': (True, _validate_bool, 'Whether artists added by plotting commands like `plot`, `plotx`, `vlines`, `hlines`, `fill_between`, and `fill_betweenx` are given "sticky" edges, i.e. whether the default axis limits are the artist bounds with no padding. See also `Axes.use_sticky_edges`.'), 'bar.bar_labels': (False, _validate_bool, 'Add value of the bars to the bar labels'), 'borders': (False, _validate_bool, 'Toggles country border lines on and off.'), 'borders.alpha': (None, _validate_or_none(_validate_float), 'Opacity for country border lines.'), 'borders.color': (BLACK, _validate_color, 'Line color for country border lines.'), 'borders.linewidth': (LINEWIDTH, _validate_pt, 'Line width for country border lines.'), 'borders.zorder': (ZLINES, _validate_float, 'Z-order for country border lines.'), 'borders.rasterized': (False, _validate_bool, 'Toggles rasterization on or off for border feature in GeoAxes.'), 'bottomlabel.color': (BLACK, _validate_color, 'Font color for column labels on the bottom of the figure.'), 'bottomlabel.pad': (TITLEPAD, _validate_pt, 'Padding between axes content and column labels on the bottom of the figure.' + _addendum_pt), 'bottomlabel.sharedpad': (2 * TITLEPAD, _validate_pt, 'Padding between column labels and a shared x label on the bottom of the figure.' + _addendum_pt), 'bottomlabel.rotation': ('horizontal', _validate_rotation, 'Rotation for column labels at the bottom of the figure.' + _addendum_rotation), 'bottomlabel.size': (LARGESIZE, _validate_fontsize, 'Font size for column labels on the bottom of the figure.' + _addendum_font), 'bottomlabel.weight': ('bold', _validate_fontweight, 'Font weight for column labels on the bottom of the figure.'), 'cftime.time_unit': ('days since 2000-01-01', _validate_string, 'Time unit for non-Gregorian calendars.'), 'cftime.resolution': ('DAILY', _validate_cftime_resolution, 'Default time resolution for non-Gregorian calendars.'), 'cftime.time_resolution_format': ({'SECONDLY': '%S', 'MINUTELY': '%M', 'HOURLY': '%H', 'DAILY': '%d', 'MONTHLY': '%m', 'YEARLY': '%Y'}, _validate_cftime_resolution_format, 'Dict used for formatting non-Gregorian calendars.'), 'cftime.max_display_ticks': (7, _validate_int, 'Number of ticks to display for cftime units.'), 'coast': (False, _validate_bool, 'Toggles coastline lines on and off.'), 'coast.alpha': (None, _validate_or_none(_validate_float), 'Opacity for coast lines'), 'coast.color': (BLACK, _validate_color, 'Line color for coast lines.'), 'coast.linewidth': (LINEWIDTH, _validate_pt, 'Line width for coast lines.'), 'coast.zorder': (ZLINES, _validate_float, 'Z-order for coast lines.'), 'coast.rasterized': (False, _validate_bool, 'Toggles the rasterization of the coastlines feature for GeoAxes.'), 'colorbar.center_levels': (False, _validate_bool, 'Center the ticks in the center of each segment.'), 'colorbar.edgecolor': (BLACK, _validate_color, 'Color for the inset colorbar frame edge.'), 'colorbar.extend': (1.3, _validate_em, 'Length of rectangular or triangular "extensions" for panel colorbars.' + _addendum_em), 'colorbar.outline': (True, _validate_bool, 'Whether to draw a frame around the colorbar.'), 'colorbar.labelrotation': ('auto', _validate_float_or_auto, 'Rotation of colorbar labels.'), 'colorbar.fancybox': (False, _validate_bool, 'Whether to use a "fancy" round bounding box for inset colorbar frames.'), 'colorbar.framealpha': (FRAMEALPHA, _validate_float, 'Opacity for inset colorbar frames.'), 'colorbar.facecolor': (WHITE, _validate_color, 'Color for the inset colorbar frame.'), 'colorbar.frameon': (True, _validate_bool, 'Whether to draw a frame behind inset colorbars.'), 'colorbar.grid': (False, _validate_bool, 'Whether to draw borders between each level of the colorbar.'), 'colorbar.insetextend': (0.9, _validate_em, 'Length of rectangular or triangular "extensions" for inset colorbars.' + _addendum_em), 'colorbar.insetlength': (8, _validate_em, 'Length of inset colorbars.' + _addendum_em), 'colorbar.insetpad': (0.7, _validate_em, 'Padding between axes edge and inset colorbars.' + _addendum_em), 'colorbar.insetwidth': (1.2, _validate_em, 'Width of inset colorbars.' + _addendum_em), 'colorbar.length': (1, _validate_em, 'Length of outer colorbars.'), 'colorbar.loc': ('right', _validate_belongs(*COLORBAR_LOCS), 'Inset colorbar location. For options see the :ref:`location table `.'), 'colorbar.width': (0.2, _validate_in, 'Width of outer colorbars.' + _addendum_in), 'colorbar.rasterized': (False, _validate_bool, 'Whether to use rasterization for colorbar solids.'), 'colorbar.shadow': (False, _validate_bool, 'Whether to add a shadow underneath inset colorbar frames.'), 'legend.cat.line': (False, _validate_bool, 'Default line/marker mode for `Axes.catlegend`.'), 'legend.cat.marker': ('o', _validate_string, 'Default marker for `Axes.catlegend` entries.'), 'legend.cat.linestyle': ('-', _validate_linestyle, 'Default line style for `Axes.catlegend` entries.'), 'legend.cat.linewidth': (2.0, _validate_float, 'Default line width for `Axes.catlegend` entries.'), 'legend.cat.markersize': (6.0, _validate_float, 'Default marker size for `Axes.catlegend` entries.'), 'legend.cat.alpha': (None, _validate_or_none(_validate_float), 'Default alpha for `Axes.catlegend` entries.'), 'legend.cat.markeredgecolor': (None, _validate_or_none(_validate_color), 'Default marker edge color for `Axes.catlegend` entries.'), 'legend.cat.markeredgewidth': (None, _validate_or_none(_validate_float), 'Default marker edge width for `Axes.catlegend` entries.'), 'legend.size.color': ('0.35', _validate_color, 'Default marker color for `Axes.sizelegend` entries.'), 'legend.size.marker': ('o', _validate_string, 'Default marker for `Axes.sizelegend` entries.'), 'legend.size.area': (True, _validate_bool, 'Whether `Axes.sizelegend` interprets levels as marker area by default.'), 'legend.size.scale': (1.0, _validate_float, 'Default marker size scale factor for `Axes.sizelegend` entries.'), 'legend.size.minsize': (3.0, _validate_float, 'Default minimum marker size for `Axes.sizelegend` entries.'), 'legend.size.format': (None, _validate_or_none(_validate_string), 'Default label format string for `Axes.sizelegend` entries.'), 'legend.size.alpha': (None, _validate_or_none(_validate_float), 'Default alpha for `Axes.sizelegend` entries.'), 'legend.size.markeredgecolor': (None, _validate_or_none(_validate_color), 'Default marker edge color for `Axes.sizelegend` entries.'), 'legend.size.markeredgewidth': (None, _validate_or_none(_validate_float), 'Default marker edge width for `Axes.sizelegend` entries.'), 'legend.num.n': (5, _validate_int, 'Default number of sampled levels for `Axes.numlegend`.'), 'legend.num.cmap': ('viridis', _validate_cmap('continuous'), 'Default colormap for `Axes.numlegend` entries.'), 'legend.num.edgecolor': ('none', _validate_or_none(_validate_color), 'Default edge color for `Axes.numlegend` patch entries.'), 'legend.num.linewidth': (0.0, _validate_float, 'Default edge width for `Axes.numlegend` patch entries.'), 'legend.num.alpha': (None, _validate_or_none(_validate_float), 'Default alpha for `Axes.numlegend` entries.'), 'legend.num.format': (None, _validate_or_none(_validate_string), 'Default label format string for `Axes.numlegend` entries.'), 'legend.geo.facecolor': ('none', _validate_or_none(_validate_color), 'Default face color for `Axes.geolegend` entries.'), 'legend.geo.edgecolor': ('0.25', _validate_or_none(_validate_color), 'Default edge color for `Axes.geolegend` entries.'), 'legend.geo.linewidth': (1.0, _validate_float, 'Default edge width for `Axes.geolegend` entries.'), 'legend.geo.alpha': (None, _validate_or_none(_validate_float), 'Default alpha for `Axes.geolegend` entries.'), 'legend.geo.fill': (None, _validate_or_none(_validate_bool), 'Default fill mode for `Axes.geolegend` entries.'), 'legend.geo.country_reso': ('110m', _validate_belongs('10m', '50m', '110m'), 'Default Natural Earth resolution used for country shorthand geometry entries in `Axes.geolegend`.'), 'legend.geo.country_territories': (False, _validate_bool, 'Whether country shorthand entries in `Axes.geolegend` include far-away territories instead of pruning to the local footprint.'), 'legend.geo.country_proj': (None, _validate_or_none(_validate_string), 'Optional projection name for country shorthand entries in `Axes.geolegend`. Can be overridden per call with a cartopy CRS or callable.'), 'legend.geo.handlesize': (1.0, _validate_float, 'Scale factor applied to both legend handle length and height for `Axes.geolegend` when explicit handle dimensions are not provided.'), 'cycle': (CYCLE, _validate_cmap('discrete', cycle=True), 'Name of the color cycle assigned to :rcraw:`axes.prop_cycle`.'), 'cmap': (CMAPSEQ, _validate_cmap('continuous'), 'Alias for :rcraw:`cmap.sequential` and :rcraw:`image.cmap`.'), 'cmap.autodiverging': (True, _validate_bool, 'Whether to automatically apply a diverging colormap and normalizer based on the data.'), 'cmap.qualitative': (CMAPCAT, _validate_cmap('discrete'), 'Default colormap for qualitative datasets.'), 'cmap.cyclic': (CMAPCYC, _validate_cmap('continuous'), 'Default colormap for cyclic datasets.'), 'cmap.discrete': (None, _validate_or_none(_validate_bool), 'If ``True``, `~ultraplot.colors.DiscreteNorm` is used for every colormap plot. If ``False``, it is never used. If ``None``, it is used for all plot types except `imshow`, `matshow`, `spy`, `hexbin`, and `hist2d`.'), 'cmap.diverging': (CMAPDIV, _validate_cmap('continuous'), 'Default colormap for diverging datasets.'), 'cmap.inbounds': (True, _validate_bool, 'If ``True`` and the *x* and *y* axis limits are fixed, only in-bounds data is considered when determining the default colormap `vmin` and `vmax`.'), 'cmap.levels': (11, _validate_int, 'Default number of `~ultraplot.colors.DiscreteNorm` levels for plotting commands that use colormaps.'), 'cmap.listedthresh': (64, _validate_int, 'Native `~matplotlib.colors.ListedColormap`\\ s with more colors than this are converted to :class:`~ultraplot.colors.ContinuousColormap` rather than :class:`~ultraplot.colors.DiscreteColormap`. This helps translate continuous colormaps from external projects.'), 'cmap.lut': (256, _validate_int, 'Number of colors in the colormap lookup table. Alias for :rcraw:`image.lut`.'), 'cmap.robust': (False, _validate_bool, 'If ``True``, the default colormap `vmin` and `vmax` are chosen using the 2nd to 98th percentiles rather than the minimum and maximum.'), 'cmap.sequential': (CMAPSEQ, _validate_cmap('continuous'), 'Default colormap for sequential datasets. Alias for :rcraw:`image.cmap`.'), 'edgefix': (True, _validate_bool, 'Whether to fix issues with "white lines" appearing between patches in saved vector graphics and with vector graphic backends. Applies to colorbar levels and bar, area, pcolor, and contour plots.'), 'font.name': (FONTNAME, _validate_fontname, 'Alias for :rcraw:`font.family`.'), 'font.small': (SMALLSIZE, _validate_fontsize, 'Alias for :rcraw:`font.smallsize`.'), 'font.smallsize': (SMALLSIZE, _validate_fontsize, "Meta setting that changes the label-like sizes ``axes.labelsize``, ``legend.fontsize``, ``tick.labelsize``, and ``grid.labelsize``. Default is ``'medium'`` (equivalent to :rcraw:`font.size`)." + _addendum_font), 'font.large': (LARGESIZE, _validate_fontsize, 'Alias for :rcraw:`font.largesize`.'), 'font.largesize': (LARGESIZE, _validate_fontsize, "Meta setting that changes the title-like sizes ``abc.size``, ``title.size``, ``suptitle.size``, ``leftlabel.size``, ``rightlabel.size``, etc. Default is ``'med-large'`` (i.e. 1.1 times :rcraw:`font.size`)." + _addendum_font), 'formatter.timerotation': ('vertical', _validate_rotation, 'Rotation for *x* axis datetime tick labels.' + _addendum_rotation), 'formatter.zerotrim': (True, _validate_bool, 'Whether to trim trailing decimal zeros on tick labels.'), 'formatter.log': (False, _validate_bool, 'Whether to use log formatting (e.g., $10^{4}$) for logarithmically scaled axis tick labels.'), 'formatter.limits': ([-5, 6], _validate['axes.formatter.limits'], 'Alias for :rcraw:`axes.formatter.limits`.'), 'formatter.min_exponent': (0, _validate['axes.formatter.min_exponent'], 'Alias for :rcraw:`axes.formatter.min_exponent`.'), 'formatter.offset_threshold': (4, _validate['axes.formatter.offset_threshold'], 'Alias for :rcraw:`axes.formatter.offset_threshold`.'), 'formatter.use_locale': (False, _validate_bool, 'Alias for :rcraw:`axes.formatter.use_locale`.'), 'formatter.use_mathtext': (MATHTEXT, _validate_bool, 'Alias for :rcraw:`axes.formatter.use_mathtext`.'), 'formatter.use_offset': (True, _validate_bool, 'Alias for :rcraw:`axes.formatter.useOffset`.'), 'mathtext.cm_symbols': (False, _validate_bool, 'Whether to render ``\\mathcal`` and big operator symbols (``\\sum``, ``\\int``, ``\\bigcup``, etc.) with Computer Modern while preserving the active font for ordinary letters and numbers. Unlike ``mathtext.fontset: cm`` this does not affect the rest of the math text.'), 'geo.backend': ('cartopy', _validate_belongs('cartopy', 'basemap'), "The backend used for `~ultraplot.axes.GeoAxes`. Must be either 'cartopy' or 'basemap'. .. deprecated:: 3.0.0 The 'basemap' backend is deprecated and may be removed in a future release. Please use 'cartopy' instead."), 'geo.extent': ('globe', _validate_belongs('globe', 'auto'), "If ``'globe'``, the extent of cartopy `~ultraplot.axes.GeoAxes` is always global. If ``'auto'``, the extent is automatically adjusted based on plotted content. Default is ``'globe'``."), 'geo.round': (True, _validate_bool, "If ``True`` (the default), polar `~ultraplot.axes.GeoAxes` like ``'npstere'`` and ``'spstere'`` are bounded with circles rather than squares."), 'geo.choropleth.country_reso': ('110m', _validate_belongs('10m', '50m', '110m'), 'Default Natural Earth resolution used by `GeoAxes.choropleth` when country identifiers are resolved to polygons.'), 'geo.choropleth.country_territories': (False, _validate_bool, 'Whether `GeoAxes.choropleth` keeps distant territories when resolving country identifiers into Natural Earth geometries.'), 'geo.choropleth.zorder': (None, _validate_or_none(_validate_float), 'Default z-order for `GeoAxes.choropleth`. When ``None``, the choropleth is drawn just above the land feature.'), 'graph.draw_nodes': (True, _validate_bool_or_iterable, 'If ``True`` draws the nodes for all the nodes, otherwise only the nodes that are in the iterable.'), 'graph.draw_edges': (True, _validate_bool_or_iterable, 'If ``True`` draws the edges for all the edges, otherwise only the edges that are in the iterable.'), 'graph.draw_labels': (False, _validate_bool_or_iterable, 'If ``True`` draws the labels for all the nodes, otherwise only the nodes that are in the iterable.'), 'graph.draw_grid': (False, _validate_bool, 'If ``True`` draws the grid for all the edges, otherwise only the edges that are in the iterable.'), 'graph.aspect': ('equal', _validate_belongs('equal', 'auto'), 'The aspect ratio of the graph.'), 'graph.facecolor': ('none', _validate_color, 'The facecolor of the graph.'), 'graph.draw_spines': (False, _validate_bool_or_iterable, 'If ``True`` draws the spines for all the edges, otherwise only the edges that are in the iterable.'), 'graph.rescale': (True, _validate_bool, 'If ``True`` rescales the graph to fit the data.'), 'grid': (True, _validate_bool, 'Toggle major gridlines on and off.'), 'grid.below': (GRIDBELOW, _validate_belongs(False, 'line', True), "Alias for :rcraw:`axes.axisbelow`. If ``True``, draw gridlines below everything. If ``True``, draw them above everything. If ``'line'``, draw them above patches but below lines and markers."), 'grid.checkoverlap': (True, _validate_bool, 'Whether to have cartopy automatically check for and remove overlapping `~ultraplot.axes.GeoAxes` gridline labels.'), 'grid.dmslabels': (True, _validate_bool, 'Whether to use degrees-minutes-seconds rather than decimals for cartopy `~ultraplot.axes.GeoAxes` gridlines.'), 'grid.geolabels': (True, _validate_bool, "Whether to include the ``'geo'`` spine in cartopy >= 0.20 when otherwise toggling left, right, bottom, or top `~ultraplot.axes.GeoAxes` gridline labels."), 'grid.inlinelabels': (False, _validate_bool, 'Whether to add inline labels for cartopy `~ultraplot.axes.GeoAxes` gridlines.'), 'grid.labels': (False, _validate_bool, 'Whether to add outer labels for `~ultraplot.axes.GeoAxes` gridlines.'), 'grid.labelcolor': (BLACK, _validate_color, 'Font color for `~ultraplot.axes.GeoAxes` gridline labels.'), 'grid.labelpad': (GRIDPAD, _validate_pt, 'Padding between the map boundary and cartopy `~ultraplot.axes.GeoAxes` gridline labels.' + _addendum_pt), 'grid.labelsize': (SMALLSIZE, _validate_fontsize, 'Font size for `~ultraplot.axes.GeoAxes` gridline labels.' + _addendum_font), 'grid.labelweight': ('normal', _validate_fontweight, 'Font weight for `~ultraplot.axes.GeoAxes` gridline labels.'), 'grid.nsteps': (250, _validate_int, 'Number of points used to draw cartopy `~ultraplot.axes.GeoAxes` gridlines.'), 'grid.pad': (GRIDPAD, _validate_pt, 'Alias for :rcraw:`grid.labelpad`.'), 'grid.rotatelabels': (False, _validate_bool, 'Whether to rotate cartopy `~ultraplot.axes.GeoAxes` gridline labels.'), 'grid.style': ('-', _validate_linestyle, 'Major gridline style. Alias for :rcraw:`grid.linestyle`.'), 'grid.width': (LINEWIDTH, _validate_pt, 'Major gridline width. Alias for :rcraw:`grid.linewidth`.'), 'grid.widthratio': (GRIDRATIO, _validate_float, 'Ratio of minor gridline width to major gridline width.'), 'gridminor': (False, _validate_bool, 'Toggle minor gridlines on and off.'), 'gridminor.alpha': (GRIDALPHA, _validate_float, 'Minor gridline opacity.'), 'gridminor.color': (BLACK, _validate_color, 'Minor gridline color.'), 'gridminor.linestyle': (GRIDSTYLE, _validate_linestyle, 'Minor gridline style.'), 'gridminor.linewidth': (GRIDRATIO * LINEWIDTH, _validate_pt, 'Minor gridline width.'), 'gridminor.style': (GRIDSTYLE, _validate_linestyle, 'Minor gridline style. Alias for :rcraw:`gridminor.linestyle`.'), 'gridminor.width': (GRIDRATIO * LINEWIDTH, _validate_pt, 'Minor gridline width. Alias for :rcraw:`gridminor.linewidth`.'), 'inlineformat': ('retina', _validate_belongs('svg', 'pdf', 'retina', 'png', 'jpeg'), "The inline backend figure format. Valid formats include ``'svg'``, ``'pdf'``, ``'retina'``, ``'png'``, and ``jpeg``."), 'innerborders': (False, _validate_bool, 'Toggles internal political border lines (e.g. states and provinces) on and off.'), 'innerborders.alpha': (None, _validate_or_none(_validate_float), 'Opacity for internal political border lines'), 'innerborders.color': (BLACK, _validate_color, 'Line color for internal political border lines.'), 'innerborders.linewidth': (LINEWIDTH, _validate_pt, 'Line width for internal political border lines.'), 'innerborders.zorder': (ZLINES, _validate_float, 'Z-order for internal political border lines.'), 'kde.points': (200, _validate_int, 'Number of evenly spaced coordinates used to evaluate kernel density estimates. Larger values give smoother curves at the cost of speed.'), 'label.color': (BLACK, _validate_color, 'Alias for :rcraw:`axes.labelcolor`.'), 'label.pad': (LABELPAD, _validate_pt, 'Alias for :rcraw:`axes.labelpad`.' + _addendum_pt), 'label.size': (SMALLSIZE, _validate_fontsize, 'Alias for :rcraw:`axes.labelsize`.' + _addendum_font), 'label.weight': ('normal', _validate_fontweight, 'Alias for :rcraw:`axes.labelweight`.'), 'lakes': (False, _validate_bool, 'Toggles lake patches on and off.'), 'lakes.alpha': (None, _validate_or_none(_validate_float), 'Opacity for lake patches'), 'lakes.color': (WHITE, _validate_color, 'Face color for lake patches.'), 'lakes.zorder': (ZPATCHES, _validate_float, 'Z-order for lake patches.'), 'lakes.rasterized': (False, _validate_bool, 'Toggles rasterization on or off for lake feature'), 'land': (False, _validate_bool, 'Toggles land patches on and off.'), 'land.alpha': (None, _validate_or_none(_validate_float), 'Opacity for land patches'), 'land.color': (BLACK, _validate_color, 'Face color for land patches.'), 'land.zorder': (ZPATCHES, _validate_float, 'Z-order for land patches.'), 'land.rasterized': (False, _validate_bool, 'Toggles the rasterization of the land feature.'), 'leftlabel.color': (BLACK, _validate_color, 'Font color for row labels on the left-hand side.'), 'leftlabel.pad': (TITLEPAD, _validate_pt, 'Padding between axes content and row labels on the left-hand side.' + _addendum_pt), 'leftlabel.sharedpad': (2 * TITLEPAD, _validate_pt, 'Padding between row labels and a shared y label on the left-hand side.' + _addendum_pt), 'leftlabel.rotation': ('vertical', _validate_rotation, 'Rotation for row labels on the left-hand side.' + _addendum_rotation), 'leftlabel.size': (LARGESIZE, _validate_fontsize, 'Font size for row labels on the left-hand side.' + _addendum_font), 'lollipop.markersize': (36, _validate_float, 'Size of lollipops in the lollipop plot.'), 'lollipop.stemcolor': (BLACK, _validate_color, 'Color of lollipop lines.'), 'lollipop.stemwidth': (LINEWIDTH, _validate_pt, 'Width of the stem'), 'lollipop.stemlinestyle': ('-', _validate_linestyle, 'Line style of lollipop lines.'), 'leftlabel.weight': ('bold', _validate_fontweight, 'Font weight for row labels on the left-hand side.'), 'margin': (MARGIN, _validate_float, 'The fractional *x* and *y* axis data margins when limits are unset. Alias for :rcraw:`axes.margin`.'), 'meta.edgecolor': (BLACK, _validate_color, 'Color of axis spines, tick marks, tick labels, and labels.'), 'meta.color': (BLACK, _validate_color, 'Color of axis spines, tick marks, tick labels, and labels. Alias for :rcraw:`meta.edgecolor`.'), 'meta.linewidth': (LINEWIDTH, _validate_pt, 'Thickness of axis spines and major tick lines.'), 'meta.width': (LINEWIDTH, _validate_pt, 'Thickness of axis spines and major tick lines. Alias for :rcraw:`meta.linewidth`.'), 'negcolor': ('blue7', _validate_color, 'Color for negative bars and shaded areas when using ``negpos=True``. See also :rcraw:`poscolor`.'), 'poscolor': ('red7', _validate_color, 'Color for positive bars and shaded areas when using ``negpos=True``. See also :rcraw:`negcolor`.'), 'ocean': (False, _validate_bool, 'Toggles ocean patches on and off.'), 'ocean.alpha': (None, _validate_or_none(_validate_float), 'Opacity for ocean patches'), 'ocean.color': (WHITE, _validate_color, 'Face color for ocean patches.'), 'ocean.zorder': (ZPATCHES, _validate_float, 'Z-order for ocean patches.'), 'ocean.rasterized': (False, _validate_bool, 'Turns rasterization on or off for the oceans feature for GeoAxes.'), 'reso': ('lo', _validate_belongs('lo', 'med', 'hi', 'x-hi', 'xx-hi'), "Resolution for `~ultraplot.axes.GeoAxes` geographic features. Must be one of ``'lo'``, ``'med'``, ``'hi'``, ``'x-hi'``, or ``'xx-hi'``."), 'rightlabel.color': (BLACK, _validate_color, 'Font color for row labels on the right-hand side.'), 'rightlabel.pad': (TITLEPAD, _validate_pt, 'Padding between axes content and row labels on the right-hand side.' + _addendum_pt), 'rightlabel.sharedpad': (2 * TITLEPAD, _validate_pt, 'Padding between row labels and a shared y label on the right-hand side.' + _addendum_pt), 'rightlabel.rotation': ('vertical', _validate_rotation, 'Rotation for row labels on the right-hand side.' + _addendum_rotation), 'rightlabel.size': (LARGESIZE, _validate_fontsize, 'Font size for row labels on the right-hand side.' + _addendum_font), 'rightlabel.weight': ('bold', _validate_fontweight, 'Font weight for row labels on the right-hand side.'), 'rivers': (False, _validate_bool, 'Toggles river lines on and off.'), 'rivers.alpha': (None, _validate_or_none(_validate_float), 'Opacity for river lines.'), 'rivers.color': (BLACK, _validate_color, 'Line color for river lines.'), 'rivers.linewidth': (LINEWIDTH, _validate_pt, 'Line width for river lines.'), 'rivers.zorder': (ZLINES, _validate_float, 'Z-order for river lines.'), 'rivers.rasterized': (False, _validate_bool, 'Toggles rasterization on or off for rivers feature for GeoAxes.'), 'chord.start': (0.0, _validate_float, 'Start angle for chord diagrams.'), 'chord.end': (360.0, _validate_float, 'End angle for chord diagrams.'), 'chord.space': (0.0, _validate_float_or_iterable, 'Inter-sector spacing for chord diagrams.'), 'chord.endspace': (True, _validate_bool, 'Whether to add an ending space gap for chord diagrams.'), 'chord.r_lim': ((97.0, 100.0), _validate_tuple_float_2, 'Radial limits for chord diagrams.'), 'chord.ticks_interval': (None, _validate_or_none(_validate_int), 'Tick interval for chord diagrams.'), 'chord.order': (None, _validate_or_none(_validate_string_or_iterable), 'Ordering of sectors for chord diagrams.'), 'radar.r_lim': ((0.0, 100.0), _validate_tuple_float_2, 'Radial limits for radar charts.'), 'radar.vmin': (0.0, _validate_float, 'Minimum value for radar charts.'), 'radar.vmax': (100.0, _validate_float, 'Maximum value for radar charts.'), 'radar.fill': (True, _validate_bool, 'Whether to fill radar chart polygons.'), 'radar.marker_size': (0, _validate_int, 'Marker size for radar charts.'), 'radar.bg_color': ('#eeeeee80', _validate_or_none(_validate_color), 'Background color for radar charts.'), 'radar.circular': (False, _validate_bool, 'Whether to use circular radar charts.'), 'radar.show_grid_label': (True, _validate_bool, 'Whether to show grid labels on radar charts.'), 'radar.grid_interval_ratio': (0.2, _validate_or_none(_validate_float), 'Grid interval ratio for radar charts.'), 'phylogeny.start': (0.0, _validate_float, 'Start angle for phylogeny plots.'), 'phylogeny.end': (360.0, _validate_float, 'End angle for phylogeny plots.'), 'phylogeny.r_lim': ((50.0, 100.0), _validate_tuple_float_2, 'Radial limits for phylogeny plots.'), 'phylogeny.format': ('newick', _validate_string, 'Input format for phylogeny plots.'), 'phylogeny.outer': (True, _validate_bool, 'Whether to place phylogeny leaves on the outer edge.'), 'phylogeny.align_leaf_label': (True, _validate_bool, 'Whether to align phylogeny leaf labels.'), 'phylogeny.ignore_branch_length': (False, _validate_bool, 'Whether to ignore branch lengths in phylogeny plots.'), 'phylogeny.leaf_label_size': (None, _validate_or_none(_validate_float), 'Leaf label font size for phylogeny plots.'), 'phylogeny.leaf_label_rmargin': (2.0, _validate_float, 'Radial margin for phylogeny leaf labels.'), 'phylogeny.reverse': (False, _validate_bool, 'Whether to reverse phylogeny orientation.'), 'phylogeny.ladderize': (False, _validate_bool, 'Whether to ladderize phylogeny branches.'), 'sankey.align': ('center', _validate_belongs('center', 'left', 'right', 'justify'), 'Horizontal alignment of nodes.'), 'sankey.connect': ((0, 0), _validate_tuple_int_2, 'Connection path for Sankey diagram.'), 'sankey.flow_labels': (False, _validate_bool, 'Whether to draw flow labels.'), 'sankey.flow_label_pos': (0.5, _validate_float, 'Position of flow labels along the flow.'), 'sankey.flow_sort': (True, _validate_bool, 'Whether to sort flows.'), 'sankey.node_labels': (True, _validate_bool, 'Whether to draw node labels.'), 'sankey.node_label_offset': (0.01, _validate_float, 'Offset for node labels.'), 'sankey.node_label_outside': ('auto', _validate_bool_or_string, 'Position of node labels relative to the node.'), 'sankey.other_label': ('Other', _validate_string, "Label for 'other' category in Sankey diagram."), 'sankey.pathlabel': ('', _validate_string, 'Label for the patch.'), 'sankey.pathlengths': (0.25, _validate_float, 'Path lengths for Sankey diagram.'), 'sankey.rotation': (0.0, _validate_float, 'Rotation of the Sankey diagram.'), 'sankey.trunklength': (1.0, _validate_float, 'Trunk length for Sankey diagram.'), 'subplots.align': (False, _validate_bool, 'Whether to align axis labels during draw. See `aligning labels `__.'), 'subplots.equalspace': (False, _validate_bool, 'Whether to make the tight layout algorithm assign the same space for every row and the same space for every column.'), 'subplots.groupspace': (True, _validate_bool, 'Whether to make the tight layout algorithm consider space between only adjacent subplot "groups" rather than every subplot in the row or column.'), 'subplots.innerpad': (1, _validate_em, 'Padding between adjacent subplots.' + _addendum_em), 'subplots.outerpad': (0.5, _validate_em, 'Padding around figure edge.' + _addendum_em), 'subplots.panelpad': (0.5, _validate_em, 'Padding between subplots and panels, and between stacked panels.' + _addendum_em), 'subplots.panelwidth': (0.5, _validate_in, 'Width of side panels.' + _addendum_in), 'subplots.refwidth': (2.5, _validate_in, 'Default width of the reference subplot.' + _addendum_in), 'subplots.share': ('auto', _validate_belongs(0, 1, 2, 3, 4, False, 'labels', 'limits', True, 'all', 'auto'), "The axis sharing level, one of ``0``, ``1``, ``2``, or ``3``, or the more intuitive aliases ``False``, ``'labels'``, ``'limits'``, ``True``, or ``'auto'``. See `~ultraplot.figure.Figure` for details."), 'subplots.span': (True, _validate_bool, 'Toggles spanning axis labels. See `~ultraplot.ui.subplots` for details.'), 'subplots.tight': (True, _validate_bool, 'Whether to auto-adjust the subplot spaces and figure margins.'), 'subplots.pixelsnap': (False, _validate_bool, 'Whether to snap subplot bounds to the renderer pixel grid during draw.'), 'suptitle.color': (BLACK, _validate_color, 'Figure title color.'), 'suptitle.pad': (TITLEPAD, _validate_pt, 'Padding between axes content and the figure super title.' + _addendum_pt), 'suptitle.size': (LARGESIZE, _validate_fontsize, 'Figure title font size.' + _addendum_font), 'suptitle.weight': ('bold', _validate_fontweight, 'Figure title font weight.'), 'tick.color': (BLACK, _validate_color, 'Major and minor tick color.'), 'tick.dir': (TICKDIR, _validate_belongs('in', 'out', 'inout'), "Major and minor tick direction. Must be one of ``'out'``, ``'in'``, or ``'inout'``."), 'tick.labelcolor': (BLACK, _validate_color, 'Axis tick label color.'), 'tick.labelpad': (TICKPAD, _validate_pt, 'Padding between ticks and tick labels.' + _addendum_pt), 'tick.labelsize': (SMALLSIZE, _validate_fontsize, 'Axis tick label font size.' + _addendum_font), 'tick.labelweight': ('normal', _validate_fontweight, 'Axis tick label font weight.'), 'tick.len': (TICKLEN, _validate_pt, 'Length of major ticks in points.'), 'tick.lenratio': (TICKLENRATIO, _validate_float, 'Ratio of minor tickline length to major tickline length.'), 'tick.linewidth': (LINEWIDTH, _validate_pt, 'Major tickline width.'), 'tick.minor': (TICKMINOR, _validate_bool, 'Toggles minor ticks on and off.'), 'tick.pad': (TICKPAD, _validate_pt, 'Alias for :rcraw:`tick.labelpad`.'), 'tick.width': (LINEWIDTH, _validate_pt, 'Major tickline width. Alias for :rcraw:`tick.linewidth`.'), 'tick.widthratio': (TICKWIDTHRATIO, _validate_float, 'Ratio of minor tickline width to major tickline width.'), 'title.above': (True, _validate_belongs(False, True, 'panels'), "Whether to move outer titles and a-b-c labels above panels, colorbars, or legends that are above the axes. If the string 'panels' then text is only redirected above axes panels. Otherwise should be boolean."), 'title.border': (True, _validate_bool, 'Whether to draw a white border around titles when :rcraw:`title.loc` is inside the axes.'), 'title.borderwidth': (1.5, _validate_pt, 'Width of the border around titles.'), 'title.bbox': (False, _validate_bool, 'Whether to draw semi-transparent bounding boxes around titles when :rcraw:`title.loc` is inside the axes.'), 'title.bboxcolor': (WHITE, _validate_color, 'Axes title bounding box color.'), 'title.bboxstyle': ('square', _validate_boxstyle, 'Axes title bounding box style.'), 'title.bboxalpha': (0.5, _validate_float, 'Axes title bounding box opacity.'), 'title.bboxpad': (None, _validate_or_none(_validate_pt), 'Padding for the title bounding box. By default this is scaled to make the box flush against the axes edge.' + _addendum_pt), 'title.color': (BLACK, _validate_color, 'Axes title color. Alias for :rcraw:`axes.titlecolor`.'), 'title.loc': ('center', _validate_belongs(*TEXT_LOCS), 'Title position. For options see the :ref:`location table `.'), 'title.pad': (TITLEPAD, _validate_pt, 'Padding between the axes edge and the inner and outer titles and a-b-c labels. Alias for :rcraw:`axes.titlepad`.' + _addendum_pt), 'title.size': (LARGESIZE, _validate_fontsize, 'Axes title font size. Alias for :rcraw:`axes.titlesize`.' + _addendum_font), 'title.weight': ('normal', _validate_fontweight, 'Axes title font weight. Alias for :rcraw:`axes.titleweight`.'), 'toplabel.color': (BLACK, _validate_color, 'Font color for column labels on the top of the figure.'), 'toplabel.pad': (TITLEPAD, _validate_pt, 'Padding between axes content and column labels on the top of the figure.' + _addendum_pt), 'toplabel.sharedpad': (2 * TITLEPAD, _validate_pt, 'Padding between column labels and a shared x label on the top of the figure.' + _addendum_pt), 'toplabel.rotation': ('horizontal', _validate_rotation, 'Rotation for column labels at the top of the figure.' + _addendum_rotation), 'toplabel.size': (LARGESIZE, _validate_fontsize, 'Font size for column labels on the top of the figure.' + _addendum_font), 'toplabel.weight': ('bold', _validate_fontweight, 'Font weight for column labels on the top of the figure.'), 'unitformat': ('L', _validate_string, 'The format string used to format `pint.Quantity` default unit labels using ``format(units, unitformat)``. See also :rcraw:`autoformat`.'), 'ultraplot.check_for_latest_version': (False, _validate_bool, 'Whether to check for the latest version of UltraPlot on PyPI when importing'), 'ultraplot.eager_import': (False, _validate_bool, 'Whether to import the full public API during setup instead of lazily.')} +_rc_children = {'font.smallsize': ('tick.labelsize', 'xtick.labelsize', 'ytick.labelsize', 'axes.labelsize', 'legend.fontsize', 'grid.labelsize'), 'font.largesize': ('abc.size', 'figure.titlesize', 'suptitle.size', 'axes.titlesize', 'title.size', 'leftlabel.size', 'toplabel.size', 'rightlabel.size', 'bottomlabel.size'), 'meta.color': ('axes.edgecolor', 'axes.labelcolor', 'legend.edgecolor', 'colorbar.edgecolor', 'tick.labelcolor', 'hatch.color', 'xtick.color', 'ytick.color'), 'meta.width': ('axes.linewidth', 'tick.width', 'tick.linewidth', 'xtick.major.width', 'ytick.major.width', 'grid.width', 'grid.linewidth'), 'axes.margin': ('axes.xmargin', 'axes.ymargin'), 'grid.color': ('gridminor.color', 'grid.labelcolor'), 'grid.alpha': ('gridminor.alpha',), 'grid.linewidth': ('gridminor.linewidth',), 'grid.linestyle': ('gridminor.linestyle',), 'tick.color': ('xtick.color', 'ytick.color'), 'tick.dir': ('xtick.direction', 'ytick.direction'), 'tick.len': ('xtick.major.size', 'ytick.major.size'), 'tick.minor': ('xtick.minor.visible', 'ytick.minor.visible'), 'tick.pad': ('xtick.major.pad', 'xtick.minor.pad', 'ytick.major.pad', 'ytick.minor.pad'), 'tick.width': ('xtick.major.width', 'ytick.major.width'), 'tick.labelsize': ('xtick.labelsize', 'ytick.labelsize')} +_rc_synonyms = (('cmap', 'image.cmap', 'cmap.sequential'), ('cmap.lut', 'image.lut'), ('font.name', 'font.family'), ('font.small', 'font.smallsize'), ('font.large', 'font.largesize'), ('formatter.limits', 'axes.formatter.limits'), ('formatter.use_locale', 'axes.formatter.use_locale'), ('formatter.use_mathtext', 'axes.formatter.use_mathtext'), ('formatter.min_exponent', 'axes.formatter.min_exponent'), ('formatter.use_offset', 'axes.formatter.useoffset'), ('formatter.offset_threshold', 'axes.formatter.offset_threshold'), ('grid.below', 'axes.axisbelow'), ('grid.labelpad', 'grid.pad'), ('grid.linewidth', 'grid.width'), ('grid.linestyle', 'grid.style'), ('gridminor.linewidth', 'gridminor.width'), ('gridminor.linestyle', 'gridminor.style'), ('label.color', 'axes.labelcolor'), ('label.pad', 'axes.labelpad'), ('label.size', 'axes.labelsize'), ('label.weight', 'axes.labelweight'), ('margin', 'axes.margin'), ('meta.width', 'meta.linewidth'), ('meta.color', 'meta.edgecolor'), ('tick.labelpad', 'tick.pad'), ('tick.labelsize', 'grid.labelsize'), ('tick.labelcolor', 'grid.labelcolor'), ('tick.labelweight', 'grid.labelweight'), ('tick.linewidth', 'tick.width'), ('title.pad', 'axes.titlepad'), ('title.size', 'axes.titlesize'), ('title.weight', 'axes.titleweight')) +_rc_removed = {'rgbcycle': ('', '0.6.0'), 'geogrid.latmax': ('Please use ax.format(latmax=N) instead.', '0.6.0'), 'geogrid.latstep': ('Please use ax.format(latlines=N) instead.', '0.6.0'), 'geogrid.lonstep': ('Please use ax.format(lonlines=N) instead.', '0.6.0'), 'gridminor.latstep': ('Please use ax.format(latminorlines=N) instead.', '0.6.0'), 'gridminor.lonstep': ('Please use ax.format(lonminorlines=N) instead.', '0.6.0')} +_rc_renamed = {'abc.format': ('abc', '0.5.0'), 'align': ('subplots.align', '0.6.0'), 'axes.facealpha': ('axes.alpha', '0.6.0'), 'geoaxes.edgecolor': ('axes.edgecolor', '0.6.0'), 'geoaxes.facealpha': ('axes.alpha', '0.6.0'), 'geoaxes.facecolor': ('axes.facecolor', '0.6.0'), 'geoaxes.linewidth': ('axes.linewidth', '0.6.0'), 'geogrid.alpha': ('grid.alpha', '0.6.0'), 'geogrid.color': ('grid.color', '0.6.0'), 'geogrid.labels': ('grid.labels', '0.6.0'), 'geogrid.labelpad': ('grid.pad', '0.6.0'), 'geogrid.labelsize': ('grid.labelsize', '0.6.0'), 'geogrid.linestyle': ('grid.linestyle', '0.6.0'), 'geogrid.linewidth': ('grid.linewidth', '0.6.0'), 'share': ('subplots.share', '0.6.0'), 'small': ('font.smallsize', '0.6.0'), 'large': ('font.largesize', '0.6.0'), 'span': ('subplots.span', '0.6.0'), 'tight': ('subplots.tight', '0.6.0'), 'axes.formatter.timerotation': ('formatter.timerotation', '0.6.0'), 'axes.formatter.zerotrim': ('formatter.zerotrim', '0.6.0'), 'abovetop': ('title.above', '0.7.0'), 'subplots.pad': ('subplots.outerpad', '0.7.0'), 'subplots.axpad': ('subplots.innerpad', '0.7.0'), 'subplots.axwidth': ('subplots.refwidth', '0.7.0'), 'text.labelsize': ('font.smallsize', '0.8.0'), 'text.titlesize': ('font.largesize', '0.8.0'), 'alpha': ('axes.alpha', '0.8.0'), 'facecolor': ('axes.facecolor', '0.8.0'), 'edgecolor': ('meta.color', '0.8.0'), 'color': ('meta.color', '0.8.0'), 'linewidth': ('meta.width', '0.8.0'), 'lut': ('cmap.lut', '0.8.0'), 'image.levels': ('cmap.levels', '0.8.0'), 'image.inbounds': ('cmap.inbounds', '0.8.0'), 'image.discrete': ('cmap.discrete', '0.8.0'), 'image.edgefix': ('edgefix', '0.8.0'), 'tick.ratio': ('tick.widthratio', '0.8.0'), 'grid.ratio': ('grid.widthratio', '0.8.0'), 'abc.style': ('abc', '0.8.0'), 'grid.loninline': ('grid.inlinelabels', '0.8.0'), 'grid.latinline': ('grid.inlinelabels', '0.8.0'), 'cmap.edgefix': ('edgefix', '0.9.0'), 'basemap': ('geo.backend', '0.10.0'), 'inlinefmt': ('inlineformat', '0.10.0'), 'cartopy.circular': ('geo.round', '0.10.0'), 'cartopy.autoextent': ('geo.extent', '0.10.0'), 'colorbar.rasterize': ('colorbar.rasterized', '0.10.0')} +_rc_ultraplot_default = ... +_rc_ultraplot_validate = ... +_rc_ultraplot_default = _RcParams(_rc_ultraplot_default, _rc_ultraplot_validate) +_rc_matplotlib_default = RcParams(_rc_matplotlib_default) +_rc_categories = ... +_rc_nodots = ... diff --git a/ultraplot/internals/versions.pyi b/ultraplot/internals/versions.pyi new file mode 100644 index 000000000..b3afe0c82 --- /dev/null +++ b/ultraplot/internals/versions.pyi @@ -0,0 +1,49 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Utilities for handling dependencies and version changes. +""" +from _typeshed import Incomplete +from . import ic +from . import warnings + +class _version(list): + """ + Casual parser for ``major.minor`` style version strings. We do not want to + add a 'packaging' dependency and only care about major and minor tags. + """ + + def __str__(self) -> str: + ... + + def __repr__(self) -> str: + ... + + def __init__(self, version: Incomplete) -> None: + ... + + def __eq__(self, other: Incomplete) -> bool: + ... + + def __ne__(self, other: Incomplete) -> bool: + ... + + def __gt__(self, other: Incomplete) -> bool: + ... + + def __lt__(self, other: Incomplete) -> bool: + ... + + def __ge__(self, other: Incomplete) -> bool: + ... + + def __le__(self, other: Incomplete) -> bool: + ... +import matplotlib +_version_mpl = _version(matplotlib.__version__) +try: + import cartopy +except ImportError: + _version_cartopy = _version('0.0.0') +else: + _version_cartopy = _version(cartopy.__version__) diff --git a/ultraplot/internals/warnings.pyi b/ultraplot/internals/warnings.pyi new file mode 100644 index 000000000..973f6102d --- /dev/null +++ b/ultraplot/internals/warnings.pyi @@ -0,0 +1,38 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Utilities for internal warnings and deprecations. +""" +from _typeshed import Incomplete +import functools +import re +import sys +import warnings +from typing import Any, Callable, TypeVar, cast +from . import ic +_F = TypeVar('_F', bound=Callable[..., Any]) +REGEX_INTERNAL = re.compile('\\A(matplotlib|mpl_toolkits|ultraplot)\\.') +UltraPlotWarning = type('UltraPlotWarning', (UserWarning,), {}) +catch_warnings = warnings.catch_warnings +simplefilter = warnings.simplefilter + +def next_release() -> str: + """message indicating the next major release.""" + ... + +def _warn_ultraplot(message: Incomplete) -> None: + """Emit a `UltraPlotWarning` and show the stack level outside of matplotlib and +ultraplot. This is adapted from matplotlib's warning system.""" + ... + +def _rename_objs(version: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Emit a basic deprecation warning after renaming function(s), method(s), or +class(es). Each key should be an old name, and each argument should be the new +object to point to. Do not document the deprecated object(s) to discourage use.""" + ... + +def _rename_kwargs(version: Incomplete, **kwargs_rename: Incomplete) -> Callable[[_F], _F]: + """Emit a basic deprecation warning after removing or renaming keyword argument(s). +Each key should be an old keyword, and each argument should be the new keyword +or *instructions* for what to use instead.""" + ... diff --git a/ultraplot/legend.pyi b/ultraplot/legend.pyi new file mode 100644 index 000000000..830cd505a --- /dev/null +++ b/ultraplot/legend.pyi @@ -0,0 +1,479 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +from _typeshed import Incomplete +from collections.abc import Mapping +from dataclasses import dataclass +from functools import lru_cache +from typing import Any, Iterable, Optional, Tuple, Union +import matplotlib.patches as mpatches +import matplotlib.path as mpath +import matplotlib.text as mtext +import numpy as np +from matplotlib import cm as mcm +from matplotlib import colors as mcolors +from matplotlib.colors import is_color_like as _mpl_is_color_like +from matplotlib import lines as mlines +from matplotlib import legend as mlegend +from matplotlib import legend_handler as mhandler +from matplotlib.markers import MarkerStyle +from .config import rc +from .internals import _not_none, _pop_props, docstring, guides, inputs, rcsetup +from .utils import _fontsize_to_pt, units +try: + from typing import override +except ImportError: + from typing_extensions import override +try: + import cartopy.crs as ccrs + from cartopy.io import shapereader as cshapereader + from cartopy.mpl.feature_artist import FeatureArtist as _CartopyFeatureArtist + from cartopy.mpl.path import shapely_to_path as _cartopy_shapely_to_path +except Exception: + ccrs = None + cshapereader = None + _CartopyFeatureArtist = None + _cartopy_shapely_to_path = None +try: + from shapely.geometry.base import BaseGeometry as _ShapelyBaseGeometry + from shapely.ops import unary_union as _shapely_unary_union +except Exception: + _ShapelyBaseGeometry = None + _shapely_unary_union = None +__all__ = ['Legend', 'LegendEntry', 'GeometryEntry'] + +def _wedge_legend_patch(legend: Incomplete, orig_handle: Incomplete, xdescent: Incomplete, ydescent: Incomplete, width: Incomplete, height: Incomplete, fontsize: Incomplete) -> Incomplete: + """Draw wedge-shaped legend keys for pie wedge handles.""" + ... + +class LegendEntry(mlines.Line2D): + """ + Convenience artist for custom legend entries. + + This is a lightweight wrapper around `matplotlib.lines.Line2D` that + initializes with empty data so it can be passed directly to + `Axes.legend()` or `Figure.legend()` handles. + """ + + def __init__(self, label: Incomplete=None, *, color: Incomplete=None, line: Incomplete=True, marker: Incomplete=None, linestyle: Incomplete='-', linewidth: Incomplete=2, markersize: Incomplete=6, markerfacecolor: Incomplete=None, markeredgecolor: Incomplete=None, markeredgewidth: Incomplete=None, alpha: Incomplete=None, marker_capstyle: Incomplete=None, marker_joinstyle: Incomplete=None, marker_transform: Incomplete=None, **kwargs: Incomplete) -> None: + ... + + @classmethod + def line(cls, label: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Build a line-style legend entry.""" + ... + + @classmethod + def marker(cls, label: Incomplete=None, marker: Incomplete='o', **kwargs: Incomplete) -> Incomplete: + """Build a marker-style legend entry.""" + ... + +class _Line2DLegendHandler(mhandler.HandlerLine2D): + """ + Match single-point marker plots by hiding the legend connector line. + """ + + def create_artists(self, legend: Incomplete, orig_handle: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + ... +_GEOMETRY_SHAPE_PATHS = {'circle': mpath.Path.unit_circle(), 'square': mpath.Path.unit_rectangle(), 'triangle': mpath.Path.unit_regular_polygon(3), 'diamond': mpath.Path.unit_regular_polygon(4), 'pentagon': mpath.Path.unit_regular_polygon(5), 'hexagon': mpath.Path.unit_regular_polygon(6), 'star': mpath.Path.unit_regular_star(5), 'rectangle': mpath.Path([[0, 0], [2, 0], [2, 1], [0, 1], [0, 0]], closed=True, readonly=True), 'line': mpath.Path([[0, 0], [1, 0]], readonly=True)} +_GEOMETRY_SHAPE_ALIASES = {'box': 'square', 'rect': 'rectangle', 'rec': 'rectangle', 'tri': 'triangle', 'pent': 'pentagon', 'hex': 'hexagon'} +_DEFAULT_GEO_JOINSTYLE = 'bevel' + +def _normalize_shape_name(value: str) -> str: + """Normalize geometry shape shorthand names.""" + ... + +def _normalize_country_resolution(resolution: str) -> str: + """Normalize Natural Earth shorthand resolution.""" + ... + +def _country_geometry_for_legend(geometry: Any, *, include_far: bool=False) -> Any: + """Reduce multi-part country geometry for readability while preserving local islands. + +This avoids tiny legend glyphs for countries with distant overseas territories +(e.g., Netherlands in Natural Earth datasets), but tries to keep nearby islands.""" + ... + +def _resolve_country_projection(country_proj: Any) -> Any: + """Resolve shorthand strings to cartopy projections for country legend geometries.""" + ... + +def _project_geometry_for_legend(geometry: Any, country_proj: Any) -> Any: + """Project geometry for legend rendering when requested.""" + ... + +def _resolve_country_geometry(code: str, resolution: str='110m', include_far: bool=False) -> Incomplete: + """Resolve a country shorthand code (e.g., ``AU`` or ``AUS``) to a geometry.""" + ... + +def _geometry_to_path(geometry: Any, *, country_reso: str='110m', country_territories: bool=False, country_proj: Any=None) -> mpath.Path: + """Convert geometry/path shorthand input to a matplotlib path.""" + ... + +def _fit_path_to_handlebox(path: mpath.Path, *, xdescent: float, ydescent: float, width: float, height: float, pad: float=0.08, preserve_aspect: bool=True) -> mpath.Path: + """Normalize an arbitrary path into the legend-handle box.""" + ... + +def _feature_geometry_path(handle: Any) -> Optional[mpath.Path]: + """Extract the first geometry path from a cartopy feature artist.""" + ... + +def _first_scalar(value: Any, default: Any=None) -> Any: + """Return first scalar from lists/arrays used by collection-style artists.""" + ... + +def _patch_joinstyle(value: Any, default: str=_DEFAULT_GEO_JOINSTYLE) -> str: + """Resolve patch joinstyle from artist methods/kwargs with a sensible default.""" + ... + +def _patch_color(orig_handle: Any, prop: str, default: Any=None) -> Any: + """Resolve a patch color, preferring the artist's original color spec. + +Collection-like artists often report post-alpha RGBA arrays from +`get_facecolor()` / `get_edgecolor()`. If we then also copy `alpha`, the +legend proxy ends up visually double-dimmed. Prefer the original color +attributes when available so patch proxies can apply alpha once.""" + ... +_PATCH_STYLE_PROP_SPECS = {'facecolor': {'default': 'none', 'transform': None}, 'edgecolor': {'default': 'none', 'transform': None}, 'linewidth': {'default': 0.0, 'transform': _first_scalar}, 'linestyle': {'default': None, 'transform': _first_scalar}, 'hatch': {'default': None, 'transform': None}, 'hatch_linewidth': {'default': None, 'transform': None}, 'fill': {'default': None, 'transform': None}, 'alpha': {'default': None, 'transform': None}, 'capstyle': {'default': None, 'transform': None}} + +def _copy_patch_style(legend_handle: mpatches.Patch, orig_handle: Any, *, joinstyle_default: str=_DEFAULT_GEO_JOINSTYLE) -> None: + """Copy common patch-style properties from source artist to legend proxy. + +Matplotlib does not provide a reliable generic style-transfer API for +cross-family artists here. In particular, `Artist.update_from()` is not +safe for `Collection -> Patch` copies like `FeatureArtist -> PathPatch`, +and `properties()` still leaves us to normalize collection-valued fields. +So this helper intentionally copies the shared patch-style surface only.""" + ... + +def _feature_legend_patch(legend: Incomplete, orig_handle: Incomplete, xdescent: Incomplete, ydescent: Incomplete, width: Incomplete, height: Incomplete, fontsize: Incomplete) -> Incomplete: + """Draw a normalized geometry path for cartopy feature artists.""" + ... + +def _shapely_geometry_patch(legend: Incomplete, orig_handle: Incomplete, xdescent: Incomplete, ydescent: Incomplete, width: Incomplete, height: Incomplete, fontsize: Incomplete) -> Incomplete: + """Draw shapely geometry handles in legend boxes.""" + ... + +def _geometry_entry_patch(legend: Incomplete, orig_handle: Incomplete, xdescent: Incomplete, ydescent: Incomplete, width: Incomplete, height: Incomplete, fontsize: Incomplete) -> Incomplete: + """Draw a geometry entry path inside the legend-handle box.""" + ... + +class _FeatureArtistLegendHandler(mhandler.HandlerPatch): + """ + Legend handler for cartopy FeatureArtist instances. + """ + + def __init__(self) -> None: + ... + + def update_prop(self, legend_handle: Incomplete, orig_handle: Incomplete, legend: Incomplete) -> Incomplete: + ... + +class _ShapelyGeometryLegendHandler(mhandler.HandlerPatch): + """ + Legend handler for raw shapely geometries. + """ + + def __init__(self) -> None: + ... + + def update_prop(self, legend_handle: Incomplete, orig_handle: Incomplete, legend: Incomplete) -> Incomplete: + ... + +class _GeometryEntryLegendHandler(mhandler.HandlerPatch): + """ + Legend handler for `GeometryEntry` custom handles. + """ + + def __init__(self) -> None: + ... + + def update_prop(self, legend_handle: Incomplete, orig_handle: Incomplete, legend: Incomplete) -> Incomplete: + ... + +class GeometryEntry(mpatches.PathPatch): + """ + Convenience geometry legend entry. + + Parameters + ---------- + geometry + Geometry shorthand (e.g. ``'triangle'`` or ``'country:AU'``), + shapely geometry, or `matplotlib.path.Path`. + """ + + def __init__(self, geometry: Any='square', *, country_reso: str='110m', country_territories: bool=False, country_proj: Any=None, label: Optional[str]=None, facecolor: Any='none', edgecolor: Any='0.25', linewidth: float=1.0, joinstyle: str=_DEFAULT_GEO_JOINSTYLE, alpha: Optional[float]=None, fill: Optional[bool]=None, **kwargs: Any) -> None: + ... + +def _geometry_default_label(geometry: Any, index: int) -> str: + """Derive default labels for geo legend entries.""" + ... + +def _geo_legend_entries(entries: Iterable[Any] | dict[Any, Any], labels: Optional[Iterable[Any]]=None, *, country_reso: str='110m', country_territories: bool=False, country_proj: Any=None, patch_kw: dict=None) -> Incomplete: + """Build geometry semantic legend handles and labels. + +Notes +----- +`entries` may be: +- mapping of ``label -> geometry`` +- sequence of ``(label, geometry)`` or ``(label, geometry, options)`` tuples + where ``options`` is either a projection spec or a dict of per-entry + `GeometryEntry` keyword overrides (e.g., `country_proj`, `country_reso`) +- sequence of geometries with explicit `labels`""" + ... +_COLOR_KEYS = {'color', 'facecolor', 'edgecolor', 'markerfacecolor', 'markeredgecolor', 'markerfacecoloralt'} + +def _is_color_like(value: Incomplete) -> Incomplete: + """Determine whether a value can be interpreted as a single color. + +A tuple or list of 3 or 4 numbers in ``[0, 1]`` is treated as one RGB(A) +color rather than a per-entry style sequence — matching matplotlib's +color parser and giving tuple/list symmetric behavior. Other lists fall +through to per-entry resolution by ``_style_lookup``.""" + ... +_LINE_ALIAS_MAP = {'c': 'color', 'm': 'marker', 'ms': 'markersize', 'markersizes': 'markersize', 'ls': 'linestyle', 'lw': 'linewidth', 'mec': 'markeredgecolor', 'mew': 'markeredgewidth', 'mfc': 'markerfacecolor', 'mfcalt': 'markerfacecoloralt', 'aa': 'antialiased', 'fs': 'fillstyle'} +_PATCH_ALIAS_MAP = {'c': 'color', 'fc': 'facecolor', 'ec': 'edgecolor', 'ls': 'linestyle', 'lw': 'linewidth', 'aa': 'antialiased'} + +def _style_lookup(style: Incomplete, key: Incomplete, index: Incomplete, default: Incomplete=None, *, prop: Incomplete=None) -> Incomplete: + """Resolve a style value from scalar, mapping, or sequence inputs. + +Parameters +---------- +style : the style value (scalar, list, dict) +key : dict key when `style` is a mapping (typically a label) +index : list index when `style` is a sequence +default : fallback value +prop : optional attribute name; if it belongs to _COLOR_KEYS, + the function treats color-like sequences as single colors.""" + ... + +def _format_label(value: Incomplete, fmt: Incomplete) -> Incomplete: + """Format legend labels from values.""" + ... + +def _default_cycle_colors() -> Incomplete: + """Return default color cycle entries.""" + ... +_ENTRY_STYLE_FROM_COLLECTION = {'colors': 'color', 'edgecolors': 'markeredgecolor', 'facecolors': 'markerfacecolor', 'linestyles': 'linestyle', 'linewidths': 'markeredgewidth'} +_ENTRY_AREA_SIZE_KEYS = ('s', 'size', 'sizes') +_ENTRY_DIAMETER_SIZE_KEYS = ('markersize', 'ms', 'markersizes') +_ENTRY_MARKERSIZE_KEYS = (*_ENTRY_AREA_SIZE_KEYS, *_ENTRY_DIAMETER_SIZE_KEYS) + +def _pop_aliases(kwargs: dict[str, Any], alias_map: dict[str, str]) -> dict[str, Any]: + """Pop short aliases (``c``, ``ls``, …) from ``kwargs`` mapped to full names.""" + ... + +def _pop_plurals(kwargs: dict[str, Any], plural_map: dict[str, str]) -> dict[str, Any]: + """Pop collection-style plurals (``colors``, ``linewidths``, …).""" + ... + +def _area_to_markersize(value: Any) -> Any: + """Convert area-style marker sizes to Line2D marker diameters.""" + ... + +def _pop_marker_size(kwargs: dict[str, Any]) -> Any: + """Pop marker-size aliases and return Line2D marker diameters. + +Semantic legend helpers accept scatter-style ``s`` / ``size`` / ``sizes`` +inputs as marker areas, but render handles with ``Line2D`` where +``markersize`` / ``ms`` are diameters.""" + ... + +def _pop_line2d_setters(kwargs: dict[str, Any]) -> dict[str, Any]: + """Pop remaining kwargs that correspond to ``Line2D`` setters. + +Catches properties that ``_pop_props(..., "line")`` does not know about +(e.g. ``fillstyle``, ``solid_capstyle``) so they survive into the +``LegendEntry`` constructor instead of leaking through to ``Axes.legend``, +where matplotlib rejects them. + +``label``/``labels`` look like Line2D setters but are intentionally not +consumed here — the semantic-legend validator (covered by +``test_semantic_legend_rejects_label{,s}_kwarg``) needs them to surface +as ``TypeError`` from the public ``legend()`` call.""" + ... + +def _pop_entry_props(kwargs: dict[str, Any]) -> dict[str, Any]: + """Extract ``LegendEntry`` style properties from ``kwargs``. + +Resolution order (highest → lowest priority): + +1. Full-name properties recognised by ``_pop_props(kwargs, "line")``. +2. Collection-style plurals (``colors`` → ``color``, …). +3. Marker-size aliases. ``s`` / ``size`` / ``sizes`` are scatter-style + areas converted to diameters; ``markersize`` / ``ms`` are diameters. +4. Short aliases (``c`` → ``color``, ``ls`` → ``linestyle``, …). +5. Any other valid ``Line2D`` setter still in ``kwargs``. + +Advanced ``MarkerStyle`` properties (``marker_capstyle``/``_joinstyle``/ +``_transform``) are pulled out first so ``_pop_props`` does not consume +them, and merged back at the end with full priority.""" + ... +_NUM_STYLE_FROM_COLLECTION = {'colors': 'facecolor', 'facecolors': 'facecolor', 'edgecolors': 'edgecolor', 'linestyles': 'linestyle', 'linewidths': 'linewidth'} + +def _pop_num_props(kwargs: dict[str, Any]) -> dict[str, Any]: + """Extract patch-style properties (and collection-plural / short aliases) for +numeric semantic legend entries (``numlegend`` / ``geolegend``).""" + ... + +def _resolve_style_values(styles: dict[str, Any], label: Any, index: int) -> dict[str, Any]: + """Resolve scalar, mapping, or sequence style values for one legend entry.""" + ... + +def _cat_legend_entries(categories: Incomplete, *, color: Incomplete=None, marker: Incomplete='o', line: Incomplete=False, linestyle: Incomplete='-', linewidth: Incomplete=2.0, markersize: Incomplete=6.0, alpha: Incomplete=None, markeredgecolor: Incomplete=None, markeredgewidth: Incomplete=None, markerfacecolor: Incomplete=None, **entry_kwargs: Incomplete) -> Incomplete: + """Build categorical semantic legend handles and labels.""" + ... + +def _entry_legend_entries(entries: Iterable[Any] | Mapping[Any, Any], *, line: bool, marker: Incomplete, color: Incomplete, linestyle: Incomplete, linewidth: Incomplete, markersize: Incomplete, alpha: Incomplete, markeredgecolor: Incomplete, markeredgewidth: Incomplete, markerfacecolor: Incomplete, styles: dict[str, Any]) -> Incomplete: + """Build generic semantic legend handles/labels from mixed entry specifications.""" + ... + +def _size_legend_entries(levels: Iterable[float], *, label_values: Incomplete=None, labels: Incomplete=None, color: Incomplete='0.35', marker: Incomplete='o', area: Incomplete=True, scale: Incomplete=1.0, minsize: Incomplete=3.0, fmt: Incomplete=None, alpha: Incomplete=None, markeredgecolor: Incomplete=None, markeredgewidth: Incomplete=None, markerfacecolor: Incomplete=None, **entry_kwargs: Incomplete) -> Incomplete: + """Build size semantic legend handles and labels.""" + ... + +def _scale_size_legend_values(values: Incomplete, *, source: Incomplete=None, vmin: Incomplete=None, vmax: Incomplete=None, smin: Incomplete=None, smax: Incomplete=None, area_size: Incomplete=True, absolute_size: Incomplete=None) -> Incomplete: + """Transform semantic size values with the same rules used by scatter().""" + ... + +def _infer_size_legend_scale(axes: Incomplete, values: Incomplete) -> Incomplete: + """Infer scatter-style size scaling from the latest compatible scatter artist.""" + ... + +def _num_legend_entries(levels: Incomplete=None, *, vmin: Incomplete=None, vmax: Incomplete=None, n: int=5, cmap: Incomplete='viridis', norm: Incomplete=None, fmt: Incomplete=None, edgecolor: Incomplete='none', linewidth: Incomplete=0.0, linestyle: Incomplete=None, alpha: Incomplete=None, facecolor: Incomplete=None, **entry_kwargs: Incomplete) -> Incomplete: + """Build numeric-color semantic legend handles and labels.""" + ... +ALIGN_OPTS = {None: {'center': 'center', 'left': 'center left', 'right': 'center right', 'top': 'upper center', 'bottom': 'lower center'}, 'left': {'center': 'center right', 'left': 'center right', 'right': 'center right', 'top': 'upper right', 'bottom': 'lower right'}, 'right': {'center': 'center left', 'left': 'center left', 'right': 'center left', 'top': 'upper left', 'bottom': 'lower left'}, 'top': {'center': 'lower center', 'left': 'lower left', 'right': 'lower right', 'top': 'lower center', 'bottom': 'lower center'}, 'bottom': {'center': 'upper center', 'left': 'upper left', 'right': 'upper right', 'top': 'upper center', 'bottom': 'upper center'}} +LegendKw = dict[str, Any] +LegendHandles = Any +LegendLabels = Any + +@dataclass(frozen=True) +class _LegendInputs: + handles: LegendHandles + labels: LegendLabels + loc: Any + align: Any + width: Any + pad: Any + space: Any + frameon: bool + ncol: Any + order: str + label: Any + title: Any + fontsize: float + fontweight: Any + fontcolor: Any + titlefontsize: float + titlefontweight: Any + titlefontcolor: Any + handle_kw: Any + handler_map: Any + span: Optional[Union[int, Tuple[int, int]]] + row: Optional[int] + col: Optional[int] + rows: Optional[Union[int, Tuple[int, int]]] + cols: Optional[Union[int, Tuple[int, int]]] + kwargs: dict[str, Any] + +class Legend(mlegend.Legend): + + def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: + ... + + @classmethod + def get_default_handler_map(cls) -> Incomplete: + """Extend matplotlib defaults with a wedge handler for pie legends.""" + ... + + @override + def set_loc(self, loc: Incomplete=None) -> Incomplete: + ... + + def remove(self) -> None: + """Remove the legend and sync Ultraplot guide tracking state. + +Matplotlib's base ``Legend.remove`` leaves Ultraplot's internal +``_legend_dict`` and ``legend_`` pointers untouched. When callers +remove a legend (e.g., ``sns.move_legend``), stale entries can keep +showing old legends alongside newly added ones. Keep both systems in +sync before delegating to Matplotlib's removal logic.""" + ... + +def _normalize_em_kwargs(kwargs: dict[str, Any], *, fontsize: float) -> dict[str, Any]: + """Convert legend-related em unit kwargs to absolute values in points.""" + ... +_semantic_style_arg_docstring = ... +_semantic_style_kwargs_docstring = ... +_semantic_num_style_kwargs_docstring = ... +_semantic_handle_kw_docstring = ... + +class UltraLegend: + """ + Centralized legend builder for axes. + """ + + def __init__(self, axes: Incomplete) -> None: + ... + + @staticmethod + def _validate_semantic_kwargs(method: str, kwargs: dict[str, Any]) -> None: + """Prevent ambiguous legend kwargs for semantic legend helpers.""" + ... + + def entrylegend(self, entries: Iterable[Any] | Mapping[Any, Any], *, line: Optional[bool]=None, marker: Incomplete=None, color: Incomplete=None, handle_kw: Optional[dict[str, Any]]=None, add: bool=True, **kwargs: Any) -> Incomplete: + """Build generic semantic legend entries and optionally draw a legend. +Public docs live on :meth:`Axes.entrylegend`.""" + ... + + def catlegend(self, categories: Iterable[Any], *, color: Incomplete=None, marker: Incomplete=None, line: Optional[bool]=None, handle_kw: Optional[dict[str, Any]]=None, add: bool=True, **kwargs: Any) -> Incomplete: + """Build categorical legend entries and optionally draw a legend. +Public docs live on :meth:`Axes.catlegend`.""" + ... + + def sizelegend(self, levels: Iterable[float], *, labels: Incomplete=None, color: Incomplete=None, marker: Incomplete=None, area: Optional[bool]=None, values: Incomplete=None, vmin: Optional[float]=None, vmax: Optional[float]=None, smin: Optional[float]=None, smax: Optional[float]=None, area_size: Optional[bool]=None, absolute_size: Optional[bool]=None, scale: Optional[float]=None, minsize: Optional[float]=None, fmt: Incomplete=None, handle_kw: Optional[dict[str, Any]]=None, add: bool=True, **kwargs: Any) -> Incomplete: + """Build size legend entries and optionally draw a legend. +Public docs live on :meth:`Axes.sizelegend`.""" + ... + + def numlegend(self, levels: Incomplete=None, *, vmin: Incomplete=None, vmax: Incomplete=None, n: Optional[int]=None, cmap: Incomplete=None, norm: Incomplete=None, fmt: Incomplete=None, facecolor: Incomplete=None, edgecolor: Incomplete=None, linewidth: Optional[float]=None, linestyle: Incomplete=None, alpha: Incomplete=None, handle_kw: Optional[dict[str, Any]]=None, add: bool=True, **kwargs: Any) -> Incomplete: + """Build numeric-color legend entries and optionally draw a legend. +Public docs live on :meth:`Axes.numlegend`.""" + ... + + def geolegend(self, entries: Iterable[Any] | dict[Any, Any], labels: Optional[Iterable[Any]]=None, *, country_reso: Optional[str]=None, country_territories: Optional[bool]=None, country_proj: Any=None, handlesize: Optional[float]=None, facecolor: Any=None, edgecolor: Any=None, linewidth: Optional[float]=None, alpha: Optional[float]=None, fill: Optional[bool]=None, handle_kw: Optional[dict[str, Any]]=None, add: bool=True, **kwargs: Any) -> Incomplete: + """Build geometry legend entries and optionally draw a legend. +Public docs live on :meth:`Axes.geolegend`.""" + ... + + @staticmethod + def _align_map() -> dict[Optional[str], dict[str, str]]: + """Mapping between panel side + align and matplotlib legend loc strings.""" + ... + + def _resolve_inputs(self, handles: Incomplete=None, labels: Incomplete=None, *, loc: Incomplete=None, align: Incomplete=None, width: Incomplete=None, pad: Incomplete=None, space: Incomplete=None, frame: Incomplete=None, frameon: Incomplete=None, ncol: Incomplete=None, ncols: Incomplete=None, alphabetize: Incomplete=False, center: Incomplete=None, order: Incomplete=None, label: Incomplete=None, title: Incomplete=None, fontsize: Incomplete=None, fontweight: Incomplete=None, fontcolor: Incomplete=None, titlefontsize: Incomplete=None, titlefontweight: Incomplete=None, titlefontcolor: Incomplete=None, handle_kw: Incomplete=None, handler_map: Incomplete=None, span: Optional[Union[int, Tuple[int, int]]]=None, row: Optional[int]=None, col: Optional[int]=None, rows: Optional[Union[int, Tuple[int, int]]]=None, cols: Optional[Union[int, Tuple[int, int]]]=None, **kwargs: Any) -> Incomplete: + """Normalize inputs, apply rc defaults, and convert units.""" + ... + + def _resolve_axes_layout(self, inputs: _LegendInputs) -> Incomplete: + """Determine the legend axes and layout-related kwargs.""" + ... + + def _resolve_style_kwargs(self, *, lax: Incomplete, fontcolor: Incomplete, fontweight: Incomplete, handle_kw: Incomplete, kwargs: Incomplete) -> Incomplete: + """Parse frame settings and build per-element style kwargs.""" + ... + + def _build_legends(self, *, lax: Incomplete, inputs: _LegendInputs, center: Incomplete, alphabetize: Incomplete, kw_frame: Incomplete, kwargs: Incomplete) -> Incomplete: + ... + + def _apply_handle_styles(self, objs: Incomplete, *, kw_text: Incomplete, kw_handle: Incomplete) -> Incomplete: + """Apply per-handle styling overrides to legend artists.""" + ... + + def _finalize(self, objs: Incomplete, *, loc: Incomplete, align: Incomplete) -> Incomplete: + """Register legend for guide tracking and return the public object.""" + ... + + def add(self, handles: Incomplete=None, labels: Incomplete=None, *, loc: Incomplete=None, align: Incomplete=None, width: Incomplete=None, pad: Incomplete=None, space: Incomplete=None, frame: Incomplete=None, frameon: Incomplete=None, ncol: Incomplete=None, ncols: Incomplete=None, alphabetize: Incomplete=False, center: Incomplete=None, order: Incomplete=None, label: Incomplete=None, title: Incomplete=None, fontsize: Incomplete=None, fontweight: Incomplete=None, fontcolor: Incomplete=None, titlefontsize: Incomplete=None, titlefontweight: Incomplete=None, titlefontcolor: Incomplete=None, handle_kw: Incomplete=None, handler_map: Incomplete=None, span: Optional[Union[int, Tuple[int, int]]]=None, row: Optional[int]=None, col: Optional[int]=None, rows: Optional[Union[int, Tuple[int, int]]]=None, cols: Optional[Union[int, Tuple[int, int]]]=None, **kwargs: Incomplete) -> Incomplete: + """The driver function for adding axes legends.""" + ... diff --git a/ultraplot/proj.pyi b/ultraplot/proj.pyi new file mode 100644 index 000000000..3b1b61687 --- /dev/null +++ b/ultraplot/proj.pyi @@ -0,0 +1,221 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Additional cartopy projection classes. +""" +from _typeshed import Incomplete +import warnings +from .internals import ic +from .internals import docstring +try: + from cartopy.crs import AzimuthalEquidistant, Gnomonic, LambertAzimuthalEqualArea, NorthPolarStereo, SouthPolarStereo, _WarpedRectangularProjection +except ModuleNotFoundError: + AzimuthalEquidistant = Gnomonic = LambertAzimuthalEqualArea = object + _WarpedRectangularProjection = NorthPolarStereo = SouthPolarStereo = object +__all__ = ['Aitoff', 'Hammer', 'KavrayskiyVII', 'WinkelTripel', 'NorthPolarAzimuthalEquidistant', 'SouthPolarAzimuthalEquidistant', 'NorthPolarGnomonic', 'SouthPolarGnomonic', 'NorthPolarLambertAzimuthalEqualArea', 'SouthPolarLambertAzimuthalEqualArea'] +_reso_docstring = ... +_init_docstring = ... + +class Aitoff(_WarpedRectangularProjection): + """ + The `Aitoff `__ projection. + """ + name = 'aitoff' + + def __init__(self, central_longitude: Incomplete=0, globe: Incomplete=None, false_easting: Incomplete=None, false_northing: Incomplete=None) -> None: + """Parameters +---------- +central_longitude : float, default: 0 + The central meridian longitude in degrees. +false_easting: float, default: 0 + X offset from planar origin in metres. +false_northing: float, default: 0 + Y offset from planar origin in metres. +globe : `~cartopy.crs.Globe`, optional + If omitted, a default globe is created.""" + ... + + @property + def threshold(self) -> float: + """The projection resolution.""" + ... + +class Hammer(_WarpedRectangularProjection): + """ + The `Hammer `__ projection. + """ + name = 'hammer' + + def __init__(self, central_longitude: Incomplete=0, globe: Incomplete=None, false_easting: Incomplete=None, false_northing: Incomplete=None) -> None: + """Parameters +---------- +central_longitude : float, default: 0 + The central meridian longitude in degrees. +false_easting: float, default: 0 + X offset from planar origin in metres. +false_northing: float, default: 0 + Y offset from planar origin in metres. +globe : `~cartopy.crs.Globe`, optional + If omitted, a default globe is created.""" + ... + + @property + def threshold(self) -> float: + """The projection resolution.""" + ... + +class KavrayskiyVII(_WarpedRectangularProjection): + """ + The `Kavrayskiy VII `__ projection. + """ + name = 'kavrayskiyVII' + + def __init__(self, central_longitude: Incomplete=0, globe: Incomplete=None, false_easting: Incomplete=None, false_northing: Incomplete=None) -> None: + """Parameters +---------- +central_longitude : float, default: 0 + The central meridian longitude in degrees. +false_easting: float, default: 0 + X offset from planar origin in metres. +false_northing: float, default: 0 + Y offset from planar origin in metres. +globe : `~cartopy.crs.Globe`, optional + If omitted, a default globe is created.""" + ... + + @property + def threshold(self) -> float: + """The projection resolution.""" + ... + +class WinkelTripel(_WarpedRectangularProjection): + """ + The `Winkel tripel (Winkel III) `__ projection. + """ + name = 'winkeltripel' + + def __init__(self, central_longitude: Incomplete=0, globe: Incomplete=None, false_easting: Incomplete=None, false_northing: Incomplete=None) -> None: + """Parameters +---------- +central_longitude : float, default: 0 + The central meridian longitude in degrees. +false_easting: float, default: 0 + X offset from planar origin in metres. +false_northing: float, default: 0 + Y offset from planar origin in metres. +globe : `~cartopy.crs.Globe`, optional + If omitted, a default globe is created.""" + ... + + @property + def threshold(self) -> float: + """The projection resolution.""" + ... + +class NorthPolarAzimuthalEquidistant(AzimuthalEquidistant): + """ + Analogous to `~cartopy.crs.NorthPolarStereo`. + """ + + def __init__(self, central_longitude: Incomplete=0.0, globe: Incomplete=None) -> None: + """Parameters +---------- +central_longitude : float, default: 0 + The central meridian longitude in degrees. +false_easting: float, default: 0 + X offset from planar origin in metres. +false_northing: float, default: 0 + Y offset from planar origin in metres. +globe : `~cartopy.crs.Globe`, optional + If omitted, a default globe is created.""" + ... + +class SouthPolarAzimuthalEquidistant(AzimuthalEquidistant): + """ + Analogous to `~cartopy.crs.SouthPolarStereo`. + """ + + def __init__(self, central_longitude: Incomplete=0.0, globe: Incomplete=None) -> None: + """Parameters +---------- +central_longitude : float, default: 0 + The central meridian longitude in degrees. +false_easting: float, default: 0 + X offset from planar origin in metres. +false_northing: float, default: 0 + Y offset from planar origin in metres. +globe : `~cartopy.crs.Globe`, optional + If omitted, a default globe is created.""" + ... + +class NorthPolarLambertAzimuthalEqualArea(LambertAzimuthalEqualArea): + """ + Analogous to `~cartopy.crs.NorthPolarStereo`. + """ + + def __init__(self, central_longitude: Incomplete=0.0, globe: Incomplete=None) -> None: + """Parameters +---------- +central_longitude : float, default: 0 + The central meridian longitude in degrees. +false_easting: float, default: 0 + X offset from planar origin in metres. +false_northing: float, default: 0 + Y offset from planar origin in metres. +globe : `~cartopy.crs.Globe`, optional + If omitted, a default globe is created.""" + ... + +class SouthPolarLambertAzimuthalEqualArea(LambertAzimuthalEqualArea): + """ + Analogous to `~cartopy.crs.SouthPolarStereo`. + """ + + def __init__(self, central_longitude: Incomplete=0.0, globe: Incomplete=None) -> None: + """Parameters +---------- +central_longitude : float, default: 0 + The central meridian longitude in degrees. +false_easting: float, default: 0 + X offset from planar origin in metres. +false_northing: float, default: 0 + Y offset from planar origin in metres. +globe : `~cartopy.crs.Globe`, optional + If omitted, a default globe is created.""" + ... + +class NorthPolarGnomonic(Gnomonic): + """ + Analogous to `~cartopy.crs.NorthPolarStereo`. + """ + + def __init__(self, central_longitude: Incomplete=0.0, globe: Incomplete=None) -> None: + """Parameters +---------- +central_longitude : float, default: 0 + The central meridian longitude in degrees. +false_easting: float, default: 0 + X offset from planar origin in metres. +false_northing: float, default: 0 + Y offset from planar origin in metres. +globe : `~cartopy.crs.Globe`, optional + If omitted, a default globe is created.""" + ... + +class SouthPolarGnomonic(Gnomonic): + """ + Analogous to `~cartopy.crs.SouthPolarStereo`. + """ + + def __init__(self, central_longitude: Incomplete=0.0, globe: Incomplete=None) -> None: + """Parameters +---------- +central_longitude : float, default: 0 + The central meridian longitude in degrees. +false_easting: float, default: 0 + X offset from planar origin in metres. +false_northing: float, default: 0 + Y offset from planar origin in metres. +globe : `~cartopy.crs.Globe`, optional + If omitted, a default globe is created.""" + ... diff --git a/ultraplot/py.typed b/ultraplot/py.typed new file mode 100644 index 000000000..8b1378917 --- /dev/null +++ b/ultraplot/py.typed @@ -0,0 +1 @@ + diff --git a/ultraplot/scale.pyi b/ultraplot/scale.pyi new file mode 100644 index 000000000..653bbb3ea --- /dev/null +++ b/ultraplot/scale.pyi @@ -0,0 +1,573 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Various axis `~matplotlib.scale.ScaleBase` classes. +""" +from _typeshed import Incomplete +import copy +import matplotlib.scale as mscale +import matplotlib.ticker as mticker +import matplotlib.transforms as mtransforms +import numpy as np +import numpy.ma as ma +from . import ticker as pticker +from .internals import _not_none, _version_mpl, ic, warnings +__all__ = ['CutoffScale', 'ExpScale', 'FuncScale', 'InverseScale', 'LinearScale', 'LogitScale', 'LogScale', 'MercatorLatitudeScale', 'PowerScale', 'SineLatitudeScale', 'SymmetricalLogScale'] + +def _parse_logscale_args(*keys: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Parse arguments for `LogScale` and `SymmetricalLogScale` that +inexplicably require `x` and `y` suffixes by default. Also +change the default `linthresh` to ``1``.""" + ... + +class _Scale(object): + """ + Mix-in class that standardizes the behavior of + `~matplotlib.scale.ScaleBase.set_default_locators_and_formatters` + and `~matplotlib.scale.ScaleBase.get_transform`. Also overrides + `__init__` so you no longer have to instantiate scales with an + `~matplotlib.axis.Axis` instance. + """ + + def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: + ... + + def set_default_locators_and_formatters(self, axis: Incomplete, only_if_default: Incomplete=False) -> Incomplete: + """Apply all locators and formatters defined as attributes on +initialization and define defaults for all scales. + +Parameters +---------- +axis : `~matplotlib.axis.Axis` + The axis. +only_if_default : bool, optional + Whether to refrain from updating the locators and formatters if the + axis is currently using non-default versions. Useful if we want to + avoid overwriting user customization when the scale is changed.""" + ... + + def get_transform(self) -> Incomplete: + """Return the scale transform.""" + ... + +class LinearScale(_Scale, mscale.LinearScale): + """ + As with `~matplotlib.scale.LinearScale` but with + `~ultraplot.ticker.AutoFormatter` as the default major formatter. + """ + name = 'linear' + + def __init__(self, **kwargs: Incomplete) -> None: + """See also +-------- +ultraplot.constructor.Scale""" + ... + +class LogitScale(_Scale, mscale.LogitScale): + """ + As with `~matplotlib.scale.LogitScale` but with `~ultraplot.ticker.AutoFormatter` + as the default major formatter. + """ + name = 'logit' + + def __init__(self, **kwargs: Incomplete) -> None: + """Parameters +---------- +nonpos : {'mask', 'clip'} + Values outside of (0, 1) can be masked as invalid, or clipped to a + number very close to 0 or 1. + +See also +-------- +ultraplot.constructor.Scale""" + ... + +class LogScale(_Scale, mscale.LogScale): + """ + As with `~matplotlib.scale.LogScale` but with `~ultraplot.ticker.AutoFormatter` + as the default major formatter. `x` and `y` versions of each keyword + argument are no longer required. + """ + name = 'log' + + def __init__(self, **kwargs: Incomplete) -> None: + """Parameters +---------- +base : float, default: 10 + The base of the logarithm. +nonpos : {'mask', 'clip'}, optional + Non-positive values in *x* or *y* can be masked as + invalid, or clipped to a very small positive number. +subs : sequence of int, default: ``[1 2 3 4 5 6 7 8 9]`` + Default *minor* tick locations are on these multiples of each power + of the base. For example, ``subs=(1, 2, 5)`` draws ticks on 1, 2, + 5, 10, 20, 50, 100, 200, 500, etc. +basex, basey, nonposx, nonposy, subsx, subsy + Aliases for the above keywords. These used to be conditional + on the *name* of the axis. + +See also +-------- +ultraplot.constructor.Scale""" + ... + +class SymmetricalLogScale(_Scale, mscale.SymmetricalLogScale): + """ + As with `~matplotlib.scale.SymmetricalLogScale` but with + `~ultraplot.ticker.AutoFormatter` as the default major formatter. + `x` and `y` versions of each keyword argument are no longer + required. + """ + name = 'symlog' + + def __init__(self, **kwargs: Incomplete) -> None: + """Parameters +---------- +base : float, default: 10 + The base of the logarithm. +linthresh : float, default: 1 + Defines the range ``(-linthresh, linthresh)``, within which the plot + is linear. This avoids having the plot go to infinity around zero. +linscale : float, default: 1 + This allows the linear range ``(-linthresh, linthresh)`` to be + stretched relative to the logarithmic range. Its value is the + number of decades to use for each half of the linear range. For + example, when `linscale` is ``1`` (the default), the space used + for the positive and negative halves of the linear range will be + equal to one decade in the logarithmic range. +subs : sequence of int, default: ``[1 2 3 4 5 6 7 8 9]`` + Default *minor* tick locations are on these multiples of each power + of the base. For example, ``subs=(1, 2, 5)`` draws ticks on 1, 2, + 5, 10, 20, 50, 100, 200, 500, etc. +basex, basey, linthreshx, linthreshy, linscalex, linscaley, subsx, subsy + Aliases for the above keywords. These keywords used to be + conditional on the name of the axis. + +See also +-------- +ultraplot.constructor.Scale""" + ... + +class FuncScale(_Scale, mscale.ScaleBase): + """ + Axis scale composed of arbitrary forward and inverse transformations. + """ + name = 'function' + + def __init__(self, transform: Incomplete=None, invert: Incomplete=False, parent_scale: Incomplete=None, **kwargs: Incomplete) -> None: + """Parameters +---------- +transform : callable, 2-tuple of callable, or scale-spec + The transform used to translate units from the parent axis to + the secondary axis. Input can be as follows: + + * A single `linear `__ or + `involutory `__ + function that accepts a number and returns some transformation of + that number. For example, to convert Kelvin to Celsius, use + ``ax.dualx(lambda x: x - 273.15)``. To convert kilometers to + meters, use ``ax.dualx(lambda x: x * 1e3)``. + * A 2-tuple of arbitrary functions. This should only be used if your + functions are non-linear and non-involutory. The second function must + be the inverse of the first. For example, to apply the square, use + ``ax.dualx((lambda x: x ** 2, lambda x: x ** 0.5))``. + * A scale specification passed to the `~ultraplot.constructor.Scale` + constructor function. The transform and default locators and formatters + are borrowed from the resulting `~matplotlib.scale.ScaleBase` instance. + For example, to apply the inverse, use ``ax.dualx('inverse')``. + To apply the base-10 exponential, use ``ax.dualx(('exp', 10))``. + +invert : bool, optional + If ``True``, the forward and inverse functions are *swapped*. + Used when drawing dual axes. +parent_scale : `~matplotlib.scale.ScaleBase`, default: `LinearScale` + The axis scale of the "parent" axis. Its forward transform + is applied to the `FuncTransform`. +major_locator, minor_locator : locator-spec, optional + The default major and minor locator. Passed to the + `~ultraplot.constructor.Locator` constructor function. By default, these are + the same as the default locators on the input transform. If the input + transform was not an axis scale, these are borrowed from `parent_scale`. +major_formatter, minor_formatter : formatter-spec, optional + The default major and minor formatter. Passed to the + `~ultraplot.constructor.Formatter` constructor function. By default, these are + the same as the default formatters on the input transform. If the input + transform was not an axis scale, these are borrowed from `parent_scale`. + +See also +-------- +ultraplot.constructor.Scale +ultraplot.axes.CartesianAxes.dualx +ultraplot.axes.CartesianAxes.dualy""" + ... + +class FuncTransform(mtransforms.Transform): + input_dims = 1 + output_dims = 1 + is_separable = True + has_inverse = True + + def __init__(self, forward: Incomplete, inverse: Incomplete) -> None: + ... + + def inverted(self) -> Incomplete: + ... + + def transform_non_affine(self, values: Incomplete) -> Incomplete: + ... + +class PowerScale(_Scale, mscale.ScaleBase): + """ + "Power scale" that performs the transformation + + .. math:: + + x^{c} + + """ + name = 'power' + + def __init__(self, power: Incomplete=1, inverse: Incomplete=False) -> None: + """Parameters +---------- +power : float, optional + The power :math:`c` to which :math:`x` is raised. +inverse : bool, optional + If ``True`` this performs the inverse operation :math:`x^{1/c}`.""" + ... + + def limit_range_for_scale(self, vmin: Incomplete, vmax: Incomplete, minpos: Incomplete) -> Incomplete: + """Return the range *vmin* and *vmax* limited to positive numbers.""" + ... + +class PowerTransform(mtransforms.Transform): + input_dims = 1 + output_dims = 1 + has_inverse = True + is_separable = True + + def __init__(self, power: Incomplete) -> None: + ... + + def inverted(self) -> Incomplete: + ... + + def transform_non_affine(self, a: Incomplete) -> Incomplete: + ... + +class InvertedPowerTransform(mtransforms.Transform): + input_dims = 1 + output_dims = 1 + has_inverse = True + is_separable = True + + def __init__(self, power: Incomplete) -> None: + ... + + def inverted(self) -> Incomplete: + ... + + def transform_non_affine(self, a: Incomplete) -> Incomplete: + ... + +class ExpScale(_Scale, mscale.ScaleBase): + """ + "Exponential scale" that performs either of two transformations. When + `inverse` is ``False`` (the default), performs the transformation + + .. math:: + + Ca^{bx} + + where the constants :math:`a`, :math:`b`, and :math:`C` are set by the + input (see below). When `inverse` is ``True``, this performs the inverse + transformation + + .. math:: + + (\\log_a(x) - \\log_a(C))/b + + which in appearance is equivalent to `LogScale` since it is just a linear + transformation of the logarithm. + """ + name = 'exp' + + def __init__(self, a: Incomplete=np.e, b: Incomplete=1, c: Incomplete=1, inverse: Incomplete=False) -> None: + """Parameters +---------- +a : float, optional + The base of the exponential, i.e. the :math:`a` in :math:`Ca^{bx}`. +b : float, optional + The scale for the exponent, i.e. the :math:`b` in :math:`Ca^{bx}`. +c : float, optional + The coefficient of the exponential, i.e. the :math:`C` in :math:`Ca^{bx}`. +inverse : bool, optional + If ``True``, the "forward" direction performs the inverse operation. + +See also +-------- +ultraplot.constructor.Scale""" + ... + + def limit_range_for_scale(self, vmin: Incomplete, vmax: Incomplete, minpos: Incomplete) -> Incomplete: + """Return the range *vmin* and *vmax* limited to positive numbers.""" + ... + +class ExpTransform(mtransforms.Transform): + input_dims = 1 + output_dims = 1 + has_inverse = True + is_separable = True + + def __init__(self, a: Incomplete, b: Incomplete, c: Incomplete) -> None: + ... + + def inverted(self) -> Incomplete: + ... + + def transform_non_affine(self, a: Incomplete) -> Incomplete: + ... + +class InvertedExpTransform(mtransforms.Transform): + input_dims = 1 + output_dims = 1 + has_inverse = True + is_separable = True + + def __init__(self, a: Incomplete, b: Incomplete, c: Incomplete) -> None: + ... + + def inverted(self) -> Incomplete: + ... + + def transform_non_affine(self, a: Incomplete) -> Incomplete: + ... + +class MercatorLatitudeScale(_Scale, mscale.ScaleBase): + """ + Axis scale that is linear in the `Mercator projection latitude `__. Adapted from `this example `__. + The scale function is as follows: + + .. math:: + + y = \\ln(\\tan(\\pi x \\,/\\, 180) + \\sec(\\pi x \\,/\\, 180)) + + The inverse scale function is as follows: + + .. math:: + + x = 180\\,\\arctan(\\sinh(y)) \\,/\\, \\pi + + """ + name = 'mercator' + + def __init__(self, thresh: Incomplete=85.0) -> None: + """Parameters +---------- +thresh : float, optional + Threshold between 0 and 90, used to constrain axis limits + between ``-thresh`` and ``+thresh``. + +See also +-------- +ultraplot.constructor.Scale""" + ... + + def limit_range_for_scale(self, vmin: Incomplete, vmax: Incomplete, minpos: Incomplete) -> Incomplete: + """Return the range *vmin* and *vmax* limited to within +/-90 degrees +(exclusive).""" + ... + +class MercatorLatitudeTransform(mtransforms.Transform): + input_dims = 1 + output_dims = 1 + is_separable = True + has_inverse = True + + def __init__(self, thresh: Incomplete) -> None: + ... + + def inverted(self) -> Incomplete: + ... + + def transform_non_affine(self, a: Incomplete) -> Incomplete: + ... + +class InvertedMercatorLatitudeTransform(mtransforms.Transform): + input_dims = 1 + output_dims = 1 + is_separable = True + has_inverse = True + + def __init__(self, thresh: Incomplete) -> None: + ... + + def inverted(self) -> Incomplete: + ... + + def transform_non_affine(self, a: Incomplete) -> Incomplete: + ... + +class SineLatitudeScale(_Scale, mscale.ScaleBase): + """ + Axis scale that is linear in the sine transformation of *x*. The axis + limits are constrained to fall between ``-90`` and ``+90`` degrees. + The scale function is as follows: + + .. math:: + + y = \\sin(\\pi x/180) + + The inverse scale function is as follows: + + .. math:: + + x = 180\\arcsin(y)/\\pi + """ + name = 'sine' + + def __init__(self) -> None: + """See also +-------- +ultraplot.constructor.Scale""" + ... + + def limit_range_for_scale(self, vmin: Incomplete, vmax: Incomplete, minpos: Incomplete) -> tuple[int, int]: + """Return the range *vmin* and *vmax* limited to within +/-90 degrees +(inclusive).""" + ... + +class SineLatitudeTransform(mtransforms.Transform): + input_dims = 1 + output_dims = 1 + is_separable = True + has_inverse = True + + def __init__(self) -> None: + ... + + def inverted(self) -> Incomplete: + ... + + def transform_non_affine(self, a: Incomplete) -> Incomplete: + ... + +class InvertedSineLatitudeTransform(mtransforms.Transform): + input_dims = 1 + output_dims = 1 + is_separable = True + has_inverse = True + + def __init__(self) -> None: + ... + + def inverted(self) -> Incomplete: + ... + + def transform_non_affine(self, a: Incomplete) -> Incomplete: + ... + +class CutoffScale(_Scale, mscale.ScaleBase): + """ + Axis scale composed of arbitrary piecewise linear transformations. + The axis can undergo discrete jumps, "accelerations", or "decelerations" + between successive thresholds. + """ + name = 'cutoff' + + def __init__(self, *args: Incomplete) -> None: + """Parameters +---------- +*args : thresh_1, scale_1, ..., thresh_N, [scale_N], optional + Sequence of "thresholds" and "scales". If the final scale is + omitted (i.e. you passed an odd number of arguments) it is set + to ``1``. Each ``scale_i`` in the sequence can be interpreted + as follows: + + * If ``scale_i < 1``, the axis is decelerated from ``thresh_i`` to + ``thresh_i+1``. For ``scale_N``, the axis is decelerated + everywhere above ``thresh_N``. + * If ``scale_i > 1``, the axis is accelerated from ``thresh_i`` to + ``thresh_i+1``. For ``scale_N``, the axis is accelerated + everywhere above ``thresh_N``. + * If ``scale_i == numpy.inf``, the axis *discretely jumps* from + ``thresh_i`` to ``thresh_i+1``. The final scale ``scale_N`` + *cannot* be ``numpy.inf``. + +See also +-------- +ultraplot.constructor.Scale + +Example +------- +>>> import ultraplot as uplt +>>> import numpy as np +>>> scale = uplt.CutoffScale(10, 0.5) # move slower above 10 +>>> scale = uplt.CutoffScale(10, 2, 20) # move faster between 10 and 20 +>>> scale = uplt.CutoffScale(10, np.inf, 20) # jump from 10 to 20""" + ... + +class CutoffTransform(mtransforms.Transform): + input_dims = 1 + output_dims = 1 + has_inverse = True + is_separable = True + + def __init__(self, threshs: Incomplete, scales: Incomplete, zero_dists: Incomplete=None) -> None: + ... + + def inverted(self) -> Incomplete: + ... + + def transform_non_affine(self, a: Incomplete) -> Incomplete: + ... + +class InverseScale(_Scale, mscale.ScaleBase): + """ + Axis scale that is linear in the *inverse* of *x*. The forward and inverse + scale functions are as follows: + + .. math:: + + y = x^{-1} + + """ + name = 'inverse' + + def __init__(self) -> None: + """See also +-------- +ultraplot.constructor.Scale""" + ... + + def limit_range_for_scale(self, vmin: Incomplete, vmax: Incomplete, minpos: Incomplete) -> Incomplete: + """Return the range *vmin* and *vmax* limited to positive numbers.""" + ... + +class InverseTransform(mtransforms.Transform): + input_dims = 1 + output_dims = 1 + is_separable = True + has_inverse = True + + def __init__(self) -> None: + ... + + def inverted(self) -> Incomplete: + ... + + def transform_non_affine(self, a: Incomplete) -> Incomplete: + ... + +def _scale_factory(scale: Incomplete, axis: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Generate an axis scale. + +Parameters +---------- +scale : str or `~matplotlib.scale.ScaleBase` + The axis scale name or scale instance. +axis : `~matplotlib.axis.Axis` + The axis instance. +*args, **kwargs + Passed to `~matplotlib.scale.ScaleBase` if `scale` is a string.""" + ... diff --git a/ultraplot/tests/test_docstring_helpers.py b/ultraplot/tests/test_docstring_helpers.py index 2ff7627ef..c83d98a00 100644 --- a/ultraplot/tests/test_docstring_helpers.py +++ b/ultraplot/tests/test_docstring_helpers.py @@ -61,6 +61,20 @@ def test_method_docstring_fully_substituted() -> None: assert "%(artist" not in doc +def test_public_docstrings_with_snippets_are_fully_substituted() -> None: + """Public methods must not expose internal snippet placeholders.""" + for obj in (uplt.axes.PlotAxes.circos, uplt.Configurator.register_handler): + doc = obj.__doc__ or "" + assert "%(" not in doc + + assert "Create a Circos instance using pyCirclize." in ( + uplt.axes.PlotAxes.circos.__doc__ or "" + ) + assert "Register a callback function to be executed" in ( + uplt.Configurator.register_handler.__doc__ or "" + ) + + def test_geo_format_folds_alias_entries() -> None: # The geo format docstring folded its standalone "Aliases for ..." blocks # into trailing notes on the canonical locator entries. diff --git a/ultraplot/tests/test_stubs.py b/ultraplot/tests/test_stubs.py new file mode 100644 index 000000000..3d978009a --- /dev/null +++ b/ultraplot/tests/test_stubs.py @@ -0,0 +1,138 @@ +import ast +import os +import re +import shutil +import subprocess +import sys +from pathlib import Path + +import pytest + +from ultraplot.internals.docstring import _snippet_manager + +ROOT = Path(__file__).resolve().parents[2] +PACKAGE = ROOT / "ultraplot" +GENERATED_HEADER = "# @generated by tools/generate_stubs.py; do not edit" +PLACEHOLDER_PATTERN = re.compile(r"%\(([^)]+)\)s") + + +def _generated_stubs(): + return sorted( + path + for path in PACKAGE.rglob("*.pyi") + if path.read_text(encoding="utf-8").startswith(GENERATED_HEADER) + ) + + +def _type_checking_imports(path): + """Return the names imported inside a ``TYPE_CHECKING`` guard.""" + tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path)) + names = set() + for node in tree.body: + if not isinstance(node, ast.If): + continue + test = node.test + if not (isinstance(test, ast.Name) and test.id == "TYPE_CHECKING") and not ( + isinstance(test, ast.Attribute) and test.attr == "TYPE_CHECKING" + ): + continue + for statement in ast.walk(node): + if isinstance(statement, (ast.Import, ast.ImportFrom)): + names.update(alias.asname or alias.name for alias in statement.names) + return names + + +def _top_level_imports(path): + """Return the names imported at module scope.""" + tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path)) + return { + alias.asname or alias.name + for node in tree.body + if isinstance(node, (ast.Import, ast.ImportFrom)) + for alias in node.names + } + + +def test_generated_stubs_are_current(): + pyrefly = shutil.which("pyrefly") + if pyrefly is None: + pytest.skip("stub freshness requires the optional `typing` dependencies") + env = os.environ.copy() + env.setdefault("MPLCONFIGDIR", "/tmp/ultraplot-matplotlib") + result = subprocess.run( + [ + sys.executable, + str(ROOT / "tools" / "generate_stubs.py"), + "--check", + "--pyrefly", + pyrefly, + ], + cwd=ROOT, + env=env, + check=True, + capture_output=True, + text=True, + ) + assert "source modules and their stubs" in result.stdout + assert "all up to date" in result.stdout + + +def test_generated_stub_signatures_are_fully_annotated(): + missing = [] + for path in _generated_stubs(): + tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path)) + for node in ast.walk(tree): + if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)): + continue + if node.returns is None: + missing.append(f"{path.relative_to(ROOT)}:{node.lineno}: return") + arguments = ( + *node.args.posonlyargs, + *node.args.args, + *node.args.kwonlyargs, + node.args.vararg, + node.args.kwarg, + ) + for argument in arguments: + if ( + argument is not None + and argument.arg not in {"self", "cls"} + and argument.annotation is None + ): + missing.append( + f"{path.relative_to(ROOT)}:{node.lineno}: {argument.arg}" + ) + assert not missing, "Unannotated generated signatures:\n" + "\n".join(missing) + + +def test_generated_stubs_are_valid_and_docstrings_are_expanded(): + stubs = _generated_stubs() + assert stubs + + unresolved = [] + for path in stubs: + tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path)) + for node in ast.walk(tree): + if not isinstance( + node, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef) + ): + continue + doc = ast.get_docstring(node, clean=False) or "" + for key in PLACEHOLDER_PATTERN.findall(doc): + try: + _snippet_manager[key] + except KeyError: + continue + unresolved.append(f"{path.relative_to(ROOT)}:{node.lineno}: {key}") + + assert not unresolved, "Registered docstring placeholders remain:\n" + "\n".join( + unresolved + ) + + +def test_root_stub_exposes_lazy_public_imports(): + source_names = _type_checking_imports(PACKAGE / "__init__.py") + stub_names = _top_level_imports(PACKAGE / "__init__.pyi") + + assert source_names + assert not source_names - stub_names diff --git a/ultraplot/text.pyi b/ultraplot/text.pyi new file mode 100644 index 000000000..f7495f27d --- /dev/null +++ b/ultraplot/text.pyi @@ -0,0 +1,78 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Text-related artists and helpers. +""" +from _typeshed import Incomplete +from typing import Iterable, Tuple +import matplotlib.text as mtext +import numpy as np +from .internals import labels +__all__ = ['CurvedText'] + +class CurvedText(mtext.Text): + """ + A text object that follows an arbitrary curve. + + Parameters + ---------- + x, y : array-like + Curve coordinates. + text : str + Text to render along the curve. + axes : matplotlib.axes.Axes + Target axes. + upright : bool, default: True + Whether to flip the curve direction to keep text upright. + ellipsis : bool, default: False + Whether to show an ellipsis when the text exceeds curve length. + avoid_overlap : bool, default: True + Whether to hide glyphs that overlap after rotation. + overlap_tol : float, default: 0.1 + Fractional overlap area (0–1) required before hiding a glyph. + curvature_pad : float, default: 2.0 + Extra spacing in pixels per radian of local curvature. + min_advance : float, default: 1.0 + Minimum additional spacing (pixels) enforced between glyph centers. + **kwargs + Passed to `matplotlib.text.Text` for character styling. + """ + + def __init__(self, x: Incomplete, y: Incomplete, text: Incomplete, axes: Incomplete, *, upright: Incomplete=True, ellipsis: Incomplete=False, avoid_overlap: Incomplete=True, overlap_tol: Incomplete=0.1, curvature_pad: Incomplete=2.0, min_advance: Incomplete=1.0, **kwargs: Incomplete) -> None: + ... + + def _restore_clip_on(self, t: Incomplete) -> None: + """Re-assert clip_on after add_artist/add_text resets it.""" + ... + + def _build_characters(self, text: str) -> None: + ... + + def set_text(self, s: Incomplete) -> None: + ... + + def get_text(self) -> str: + ... + + def set_curve(self, x: Iterable[float], y: Iterable[float]) -> None: + ... + + def get_curve(self) -> Tuple[np.ndarray, np.ndarray]: + ... + + def _apply_label_props(self, props: Incomplete) -> None: + ... + + def set_zorder(self, zorder: Incomplete) -> None: + ... + + def set_transform(self, transform: Incomplete) -> None: + ... + + def draw(self, renderer: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> None: + """Overload `Text.draw()` to update character positions and rotations.""" + ... + + def update_positions(self, renderer: Incomplete) -> None: + """Update positions and rotations of the individual text elements.""" + ... diff --git a/ultraplot/textalign.pyi b/ultraplot/textalign.pyi new file mode 100644 index 000000000..ac2243196 --- /dev/null +++ b/ultraplot/textalign.pyi @@ -0,0 +1,159 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Automatic repositioning of text and annotation boxes so they do not overlap. + +The solver works entirely in display (pixel) space, so it is agnostic to the +transform attached to each label -- data, axes, log-scaled, polar and +geographic labels are all handled the same way. Labels are reset to their +original anchors before every pass, which keeps the result stable across +repeated draws, resizes and dpi changes. +""" +from _typeshed import Incomplete +from typing import Iterable, Optional, Sequence +import matplotlib.collections as mcollections +import matplotlib.lines as mlines +import matplotlib.patches as mpatches +import matplotlib.text as mtext +import matplotlib.transforms as mtransforms +import numpy as np +__all__ = ['align_text'] +_RESTART_LIMIT = 120 + +def _points_to_pixels(fig: Incomplete, value: Incomplete) -> float: + ... + +def _expand_bbox(bbox: Incomplete, padx: float, pady: float) -> Incomplete: + ... + +def _fits(box: Incomplete, sx: Incomplete, sy: Incomplete, bounds: Incomplete) -> bool: + """Whether shifting ``box`` (x0, y0, x1, y1) by half of (sx, sy) keeps it inside +``bounds`` -- half, because a box only takes half of a pairwise push.""" + ... + +def _overlap_shift(b1: Incomplete, b2: Incomplete, bounds: Incomplete=None) -> Incomplete: + """Return the translation ``(sx, sy)`` separating box ``b1`` from ``b2``, or zeros. + +Boxes are ``(x0, y0, x1, y1)``. Both axis-aligned escape routes are considered +and the shallower one wins, because every pixel a label moves is a pixel further +from the thing it describes. If that route would push the label out of +``bounds`` the other one is used instead -- without this, a stack of labels +jammed against the edge of the axes gets shoved straight back into the wall on +every iteration and can never spread out sideways. + +This runs once per colliding pair per iteration, so it deals in plain floats: +building a two-element numpy array here costs more than all the arithmetic.""" + ... + +def _point_shift(box: Incomplete, px: Incomplete, py: Incomplete) -> Incomplete: + """Return the shortest translation ``(sx, sy)`` that moves ``box`` off a point.""" + ... + +def _colliding_pairs(boxes: Incomplete, live: Incomplete) -> Incomplete: + """Indices (i, j), i < j, of every pair of live boxes that currently overlap. + +One vectorised sweep. A k-d tree radius query is asymptotically better and is +genuinely faster at this step in isolation, but it does not pay for itself +here: even at 800 labels this sweep is a low single-digit percentage of the +solve, which is dominated by resolving the collisions it finds. It is not worth +a SciPy dependency to speed up something that is not the bottleneck.""" + ... + +def _count_overlaps(boxes: Incomplete) -> int: + """Number of label pairs that visibly overlap. Takes the raw boxes, without the +padding cushion: the cushion is a solver knob, but the score must be judged on +the boxes the reader actually sees.""" + ... + +def _crowd_seed(anchors: Incomplete, obstacles: Incomplete, sizes: Incomplete) -> np.ndarray: + """Initial offsets that push every label away from its local crowd. + +Relaxing from the original positions is a purely local search, so a dense +cluster can settle into a knot that no amount of further iteration undoes. +Starting from a pre-exploded configuration puts the solver in a different +basin, which is what the restarts are for.""" + ... + +def _artist_points(artist: Incomplete) -> Optional[np.ndarray]: + """Sample the display-space points an artist occupies, or None if unsupported.""" + ... + +def _gather_obstacles(ax: Incomplete, labels: Incomplete, avoid_points: bool) -> Incomplete: + """Collect display-space points (data markers/vertices) that labels avoid.""" + ... + +def _label_bbox(label: Incomplete, renderer: Incomplete, padx: Incomplete, pady: Incomplete) -> Incomplete: + ... + +def _position(label: Incomplete) -> tuple: + """Where the label currently sits, in its own coordinate system.""" + ... + +def _place(label: Incomplete, point: Incomplete) -> None: + """Move a label to ``point`` and record that we are the ones who put it there.""" + ... + +def _reset_label(label: Incomplete) -> np.ndarray: + """Restore a label to its user-specified anchor and return that anchor. + +The anchor is cached in the label's own coordinate system the first time we +see it, so re-running the solver on every draw is idempotent rather than +cumulative. A label that is not where we last left it has been repositioned by +the user since the previous solve, and that new position becomes the anchor -- +otherwise ``set_position`` on an aligned label would appear to do nothing, +with the next draw quietly dragging it back to an anchor the user has +abandoned.""" + ... + +def _text_transform(label: Incomplete, renderer: Incomplete) -> Incomplete: + """Return the transform mapping a label's stored position to display space.""" + ... + +def _move_label(label: Incomplete, delta_display: Incomplete, anchor: Incomplete, transform: Incomplete) -> None: + """Offset a label by ``delta_display`` pixels from its anchor.""" + ... + +def _target_display(label: Incomplete, renderer: Incomplete) -> Incomplete: + """Display-space point the label refers to (the annotated point, or its anchor).""" + ... + +def align_text(ax: Incomplete, labels: Optional[Sequence[mtext.Text]]=None, *, renderer: Incomplete=None, pad: float=2.0, avoid_points: bool=True, avoid: Iterable=(), only_move: str='xy', max_iter: int=60, spring: float=0.05, step: float=0.6, clip: bool=True, arrows: bool | dict=False, min_arrow_dist: float=8.0) -> list: + """Nudge text objects until they no longer overlap each other or the data. + +Parameters +---------- +ax : ultraplot.axes.Axes + The axes whose labels are aligned. +labels : sequence of `~matplotlib.text.Text`, optional + The labels to move. Default is every text registered for alignment on + the axes (see `~ultraplot.axes.Axes.text` with ``avoid_overlap=True``). +pad : float, default: 2.0 + Padding in points added around every label bounding box. +avoid_points : bool, default: True + Whether labels also repel the data points of lines and scatter plots. +avoid : sequence of `~matplotlib.artist.Artist`, optional + Additional artists (a legend, an inset, ...) whose bounding boxes the + labels must stay clear of. +only_move : {'xy', 'x', 'y'}, default: 'xy' + Restrict movement to a single axis. Useful when the horizontal position + of a label is meaningful, e.g. labels on a time series. +max_iter : int, default: 60 + Maximum number of relaxation iterations. +spring : float, default: 0.05 + Strength of the pull back towards the original anchor. Larger values + keep labels closer to where they were placed at the cost of overlap. +step : float, default: 0.6 + Damping applied to each iteration's displacement. +clip : bool, default: True + Whether to keep labels inside the axes. +arrows : bool or dict, default: False + Whether to draw a connector from displaced labels back to their anchor. + A dict is passed to `~matplotlib.patches.FancyArrowPatch`. +min_arrow_dist : float, default: 8.0 + Only draw connectors for labels displaced further than this (in points). + +Returns +------- +list + The connector patches that were drawn, if any.""" + ... diff --git a/ultraplot/ticker.pyi b/ultraplot/ticker.pyi new file mode 100644 index 000000000..6fa4b1c66 --- /dev/null +++ b/ultraplot/ticker.pyi @@ -0,0 +1,605 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Various `~matplotlib.ticker.Locator` and `~matplotlib.ticker.Formatter` classes. +""" +from _typeshed import Incomplete +import locale +import re +from fractions import Fraction +import matplotlib.axis as maxis +import matplotlib.dates as mdates +import matplotlib.ticker as mticker +import matplotlib.transforms as mtransforms +import matplotlib.units as munits +from datetime import datetime, timedelta +import numpy as np +try: + import cftime +except ModuleNotFoundError: + cftime = None +from .config import rc +from .internals import ic +from .internals import _not_none, context, docstring +try: + import cartopy.crs as ccrs + from cartopy.mpl.ticker import LatitudeFormatter, LongitudeFormatter, _PlateCarreeFormatter +except ModuleNotFoundError: + ccrs = None + LatitudeFormatter = LongitudeFormatter = _PlateCarreeFormatter = object +__all__ = ['IndexLocator', 'DiscreteLocator', 'DegreeLocator', 'LongitudeLocator', 'LatitudeLocator', 'AutoFormatter', 'SimpleFormatter', 'IndexFormatter', 'SciFormatter', 'SigFigFormatter', 'FracFormatter', 'CFDatetimeFormatter', 'AutoCFDatetimeFormatter', 'AutoCFDatetimeLocator', 'DegreeFormatter', 'LongitudeFormatter', 'LatitudeFormatter'] +REGEX_ZERO = re.compile('\\A[-−]?0(.0*)?\\Z') +REGEX_MINUS = re.compile('\\A[-−]\\Z') +REGEX_MINUS_ZERO = re.compile('\\A[-−]0(.0*)?\\Z') +_precision_docstring = ... +_zerotrim_docstring = ... +_auto_docstring = ... +_formatter_call = '\nConvert number to a string.\n\nParameters\n----------\nx : float\n The value.\npos : float, optional\n The position.\n' +_dms_docstring = ... + +def _default_precision_zerotrim(precision: Incomplete=None, zerotrim: Incomplete=None) -> Incomplete: + """Return the default zerotrim and precision. Shared by several formatters.""" + ... + +class IndexLocator(mticker.Locator): + """ + Format numbers by assigning fixed strings to non-negative indices. The ticks + are restricted to the extent of plotted content when content is present. + """ + + def __init__(self, base: Incomplete=1, offset: Incomplete=0) -> None: + ... + + def set_params(self, base: Incomplete=None, offset: Incomplete=None) -> None: + ... + + def __call__(self) -> Incomplete: + ... + + def tick_values(self, vmin: Incomplete, vmax: Incomplete) -> Incomplete: + ... + +class DiscreteLocator(mticker.Locator): + """ + A tick locator suitable for discretized colorbars. Adds ticks to some + subset of the location list depending on the available space determined from + `~matplotlib.axis.Axis.get_tick_space`. Zero will be used if it appears in the + location list, and step sizes along the location list are restricted to "nice" + intervals by default. + """ + default_params = {'nbins': None, 'minor': False, 'steps': np.array([1, 2, 3, 4, 5, 6, 8, 10]), 'min_n_ticks': 2} + + def __init__(self, locs: Incomplete, **kwargs: Incomplete) -> None: + """Parameters +---------- +locs : array-like + The tick location list. +nbins : int, optional + Maximum number of ticks to select. By default this is automatically + determined based on the the axis length and tick label font size. +minor : bool, default: False + Whether this is for "minor" ticks. Setting to ``True`` will select more + ticks with an index step that divides the index step used for "major" ticks. +steps : array-like of int, default: ``[1 2 3 4 5 6 8]`` + Valid integer index steps when selecting from the tick list. Must fall + between 1 and 9. Powers of 10 of these step sizes will also be permitted. +min_n_ticks : int, default: 1 + The minimum number of ticks to select. See also `nbins`.""" + ... + + def __call__(self) -> Incomplete: + """Return the locations of the ticks.""" + ... + + def set_params(self, steps: Incomplete=None, nbins: Incomplete=None, minor: Incomplete=None, min_n_ticks: Incomplete=None) -> None: + """Set the parameters for this locator. See `DiscreteLocator` for details.""" + ... + + def tick_values(self, vmin: Incomplete, vmax: Incomplete) -> Incomplete: + """Return the locations of the ticks.""" + ... + +class DegreeLocator(mticker.MaxNLocator): + """ + Locate geographic gridlines with degree-minute-second support. + Adapted from cartopy. + """ + default_params = mticker.MaxNLocator.default_params.copy() + + def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: + """Parameters +---------- +dms : bool, default: False + Locate the ticks on clean degree-minute-second intervals and format the + ticks with minutes and seconds instead of decimals.""" + ... + + def set_params(self, **kwargs: Incomplete) -> None: + ... + + def _guess_steps(self, vmin: Incomplete, vmax: Incomplete) -> None: + ... + + def _raw_ticks(self, vmin: Incomplete, vmax: Incomplete) -> Incomplete: + ... + + def bin_boundaries(self, vmin: Incomplete, vmax: Incomplete) -> Incomplete: + ... + +class LongitudeLocator(DegreeLocator): + """ + Locate longitude gridlines with degree-minute-second support. + Adapted from cartopy. + """ + + def __init__(self, lon0: Incomplete=0, *args: Incomplete, **kwargs: Incomplete) -> None: + """Parameters +---------- +dms : bool, default: False + Locate the ticks on clean degree-minute-second intervals and format the + ticks with minutes and seconds instead of decimals. + +Parameters +---------- +lon0 : float, default=0 + The central longitude around which the longitude labels are centered. + This parameter adjusts the alignment of the longitude gridlines and + labels, ensuring they are centered relative to the specified value.""" + ... + +class LatitudeLocator(DegreeLocator): + """ + Locate latitude gridlines with degree-minute-second support. + Adapted from cartopy. + """ + + def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: + """Parameters +---------- +dms : bool, default: False + Locate the ticks on clean degree-minute-second intervals and format the + ticks with minutes and seconds instead of decimals.""" + ... + + def tick_values(self, vmin: Incomplete, vmax: Incomplete) -> Incomplete: + ... + + def _guess_steps(self, vmin: Incomplete, vmax: Incomplete) -> None: + ... + + def _raw_ticks(self, vmin: Incomplete, vmax: Incomplete) -> Incomplete: + ... + +class AutoFormatter(mticker.ScalarFormatter): + """ + The default formatter used for ultraplot tick labels. + Replaces `~matplotlib.ticker.ScalarFormatter`. + """ + + def __init__(self, zerotrim: Incomplete=None, tickrange: Incomplete=None, wraprange: Incomplete=None, prefix: Incomplete=None, suffix: Incomplete=None, negpos: Incomplete=None, **kwargs: Incomplete) -> None: + """Parameters +---------- +zerotrim : bool, default: :rc:`formatter.zerotrim` + Whether to trim trailing decimal zeros. +tickrange : 2-tuple of float, optional + Range within which major tick marks are labeled. + All ticks are labeled by default. +wraprange : 2-tuple of float, optional + Range outside of which tick values are wrapped. For example, + ``(-180, 180)`` will format a value of ``200`` as ``-160``. +prefix, suffix : str, optional + Prefix and suffix for all tick strings. The suffix is added before + the optional `negpos` suffix. +negpos : str, optional + Length-2 string indicating the suffix for "negative" and "positive" + numbers, meant to replace the minus sign. + +Other parameters +---------------- +**kwargs + Passed to `matplotlib.ticker.ScalarFormatter`. + +See also +-------- +ultraplot.constructor.Formatter +ultraplot.ticker.SimpleFormatter + +Note +---- +`matplotlib.ticker.ScalarFormatter` determines the number of +significant digits based on the axis limits, and therefore may +truncate digits while formatting ticks on highly non-linear axis +scales like `~ultraplot.scale.LogScale`. `AutoFormatter` corrects +this behavior, making it suitable for arbitrary axis scales. We +therefore use `AutoFormatter` with every axis scale by default.""" + ... + + def __call__(self, x: Incomplete, pos: Incomplete=None) -> Incomplete: + """Convert number to a string. + +Parameters +---------- +x : float + The value. +pos : float, optional + The position.""" + ... + + def get_offset(self) -> str: + """Get the offset but *always* use math text.""" + ... + + @staticmethod + def _add_prefix_suffix(string: Incomplete, prefix: Incomplete=None, suffix: Incomplete=None) -> Incomplete: + """Add prefix and suffix to string.""" + ... + + def _fix_small_number(self, x: Incomplete, string: Incomplete, precision_offset: Incomplete=2) -> Incomplete: + """Fix formatting for non-zero formatted as zero. The `offset` controls the offset +from true floating point precision at which we want to limit string precision.""" + ... + + def _get_decimal_point(self, use_locale: Incomplete=None) -> str: + """Get decimal point symbol for current locale (e.g. in Europe will be comma).""" + ... + + @staticmethod + def _get_default_decimal_point(use_locale: Incomplete=None) -> str: + """Get decimal point symbol for current locale. Called externally.""" + ... + + @staticmethod + def _decimal_place(x: Incomplete) -> int: + """Return the decimal place of the number (e.g., 100 is -2 and 0.01 is 2).""" + ... + + @staticmethod + def _minus_format(string: Incomplete) -> Incomplete: + """Format the minus sign and avoid "negative zero," e.g. ``-0.000``.""" + ... + + @staticmethod + def _neg_pos_format(x: Incomplete, negpos: Incomplete, wraprange: Incomplete=None) -> Incomplete: + """Permit suffixes indicators for "negative" and "positive" numbers.""" + ... + + @staticmethod + def _outside_tick_range(x: Incomplete, tickrange: Incomplete) -> Incomplete: + """Return whether point is outside tick range up to some precision.""" + ... + + @staticmethod + def _trim_trailing_zeros(string: Incomplete, decimal_point: Incomplete='.') -> Incomplete: + """Sanitize tick label strings.""" + ... + + @staticmethod + def _wrap_tick_range(x: Incomplete, wraprange: Incomplete) -> Incomplete: + """Wrap the tick range to within these values.""" + ... + +class SimpleFormatter(mticker.Formatter): + """ + A general purpose number formatter. This is similar to `AutoFormatter` + but suitable for arbitrary formatting not necessarily associated with + an `~matplotlib.axis.Axis` instance. + """ + + def __init__(self, precision: Incomplete=None, zerotrim: Incomplete=None, tickrange: Incomplete=None, wraprange: Incomplete=None, prefix: Incomplete=None, suffix: Incomplete=None, negpos: Incomplete=None) -> None: + """Parameters +---------- +precision : int, default: {6, 2} + The maximum number of digits after the decimal point. Default is ``6`` + when `zerotrim` is ``True`` and ``2`` otherwise. +zerotrim : bool, default: :rc:`formatter.zerotrim` + Whether to trim trailing decimal zeros. +tickrange : 2-tuple of float, optional + Range within which major tick marks are labeled. + All ticks are labeled by default. +wraprange : 2-tuple of float, optional + Range outside of which tick values are wrapped. For example, + ``(-180, 180)`` will format a value of ``200`` as ``-160``. +prefix, suffix : str, optional + Prefix and suffix for all tick strings. The suffix is added before + the optional `negpos` suffix. +negpos : str, optional + Length-2 string indicating the suffix for "negative" and "positive" + numbers, meant to replace the minus sign. + +See also +-------- +ultraplot.constructor.Formatter +ultraplot.ticker.AutoFormatter""" + ... + + def __call__(self, x: Incomplete, pos: Incomplete=None) -> Incomplete: + """Convert number to a string. + +Parameters +---------- +x : float + The value. +pos : float, optional + The position.""" + ... + +class IndexFormatter(mticker.Formatter): + """ + Format numbers by assigning fixed strings to non-negative indices. Generally + paired with `IndexLocator` or `~matplotlib.ticker.FixedLocator`. + """ + + def __init__(self, labels: Incomplete) -> None: + ... + + def __call__(self, x: Incomplete, pos: Incomplete=None) -> Incomplete: + ... + +class SciFormatter(mticker.Formatter): + """ + Format numbers with scientific notation. + """ + + def __init__(self, precision: Incomplete=None, zerotrim: Incomplete=None) -> None: + """Parameters +---------- +precision : int, default: {6, 2} + The maximum number of digits after the decimal point. Default is ``6`` + when `zerotrim` is ``True`` and ``2`` otherwise. +zerotrim : bool, default: :rc:`formatter.zerotrim` + Whether to trim trailing decimal zeros. + +See also +-------- +ultraplot.constructor.Formatter +ultraplot.ticker.AutoFormatter""" + ... + + def __call__(self, x: Incomplete, pos: Incomplete=None) -> str: + """Convert number to a string. + +Parameters +---------- +x : float + The value. +pos : float, optional + The position.""" + ... + +class SigFigFormatter(mticker.Formatter): + """ + Format numbers by retaining the specified number of significant digits. + """ + + def __init__(self, sigfig: Incomplete=None, zerotrim: Incomplete=None, base: Incomplete=None) -> None: + """Parameters +---------- +sigfig : float, default: 3 + The number of significant digits. +zerotrim : bool, default: :rc:`formatter.zerotrim` + Whether to trim trailing decimal zeros. +base : float, default: 1 + The base unit for rounding. For example ``SigFigFormatter(2, base=5)`` + rounds to the nearest 5 with up to 2 digits (e.g., 87 --> 85, 8.7 --> 8.5). + +See also +-------- +ultraplot.constructor.Formatter +ultraplot.ticker.AutoFormatter""" + ... + + def __call__(self, x: Incomplete, pos: Incomplete=None) -> Incomplete: + """Convert number to a string. + +Parameters +---------- +x : float + The value. +pos : float, optional + The position.""" + ... + +class FracFormatter(mticker.Formatter): + """ + Format numbers as integers or integer fractions. Optionally express the + values relative to some constant like `numpy.pi`. + """ + + def __init__(self, symbol: Incomplete='', number: Incomplete=1) -> None: + """Parameters +---------- +symbol : str, default: '' + The constant symbol, e.g. ``r'$\\pi$'``. +number : float, default: 1 + The constant value, e.g. `numpy.pi`. + +Note +---- +The fractions shown by this formatter are resolved using the builtin +`fractions.Fraction` class and `fractions.Fraction.limit_denominator`. + +See also +-------- +ultraplot.constructor.Formatter +ultraplot.ticker.AutoFormatter""" + ... + + def __call__(self, x: Incomplete, pos: Incomplete=None) -> Incomplete: + """Convert number to a string. + +Parameters +---------- +x : float + The value. +pos : float, optional + The position.""" + ... + +class CFDatetimeFormatter(mticker.Formatter): + """ + Format dates using `cftime.datetime.strftime` format strings. + """ + + def __init__(self, fmt: Incomplete, calendar: Incomplete='standard', units: Incomplete='days since 2000-01-01') -> None: + """Parameters +---------- +fmt : str + The `strftime` format string. +calendar : str, default: 'standard' + The calendar for interpreting numeric tick values. +units : str, default: 'days since 2000-01-01' + The time units for interpreting numeric tick values.""" + ... + + def __call__(self, x: Incomplete, pos: Incomplete=None) -> Incomplete: + ... + +class AutoCFDatetimeFormatter(mticker.Formatter): + """Automatic formatter for `cftime.datetime` data.""" + + def __init__(self, locator: Incomplete, calendar: Incomplete, time_units: Incomplete=None) -> None: + ... + + def pick_format(self, resolution: Incomplete) -> Incomplete: + ... + + def __call__(self, x: Incomplete, pos: Incomplete=0) -> Incomplete: + ... + +class AutoCFDatetimeLocator(mticker.Locator): + """Determines tick locations when plotting `cftime.datetime` data.""" + if cftime: + real_world_calendars = cftime._cftime._calendars + else: + real_world_calendars = () + + def __init__(self, maxticks: Incomplete=None, calendar: Incomplete='standard', date_unit: Incomplete=None, minticks: Incomplete=3) -> None: + ... + + def set_params(self, maxticks: Incomplete=None, minticks: Incomplete=None, max_display_ticks: Incomplete=None) -> None: + """Set the parameters for the locator.""" + ... + + def compute_resolution(self, num1: Incomplete, num2: Incomplete, date1: Incomplete, date2: Incomplete) -> Incomplete: + """Returns the resolution of the dates. +Also updates self.calendar from date1 for consistency.""" + ... + + def __call__(self) -> Incomplete: + ... + + def tick_values(self, vmin: Incomplete, vmax: Incomplete) -> Incomplete: + ... + + def _safe_num2date(self, value: Incomplete, vmax: Incomplete=None) -> Incomplete: + """Safely converts numeric values to cftime.datetime objects. + +If a single value is provided, it converts and returns a single datetime object. +If both value (vmin) and vmax are provided, it converts and returns a tuple of +datetime objects (lower, upper). + +This helper is used to handle cases where the conversion might fail +due to invalid inputs or calendar-specific constraints. If the conversion +fails, it returns None or a tuple of Nones.""" + ... + + def _safe_create_datetime(self, year: Incomplete, month: Incomplete=1, day: Incomplete=1, hour: Incomplete=0, minute: Incomplete=0, second: Incomplete=0) -> Incomplete: + """Safely creates a cftime.datetime object with the given date and time components. + +This helper is used to handle cases where creating a datetime object might fail +due to invalid inputs (e.g., invalid dates in specific calendars). If the creation +fails, it returns None.""" + ... + + def _safe_daily_locator(self, vmin: Incomplete, vmax: Incomplete) -> Incomplete: + """Safely generates daily tick values using MaxNLocator. + +This helper is used to handle cases where the locator might fail +due to invalid input ranges or other issues. If the locator fails, +it returns None.""" + ... + +class _CartopyFormatter(object): + """ + Mixin class for cartopy formatters. + """ + + def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: + ... + + def __call__(self, value: Incomplete, pos: Incomplete=None) -> Incomplete: + ... + +class DegreeFormatter(_CartopyFormatter, _PlateCarreeFormatter): + """ + Formatter for longitude and latitude gridline labels. + Adapted from cartopy. + """ + + def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: + """Parameters +---------- +dms : bool, default: False + Locate the ticks on clean degree-minute-second intervals and format the + ticks with minutes and seconds instead of decimals.""" + ... + + def _apply_transform(self, value: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + ... + + def _hemisphere(self, value: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + ... + +class LongitudeFormatter(_CartopyFormatter, LongitudeFormatter): + """ + Format longitude gridline labels. Adapted from + `cartopy.mpl.ticker.LongitudeFormatter` with support for + proper centering based on lon0. + """ + + def __init__(self, lon0: Incomplete=0, *args: Incomplete, **kwargs: Incomplete) -> None: + """Parameters +---------- +lon0 : float, optional + Central longitude value to use for centering the map. + Labels will be adjusted relative to this value. +Parameters +---------- +dms : bool, default: False + Locate the ticks on clean degree-minute-second intervals and format the + ticks with minutes and seconds instead of decimals.""" + ... + +class LatitudeFormatter(_CartopyFormatter, LatitudeFormatter): + """ + Format latitude gridline labels. Adapted from + `cartopy.mpl.ticker.LatitudeFormatter`. + """ + + def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: + """Parameters +---------- +dms : bool, default: False + Locate the ticks on clean degree-minute-second intervals and format the + ticks with minutes and seconds instead of decimals.""" + ... + +class CFTimeConverter(mdates.DateConverter): + """ + Converter for cftime.datetime data. + """ + + @staticmethod + def axisinfo(unit: Incomplete, axis: Incomplete) -> Incomplete: + """Returns the :class:`~matplotlib.units.AxisInfo` for *unit*.""" + ... + + @classmethod + def default_units(cls, x: Incomplete, axis: Incomplete) -> Incomplete: + """Computes some units for the given data point.""" + ... + + @classmethod + def convert(cls, value: Incomplete, unit: Incomplete, axis: Incomplete) -> Incomplete: + """Converts value with :py:func:`cftime.date2num`.""" + ... diff --git a/ultraplot/ui.pyi b/ultraplot/ui.pyi new file mode 100644 index 000000000..0a57111b3 --- /dev/null +++ b/ultraplot/ui.pyi @@ -0,0 +1,635 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +The starting point for creating ultraplot figures. +""" +from _typeshed import Incomplete +import matplotlib.pyplot as plt +from . import axes as paxes +from . import figure as pfigure +from . import gridspec as pgridspec +from ._subplots import SubplotManager +from .internals import _not_none, _pop_params, _pop_props, _pop_rc, docstring, ic +__all__ = ['figure', 'subplot', 'subplots', 'show', 'close', 'switch_backend', 'ion', 'ioff', 'isinteractive'] +_pyplot_docstring = ... + +def _parse_figsize(kwargs: Incomplete) -> Incomplete: + """Translate `figsize` into ultraplot-specific `figwidth` and `figheight` keys.""" + ... + +def show(*args: Incomplete, **kwargs: Incomplete) -> None: + """Call `matplotlib.pyplot.show`. +This is included so you don't have to import `~matplotlib.pyplot`. + +Parameters +---------- +*args, **kwargs + Passed to `matplotlib.pyplot.show`.""" + ... + +def close(*args: Incomplete, **kwargs: Incomplete) -> None: + """Call `matplotlib.pyplot.close`. +This is included so you don't have to import `~matplotlib.pyplot`. + +Parameters +---------- +*args, **kwargs + Passed to `matplotlib.pyplot.close`.""" + ... + +def switch_backend(*args: Incomplete, **kwargs: Incomplete) -> None: + """Call `matplotlib.pyplot.switch_backend`. +This is included so you don't have to import `~matplotlib.pyplot`. + +Parameters +---------- +*args, **kwargs + Passed to `matplotlib.pyplot.switch_backend`.""" + ... + +def ion() -> Incomplete: + """Call `matplotlib.pyplot.ion`. +This is included so you don't have to import `~matplotlib.pyplot`.""" + ... + +def ioff() -> Incomplete: + """Call `matplotlib.pyplot.ioff`. +This is included so you don't have to import `~matplotlib.pyplot`.""" + ... + +def isinteractive() -> bool: + """Call `matplotlib.pyplot.isinteractive`. +This is included so you don't have to import `~matplotlib.pyplot`.""" + ... + +def figure(**kwargs: Incomplete) -> pfigure.Figure: + """Create an empty figure. Subplots can be subsequently added using +`~ultraplot.figure.Figure.add_subplot` or `~ultraplot.figure.Figure.subplots`. +This command is analogous to `matplotlib.pyplot.figure`. + +Parameters +---------- +refnum : int, optional + The reference subplot number. The `refwidth`, `refheight`, and `refaspect` + keyword args are applied to this subplot, and the aspect ratio is conserved + for this subplot in the `~Figure.auto_layout`. The default is the first + subplot created in the figure. +refaspect : float or 2-tuple of float, optional + The reference subplot aspect ratio. If scalar, this indicates the width + divided by height. If 2-tuple, this indicates the (width, height). Ignored + if both `figwidth` *and* `figheight` or both `refwidth` *and* `refheight` were + passed. The default value is ``1`` or the "data aspect ratio" if the latter + is explicitly fixed (as with `~ultraplot.axes.PlotAxes.imshow` plots and + `~ultraplot.axes.Axes.GeoAxes` projections; see :func:`~matplotlib.axes.Axes.set_aspect`). +refwidth, refheight : unit-spec, default: :rc:`subplots.refwidth` + The width, height of the reference subplot. + If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + Ignored if `figwidth`, `figheight`, or `figsize` was passed. If you + specify just one, `refaspect` will be respected. +ref, aspect, axwidth, axheight + Aliases for `refnum`, `refaspect`, `refwidth`, `refheight`. + *These may be deprecated in a future release.* +figwidth, figheight : unit-spec, optional + The figure width and height. Default behavior is to use `refwidth`. + If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + If you specify just one, `refaspect` will be respected. +width, height + Aliases for `figwidth`, `figheight`. +figsize : 2-tuple, optional + Tuple specifying the figure ``(width, height)``. +sharex, sharey, share : {0, False, 1, 'labels', 'labs', 2, 'limits', 'lims', 3, True, 4, 'all', 'auto'}, default: :rc:`subplots.share` + The axis sharing "level" for the *x* axis, *y* axis, or both + axes. Options are as follows: + + * ``0`` or ``False``: No axis sharing. This also sets the default `spanx` + and `spany` values to ``False``. + * ``1`` or ``'labels'`` or ``'labs'``: Only draw axis labels on the bottommost + row or leftmost column of subplots. Tick labels still appear on every subplot. + * ``2`` or ``'limits'`` or ``'lims'``: As above but force the axis limits, scales, + and tick locations to be identical. Tick labels still appear on every subplot. + * ``3`` or ``True``: As above but only show the tick labels on the bottommost + row and leftmost column of subplots. + * ``4`` or ``'all'``: As above but also share the axis limits, scales, and + tick locations between subplots not in the same row or column. + * ``'auto'``: Start from level ``3`` and only share axes that are compatible + (for example, mixed cartesian and polar axes are kept unshared). + + Explicit sharing levels (``0`` to ``4`` and aliases) still force sharing + attempts and can emit warnings for incompatible axes. + +spanx, spany, span : bool or {0, 1}, default: :rc:`subplots.span` + Whether to use "spanning" axis labels for the *x* axis, *y* axis, or both + axes. Default is ``False`` if `sharex`, `sharey`, or `share` are ``0`` or + ``False``. When ``True``, a single, centered axis label is used for all axes + with bottom and left edges in the same row or column. This can considerably + redundancy in your figure. "Spanning" labels integrate with "shared" axes. For + example, for a 3-row, 3-column figure, with ``sharey > 1`` and ``spany == True``, + your figure will have 1 y axis label instead of 9 y axis labels. +alignx, aligny, align : bool or {0, 1}, default: :rc:`subplots.align` + Whether to `"align" axis labels `__ + for the *x* axis, *y* axis, or both axes. Aligned labels always appear in the same + row or column. This is ignored if `spanx`, `spany`, or `span` are ``True``. +left, right, top, bottom : unit-spec, default: None + The fixed space between the subplots and the figure edge. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If ``None``, the space is determined automatically based on the tick and + label settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + passed to the figure, the space is determined by the tight layout algorithm. +wspace, hspace, space : unit-spec, default: None + The fixed space between grid columns, rows, or both. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If ``None``, the space is determined automatically based on the font size and axis + sharing settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + passed to the figure, the space is determined by the tight layout algorithm. +tight : bool, default: :rc`subplots.tight` + Whether automatic calls to `~Figure.auto_layout` should include + :ref:`tight layout adjustments `. If you manually specified a spacing + in the call to `~ultraplot.ui.subplots`, it will be used to override the tight + layout spacing. For example, with ``left=1``, the left margin is set to 1 + em-width, while the remaining margin widths are calculated automatically. +wequal, hequal, equal : bool, default: :rc:`subplots.equalspace` + Whether to make the tight layout algorithm apply equal spacing + between columns, rows, or both. +wgroup, hgroup, group : bool, default: :rc:`subplots.groupspace` + Whether to make the tight layout algorithm just consider spaces between + adjacent subplots instead of entire columns and rows of subplots. +outerpad : unit-spec, default: :rc:`subplots.outerpad` + The scalar tight layout padding around the left, right, top, bottom figure edges. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +innerpad : unit-spec, default: :rc:`subplots.innerpad` + The scalar tight layout padding between columns and rows. Synonymous with `pad`. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +panelpad : unit-spec, default: :rc:`subplots.panelpad` + The scalar tight layout padding between subplots and their panels, + colorbars, and legends and between "stacks" of these objects. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +journal : str, optional + String corresponding to an academic journal standard used to control the figure + width `figwidth` and, if specified, the figure height `figheight`. See the below + table. Feel free to add to this table by submitting a pull request. + + .. _journal_table: + + =========== ==================== =============================================================================== + Key Size description Organization + =========== ==================== =============================================================================== + ``'aaas1'`` 1-column `American Association for the Advancement of Science `_ (e.g. *Science*) + ``'aaas2'`` 2-column ” + ``'agu1'`` 1-column `American Geophysical Union `_ + ``'agu2'`` 2-column ” + ``'agu3'`` full height 1-column ” + ``'agu4'`` full height 2-column ” + ``'ams1'`` 1-column `American Meteorological Society `_ + ``'ams2'`` small 2-column ” + ``'ams3'`` medium 2-column ” + ``'ams4'`` full 2-column ” + ``'cop1'`` 1-column `Copernicus Publications `_ (e.g. *The Cryosphere*, *Geoscientific Model Development*) + ``'cop2'`` 2-column ” + ``'nat1'`` 1-column `Nature Research `_ + ``'nat2'`` 2-column ” + ``'pnas1'`` 1-column `Proceedings of the National Academy of Sciences `_ + ``'pnas2'`` 2-column ” + ``'pnas3'`` landscape page ” + =========== ==================== =============================================================================== + + .. _aaas: https://www.sciencemag.org/authors/instructions-preparing-initial-manuscript + .. _agu: https://www.agu.org/Publish-with-AGU/Publish/Author-Resources/Graphic-Requirements + .. _ams: https://www.ametsoc.org/ams/index.cfm/publications/authors/journal-and-bams-authors/figure-information-for-authors/ + .. _cop: https://publications.copernicus.org/for_authors/manuscript_preparation.html#figurestables + .. _nat: https://www.nature.com/nature/for-authors/formatting-guide + .. _pnas: https://www.pnas.org/page/authors/format + +Other parameters +---------------- +**kwargs + Passed to `ultraplot.figure.Figure.format`. + +See also +-------- +ultraplot.ui.subplots +ultraplot.figure.Figure.add_subplot +ultraplot.figure.Figure.subplots +ultraplot.figure.Figure +matplotlib.figure.Figure""" + ... + +def subplot(**kwargs: Incomplete) -> tuple[pfigure.Figure, paxes.Axes]: + """Return a figure and a single subplot. +This command is analogous to `matplotlib.pyplot.subplot`, +except the figure instance is also returned. + +Other parameters +---------------- +refnum : int, optional + The reference subplot number. The `refwidth`, `refheight`, and `refaspect` + keyword args are applied to this subplot, and the aspect ratio is conserved + for this subplot in the `~Figure.auto_layout`. The default is the first + subplot created in the figure. +refaspect : float or 2-tuple of float, optional + The reference subplot aspect ratio. If scalar, this indicates the width + divided by height. If 2-tuple, this indicates the (width, height). Ignored + if both `figwidth` *and* `figheight` or both `refwidth` *and* `refheight` were + passed. The default value is ``1`` or the "data aspect ratio" if the latter + is explicitly fixed (as with `~ultraplot.axes.PlotAxes.imshow` plots and + `~ultraplot.axes.Axes.GeoAxes` projections; see :func:`~matplotlib.axes.Axes.set_aspect`). +refwidth, refheight : unit-spec, default: :rc:`subplots.refwidth` + The width, height of the reference subplot. + If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + Ignored if `figwidth`, `figheight`, or `figsize` was passed. If you + specify just one, `refaspect` will be respected. +ref, aspect, axwidth, axheight + Aliases for `refnum`, `refaspect`, `refwidth`, `refheight`. + *These may be deprecated in a future release.* +figwidth, figheight : unit-spec, optional + The figure width and height. Default behavior is to use `refwidth`. + If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + If you specify just one, `refaspect` will be respected. +width, height + Aliases for `figwidth`, `figheight`. +figsize : 2-tuple, optional + Tuple specifying the figure ``(width, height)``. +sharex, sharey, share : {0, False, 1, 'labels', 'labs', 2, 'limits', 'lims', 3, True, 4, 'all', 'auto'}, default: :rc:`subplots.share` + The axis sharing "level" for the *x* axis, *y* axis, or both + axes. Options are as follows: + + * ``0`` or ``False``: No axis sharing. This also sets the default `spanx` + and `spany` values to ``False``. + * ``1`` or ``'labels'`` or ``'labs'``: Only draw axis labels on the bottommost + row or leftmost column of subplots. Tick labels still appear on every subplot. + * ``2`` or ``'limits'`` or ``'lims'``: As above but force the axis limits, scales, + and tick locations to be identical. Tick labels still appear on every subplot. + * ``3`` or ``True``: As above but only show the tick labels on the bottommost + row and leftmost column of subplots. + * ``4`` or ``'all'``: As above but also share the axis limits, scales, and + tick locations between subplots not in the same row or column. + * ``'auto'``: Start from level ``3`` and only share axes that are compatible + (for example, mixed cartesian and polar axes are kept unshared). + + Explicit sharing levels (``0`` to ``4`` and aliases) still force sharing + attempts and can emit warnings for incompatible axes. + +spanx, spany, span : bool or {0, 1}, default: :rc:`subplots.span` + Whether to use "spanning" axis labels for the *x* axis, *y* axis, or both + axes. Default is ``False`` if `sharex`, `sharey`, or `share` are ``0`` or + ``False``. When ``True``, a single, centered axis label is used for all axes + with bottom and left edges in the same row or column. This can considerably + redundancy in your figure. "Spanning" labels integrate with "shared" axes. For + example, for a 3-row, 3-column figure, with ``sharey > 1`` and ``spany == True``, + your figure will have 1 y axis label instead of 9 y axis labels. +alignx, aligny, align : bool or {0, 1}, default: :rc:`subplots.align` + Whether to `"align" axis labels `__ + for the *x* axis, *y* axis, or both axes. Aligned labels always appear in the same + row or column. This is ignored if `spanx`, `spany`, or `span` are ``True``. +left, right, top, bottom : unit-spec, default: None + The fixed space between the subplots and the figure edge. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If ``None``, the space is determined automatically based on the tick and + label settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + passed to the figure, the space is determined by the tight layout algorithm. +wspace, hspace, space : unit-spec, default: None + The fixed space between grid columns, rows, or both. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If ``None``, the space is determined automatically based on the font size and axis + sharing settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + passed to the figure, the space is determined by the tight layout algorithm. +tight : bool, default: :rc`subplots.tight` + Whether automatic calls to `~Figure.auto_layout` should include + :ref:`tight layout adjustments `. If you manually specified a spacing + in the call to `~ultraplot.ui.subplots`, it will be used to override the tight + layout spacing. For example, with ``left=1``, the left margin is set to 1 + em-width, while the remaining margin widths are calculated automatically. +wequal, hequal, equal : bool, default: :rc:`subplots.equalspace` + Whether to make the tight layout algorithm apply equal spacing + between columns, rows, or both. +wgroup, hgroup, group : bool, default: :rc:`subplots.groupspace` + Whether to make the tight layout algorithm just consider spaces between + adjacent subplots instead of entire columns and rows of subplots. +outerpad : unit-spec, default: :rc:`subplots.outerpad` + The scalar tight layout padding around the left, right, top, bottom figure edges. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +innerpad : unit-spec, default: :rc:`subplots.innerpad` + The scalar tight layout padding between columns and rows. Synonymous with `pad`. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +panelpad : unit-spec, default: :rc:`subplots.panelpad` + The scalar tight layout padding between subplots and their panels, + colorbars, and legends and between "stacks" of these objects. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +journal : str, optional + String corresponding to an academic journal standard used to control the figure + width `figwidth` and, if specified, the figure height `figheight`. See the below + table. Feel free to add to this table by submitting a pull request. + + .. _journal_table: + + =========== ==================== =============================================================================== + Key Size description Organization + =========== ==================== =============================================================================== + ``'aaas1'`` 1-column `American Association for the Advancement of Science `_ (e.g. *Science*) + ``'aaas2'`` 2-column ” + ``'agu1'`` 1-column `American Geophysical Union `_ + ``'agu2'`` 2-column ” + ``'agu3'`` full height 1-column ” + ``'agu4'`` full height 2-column ” + ``'ams1'`` 1-column `American Meteorological Society `_ + ``'ams2'`` small 2-column ” + ``'ams3'`` medium 2-column ” + ``'ams4'`` full 2-column ” + ``'cop1'`` 1-column `Copernicus Publications `_ (e.g. *The Cryosphere*, *Geoscientific Model Development*) + ``'cop2'`` 2-column ” + ``'nat1'`` 1-column `Nature Research `_ + ``'nat2'`` 2-column ” + ``'pnas1'`` 1-column `Proceedings of the National Academy of Sciences `_ + ``'pnas2'`` 2-column ” + ``'pnas3'`` landscape page ” + =========== ==================== =============================================================================== + + .. _aaas: https://www.sciencemag.org/authors/instructions-preparing-initial-manuscript + .. _agu: https://www.agu.org/Publish-with-AGU/Publish/Author-Resources/Graphic-Requirements + .. _ams: https://www.ametsoc.org/ams/index.cfm/publications/authors/journal-and-bams-authors/figure-information-for-authors/ + .. _cop: https://publications.copernicus.org/for_authors/manuscript_preparation.html#figurestables + .. _nat: https://www.nature.com/nature/for-authors/formatting-guide + .. _pnas: https://www.pnas.org/page/authors/format +**kwargs + Passed to `ultraplot.figure.Figure.format` or the + projection-specific ``format`` command for the axes. + +Returns +------- +fig : `ultraplot.figure.Figure` + The figure instance. +ax : `ultraplot.axes.Axes` + The axes instance. + +See also +-------- +ultraplot.ui.figure +ultraplot.figure.Figure.subplot +ultraplot.figure.Figure +matplotlib.figure.Figure""" + ... + +def subplots(*args: Incomplete, **kwargs: Incomplete) -> tuple[pfigure.Figure, pgridspec.SubplotGrid]: + """Return a figure and an arbitrary grid of subplots. +This command is analogous to `matplotlib.pyplot.subplots`, +except the subplots are stored in a :class:`~ultraplot.gridspec.SubplotGrid`. + +Parameters +---------- +array : `ultraplot.gridspec.GridSpec` or array-like of int, optional + The subplot grid specifier. If a :class:`~ultraplot.gridspec.GridSpec`, one subplot is + drawn for each unique :class:`~ultraplot.gridspec.GridSpec` slot. If a 2D array of integers, + one subplot is drawn for each unique integer in the array. Think of this array as + a "picture" of the subplot grid -- for example, the array ``[[1, 1], [2, 3]]`` + creates one long subplot in the top row, two smaller subplots in the bottom row. + Integers must range from 1 to the number of plots, and ``0`` indicates an + empty space -- for example, ``[[1, 1, 1], [2, 0, 3]]`` creates one long subplot + in the top row with two subplots in the bottom row separated by a space. +nrows, ncols : int, default: 1 + The number of rows and columns in the subplot grid. Ignored + if `array` was passed. Use these arguments for simple subplot grids. +order : {'C', 'F'}, default: 'C' + Whether subplots are numbered in column-major (``'C'``) or row-major (``'F'``) + order. Analogous to `numpy.array` ordering. This controls the order that + subplots appear in the `SubplotGrid` returned by this function, and the order + of subplot a-b-c labels (see `~ultraplot.axes.Axes.format`). +proj, projection : +str, `cartopy.crs.Projection`, or `~mpl_toolkits.basemap.Basemap`, optional + The map projection specification(s). If ``'cart'`` or ``'cartesian'`` + (the default), a `~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, + a :class:`~ultraplot.axes.PolarAxes` is created. Otherwise, the argument is + interpreted by `~ultraplot.constructor.Proj`, and the result is used + to make a `~ultraplot.axes.GeoAxes` (in this case the argument can be + a `cartopy.crs.Projection` instance, a `~mpl_toolkits.basemap.Basemap` + instance, or a projection name listed in :ref:`this table `). + + To use different projections for different subplots, you have + two options: + + * Pass a *list* of projection specifications, one for each subplot. + For example, ``uplt.subplots(ncols=2, proj=('cart', 'robin'))``. + * Pass a *dictionary* of projection specifications, where the + keys are integers or tuples of integers that indicate the projection + to use for the corresponding subplot number(s). If a key is not + provided, the default projection ``'cartesian'`` is used. For example, + ``uplt.subplots(ncols=4, proj={2: 'cyl', (3, 4): 'stere'})`` creates + a figure with a default Cartesian axes for the first subplot, a Mercator + projection for the second subplot, and a Stereographic projection + for the third and fourth subplots. + +proj_kw, projection_kw : dict-like, optional + Keyword arguments passed to `~mpl_toolkits.basemap.Basemap` or + cartopy `~cartopy.crs.Projection` classes on instantiation. + If dictionary of properties, applies globally. If list or dictionary of + dictionaries, applies to specific subplots, as with `proj`. For example, + ``uplt.subplots(ncols=2, proj='cyl', proj_kw=({'lon_0': 0}, {'lon_0': 180})`` + centers the projection in the left subplot on the prime meridian and in the + right subplot on the international dateline. +backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` + Whether to use `~mpl_toolkits.basemap.Basemap` or + `~cartopy.crs.Projection` for map projections. + + .. deprecated:: 3.0.0 + The ``'basemap'`` backend is deprecated and may be removed in a + future release. Please use the ``'cartopy'`` backend instead. + If string, applies to all subplots. If list or dict, applies to specific + subplots, as with `proj`. +left, right, top, bottom : unit-spec, default: None + The fixed space between the subplots and the figure edge. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If ``None``, the space is determined automatically based on the tick and + label settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + passed to the figure, the space is determined by the tight layout algorithm. +wspace, hspace, space : unit-spec or sequence, default: None + The fixed space between grid columns, rows, and both, respectively. If + float, string, or ``None``, this value is expanded into lists of length + ``ncols - 1`` (for `wspace`) or length ``nrows - 1`` (for `hspace`). If + a sequence, its length must match these lengths. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + + For elements equal to ``None``, the space is determined automatically based + on the tick and label settings. If :rcraw:`subplots.tight` is ``True`` or + ``tight=True`` was passed to the figure, the space is determined by the tight + layout algorithm. For example, ``subplots(ncols=3, tight=True, wspace=(2, None))`` + fixes the space between columns 1 and 2 but lets the tight layout algorithm + determine the space between columns 2 and 3. +wratios, hratios : float or sequence, optional + Passed to :class:`~ultraplot.gridspec.GridSpec`, denotes the width and height + ratios for the subplot grid. Length of `wratios` must match the number + of columns, and length of `hratios` must match the number of rows. +width_ratios, height_ratios + Aliases for `wratios`, `hratios`. Included for + consistency with `matplotlib.gridspec.GridSpec`. +wpad, hpad, pad : unit-spec or sequence, optional + The tight layout padding between columns, rows, and both, respectively. + Unlike ``space``, these control the padding between subplot content + (including text, ticks, etc.) rather than subplot edges. As with + ``space``, these can be scalars or arrays optionally containing ``None``. + For elements equal to ``None``, the default is `innerpad`. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +wequal, hequal, equal : bool, default: :rc:`subplots.equalspace` + Whether to make the tight layout algorithm apply equal spacing + between columns, rows, or both. +wgroup, hgroup, group : bool, default: :rc:`subplots.groupspace` + Whether to make the tight layout algorithm just consider spaces between + adjacent subplots instead of entire columns and rows of subplots. +outerpad : unit-spec, default: :rc:`subplots.outerpad` + The scalar tight layout padding around the left, right, top, bottom figure edges. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +innerpad : unit-spec, default: :rc:`subplots.innerpad` + The scalar tight layout padding between columns and rows. Synonymous with `pad`. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +panelpad : unit-spec, default: :rc:`subplots.panelpad` + The scalar tight layout padding between subplots and their panels, + colorbars, and legends and between "stacks" of these objects. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + +Other parameters +---------------- +refnum : int, optional + The reference subplot number. The `refwidth`, `refheight`, and `refaspect` + keyword args are applied to this subplot, and the aspect ratio is conserved + for this subplot in the `~Figure.auto_layout`. The default is the first + subplot created in the figure. +refaspect : float or 2-tuple of float, optional + The reference subplot aspect ratio. If scalar, this indicates the width + divided by height. If 2-tuple, this indicates the (width, height). Ignored + if both `figwidth` *and* `figheight` or both `refwidth` *and* `refheight` were + passed. The default value is ``1`` or the "data aspect ratio" if the latter + is explicitly fixed (as with `~ultraplot.axes.PlotAxes.imshow` plots and + `~ultraplot.axes.Axes.GeoAxes` projections; see :func:`~matplotlib.axes.Axes.set_aspect`). +refwidth, refheight : unit-spec, default: :rc:`subplots.refwidth` + The width, height of the reference subplot. + If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + Ignored if `figwidth`, `figheight`, or `figsize` was passed. If you + specify just one, `refaspect` will be respected. +ref, aspect, axwidth, axheight + Aliases for `refnum`, `refaspect`, `refwidth`, `refheight`. + *These may be deprecated in a future release.* +figwidth, figheight : unit-spec, optional + The figure width and height. Default behavior is to use `refwidth`. + If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + If you specify just one, `refaspect` will be respected. +width, height + Aliases for `figwidth`, `figheight`. +figsize : 2-tuple, optional + Tuple specifying the figure ``(width, height)``. +sharex, sharey, share : {0, False, 1, 'labels', 'labs', 2, 'limits', 'lims', 3, True, 4, 'all', 'auto'}, default: :rc:`subplots.share` + The axis sharing "level" for the *x* axis, *y* axis, or both + axes. Options are as follows: + + * ``0`` or ``False``: No axis sharing. This also sets the default `spanx` + and `spany` values to ``False``. + * ``1`` or ``'labels'`` or ``'labs'``: Only draw axis labels on the bottommost + row or leftmost column of subplots. Tick labels still appear on every subplot. + * ``2`` or ``'limits'`` or ``'lims'``: As above but force the axis limits, scales, + and tick locations to be identical. Tick labels still appear on every subplot. + * ``3`` or ``True``: As above but only show the tick labels on the bottommost + row and leftmost column of subplots. + * ``4`` or ``'all'``: As above but also share the axis limits, scales, and + tick locations between subplots not in the same row or column. + * ``'auto'``: Start from level ``3`` and only share axes that are compatible + (for example, mixed cartesian and polar axes are kept unshared). + + Explicit sharing levels (``0`` to ``4`` and aliases) still force sharing + attempts and can emit warnings for incompatible axes. + +spanx, spany, span : bool or {0, 1}, default: :rc:`subplots.span` + Whether to use "spanning" axis labels for the *x* axis, *y* axis, or both + axes. Default is ``False`` if `sharex`, `sharey`, or `share` are ``0`` or + ``False``. When ``True``, a single, centered axis label is used for all axes + with bottom and left edges in the same row or column. This can considerably + redundancy in your figure. "Spanning" labels integrate with "shared" axes. For + example, for a 3-row, 3-column figure, with ``sharey > 1`` and ``spany == True``, + your figure will have 1 y axis label instead of 9 y axis labels. +alignx, aligny, align : bool or {0, 1}, default: :rc:`subplots.align` + Whether to `"align" axis labels `__ + for the *x* axis, *y* axis, or both axes. Aligned labels always appear in the same + row or column. This is ignored if `spanx`, `spany`, or `span` are ``True``. +left, right, top, bottom : unit-spec, default: None + The fixed space between the subplots and the figure edge. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If ``None``, the space is determined automatically based on the tick and + label settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + passed to the figure, the space is determined by the tight layout algorithm. +wspace, hspace, space : unit-spec, default: None + The fixed space between grid columns, rows, or both. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If ``None``, the space is determined automatically based on the font size and axis + sharing settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + passed to the figure, the space is determined by the tight layout algorithm. +tight : bool, default: :rc`subplots.tight` + Whether automatic calls to `~Figure.auto_layout` should include + :ref:`tight layout adjustments `. If you manually specified a spacing + in the call to `~ultraplot.ui.subplots`, it will be used to override the tight + layout spacing. For example, with ``left=1``, the left margin is set to 1 + em-width, while the remaining margin widths are calculated automatically. +wequal, hequal, equal : bool, default: :rc:`subplots.equalspace` + Whether to make the tight layout algorithm apply equal spacing + between columns, rows, or both. +wgroup, hgroup, group : bool, default: :rc:`subplots.groupspace` + Whether to make the tight layout algorithm just consider spaces between + adjacent subplots instead of entire columns and rows of subplots. +outerpad : unit-spec, default: :rc:`subplots.outerpad` + The scalar tight layout padding around the left, right, top, bottom figure edges. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +innerpad : unit-spec, default: :rc:`subplots.innerpad` + The scalar tight layout padding between columns and rows. Synonymous with `pad`. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +panelpad : unit-spec, default: :rc:`subplots.panelpad` + The scalar tight layout padding between subplots and their panels, + colorbars, and legends and between "stacks" of these objects. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +journal : str, optional + String corresponding to an academic journal standard used to control the figure + width `figwidth` and, if specified, the figure height `figheight`. See the below + table. Feel free to add to this table by submitting a pull request. + + .. _journal_table: + + =========== ==================== =============================================================================== + Key Size description Organization + =========== ==================== =============================================================================== + ``'aaas1'`` 1-column `American Association for the Advancement of Science `_ (e.g. *Science*) + ``'aaas2'`` 2-column ” + ``'agu1'`` 1-column `American Geophysical Union `_ + ``'agu2'`` 2-column ” + ``'agu3'`` full height 1-column ” + ``'agu4'`` full height 2-column ” + ``'ams1'`` 1-column `American Meteorological Society `_ + ``'ams2'`` small 2-column ” + ``'ams3'`` medium 2-column ” + ``'ams4'`` full 2-column ” + ``'cop1'`` 1-column `Copernicus Publications `_ (e.g. *The Cryosphere*, *Geoscientific Model Development*) + ``'cop2'`` 2-column ” + ``'nat1'`` 1-column `Nature Research `_ + ``'nat2'`` 2-column ” + ``'pnas1'`` 1-column `Proceedings of the National Academy of Sciences `_ + ``'pnas2'`` 2-column ” + ``'pnas3'`` landscape page ” + =========== ==================== =============================================================================== + + .. _aaas: https://www.sciencemag.org/authors/instructions-preparing-initial-manuscript + .. _agu: https://www.agu.org/Publish-with-AGU/Publish/Author-Resources/Graphic-Requirements + .. _ams: https://www.ametsoc.org/ams/index.cfm/publications/authors/journal-and-bams-authors/figure-information-for-authors/ + .. _cop: https://publications.copernicus.org/for_authors/manuscript_preparation.html#figurestables + .. _nat: https://www.nature.com/nature/for-authors/formatting-guide + .. _pnas: https://www.pnas.org/page/authors/format +**kwargs + Passed to `ultraplot.figure.Figure.format` or the + projection-specific ``format`` command for each axes. + +Returns +------- +fig : `ultraplot.figure.Figure` + The figure instance. +axs : `ultraplot.gridspec.SubplotGrid` + The axes instances stored in a :class:`~ultraplot.gridspec.SubplotGrid`. + +See also +-------- +ultraplot.ui.figure +ultraplot.figure.Figure.subplots +ultraplot.gridspec.SubplotGrid +ultraplot.figure.Figure +matplotlib.figure.Figure""" + ... diff --git a/ultraplot/ultralayout.pyi b/ultraplot/ultralayout.pyi new file mode 100644 index 000000000..ab1eceedf --- /dev/null +++ b/ultraplot/ultralayout.pyi @@ -0,0 +1,157 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +UltraLayout: Advanced constraint-based layout system for non-orthogonal subplot arrangements. + +This module provides UltraPlot's constraint-based layout computation for subplot grids +that don't follow simple orthogonal patterns, such as [[1, 1, 2, 2], [0, 3, 3, 0]] +where subplot 3 should be nicely centered between subplots 1 and 2. +""" +from _typeshed import Incomplete +from typing import Dict, List, Optional, Tuple +import numpy as np +try: + from kiwisolver import Solver, Variable + KIWI_AVAILABLE = True +except ImportError: + KIWI_AVAILABLE = False + Variable = None + Solver = None +__all__ = ['ColorbarLayoutSolver', 'UltraLayoutSolver', 'compute_ultra_positions', 'get_grid_positions_ultra', 'is_orthogonal_layout'] + +def is_orthogonal_layout(array: np.ndarray) -> bool: + """Check if a subplot array follows an orthogonal (grid-aligned) layout. + +An orthogonal layout is one where every subplot's edges align with +other subplots' edges, forming a simple grid. + +Parameters +---------- +array : np.ndarray + 2D array of subplot numbers (with 0 for empty cells) + +Returns +------- +bool + True if layout is orthogonal, False otherwise""" + ... + +class UltraLayoutSolver: + """ + UltraLayout: Constraint-based layout solver using kiwisolver for subplot positioning. + + This solver computes aesthetically pleasing positions for subplots in + non-orthogonal arrangements by using constraint satisfaction, providing + a superior layout experience for complex subplot arrangements. + """ + + def __init__(self, array: np.ndarray, figwidth: float=10.0, figheight: float=8.0, wspace: Optional[List[float]]=None, hspace: Optional[List[float]]=None, left: float=0.125, right: float=0.125, top: float=0.125, bottom: float=0.125, wratios: Optional[List[float]]=None, hratios: Optional[List[float]]=None, wpanels: Optional[List[bool]]=None, hpanels: Optional[List[bool]]=None) -> None: + """Initialize the UltraLayout solver. + +Parameters +---------- +array : np.ndarray + 2D array of subplot numbers (with 0 for empty cells) +figwidth, figheight : float + Figure dimensions in inches +wspace, hspace : list of float, optional + Spacing between columns and rows in inches +left, right, top, bottom : float + Margins in inches +wratios, hratios : list of float, optional + Width and height ratios for columns and rows +wpanels, hpanels : list of bool, optional + Flags indicating panel columns or rows with fixed widths/heights.""" + ... + + def _setup_variables(self) -> None: + """Create kiwisolver variables for all grid lines.""" + ... + + def _setup_constraints(self) -> None: + """Set up all constraints for the layout.""" + ... + + def solve(self) -> Dict[int, Tuple[float, float, float, float]]: + """Solve the constraint system and return subplot positions. + +Returns +------- +dict + Dictionary mapping subplot numbers to (left, bottom, width, height) + in figure-relative coordinates [0, 1]""" + ... + +class ColorbarLayoutSolver: + """ + Constraint-based solver for inset colorbar frame alignment. + """ + + def __init__(self, loc: str, cb_width: float, cb_height: float, pad_left: float, pad_right: float, pad_bottom: float, pad_top: float) -> None: + ... + + def _setup_constraints(self) -> None: + ... + + def solve(self) -> Dict[str, Tuple[float, float, float, float]]: + """Solve the constraint system and return inset and frame bounds.""" + ... + +def compute_ultra_positions(array: np.ndarray, figwidth: float=10.0, figheight: float=8.0, wspace: Optional[List[float]]=None, hspace: Optional[List[float]]=None, left: float=0.125, right: float=0.125, top: float=0.125, bottom: float=0.125, wratios: Optional[List[float]]=None, hratios: Optional[List[float]]=None, wpanels: Optional[List[bool]]=None, hpanels: Optional[List[bool]]=None) -> Dict[int, Tuple[float, float, float, float]]: + """Compute subplot positions using UltraLayout for non-orthogonal layouts. + +Parameters +---------- +array : np.ndarray + 2D array of subplot numbers (with 0 for empty cells) +figwidth, figheight : float + Figure dimensions in inches +wspace, hspace : list of float, optional + Spacing between columns and rows in inches +left, right, top, bottom : float + Margins in inches +wratios, hratios : list of float, optional + Width and height ratios for columns and rows +wpanels, hpanels : list of bool, optional + Flags indicating panel columns or rows with fixed widths/heights. + +Returns +------- +dict + Dictionary mapping subplot numbers to (left, bottom, width, height) + in figure-relative coordinates [0, 1] + +Examples +-------- +>>> array = np.array([[1, 1, 2, 2], [0, 3, 3, 0]]) +>>> positions = compute_ultra_positions(array) +>>> positions[3] # Position of subplot 3 +(0.25, 0.125, 0.5, 0.35)""" + ... + +def get_grid_positions_ultra(array: np.ndarray, figwidth: float, figheight: float, wspace: Optional[List[float]]=None, hspace: Optional[List[float]]=None, left: float=0.125, right: float=0.125, top: float=0.125, bottom: float=0.125, wratios: Optional[List[float]]=None, hratios: Optional[List[float]]=None, wpanels: Optional[List[bool]]=None, hpanels: Optional[List[bool]]=None) -> Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]: + """Get grid line positions using UltraLayout. + +This returns arrays of grid line positions similar to GridSpec.get_grid_positions(), +but computed using UltraLayout's constraint satisfaction for better handling of non-orthogonal layouts. + +Parameters +---------- +array : np.ndarray + 2D array of subplot numbers +figwidth, figheight : float + Figure dimensions in inches +wspace, hspace : list of float, optional + Spacing between columns and rows in inches +left, right, top, bottom : float + Margins in inches +wratios, hratios : list of float, optional + Width and height ratios for columns and rows +wpanels, hpanels : list of bool, optional + Flags indicating panel columns or rows with fixed widths/heights. + +Returns +------- +bottoms, tops, lefts, rights : np.ndarray + Arrays of grid line positions for each cell""" + ... diff --git a/ultraplot/utils.pyi b/ultraplot/utils.pyi new file mode 100644 index 000000000..d4e9fdbae --- /dev/null +++ b/ultraplot/utils.pyi @@ -0,0 +1,630 @@ +# @generated by tools/generate_stubs.py; do not edit +# fmt: off +""" +Various tools that may be useful while making plots. +""" +from _typeshed import Incomplete +import functools +import re +from numbers import Integral, Real +from dataclasses import dataclass +from typing import Generator +import matplotlib.colors as mcolors +import matplotlib.font_manager as mfonts +from matplotlib.gridspec import GridSpec +import numpy as np +from matplotlib import rcParams as rc_matplotlib +from .externals import hsluv +from .internals import ic +from .internals import _not_none, docstring, warnings +__all__ = ['arange', 'edges', 'edges2d', 'get_colors', 'set_hue', 'set_saturation', 'set_luminance', 'set_alpha', 'shift_hue', 'scale_saturation', 'scale_luminance', 'to_hex', 'to_rgb', 'to_xyz', 'to_rgba', 'to_xyza', 'units'] +UNIT_REGEX = re.compile('\\A([-+]?[0-9._]+(?:[eE][-+]?[0-9_]+)?)(.*)\\Z') +UNIT_DICT = {'in': 1.0, 'ft': 12.0, 'yd': 36.0, 'm': 39.37, 'dm': 3.937, 'cm': 0.3937, 'mm': 0.03937, 'pc': 1 / 6.0, 'pt': 1 / 72.0, 'ly': 3.725e+17} +_docstring_rgba = '\ncolor : color-spec\n The color. Sanitized with `to_rgba`.\n' +_docstring_to_rgb = "\ncolor : color-spec\n The color. Can be a 3-tuple or 4-tuple of channel values, a hex\n string, a registered color name, a cycle color like ``'C0'``, or\n a 2-tuple colormap coordinate specification like ``('magma', 0.5)``\n (see `~ultraplot.colors.ColorDatabase` for details).\n\n If `space` is ``'rgb'``, this is a tuple of RGB values, and any\n channels are larger than ``2``, the channels are assumed to be\n on the ``0`` to ``255`` scale and are divided by ``255``.\nspace : {'rgb', 'hsv', 'hcl', 'hpl', 'hsl'}, optional\n The colorspace for the input channel values. Ignored unless `color`\n is a tuple of numbers.\ncycle : str, default: :rcraw:`cycle`\n The registered color cycle name used to interpret colors that\n look like ``'C0'``, ``'C1'``, etc.\nclip : bool, default: True\n Whether to clip channel values into the valid ``0`` to ``1`` range.\n Setting this to ``False`` can result in invalid colors.\n" +_docstring_space = "\nspace : {'hcl', 'hpl', 'hsl', 'hsv'}, optional\n The hue-saturation-luminance-like colorspace used to transform the color.\n Default is the strictly perceptually uniform colorspace ``'hcl'``.\n" +_docstring_hex = '\ncolor : str\n An 8-digit HEX string indicating the\n red, green, blue, and alpha channel values.\n' + +def _keep_units(func: Incomplete) -> Incomplete: + """Very simple decorator to strip and re-apply the same units.""" + ... + +def arange(min_: Incomplete, *args: Incomplete) -> Incomplete: + """Identical to `numpy.arange` but with inclusive endpoints. For example, +``uplt.arange(2, 4)`` returns the numpy array ``[2, 3, 4]`` instead of +``[2, 3]``. This is useful for generating lists of tick locations or +colormap levels, e.g. ``ax.format(xlocator=uplt.arange(0, 10))`` +or ``ax.pcolor(levels=uplt.arange(0, 10))``. + +Parameters +---------- +*args : float + If three arguments are passed, these are the minimum, maximum, and step + size. If fewer than three arguments are passed, the step size is ``1``. + If one argument is passed, this is the maximum, and the minimum is ``0``. + +Returns +------- +numpy.ndarray + Array of points. + +See also +-------- +numpy.arange +ultraplot.constructor.Locator +ultraplot.axes.CartesianAxes.format +ultraplot.axes.PolarAxes.format +ultraplot.axes.GeoAxes.format +ultraplot.axes.Axes.colorbar +ultraplot.axes.PlotAxes""" + ... + +def edges(z: Incomplete, axis: Incomplete=-1) -> Incomplete: + """Calculate the approximate "edge" values along an axis given "center" values. +The size of the axis is increased by one. This is used internally to calculate +coordinate edges when you supply coordinate centers to pseudocolor commands. + +Parameters +---------- +z : array-like + An array of any shape. +axis : int, optional + The axis along which "edges" are calculated. The size of this + axis will be increased by one. + +Returns +------- +numpy.ndarray + Array of "edge" coordinates. + +See also +-------- +edges2d +ultraplot.axes.PlotAxes.pcolor +ultraplot.axes.PlotAxes.pcolormesh +ultraplot.axes.PlotAxes.pcolorfast""" + ... + +def edges2d(z: Incomplete) -> Incomplete: + """Calculate the approximate "edge" values given a 2D grid of "center" values. +The size of both axes is increased by one. This is used internally to calculate +coordinate edges when you supply coordinate to pseudocolor commands. + +Parameters +---------- +z : array-like + A 2D array. + +Returns +------- +numpy.ndarray + Array of "edge" coordinates. + +See also +-------- +edges +ultraplot.axes.PlotAxes.pcolor +ultraplot.axes.PlotAxes.pcolormesh +ultraplot.axes.PlotAxes.pcolorfast""" + ... + +def get_colors(*args: Incomplete, **kwargs: Incomplete) -> list[str]: + """Get the colors associated with a registered or +on-the-fly color cycle or colormap. + +Parameters +---------- +*args, **kwargs + Passed to `~ultraplot.constructor.Cycle`. + +Returns +------- +colors : list of str + A list of HEX strings. + +See also +-------- +ultraplot.constructor.Cycle +ultraplot.constructor.Colormap""" + ... + +def _transform_color(func: Incomplete, color: Incomplete, space: Incomplete) -> Incomplete: + """Standardize input for color transformation functions.""" + ... + +def shift_hue(color: Incomplete, shift: Incomplete=0, space: Incomplete='hcl') -> str: + """Shift the hue channel of a color. + +Parameters +---------- +color : color-spec + The color. Sanitized with `to_rgba`. +shift : float, optional + The HCL hue channel is offset by this value. +space : {'hcl', 'hpl', 'hsl', 'hsv'}, optional + The hue-saturation-luminance-like colorspace used to transform the color. + Default is the strictly perceptually uniform colorspace ``'hcl'``. + +Returns +------- +color : str + An 8-digit HEX string indicating the + red, green, blue, and alpha channel values. + +See also +-------- +set_hue +set_saturation +set_luminance +set_alpha +scale_saturation +scale_luminance""" + ... + +def scale_saturation(color: Incomplete, scale: Incomplete=1, space: Incomplete='hcl') -> str: + """Scale the saturation channel of a color. + +Parameters +---------- +color : color-spec + The color. Sanitized with `to_rgba`. +scale : float, optional + The HCL saturation channel is multiplied by this value. +space : {'hcl', 'hpl', 'hsl', 'hsv'}, optional + The hue-saturation-luminance-like colorspace used to transform the color. + Default is the strictly perceptually uniform colorspace ``'hcl'``. + +Returns +------- +color : str + An 8-digit HEX string indicating the + red, green, blue, and alpha channel values. + +See also +-------- +set_hue +set_saturation +set_luminance +set_alpha +shift_hue +scale_luminance""" + ... + +def scale_luminance(color: Incomplete, scale: Incomplete=1, space: Incomplete='hcl') -> str: + """Scale the luminance channel of a color. + +Parameters +---------- +color : color-spec + The color. Sanitized with `to_rgba`. +scale : float, optional + The luminance channel is multiplied by this value. +space : {'hcl', 'hpl', 'hsl', 'hsv'}, optional + The hue-saturation-luminance-like colorspace used to transform the color. + Default is the strictly perceptually uniform colorspace ``'hcl'``. + +Returns +------- +color : str + An 8-digit HEX string indicating the + red, green, blue, and alpha channel values. + +See also +-------- +set_hue +set_saturation +set_luminance +set_alpha +shift_hue +scale_saturation""" + ... + +def set_hue(color: Incomplete, hue: Incomplete, space: Incomplete='hcl') -> str: + """Return a color with a different hue and the same luminance and saturation +as the input color. + +Parameters +---------- +color : color-spec + The color. Sanitized with `to_rgba`. +hue : float, optional + The new hue. Should lie between ``0`` and ``360`` degrees. +space : {'hcl', 'hpl', 'hsl', 'hsv'}, optional + The hue-saturation-luminance-like colorspace used to transform the color. + Default is the strictly perceptually uniform colorspace ``'hcl'``. + +Returns +------- +color : str + An 8-digit HEX string indicating the + red, green, blue, and alpha channel values. + +See also +-------- +set_saturation +set_luminance +set_alpha +shift_hue +scale_saturation +scale_luminance""" + ... + +def set_saturation(color: Incomplete, saturation: Incomplete, space: Incomplete='hcl') -> str: + """Return a color with a different saturation and the same hue and luminance +as the input color. + +Parameters +---------- +color : color-spec + The color. Sanitized with `to_rgba`. +saturation : float, optional + The new saturation. Should lie between ``0`` and ``360`` degrees. +space : {'hcl', 'hpl', 'hsl', 'hsv'}, optional + The hue-saturation-luminance-like colorspace used to transform the color. + Default is the strictly perceptually uniform colorspace ``'hcl'``. + +Returns +------- +color : str + An 8-digit HEX string indicating the + red, green, blue, and alpha channel values. + +See also +-------- +set_hue +set_luminance +set_alpha +shift_hue +scale_saturation +scale_luminance""" + ... + +def set_luminance(color: Incomplete, luminance: Incomplete, space: Incomplete='hcl') -> str: + """Return a color with a different luminance and the same hue and saturation +as the input color. + +Parameters +---------- +color : color-spec + The color. Sanitized with `to_rgba`. +luminance : float, optional + The new luminance. Should lie between ``0`` and ``100``. +space : {'hcl', 'hpl', 'hsl', 'hsv'}, optional + The hue-saturation-luminance-like colorspace used to transform the color. + Default is the strictly perceptually uniform colorspace ``'hcl'``. + +Returns +------- +color : str + An 8-digit HEX string indicating the + red, green, blue, and alpha channel values. + +See also +-------- +set_hue +set_saturation +set_alpha +shift_hue +scale_saturation +scale_luminance""" + ... + +def set_alpha(color: Incomplete, alpha: Incomplete) -> str: + """Return a color with the opacity channel set to the specified value. + +Parameters +---------- +color : color-spec + The color. Sanitized with `to_rgba`. +alpha : float, optional + The new opacity. Should be between ``0`` and ``1``. + +Returns +------- +color : str + An 8-digit HEX string indicating the + red, green, blue, and alpha channel values. + +See also +-------- +set_hue +set_saturation +set_luminance +shift_hue +scale_saturation +scale_luminance""" + ... + +def _translate_cycle_color(color: Incomplete, cycle: Incomplete=None) -> Incomplete: + """Parse the input cycle color.""" + ... + +def to_hex(color: Incomplete, space: Incomplete='rgb', cycle: Incomplete=None, keep_alpha: Incomplete=True) -> str: + """Translate the color from an arbitrary colorspace to a HEX string. +This is a generalization of `matplotlib.colors.to_hex`. + +Parameters +---------- +color : color-spec + The color. Can be a 3-tuple or 4-tuple of channel values, a hex + string, a registered color name, a cycle color like ``'C0'``, or + a 2-tuple colormap coordinate specification like ``('magma', 0.5)`` + (see `~ultraplot.colors.ColorDatabase` for details). + + If `space` is ``'rgb'``, this is a tuple of RGB values, and any + channels are larger than ``2``, the channels are assumed to be + on the ``0`` to ``255`` scale and are divided by ``255``. +space : {'rgb', 'hsv', 'hcl', 'hpl', 'hsl'}, optional + The colorspace for the input channel values. Ignored unless `color` + is a tuple of numbers. +cycle : str, default: :rcraw:`cycle` + The registered color cycle name used to interpret colors that + look like ``'C0'``, ``'C1'``, etc. +clip : bool, default: True + Whether to clip channel values into the valid ``0`` to ``1`` range. + Setting this to ``False`` can result in invalid colors. +keep_alpha : bool, default: True + Whether to keep the opacity channel. If ``True`` an 8-digit HEX + is returned. Otherwise a 6-digit HEX is returned. + +Returns +------- +color : str + An 8-digit HEX string indicating the + red, green, blue, and alpha channel values. + +See also +-------- +to_rgb +to_rgba +to_xyz +to_xyza""" + ... + +def to_rgb(color: Incomplete, space: Incomplete='rgb', cycle: Incomplete=None) -> Incomplete: + """Translate the color from an arbitrary colorspace to an RGB tuple. This is +a generalization of `matplotlib.colors.to_rgb` and the inverse of `to_xyz`. + +Parameters +---------- +color : color-spec + The color. Can be a 3-tuple or 4-tuple of channel values, a hex + string, a registered color name, a cycle color like ``'C0'``, or + a 2-tuple colormap coordinate specification like ``('magma', 0.5)`` + (see `~ultraplot.colors.ColorDatabase` for details). + + If `space` is ``'rgb'``, this is a tuple of RGB values, and any + channels are larger than ``2``, the channels are assumed to be + on the ``0`` to ``255`` scale and are divided by ``255``. +space : {'rgb', 'hsv', 'hcl', 'hpl', 'hsl'}, optional + The colorspace for the input channel values. Ignored unless `color` + is a tuple of numbers. +cycle : str, default: :rcraw:`cycle` + The registered color cycle name used to interpret colors that + look like ``'C0'``, ``'C1'``, etc. +clip : bool, default: True + Whether to clip channel values into the valid ``0`` to ``1`` range. + Setting this to ``False`` can result in invalid colors. + +Returns +------- +color : 3-tuple + An RGB tuple. + +See also +-------- +to_hex +to_rgba +to_xyz +to_xyza""" + ... + +def to_rgba(color: Incomplete, space: Incomplete='rgb', cycle: Incomplete=None, clip: Incomplete=True) -> Incomplete: + """Translate the color from an arbitrary colorspace to an RGBA tuple. This is +a generalization of `matplotlib.colors.to_rgba` and the inverse of `to_xyz`. + +Parameters +---------- +color : color-spec + The color. Can be a 3-tuple or 4-tuple of channel values, a hex + string, a registered color name, a cycle color like ``'C0'``, or + a 2-tuple colormap coordinate specification like ``('magma', 0.5)`` + (see `~ultraplot.colors.ColorDatabase` for details). + + If `space` is ``'rgb'``, this is a tuple of RGB values, and any + channels are larger than ``2``, the channels are assumed to be + on the ``0`` to ``255`` scale and are divided by ``255``. +space : {'rgb', 'hsv', 'hcl', 'hpl', 'hsl'}, optional + The colorspace for the input channel values. Ignored unless `color` + is a tuple of numbers. +cycle : str, default: :rcraw:`cycle` + The registered color cycle name used to interpret colors that + look like ``'C0'``, ``'C1'``, etc. +clip : bool, default: True + Whether to clip channel values into the valid ``0`` to ``1`` range. + Setting this to ``False`` can result in invalid colors. + +Returns +------- +color : 4-tuple + An RGBA tuple. + +See also +-------- +to_hex +to_rgb +to_xyz +to_xyza""" + ... + +def to_xyz(color: Incomplete, space: Incomplete='hcl') -> Incomplete: + """Translate color in *any* format to a tuple of channel values in *any* +colorspace. This is the inverse of `to_rgb`. + +Parameters +---------- +color : color-spec + The color. Sanitized with `to_rgba`. +space : {'hcl', 'hpl', 'hsl', 'hsv', 'rgb'}, optional + The colorspace for the output channel values. + +Returns +------- +color : 3-tuple + Tuple of channel values for the colorspace `space`. + +See also +-------- +to_hex +to_rgb +to_rgba +to_xyza""" + ... + +def to_xyza(color: Incomplete, space: Incomplete='hcl') -> Incomplete: + """Translate color in *any* format to a tuple of channel values in *any* +colorspace. This is the inverse of `to_rgba`. + +Parameters +---------- +color : color-spec + The color. Sanitized with `to_rgba`. +space : {'hcl', 'hpl', 'hsl', 'hsv', 'rgb'}, optional + The colorspace for the output channel values. + +Returns +------- +color : 3-tuple + Tuple of channel values for the colorspace `space`. + +See also +-------- +to_hex +to_rgb +to_rgba +to_xyz""" + ... + +def _fontsize_to_pt(size: Incomplete) -> Incomplete: + """Translate font preset size or unit string to points.""" + ... + +def units(value: Incomplete, numeric: Incomplete=None, dest: Incomplete=None, *, fontsize: Incomplete=None, figure: Incomplete=None, axes: Incomplete=None, width: Incomplete=None) -> Incomplete: + """Convert values between arbitrary physical units. This is used internally all +over ultraplot, permitting flexible units for various keyword arguments. + +Parameters +---------- +value : float or str or sequence + A size specifier or sequence of size specifiers. If numeric, units are + converted from `numeric` to `dest`. If string, units are converted to + `dest` according to the string specifier. The string should look like + ``'123.456unit'``, where the number is the magnitude and ``'unit'`` + matches a key in the below table. + + .. _units_table: + + ========= ===================================================== + Key Description + ========= ===================================================== + ``'m'`` Meters + ``'dm'`` Decimeters + ``'cm'`` Centimeters + ``'mm'`` Millimeters + ``'yd'`` Yards + ``'ft'`` Feet + ``'in'`` Inches + ``'pc'`` `Pica `_ (1/6 inches) + ``'pt'`` `Points `_ (1/72 inches) + ``'px'`` Pixels on screen, using dpi of :rcraw:`figure.dpi` + ``'pp'`` Pixels once printed, using dpi of :rcraw:`savefig.dpi` + ``'em'`` `Em square `_ for :rcraw:`font.size` + ``'en'`` `En square `_ for :rcraw:`font.size` + ``'Em'`` `Em square `_ for :rcraw:`axes.titlesize` + ``'En'`` `En square `_ for :rcraw:`axes.titlesize` + ``'ax'`` Axes-relative units (not always available) + ``'fig'`` Figure-relative units (not always available) + ``'ly'`` Light years ;) + ========= ===================================================== + + .. _pt: https://en.wikipedia.org/wiki/Point_(typography) + .. _pc: https://en.wikipedia.org/wiki/Pica_(typography) + .. _em: https://en.wikipedia.org/wiki/Em_(typography) + .. _en: https://en.wikipedia.org/wiki/En_(typography) + +numeric : str, default: 'in' + The units associated with numeric input. +dest : str, default: `numeric` + The destination units. +fontsize : str or float, default: :rc:`font.size` or :rc:`axes.titlesize` + The font size in points used for scaling. Default is + :rcraw:`font.size` for ``em`` and ``en`` units and + :rcraw:`axes.titlesize` for ``Em`` and ``En`` units. +axes : `~matplotlib.axes.Axes`, optional + The axes to use for scaling units that look like ``'0.1ax'``. +figure : `~matplotlib.figure.Figure`, optional + The figure to use for scaling units that look like ``'0.1fig'``. + If not provided we try to get the figure from ``axes.figure``. +width : bool, optional + Whether to use the width or height for the axes and figure + relative coordinates.""" + ... + +def _get_subplot_layout(gs: 'GridSpec', all_axes: Incomplete, same_type: Incomplete=True) -> tuple[np.ndarray[int, int], np.ndarray[int, int], dict[type, int]]: + """Helper function to determine the grid layout of axes in a +GridSpec. It returns a grid of axis numbers and a grid of +axis types. This function is used internally to determine +the layout of axes in a GridSpec.""" + ... + +@dataclass +class _Crawler: + """ + A crawler is used to find edges of axes in a grid layout. + This is useful for determining whether to turn shared labels + on or depending on the position of an axis in the gridspec. + It crawls over the grid in all four cardinal directions and + checks whether it reaches a border of the grid or an axis of + a different type. It was created as adding colorbars will + change the underlying gridspec and therefore we cannot rely + on the original gridspec to determine whether an axis is a + border or not. + """ + ax: object + grid: np.ndarray[int, int] + grid_axis_type: np.ndarray[int, int] + target: int + axis_type: int + directions = {'left': (0, -1), 'right': (0, 1), 'top': (-1, 0), 'bottom': (1, 0)} + + def find_edges(self) -> Generator[tuple[str, bool], None, None]: + """Check all cardinal directions. When we find a +border for any starting conditions we break and +consider it a border. This could mean that for some +partial overlaps we consider borders that should +not be borders -- we are conservative in this +regard.""" + ... + + def find_edge_for(self, direction: str, d: tuple[int, int]) -> tuple[str, bool]: + """Setup search for a specific direction.""" + ... + + def is_border(self, pos: tuple[int, int], direction: tuple[int, int]) -> bool: + """Recursively move over the grid by following the direction.""" + ... + + def _check_ranges(self, direction: tuple[int, int], other: int) -> bool: + """Helper function to determined whether a subplot +is enclosed or enclosed another subplot. This is +key to know where a border is, e.g. + +1 2 +1 3 + +Implies that 1 cannot share y with 2 and 3, but 2, and 3 +can share x.""" + ... + +def check_for_update(package_name: str) -> None: + ... From 58a2f699ea19edb4d450792d786c44c190a053e6 Mon Sep 17 00:00:00 2001 From: cvanelteren Date: Fri, 4 Sep 2026 01:16:41 +1000 Subject: [PATCH 4/9] do runtime inspection --- tools/generate_stubs.py | 88 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 80 insertions(+), 8 deletions(-) diff --git a/tools/generate_stubs.py b/tools/generate_stubs.py index bdfbb3c62..0db4201d4 100644 --- a/tools/generate_stubs.py +++ b/tools/generate_stubs.py @@ -6,6 +6,8 @@ import ast import builtins import copy +import importlib +import inspect import os import re import shutil @@ -419,11 +421,55 @@ def _run_pyrefly(executable: str) -> tuple[dict[Path, ast.Module], list[Path]]: return trees, invalid +def _module_name(source_path: Path) -> str: + """Return the dotted Python module name for a package file.""" + relative = source_path.relative_to(ROOT).with_suffix("") + parts = list(relative.parts) + if parts[-1] == "__init__": + parts.pop() + return ".".join(parts) + + +def _load_module(name: str): + """Safely import a module from the package for runtime inspection.""" + os.environ.setdefault("MPLCONFIGDIR", "/tmp/ultraplot-matplotlib") + if str(ROOT) not in sys.path: + sys.path.insert(0, str(ROOT)) + try: + return importlib.import_module(name) + except Exception: + return None + + +def _resolve_runtime_doc(module: Any, qualname: str) -> str | None: + """Retrieve the fully expanded runtime docstring for a given qualified name.""" + if module is None or not qualname: + return None + try: + obj = module + for part in qualname.split("."): + if isinstance(obj, type) and part in obj.__dict__: + candidate = obj.__dict__[part] + if isinstance(candidate, property): + doc = inspect.getdoc(candidate) or inspect.getdoc(candidate.fget) + if doc: + return doc + obj = getattr(obj, part) + doc = inspect.getdoc(obj) + if doc: + return doc + except Exception: + pass + return None + + class _StubTransformer(ast.NodeTransformer): """Reduce implementation syntax to declarations suitable for ``.pyi`` files.""" - def __init__(self, expand_docstring): + def __init__(self, expand_docstring, module: Any = None): self._expand_docstring = expand_docstring + self._module = module + self._scope: list[str] = [] def _decorators(self, nodes: list[ast.expr]) -> list[ast.expr]: kept = [] @@ -433,11 +479,22 @@ def _decorators(self, nodes: list[ast.expr]) -> list[ast.expr]: kept.append(node) return kept - def _doc_body(self, node: ast.AST) -> list[ast.stmt]: - doc = ast.get_docstring(node, clean=True) + def _doc_body( + self, node: ast.AST, qualname: str | None = None + ) -> list[ast.stmt]: + doc = None + if qualname: + doc = _resolve_runtime_doc(self._module, qualname) + if not doc: + ast_doc = ast.get_docstring(node, clean=True) + if ast_doc: + doc = self._expand_docstring(ast_doc) + elif "%(" in doc: + doc = self._expand_docstring(doc) + body = [] if doc: - body.append(ast.Expr(value=ast.Constant(self._expand_docstring(doc)))) + body.append(ast.Expr(value=ast.Constant(doc))) body.append(ast.Expr(value=ast.Constant(Ellipsis))) return body @@ -480,21 +537,34 @@ def visit_Module(self, node: ast.Module) -> ast.Module: def visit_ClassDef(self, node: ast.ClassDef) -> ast.ClassDef: node.decorator_list = self._decorators(node.decorator_list) - node.body = self._scope_body(node.body) + self._scope.append(node.name) + try: + node.body = self._scope_body(node.body) + finally: + self._scope.pop() + if node.body and _is_docstring_statement(node.body[0]): + qualname = ".".join((*self._scope, node.name)) + doc = _resolve_runtime_doc(self._module, qualname) + if doc: + if "%(" in doc: + doc = self._expand_docstring(doc) + node.body[0] = ast.Expr(value=ast.Constant(doc)) if not node.body: node.body = [ast.Expr(value=ast.Constant(Ellipsis))] return node def visit_FunctionDef(self, node: ast.FunctionDef) -> ast.FunctionDef: node.decorator_list = self._decorators(node.decorator_list) - node.body = self._doc_body(node) + qualname = ".".join((*self._scope, node.name)) + node.body = self._doc_body(node, qualname) return node def visit_AsyncFunctionDef( self, node: ast.AsyncFunctionDef ) -> ast.AsyncFunctionDef: node.decorator_list = self._decorators(node.decorator_list) - node.body = self._doc_body(node) + qualname = ".".join((*self._scope, node.name)) + node.body = self._doc_body(node, qualname) return node def visit_Expr(self, node: ast.Expr) -> ast.Expr | None: @@ -613,7 +683,9 @@ def _render( source = source_path.read_text() tree = ast.parse(source, filename=str(source_path)) annotation_counts = _merge_annotations(tree, inferred) - tree = _StubTransformer(expand_docstring).visit(copy.deepcopy(tree)) + module_name = _module_name(source_path) + module = _load_module(module_name) + tree = _StubTransformer(expand_docstring, module=module).visit(copy.deepcopy(tree)) ast.fix_missing_locations(tree) rendered = ast.unparse(tree).rstrip() + "\n" return HEADER + rendered, annotation_counts From 8ea7f8b6475b81c404f2be1f728d4468ba4b915d Mon Sep 17 00:00:00 2001 From: cvanelteren Date: Fri, 4 Sep 2026 12:07:52 +1000 Subject: [PATCH 5/9] resolve and fix doc resolution with pyright -- pylance not tested --- tools/ci/stub_consumer.py | 12 + tools/generate_stubs.py | 77 +- ultraplot/_animation.pyi | 64 +- ultraplot/_interaction.pyi | 2 + ultraplot/_layout.pyi | 47 +- ultraplot/_lazy.pyi | 6 +- ultraplot/_subplots.pyi | 16 +- ultraplot/animation.pyi | 176 +- ultraplot/axes/base.pyi | 751 ++- ultraplot/axes/cartesian.pyi | 96 +- ultraplot/axes/container.pyi | 85 +- ultraplot/axes/geo.pyi | 190 +- ultraplot/axes/plot.pyi | 4940 ++++++++++++++++++- ultraplot/axes/plot_types/circlize.pyi | 11 + ultraplot/axes/plot_types/curved_quiver.pyi | 42 +- ultraplot/axes/polar.pyi | 68 +- ultraplot/axes/shared.pyi | 6 +- ultraplot/axes/taylor.pyi | 18 +- ultraplot/axes/three.pyi | 17 +- ultraplot/colorbar.pyi | 9 +- ultraplot/colors.pyi | 74 +- ultraplot/config.pyi | 67 +- ultraplot/constructor.pyi | 162 +- ultraplot/figure.pyi | 956 +++- ultraplot/gridspec.py | 20 +- ultraplot/gridspec.pyi | 407 +- ultraplot/internals/benchmarks.pyi | 5 +- ultraplot/internals/context.pyi | 10 +- ultraplot/internals/docstring.pyi | 8 +- ultraplot/internals/fonts.pyi | 34 +- ultraplot/internals/guides.pyi | 8 +- ultraplot/internals/rcsetup.pyi | 12 +- ultraplot/internals/versions.pyi | 15 +- ultraplot/legend.pyi | 486 +- ultraplot/proj.pyi | 40 +- ultraplot/scale.pyi | 497 +- ultraplot/tests/test_stubs.py | 45 + ultraplot/text.pyi | 130 +- ultraplot/ticker.pyi | 183 +- ultraplot/ui.py | 7 +- ultraplot/ui.pyi | 7 +- ultraplot/ultralayout.pyi | 15 +- ultraplot/utils.pyi | 20 +- 43 files changed, 8892 insertions(+), 949 deletions(-) diff --git a/tools/ci/stub_consumer.py b/tools/ci/stub_consumer.py index 717362aae..1129ebf3a 100644 --- a/tools/ci/stub_consumer.py +++ b/tools/ci/stub_consumer.py @@ -1,6 +1,18 @@ """Representative lazy public imports consumed by static type checkers.""" +from collections.abc import Callable +from typing import Any, assert_type + import ultraplot as uplt reveal_type(uplt.subplots) reveal_type(uplt.Axes.format) + +figure, axes = uplt.subplots() +assert_type(figure, uplt.Figure) +assert_type(axes, uplt.SubplotGrid) +assert_type(axes[0], uplt.Axes) +axes[0].format(title="Static typing") +assert_type(axes.plot, Callable[..., Any]) +_ = axes.plot([0, 1], [0, 1]) +reveal_type(axes.plot) diff --git a/tools/generate_stubs.py b/tools/generate_stubs.py index 0db4201d4..d976a3bb9 100644 --- a/tools/generate_stubs.py +++ b/tools/generate_stubs.py @@ -47,6 +47,9 @@ SNIPPET_PATTERN = re.compile(r"%\(([^)]+)\)s") BUILTIN_NAMES = set(dir(builtins)) | {"None"} TRY_NODES = (ast.Try,) + ((ast.TryStar,) if hasattr(ast, "TryStar") else ()) +RUNTIME_DOC_BANNERS = re.compile( + r"(?m)^=+\n(ultraplot documentation|Matplotlib documentation)\n=+\n?" +) def _dotted_name(node: ast.expr) -> str | None: @@ -430,15 +433,18 @@ def _module_name(source_path: Path) -> str: return ".".join(parts) -def _load_module(name: str): - """Safely import a module from the package for runtime inspection.""" +def _load_runtime_modules(source_files: Iterable[Path]) -> dict[Path, Any]: + """Evaluate package modules once and retain the resulting runtime API.""" os.environ.setdefault("MPLCONFIGDIR", "/tmp/ultraplot-matplotlib") if str(ROOT) not in sys.path: sys.path.insert(0, str(ROOT)) - try: - return importlib.import_module(name) - except Exception: - return None + modules = {} + for source_path in source_files: + try: + modules[source_path] = importlib.import_module(_module_name(source_path)) + except Exception: + modules[source_path] = None + return modules def _resolve_runtime_doc(module: Any, qualname: str) -> str | None: @@ -453,16 +459,27 @@ def _resolve_runtime_doc(module: Any, qualname: str) -> str | None: if isinstance(candidate, property): doc = inspect.getdoc(candidate) or inspect.getdoc(candidate.fget) if doc: - return doc + return _clean_runtime_doc(doc) obj = getattr(obj, part) doc = inspect.getdoc(obj) if doc: - return doc + return _clean_runtime_doc(doc) except Exception: pass return None +def _clean_runtime_doc(doc: str) -> str: + """Remove website-oriented reStructuredText banners from editor hovers.""" + def replace(match: re.Match) -> str: + if match.group(1).startswith("ultraplot"): + return "" + return "Matplotlib documentation\n\n" + + doc = RUNTIME_DOC_BANNERS.sub(replace, doc) + return doc.strip() + + class _StubTransformer(ast.NodeTransformer): """Reduce implementation syntax to declarations suitable for ``.pyi`` files.""" @@ -672,8 +689,33 @@ def replace(match: re.Match) -> str: return expand +def _add_static_forwarding_bases(source_path: Path, tree: ast.Module) -> None: + """Expose runtime ``__getattr__`` proxies to static analyzers. + + ``SubplotGrid`` forwards missing attributes to its axes, but language servers + cannot enumerate attributes implemented by ``__getattr__``. Its stub can + advertise the shared two-dimensional plotting API as a base, while the + runtime proxy continues to handle calls for each compatible axes. + """ + if source_path != PACKAGE / "gridspec.py": + return + for node in tree.body: + if isinstance(node, ast.ClassDef) and node.name == "SubplotGrid": + node.bases.append( + ast.Attribute( + value=ast.Name(id="paxes", ctx=ast.Load()), + attr="PlotAxes", + ctx=ast.Load(), + ) + ) + return + + def _render( - source_path: Path, expand_docstring, inferred: ast.Module | None + source_path: Path, + expand_docstring, + inferred: ast.Module | None, + runtime_module: Any, ) -> tuple[str, tuple[int, int, int, int]]: """Render one implementation module as a deterministic type stub.""" if source_path == PACKAGE / "_version.py": @@ -683,11 +725,14 @@ def _render( source = source_path.read_text() tree = ast.parse(source, filename=str(source_path)) annotation_counts = _merge_annotations(tree, inferred) - module_name = _module_name(source_path) - module = _load_module(module_name) - tree = _StubTransformer(expand_docstring, module=module).visit(copy.deepcopy(tree)) + _add_static_forwarding_bases(source_path, tree) + tree = _StubTransformer(expand_docstring, module=runtime_module).visit( + copy.deepcopy(tree) + ) ast.fix_missing_locations(tree) - rendered = ast.unparse(tree).rstrip() + "\n" + rendered = ast.unparse(tree) + rendered = "\n".join(line.rstrip() for line in rendered.splitlines()) + rendered = rendered.rstrip() + "\n" return HEADER + rendered, annotation_counts @@ -725,6 +770,7 @@ def main(argv: list[str] | None = None) -> int: expand_docstring = _snippet_expander() source_files = list(_source_files()) + runtime_modules = _load_runtime_modules(source_files) expected = set() changed = [] inferred_count = fallback_count = unmatched_count = discarded_count = 0 @@ -734,7 +780,10 @@ def main(argv: list[str] | None = None) -> int: stub_path = _stub_path(source_path) expected.add(stub_path) rendered, counts = _render( - source_path, expand_docstring, inferred_trees.get(source_path) + source_path, + expand_docstring, + inferred_trees.get(source_path), + runtime_modules.get(source_path), ) inferred_count += counts[0] fallback_count += counts[1] diff --git a/ultraplot/_animation.pyi b/ultraplot/_animation.pyi index a0b025a28..3734e42f6 100644 --- a/ultraplot/_animation.pyi +++ b/ultraplot/_animation.pyi @@ -27,21 +27,20 @@ _MISSING = object() _OPAQUE_TICKER_TYPES = frozenset(('FuncFormatter', 'FuncScale', 'FuncScaleLog')) class _SelectiveDrawManager: - """ - Retain safe draw layers and bypass unchanged Matplotlib traversal. - - Multi-axes figures retain each complete axes as one layer. Single Cartesian - axes retain the stable draw-order prefix below their first clipped numeric - line, then redraw that line and every later artist as an exact z-order suffix. - Unknown stale artists, geometry changes, overlapping layers, unsupported - artist orders, and export draws fall back to a complete draw. The first display - is always untouched; a later complete draw primes the retained layers. - """ + """Retain safe draw layers and bypass unchanged Matplotlib traversal. + +Multi-axes figures retain each complete axes as one layer. Single Cartesian +axes retain the stable draw-order prefix below their first clipped numeric +line, then redraw that line and every later artist as an exact z-order suffix. +Unknown stale artists, geometry changes, overlapping layers, unsupported +artist orders, and export draws fall back to a complete draw. The first display +is always untouched; a later complete draw primes the retained layers.""" _data_artist_types = (mlines.Line2D, mcollections.Collection, mimage.AxesImage) _region_pad = 2 _min_axes_for_view_redraw = 3 def __init__(self, canvas: Incomplete, figure: Incomplete=None) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... @staticmethod @@ -209,31 +208,30 @@ clears every painted pixel by ``_region_pad`` on all sides.""" ... class _BlitManager: - """ - Manage efficient updates of a small set of changing artists. - - The manager caches the static canvas background, restores it for each - update, redraws only the managed artists, and blits the affected region. - Backends without blitting support safely fall back to ``draw_idle()``. - - Parameters - ---------- - canvas : `~matplotlib.backend_bases.FigureCanvasBase` - Canvas containing the artists. - artists : iterable of `~matplotlib.artist.Artist`, optional - Artists that will change between updates. - bbox : `~matplotlib.transforms.Bbox` or object with a ``bbox`` attribute, optional - Region to cache and blit. By default, the union of the managed artists' - axes bounding boxes is used. Figure-level artists fall back to the full - figure bounding box. - - Notes - ----- - Managed artists are drawn above the cached static background, matching - Matplotlib's standard blitting behavior. - """ + """Manage efficient updates of a small set of changing artists. + +The manager caches the static canvas background, restores it for each +update, redraws only the managed artists, and blits the affected region. +Backends without blitting support safely fall back to ``draw_idle()``. + +Parameters +---------- +canvas : `~matplotlib.backend_bases.FigureCanvasBase` + Canvas containing the artists. +artists : iterable of `~matplotlib.artist.Artist`, optional + Artists that will change between updates. +bbox : `~matplotlib.transforms.Bbox` or object with a ``bbox`` attribute, optional + Region to cache and blit. By default, the union of the managed artists' + axes bounding boxes is used. Figure-level artists fall back to the full + figure bounding box. + +Notes +----- +Managed artists are drawn above the cached static background, matching +Matplotlib's standard blitting behavior.""" def __init__(self, canvas: Incomplete, artists: Iterable[martist.Artist]=(), bbox: Incomplete=None) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... @property diff --git a/ultraplot/_interaction.pyi b/ultraplot/_interaction.pyi index dfccd1ed2..5939a5659 100644 --- a/ultraplot/_interaction.pyi +++ b/ultraplot/_interaction.pyi @@ -121,6 +121,7 @@ class _FramePacer: _interval = 1 / _TARGET_FRAME_RATE def __init__(self, canvas: Incomplete, is_active: Incomplete) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def cancel(self) -> None: @@ -144,6 +145,7 @@ class _NavigationInteractionManager: _scatter_limit = 2000 def __init__(self, canvas: Incomplete, figure: Incomplete, selective: Incomplete) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def _is_active(self) -> Incomplete: diff --git a/ultraplot/_layout.pyi b/ultraplot/_layout.pyi index b489092ee..ba9effa86 100644 --- a/ultraplot/_layout.pyi +++ b/ultraplot/_layout.pyi @@ -51,21 +51,20 @@ class _AxisTickResult: minor_locs: np.ndarray | tuple class _AxisTickCache: - """ - Cache repeated tick updates during one layout-and-render transaction. - - Tight bounding-box calculation and the final axes draw repeatedly call - ``Axis._update_ticks`` with identical state. The method runs locators, - formatters, tick positioning, and visibility filtering each time. This - manager replaces the method on individual axes for the duration of a - canvas draw and restores the original instance state afterwards. - - Custom third-party locators and formatters conservatively bypass the - cache because they may rely on repeated side effects. - """ + """Cache repeated tick updates during one layout-and-render transaction. + +Tight bounding-box calculation and the final axes draw repeatedly call +``Axis._update_ticks`` with identical state. The method runs locators, +formatters, tick positioning, and visibility filtering each time. This +manager replaces the method on individual axes for the duration of a +canvas draw and restores the original instance state afterwards. + +Custom third-party locators and formatters conservatively bypass the +cache because they may rely on repeated side effects.""" _MAX_STATES_PER_AXIS = 4 def __init__(self, figure: Incomplete) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def __enter__(self) -> Incomplete: @@ -114,17 +113,16 @@ class _AxesExtentRecord: outsets: tuple class _LayoutExtentStore: - """ - Persist relative axes outsets and dependency versions between layouts. + """Persist relative axes outsets and dependency versions between layouts. - Absolute axes positions are solver outputs. Tick labels, axis labels, and - titles are better represented as four overhangs around those positions. - Standard Cartesian axes can therefore move without repeating renderer text - measurements. Position-sensitive axes and extra artists automatically add - the absolute origin to their state key. - """ +Absolute axes positions are solver outputs. Tick labels, axis labels, and +titles are better represented as four overhangs around those positions. +Standard Cartesian axes can therefore move without repeating renderer text +measurements. Position-sensitive axes and extra artists automatically add +the absolute origin to their state key.""" def __init__(self, figure: Incomplete) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def __enter__(self) -> Incomplete: @@ -185,14 +183,13 @@ relative outsets remain valid for the next layout transaction.""" ... class _LayoutTransaction: - """ - Own temporary and persistent caches for one dirty canvas draw. + """Own temporary and persistent caches for one dirty canvas draw. - Figure code only needs to know whether a transaction is active. Cache setup, - dynamic-axes refresh, and exception-safe cleanup stay private to this object. - """ +Figure code only needs to know whether a transaction is active. Cache setup, +dynamic-axes refresh, and exception-safe cleanup stay private to this object.""" def __init__(self, figure: Incomplete, *, cache_ticks: Incomplete=True, cache_extents: Incomplete=True) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def __enter__(self) -> Incomplete: diff --git a/ultraplot/_lazy.pyi b/ultraplot/_lazy.pyi index a0b280d71..a87412add 100644 --- a/ultraplot/_lazy.pyi +++ b/ultraplot/_lazy.pyi @@ -12,11 +12,10 @@ from pathlib import Path from typing import Any, Callable, Dict, Mapping, MutableMapping, Optional class LazyLoader: - """ - Encapsulates lazy-loading mechanics for the ultraplot top-level module. - """ + """Encapsulates lazy-loading mechanics for the ultraplot top-level module.""" def __init__(self, *, package: str, package_path: Path, exceptions: Mapping[str, tuple[str, Optional[str]]], setup_callback: Callable[[], None], registry_attr_callback: Callable[[str], Optional[type]], registry_build_callback: Callable[[], None], registry_names_callback: Callable[[], Optional[Mapping[str, type]]], attr_map_key: str='_ATTR_MAP', eager_key: str='_EAGER_DONE') -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def _import_module(self, module_name: str) -> types.ModuleType: @@ -56,6 +55,7 @@ class LazyLoader: class _UltraPlotModule(types.ModuleType): def __setattr__(self, name: str, value: Any) -> None: + """Implement setattr(self, name, value).""" ... def install_module_proxy(module: Optional[types.ModuleType]) -> None: diff --git a/ultraplot/_subplots.pyi b/ultraplot/_subplots.pyi index a69c78bb8..de3465ef6 100644 --- a/ultraplot/_subplots.pyi +++ b/ultraplot/_subplots.pyi @@ -17,17 +17,16 @@ from .internals import _not_none, _pop_params, warnings from .figure import Figure class SubplotManager: - """ - Manages subplot creation, gridspec ownership, and projection parsing - for a Figure instance. + """Manages subplot creation, gridspec ownership, and projection parsing +for a Figure instance. - Parameters - ---------- - figure : `~ultraplot.figure.Figure` - The parent figure. - """ +Parameters +---------- +figure : `~ultraplot.figure.Figure` + The parent figure.""" def __init__(self, figure: 'Figure') -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def reset(self) -> None: @@ -45,6 +44,7 @@ longer attached to it.""" @gridspec.setter def gridspec(self, gs: Incomplete) -> None: + """The single GridSpec used for all subplots in the figure.""" ... @staticmethod diff --git a/ultraplot/animation.pyi b/ultraplot/animation.pyi index 4f9f5c67d..134176144 100644 --- a/ultraplot/animation.pyi +++ b/ultraplot/animation.pyi @@ -42,15 +42,14 @@ def _suffix(filename: Incomplete) -> Incomplete: ... class _RawWriter: - """ - Base class for writers that consume raw ``RGBA`` frames. + """Base class for writers that consume raw ``RGBA`` frames. - Subclasses implement `write`, `_close`, and `_discard`. The output file is - deleted unless `finish` completed, so an animation that fails halfway - through never leaves a truncated movie that looks like a whole one. - """ +Subclasses implement `write`, `_close`, and `_discard`. The output file is +deleted unless `finish` completed, so an animation that fails halfway +through never leaves a truncated movie that looks like a whole one.""" def __init__(self, filename: Incomplete, fps: Incomplete) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def setup(self, width: Incomplete, height: Incomplete) -> Incomplete: @@ -74,11 +73,10 @@ class _RawWriter: ... class _RawFFMpegWriter(_RawWriter): - """ - Pipe raw ``RGBA`` frames into ``ffmpeg`` with no intermediate encoding. - """ + """Pipe raw ``RGBA`` frames into ``ffmpeg`` with no intermediate encoding.""" def __init__(self, filename: Incomplete, fps: Incomplete, *, codec: Incomplete=None, bitrate: Incomplete=None, extra_args: Incomplete=None, metadata: Incomplete=None) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... @staticmethod @@ -105,11 +103,10 @@ class _RawFFMpegWriter(_RawWriter): ... class _RawPillowWriter(_RawWriter): - """ - Collect raw ``RGBA`` frames and write an animated image with Pillow. - """ + """Collect raw ``RGBA`` frames and write an animated image with Pillow.""" def __init__(self, filename: Incomplete, fps: Incomplete) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def write(self, buffer: Incomplete) -> Incomplete: @@ -122,12 +119,10 @@ class _RawPillowWriter(_RawWriter): ... class _FastSaveMixin: - """ - The fast `save` path, shared by the animation classes. + """The fast `save` path, shared by the animation classes. - Subclasses supply the three frame hooks below; everything else here is the - machinery that renders those frames into a movie file. - """ +Subclasses supply the three frame hooks below; everything else here is the +machinery that renders those frames into a movie file.""" def _fast_frame_seq(self) -> Incomplete: ... @@ -242,64 +237,63 @@ matplotlib.animation.Animation.save""" ... class FuncAnimation(_FastSaveMixin, manimation.FuncAnimation): - """ - A faster drop-in replacement for `matplotlib.animation.FuncAnimation`. - - The signature matches Matplotlib's, with two differences: `blit` defaults - to ``True`` instead of ``False``, and `freeze_layout` is added. Saving - renders frames directly into the Agg buffer instead of calling - `~matplotlib.figure.Figure.savefig` once per frame, which removes the - per-frame PNG round-trip and the repeated UltraPlot tight-layout pass. - - Parameters - ---------- - fig : `~ultraplot.figure.Figure` - The figure to animate. - func : callable - The update function, called as ``func(frame, *fargs)``. It should - return an iterable of the artists it modified. This is required when - `blit` is ``True``, and lets the fast path skip untouched artists. - frames : int, iterable, generator, or None, optional - Source of frame data, as in Matplotlib. - init_func : callable, optional - Function drawing the clear frame. Should return the animated artists. - fargs : tuple, optional - Extra positional arguments for `func` and `init_func`. - save_count : int, optional - Number of frames to cache from a generator. - blit : bool, default: True - Whether to redraw only the artists returned by `func`. This is the main - source of the speedup, but it means changes to artists that are *not* - returned, such as titles or tick labels, will not show up. Pass - ``False`` to redraw the whole figure each frame, which is still faster - than Matplotlib because the layout solver is frozen. - cache_frame_data : bool, default: True - Whether to cache frame data, as in Matplotlib. - **kwargs - Passed to `matplotlib.animation.TimedAnimation`, e.g. `interval`, - `repeat`, and `repeat_delay`. - - Examples - -------- - >>> import ultraplot as uplt - >>> import numpy as np - >>> fig, ax = uplt.subplots() - >>> x = np.linspace(0, 2 * np.pi, 200) - >>> (line,) = ax.plot(x, np.sin(x)) - >>> def update(frame): - ... line.set_ydata(np.sin(x + frame / 10)) - ... return (line,) - ... - >>> ani = uplt.FuncAnimation(fig, update, frames=100) - >>> ani.save('waves.mp4') + """A faster drop-in replacement for `matplotlib.animation.FuncAnimation`. + +The signature matches Matplotlib's, with two differences: `blit` defaults +to ``True`` instead of ``False``, and `freeze_layout` is added. Saving +renders frames directly into the Agg buffer instead of calling +`~matplotlib.figure.Figure.savefig` once per frame, which removes the +per-frame PNG round-trip and the repeated UltraPlot tight-layout pass. + +Parameters +---------- +fig : `~ultraplot.figure.Figure` + The figure to animate. +func : callable + The update function, called as ``func(frame, *fargs)``. It should + return an iterable of the artists it modified. This is required when + `blit` is ``True``, and lets the fast path skip untouched artists. +frames : int, iterable, generator, or None, optional + Source of frame data, as in Matplotlib. +init_func : callable, optional + Function drawing the clear frame. Should return the animated artists. +fargs : tuple, optional + Extra positional arguments for `func` and `init_func`. +save_count : int, optional + Number of frames to cache from a generator. +blit : bool, default: True + Whether to redraw only the artists returned by `func`. This is the main + source of the speedup, but it means changes to artists that are *not* + returned, such as titles or tick labels, will not show up. Pass + ``False`` to redraw the whole figure each frame, which is still faster + than Matplotlib because the layout solver is frozen. +cache_frame_data : bool, default: True + Whether to cache frame data, as in Matplotlib. +**kwargs + Passed to `matplotlib.animation.TimedAnimation`, e.g. `interval`, + `repeat`, and `repeat_delay`. + +Examples +-------- +>>> import ultraplot as uplt +>>> import numpy as np +>>> fig, ax = uplt.subplots() +>>> x = np.linspace(0, 2 * np.pi, 200) +>>> (line,) = ax.plot(x, np.sin(x)) +>>> def update(frame): +... line.set_ydata(np.sin(x + frame / 10)) +... return (line,) +... +>>> ani = uplt.FuncAnimation(fig, update, frames=100) +>>> ani.save('waves.mp4') - See also - -------- - matplotlib.animation.FuncAnimation - ultraplot.animation.ArtistAnimation - """ +See also +-------- +matplotlib.animation.FuncAnimation +ultraplot.animation.ArtistAnimation""" def __init__(self, fig: Incomplete, func: Incomplete, frames: Incomplete=None, init_func: Incomplete=None, fargs: Incomplete=None, save_count: Incomplete=None, *, blit: Incomplete=True, **kwargs: Incomplete) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def _fast_frame_seq(self) -> Incomplete: @@ -312,26 +306,24 @@ class FuncAnimation(_FastSaveMixin, manimation.FuncAnimation): ... class ArtistAnimation(_FastSaveMixin, manimation.ArtistAnimation): - """ - A faster drop-in replacement for `matplotlib.animation.ArtistAnimation`. - - Frames are lists of artists that are made visible in turn. Saving uses the - same direct-to-buffer renderer as `FuncAnimation`. - - Parameters - ---------- - fig : `~ultraplot.figure.Figure` - The figure to animate. - artists : list of list of `~matplotlib.artist.Artist` - Each entry is the collection of artists making up one frame. - **kwargs - Passed to `matplotlib.animation.TimedAnimation`. - - See also - -------- - matplotlib.animation.ArtistAnimation - ultraplot.animation.FuncAnimation - """ + """A faster drop-in replacement for `matplotlib.animation.ArtistAnimation`. + +Frames are lists of artists that are made visible in turn. Saving uses the +same direct-to-buffer renderer as `FuncAnimation`. + +Parameters +---------- +fig : `~ultraplot.figure.Figure` + The figure to animate. +artists : list of list of `~matplotlib.artist.Artist` + Each entry is the collection of artists making up one frame. +**kwargs + Passed to `matplotlib.animation.TimedAnimation`. + +See also +-------- +matplotlib.animation.ArtistAnimation +ultraplot.animation.FuncAnimation""" def _fast_frame_seq(self) -> Incomplete: ... diff --git a/ultraplot/axes/base.pyi b/ultraplot/axes/base.pyi index cff7cd0dc..260bcea0f 100644 --- a/ultraplot/axes/base.pyi +++ b/ultraplot/axes/base.pyi @@ -37,7 +37,7 @@ from .. import colors as pcolors from .. import constructor from .. import legend as plegend from .. import ticker as pticker -from ..colorbar import UltraColorbar, _apply_inset_colorbar_layout, _determine_label_rotation, _get_axis_for, _get_colorbar_long_axis, _legacy_inset_colorbar_bounds, _reflow_inset_colorbar_frame, _register_inset_colorbar_reflow, _solve_inset_colorbar_bounds +from ..colorbar import UltraColorbar, _anchor_inset_colorbar_bounds, _apply_inset_colorbar_layout, _determine_label_rotation, _get_axis_for, _get_colorbar_long_axis, _legacy_inset_colorbar_bounds, _reflow_inset_colorbar_frame, _register_inset_colorbar_reflow, _solve_inset_colorbar_bounds from ..config import rc from ..internals import _kwargs_to_args, _not_none, _pop_kwargs, _pop_params, _pop_props, _pop_rc, _translate_loc, _version_mpl, docstring, guides, ic, labels, rcsetup, warnings from ..ultralayout import KIWI_AVAILABLE, ColorbarLayoutSolver @@ -92,35 +92,36 @@ def _get_colorbar_aligned_position(side: Incomplete, align: Incomplete, length: ... class _TransformedBoundsLocator: - """ - Axes locator for `~Axes.inset_axes` and other axes. - """ + """Axes locator for `~Axes.inset_axes` and other axes.""" def __init__(self, bounds: Incomplete, transform: Incomplete) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def __call__(self, ax: Incomplete, renderer: Incomplete) -> Incomplete: + """Call self as a function.""" ... class _AspectAwareTransformedBoundsLocator(_TransformedBoundsLocator): """Preserve an inset's lower-left anchor after box-aspect adjustment.""" def __call__(self, ax: Incomplete, renderer: Incomplete) -> Incomplete: + """Call self as a function.""" ... class _SideColorbarLocator: """Position a side colorbar beyond its parent axes decorations.""" def __init__(self, parent: Incomplete, side: Incomplete, bounds: Incomplete, pad: Incomplete, previous: Incomplete=()) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def __call__(self, ax: Incomplete, renderer: Incomplete) -> Incomplete: + """Call self as a function.""" ... class _ExternalModeMixin: - """ - Mixin providing explicit external-mode control and a context manager. - """ + """Mixin providing explicit external-mode control and a context manager.""" def set_external(self, value: Incomplete=True) -> Incomplete: """Set explicit external-mode override for this axes. @@ -133,6 +134,7 @@ value: class _ExternalContext: def __init__(self, ax: Incomplete, value: Incomplete=True) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def __enter__(self) -> Incomplete: @@ -150,18 +152,18 @@ value: ... class Axes(_ExternalModeMixin, maxes.Axes): - """ - The lowest-level `~matplotlib.axes.Axes` subclass used by ultraplot. - Implements basic universal features. - """ + """The lowest-level `~matplotlib.axes.Axes` subclass used by ultraplot. +Implements basic universal features.""" _name = None _name_aliases = () _make_inset_locator = _TransformedBoundsLocator def __repr__(self) -> str: + """Return repr(self).""" ... def __str__(self) -> str: + """Return str(self).""" ... def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: @@ -371,7 +373,7 @@ objects whose data values span a natural colormap range).""" """Return the axes and adjusted keyword args for a panel-filling colorbar.""" ... - def _parse_colorbar_inset(self, loc: Incomplete=None, width: Incomplete=None, length: Incomplete=None, shrink: Incomplete=None, frame: Incomplete=None, frameon: Incomplete=None, label: Incomplete=None, labelsize: Incomplete=None, pad: Incomplete=None, tickloc: Incomplete=None, ticklocation: Incomplete=None, orientation: Incomplete=None, labelloc: Incomplete=None, labelrotation: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + def _parse_colorbar_inset(self, loc: Incomplete=None, bbox_to_anchor: Incomplete=None, width: Incomplete=None, length: Incomplete=None, shrink: Incomplete=None, frame: Incomplete=None, frameon: Incomplete=None, label: Incomplete=None, labelsize: Incomplete=None, pad: Incomplete=None, tickloc: Incomplete=None, ticklocation: Incomplete=None, orientation: Incomplete=None, labelloc: Incomplete=None, labelrotation: Incomplete=None, **kwargs: Incomplete) -> Incomplete: """Return the axes and adjusted keyword args for an inset colorbar.""" ... @@ -620,15 +622,131 @@ ultraplot.config.Configurator.context""" ... def draw(self, renderer: Incomplete=None, *args: Incomplete, **kwargs: Incomplete) -> None: + """Draw the Artist (and its children) using the given renderer. + +This has no effect if the artist is not visible (`.Artist.get_visible` +returns False). + +Parameters +---------- +renderer : `~matplotlib.backend_bases.RendererBase` subclass. + +Notes +----- +This method is overridden in the Artist subclasses.""" ... def get_tightbbox(self, renderer: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Return the tight bounding box of the Axes, including axis and their +decorators (xlabel, title, etc). + +Artists that have ``artist.set_in_layout(False)`` are not included +in the bbox. + +Parameters +---------- +renderer : `.RendererBase` subclass + renderer that will be used to draw the figures (i.e. + ``fig.canvas.get_renderer()``) + +bbox_extra_artists : list of `.Artist` or ``None`` + List of artists to include in the tight bounding box. If + ``None`` (default), then all artist children of the Axes are + included in the tight bounding box. + +call_axes_locator : bool, default: True + If *call_axes_locator* is ``False``, it does not call the + ``_axes_locator`` attribute, which is necessary to get the correct + bounding box. ``call_axes_locator=False`` can be used if the + caller is only interested in the relative size of the tightbbox + compared to the Axes bbox. + +for_layout_only : default: False + The bounding box will *not* include the x-extent of the title and + the xlabel, or the y-extent of the ylabel. + +Returns +------- +`.BboxBase` + Bounding box in figure pixel coordinates. + +See Also +-------- +matplotlib.axes.Axes.get_window_extent +matplotlib.axis.Axis.get_tightbbox +matplotlib.spines.Spine.get_window_extent""" ... def get_default_bbox_extra_artists(self) -> Incomplete: + """Return a default list of artists that are used for the bounding box +calculation. + +Artists are excluded either by not being visible or +``artist.set_in_layout(False)``.""" ... def set_prop_cycle(self, *args: Incomplete, **kwargs: Incomplete) -> None: + """Set the property cycle of the Axes. + +The property cycle controls the style properties such as color, +marker and linestyle of future plot commands. The style properties +of data already added to the Axes are not modified. + +Call signatures:: + + set_prop_cycle(cycler) + set_prop_cycle(label=values, label2=values2, ...) + set_prop_cycle(label, values) + +Form 1 sets given `~cycler.Cycler` object. + +Form 2 creates a `~cycler.Cycler` which cycles over one or more +properties simultaneously and set it as the property cycle of the +Axes. If multiple properties are given, their value lists must have +the same length. This is just a shortcut for explicitly creating a +cycler and passing it to the function, i.e. it's short for +``set_prop_cycle(cycler(label=values, label2=values2, ...))``. + +Form 3 creates a `~cycler.Cycler` for a single property and set it +as the property cycle of the Axes. This form exists for compatibility +with the original `cycler.cycler` interface. Its use is discouraged +in favor of the kwarg form, i.e. ``set_prop_cycle(label=values)``. + +Parameters +---------- +cycler : `~cycler.Cycler` or ``None`` + Set the given Cycler. *None* resets to the cycle defined by the + current style. + + .. ACCEPTS: `~cycler.Cycler` + +label : str + The property key. Must be a valid `.Artist` property. + For example, 'color' or 'linestyle'. Aliases are allowed, + such as 'c' for 'color' and 'lw' for 'linewidth'. + +values : iterable + Finite-length iterable of the property values. These values + are validated and will raise a ValueError if invalid. + +See Also +-------- +matplotlib.rcsetup.cycler + Convenience function for creating validated cyclers for properties. +cycler.cycler + The original function for creating unvalidated cyclers. + +Examples +-------- +Setting the property cycle for a single property: + +>>> ax.set_prop_cycle(color=['red', 'green', 'blue']) + +Setting the property cycle for simultaneously cycling over multiple +properties (e.g. red circle, green plus, blue cross): + +>>> ax.set_prop_cycle(color=['red', 'green', 'blue'], +... marker=['o', '+', 'x'])""" ... def _is_panel_group_member(self, other: 'Axes') -> bool: @@ -1041,6 +1159,11 @@ align : {'center', 'top', 'bottom', 'left', 'right', 't', 'b', 'l', 'r'}, option and ``'left'`` and ``'right'`` are valid for top and bottom colorbars. The default is always ``'center'``. Has no visible effect if `length` is ``1``. + bbox_to_anchor : 2-tuple, 4-tuple, or `matplotlib.transforms.Bbox`, optional + For inset colorbars, anchor the full colorbar footprint using the + same semantics as `~matplotlib.axes.Axes.legend`. The colorbar + `loc` selects the corresponding anchor corner. Outer colorbar + placement is unchanged. Other parameters ---------------- orientation : {None, 'horizontal', 'vertical'}, optional @@ -1295,7 +1418,323 @@ handler_map : dict-like, optional See also -------- ultraplot.figure.Figure.legend -matplotlib.axes.Axes.legend""" +matplotlib.axes.Axes.legend + +Matplotlib documentation + + +Place a legend on the Axes. + +Call signatures:: + + legend() + legend(handles, labels) + legend(handles=handles) + legend(labels) + +The call signatures correspond to the following different ways to use +this method: + +**1. Automatic detection of elements to be shown in the legend** + +The elements to be added to the legend are automatically determined, +when you do not pass in any extra arguments. + +In this case, the labels are taken from the artist. You can specify +them either at artist creation or by calling the +:meth:`~.Artist.set_label` method on the artist:: + + ax.plot([1, 2, 3], label='Inline label') + ax.legend() + +or:: + + line, = ax.plot([1, 2, 3]) + line.set_label('Label via method') + ax.legend() + +.. note:: + Specific artists can be excluded from the automatic legend element + selection by using a label starting with an underscore, "_". + A string starting with an underscore is the default label for all + artists, so calling `.Axes.legend` without any arguments and + without setting the labels manually will result in a ``UserWarning`` + and an empty legend being drawn. + + +**2. Explicitly listing the artists and labels in the legend** + +For full control of which artists have a legend entry, it is possible +to pass an iterable of legend artists followed by an iterable of +legend labels respectively:: + + ax.legend([line1, line2, line3], ['label1', 'label2', 'label3']) + + +**3. Explicitly listing the artists in the legend** + +This is similar to 2, but the labels are taken from the artists' +label properties. Example:: + + line1, = ax.plot([1, 2, 3], label='label1') + line2, = ax.plot([1, 2, 3], label='label2') + ax.legend(handles=[line1, line2]) + + +**4. Labeling existing plot elements** + +.. admonition:: Discouraged + + This call signature is discouraged, because the relation between + plot elements and labels is only implicit by their order and can + easily be mixed up. + +To make a legend for all artists on an Axes, call this function with +an iterable of strings, one for each legend item. For example:: + + ax.plot([1, 2, 3]) + ax.plot([5, 6, 7]) + ax.legend(['First line', 'Second line']) + + +Parameters +---------- +handles : list of (`.Artist` or tuple of `.Artist`), optional + A list of Artists (lines, patches) to be added to the legend. + Use this together with *labels*, if you need full control on what + is shown in the legend and the automatic mechanism described above + is not sufficient. + + The length of handles and labels should be the same in this + case. If they are not, they are truncated to the smaller length. + + If an entry contains a tuple, then the legend handler for all Artists in the + tuple will be placed alongside a single label. + +labels : list of str, optional + A list of labels to show next to the artists. + Use this together with *handles*, if you need full control on what + is shown in the legend and the automatic mechanism described above + is not sufficient. + +Returns +------- +`~matplotlib.legend.Legend` + +Other Parameters +---------------- + +loc : str or pair of floats, default: :rc:`legend.loc` + The location of the legend. + + The strings ``'upper left'``, ``'upper right'``, ``'lower left'``, + ``'lower right'`` place the legend at the corresponding corner of the + axes. + + The strings ``'upper center'``, ``'lower center'``, ``'center left'``, + ``'center right'`` place the legend at the center of the corresponding edge + of the axes. + + The string ``'center'`` places the legend at the center of the axes. + + The string ``'best'`` places the legend at the location, among the nine + locations defined so far, with the minimum overlap with other drawn + artists. This option can be quite slow for plots with large amounts of + data; your plotting speed may benefit from providing a specific location. + + The location can also be a 2-tuple giving the coordinates of the lower-left + corner of the legend in axes coordinates (in which case *bbox_to_anchor* + will be ignored). + + For back-compatibility, ``'center right'`` (but no other location) can also + be spelled ``'right'``, and each "string" location can also be given as a + numeric value: + + ================== ============= + Location String Location Code + ================== ============= + 'best' (Axes only) 0 + 'upper right' 1 + 'upper left' 2 + 'lower left' 3 + 'lower right' 4 + 'right' 5 + 'center left' 6 + 'center right' 7 + 'lower center' 8 + 'upper center' 9 + 'center' 10 + ================== ============= + +bbox_to_anchor : `.BboxBase`, 2-tuple, or 4-tuple of floats + Box that is used to position the legend in conjunction with *loc*. + Defaults to ``axes.bbox`` (if called as a method to `.Axes.legend`) or + ``figure.bbox`` (if ``figure.legend``). This argument allows arbitrary + placement of the legend. + + Bbox coordinates are interpreted in the coordinate system given by + *bbox_transform*, with the default transform + Axes or Figure coordinates, depending on which ``legend`` is called. + + If a 4-tuple or `.BboxBase` is given, then it specifies the bbox + ``(x, y, width, height)`` that the legend is placed in. + To put the legend in the best location in the bottom right + quadrant of the Axes (or figure):: + + loc='best', bbox_to_anchor=(0.5, 0., 0.5, 0.5) + + A 2-tuple ``(x, y)`` places the corner of the legend specified by *loc* at + x, y. For example, to put the legend's upper right-hand corner in the + center of the Axes (or figure) the following keywords can be used:: + + loc='upper right', bbox_to_anchor=(0.5, 0.5) + +ncols : int, default: 1 + The number of columns that the legend has. + + For backward compatibility, the spelling *ncol* is also supported + but it is discouraged. If both are given, *ncols* takes precedence. + +prop : None or `~matplotlib.font_manager.FontProperties` or dict + The font properties of the legend. If None (default), the current + :data:`matplotlib.rcParams` will be used. + +fontsize : int or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'} + The font size of the legend. If the value is numeric the size will be the + absolute font size in points. String values are relative to the current + default font size. This argument is only used if *prop* is not specified. + +labelcolor : str or list, default: :rc:`legend.labelcolor` + The color of the text in the legend. Either a valid color string + (for example, 'red'), or a list of color strings. The labelcolor can + also be made to match the color of the line or marker using 'linecolor', + 'markerfacecolor' (or 'mfc'), or 'markeredgecolor' (or 'mec'). + + Labelcolor can be set globally using :rc:`legend.labelcolor`. If None, + use :rc:`text.color`. + +numpoints : int, default: :rc:`legend.numpoints` + The number of marker points in the legend when creating a legend + entry for a `.Line2D` (line). + +scatterpoints : int, default: :rc:`legend.scatterpoints` + The number of marker points in the legend when creating + a legend entry for a `.PathCollection` (scatter plot). + +scatteryoffsets : iterable of floats, default: ``[0.375, 0.5, 0.3125]`` + The vertical offset (relative to the font size) for the markers + created for a scatter plot legend entry. 0.0 is at the base the + legend text, and 1.0 is at the top. To draw all markers at the + same height, set to ``[0.5]``. + +markerscale : float, default: :rc:`legend.markerscale` + The relative size of legend markers compared to the originally drawn ones. + +markerfirst : bool, default: True + If *True*, legend marker is placed to the left of the legend label. + If *False*, legend marker is placed to the right of the legend label. + +reverse : bool, default: False + If *True*, the legend labels are displayed in reverse order from the input. + If *False*, the legend labels are displayed in the same order as the input. + + .. versionadded:: 3.7 + +frameon : bool, default: :rc:`legend.frameon` + Whether the legend should be drawn on a patch (frame). + +fancybox : bool, default: :rc:`legend.fancybox` + Whether round edges should be enabled around the `.FancyBboxPatch` which + makes up the legend's background. + +shadow : None, bool or dict, default: :rc:`legend.shadow` + Whether to draw a shadow behind the legend. + The shadow can be configured using `.Patch` keywords. + Customization via :rc:`legend.shadow` is currently not supported. + +framealpha : float, default: :rc:`legend.framealpha` + The alpha transparency of the legend's background. + If *shadow* is activated and *framealpha* is ``None``, the default value is + ignored. + +facecolor : "inherit" or color, default: :rc:`legend.facecolor` + The legend's background color. + If ``"inherit"``, use :rc:`axes.facecolor`. + +edgecolor : "inherit" or color, default: :rc:`legend.edgecolor` + The legend's background patch edge color. + If ``"inherit"``, use :rc:`axes.edgecolor`. + +mode : {"expand", None} + If *mode* is set to ``"expand"`` the legend will be horizontally + expanded to fill the Axes area (or *bbox_to_anchor* if defines + the legend's size). + +bbox_transform : None or `~matplotlib.transforms.Transform` + The transform for the bounding box (*bbox_to_anchor*). For a value + of ``None`` (default) the Axes' + :data:`~matplotlib.axes.Axes.transAxes` transform will be used. + +title : str or None + The legend's title. Default is no title (``None``). + +title_fontproperties : None or `~matplotlib.font_manager.FontProperties` or dict + The font properties of the legend's title. If None (default), the + *title_fontsize* argument will be used if present; if *title_fontsize* is + also None, the current :rc:`legend.title_fontsize` will be used. + +title_fontsize : int or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}, default: :rc:`legend.title_fontsize` + The font size of the legend's title. + Note: This cannot be combined with *title_fontproperties*. If you want + to set the fontsize alongside other font properties, use the *size* + parameter in *title_fontproperties*. + +alignment : {'center', 'left', 'right'}, default: 'center' + The alignment of the legend title and the box of entries. The entries + are aligned as a single block, so that markers always lined up. + +borderpad : float, default: :rc:`legend.borderpad` + The fractional whitespace inside the legend border, in font-size units. + +labelspacing : float, default: :rc:`legend.labelspacing` + The vertical space between the legend entries, in font-size units. + +handlelength : float, default: :rc:`legend.handlelength` + The length of the legend handles, in font-size units. + +handleheight : float, default: :rc:`legend.handleheight` + The height of the legend handles, in font-size units. + +handletextpad : float, default: :rc:`legend.handletextpad` + The pad between the legend handle and text, in font-size units. + +borderaxespad : float, default: :rc:`legend.borderaxespad` + The pad between the Axes and legend border, in font-size units. + +columnspacing : float, default: :rc:`legend.columnspacing` + The spacing between columns, in font-size units. + +handler_map : dict or None + The custom dictionary mapping instances or types to a legend + handler. This *handler_map* updates the default handler map + found at `matplotlib.legend.Legend.get_legend_handler_map`. + +draggable : bool, default: False + Whether the legend can be dragged with the mouse. + + +See Also +-------- +.Figure.legend + +Notes +----- +Some artists are not supported by this function. See +:ref:`legend_guide` for details. + +Examples +-------- +.. plot:: gallery/text_labels_and_annotations/legend.py""" ... def add_legend(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -1836,7 +2275,118 @@ fontsize : unit-spec or str, optional See also -------- matplotlib.axes.Axes.text -ultraplot.axes.Axes.auto_align_text""" +ultraplot.axes.Axes.auto_align_text + +Matplotlib documentation + + +Add text to the Axes. + +Add the text *s* to the Axes at location *x*, *y* in data coordinates, +with a default ``horizontalalignment`` on the ``left`` and +``verticalalignment`` at the ``baseline``. See +:doc:`/gallery/text_labels_and_annotations/text_alignment`. + +Parameters +---------- +x, y : float + The position to place the text. By default, this is in data + coordinates. The coordinate system can be changed using the + *transform* parameter. + +s : str + The text. + +fontdict : dict, default: None + + .. admonition:: Discouraged + + The use of *fontdict* is discouraged. Parameters should be passed as + individual keyword arguments or using dictionary-unpacking + ``text(..., **fontdict)``. + + A dictionary to override the default text properties. If fontdict + is None, the defaults are determined by `.rcParams`. + +Returns +------- +`.Text` + The created `.Text` instance. + +Other Parameters +---------------- +**kwargs : `~matplotlib.text.Text` properties. + Other miscellaneous text parameters. + + Properties: + agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image + alpha: float or None + animated: bool + antialiased: bool + backgroundcolor: :mpltype:`color` + bbox: dict with properties for `.patches.FancyBboxPatch` + clip_box: unknown + clip_on: unknown + clip_path: unknown + color or c: :mpltype:`color` + figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + fontfamily or family or fontname: {FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'} + fontproperties or font or font_properties: `.font_manager.FontProperties` or `str` or `pathlib.Path` + fontsize or size: float or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'} + fontstretch or stretch: {a numeric value in range 0-1000, 'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', 'expanded', 'extra-expanded', 'ultra-expanded'} + fontstyle or style: {'normal', 'italic', 'oblique'} + fontvariant or variant: {'normal', 'small-caps'} + fontweight or weight: {a numeric value in range 0-1000, 'ultralight', 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black'} + gid: str + horizontalalignment or ha: {'left', 'center', 'right'} + in_layout: bool + label: object + linespacing: float (multiple of font size) + math_fontfamily: str + mouseover: bool + multialignment or ma: {'left', 'right', 'center'} + parse_math: bool + path_effects: list of `.AbstractPathEffect` + picker: None or bool or float or callable + position: (float, float) + rasterized: bool + rotation: float or {'vertical', 'horizontal'} + rotation_mode: {None, 'default', 'anchor'} + sketch_params: (scale: float, length: float, randomness: float) + snap: bool or None + text: object + transform: `~matplotlib.transforms.Transform` + transform_rotates_text: bool + url: str + usetex: bool, default: :rc:`text.usetex` + verticalalignment or va: {'baseline', 'bottom', 'center', 'center_baseline', 'top'} + visible: bool + wrap: bool + x: float + y: float + zorder: float + +Examples +-------- +Individual keyword arguments can be used to override any given +parameter:: + + >>> text(x, y, s, fontsize=12) + +The default transform specifies that text is in data coords, +alternatively, you can specify text in axis coords ((0, 0) is +lower-left and (1, 1) is upper-right). The example below places +text in the center of the Axes:: + + >>> text(0.5, 0.5, 'matplotlib', horizontalalignment='center', + ... verticalalignment='center', transform=ax.transAxes) + +You can put a rectangular box around the text instance (e.g., to +set a background color) by using the keyword *bbox*. *bbox* is +a dictionary of `~matplotlib.patches.Rectangle` +properties. For example:: + + >>> text(x, y, s, bbox=dict(facecolor='red', alpha=0.5))""" ... def _register_align_text(self, obj: Incomplete, avoid_overlap: Incomplete=None) -> Incomplete: @@ -1910,7 +2460,171 @@ Parameters avoid_overlap : bool, default: :rc:`text.align` Whether to automatically nudge this annotation at draw time so it does not overlap other auto-aligned text or the plotted data. See - `~ultraplot.axes.Axes.auto_align_text`.""" + `~ultraplot.axes.Axes.auto_align_text`. + +Matplotlib documentation + + +Annotate the point *xy* with text *text*. + +In the simplest form, the text is placed at *xy*. + +Optionally, the text can be displayed in another position *xytext*. +An arrow pointing from the text to the annotated point *xy* can then +be added by defining *arrowprops*. + +Parameters +---------- +text : str + The text of the annotation. + +xy : (float, float) + The point *(x, y)* to annotate. The coordinate system is determined + by *xycoords*. + +xytext : (float, float), default: *xy* + The position *(x, y)* to place the text at. The coordinate system + is determined by *textcoords*. + +xycoords : single or two-tuple of str or `.Artist` or `.Transform` or callable, default: 'data' + + The coordinate system that *xy* is given in. The following types + of values are supported: + + - One of the following strings: + + ==================== ============================================ + Value Description + ==================== ============================================ + 'figure points' Points from the lower left of the figure + 'figure pixels' Pixels from the lower left of the figure + 'figure fraction' Fraction of figure from lower left + 'subfigure points' Points from the lower left of the subfigure + 'subfigure pixels' Pixels from the lower left of the subfigure + 'subfigure fraction' Fraction of subfigure from lower left + 'axes points' Points from lower left corner of the Axes + 'axes pixels' Pixels from lower left corner of the Axes + 'axes fraction' Fraction of Axes from lower left + 'data' Use the coordinate system of the object + being annotated (default) + 'polar' *(theta, r)* if not native 'data' + coordinates + ==================== ============================================ + + Note that 'subfigure pixels' and 'figure pixels' are the same + for the parent figure, so users who want code that is usable in + a subfigure can use 'subfigure pixels'. + + - An `.Artist`: *xy* is interpreted as a fraction of the artist's + `~matplotlib.transforms.Bbox`. E.g. *(0, 0)* would be the lower + left corner of the bounding box and *(0.5, 1)* would be the + center top of the bounding box. + + - A `.Transform` to transform *xy* to screen coordinates. + + - A function with one of the following signatures:: + + def transform(renderer) -> Bbox + def transform(renderer) -> Transform + + where *renderer* is a `.RendererBase` subclass. + + The result of the function is interpreted like the `.Artist` and + `.Transform` cases above. + + - A tuple *(xcoords, ycoords)* specifying separate coordinate + systems for *x* and *y*. *xcoords* and *ycoords* must each be + of one of the above described types. + + See :ref:`plotting-guide-annotation` for more details. + +textcoords : single or two-tuple of str or `.Artist` or `.Transform` or callable, default: value of *xycoords* + The coordinate system that *xytext* is given in. + + All *xycoords* values are valid as well as the following strings: + + ================= ================================================= + Value Description + ================= ================================================= + 'offset points' Offset, in points, from the *xy* value + 'offset pixels' Offset, in pixels, from the *xy* value + 'offset fontsize' Offset, relative to fontsize, from the *xy* value + ================= ================================================= + +arrowprops : dict, optional + The properties used to draw a `.FancyArrowPatch` arrow between the + positions *xy* and *xytext*. Defaults to None, i.e. no arrow is + drawn. + + For historical reasons there are two different ways to specify + arrows, "simple" and "fancy": + + **Simple arrow:** + + If *arrowprops* does not contain the key 'arrowstyle' the + allowed keys are: + + ========== ================================================= + Key Description + ========== ================================================= + width The width of the arrow in points + headwidth The width of the base of the arrow head in points + headlength The length of the arrow head in points + shrink Fraction of total length to shrink from both ends + ? Any `.FancyArrowPatch` property + ========== ================================================= + + The arrow is attached to the edge of the text box, the exact + position (corners or centers) depending on where it's pointing to. + + **Fancy arrow:** + + This is used if 'arrowstyle' is provided in the *arrowprops*. + + Valid keys are the following `.FancyArrowPatch` parameters: + + =============== =================================== + Key Description + =============== =================================== + arrowstyle The arrow style + connectionstyle The connection style + relpos See below; default is (0.5, 0.5) + patchA Default is bounding box of the text + patchB Default is None + shrinkA In points. Default is 2 points + shrinkB In points. Default is 2 points + mutation_scale Default is text size (in points) + mutation_aspect Default is 1 + ? Any `.FancyArrowPatch` property + =============== =================================== + + The exact starting point position of the arrow is defined by + *relpos*. It's a tuple of relative coordinates of the text box, + where (0, 0) is the lower left corner and (1, 1) is the upper + right corner. Values <0 and >1 are supported and specify points + outside the text box. By default (0.5, 0.5), so the starting point + is centered in the text box. + +annotation_clip : bool or None, default: None + Whether to clip (i.e. not draw) the annotation when the annotation + point *xy* is outside the Axes area. + + - If *True*, the annotation will be clipped when *xy* is outside + the Axes. + - If *False*, the annotation will always be drawn. + - If *None*, the annotation will be clipped when *xy* is outside + the Axes and *xycoords* is 'data'. + +**kwargs + Additional kwargs are passed to `.Text`. + +Returns +------- +`.Annotation` + +See Also +-------- +:ref:`annotations`""" ... def curvedtext(self, x: Incomplete, y: Incomplete, text: Incomplete, *, upright: Incomplete=None, ellipsis: Incomplete=None, avoid_overlap: Incomplete=None, overlap_tol: Incomplete=None, curvature_pad: Incomplete=None, min_advance: Incomplete=None, border: Incomplete=False, bbox: Incomplete=False, bordercolor: Incomplete='w', borderwidth: Incomplete=2, borderinvert: Incomplete=False, borderstyle: Incomplete='miter', bboxcolor: Incomplete='w', bboxstyle: Incomplete='round', bboxalpha: Incomplete=0.5, bboxpad: Incomplete=None, **kwargs: Incomplete) -> Incomplete: @@ -2021,6 +2735,9 @@ by `~ultraplot.figure.Figure.subplots`.""" @number.setter def number(self, num: Incomplete) -> None: + """The axes number. This controls the order of a-b-c labels and the +order of appearance in the :class:`~ultraplot.gridspec.SubplotGrid` returned +by `~ultraplot.figure.Figure.subplots`.""" ... @property @@ -2033,6 +2750,10 @@ Initialized from :rcraw:`axes.sticky_edges`.""" @use_sticky_edges.setter def use_sticky_edges(self, value: Incomplete) -> None: + """Whether plotting commands like `plot`, `plotx`, `vlines`, `hlines`, +`fill_between`, and `fill_betweenx` add "sticky" edges to their artists, +i.e. whether the default axis limits are the artist bounds with no padding. +Initialized from :rcraw:`axes.sticky_edges`.""" ... def _get_pos_from_locator(loc: str, x_pad: float, y_pad: float) -> tuple[float, float]: diff --git a/ultraplot/axes/cartesian.pyi b/ultraplot/axes/cartesian.pyi index c32fb1c0e..d2bf86e20 100644 --- a/ultraplot/axes/cartesian.pyi +++ b/ultraplot/axes/cartesian.pyi @@ -88,17 +88,15 @@ class _AxisFormatConfig: ticklabelweight: Optional[str] = None class CartesianAxes(shared._SharedAxes, plot.PlotAxes): - """ - Axes subclass for plotting in ordinary Cartesian coordinates. Adds the - `~CartesianAxes.format` method and overrides several existing methods. - - Important - --------- - This is the default axes subclass. It can be specified explicitly by passing - ``proj='cart'``, ``proj='cartesian'``, ``proj='rect'``, or ``proj='rectilinear'`` - to axes-creation commands like `~ultraplot.figure.Figure.add_axes`, - `~ultraplot.figure.Figure.add_subplot`, and `~ultraplot.figure.Figure.subplots`. - """ + """Axes subclass for plotting in ordinary Cartesian coordinates. Adds the +`~CartesianAxes.format` method and overrides several existing methods. + +Important +--------- +This is the default axes subclass. It can be specified explicitly by passing +``proj='cart'``, ``proj='cartesian'``, ``proj='rect'``, or ``proj='rectilinear'`` +to axes-creation commands like `~ultraplot.figure.Figure.add_axes`, +`~ultraplot.figure.Figure.add_subplot`, and `~ultraplot.figure.Figure.subplots`.""" _name = 'cartesian' _name_aliases = ('cart', 'rect', 'rectilinar') @@ -457,9 +455,35 @@ one will draw its properties. Use keyword args to override settings.""" ... def set_xscale(self, value: Incomplete, **kwargs: Incomplete) -> None: + """Set the xaxis' scale. + +Parameters +---------- +value : str or `.ScaleBase` + The axis scale type to apply. Valid string values are the names of scale + classes ("linear", "log", "function",...). These may be the names of any + of the :ref:`built-in scales` or of any custom scales + registered using `matplotlib.scale.register_scale`. + +**kwargs + If *value* is a string, keywords are passed to the instantiation method of + the respective class.""" ... def set_yscale(self, value: Incomplete, **kwargs: Incomplete) -> None: + """Set the yaxis' scale. + +Parameters +---------- +value : str or `.ScaleBase` + The axis scale type to apply. Valid string values are the names of scale + classes ("linear", "log", "function",...). These may be the names of any + of the :ref:`built-in scales` or of any custom scales + registered using `matplotlib.scale.register_scale`. + +**kwargs + If *value* is a string, keywords are passed to the instantiation method of + the respective class.""" ... def _update_formatter(self, s: Incomplete, formatter: Incomplete=None, *, formatter_kw: Incomplete=None, tickrange: Incomplete=None, wraprange: Incomplete=None) -> None: @@ -1031,9 +1055,59 @@ This enforces the following default settings: ... def draw(self, renderer: Incomplete=None, *args: Incomplete, **kwargs: Incomplete) -> None: + """Draw the Artist (and its children) using the given renderer. + +This has no effect if the artist is not visible (`.Artist.get_visible` +returns False). + +Parameters +---------- +renderer : `~matplotlib.backend_bases.RendererBase` subclass. + +Notes +----- +This method is overridden in the Artist subclasses.""" ... def get_tightbbox(self, renderer: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Return the tight bounding box of the Axes, including axis and their +decorators (xlabel, title, etc). + +Artists that have ``artist.set_in_layout(False)`` are not included +in the bbox. + +Parameters +---------- +renderer : `.RendererBase` subclass + renderer that will be used to draw the figures (i.e. + ``fig.canvas.get_renderer()``) + +bbox_extra_artists : list of `.Artist` or ``None`` + List of artists to include in the tight bounding box. If + ``None`` (default), then all artist children of the Axes are + included in the tight bounding box. + +call_axes_locator : bool, default: True + If *call_axes_locator* is ``False``, it does not call the + ``_axes_locator`` attribute, which is necessary to get the correct + bounding box. ``call_axes_locator=False`` can be used if the + caller is only interested in the relative size of the tightbbox + compared to the Axes bbox. + +for_layout_only : default: False + The bounding box will *not* include the x-extent of the title and + the xlabel, or the y-extent of the ylabel. + +Returns +------- +`.BboxBase` + Bounding box in figure pixel coordinates. + +See Also +-------- +matplotlib.axes.Axes.get_window_extent +matplotlib.axis.Axis.get_tightbbox +matplotlib.spines.Spine.get_window_extent""" ... def _capture_explicit_format_keys(func: _F) -> _F: diff --git a/ultraplot/axes/container.pyi b/ultraplot/axes/container.pyi index 660917c8b..a6287bab6 100644 --- a/ultraplot/axes/container.pyi +++ b/ultraplot/axes/container.pyi @@ -18,48 +18,46 @@ __all__ = ['ExternalAxesContainer'] _ABOVE_AXES_TITLE_LOCS = {'left', 'center', 'right'} class ExternalAxesContainer(CartesianAxes): - """ - Container axes that wraps an external axes instance. - - This class inherits from ultraplot's CartesianAxes and creates/manages an external - axes as a child. It provides ultraplot's interface while delegating - drawing and interaction to the wrapped external axes. - - Parameters - ---------- - *args - Positional arguments passed to Axes.__init__ - external_axes_class : type - The external axes class to instantiate (e.g., mpltern.TernaryAxes) - external_axes_kwargs : dict, optional - Keyword arguments to pass to the external axes constructor - external_shrink_factor : float, optional, default: :rc:`external.shrink` - The factor by which to shrink the external axes within the container - to leave room for labels. For ternary plots, labels extend significantly - beyond the plot area, so a value of 0.90 (10% padding) helps prevent - overlap with adjacent subplots while keeping the axes large. - external_padding : float, optional, default: 5.0 - Padding in points to add around the external axes tight bbox. This creates - space between the external axes and adjacent subplots, preventing overlap - with tick labels or other elements. Set to 0 to disable padding. - **kwargs - Keyword arguments passed to Axes.__init__ - - Notes - ----- - When using external axes containers with multiple subplots, the external axes - (e.g., ternary plots) are automatically shrunk to prevent label overlap with - adjacent subplots. If you still experience overlap, you can: - - 1. Increase spacing with ``wspace`` or ``hspace`` in subplots() - 2. Decrease ``external_shrink_factor`` (more aggressive shrinking) - 3. Use tight_layout or constrained_layout for automatic spacing - - Example: ``uplt.subplots(ncols=2, projection=('ternary', None), wspace=5)`` - - To reduce padding between external axes and adjacent subplots, use: - ``external_padding=2`` or ``external_padding=0`` to disable padding entirely. - """ + """Container axes that wraps an external axes instance. + +This class inherits from ultraplot's CartesianAxes and creates/manages an external +axes as a child. It provides ultraplot's interface while delegating +drawing and interaction to the wrapped external axes. + +Parameters +---------- +*args + Positional arguments passed to Axes.__init__ +external_axes_class : type + The external axes class to instantiate (e.g., mpltern.TernaryAxes) +external_axes_kwargs : dict, optional + Keyword arguments to pass to the external axes constructor +external_shrink_factor : float, optional, default: :rc:`external.shrink` + The factor by which to shrink the external axes within the container + to leave room for labels. For ternary plots, labels extend significantly + beyond the plot area, so a value of 0.90 (10% padding) helps prevent + overlap with adjacent subplots while keeping the axes large. +external_padding : float, optional, default: 5.0 + Padding in points to add around the external axes tight bbox. This creates + space between the external axes and adjacent subplots, preventing overlap + with tick labels or other elements. Set to 0 to disable padding. +**kwargs + Keyword arguments passed to Axes.__init__ + +Notes +----- +When using external axes containers with multiple subplots, the external axes +(e.g., ternary plots) are automatically shrunk to prevent label overlap with +adjacent subplots. If you still experience overlap, you can: + +1. Increase spacing with ``wspace`` or ``hspace`` in subplots() +2. Decrease ``external_shrink_factor`` (more aggressive shrinking) +3. Use tight_layout or constrained_layout for automatic spacing + +Example: ``uplt.subplots(ncols=2, projection=('ternary', None), wspace=5)`` + +To reduce padding between external axes and adjacent subplots, use: +``external_padding=2`` or ``external_padding=0`` to disable padding entirely.""" _EXTERNAL_DELEGATE_BLOCKLIST = {'format', 'colorbar', 'legend', 'set_title'} def __init__(self, *args: Incomplete, external_axes_class: Incomplete=None, external_axes_kwargs: Incomplete=None, **kwargs: Incomplete) -> None: @@ -93,9 +91,12 @@ allocated space and overlap with adjacent subplots.""" ... def _reposition_subplot(self) -> None: + """Reposition the subplot axes.""" ... def _update_title_position(self, renderer: Incomplete) -> None: + """Update the position of inset titles and outer titles. This is called +by matplotlib at drawtime.""" ... def _title_reserves_external_space(self, loc: Incomplete) -> bool: diff --git a/ultraplot/axes/geo.pyi b/ultraplot/axes/geo.pyi index ba0aac785..df392269e 100644 --- a/ultraplot/axes/geo.pyi +++ b/ultraplot/axes/geo.pyi @@ -60,9 +60,11 @@ class _AnchoredInsetLocator: """Locate an inset by anchoring one of its points to a parent coordinate.""" def __init__(self, parent: Incomplete, xy: Incomplete, size: Incomplete, transform: Incomplete, anchor: Incomplete, square: Incomplete=False) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def __call__(self, ax: Incomplete, renderer: Incomplete) -> Incomplete: + """Call self as a function.""" ... _HAWKEYE_TRANSFORM_NAMES = frozenset({'axes', 'data', 'figure', 'subfigure', 'map'}) @@ -170,18 +172,16 @@ matplotlib >= 3.10 the ``InsetIndicator`` resolves its connectors in its own @dataclass class _HawkeyeSpec: - """ - Validated inputs for :meth:`GeoAxes.hawkeye`. - - ``extent_transform`` and ``relation`` are only fully resolved when ``extent`` - is not ``None`` (they require a geographic extent to normalize and infer); - otherwise they retain their raw defaults and are never consumed. ``aspect`` is - intentionally not stored here because ``'projection'`` can only be resolved - from the live inset axes (see :meth:`GeoAxes._build_hawkeye_inset`). When - ``anchor_transform`` is not ``None`` the ``anchor`` is a geographic/projected - point rather than an axes fraction; it is converted to a fraction against the - live inset view limits in :meth:`GeoAxes._build_hawkeye_inset`. - """ + """Validated inputs for :meth:`GeoAxes.hawkeye`. + +``extent_transform`` and ``relation`` are only fully resolved when ``extent`` +is not ``None`` (they require a geographic extent to normalize and infer); +otherwise they retain their raw defaults and are never consumed. ``aspect`` is +intentionally not stored here because ``'projection'`` can only be resolved +from the live inset axes (see :meth:`GeoAxes._build_hawkeye_inset`). When +``anchor_transform`` is not ``None`` the ``anchor`` is a geographic/projected +point rather than an axes fraction; it is converted to a fraction against the +live inset view limits in :meth:`GeoAxes._build_hawkeye_inset`.""" xy: tuple[float, float] size: tuple[float, float] anchor: tuple[float, float] @@ -206,9 +206,7 @@ _hawkeye_docstring = ... _choropleth_docstring = ... class _GeoLabel(object): - """ - Optionally omit overlapping check if an rc setting is disabled. - """ + """Optionally omit overlapping check if an rc setting is disabled.""" def check_overlapping(self, *args: Any, **kwargs: Any) -> bool: ... @@ -218,9 +216,7 @@ if cgridliner is not None and hasattr(cgridliner, 'Label'): """Label class with configurable overlap checks.""" class _CartopyGridliner(cgridliner.Gridliner): - """ - Gridliner subclass to localize cartopy quirks in one place. - """ + """Gridliner subclass to localize cartopy quirks in one place.""" LabelClass = _CartopyLabel def _generate_labels(self) -> Iterator[_CartopyLabel]: @@ -228,21 +224,31 @@ if cgridliner is not None and hasattr(cgridliner, 'Label'): ... def _axes_domain(self, *args: Any, **kwargs: Any) -> tuple[Any, Any]: + """Return lon_range, lat_range""" ... def _draw_gridliner(self, *args: Any, **kwargs: Any) -> Any: + """Create Artists for all visible elements and add to our Axes. + +The following rules apply for the visibility of labels: + +- X-type labels are plotted along the bottom, top and geo spines. +- Y-type labels are plotted along the left, right and geo spines. +- A label must not overlap another label marked as visible. +- A label must not overlap the map boundary. +- When a label is about to be hidden, its padding is slightly + increase until it can be drawn or until a padding limit is reached.""" ... else: _CartopyGridliner = None class _GeoAxis(object): - """ - Dummy axis used by longitude and latitude locators and for storing view limits on - longitude and latitude coordinates. Modeled after how `matplotlib.ticker._DummyAxis` - and `matplotlib.ticker.TickHelper` are used to control tick locations and labels. - """ + """Dummy axis used by longitude and latitude locators and for storing view limits on +longitude and latitude coordinates. Modeled after how `matplotlib.ticker._DummyAxis` +and `matplotlib.ticker.TickHelper` are used to control tick locations and labels.""" def __init__(self, axes: 'GeoAxes') -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def _get_extent(self) -> tuple[float, float, float, float]: @@ -291,11 +297,9 @@ used when the @self is sharing with @other.""" ... class _GridlinerAdapter(Protocol): - """ - Lightweight facade used to normalize cartopy and basemap gridliner behavior. - These adapters let GeoAxes apply gridline label toggles and styles without - backend-specific branching. - """ + """Lightweight facade used to normalize cartopy and basemap gridliner behavior. +These adapters let GeoAxes apply gridline label toggles and styles without +backend-specific branching.""" def labels_for_sides(self, *, bottom: bool | str | None=None, top: bool | str | None=None, left: bool | str | None=None, right: bool | str | None=None) -> dict[str, list[mtext.Text]]: ... @@ -313,10 +317,8 @@ class _GridlinerAdapter(Protocol): ... class _CartopyGridlinerProtocol(Protocol): - """ - Structural protocol for the subset of cartopy Gridliner attributes we use. - This keeps type hints tight without importing cartopy at runtime. - """ + """Structural protocol for the subset of cartopy Gridliner attributes we use. +This keeps type hints tight without importing cartopy at runtime.""" collection_kwargs: dict[str, Any] xlabel_style: dict[str, Any] ylabel_style: dict[str, Any] @@ -344,12 +346,11 @@ class _CartopyGridlinerProtocol(Protocol): ... class _CartopyGridlinerAdapter(_GridlinerAdapter): - """ - Adapter for cartopy's Gridliner, translating common label/style operations - into the Gridliner API while hiding cartopy version differences. - """ + """Adapter for cartopy's Gridliner, translating common label/style operations +into the Gridliner API while hiding cartopy version differences.""" def __init__(self, gridliner: Optional[_CartopyGridlinerProtocol]) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... @staticmethod @@ -372,12 +373,11 @@ class _CartopyGridlinerAdapter(_GridlinerAdapter): ... class _BasemapGridlinerAdapter(_GridlinerAdapter): - """ - Adapter for basemap meridian/parallel dictionaries, emulating the subset - of cartopy Gridliner behavior needed by GeoAxes (labels, toggles, styling). - """ + """Adapter for basemap meridian/parallel dictionaries, emulating the subset +of cartopy Gridliner behavior needed by GeoAxes (labels, toggles, styling).""" def __init__(self, lonlines: GridlineDict | None, latlines: GridlineDict | None) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def labels_for_sides(self, *, bottom: bool | str | None=None, top: bool | str | None=None, left: bool | str | None=None, right: bool | str | None=None) -> dict[str, list[mtext.Text]]: @@ -396,12 +396,11 @@ class _BasemapGridlinerAdapter(_GridlinerAdapter): ... class _LonAxis(_GeoAxis): - """ - Axis with default longitude locator. - """ + """Axis with default longitude locator.""" axis_name = 'lon' def __init__(self, axes: 'GeoAxes') -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def _get_ticklocs(self, locator: mticker.Locator) -> np.ndarray: @@ -411,12 +410,11 @@ class _LonAxis(_GeoAxis): ... class _LatAxis(_GeoAxis): - """ - Axis with default latitude locator. - """ + """Axis with default latitude locator.""" axis_name = 'lat' def __init__(self, axes: 'GeoAxes', latmax: float=90) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def _get_ticklocs(self, locator: mticker.Locator) -> np.ndarray: @@ -445,31 +443,29 @@ include_false ... class GeoAxes(shared._SharedAxes, plot.PlotAxes): - """ - Axes subclass for plotting in geographic projections. Uses either cartopy - or basemap as a "backend". - - Note - ---- - This subclass uses longitude and latitude as the default coordinate system for all - plotting commands by internally passing ``transform=cartopy.crs.PlateCarree()`` to - cartopy commands and ``latlon=True`` to basemap commands. Also, when using basemap - as the "backend", plotting is still done "cartopy-style" by calling methods from - the axes instance rather than the `~mpl_toolkits.basemap.Basemap` instance. - - Important - --------- - This axes subclass can be used by passing ``proj='proj_name'`` - to axes-creation commands like `~ultraplot.figure.Figure.add_axes`, - `~ultraplot.figure.Figure.add_subplot`, and `~ultraplot.figure.Figure.subplots`, - where ``proj_name`` is a registered :ref:`PROJ projection name `. - You can also pass a `~cartopy.crs.Projection` or `~mpl_toolkits.basemap.Basemap` - instance instead of a projection name. Alternatively, you can pass any of the - matplotlib-recognized axes subclass names ``proj='cartopy'``, ``proj='geo'``, or - ``proj='geographic'`` with a `~cartopy.crs.Projection` `map_projection` keyword - argument, or pass ``proj='basemap'`` with a `~mpl_toolkits.basemap.Basemap` - `map_projection` keyword argument. - """ + """Axes subclass for plotting in geographic projections. Uses either cartopy +or basemap as a "backend". + +Note +---- +This subclass uses longitude and latitude as the default coordinate system for all +plotting commands by internally passing ``transform=cartopy.crs.PlateCarree()`` to +cartopy commands and ``latlon=True`` to basemap commands. Also, when using basemap +as the "backend", plotting is still done "cartopy-style" by calling methods from +the axes instance rather than the `~mpl_toolkits.basemap.Basemap` instance. + +Important +--------- +This axes subclass can be used by passing ``proj='proj_name'`` +to axes-creation commands like `~ultraplot.figure.Figure.add_axes`, +`~ultraplot.figure.Figure.add_subplot`, and `~ultraplot.figure.Figure.subplots`, +where ``proj_name`` is a registered :ref:`PROJ projection name `. +You can also pass a `~cartopy.crs.Projection` or `~mpl_toolkits.basemap.Basemap` +instance instead of a projection name. Alternatively, you can pass any of the +matplotlib-recognized axes subclass names ``proj='cartopy'``, ``proj='geo'``, or +``proj='geographic'`` with a `~cartopy.crs.Projection` `map_projection` keyword +argument, or pass ``proj='basemap'`` with a `~mpl_toolkits.basemap.Basemap` +`map_projection` keyword argument.""" def __init__(self, *args: Any, **kwargs: Any) -> None: """Parameters @@ -859,6 +855,7 @@ projected coordinates.""" @override def _sharex_setup(self, sharex: 'GeoAxes', *, labels: bool=True, limits: bool=True) -> None: + """Configure x-axis sharing for panels. See also `~CartesianAxes._sharex_setup`.""" ... def _toggle_ticks(self, label: Any, which: str) -> None: @@ -981,6 +978,18 @@ geo : optional @override def draw(self, renderer: Any=None, *args: Any, **kwargs: Any) -> None: + """Draw the Artist (and its children) using the given renderer. + +This has no effect if the artist is not visible (`.Artist.get_visible` +returns False). + +Parameters +---------- +renderer : `~matplotlib.backend_bases.RendererBase` subclass. + +Notes +----- +This method is overridden in the Artist subclasses.""" ... def _get_lonticklocs(self, which: str='major') -> np.ndarray: @@ -1433,12 +1442,12 @@ instance associated with this axes.""" @projection.setter def projection(self, map_projection: Any) -> None: + """The cartopy `~cartopy.crs.Projection` or basemap `~mpl_toolkits.basemap.Basemap` +instance associated with this axes.""" ... class _CartopyAxes(GeoAxes, _GeoAxes): - """ - Axes subclass for plotting cartopy projections. - """ + """Axes subclass for plotting cartopy projections.""" _name = 'cartopy' _name_aliases = ('geo', 'geographic') _proj_class = Projection @@ -1515,6 +1524,11 @@ projections. This was developed from `this cartopy example Sequence[float]: + """Get the extent (x0, x1, y0, y1) of the map in the given coordinate +system. + +If no crs is given, the returned extents' coordinate system will be +the CRS of this Axes.""" ... @override @@ -1527,18 +1541,40 @@ after the main axes has applied its aspect but before the panel axes are drawn." ... def get_tightbbox(self, renderer: Any, *args: Any, **kwargs: Any) -> Any: + """Extend the standard behaviour of +:func:`matplotlib.axes.Axes.get_tightbbox`. + +Adjust the axes aspect ratio and background patch location before +calculating the tight bounding box.""" ... def set_extent(self, extent: Sequence[float], crs: Any=None) -> Any: + """Set the extent (x0, x1, y0, y1) of the map in the given +coordinate system. + +If no crs is given, the extents' coordinate system will be assumed +to be the Geodetic version of this axes' projection. + +Parameters +---------- +extents + Tuple of floats representing the required extent (x0, x1, y0, y1).""" ... def set_global(self) -> Any: + """Set the extent of the Axes to the limits of the projection. + +Note +---- + In some cases where the projection has a limited sensible range + the ``set_global`` method does not actually make the whole globe + visible. Instead, the most appropriate extents will be used (e.g. + Ordnance Survey UK will set the extents to be around the British + Isles.""" ... class _BasemapAxes(GeoAxes): - """ - Axes subclass for plotting basemap projections. - """ + """Axes subclass for plotting basemap projections.""" _name = 'basemap' _proj_class = Basemap _proj_north = ('npaeqd', 'nplaea', 'npstere') diff --git a/ultraplot/axes/plot.pyi b/ultraplot/axes/plot.pyi index da28483aa..450cf496a 100644 --- a/ultraplot/axes/plot.pyi +++ b/ultraplot/axes/plot.pyi @@ -124,10 +124,8 @@ def _get_hist_colors(res: Incomplete, n: Incomplete) -> Incomplete: ... class PlotAxes(base.Axes): - """ - The second lowest-level `~matplotlib.axes.Axes` subclass used by ultraplot. - Implements all plotting overrides. - """ + """The second lowest-level `~matplotlib.axes.Axes` subclass used by ultraplot. +Implements all plotting overrides.""" def curved_quiver(self, x: np.ndarray, y: np.ndarray, u: np.ndarray, v: np.ndarray, linewidth: Optional[float]=None, color: Optional[Union[str, Any]]=None, cmap: Optional[Any]=None, norm: Optional[Any]=None, arrowsize: Optional[float]=None, arrowstyle: Optional[str]=None, transform: Optional[Any]=None, zorder: Optional[int]=None, start_points: Optional[np.ndarray]=None, scale: Optional[float]=None, grains: Optional[int]=None, density: Optional[int]=None, arrow_at_end: Optional[bool]=None, colorbar: Optional[str]=None, colorbar_kw: Optional[dict[str, Any]]=None) -> Incomplete: """Draws curved vector field arrows (streamlines with arrows) for 2D vector fields. @@ -2472,7 +2470,294 @@ See also -------- PlotAxes.plot PlotAxes.plotx -matplotlib.axes.Axes.plot""" +matplotlib.axes.Axes.plot + +Matplotlib documentation + + +Plot y versus x as lines and/or markers. + +Call signatures:: + + plot([x], y, [fmt], *, data=None, **kwargs) + plot([x], y, [fmt], [x2], y2, [fmt2], ..., **kwargs) + +The coordinates of the points or line nodes are given by *x*, *y*. + +The optional parameter *fmt* is a convenient way for defining basic +formatting like color, marker and linestyle. It's a shortcut string +notation described in the *Notes* section below. + +>>> plot(x, y) # plot x and y using default line style and color +>>> plot(x, y, 'bo') # plot x and y using blue circle markers +>>> plot(y) # plot y using x as index array 0..N-1 +>>> plot(y, 'r+') # ditto, but with red plusses + +You can use `.Line2D` properties as keyword arguments for more +control on the appearance. Line properties and *fmt* can be mixed. +The following two calls yield identical results: + +>>> plot(x, y, 'go--', linewidth=2, markersize=12) +>>> plot(x, y, color='green', marker='o', linestyle='dashed', +... linewidth=2, markersize=12) + +When conflicting with *fmt*, keyword arguments take precedence. + + +**Plotting labelled data** + +There's a convenient way for plotting objects with labelled data (i.e. +data that can be accessed by index ``obj['y']``). Instead of giving +the data in *x* and *y*, you can provide the object in the *data* +parameter and just give the labels for *x* and *y*:: + +>>> plot('xlabel', 'ylabel', data=obj) + +All indexable objects are supported. This could e.g. be a `dict`, a +`pandas.DataFrame` or a structured numpy array. + + +**Plotting multiple sets of data** + +There are various ways to plot multiple sets of data. + +- The most straight forward way is just to call `plot` multiple times. + Example: + + >>> plot(x1, y1, 'bo') + >>> plot(x2, y2, 'go') + +- If *x* and/or *y* are 2D arrays, a separate data set will be drawn + for every column. If both *x* and *y* are 2D, they must have the + same shape. If only one of them is 2D with shape (N, m) the other + must have length N and will be used for every data set m. + + Example: + + >>> x = [1, 2, 3] + >>> y = np.array([[1, 2], [3, 4], [5, 6]]) + >>> plot(x, y) + + is equivalent to: + + >>> for col in range(y.shape[1]): + ... plot(x, y[:, col]) + +- The third way is to specify multiple sets of *[x]*, *y*, *[fmt]* + groups:: + + >>> plot(x1, y1, 'g^', x2, y2, 'g-') + + In this case, any additional keyword argument applies to all + datasets. Also, this syntax cannot be combined with the *data* + parameter. + +By default, each line is assigned a different style specified by a +'style cycle'. The *fmt* and line property parameters are only +necessary if you want explicit deviations from these defaults. +Alternatively, you can also change the style cycle using +:rc:`axes.prop_cycle`. + + +Parameters +---------- +x, y : array-like or float + The horizontal / vertical coordinates of the data points. + *x* values are optional and default to ``range(len(y))``. + + Commonly, these parameters are 1D arrays. + + They can also be scalars, or two-dimensional (in that case, the + columns represent separate data sets). + + These arguments cannot be passed as keywords. + +fmt : str, optional + A format string, e.g. 'ro' for red circles. See the *Notes* + section for a full description of the format strings. + + Format strings are just an abbreviation for quickly setting + basic line properties. All of these and more can also be + controlled by keyword arguments. + + This argument cannot be passed as keyword. + +data : indexable object, optional + An object with labelled data. If given, provide the label names to + plot in *x* and *y*. + + .. note:: + Technically there's a slight ambiguity in calls where the + second label is a valid *fmt*. ``plot('n', 'o', data=obj)`` + could be ``plt(x, y)`` or ``plt(y, fmt)``. In such cases, + the former interpretation is chosen, but a warning is issued. + You may suppress the warning by adding an empty format string + ``plot('n', 'o', '', data=obj)``. + +Returns +------- +list of `.Line2D` + A list of lines representing the plotted data. + +Other Parameters +---------------- +scalex, scaley : bool, default: True + These parameters determine if the view limits are adapted to the + data limits. The values are passed on to + `~.axes.Axes.autoscale_view`. + +**kwargs : `~matplotlib.lines.Line2D` properties, optional + *kwargs* are used to specify properties like a line label (for + auto legends), linewidth, antialiasing, marker face color. + Example:: + + >>> plot([1, 2, 3], [1, 2, 3], 'go-', label='line 1', linewidth=2) + >>> plot([1, 2, 3], [1, 4, 9], 'rs', label='line 2') + + If you specify multiple lines with one plot call, the kwargs apply + to all those lines. In case the label object is iterable, each + element is used as labels for each set of data. + + Here is a list of available `.Line2D` properties: + + Properties: + agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image + alpha: float or None + animated: bool + antialiased or aa: bool + clip_box: `~matplotlib.transforms.BboxBase` or None + clip_on: bool + clip_path: Patch or (Path, Transform) or None + color or c: :mpltype:`color` + dash_capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} + dash_joinstyle: `.JoinStyle` or {'miter', 'round', 'bevel'} + dashes: sequence of floats (on/off ink in points) or (None, None) + data: (2, N) array or two 1D arrays + drawstyle or ds: {'default', 'steps', 'steps-pre', 'steps-mid', 'steps-post'}, default: 'default' + figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + fillstyle: {'full', 'left', 'right', 'bottom', 'top', 'none'} + gapcolor: :mpltype:`color` or None + gid: str + in_layout: bool + label: object + linestyle or ls: {'-', '--', '-.', ':', '', (offset, on-off-seq), ...} + linewidth or lw: float + marker: marker style string, `~.path.Path` or `~.markers.MarkerStyle` + markeredgecolor or mec: :mpltype:`color` + markeredgewidth or mew: float + markerfacecolor or mfc: :mpltype:`color` + markerfacecoloralt or mfcalt: :mpltype:`color` + markersize or ms: float + markevery: None or int or (int, int) or slice or list[int] or float or (float, float) or list[bool] + mouseover: bool + path_effects: list of `.AbstractPathEffect` + picker: float or callable[[Artist, Event], tuple[bool, dict]] + pickradius: float + rasterized: bool + sketch_params: (scale: float, length: float, randomness: float) + snap: bool or None + solid_capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} + solid_joinstyle: `.JoinStyle` or {'miter', 'round', 'bevel'} + transform: unknown + url: str + visible: bool + xdata: 1D array + ydata: 1D array + zorder: float + +See Also +-------- +scatter : XY scatter plot with markers of varying size and/or color ( + sometimes also called bubble chart). + +Notes +----- +**Format Strings** + +A format string consists of a part for color, marker and line:: + + fmt = '[marker][line][color]' + +Each of them is optional. If not provided, the value from the style +cycle is used. Exception: If ``line`` is given, but no ``marker``, +the data will be a line without markers. + +Other combinations such as ``[color][marker][line]`` are also +supported, but note that their parsing may be ambiguous. + +**Markers** + +============= =============================== +character description +============= =============================== +``'.'`` point marker +``','`` pixel marker +``'o'`` circle marker +``'v'`` triangle_down marker +``'^'`` triangle_up marker +``'<'`` triangle_left marker +``'>'`` triangle_right marker +``'1'`` tri_down marker +``'2'`` tri_up marker +``'3'`` tri_left marker +``'4'`` tri_right marker +``'8'`` octagon marker +``'s'`` square marker +``'p'`` pentagon marker +``'P'`` plus (filled) marker +``'*'`` star marker +``'h'`` hexagon1 marker +``'H'`` hexagon2 marker +``'+'`` plus marker +``'x'`` x marker +``'X'`` x (filled) marker +``'D'`` diamond marker +``'d'`` thin_diamond marker +``'|'`` vline marker +``'_'`` hline marker +============= =============================== + +**Line Styles** + +============= =============================== +character description +============= =============================== +``'-'`` solid line style +``'--'`` dashed line style +``'-.'`` dash-dot line style +``':'`` dotted line style +============= =============================== + +Example format strings:: + + 'b' # blue markers with default shape + 'or' # red circles + '-g' # green solid line + '--' # dashed line with default color + '^k:' # black triangle_up markers connected by a dotted line + +**Colors** + +The supported color abbreviations are the single letter codes + +============= =============================== +character color +============= =============================== +``'b'`` blue +``'g'`` green +``'r'`` red +``'c'`` cyan +``'m'`` magenta +``'y'`` yellow +``'k'`` black +``'w'`` white +============= =============================== + +and the ``'CN'`` colors that index into the default property cycle. + +If the color is the only part of the format string, you can +additionally use any `matplotlib.colors` spec, e.g. full names +(``'green'``) or hex strings (``'#008000'``).""" ... def plotx(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -2733,7 +3018,72 @@ See also -------- PlotAxes.step PlotAxes.stepx -matplotlib.axes.Axes.step""" +matplotlib.axes.Axes.step + +Matplotlib documentation + + +Make a step plot. + +Call signatures:: + + step(x, y, [fmt], *, data=None, where='pre', **kwargs) + step(x, y, [fmt], x2, y2, [fmt2], ..., *, where='pre', **kwargs) + +This is just a thin wrapper around `.plot` which changes some +formatting options. Most of the concepts and parameters of plot can be +used here as well. + +.. note:: + + This method uses a standard plot with a step drawstyle: The *x* + values are the reference positions and steps extend left/right/both + directions depending on *where*. + + For the common case where you know the values and edges of the + steps, use `~.Axes.stairs` instead. + +Parameters +---------- +x : array-like + 1D sequence of x positions. It is assumed, but not checked, that + it is uniformly increasing. + +y : array-like + 1D sequence of y levels. + +fmt : str, optional + A format string, e.g. 'g' for a green line. See `.plot` for a more + detailed description. + + Note: While full format strings are accepted, it is recommended to + only specify the color. Line styles are currently ignored (use + the keyword argument *linestyle* instead). Markers are accepted + and plotted on the given positions, however, this is a rarely + needed feature for step plots. + +where : {'pre', 'post', 'mid'}, default: 'pre' + Define where the steps should be placed: + + - 'pre': The y value is continued constantly to the left from + every *x* position, i.e. the interval ``(x[i-1], x[i]]`` has the + value ``y[i]``. + - 'post': The y value is continued constantly to the right from + every *x* position, i.e. the interval ``[x[i], x[i+1])`` has the + value ``y[i]``. + - 'mid': Steps occur half-way between the *x* positions. + +data : indexable object, optional + An object with labelled data. If given, provide the label names to + plot in *x* and *y*. + +**kwargs + Additional parameters are the same as those for `.plot`. + +Returns +------- +list of `.Line2D` + Objects representing the plotted data.""" ... def stepx(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -2894,7 +3244,89 @@ legend : bool, int, or str, optional legend_kw : dict-like, optional Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. **kwargs - Passed to `~matplotlib.axes.Axes.stem`.""" + Passed to `~matplotlib.axes.Axes.stem`. + +Matplotlib documentation + + +Create a stem plot. + +A stem plot draws lines perpendicular to a baseline at each location +*locs* from the baseline to *heads*, and places a marker there. For +vertical stem plots (the default), the *locs* are *x* positions, and +the *heads* are *y* values. For horizontal stem plots, the *locs* are +*y* positions, and the *heads* are *x* values. + +Call signature:: + + stem([locs,] heads, linefmt=None, markerfmt=None, basefmt=None) + +The *locs*-positions are optional. *linefmt* may be provided as +positional, but all other formats must be provided as keyword +arguments. + +Parameters +---------- +locs : array-like, default: (0, 1, ..., len(heads) - 1) + For vertical stem plots, the x-positions of the stems. + For horizontal stem plots, the y-positions of the stems. + +heads : array-like + For vertical stem plots, the y-values of the stem heads. + For horizontal stem plots, the x-values of the stem heads. + +linefmt : str, optional + A string defining the color and/or linestyle of the vertical lines: + + ========= ============= + Character Line Style + ========= ============= + ``'-'`` solid line + ``'--'`` dashed line + ``'-.'`` dash-dot line + ``':'`` dotted line + ========= ============= + + Default: 'C0-', i.e. solid line with the first color of the color + cycle. + + Note: Markers specified through this parameter (e.g. 'x') will be + silently ignored. Instead, markers should be specified using + *markerfmt*. + +markerfmt : str, optional + A string defining the color and/or shape of the markers at the stem + heads. If the marker is not given, use the marker 'o', i.e. filled + circles. If the color is not given, use the color from *linefmt*. + +basefmt : str, default: 'C3-' ('C2-' in classic mode) + A format string defining the properties of the baseline. + +orientation : {'vertical', 'horizontal'}, default: 'vertical' + The orientation of the stems. + +bottom : float, default: 0 + The y/x-position of the baseline (depending on *orientation*). + +label : str, optional + The label to use for the stems in legends. + +data : indexable object, optional + If given, all parameters also accept a string ``s``, which is + interpreted as ``data[s]`` if ``s`` is a key in ``data``. + +Returns +------- +`.StemContainer` + The container may be treated like a tuple + (*markerline*, *stemlines*, *baseline*) + +Notes +----- +.. seealso:: + The MATLAB function + `stem `_ + which inspired this method.""" ... def stemx(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -3589,7 +4021,197 @@ See also -------- PlotAxes.scatter PlotAxes.scatterx -matplotlib.axes.Axes.scatter""" +matplotlib.axes.Axes.scatter + +Matplotlib documentation + + +A scatter plot of *y* vs. *x* with varying marker size and/or color. + +Parameters +---------- +x, y : float or array-like, shape (n, ) + The data positions. + +s : float or array-like, shape (n, ), optional + The marker size in points**2 (typographic points are 1/72 in.). + Default is ``rcParams['lines.markersize'] ** 2``. + + The linewidth and edgecolor can visually interact with the marker + size, and can lead to artifacts if the marker size is smaller than + the linewidth. + + If the linewidth is greater than 0 and the edgecolor is anything + but *'none'*, then the effective size of the marker will be + increased by half the linewidth because the stroke will be centered + on the edge of the shape. + + To eliminate the marker edge either set *linewidth=0* or + *edgecolor='none'*. + +c : array-like or list of :mpltype:`color` or :mpltype:`color`, optional + The marker colors. Possible values: + + - A scalar or sequence of n numbers to be mapped to colors using + *cmap* and *norm*. + - A 2D array in which the rows are RGB or RGBA. + - A sequence of colors of length n. + - A single color format string. + + Note that *c* should not be a single numeric RGB or RGBA sequence + because that is indistinguishable from an array of values to be + colormapped. If you want to specify the same RGB or RGBA value for + all points, use a 2D array with a single row. Otherwise, + value-matching will have precedence in case of a size matching with + *x* and *y*. + + If you wish to specify a single color for all points + prefer the *color* keyword argument. + + Defaults to `None`. In that case the marker color is determined + by the value of *color*, *facecolor* or *facecolors*. In case + those are not specified or `None`, the marker color is determined + by the next color of the ``Axes``' current "shape and fill" color + cycle. This cycle defaults to :rc:`axes.prop_cycle`. + +marker : `~.markers.MarkerStyle`, default: :rc:`scatter.marker` + The marker style. *marker* can be either an instance of the class + or the text shorthand for a particular marker. + See :mod:`matplotlib.markers` for more information about marker + styles. + +cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap` + The Colormap instance or registered colormap name used to map scalar data + to colors. + + This parameter is ignored if *c* is RGB(A). + +norm : str or `~matplotlib.colors.Normalize`, optional + The normalization method used to scale scalar data to the [0, 1] range + before mapping to colors using *cmap*. By default, a linear scaling is + used, mapping the lowest value to 0 and the highest to 1. + + If given, this can be one of the following: + + - An instance of `.Normalize` or one of its subclasses + (see :ref:`colormapnorms`). + - A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For a + list of available scales, call `matplotlib.scale.get_scale_names()`. + In that case, a suitable `.Normalize` subclass is dynamically generated + and instantiated. + + This parameter is ignored if *c* is RGB(A). + +vmin, vmax : float, optional + When using scalar data and no explicit *norm*, *vmin* and *vmax* define + the data range that the colormap covers. By default, the colormap covers + the complete value range of the supplied data. It is an error to use + *vmin*/*vmax* when a *norm* instance is given (but using a `str` *norm* + name together with *vmin*/*vmax* is acceptable). + + This parameter is ignored if *c* is RGB(A). + +alpha : float, default: None + The alpha blending value, between 0 (transparent) and 1 (opaque). + +linewidths : float or array-like, default: :rc:`lines.linewidth` + The linewidth of the marker edges. Note: The default *edgecolors* + is 'face'. You may want to change this as well. + +edgecolors : {'face', 'none', *None*} or :mpltype:`color` or list of :mpltype:`color`, default: :rc:`scatter.edgecolors` + The edge color of the marker. Possible values: + + - 'face': The edge color will always be the same as the face color. + - 'none': No patch boundary will be drawn. + - A color or sequence of colors. + + For non-filled markers, *edgecolors* is ignored. Instead, the color + is determined like with 'face', i.e. from *c*, *colors*, or + *facecolors*. + +colorizer : `~matplotlib.colorizer.Colorizer` or None, default: None + The Colorizer object used to map color to data. If None, a Colorizer + object is created from a *norm* and *cmap*. + + This parameter is ignored if *c* is RGB(A). + +plotnonfinite : bool, default: False + Whether to plot points with nonfinite *c* (i.e. ``inf``, ``-inf`` + or ``nan``). If ``True`` the points are drawn with the *bad* + colormap color (see `.Colormap.set_bad`). + +Returns +------- +`~matplotlib.collections.PathCollection` + +Other Parameters +---------------- +data : indexable object, optional + If given, the following parameters also accept a string ``s``, which is + interpreted as ``data[s]`` if ``s`` is a key in ``data``: + + *x*, *y*, *s*, *linewidths*, *edgecolors*, *c*, *facecolor*, *facecolors*, *color* +**kwargs : `~matplotlib.collections.PathCollection` properties + Properties: + agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image + alpha: array-like or float or None + animated: bool + antialiased or aa or antialiaseds: bool or list of bools + array: array-like or None + capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} + clim: (vmin: float, vmax: float) + clip_box: `~matplotlib.transforms.BboxBase` or None + clip_on: bool + clip_path: Patch or (Path, Transform) or None + cmap: `.Colormap` or str or None + color: :mpltype:`color` or list of RGBA tuples + edgecolor or ec or edgecolors: :mpltype:`color` or list of :mpltype:`color` or 'face' + facecolor or facecolors or fc: :mpltype:`color` or list of :mpltype:`color` + figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + gid: str + hatch: {'/', '\\\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'} + hatch_linewidth: unknown + in_layout: bool + joinstyle: `.JoinStyle` or {'miter', 'round', 'bevel'} + label: object + linestyle or dashes or linestyles or ls: str or tuple or list thereof + linewidth or linewidths or lw: float or list of floats + mouseover: bool + norm: `.Normalize` or str or None + offset_transform or transOffset: `.Transform` + offsets: (N, 2) or (2,) array-like + path_effects: list of `.AbstractPathEffect` + paths: unknown + picker: None or bool or float or callable + pickradius: float + rasterized: bool + sizes: `numpy.ndarray` or None + sketch_params: (scale: float, length: float, randomness: float) + snap: bool or None + transform: `~matplotlib.transforms.Transform` + url: str + urls: list of str or None + visible: bool + zorder: float + +See Also +-------- +plot : To plot scatter plots when markers are identical in size and + color. + +Notes +----- +* The `.plot` function will be faster for scatterplots where markers + don't vary in size or color. + +* Any or all of *x*, *y*, *s*, and *c* may be masked arrays, in which + case all masks will be combined and only unmasked points will be + plotted. + +* Fundamentally, scatter works with 1D arrays; *x*, *y*, *s*, and *c* + may be input as N-D arrays, but within scatter they will be + flattened. The exception is *c*, which will be flattened only if its + size matches the size of *x* and *y*.""" ... def scatterx(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -4259,7 +4881,136 @@ PlotAxes.areax PlotAxes.fill_between PlotAxes.fill_betweenx matplotlib.axes.Axes.fill_between -matplotlib.axes.Axes.fill_betweenx""" +matplotlib.axes.Axes.fill_betweenx + +Matplotlib documentation + + +Fill the area between two horizontal curves. + +The curves are defined by the points (*x*, *y1*) and (*x*, +*y2*). This creates one or multiple polygons describing the filled +area. + +You may exclude some horizontal sections from filling using *where*. + +By default, the edges connect the given points directly. Use *step* +if the filling should be a step function, i.e. constant in between +*x*. + +Parameters +---------- +x : array-like + The x coordinates of the nodes defining the curves. + +y1 : array-like or float + The y coordinates of the nodes defining the first curve. + +y2 : array-like or float, default: 0 + The y coordinates of the nodes defining the second curve. + +where : array-like of bool, optional + Define *where* to exclude some horizontal regions from being filled. + The filled regions are defined by the coordinates ``x[where]``. + More precisely, fill between ``x[i]`` and ``x[i+1]`` if + ``where[i] and where[i+1]``. Note that this definition implies + that an isolated *True* value between two *False* values in *where* + will not result in filling. Both sides of the *True* position + remain unfilled due to the adjacent *False* values. + +interpolate : bool, default: False + This option is only relevant if *where* is used and the two curves + are crossing each other. + + Semantically, *where* is often used for *y1* > *y2* or + similar. By default, the nodes of the polygon defining the filled + region will only be placed at the positions in the *x* array. + Such a polygon cannot describe the above semantics close to the + intersection. The x-sections containing the intersection are + simply clipped. + + Setting *interpolate* to *True* will calculate the actual + intersection point and extend the filled region up to this point. + +step : {'pre', 'post', 'mid'}, optional + Define *step* if the filling should be a step function, + i.e. constant in between *x*. The value determines where the + step will occur: + + - 'pre': The y value is continued constantly to the left from + every *x* position, i.e. the interval ``(x[i-1], x[i]]`` + has the value ``y[i]``. + - 'post': The y value is continued constantly to the right from + every *x* position, i.e. the interval ``[x[i], x[i+1])`` + has the value ``y[i]``. + - 'mid': Steps occur half-way between the *x* positions. + +Returns +------- +`.FillBetweenPolyCollection` + A `.FillBetweenPolyCollection` containing the plotted polygons. + +Other Parameters +---------------- +data : indexable object, optional + If given, the following parameters also accept a string ``s``, which is + interpreted as ``data[s]`` if ``s`` is a key in ``data``: + + *x*, *y1*, *y2*, *where* + +**kwargs + All other keyword arguments are passed on to + `.FillBetweenPolyCollection`. They control the `.Polygon` properties: + + Properties: + agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image + alpha: array-like or float or None + animated: bool + antialiased or aa or antialiaseds: bool or list of bools + array: array-like or None + capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} + clim: (vmin: float, vmax: float) + clip_box: `~matplotlib.transforms.BboxBase` or None + clip_on: bool + clip_path: Patch or (Path, Transform) or None + cmap: `.Colormap` or str or None + color: :mpltype:`color` or list of RGBA tuples + data: array-like + edgecolor or ec or edgecolors: :mpltype:`color` or list of :mpltype:`color` or 'face' + facecolor or facecolors or fc: :mpltype:`color` or list of :mpltype:`color` + figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + gid: str + hatch: {'/', '\\\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'} + hatch_linewidth: unknown + in_layout: bool + joinstyle: `.JoinStyle` or {'miter', 'round', 'bevel'} + label: object + linestyle or dashes or linestyles or ls: str or tuple or list thereof + linewidth or linewidths or lw: float or list of floats + mouseover: bool + norm: `.Normalize` or str or None + offset_transform or transOffset: `.Transform` + offsets: (N, 2) or (2,) array-like + path_effects: list of `.AbstractPathEffect` + paths: list of array-like + picker: None or bool or float or callable + pickradius: float + rasterized: bool + sizes: `numpy.ndarray` or None + sketch_params: (scale: float, length: float, randomness: float) + snap: bool or None + transform: `~matplotlib.transforms.Transform` + url: str + urls: list of str or None + verts: list of array-like + verts_and_codes: unknown + visible: bool + zorder: float + +See Also +-------- +fill_between : Fill between two sets of y-values. +fill_betweenx : Fill between two sets of x-values.""" ... def fill_betweenx(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -4375,7 +5126,136 @@ PlotAxes.areax PlotAxes.fill_between PlotAxes.fill_betweenx matplotlib.axes.Axes.fill_between -matplotlib.axes.Axes.fill_betweenx""" +matplotlib.axes.Axes.fill_betweenx + +Matplotlib documentation + + +Fill the area between two vertical curves. + +The curves are defined by the points (*y*, *x1*) and (*y*, +*x2*). This creates one or multiple polygons describing the filled +area. + +You may exclude some vertical sections from filling using *where*. + +By default, the edges connect the given points directly. Use *step* +if the filling should be a step function, i.e. constant in between +*y*. + +Parameters +---------- +y : array-like + The y coordinates of the nodes defining the curves. + +x1 : array-like or float + The x coordinates of the nodes defining the first curve. + +x2 : array-like or float, default: 0 + The x coordinates of the nodes defining the second curve. + +where : array-like of bool, optional + Define *where* to exclude some vertical regions from being filled. + The filled regions are defined by the coordinates ``y[where]``. + More precisely, fill between ``y[i]`` and ``y[i+1]`` if + ``where[i] and where[i+1]``. Note that this definition implies + that an isolated *True* value between two *False* values in *where* + will not result in filling. Both sides of the *True* position + remain unfilled due to the adjacent *False* values. + +interpolate : bool, default: False + This option is only relevant if *where* is used and the two curves + are crossing each other. + + Semantically, *where* is often used for *x1* > *x2* or + similar. By default, the nodes of the polygon defining the filled + region will only be placed at the positions in the *y* array. + Such a polygon cannot describe the above semantics close to the + intersection. The y-sections containing the intersection are + simply clipped. + + Setting *interpolate* to *True* will calculate the actual + intersection point and extend the filled region up to this point. + +step : {'pre', 'post', 'mid'}, optional + Define *step* if the filling should be a step function, + i.e. constant in between *y*. The value determines where the + step will occur: + + - 'pre': The x value is continued constantly to the left from + every *y* position, i.e. the interval ``(y[i-1], y[i]]`` + has the value ``x[i]``. + - 'post': The y value is continued constantly to the right from + every *y* position, i.e. the interval ``[y[i], y[i+1])`` + has the value ``x[i]``. + - 'mid': Steps occur half-way between the *y* positions. + +Returns +------- +`.FillBetweenPolyCollection` + A `.FillBetweenPolyCollection` containing the plotted polygons. + +Other Parameters +---------------- +data : indexable object, optional + If given, the following parameters also accept a string ``s``, which is + interpreted as ``data[s]`` if ``s`` is a key in ``data``: + + *y*, *x1*, *x2*, *where* + +**kwargs + All other keyword arguments are passed on to + `.FillBetweenPolyCollection`. They control the `.Polygon` properties: + + Properties: + agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image + alpha: array-like or float or None + animated: bool + antialiased or aa or antialiaseds: bool or list of bools + array: array-like or None + capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} + clim: (vmin: float, vmax: float) + clip_box: `~matplotlib.transforms.BboxBase` or None + clip_on: bool + clip_path: Patch or (Path, Transform) or None + cmap: `.Colormap` or str or None + color: :mpltype:`color` or list of RGBA tuples + data: array-like + edgecolor or ec or edgecolors: :mpltype:`color` or list of :mpltype:`color` or 'face' + facecolor or facecolors or fc: :mpltype:`color` or list of :mpltype:`color` + figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + gid: str + hatch: {'/', '\\\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'} + hatch_linewidth: unknown + in_layout: bool + joinstyle: `.JoinStyle` or {'miter', 'round', 'bevel'} + label: object + linestyle or dashes or linestyles or ls: str or tuple or list thereof + linewidth or linewidths or lw: float or list of floats + mouseover: bool + norm: `.Normalize` or str or None + offset_transform or transOffset: `.Transform` + offsets: (N, 2) or (2,) array-like + path_effects: list of `.AbstractPathEffect` + paths: list of array-like + picker: None or bool or float or callable + pickradius: float + rasterized: bool + sizes: `numpy.ndarray` or None + sketch_params: (scale: float, length: float, randomness: float) + snap: bool or None + transform: `~matplotlib.transforms.Transform` + url: str + urls: list of str or None + verts: list of array-like + verts_and_codes: unknown + visible: bool + zorder: float + +See Also +-------- +fill_between : Fill between two sets of y-values. +fill_betweenx : Fill between two sets of x-values.""" ... def graph(self, g: Incomplete, layout: Union[str, dict, Callable]=None, nodes: Union[None, bool, Iterable]=None, edges: Union[None, bool, Iterable]=None, labels: Union[None, bool, Iterable]=None, layout_kw: Optional[dict]=None, node_kw: Optional[dict]=None, edge_kw: Optional[dict]=None, label_kw: Optional[dict]=None, rescale: Union[None, bool]=None) -> Incomplete: @@ -4609,7 +5489,179 @@ See also PlotAxes.bar PlotAxes.barh matplotlib.axes.Axes.bar -matplotlib.axes.Axes.barh""" +matplotlib.axes.Axes.barh + +Matplotlib documentation + + +Make a bar plot. + +The bars are positioned at *x* with the given *align*\\ment. Their +dimensions are given by *height* and *width*. The vertical baseline +is *bottom* (default 0). + +Many parameters can take either a single value applying to all bars +or a sequence of values, one for each bar. + +Parameters +---------- +x : float or array-like + The x coordinates of the bars. See also *align* for the + alignment of the bars to the coordinates. + + Bars are often used for categorical data, i.e. string labels below + the bars. You can provide a list of strings directly to *x*. + ``bar(['A', 'B', 'C'], [1, 2, 3])`` is often a shorter and more + convenient notation compared to + ``bar(range(3), [1, 2, 3], tick_label=['A', 'B', 'C'])``. They are + equivalent as long as the names are unique. The explicit *tick_label* + notation draws the names in the sequence given. However, when having + duplicate values in categorical *x* data, these values map to the same + numerical x coordinate, and hence the corresponding bars are drawn on + top of each other. + +height : float or array-like + The height(s) of the bars. + + Note that if *bottom* has units (e.g. datetime), *height* should be in + units that are a difference from the value of *bottom* (e.g. timedelta). + +width : float or array-like, default: 0.8 + The width(s) of the bars. + + Note that if *x* has units (e.g. datetime), then *width* should be in + units that are a difference (e.g. timedelta) around the *x* values. + +bottom : float or array-like, default: 0 + The y coordinate(s) of the bottom side(s) of the bars. + + Note that if *bottom* has units, then the y-axis will get a Locator and + Formatter appropriate for the units (e.g. dates, or categorical). + +align : {'center', 'edge'}, default: 'center' + Alignment of the bars to the *x* coordinates: + + - 'center': Center the base on the *x* positions. + - 'edge': Align the left edges of the bars with the *x* positions. + + To align the bars on the right edge pass a negative *width* and + ``align='edge'``. + +Returns +------- +`.BarContainer` + Container with all the bars and optionally errorbars. + +Other Parameters +---------------- +color : :mpltype:`color` or list of :mpltype:`color`, optional + The colors of the bar faces. This is an alias for *facecolor*. + If both are given, *facecolor* takes precedence. + +facecolor : :mpltype:`color` or list of :mpltype:`color`, optional + The colors of the bar faces. + If both *color* and *facecolor are given, *facecolor* takes precedence. + +edgecolor : :mpltype:`color` or list of :mpltype:`color`, optional + The colors of the bar edges. + +linewidth : float or array-like, optional + Width of the bar edge(s). If 0, don't draw edges. + +tick_label : str or list of str, optional + The tick labels of the bars. + Default: None (Use default numeric labels.) + +label : str or list of str, optional + A single label is attached to the resulting `.BarContainer` as a + label for the whole dataset. + If a list is provided, it must be the same length as *x* and + labels the individual bars. Repeated labels are not de-duplicated + and will cause repeated label entries, so this is best used when + bars also differ in style (e.g., by passing a list to *color*.) + +xerr, yerr : float or array-like of shape(N,) or shape(2, N), optional + If not *None*, add horizontal / vertical errorbars to the bar tips. + The values are +/- sizes relative to the data: + + - scalar: symmetric +/- values for all bars + - shape(N,): symmetric +/- values for each bar + - shape(2, N): Separate - and + values for each bar. First row + contains the lower errors, the second row contains the upper + errors. + - *None*: No errorbar. (Default) + + See :doc:`/gallery/statistics/errorbar_features` for an example on + the usage of *xerr* and *yerr*. + +ecolor : :mpltype:`color` or list of :mpltype:`color`, default: 'black' + The line color of the errorbars. + +capsize : float, default: :rc:`errorbar.capsize` + The length of the error bar caps in points. + +error_kw : dict, optional + Dictionary of keyword arguments to be passed to the + `~.Axes.errorbar` method. Values of *ecolor* or *capsize* defined + here take precedence over the independent keyword arguments. + +log : bool, default: False + If *True*, set the y-axis to be log scale. + +data : indexable object, optional + If given, all parameters also accept a string ``s``, which is + interpreted as ``data[s]`` if ``s`` is a key in ``data``. + +**kwargs : `.Rectangle` properties + +Properties: + agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image + alpha: float or None + angle: unknown + animated: bool + antialiased or aa: bool or None + bounds: (left, bottom, width, height) + capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} + clip_box: `~matplotlib.transforms.BboxBase` or None + clip_on: bool + clip_path: Patch or (Path, Transform) or None + color: :mpltype:`color` + edgecolor or ec: :mpltype:`color` or None + facecolor or fc: :mpltype:`color` or None + figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + fill: bool + gid: str + hatch: {'/', '\\\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'} + hatch_linewidth: unknown + height: unknown + in_layout: bool + joinstyle: `.JoinStyle` or {'miter', 'round', 'bevel'} + label: object + linestyle or ls: {'-', '--', '-.', ':', '', (offset, on-off-seq), ...} + linewidth or lw: float or None + mouseover: bool + path_effects: list of `.AbstractPathEffect` + picker: None or bool or float or callable + rasterized: bool + sketch_params: (scale: float, length: float, randomness: float) + snap: bool or None + transform: `~matplotlib.transforms.Transform` + url: str + visible: bool + width: unknown + x: unknown + xy: (float, float) + y: unknown + zorder: float + +See Also +-------- +barh : Plot a horizontal bar plot. + +Notes +----- +Stacked bars can be achieved by passing individual *bottom* values per +bar. See :doc:`/gallery/lines_bars_and_markers/bar_stacked`.""" ... def barh(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -4782,47 +5834,216 @@ See also PlotAxes.bar PlotAxes.barh matplotlib.axes.Axes.bar -matplotlib.axes.Axes.barh""" - ... +matplotlib.axes.Axes.barh - def pie(self, x: Incomplete, explode: Incomplete, *, labelpad: Incomplete=None, labeldistance: Incomplete=None, **kwargs: Incomplete) -> Incomplete: - """Plot a pie chart. +Matplotlib documentation + + +Make a horizontal bar plot. + +The bars are positioned at *y* with the given *align*\\ment. Their +dimensions are given by *width* and *height*. The horizontal baseline +is *left* (default 0). + +Many parameters can take either a single value applying to all bars +or a sequence of values, one for each bar. Parameters ---------- -*args : y or x, y - The data passed as positional or keyword arguments. Interpreted as follows: +y : float or array-like + The y coordinates of the bars. See also *align* for the + alignment of the bars to the coordinates. - * If only `y` coordinates are passed, try to infer the `x` coordinates - from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the - :class:`~xarray.DataArray` coordinates. Otherwise, the `x` coordinates - are ``np.arange(0, y.shape[0])``. - * If the `y` coordinates are a 2D array, plot each column of data in succession - (except where each column of data represents a statistical distribution, as with - ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. -data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally - be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` - Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, - legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + Bars are often used for categorical data, i.e. string labels below + the bars. You can provide a list of strings directly to *y*. + ``barh(['A', 'B', 'C'], [1, 2, 3])`` is often a shorter and more + convenient notation compared to + ``barh(range(3), [1, 2, 3], tick_label=['A', 'B', 'C'])``. They are + equivalent as long as the names are unique. The explicit *tick_label* + notation draws the names in the sequence given. However, when having + duplicate values in categorical *y* data, these values map to the same + numerical y coordinate, and hence the corresponding bars are drawn on + top of each other. -Other parameters ----------------- -cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. - If the returned cycler is unchanged from the current cycler, the axes - cycler will not be reset to its first position. To disable property cycling - and just use black for the default color, use ``cycle=False``, ``cycle='none'``, +width : float or array-like + The width(s) of the bars. + + Note that if *left* has units (e.g. datetime), *width* should be in + units that are a difference from the value of *left* (e.g. timedelta). + +height : float or array-like, default: 0.8 + The heights of the bars. + + Note that if *y* has units (e.g. datetime), then *height* should be in + units that are a difference (e.g. timedelta) around the *y* values. + +left : float or array-like, default: 0 + The x coordinates of the left side(s) of the bars. + + Note that if *left* has units, then the x-axis will get a Locator and + Formatter appropriate for the units (e.g. dates, or categorical). + +align : {'center', 'edge'}, default: 'center' + Alignment of the base to the *y* coordinates*: + + - 'center': Center the bars on the *y* positions. + - 'edge': Align the bottom edges of the bars with the *y* + positions. + + To align the bars on the top edge pass a negative *height* and + ``align='edge'``. + +Returns +------- +`.BarContainer` + Container with all the bars and optionally errorbars. + +Other Parameters +---------------- +color : :mpltype:`color` or list of :mpltype:`color`, optional + The colors of the bar faces. + +edgecolor : :mpltype:`color` or list of :mpltype:`color`, optional + The colors of the bar edges. + +linewidth : float or array-like, optional + Width of the bar edge(s). If 0, don't draw edges. + +tick_label : str or list of str, optional + The tick labels of the bars. + Default: None (Use default numeric labels.) + +label : str or list of str, optional + A single label is attached to the resulting `.BarContainer` as a + label for the whole dataset. + If a list is provided, it must be the same length as *y* and + labels the individual bars. Repeated labels are not de-duplicated + and will cause repeated label entries, so this is best used when + bars also differ in style (e.g., by passing a list to *color*.) + +xerr, yerr : float or array-like of shape(N,) or shape(2, N), optional + If not *None*, add horizontal / vertical errorbars to the bar tips. + The values are +/- sizes relative to the data: + + - scalar: symmetric +/- values for all bars + - shape(N,): symmetric +/- values for each bar + - shape(2, N): Separate - and + values for each bar. First row + contains the lower errors, the second row contains the upper + errors. + - *None*: No errorbar. (default) + + See :doc:`/gallery/statistics/errorbar_features` for an example on + the usage of *xerr* and *yerr*. + +ecolor : :mpltype:`color` or list of :mpltype:`color`, default: 'black' + The line color of the errorbars. + +capsize : float, default: :rc:`errorbar.capsize` + The length of the error bar caps in points. + +error_kw : dict, optional + Dictionary of keyword arguments to be passed to the + `~.Axes.errorbar` method. Values of *ecolor* or *capsize* defined + here take precedence over the independent keyword arguments. + +log : bool, default: False + If ``True``, set the x-axis to be log scale. + +data : indexable object, optional + If given, all parameters also accept a string ``s``, which is + interpreted as ``data[s]`` if ``s`` is a key in ``data``. + +**kwargs : `.Rectangle` properties + +Properties: + agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image + alpha: float or None + angle: unknown + animated: bool + antialiased or aa: bool or None + bounds: (left, bottom, width, height) + capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} + clip_box: `~matplotlib.transforms.BboxBase` or None + clip_on: bool + clip_path: Patch or (Path, Transform) or None + color: :mpltype:`color` + edgecolor or ec: :mpltype:`color` or None + facecolor or fc: :mpltype:`color` or None + figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + fill: bool + gid: str + hatch: {'/', '\\\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'} + hatch_linewidth: unknown + height: unknown + in_layout: bool + joinstyle: `.JoinStyle` or {'miter', 'round', 'bevel'} + label: object + linestyle or ls: {'-', '--', '-.', ':', '', (offset, on-off-seq), ...} + linewidth or lw: float or None + mouseover: bool + path_effects: list of `.AbstractPathEffect` + picker: None or bool or float or callable + rasterized: bool + sketch_params: (scale: float, length: float, randomness: float) + snap: bool or None + transform: `~matplotlib.transforms.Transform` + url: str + visible: bool + width: unknown + x: unknown + xy: (float, float) + y: unknown + zorder: float + +See Also +-------- +bar : Plot a vertical bar plot. + +Notes +----- +Stacked bars can be achieved by passing individual *left* values per +bar. See +:doc:`/gallery/lines_bars_and_markers/horizontal_barchart_distribution`.""" + ... + + def pie(self, x: Incomplete, explode: Incomplete, *, labelpad: Incomplete=None, labeldistance: Incomplete=None, **kwargs: Incomplete) -> Incomplete: + """Plot a pie chart. + +Parameters +---------- +*args : y or x, y + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `y` coordinates are passed, try to infer the `x` coordinates + from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the + :class:`~xarray.DataArray` coordinates. Otherwise, the `x` coordinates + are ``np.arange(0, y.shape[0])``. + * If the `y` coordinates are a 2D array, plot each column of data in succession + (except where each column of data represents a statistical distribution, as with + ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). + * If any arguments are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. + A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. +data : dict-like, optional + A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or + `~xarray.Dataset`). If passed, each data argument can optionally + be a string `key` and the arrays used for plotting are retrieved + with ``data[key]``. This is a `native matplotlib feature + `__. +autoformat : bool, default: :rc:`autoformat` + Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, + legend titles, and colorbar labels are automatically configured when a + `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` + is passed to the plotting command. Formatting of `pint.Quantity` + unit strings is controlled by :rc:`unitformat`. + +Other parameters +---------------- +cycle : cycle-spec, optional + The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + If the returned cycler is unchanged from the current cycler, the axes + cycler will not be reset to its first position. To disable property cycling + and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional @@ -4859,7 +6080,125 @@ labelpad, labeldistance : float, optional See also -------- -matplotlib.axes.Axes.pie""" +matplotlib.axes.Axes.pie + +Matplotlib documentation + + +Plot a pie chart. + +Make a pie chart of array *x*. The fractional area of each wedge is +given by ``x/sum(x)``. + +The wedges are plotted counterclockwise, by default starting from the +x-axis. + +Parameters +---------- +x : 1D array-like + The wedge sizes. + +explode : array-like, default: None + If not *None*, is a ``len(x)`` array which specifies the fraction + of the radius with which to offset each wedge. + +labels : list, default: None + A sequence of strings providing the labels for each wedge + +colors : :mpltype:`color` or list of :mpltype:`color`, default: None + A sequence of colors through which the pie chart will cycle. If + *None*, will use the colors in the currently active cycle. + +hatch : str or list, default: None + Hatching pattern applied to all pie wedges or sequence of patterns + through which the chart will cycle. For a list of valid patterns, + see :doc:`/gallery/shapes_and_collections/hatch_style_reference`. + + .. versionadded:: 3.7 + +autopct : None or str or callable, default: None + If not *None*, *autopct* is a string or function used to label the + wedges with their numeric value. The label will be placed inside + the wedge. If *autopct* is a format string, the label will be + ``fmt % pct``. If *autopct* is a function, then it will be called. + +pctdistance : float, default: 0.6 + The relative distance along the radius at which the text + generated by *autopct* is drawn. To draw the text outside the pie, + set *pctdistance* > 1. This parameter is ignored if *autopct* is + ``None``. + +labeldistance : float or None, default: 1.1 + The relative distance along the radius at which the labels are + drawn. To draw the labels inside the pie, set *labeldistance* < 1. + If set to ``None``, labels are not drawn but are still stored for + use in `.legend`. + +shadow : bool or dict, default: False + If bool, whether to draw a shadow beneath the pie. If dict, draw a shadow + passing the properties in the dict to `.Shadow`. + + .. versionadded:: 3.8 + *shadow* can be a dict. + +startangle : float, default: 0 degrees + The angle by which the start of the pie is rotated, + counterclockwise from the x-axis. + +radius : float, default: 1 + The radius of the pie. + +counterclock : bool, default: True + Specify fractions direction, clockwise or counterclockwise. + +wedgeprops : dict, default: None + Dict of arguments passed to each `.patches.Wedge` of the pie. + For example, ``wedgeprops = {'linewidth': 3}`` sets the width of + the wedge border lines equal to 3. By default, ``clip_on=False``. + When there is a conflict between these properties and other + keywords, properties passed to *wedgeprops* take precedence. + +textprops : dict, default: None + Dict of arguments to pass to the text objects. + +center : (float, float), default: (0, 0) + The coordinates of the center of the chart. + +frame : bool, default: False + Plot Axes frame with the chart if true. + +rotatelabels : bool, default: False + Rotate each label to the angle of the corresponding slice if true. + +normalize : bool, default: True + When *True*, always make a full pie by normalizing x so that + ``sum(x) == 1``. *False* makes a partial pie if ``sum(x) <= 1`` + and raises a `ValueError` for ``sum(x) > 1``. + +data : indexable object, optional + If given, the following parameters also accept a string ``s``, which is + interpreted as ``data[s]`` if ``s`` is a key in ``data``: + + *x*, *explode*, *labels*, *colors* + +Returns +------- +patches : list + A sequence of `matplotlib.patches.Wedge` instances + +texts : list + A list of the label `.Text` instances. + +autotexts : list + A list of `.Text` instances for the numeric labels. This will only + be returned if the parameter *autopct* is not *None*. + +Notes +----- +The pie chart will probably look best if the figure and Axes are +square, or the Axes aspect is equal. +This method sets the aspect ratio of the axis to "equal". +The Axes aspect ratio can be controlled with `.Axes.set_aspect`.""" ... @staticmethod @@ -5167,7 +6506,232 @@ PlotAxes.boxes PlotAxes.boxesh PlotAxes.boxplot PlotAxes.boxploth -matplotlib.axes.Axes.boxplot""" +matplotlib.axes.Axes.boxplot + +Matplotlib documentation + + +Draw a box and whisker plot. + +The box extends from the first quartile (Q1) to the third +quartile (Q3) of the data, with a line at the median. +The whiskers extend from the box to the farthest data point +lying within 1.5x the inter-quartile range (IQR) from the box. +Flier points are those past the end of the whiskers. +See https://en.wikipedia.org/wiki/Box_plot for reference. + +.. code-block:: none + + Q1-1.5IQR Q1 median Q3 Q3+1.5IQR + |-----:-----| + o |--------| : |--------| o o + |-----:-----| + flier <-----------> fliers + IQR + + +Parameters +---------- +x : Array or a sequence of vectors. + The input data. If a 2D array, a boxplot is drawn for each column + in *x*. If a sequence of 1D arrays, a boxplot is drawn for each + array in *x*. + +notch : bool, default: :rc:`boxplot.notch` + Whether to draw a notched boxplot (`True`), or a rectangular + boxplot (`False`). The notches represent the confidence interval + (CI) around the median. The documentation for *bootstrap* + describes how the locations of the notches are computed by + default, but their locations may also be overridden by setting the + *conf_intervals* parameter. + + .. note:: + + In cases where the values of the CI are less than the + lower quartile or greater than the upper quartile, the + notches will extend beyond the box, giving it a + distinctive "flipped" appearance. This is expected + behavior and consistent with other statistical + visualization packages. + +sym : str, optional + The default symbol for flier points. An empty string ('') hides + the fliers. If `None`, then the fliers default to 'b+'. More + control is provided by the *flierprops* parameter. + +vert : bool, optional + .. deprecated:: 3.11 + Use *orientation* instead. + + This is a pending deprecation for 3.10, with full deprecation + in 3.11 and removal in 3.13. + If this is given during the deprecation period, it overrides + the *orientation* parameter. + + If True, plots the boxes vertically. + If False, plots the boxes horizontally. + +orientation : {'vertical', 'horizontal'}, default: 'vertical' + If 'horizontal', plots the boxes horizontally. + Otherwise, plots the boxes vertically. + + .. versionadded:: 3.10 + +whis : float or (float, float), default: 1.5 + The position of the whiskers. + + If a float, the lower whisker is at the lowest datum above + ``Q1 - whis*(Q3-Q1)``, and the upper whisker at the highest datum + below ``Q3 + whis*(Q3-Q1)``, where Q1 and Q3 are the first and + third quartiles. The default value of ``whis = 1.5`` corresponds + to Tukey's original definition of boxplots. + + If a pair of floats, they indicate the percentiles at which to + draw the whiskers (e.g., (5, 95)). In particular, setting this to + (0, 100) results in whiskers covering the whole range of the data. + + In the edge case where ``Q1 == Q3``, *whis* is automatically set + to (0, 100) (cover the whole range of the data) if *autorange* is + True. + + Beyond the whiskers, data are considered outliers and are plotted + as individual points. + +bootstrap : int, optional + Specifies whether to bootstrap the confidence intervals + around the median for notched boxplots. If *bootstrap* is + None, no bootstrapping is performed, and notches are + calculated using a Gaussian-based asymptotic approximation + (see McGill, R., Tukey, J.W., and Larsen, W.A., 1978, and + Kendall and Stuart, 1967). Otherwise, bootstrap specifies + the number of times to bootstrap the median to determine its + 95% confidence intervals. Values between 1000 and 10000 are + recommended. + +usermedians : 1D array-like, optional + A 1D array-like of length ``len(x)``. Each entry that is not + `None` forces the value of the median for the corresponding + dataset. For entries that are `None`, the medians are computed + by Matplotlib as normal. + +conf_intervals : array-like, optional + A 2D array-like of shape ``(len(x), 2)``. Each entry that is not + None forces the location of the corresponding notch (which is + only drawn if *notch* is `True`). For entries that are `None`, + the notches are computed by the method specified by the other + parameters (e.g., *bootstrap*). + +positions : array-like, optional + The positions of the boxes. The ticks and limits are + automatically set to match the positions. Defaults to + ``range(1, N+1)`` where N is the number of boxes to be drawn. + +widths : float or array-like + The widths of the boxes. The default is 0.5, or ``0.15*(distance + between extreme positions)``, if that is smaller. + +patch_artist : bool, default: :rc:`boxplot.patchartist` + If `False` produces boxes with the Line2D artist. Otherwise, + boxes are drawn with Patch artists. + +tick_labels : list of str, optional + The tick labels of each boxplot. + Ticks are always placed at the box *positions*. If *tick_labels* is given, + the ticks are labelled accordingly. Otherwise, they keep their numeric + values. + + .. versionchanged:: 3.9 + Renamed from *labels*, which is deprecated since 3.9 + and will be removed in 3.11. + +manage_ticks : bool, default: True + If True, the tick locations and labels will be adjusted to match + the boxplot positions. + +autorange : bool, default: False + When `True` and the data are distributed such that the 25th and + 75th percentiles are equal, *whis* is set to (0, 100) such + that the whisker ends are at the minimum and maximum of the data. + +meanline : bool, default: :rc:`boxplot.meanline` + If `True` (and *showmeans* is `True`), will try to render the + mean as a line spanning the full width of the box according to + *meanprops* (see below). Not recommended if *shownotches* is also + True. Otherwise, means will be shown as points. + +zorder : float, default: ``Line2D.zorder = 2`` + The zorder of the boxplot. + +Returns +------- +dict + A dictionary mapping each component of the boxplot to a list + of the `.Line2D` instances created. That dictionary has the + following keys (assuming vertical boxplots): + + - ``boxes``: the main body of the boxplot showing the + quartiles and the median's confidence intervals if + enabled. + + - ``medians``: horizontal lines at the median of each box. + + - ``whiskers``: the vertical lines extending to the most + extreme, non-outlier data points. + + - ``caps``: the horizontal lines at the ends of the + whiskers. + + - ``fliers``: points representing data that extend beyond + the whiskers (fliers). + + - ``means``: points or lines representing the means. + +Other Parameters +---------------- +showcaps : bool, default: :rc:`boxplot.showcaps` + Show the caps on the ends of whiskers. +showbox : bool, default: :rc:`boxplot.showbox` + Show the central box. +showfliers : bool, default: :rc:`boxplot.showfliers` + Show the outliers beyond the caps. +showmeans : bool, default: :rc:`boxplot.showmeans` + Show the arithmetic means. +capprops : dict, default: None + The style of the caps. +capwidths : float or array, default: None + The widths of the caps. +boxprops : dict, default: None + The style of the box. +whiskerprops : dict, default: None + The style of the whiskers. +flierprops : dict, default: None + The style of the fliers. +medianprops : dict, default: None + The style of the median. +meanprops : dict, default: None + The style of the mean. +label : str or list of str, optional + Legend labels. Use a single string when all boxes have the same style and + you only want a single legend entry for them. Use a list of strings to + label all boxes individually. To be distinguishable, the boxes should be + styled individually, which is currently only possible by modifying the + returned artists, see e.g. :doc:`/gallery/statistics/boxplot_demo`. + + In the case of a single string, the legend entry will technically be + associated with the first box only. By default, the legend will show the + median line (``result["medians"]``); if *patch_artist* is True, the legend + will show the box `.Patch` artists (``result["boxes"]``) instead. + + .. versionadded:: 3.9 + +data : indexable object, optional + If given, all parameters also accept a string ``s``, which is + interpreted as ``data[s]`` if ``s`` is a key in ``data``. + +See Also +-------- +.Axes.bxp : Draw a boxplot from pre-computed statistics. +violinplot : Draw an estimate of the probability density function.""" ... def boxploth(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -5622,7 +7186,115 @@ PlotAxes.violin PlotAxes.violinh PlotAxes.violinplot PlotAxes.violinploth -matplotlib.axes.Axes.violinplot""" +matplotlib.axes.Axes.violinplot + +Matplotlib documentation + + +Make a violin plot. + +Make a violin plot for each column of *dataset* or each vector in +sequence *dataset*. Each filled area extends to represent the +entire data range, with optional lines at the mean, the median, +the minimum, the maximum, and user-specified quantiles. + +Parameters +---------- +dataset : Array or a sequence of vectors. + The input data. + +positions : array-like, default: [1, 2, ..., n] + The positions of the violins; i.e. coordinates on the x-axis for + vertical violins (or y-axis for horizontal violins). + +vert : bool, optional + .. deprecated:: 3.10 + Use *orientation* instead. + + If this is given during the deprecation period, it overrides + the *orientation* parameter. + + If True, plots the violins vertically. + If False, plots the violins horizontally. + +orientation : {'vertical', 'horizontal'}, default: 'vertical' + If 'horizontal', plots the violins horizontally. + Otherwise, plots the violins vertically. + + .. versionadded:: 3.10 + +widths : float or array-like, default: 0.5 + The maximum width of each violin in units of the *positions* axis. + The default is 0.5, which is half the available space when using default + *positions*. + +showmeans : bool, default: False + Whether to show the mean with a line. + +showextrema : bool, default: True + Whether to show extrema with a line. + +showmedians : bool, default: False + Whether to show the median with a line. + +quantiles : array-like, default: None + If not None, set a list of floats in interval [0, 1] for each violin, + which stands for the quantiles that will be rendered for that + violin. + +points : int, default: 100 + The number of points to evaluate each of the gaussian kernel density + estimations at. + +bw_method : {'scott', 'silverman'} or float or callable, default: 'scott' + The method used to calculate the estimator bandwidth. If a + float, this will be used directly as `kde.factor`. If a + callable, it should take a `matplotlib.mlab.GaussianKDE` instance as + its only parameter and return a float. + +side : {'both', 'low', 'high'}, default: 'both' + 'both' plots standard violins. 'low'/'high' only + plots the side below/above the positions value. + +data : indexable object, optional + If given, the following parameters also accept a string ``s``, which is + interpreted as ``data[s]`` if ``s`` is a key in ``data``: + + *dataset* + +Returns +------- +dict + A dictionary mapping each component of the violinplot to a + list of the corresponding collection instances created. The + dictionary has the following keys: + + - ``bodies``: A list of the `~.collections.PolyCollection` + instances containing the filled area of each violin. + + - ``cmeans``: A `~.collections.LineCollection` instance that marks + the mean values of each of the violin's distribution. + + - ``cmins``: A `~.collections.LineCollection` instance that marks + the bottom of each violin's distribution. + + - ``cmaxes``: A `~.collections.LineCollection` instance that marks + the top of each violin's distribution. + + - ``cbars``: A `~.collections.LineCollection` instance that marks + the centers of each violin's distribution. + + - ``cmedians``: A `~.collections.LineCollection` instance that + marks the median values of each of the violin's distribution. + + - ``cquantiles``: A `~.collections.LineCollection` instance created + to identify the quantile values of each of the violin's + distribution. + +See Also +-------- +.Axes.violin : Draw a violin from pre-computed statistics. +boxplot : Draw a box and whisker plot.""" ... def violinploth(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -6128,7 +7800,205 @@ See also -------- PlotAxes.hist PlotAxes.histh -matplotlib.axes.Axes.hist""" +matplotlib.axes.Axes.hist + +Matplotlib documentation + + +Compute and plot a histogram. + +This method uses `numpy.histogram` to bin the data in *x* and count the +number of values in each bin, then draws the distribution either as a +`.BarContainer` or `.Polygon`. The *bins*, *range*, *density*, and +*weights* parameters are forwarded to `numpy.histogram`. + +If the data has already been binned and counted, use `~.bar` or +`~.stairs` to plot the distribution:: + + counts, bins = np.histogram(x) + plt.stairs(counts, bins) + +Alternatively, plot pre-computed bins and counts using ``hist()`` by +treating each bin as a single point with a weight equal to its count:: + + plt.hist(bins[:-1], bins, weights=counts) + +The data input *x* can be a singular array, a list of datasets of +potentially different lengths ([*x0*, *x1*, ...]), or a 2D ndarray in +which each column is a dataset. Note that the ndarray form is +transposed relative to the list form. If the input is an array, then +the return value is a tuple (*n*, *bins*, *patches*); if the input is a +sequence of arrays, then the return value is a tuple +([*n0*, *n1*, ...], *bins*, [*patches0*, *patches1*, ...]). + +Masked arrays are not supported. + +Parameters +---------- +x : (n,) array or sequence of (n,) arrays + Input values, this takes either a single array or a sequence of + arrays which are not required to be of the same length. + +bins : int or sequence or str, default: :rc:`hist.bins` + If *bins* is an integer, it defines the number of equal-width bins + in the range. + + If *bins* is a sequence, it defines the bin edges, including the + left edge of the first bin and the right edge of the last bin; + in this case, bins may be unequally spaced. All but the last + (righthand-most) bin is half-open. In other words, if *bins* is:: + + [1, 2, 3, 4] + + then the first bin is ``[1, 2)`` (including 1, but excluding 2) and + the second ``[2, 3)``. The last bin, however, is ``[3, 4]``, which + *includes* 4. + + If *bins* is a string, it is one of the binning strategies + supported by `numpy.histogram_bin_edges`: 'auto', 'fd', 'doane', + 'scott', 'stone', 'rice', 'sturges', or 'sqrt'. + +range : tuple or None, default: None + The lower and upper range of the bins. Lower and upper outliers + are ignored. If not provided, *range* is ``(x.min(), x.max())``. + Range has no effect if *bins* is a sequence. + + If *bins* is a sequence or *range* is specified, autoscaling + is based on the specified bin range instead of the + range of x. + +density : bool, default: False + If ``True``, draw and return a probability density: each bin + will display the bin's raw count divided by the total number of + counts *and the bin width* + (``density = counts / (sum(counts) * np.diff(bins))``), + so that the area under the histogram integrates to 1 + (``np.sum(density * np.diff(bins)) == 1``). + + If *stacked* is also ``True``, the sum of the histograms is + normalized to 1. + +weights : (n,) array-like or None, default: None + An array of weights, of the same shape as *x*. Each value in + *x* only contributes its associated weight towards the bin count + (instead of 1). If *density* is ``True``, the weights are + normalized, so that the integral of the density over the range + remains 1. + +cumulative : bool or -1, default: False + If ``True``, then a histogram is computed where each bin gives the + counts in that bin plus all bins for smaller values. The last bin + gives the total number of datapoints. + + If *density* is also ``True`` then the histogram is normalized such + that the last bin equals 1. + + If *cumulative* is a number less than 0 (e.g., -1), the direction + of accumulation is reversed. In this case, if *density* is also + ``True``, then the histogram is normalized such that the first bin + equals 1. + +bottom : array-like or float, default: 0 + Location of the bottom of each bin, i.e. bins are drawn from + ``bottom`` to ``bottom + hist(x, bins)`` If a scalar, the bottom + of each bin is shifted by the same amount. If an array, each bin + is shifted independently and the length of bottom must match the + number of bins. If None, defaults to 0. + +histtype : {'bar', 'barstacked', 'step', 'stepfilled'}, default: 'bar' + The type of histogram to draw. + + - 'bar' is a traditional bar-type histogram. If multiple data + are given the bars are arranged side by side. + - 'barstacked' is a bar-type histogram where multiple + data are stacked on top of each other. + - 'step' generates a lineplot that is by default unfilled. + - 'stepfilled' generates a lineplot that is by default filled. + +align : {'left', 'mid', 'right'}, default: 'mid' + The horizontal alignment of the histogram bars. + + - 'left': bars are centered on the left bin edges. + - 'mid': bars are centered between the bin edges. + - 'right': bars are centered on the right bin edges. + +orientation : {'vertical', 'horizontal'}, default: 'vertical' + If 'horizontal', `~.Axes.barh` will be used for bar-type histograms + and the *bottom* kwarg will be the left edges. + +rwidth : float or None, default: None + The relative width of the bars as a fraction of the bin width. If + ``None``, automatically compute the width. + + Ignored if *histtype* is 'step' or 'stepfilled'. + +log : bool, default: False + If ``True``, the histogram axis will be set to a log scale. + +color : :mpltype:`color` or list of :mpltype:`color` or None, default: None + Color or sequence of colors, one per dataset. Default (``None``) + uses the standard line color sequence. + +label : str or list of str, optional + String, or sequence of strings to match multiple datasets. Bar + charts yield multiple patches per dataset, but only the first gets + the label, so that `~.Axes.legend` will work as expected. + +stacked : bool, default: False + If ``True``, multiple data are stacked on top of each other If + ``False`` multiple data are arranged side by side if histtype is + 'bar' or on top of each other if histtype is 'step' + +Returns +------- +n : array or list of arrays + The values of the histogram bins. See *density* and *weights* for a + description of the possible semantics. If input *x* is an array, + then this is an array of length *nbins*. If input is a sequence of + arrays ``[data1, data2, ...]``, then this is a list of arrays with + the values of the histograms for each of the arrays in the same + order. The dtype of the array *n* (or of its element arrays) will + always be float even if no weighting or normalization is used. + +bins : array + The edges of the bins. Length nbins + 1 (nbins left edges and right + edge of last bin). Always a single array even when multiple data + sets are passed in. + +patches : `.BarContainer` or list of a single `.Polygon` or list of such objects + Container of individual artists used to create the histogram + or list of such containers if there are multiple input datasets. + +Other Parameters +---------------- +data : indexable object, optional + If given, the following parameters also accept a string ``s``, which is + interpreted as ``data[s]`` if ``s`` is a key in ``data``: + + *x*, *weights* + +**kwargs + `~matplotlib.patches.Patch` properties. The following properties + additionally accept a sequence of values corresponding to the + datasets in *x*: + *edgecolor*, *facecolor*, *linewidth*, *linestyle*, *hatch*. + + .. versionadded:: 3.10 + Allowing sequences of values in above listed Patch properties. + +See Also +-------- +hist2d : 2D histogram with rectangular bins +hexbin : 2D histogram with hexagonal bins +stairs : Plot a pre-computed histogram +bar : Plot a pre-computed histogram + +Notes +----- +For large numbers of bins (>1000), plotting can be significantly +accelerated by using `~.Axes.stairs` to plot a pre-computed histogram +(``plt.stairs(*np.histogram(data))``), or by setting *histtype* to +'step' or 'stepfilled' rather than 'bar' or 'barstacked'.""" ... def histh(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -6438,7 +8308,123 @@ See also -------- PlotAxes.hist2d PlotAxes.hexbin -matplotlib.axes.Axes.hist2d""" +matplotlib.axes.Axes.hist2d + +Matplotlib documentation + + +Make a 2D histogram plot. + +Parameters +---------- +x, y : array-like, shape (n, ) + Input values + +bins : None or int or [int, int] or array-like or [array, array] + + The bin specification: + + - If int, the number of bins for the two dimensions + (``nx = ny = bins``). + - If ``[int, int]``, the number of bins in each dimension + (``nx, ny = bins``). + - If array-like, the bin edges for the two dimensions + (``x_edges = y_edges = bins``). + - If ``[array, array]``, the bin edges in each dimension + (``x_edges, y_edges = bins``). + + The default value is 10. + +range : array-like shape(2, 2), optional + The leftmost and rightmost edges of the bins along each dimension + (if not specified explicitly in the bins parameters): ``[[xmin, + xmax], [ymin, ymax]]``. All values outside of this range will be + considered outliers and not tallied in the histogram. + +density : bool, default: False + Normalize histogram. See the documentation for the *density* + parameter of `~.Axes.hist` for more details. + +weights : array-like, shape (n, ), optional + An array of values w_i weighing each sample (x_i, y_i). + +cmin, cmax : float, default: None + All bins that has count less than *cmin* or more than *cmax* will not be + displayed (set to NaN before passing to `~.Axes.pcolormesh`) and these count + values in the return value count histogram will also be set to nan upon + return. + +Returns +------- +h : 2D array + The bi-dimensional histogram of samples x and y. Values in x are + histogrammed along the first dimension and values in y are + histogrammed along the second dimension. +xedges : 1D array + The bin edges along the x-axis. +yedges : 1D array + The bin edges along the y-axis. +image : `~.matplotlib.collections.QuadMesh` + +Other Parameters +---------------- +cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap` + The Colormap instance or registered colormap name used to map scalar data + to colors. + +norm : str or `~matplotlib.colors.Normalize`, optional + The normalization method used to scale scalar data to the [0, 1] range + before mapping to colors using *cmap*. By default, a linear scaling is + used, mapping the lowest value to 0 and the highest to 1. + + If given, this can be one of the following: + + - An instance of `.Normalize` or one of its subclasses + (see :ref:`colormapnorms`). + - A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For a + list of available scales, call `matplotlib.scale.get_scale_names()`. + In that case, a suitable `.Normalize` subclass is dynamically generated + and instantiated. + +vmin, vmax : float, optional + When using scalar data and no explicit *norm*, *vmin* and *vmax* define + the data range that the colormap covers. By default, the colormap covers + the complete value range of the supplied data. It is an error to use + *vmin*/*vmax* when a *norm* instance is given (but using a `str` *norm* + name together with *vmin*/*vmax* is acceptable). + +colorizer : `~matplotlib.colorizer.Colorizer` or None, default: None + The Colorizer object used to map color to data. If None, a Colorizer + object is created from a *norm* and *cmap*. + +alpha : ``0 <= scalar <= 1`` or ``None``, optional + The alpha blending value. + +data : indexable object, optional + If given, the following parameters also accept a string ``s``, which is + interpreted as ``data[s]`` if ``s`` is a key in ``data``: + + *x*, *y*, *weights* + +**kwargs + Additional parameters are passed along to the + `~.Axes.pcolormesh` method and `~matplotlib.collections.QuadMesh` + constructor. + +See Also +-------- +hist : 1D histogram plotting +hexbin : 2D histogram with hexagonal bins + +Notes +----- +- Currently ``hist2d`` calculates its own axis limits, and any limits + previously set are ignored. +- Rendering the histogram with a logarithmic color scale is + accomplished by passing a `.colors.LogNorm` instance to the *norm* + keyword argument. Likewise, power-law normalization (similar + in effect to gamma correction) can be accomplished with + `.colors.PowerNorm`.""" ... def hexbin(self, x: Incomplete, y: Incomplete, weights: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -6615,26 +8601,250 @@ See also -------- PlotAxes.hist2d PlotAxes.hexbin -matplotlib.axes.Axes.hexbin""" - ... +matplotlib.axes.Axes.hexbin - def contour(self, x: Incomplete, y: Incomplete, z: Incomplete, **kwargs: Incomplete) -> Incomplete: - """Plot contour lines. +Matplotlib documentation + + +Make a 2D hexagonal binning plot of points *x*, *y*. + +If *C* is *None*, the value of the hexagon is determined by the number +of points in the hexagon. Otherwise, *C* specifies values at the +coordinate (x[i], y[i]). For each hexagon, these values are reduced +using *reduce_C_function*. Parameters ---------- -*args : z or x, y, z - The data passed as positional or keyword arguments. Interpreted as follows: +x, y : array-like + The data positions. *x* and *y* must be of the same length. + +C : array-like, optional + If given, these values are accumulated in the bins. Otherwise, + every point has a value of 1. Must be of the same length as *x* + and *y*. + +gridsize : int or (int, int), default: 100 + If a single int, the number of hexagons in the *x*-direction. + The number of hexagons in the *y*-direction is chosen such that + the hexagons are approximately regular. + + Alternatively, if a tuple (*nx*, *ny*), the number of hexagons + in the *x*-direction and the *y*-direction. In the + *y*-direction, counting is done along vertically aligned + hexagons, not along the zig-zag chains of hexagons; see the + following illustration. + + .. plot:: + + import numpy + import matplotlib.pyplot as plt + + np.random.seed(19680801) + n= 300 + x = np.random.standard_normal(n) + y = np.random.standard_normal(n) + + fig, ax = plt.subplots(figsize=(4, 4)) + h = ax.hexbin(x, y, gridsize=(5, 3)) + hx, hy = h.get_offsets().T + ax.plot(hx[24::3], hy[24::3], 'ro-') + ax.plot(hx[-3:], hy[-3:], 'ro-') + ax.set_title('gridsize=(5, 3)') + ax.axis('off') + + To get approximately regular hexagons, choose + :math:`n_x = \\sqrt{3}\\,n_y`. + +bins : 'log' or int or sequence, default: None + Discretization of the hexagon values. + + - If *None*, no binning is applied; the color of each hexagon + directly corresponds to its count value. + - If 'log', use a logarithmic scale for the colormap. + Internally, :math:`log_{10}(i+1)` is used to determine the + hexagon color. This is equivalent to ``norm=LogNorm()``. + - If an integer, divide the counts in the specified number + of bins, and color the hexagons accordingly. + - If a sequence of values, the values of the lower bound of + the bins to be used. + +xscale : {'linear', 'log'}, default: 'linear' + Use a linear or log10 scale on the horizontal axis. + +yscale : {'linear', 'log'}, default: 'linear' + Use a linear or log10 scale on the vertical axis. + +mincnt : int >= 0, default: *None* + If not *None*, only display cells with at least *mincnt* + number of points in the cell. + +marginals : bool, default: *False* + If marginals is *True*, plot the marginal density as + colormapped rectangles along the bottom of the x-axis and + left of the y-axis. + +extent : 4-tuple of float, default: *None* + The limits of the bins (xmin, xmax, ymin, ymax). + The default assigns the limits based on + *gridsize*, *x*, *y*, *xscale* and *yscale*. + + If *xscale* or *yscale* is set to 'log', the limits are + expected to be the exponent for a power of 10. E.g. for + x-limits of 1 and 50 in 'linear' scale and y-limits + of 10 and 1000 in 'log' scale, enter (1, 50, 1, 3). - * If only `z` coordinates are passed, try to infer the `x` and `y` coordinates - from the :class:`~pandas.DataFrame` indices and columns or the :class:`~xarray.DataArray` - coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` - and the `x` coordinates are ``np.arange(0, y.shape[1])``. - * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using - `~ultraplot.utils.edges` or `:func:`~ultraplot.utils.edges2d`` if *centers* were provided. - For all other methods, calculate coordinate *centers* if *edges* were provided. - * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the +Returns +------- +`~matplotlib.collections.PolyCollection` + A `.PolyCollection` defining the hexagonal bins. + + - `.PolyCollection.get_offsets` contains a Mx2 array containing + the x, y positions of the M hexagon centers in data coordinates. + - `.PolyCollection.get_array` contains the values of the M + hexagons. + + If *marginals* is *True*, horizontal + bar and vertical bar (both PolyCollections) will be attached + to the return collection as attributes *hbar* and *vbar*. + +Other Parameters +---------------- +cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap` + The Colormap instance or registered colormap name used to map scalar data + to colors. + +norm : str or `~matplotlib.colors.Normalize`, optional + The normalization method used to scale scalar data to the [0, 1] range + before mapping to colors using *cmap*. By default, a linear scaling is + used, mapping the lowest value to 0 and the highest to 1. + + If given, this can be one of the following: + + - An instance of `.Normalize` or one of its subclasses + (see :ref:`colormapnorms`). + - A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For a + list of available scales, call `matplotlib.scale.get_scale_names()`. + In that case, a suitable `.Normalize` subclass is dynamically generated + and instantiated. + +vmin, vmax : float, optional + When using scalar data and no explicit *norm*, *vmin* and *vmax* define + the data range that the colormap covers. By default, the colormap covers + the complete value range of the supplied data. It is an error to use + *vmin*/*vmax* when a *norm* instance is given (but using a `str` *norm* + name together with *vmin*/*vmax* is acceptable). + +alpha : float between 0 and 1, optional + The alpha blending value, between 0 (transparent) and 1 (opaque). + +linewidths : float, default: *None* + If *None*, defaults to :rc:`patch.linewidth`. + +edgecolors : {'face', 'none', *None*} or color, default: 'face' + The color of the hexagon edges. Possible values are: + + - 'face': Draw the edges in the same color as the fill color. + - 'none': No edges are drawn. This can sometimes lead to unsightly + unpainted pixels between the hexagons. + - *None*: Draw outlines in the default color. + - An explicit color. + +reduce_C_function : callable, default: `numpy.mean` + The function to aggregate *C* within the bins. It is ignored if + *C* is not given. This must have the signature:: + + def reduce_C_function(C: array) -> float + + Commonly used functions are: + + - `numpy.mean`: average of the points + - `numpy.sum`: integral of the point values + - `numpy.amax`: value taken from the largest point + + By default will only reduce cells with at least 1 point because some + reduction functions (such as `numpy.amax`) will error/warn with empty + input. Changing *mincnt* will adjust the cutoff, and if set to 0 will + pass empty input to the reduction function. + +colorizer : `~matplotlib.colorizer.Colorizer` or None, default: None + The Colorizer object used to map color to data. If None, a Colorizer + object is created from a *norm* and *cmap*. + +data : indexable object, optional + If given, the following parameters also accept a string ``s``, which is + interpreted as ``data[s]`` if ``s`` is a key in ``data``: + + *x*, *y*, *C* + +**kwargs : `~matplotlib.collections.PolyCollection` properties + All other keyword arguments are passed on to `.PolyCollection`: + + Properties: + agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image + alpha: array-like or float or None + animated: bool + antialiased or aa or antialiaseds: bool or list of bools + array: array-like or None + capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} + clim: (vmin: float, vmax: float) + clip_box: `~matplotlib.transforms.BboxBase` or None + clip_on: bool + clip_path: Patch or (Path, Transform) or None + cmap: `.Colormap` or str or None + color: :mpltype:`color` or list of RGBA tuples + edgecolor or ec or edgecolors: :mpltype:`color` or list of :mpltype:`color` or 'face' + facecolor or facecolors or fc: :mpltype:`color` or list of :mpltype:`color` + figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + gid: str + hatch: {'/', '\\\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'} + hatch_linewidth: unknown + in_layout: bool + joinstyle: `.JoinStyle` or {'miter', 'round', 'bevel'} + label: object + linestyle or dashes or linestyles or ls: str or tuple or list thereof + linewidth or linewidths or lw: float or list of floats + mouseover: bool + norm: `.Normalize` or str or None + offset_transform or transOffset: `.Transform` + offsets: (N, 2) or (2,) array-like + path_effects: list of `.AbstractPathEffect` + paths: list of array-like + picker: None or bool or float or callable + pickradius: float + rasterized: bool + sizes: `numpy.ndarray` or None + sketch_params: (scale: float, length: float, randomness: float) + snap: bool or None + transform: `~matplotlib.transforms.Transform` + url: str + urls: list of str or None + verts: list of array-like + verts_and_codes: unknown + visible: bool + zorder: float + +See Also +-------- +hist2d : 2D histogram rectangular bins""" + ... + + def contour(self, x: Incomplete, y: Incomplete, z: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Plot contour lines. + +Parameters +---------- +*args : z or x, y, z + The data passed as positional or keyword arguments. Interpreted as follows: + + * If only `z` coordinates are passed, try to infer the `x` and `y` coordinates + from the :class:`~pandas.DataFrame` indices and columns or the :class:`~xarray.DataArray` + coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` + and the `x` coordinates are ``np.arange(0, y.shape[1])``. + * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using + `~ultraplot.utils.edges` or `:func:`~ultraplot.utils.edges2d`` if *centers* were provided. + For all other methods, calculate coordinate *centers* if *edges* were provided. + * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry + to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the `z` coordinates are `pint.Quantity`, pass the magnitude to the plotting command. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. @@ -6822,7 +9032,283 @@ PlotAxes.contour PlotAxes.contourf PlotAxes.tricontour PlotAxes.tricontourf -matplotlib.axes.Axes.contour""" +matplotlib.axes.Axes.contour + +Matplotlib documentation + + +Plot contour lines. + +Call signature:: + + contour([X, Y,] Z, /, [levels], **kwargs) + +The arguments *X*, *Y*, *Z* are positional-only. + +`.contour` and `.contourf` draw contour lines and filled contours, +respectively. Except as noted, function signatures and return values +are the same for both versions. + +Parameters +---------- +X, Y : array-like, optional + The coordinates of the values in *Z*. + + *X* and *Y* must both be 2D with the same shape as *Z* (e.g. + created via `numpy.meshgrid`), or they must both be 1-D such + that ``len(X) == N`` is the number of columns in *Z* and + ``len(Y) == M`` is the number of rows in *Z*. + + *X* and *Y* must both be ordered monotonically. + + If not given, they are assumed to be integer indices, i.e. + ``X = range(N)``, ``Y = range(M)``. + +Z : (M, N) array-like + The height values over which the contour is drawn. Color-mapping is + controlled by *cmap*, *norm*, *vmin*, and *vmax*. + +levels : int or array-like, optional + Determines the number and positions of the contour lines / regions. + + If an int *n*, use `~matplotlib.ticker.MaxNLocator`, which tries + to automatically choose no more than *n+1* "nice" contour levels + between minimum and maximum numeric values of *Z*. + + If array-like, draw contour lines at the specified levels. + The values must be in increasing order. + +Returns +------- +`~.contour.QuadContourSet` + +Other Parameters +---------------- +corner_mask : bool, default: :rc:`contour.corner_mask` + Enable/disable corner masking, which only has an effect if *Z* is + a masked array. If ``False``, any quad touching a masked point is + masked out. If ``True``, only the triangular corners of quads + nearest those points are always masked out, other triangular + corners comprising three unmasked points are contoured as usual. + +colors : :mpltype:`color` or list of :mpltype:`color`, optional + The colors of the levels, i.e. the lines for `.contour` and the + areas for `.contourf`. + + The sequence is cycled for the levels in ascending order. If the + sequence is shorter than the number of levels, it's repeated. + + As a shortcut, a single color may be used in place of one-element lists, i.e. + ``'red'`` instead of ``['red']`` to color all levels with the same color. + + .. versionchanged:: 3.10 + Previously a single color had to be expressed as a string, but now any + valid color format may be passed. + + By default (value *None*), the colormap specified by *cmap* + will be used. + +alpha : float, default: 1 + The alpha blending value, between 0 (transparent) and 1 (opaque). + +cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap` + The Colormap instance or registered colormap name used to map scalar data + to colors. + + This parameter is ignored if *colors* is set. + +norm : str or `~matplotlib.colors.Normalize`, optional + The normalization method used to scale scalar data to the [0, 1] range + before mapping to colors using *cmap*. By default, a linear scaling is + used, mapping the lowest value to 0 and the highest to 1. + + If given, this can be one of the following: + + - An instance of `.Normalize` or one of its subclasses + (see :ref:`colormapnorms`). + - A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For a + list of available scales, call `matplotlib.scale.get_scale_names()`. + In that case, a suitable `.Normalize` subclass is dynamically generated + and instantiated. + + This parameter is ignored if *colors* is set. + +vmin, vmax : float, optional + When using scalar data and no explicit *norm*, *vmin* and *vmax* define + the data range that the colormap covers. By default, the colormap covers + the complete value range of the supplied data. It is an error to use + *vmin*/*vmax* when a *norm* instance is given (but using a `str` *norm* + name together with *vmin*/*vmax* is acceptable). + + If *vmin* or *vmax* are not given, the default color scaling is based on + *levels*. + + This parameter is ignored if *colors* is set. + +colorizer : `~matplotlib.colorizer.Colorizer` or None, default: None + The Colorizer object used to map color to data. If None, a Colorizer + object is created from a *norm* and *cmap*. + + This parameter is ignored if *colors* is set. + +origin : {*None*, 'upper', 'lower', 'image'}, default: None + Determines the orientation and exact position of *Z* by specifying + the position of ``Z[0, 0]``. This is only relevant, if *X*, *Y* + are not given. + + - *None*: ``Z[0, 0]`` is at X=0, Y=0 in the lower left corner. + - 'lower': ``Z[0, 0]`` is at X=0.5, Y=0.5 in the lower left corner. + - 'upper': ``Z[0, 0]`` is at X=N+0.5, Y=0.5 in the upper left + corner. + - 'image': Use the value from :rc:`image.origin`. + +extent : (x0, x1, y0, y1), optional + If *origin* is not *None*, then *extent* is interpreted as in + `.imshow`: it gives the outer pixel boundaries. In this case, the + position of Z[0, 0] is the center of the pixel, not a corner. If + *origin* is *None*, then (*x0*, *y0*) is the position of Z[0, 0], + and (*x1*, *y1*) is the position of Z[-1, -1]. + + This argument is ignored if *X* and *Y* are specified in the call + to contour. + +locator : ticker.Locator subclass, optional + The locator is used to determine the contour levels if they + are not given explicitly via *levels*. + Defaults to `~.ticker.MaxNLocator`. + +extend : {'neither', 'both', 'min', 'max'}, default: 'neither' + Determines the ``contourf``-coloring of values that are outside the + *levels* range. + + If 'neither', values outside the *levels* range are not colored. + If 'min', 'max' or 'both', color the values below, above or below + and above the *levels* range. + + Values below ``min(levels)`` and above ``max(levels)`` are mapped + to the under/over values of the `.Colormap`. Note that most + colormaps do not have dedicated colors for these by default, so + that the over and under values are the edge values of the colormap. + You may want to set these values explicitly using + `.Colormap.set_under` and `.Colormap.set_over`. + + .. note:: + + An existing `.QuadContourSet` does not get notified if + properties of its colormap are changed. Therefore, an explicit + call `~.ContourSet.changed()` is needed after modifying the + colormap. The explicit call can be left out, if a colorbar is + assigned to the `.QuadContourSet` because it internally calls + `~.ContourSet.changed()`. + + Example:: + + x = np.arange(1, 10) + y = x.reshape(-1, 1) + h = x * y + + cs = plt.contourf(h, levels=[10, 30, 50], + colors=['#808080', '#A0A0A0', '#C0C0C0'], extend='both') + cs.cmap.set_over('red') + cs.cmap.set_under('blue') + cs.changed() + +xunits, yunits : registered units, optional + Override axis units by specifying an instance of a + :class:`matplotlib.units.ConversionInterface`. + +antialiased : bool, optional + Enable antialiasing, overriding the defaults. For + filled contours, the default is *False*. For line contours, + it is taken from :rc:`lines.antialiased`. + +nchunk : int >= 0, optional + If 0, no subdivision of the domain. Specify a positive integer to + divide the domain into subdomains of *nchunk* by *nchunk* quads. + Chunking reduces the maximum length of polygons generated by the + contouring algorithm which reduces the rendering workload passed + on to the backend and also requires slightly less RAM. It can + however introduce rendering artifacts at chunk boundaries depending + on the backend, the *antialiased* flag and value of *alpha*. + +linewidths : float or array-like, default: :rc:`contour.linewidth` + *Only applies to* `.contour`. + + The line width of the contour lines. + + If a number, all levels will be plotted with this linewidth. + + If a sequence, the levels in ascending order will be plotted with + the linewidths in the order specified. + + If None, this falls back to :rc:`lines.linewidth`. + +linestyles : {*None*, 'solid', 'dashed', 'dashdot', 'dotted'}, optional + *Only applies to* `.contour`. + + If *linestyles* is *None*, the default is 'solid' unless the lines are + monochrome. In that case, negative contours will instead take their + linestyle from the *negative_linestyles* argument. + + *linestyles* can also be an iterable of the above strings specifying a set + of linestyles to be used. If this iterable is shorter than the number of + contour levels it will be repeated as necessary. + +negative_linestyles : {*None*, 'solid', 'dashed', 'dashdot', 'dotted'}, optional + *Only applies to* `.contour`. + + If *linestyles* is *None* and the lines are monochrome, this argument + specifies the line style for negative contours. + + If *negative_linestyles* is *None*, the default is taken from + :rc:`contour.negative_linestyle`. + + *negative_linestyles* can also be an iterable of the above strings + specifying a set of linestyles to be used. If this iterable is shorter than + the number of contour levels it will be repeated as necessary. + +hatches : list[str], optional + *Only applies to* `.contourf`. + + A list of cross hatch patterns to use on the filled areas. + If None, no hatching will be added to the contour. + +algorithm : {'mpl2005', 'mpl2014', 'serial', 'threaded'}, optional + Which contouring algorithm to use to calculate the contour lines and + polygons. The algorithms are implemented in + `ContourPy `_, consult the + `ContourPy documentation `_ for + further information. + + The default is taken from :rc:`contour.algorithm`. + +clip_path : `~matplotlib.patches.Patch` or `.Path` or `.TransformedPath` + Set the clip path. See `~matplotlib.artist.Artist.set_clip_path`. + + .. versionadded:: 3.8 + +data : indexable object, optional + If given, all parameters also accept a string ``s``, which is + interpreted as ``data[s]`` if ``s`` is a key in ``data``. + +Notes +----- +1. `.contourf` differs from the MATLAB version in that it does not draw + the polygon edges. To draw edges, add line contours with calls to + `.contour`. + +2. `.contourf` fills intervals that are closed at the top; that is, for + boundaries *z1* and *z2*, the filled region is:: + + z1 < Z <= z2 + + except for the lowest interval, which is closed on both sides (i.e. + it includes the lowest value). + +3. `.contour` and `.contourf` use a `marching squares + `_ algorithm to + compute contour locations. More information can be found in + `ContourPy documentation `_.""" ... def contourf(self, x: Incomplete, y: Incomplete, z: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -7037,7 +9523,283 @@ PlotAxes.contour PlotAxes.contourf PlotAxes.tricontour PlotAxes.tricontourf -matplotlib.axes.Axes.contourf""" +matplotlib.axes.Axes.contourf + +Matplotlib documentation + + +Plot filled contours. + +Call signature:: + + contourf([X, Y,] Z, /, [levels], **kwargs) + +The arguments *X*, *Y*, *Z* are positional-only. + +`.contour` and `.contourf` draw contour lines and filled contours, +respectively. Except as noted, function signatures and return values +are the same for both versions. + +Parameters +---------- +X, Y : array-like, optional + The coordinates of the values in *Z*. + + *X* and *Y* must both be 2D with the same shape as *Z* (e.g. + created via `numpy.meshgrid`), or they must both be 1-D such + that ``len(X) == N`` is the number of columns in *Z* and + ``len(Y) == M`` is the number of rows in *Z*. + + *X* and *Y* must both be ordered monotonically. + + If not given, they are assumed to be integer indices, i.e. + ``X = range(N)``, ``Y = range(M)``. + +Z : (M, N) array-like + The height values over which the contour is drawn. Color-mapping is + controlled by *cmap*, *norm*, *vmin*, and *vmax*. + +levels : int or array-like, optional + Determines the number and positions of the contour lines / regions. + + If an int *n*, use `~matplotlib.ticker.MaxNLocator`, which tries + to automatically choose no more than *n+1* "nice" contour levels + between minimum and maximum numeric values of *Z*. + + If array-like, draw contour lines at the specified levels. + The values must be in increasing order. + +Returns +------- +`~.contour.QuadContourSet` + +Other Parameters +---------------- +corner_mask : bool, default: :rc:`contour.corner_mask` + Enable/disable corner masking, which only has an effect if *Z* is + a masked array. If ``False``, any quad touching a masked point is + masked out. If ``True``, only the triangular corners of quads + nearest those points are always masked out, other triangular + corners comprising three unmasked points are contoured as usual. + +colors : :mpltype:`color` or list of :mpltype:`color`, optional + The colors of the levels, i.e. the lines for `.contour` and the + areas for `.contourf`. + + The sequence is cycled for the levels in ascending order. If the + sequence is shorter than the number of levels, it's repeated. + + As a shortcut, a single color may be used in place of one-element lists, i.e. + ``'red'`` instead of ``['red']`` to color all levels with the same color. + + .. versionchanged:: 3.10 + Previously a single color had to be expressed as a string, but now any + valid color format may be passed. + + By default (value *None*), the colormap specified by *cmap* + will be used. + +alpha : float, default: 1 + The alpha blending value, between 0 (transparent) and 1 (opaque). + +cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap` + The Colormap instance or registered colormap name used to map scalar data + to colors. + + This parameter is ignored if *colors* is set. + +norm : str or `~matplotlib.colors.Normalize`, optional + The normalization method used to scale scalar data to the [0, 1] range + before mapping to colors using *cmap*. By default, a linear scaling is + used, mapping the lowest value to 0 and the highest to 1. + + If given, this can be one of the following: + + - An instance of `.Normalize` or one of its subclasses + (see :ref:`colormapnorms`). + - A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For a + list of available scales, call `matplotlib.scale.get_scale_names()`. + In that case, a suitable `.Normalize` subclass is dynamically generated + and instantiated. + + This parameter is ignored if *colors* is set. + +vmin, vmax : float, optional + When using scalar data and no explicit *norm*, *vmin* and *vmax* define + the data range that the colormap covers. By default, the colormap covers + the complete value range of the supplied data. It is an error to use + *vmin*/*vmax* when a *norm* instance is given (but using a `str` *norm* + name together with *vmin*/*vmax* is acceptable). + + If *vmin* or *vmax* are not given, the default color scaling is based on + *levels*. + + This parameter is ignored if *colors* is set. + +colorizer : `~matplotlib.colorizer.Colorizer` or None, default: None + The Colorizer object used to map color to data. If None, a Colorizer + object is created from a *norm* and *cmap*. + + This parameter is ignored if *colors* is set. + +origin : {*None*, 'upper', 'lower', 'image'}, default: None + Determines the orientation and exact position of *Z* by specifying + the position of ``Z[0, 0]``. This is only relevant, if *X*, *Y* + are not given. + + - *None*: ``Z[0, 0]`` is at X=0, Y=0 in the lower left corner. + - 'lower': ``Z[0, 0]`` is at X=0.5, Y=0.5 in the lower left corner. + - 'upper': ``Z[0, 0]`` is at X=N+0.5, Y=0.5 in the upper left + corner. + - 'image': Use the value from :rc:`image.origin`. + +extent : (x0, x1, y0, y1), optional + If *origin* is not *None*, then *extent* is interpreted as in + `.imshow`: it gives the outer pixel boundaries. In this case, the + position of Z[0, 0] is the center of the pixel, not a corner. If + *origin* is *None*, then (*x0*, *y0*) is the position of Z[0, 0], + and (*x1*, *y1*) is the position of Z[-1, -1]. + + This argument is ignored if *X* and *Y* are specified in the call + to contour. + +locator : ticker.Locator subclass, optional + The locator is used to determine the contour levels if they + are not given explicitly via *levels*. + Defaults to `~.ticker.MaxNLocator`. + +extend : {'neither', 'both', 'min', 'max'}, default: 'neither' + Determines the ``contourf``-coloring of values that are outside the + *levels* range. + + If 'neither', values outside the *levels* range are not colored. + If 'min', 'max' or 'both', color the values below, above or below + and above the *levels* range. + + Values below ``min(levels)`` and above ``max(levels)`` are mapped + to the under/over values of the `.Colormap`. Note that most + colormaps do not have dedicated colors for these by default, so + that the over and under values are the edge values of the colormap. + You may want to set these values explicitly using + `.Colormap.set_under` and `.Colormap.set_over`. + + .. note:: + + An existing `.QuadContourSet` does not get notified if + properties of its colormap are changed. Therefore, an explicit + call `~.ContourSet.changed()` is needed after modifying the + colormap. The explicit call can be left out, if a colorbar is + assigned to the `.QuadContourSet` because it internally calls + `~.ContourSet.changed()`. + + Example:: + + x = np.arange(1, 10) + y = x.reshape(-1, 1) + h = x * y + + cs = plt.contourf(h, levels=[10, 30, 50], + colors=['#808080', '#A0A0A0', '#C0C0C0'], extend='both') + cs.cmap.set_over('red') + cs.cmap.set_under('blue') + cs.changed() + +xunits, yunits : registered units, optional + Override axis units by specifying an instance of a + :class:`matplotlib.units.ConversionInterface`. + +antialiased : bool, optional + Enable antialiasing, overriding the defaults. For + filled contours, the default is *False*. For line contours, + it is taken from :rc:`lines.antialiased`. + +nchunk : int >= 0, optional + If 0, no subdivision of the domain. Specify a positive integer to + divide the domain into subdomains of *nchunk* by *nchunk* quads. + Chunking reduces the maximum length of polygons generated by the + contouring algorithm which reduces the rendering workload passed + on to the backend and also requires slightly less RAM. It can + however introduce rendering artifacts at chunk boundaries depending + on the backend, the *antialiased* flag and value of *alpha*. + +linewidths : float or array-like, default: :rc:`contour.linewidth` + *Only applies to* `.contour`. + + The line width of the contour lines. + + If a number, all levels will be plotted with this linewidth. + + If a sequence, the levels in ascending order will be plotted with + the linewidths in the order specified. + + If None, this falls back to :rc:`lines.linewidth`. + +linestyles : {*None*, 'solid', 'dashed', 'dashdot', 'dotted'}, optional + *Only applies to* `.contour`. + + If *linestyles* is *None*, the default is 'solid' unless the lines are + monochrome. In that case, negative contours will instead take their + linestyle from the *negative_linestyles* argument. + + *linestyles* can also be an iterable of the above strings specifying a set + of linestyles to be used. If this iterable is shorter than the number of + contour levels it will be repeated as necessary. + +negative_linestyles : {*None*, 'solid', 'dashed', 'dashdot', 'dotted'}, optional + *Only applies to* `.contour`. + + If *linestyles* is *None* and the lines are monochrome, this argument + specifies the line style for negative contours. + + If *negative_linestyles* is *None*, the default is taken from + :rc:`contour.negative_linestyle`. + + *negative_linestyles* can also be an iterable of the above strings + specifying a set of linestyles to be used. If this iterable is shorter than + the number of contour levels it will be repeated as necessary. + +hatches : list[str], optional + *Only applies to* `.contourf`. + + A list of cross hatch patterns to use on the filled areas. + If None, no hatching will be added to the contour. + +algorithm : {'mpl2005', 'mpl2014', 'serial', 'threaded'}, optional + Which contouring algorithm to use to calculate the contour lines and + polygons. The algorithms are implemented in + `ContourPy `_, consult the + `ContourPy documentation `_ for + further information. + + The default is taken from :rc:`contour.algorithm`. + +clip_path : `~matplotlib.patches.Patch` or `.Path` or `.TransformedPath` + Set the clip path. See `~matplotlib.artist.Artist.set_clip_path`. + + .. versionadded:: 3.8 + +data : indexable object, optional + If given, all parameters also accept a string ``s``, which is + interpreted as ``data[s]`` if ``s`` is a key in ``data``. + +Notes +----- +1. `.contourf` differs from the MATLAB version in that it does not draw + the polygon edges. To draw edges, add line contours with calls to + `.contour`. + +2. `.contourf` fills intervals that are closed at the top; that is, for + boundaries *z1* and *z2*, the filled region is:: + + z1 < Z <= z2 + + except for the lowest interval, which is closed on both sides (i.e. + it includes the lowest value). + +3. `.contour` and `.contourf` use a `marching squares + `_ algorithm to + compute contour locations. More information can be found in + `ContourPy documentation `_.""" ... def pcolor(self, x: Incomplete, y: Incomplete, z: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -7251,7 +10013,219 @@ PlotAxes.pcolormesh PlotAxes.pcolorfast PlotAxes.heatmap PlotAxes.tripcolor -matplotlib.axes.Axes.pcolor""" +matplotlib.axes.Axes.pcolor + +Matplotlib documentation + + +Create a pseudocolor plot with a non-regular rectangular grid. + +Call signature:: + + pcolor([X, Y,] C, /, **kwargs) + +*X* and *Y* can be used to specify the corners of the quadrilaterals. + +The arguments *X*, *Y*, *C* are positional-only. + +.. hint:: + + ``pcolor()`` can be very slow for large arrays. In most + cases you should use the similar but much faster + `~.Axes.pcolormesh` instead. See + :ref:`Differences between pcolor() and pcolormesh() + ` for a discussion of the + differences. + +Parameters +---------- +C : 2D array-like + The color-mapped values. Color-mapping is controlled by *cmap*, + *norm*, *vmin*, and *vmax*. + +X, Y : array-like, optional + The coordinates of the corners of quadrilaterals of a pcolormesh:: + + (X[i+1, j], Y[i+1, j]) (X[i+1, j+1], Y[i+1, j+1]) + ●╶───╴● + │ │ + ●╶───╴● + (X[i, j], Y[i, j]) (X[i, j+1], Y[i, j+1]) + + Note that the column index corresponds to the x-coordinate, and + the row index corresponds to y. For details, see the + :ref:`Notes ` section below. + + If ``shading='flat'`` the dimensions of *X* and *Y* should be one + greater than those of *C*, and the quadrilateral is colored due + to the value at ``C[i, j]``. If *X*, *Y* and *C* have equal + dimensions, a warning will be raised and the last row and column + of *C* will be ignored. + + If ``shading='nearest'``, the dimensions of *X* and *Y* should be + the same as those of *C* (if not, a ValueError will be raised). The + color ``C[i, j]`` will be centered on ``(X[i, j], Y[i, j])``. + + If *X* and/or *Y* are 1-D arrays or column vectors they will be + expanded as needed into the appropriate 2D arrays, making a + rectangular grid. + +shading : {'flat', 'nearest', 'auto'}, default: :rc:`pcolor.shading` + The fill style for the quadrilateral. Possible values: + + - 'flat': A solid color is used for each quad. The color of the + quad (i, j), (i+1, j), (i, j+1), (i+1, j+1) is given by + ``C[i, j]``. The dimensions of *X* and *Y* should be + one greater than those of *C*; if they are the same as *C*, + then a deprecation warning is raised, and the last row + and column of *C* are dropped. + - 'nearest': Each grid point will have a color centered on it, + extending halfway between the adjacent grid centers. The + dimensions of *X* and *Y* must be the same as *C*. + - 'auto': Choose 'flat' if dimensions of *X* and *Y* are one + larger than *C*. Choose 'nearest' if dimensions are the same. + + See :doc:`/gallery/images_contours_and_fields/pcolormesh_grids` + for more description. + +cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap` + The Colormap instance or registered colormap name used to map scalar data + to colors. + +norm : str or `~matplotlib.colors.Normalize`, optional + The normalization method used to scale scalar data to the [0, 1] range + before mapping to colors using *cmap*. By default, a linear scaling is + used, mapping the lowest value to 0 and the highest to 1. + + If given, this can be one of the following: + + - An instance of `.Normalize` or one of its subclasses + (see :ref:`colormapnorms`). + - A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For a + list of available scales, call `matplotlib.scale.get_scale_names()`. + In that case, a suitable `.Normalize` subclass is dynamically generated + and instantiated. + +vmin, vmax : float, optional + When using scalar data and no explicit *norm*, *vmin* and *vmax* define + the data range that the colormap covers. By default, the colormap covers + the complete value range of the supplied data. It is an error to use + *vmin*/*vmax* when a *norm* instance is given (but using a `str` *norm* + name together with *vmin*/*vmax* is acceptable). + +colorizer : `~matplotlib.colorizer.Colorizer` or None, default: None + The Colorizer object used to map color to data. If None, a Colorizer + object is created from a *norm* and *cmap*. + +edgecolors : {'none', None, 'face', color, color sequence}, optional + The color of the edges. Defaults to 'none'. Possible values: + + - 'none' or '': No edge. + - *None*: :rc:`patch.edgecolor` will be used. Note that currently + :rc:`patch.force_edgecolor` has to be True for this to work. + - 'face': Use the adjacent face color. + - A color or sequence of colors will set the edge color. + + The singular form *edgecolor* works as an alias. + +alpha : float, default: None + The alpha blending value of the face color, between 0 (transparent) + and 1 (opaque). Note: The edgecolor is currently not affected by + this. + +snap : bool, default: False + Whether to snap the mesh to pixel boundaries. + +Returns +------- +`matplotlib.collections.PolyQuadMesh` + +Other Parameters +---------------- +antialiaseds : bool, default: False + The default *antialiaseds* is False if the default + *edgecolors*\\ ="none" is used. This eliminates artificial lines + at patch boundaries, and works regardless of the value of alpha. + If *edgecolors* is not "none", then the default *antialiaseds* + is taken from :rc:`patch.antialiased`. + Stroking the edges may be preferred if *alpha* is 1, but will + cause artifacts otherwise. + +data : indexable object, optional + If given, all parameters also accept a string ``s``, which is + interpreted as ``data[s]`` if ``s`` is a key in ``data``. + +**kwargs + Additionally, the following arguments are allowed. They are passed + along to the `~matplotlib.collections.PolyQuadMesh` constructor: + +Properties: + agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image + alpha: array-like or float or None + animated: bool + antialiased or aa or antialiaseds: bool or list of bools + array: array-like or None + capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} + clim: (vmin: float, vmax: float) + clip_box: `~matplotlib.transforms.BboxBase` or None + clip_on: bool + clip_path: Patch or (Path, Transform) or None + cmap: `.Colormap` or str or None + color: :mpltype:`color` or list of RGBA tuples + edgecolor or ec or edgecolors: :mpltype:`color` or list of :mpltype:`color` or 'face' + facecolor or facecolors or fc: :mpltype:`color` or list of :mpltype:`color` + figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + gid: str + hatch: {'/', '\\\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'} + hatch_linewidth: unknown + in_layout: bool + joinstyle: `.JoinStyle` or {'miter', 'round', 'bevel'} + label: object + linestyle or dashes or linestyles or ls: str or tuple or list thereof + linewidth or linewidths or lw: float or list of floats + mouseover: bool + norm: `.Normalize` or str or None + offset_transform or transOffset: `.Transform` + offsets: (N, 2) or (2,) array-like + path_effects: list of `.AbstractPathEffect` + paths: list of array-like + picker: None or bool or float or callable + pickradius: float + rasterized: bool + sizes: `numpy.ndarray` or None + sketch_params: (scale: float, length: float, randomness: float) + snap: bool or None + transform: `~matplotlib.transforms.Transform` + url: str + urls: list of str or None + verts: list of array-like + verts_and_codes: unknown + visible: bool + zorder: float + +See Also +-------- +pcolormesh : for an explanation of the differences between + pcolor and pcolormesh. +imshow : If *X* and *Y* are each equidistant, `~.Axes.imshow` can be a + faster alternative. + +Notes +----- +**Masked arrays** + +*X*, *Y* and *C* may be masked arrays. If either ``C[i, j]``, or one +of the vertices surrounding ``C[i, j]`` (*X* or *Y* at +``[i, j], [i+1, j], [i, j+1], [i+1, j+1]``) is masked, nothing is +plotted. + +.. _axes-pcolor-grid-orientation: + +**Grid orientation** + +The grid orientation follows the standard matrix convention: An array +*C* with shape (nrows, ncolumns) is plotted with the column number as +*X* and the row number as *Y*.""" ... def pcolormesh(self, x: Incomplete, y: Incomplete, z: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -7465,7 +10439,254 @@ PlotAxes.pcolormesh PlotAxes.pcolorfast PlotAxes.heatmap PlotAxes.tripcolor -matplotlib.axes.Axes.pcolormesh""" +matplotlib.axes.Axes.pcolormesh + +Matplotlib documentation + + +Create a pseudocolor plot with a non-regular rectangular grid. + +Call signature:: + + pcolormesh([X, Y,] C, /, **kwargs) + +*X* and *Y* can be used to specify the corners of the quadrilaterals. + +The arguments *X*, *Y*, *C* are positional-only. + +.. hint:: + + `~.Axes.pcolormesh` is similar to `~.Axes.pcolor`. It is much faster + and preferred in most cases. For a detailed discussion on the + differences see :ref:`Differences between pcolor() and pcolormesh() + `. + +Parameters +---------- +C : array-like + The mesh data. Supported array shapes are: + + - (M, N) or M*N: a mesh with scalar data. The values are mapped to + colors using normalization and a colormap. See parameters *norm*, + *cmap*, *vmin*, *vmax*. + - (M, N, 3): an image with RGB values (0-1 float or 0-255 int). + - (M, N, 4): an image with RGBA values (0-1 float or 0-255 int), + i.e. including transparency. + + The first two dimensions (M, N) define the rows and columns of + the mesh data. + +X, Y : array-like, optional + The coordinates of the corners of quadrilaterals of a pcolormesh:: + + (X[i+1, j], Y[i+1, j]) (X[i+1, j+1], Y[i+1, j+1]) + ●╶───╴● + │ │ + ●╶───╴● + (X[i, j], Y[i, j]) (X[i, j+1], Y[i, j+1]) + + Note that the column index corresponds to the x-coordinate, and + the row index corresponds to y. For details, see the + :ref:`Notes ` section below. + + If ``shading='flat'`` the dimensions of *X* and *Y* should be one + greater than those of *C*, and the quadrilateral is colored due + to the value at ``C[i, j]``. If *X*, *Y* and *C* have equal + dimensions, a warning will be raised and the last row and column + of *C* will be ignored. + + If ``shading='nearest'`` or ``'gouraud'``, the dimensions of *X* + and *Y* should be the same as those of *C* (if not, a ValueError + will be raised). For ``'nearest'`` the color ``C[i, j]`` is + centered on ``(X[i, j], Y[i, j])``. For ``'gouraud'``, a smooth + interpolation is carried out between the quadrilateral corners. + + If *X* and/or *Y* are 1-D arrays or column vectors they will be + expanded as needed into the appropriate 2D arrays, making a + rectangular grid. + +cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap` + The Colormap instance or registered colormap name used to map scalar data + to colors. + +norm : str or `~matplotlib.colors.Normalize`, optional + The normalization method used to scale scalar data to the [0, 1] range + before mapping to colors using *cmap*. By default, a linear scaling is + used, mapping the lowest value to 0 and the highest to 1. + + If given, this can be one of the following: + + - An instance of `.Normalize` or one of its subclasses + (see :ref:`colormapnorms`). + - A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For a + list of available scales, call `matplotlib.scale.get_scale_names()`. + In that case, a suitable `.Normalize` subclass is dynamically generated + and instantiated. + +vmin, vmax : float, optional + When using scalar data and no explicit *norm*, *vmin* and *vmax* define + the data range that the colormap covers. By default, the colormap covers + the complete value range of the supplied data. It is an error to use + *vmin*/*vmax* when a *norm* instance is given (but using a `str` *norm* + name together with *vmin*/*vmax* is acceptable). + +colorizer : `~matplotlib.colorizer.Colorizer` or None, default: None + The Colorizer object used to map color to data. If None, a Colorizer + object is created from a *norm* and *cmap*. + +edgecolors : {'none', None, 'face', color, color sequence}, optional + The color of the edges. Defaults to 'none'. Possible values: + + - 'none' or '': No edge. + - *None*: :rc:`patch.edgecolor` will be used. Note that currently + :rc:`patch.force_edgecolor` has to be True for this to work. + - 'face': Use the adjacent face color. + - A color or sequence of colors will set the edge color. + + The singular form *edgecolor* works as an alias. + +alpha : float, default: None + The alpha blending value, between 0 (transparent) and 1 (opaque). + +shading : {'flat', 'nearest', 'gouraud', 'auto'}, optional + The fill style for the quadrilateral; defaults to + :rc:`pcolor.shading`. Possible values: + + - 'flat': A solid color is used for each quad. The color of the + quad (i, j), (i+1, j), (i, j+1), (i+1, j+1) is given by + ``C[i, j]``. The dimensions of *X* and *Y* should be + one greater than those of *C*; if they are the same as *C*, + then a deprecation warning is raised, and the last row + and column of *C* are dropped. + - 'nearest': Each grid point will have a color centered on it, + extending halfway between the adjacent grid centers. The + dimensions of *X* and *Y* must be the same as *C*. + - 'gouraud': Each quad will be Gouraud shaded: The color of the + corners (i', j') are given by ``C[i', j']``. The color values of + the area in between is interpolated from the corner values. + The dimensions of *X* and *Y* must be the same as *C*. When + Gouraud shading is used, *edgecolors* is ignored. + - 'auto': Choose 'flat' if dimensions of *X* and *Y* are one + larger than *C*. Choose 'nearest' if dimensions are the same. + + See :doc:`/gallery/images_contours_and_fields/pcolormesh_grids` + for more description. + +snap : bool, default: False + Whether to snap the mesh to pixel boundaries. + +rasterized : bool, optional + Rasterize the pcolormesh when drawing vector graphics. This can + speed up rendering and produce smaller files for large data sets. + See also :doc:`/gallery/misc/rasterization_demo`. + +Returns +------- +`matplotlib.collections.QuadMesh` + +Other Parameters +---------------- +data : indexable object, optional + If given, all parameters also accept a string ``s``, which is + interpreted as ``data[s]`` if ``s`` is a key in ``data``. + +**kwargs + Additionally, the following arguments are allowed. They are passed + along to the `~matplotlib.collections.QuadMesh` constructor: + +Properties: + agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image + alpha: array-like or float or None + animated: bool + antialiased or aa or antialiaseds: bool or list of bools + array: array-like + capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} + clim: (vmin: float, vmax: float) + clip_box: `~matplotlib.transforms.BboxBase` or None + clip_on: bool + clip_path: Patch or (Path, Transform) or None + cmap: `.Colormap` or str or None + color: :mpltype:`color` or list of RGBA tuples + edgecolor or ec or edgecolors: :mpltype:`color` or list of :mpltype:`color` or 'face' + facecolor or facecolors or fc: :mpltype:`color` or list of :mpltype:`color` + figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + gid: str + hatch: {'/', '\\\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'} + hatch_linewidth: unknown + in_layout: bool + joinstyle: `.JoinStyle` or {'miter', 'round', 'bevel'} + label: object + linestyle or dashes or linestyles or ls: str or tuple or list thereof + linewidth or linewidths or lw: float or list of floats + mouseover: bool + norm: `.Normalize` or str or None + offset_transform or transOffset: `.Transform` + offsets: (N, 2) or (2,) array-like + path_effects: list of `.AbstractPathEffect` + picker: None or bool or float or callable + pickradius: float + rasterized: bool + sketch_params: (scale: float, length: float, randomness: float) + snap: bool or None + transform: `~matplotlib.transforms.Transform` + url: str + urls: list of str or None + visible: bool + zorder: float + +See Also +-------- +pcolor : An alternative implementation with slightly different + features. For a detailed discussion on the differences see + :ref:`Differences between pcolor() and pcolormesh() + `. +imshow : If *X* and *Y* are each equidistant, `~.Axes.imshow` can be a + faster alternative. + +Notes +----- +**Masked arrays** + +*C* may be a masked array. If ``C[i, j]`` is masked, the corresponding +quadrilateral will be transparent. Masking of *X* and *Y* is not +supported. Use `~.Axes.pcolor` if you need this functionality. + +.. _axes-pcolormesh-grid-orientation: + +**Grid orientation** + +The grid orientation follows the standard matrix convention: An array +*C* with shape (nrows, ncolumns) is plotted with the column number as +*X* and the row number as *Y*. + +.. _differences-pcolor-pcolormesh: + +**Differences between pcolor() and pcolormesh()** + +Both methods are used to create a pseudocolor plot of a 2D array +using quadrilaterals. + +The main difference lies in the created object and internal data +handling: +While `~.Axes.pcolor` returns a `.PolyQuadMesh`, `~.Axes.pcolormesh` +returns a `.QuadMesh`. The latter is more specialized for the given +purpose and thus is faster. It should almost always be preferred. + +There is also a slight difference in the handling of masked arrays. +Both `~.Axes.pcolor` and `~.Axes.pcolormesh` support masked arrays +for *C*. However, only `~.Axes.pcolor` supports masked arrays for *X* +and *Y*. The reason lies in the internal handling of the masked values. +`~.Axes.pcolor` leaves out the respective polygons from the +PolyQuadMesh. `~.Axes.pcolormesh` sets the facecolor of the masked +elements to transparent. You can see the difference when using +edgecolors. While all edges are drawn irrespective of masking in a +QuadMesh, the edge between two adjacent masked quadrilaterals in +`~.Axes.pcolor` is not drawn as the corresponding polygons do not +exist in the PolyQuadMesh. Because PolyQuadMesh draws each individual +polygon, it also supports applying hatches and linestyles to the collection. + +Another difference is the support of Gouraud shading in +`~.Axes.pcolormesh`, which is not available with `~.Axes.pcolor`.""" ... def pcolorfast(self, x: Incomplete, y: Incomplete, z: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -7679,7 +10900,144 @@ PlotAxes.pcolormesh PlotAxes.pcolorfast PlotAxes.heatmap PlotAxes.tripcolor -matplotlib.axes.Axes.pcolorfast""" +matplotlib.axes.Axes.pcolorfast + +Matplotlib documentation + + +Create a pseudocolor plot with a non-regular rectangular grid. + +Call signature:: + + ax.pcolorfast([X, Y], C, /, **kwargs) + +The arguments *X*, *Y*, *C* are positional-only. + +This method is similar to `~.Axes.pcolor` and `~.Axes.pcolormesh`. +It's designed to provide the fastest pcolor-type plotting with the +Agg backend. To achieve this, it uses different algorithms internally +depending on the complexity of the input grid (regular rectangular, +non-regular rectangular or arbitrary quadrilateral). + +.. warning:: + + This method is experimental. Compared to `~.Axes.pcolor` or + `~.Axes.pcolormesh` it has some limitations: + + - It supports only flat shading (no outlines) + - It lacks support for log scaling of the axes. + - It does not have a pyplot wrapper. + +Parameters +---------- +C : array-like + The image data. Supported array shapes are: + + - (M, N): an image with scalar data. Color-mapping is controlled + by *cmap*, *norm*, *vmin*, and *vmax*. + - (M, N, 3): an image with RGB values (0-1 float or 0-255 int). + - (M, N, 4): an image with RGBA values (0-1 float or 0-255 int), + i.e. including transparency. + + The first two dimensions (M, N) define the rows and columns of + the image. + + This parameter can only be passed positionally. + +X, Y : tuple or array-like, default: ``(0, N)``, ``(0, M)`` + *X* and *Y* are used to specify the coordinates of the + quadrilaterals. There are different ways to do this: + + - Use tuples ``X=(xmin, xmax)`` and ``Y=(ymin, ymax)`` to define + a *uniform rectangular grid*. + + The tuples define the outer edges of the grid. All individual + quadrilaterals will be of the same size. This is the fastest + version. + + - Use 1D arrays *X*, *Y* to specify a *non-uniform rectangular + grid*. + + In this case *X* and *Y* have to be monotonic 1D arrays of length + *N+1* and *M+1*, specifying the x and y boundaries of the cells. + + The speed is intermediate. Note: The grid is checked, and if + found to be uniform the fast version is used. + + - Use 2D arrays *X*, *Y* if you need an *arbitrary quadrilateral + grid* (i.e. if the quadrilaterals are not rectangular). + + In this case *X* and *Y* are 2D arrays with shape (M + 1, N + 1), + specifying the x and y coordinates of the corners of the colored + quadrilaterals. + + This is the most general, but the slowest to render. It may + produce faster and more compact output using ps, pdf, and + svg backends, however. + + These arguments can only be passed positionally. + +cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap` + The Colormap instance or registered colormap name used to map scalar data + to colors. + + This parameter is ignored if *C* is RGB(A). + +norm : str or `~matplotlib.colors.Normalize`, optional + The normalization method used to scale scalar data to the [0, 1] range + before mapping to colors using *cmap*. By default, a linear scaling is + used, mapping the lowest value to 0 and the highest to 1. + + If given, this can be one of the following: + + - An instance of `.Normalize` or one of its subclasses + (see :ref:`colormapnorms`). + - A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For a + list of available scales, call `matplotlib.scale.get_scale_names()`. + In that case, a suitable `.Normalize` subclass is dynamically generated + and instantiated. + + This parameter is ignored if *C* is RGB(A). + +vmin, vmax : float, optional + When using scalar data and no explicit *norm*, *vmin* and *vmax* define + the data range that the colormap covers. By default, the colormap covers + the complete value range of the supplied data. It is an error to use + *vmin*/*vmax* when a *norm* instance is given (but using a `str` *norm* + name together with *vmin*/*vmax* is acceptable). + + This parameter is ignored if *C* is RGB(A). + +colorizer : `~matplotlib.colorizer.Colorizer` or None, default: None + The Colorizer object used to map color to data. If None, a Colorizer + object is created from a *norm* and *cmap*. + + This parameter is ignored if *C* is RGB(A). + +alpha : float, default: None + The alpha blending value, between 0 (transparent) and 1 (opaque). + +snap : bool, default: False + Whether to snap the mesh to pixel boundaries. + +Returns +------- +`.AxesImage` or `.PcolorImage` or `.QuadMesh` + The return type depends on the type of grid: + + - `.AxesImage` for a regular rectangular grid. + - `.PcolorImage` for a non-regular rectangular grid. + - `.QuadMesh` for a non-rectangular grid. + +Other Parameters +---------------- +data : indexable object, optional + If given, all parameters also accept a string ``s``, which is + interpreted as ``data[s]`` if ``s`` is a key in ``data``. + +**kwargs + Supported additional parameters depend on the type of grid. + See return types of *image* for further description.""" ... def heatmap(self, *args: Incomplete, aspect: Incomplete=None, **kwargs: Incomplete) -> Incomplete: @@ -8067,7 +11425,188 @@ PlotAxes.barbs PlotAxes.quiver PlotAxes.stream PlotAxes.streamplot -matplotlib.axes.Axes.barbs""" +matplotlib.axes.Axes.barbs + +Matplotlib documentation + + +Plot a 2D field of wind barbs. + +Call signature:: + + barbs([X, Y], U, V, [C], /, **kwargs) + +Where *X*, *Y* define the barb locations, *U*, *V* define the barb +directions, and *C* optionally sets the color. + +The arguments *X*, *Y*, *U*, *V*, *C* are positional-only and may be +1D or 2D. *U*, *V*, *C* may be masked arrays, but masked *X*, *Y* +are not supported at present. + +Barbs are traditionally used in meteorology as a way to plot the speed +and direction of wind observations, but can technically be used to +plot any two dimensional vector quantity. As opposed to arrows, which +give vector magnitude by the length of the arrow, the barbs give more +quantitative information about the vector magnitude by putting slanted +lines or a triangle for various increments in magnitude, as show +schematically below:: + + : /\\ \\ + : / \\ \\ + : / \\ \\ \\ + : / \\ \\ \\ + : ------------------------------ + +The largest increment is given by a triangle (or "flag"). After those +come full lines (barbs). The smallest increment is a half line. There +is only, of course, ever at most 1 half line. If the magnitude is +small and only needs a single half-line and no full lines or +triangles, the half-line is offset from the end of the barb so that it +can be easily distinguished from barbs with a single full line. The +magnitude for the barb shown above would nominally be 65, using the +standard increments of 50, 10, and 5. + +See also https://en.wikipedia.org/wiki/Wind_barb. + +Parameters +---------- +X, Y : 1D or 2D array-like, optional + The x and y coordinates of the barb locations. See *pivot* for how the + barbs are drawn to the x, y positions. + + If not given, they will be generated as a uniform integer meshgrid based + on the dimensions of *U* and *V*. + + If *X* and *Y* are 1D but *U*, *V* are 2D, *X*, *Y* are expanded to 2D + using ``X, Y = np.meshgrid(X, Y)``. In this case ``len(X)`` and ``len(Y)`` + must match the column and row dimensions of *U* and *V*. + +U, V : 1D or 2D array-like + The x and y components of the barb shaft. + +C : 1D or 2D array-like, optional + Numeric data that defines the barb colors by colormapping via *norm* and + *cmap*. + + This does not support explicit colors. If you want to set colors directly, + use *barbcolor* instead. + +length : float, default: 7 + Length of the barb in points; the other parts of the barb + are scaled against this. + +pivot : {'tip', 'middle'} or float, default: 'tip' + The part of the arrow that is anchored to the *X*, *Y* grid. The barb + rotates about this point. This can also be a number, which shifts the + start of the barb that many points away from grid point. + +barbcolor : :mpltype:`color` or color sequence + The color of all parts of the barb except for the flags. This parameter + is analogous to the *edgecolor* parameter for polygons, which can be used + instead. However this parameter will override facecolor. + +flagcolor : :mpltype:`color` or color sequence + The color of any flags on the barb. This parameter is analogous to the + *facecolor* parameter for polygons, which can be used instead. However, + this parameter will override facecolor. If this is not set (and *C* has + not either) then *flagcolor* will be set to match *barbcolor* so that the + barb has a uniform color. If *C* has been set, *flagcolor* has no effect. + +sizes : dict, optional + A dictionary of coefficients specifying the ratio of a given + feature to the length of the barb. Only those values one wishes to + override need to be included. These features include: + + - 'spacing' - space between features (flags, full/half barbs) + - 'height' - height (distance from shaft to top) of a flag or full barb + - 'width' - width of a flag, twice the width of a full barb + - 'emptybarb' - radius of the circle used for low magnitudes + +fill_empty : bool, default: False + Whether the empty barbs (circles) that are drawn should be filled with + the flag color. If they are not filled, the center is transparent. + +rounding : bool, default: True + Whether the vector magnitude should be rounded when allocating barb + components. If True, the magnitude is rounded to the nearest multiple + of the half-barb increment. If False, the magnitude is simply truncated + to the next lowest multiple. + +barb_increments : dict, optional + A dictionary of increments specifying values to associate with + different parts of the barb. Only those values one wishes to + override need to be included. + + - 'half' - half barbs (Default is 5) + - 'full' - full barbs (Default is 10) + - 'flag' - flags (default is 50) + +flip_barb : bool or array-like of bool, default: False + Whether the lines and flags should point opposite to normal. + Normal behavior is for the barbs and lines to point right (comes from wind + barbs having these features point towards low pressure in the Northern + Hemisphere). + + A single value is applied to all barbs. Individual barbs can be flipped by + passing a bool array of the same size as *U* and *V*. + +Returns +------- +barbs : `~matplotlib.quiver.Barbs` + +Other Parameters +---------------- +data : indexable object, optional + If given, all parameters also accept a string ``s``, which is + interpreted as ``data[s]`` if ``s`` is a key in ``data``. + +**kwargs + The barbs can further be customized using `.PolyCollection` keyword + arguments: + + Properties: + agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image + alpha: array-like or float or None + animated: bool + antialiased or aa or antialiaseds: bool or list of bools + array: array-like or None + capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} + clim: (vmin: float, vmax: float) + clip_box: `~matplotlib.transforms.BboxBase` or None + clip_on: bool + clip_path: Patch or (Path, Transform) or None + cmap: `.Colormap` or str or None + color: :mpltype:`color` or list of RGBA tuples + edgecolor or ec or edgecolors: :mpltype:`color` or list of :mpltype:`color` or 'face' + facecolor or facecolors or fc: :mpltype:`color` or list of :mpltype:`color` + figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + gid: str + hatch: {'/', '\\\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'} + hatch_linewidth: unknown + in_layout: bool + joinstyle: `.JoinStyle` or {'miter', 'round', 'bevel'} + label: object + linestyle or dashes or linestyles or ls: str or tuple or list thereof + linewidth or linewidths or lw: float or list of floats + mouseover: bool + norm: `.Normalize` or str or None + offset_transform or transOffset: `.Transform` + offsets: (N, 2) or (2,) array-like + path_effects: list of `.AbstractPathEffect` + paths: list of array-like + picker: None or bool or float or callable + pickradius: float + rasterized: bool + sizes: `numpy.ndarray` or None + sketch_params: (scale: float, length: float, randomness: float) + snap: bool or None + transform: `~matplotlib.transforms.Transform` + url: str + urls: list of str or None + verts: list of array-like + verts_and_codes: unknown + visible: bool + zorder: float""" ... def quiver(self, x: Incomplete, y: Incomplete, u: Incomplete, v: Incomplete, c: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -8224,13 +11763,301 @@ nozero : bool, default: False **kwargs Passed to `matplotlib.axes.Axes.quiver` -See also +See also +-------- +PlotAxes.barbs +PlotAxes.quiver +PlotAxes.stream +PlotAxes.streamplot +matplotlib.axes.Axes.quiver + +Matplotlib documentation + + +Plot a 2D field of arrows. + +Call signature:: + + quiver([X, Y], U, V, [C], /, **kwargs) + +*X*, *Y* define the arrow locations, *U*, *V* define the arrow directions, and +*C* optionally sets the color. The arguments *X*, *Y*, *U*, *V*, *C* are +positional-only. + +**Arrow length** + +The default settings auto-scales the length of the arrows to a reasonable size. +To change this behavior see the *scale* and *scale_units* parameters. + +**Arrow shape** + +The arrow shape is determined by *width*, *headwidth*, *headlength* and +*headaxislength*. See the notes below. + +**Arrow styling** + +Each arrow is internally represented by a filled polygon with a default edge +linewidth of 0. As a result, an arrow is rather a filled area, not a line with +a head, and `.PolyCollection` properties like *linewidth*, *edgecolor*, +*facecolor*, etc. act accordingly. + + +Parameters +---------- +X, Y : 1D or 2D array-like, optional + The x and y coordinates of the arrow locations. + + If not given, they will be generated as a uniform integer meshgrid based + on the dimensions of *U* and *V*. + + If *X* and *Y* are 1D but *U*, *V* are 2D, *X*, *Y* are expanded to 2D + using ``X, Y = np.meshgrid(X, Y)``. In this case ``len(X)`` and ``len(Y)`` + must match the column and row dimensions of *U* and *V*. + +U, V : 1D or 2D array-like + The x and y direction components of the arrow vectors. The interpretation + of these components (in data or in screen space) depends on *angles*. + + *U* and *V* must have the same number of elements, matching the number of + arrow locations in *X*, *Y*. *U* and *V* may be masked. Locations masked + in any of *U*, *V*, and *C* will not be drawn. + +C : 1D or 2D array-like, optional + Numeric data that defines the arrow colors by colormapping via *norm* and + *cmap*. + + This does not support explicit colors. If you want to set colors directly, + use *color* instead. The size of *C* must match the number of arrow + locations. + +angles : {'uv', 'xy'} or array-like, default: 'uv' + Method for determining the angle of the arrows. + + - 'uv': Arrow directions are based on + :ref:`display coordinates `; i.e. a 45° angle will + always show up as diagonal on the screen, irrespective of figure or Axes + aspect ratio or Axes data ranges. This is useful when the arrows represent + a quantity whose direction is not tied to the x and y data coordinates. + + If *U* == *V* the orientation of the arrow on the plot is 45 degrees + counter-clockwise from the horizontal axis (positive to the right). + + - 'xy': Arrow direction in data coordinates, i.e. the arrows point from + (x, y) to (x+u, y+v). This is ideal for vector fields or gradient plots + where the arrows should directly represent movements or gradients in the + x and y directions. + + - Arbitrary angles may be specified explicitly as an array of values + in degrees, counter-clockwise from the horizontal axis. + + In this case *U*, *V* is only used to determine the length of the + arrows. + + For example, ``angles=[30, 60, 90]`` will orient the arrows at 30, 60, and 90 + degrees respectively, regardless of the *U* and *V* components. + + Note: inverting a data axis will correspondingly invert the + arrows only with ``angles='xy'``. + +pivot : {'tail', 'mid', 'middle', 'tip'}, default: 'tail' + The part of the arrow that is anchored to the *X*, *Y* grid. The arrow + rotates about this point. + + 'mid' is a synonym for 'middle'. + +scale : float, optional + Scales the length of the arrow inversely. + + Number of data values represented by one unit of arrow length on the plot. + For example, if the data represents velocity in meters per second (m/s), the + scale parameter determines how many meters per second correspond to one unit of + arrow length relative to the width of the plot. + Smaller scale parameter makes the arrow longer. + + By default, an autoscaling algorithm is used to scale the arrow length to a + reasonable size, which is based on the average vector length and the number of + vectors. + + The arrow length unit is given by the *scale_units* parameter. + +scale_units : {'width', 'height', 'dots', 'inches', 'x', 'y', 'xy'}, default: 'width' + + The physical image unit, which is used for rendering the scaled arrow data *U*, *V*. + + The rendered arrow length is given by + + length in x direction = $\\frac{u}{\\mathrm{scale}} \\mathrm{scale_unit}$ + + length in y direction = $\\frac{v}{\\mathrm{scale}} \\mathrm{scale_unit}$ + + For example, ``(u, v) = (0.5, 0)`` with ``scale=10, scale_units="width"`` results + in a horizontal arrow with a length of *0.5 / 10 * "width"*, i.e. 0.05 times the + Axes width. + + Supported values are: + + - 'width' or 'height': The arrow length is scaled relative to the width or height + of the Axes. + For example, ``scale_units='width', scale=1.0``, will result in an arrow length + of width of the Axes. + + - 'dots': The arrow length of the arrows is in measured in display dots (pixels). + + - 'inches': Arrow lengths are scaled based on the DPI (dots per inch) of the figure. + This ensures that the arrows have a consistent physical size on the figure, + in inches, regardless of data values or plot scaling. + For example, ``(u, v) = (1, 0)`` with ``scale_units='inches', scale=2`` results + in a 0.5 inch-long arrow. + + - 'x' or 'y': The arrow length is scaled relative to the x or y axis units. + For example, ``(u, v) = (0, 1)`` with ``scale_units='x', scale=1`` results + in a vertical arrow with the length of 1 x-axis unit. + + - 'xy': Arrow length will be same as 'x' or 'y' units. + This is useful for creating vectors in the x-y plane where u and v have + the same units as x and y. To plot vectors in the x-y plane with u and v having + the same units as x and y, use ``angles='xy', scale_units='xy', scale=1``. + + Note: Setting *scale_units* without setting scale does not have any effect because + the scale units only differ by a constant factor and that is rescaled through + autoscaling. + +units : {'width', 'height', 'dots', 'inches', 'x', 'y', 'xy'}, default: 'width' + Affects the arrow size (except for the length). In particular, the shaft + *width* is measured in multiples of this unit. + + Supported values are: + + - 'width', 'height': The width or height of the Axes. + - 'dots', 'inches': Pixels or inches based on the figure dpi. + - 'x', 'y', 'xy': *X*, *Y* or :math:`\\sqrt{X^2 + Y^2}` in data units. + + The following table summarizes how these values affect the visible arrow + size under zooming and figure size changes: + + ================= ================= ================== + units zoom figure size change + ================= ================= ================== + 'x', 'y', 'xy' arrow size scales — + 'width', 'height' — arrow size scales + 'dots', 'inches' — — + ================= ================= ================== + +width : float, optional + Shaft width in arrow units. All head parameters are relative to *width*. + + The default depends on choice of *units* above, and number of vectors; + a typical starting value is about 0.005 times the width of the plot. + +headwidth : float, default: 3 + Head width as multiple of shaft *width*. See the notes below. + +headlength : float, default: 5 + Head length as multiple of shaft *width*. See the notes below. + +headaxislength : float, default: 4.5 + Head length at shaft intersection as multiple of shaft *width*. + See the notes below. + +minshaft : float, default: 1 + Length below which arrow scales, in units of head length. Do not + set this to less than 1, or small arrows will look terrible! + +minlength : float, default: 1 + Minimum length as a multiple of shaft width; if an arrow length + is less than this, plot a dot (hexagon) of this diameter instead. + +color : :mpltype:`color` or list :mpltype:`color`, optional + Explicit color(s) for the arrows. If *C* has been set, *color* has no + effect. + + This is a synonym for the `.PolyCollection` *facecolor* parameter. + +Other Parameters +---------------- +data : indexable object, optional + If given, all parameters also accept a string ``s``, which is + interpreted as ``data[s]`` if ``s`` is a key in ``data``. + +**kwargs : `~matplotlib.collections.PolyCollection` properties, optional + All other keyword arguments are passed on to `.PolyCollection`: + + Properties: + agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image + alpha: array-like or float or None + animated: bool + antialiased or aa or antialiaseds: bool or list of bools + array: array-like or None + capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} + clim: (vmin: float, vmax: float) + clip_box: `~matplotlib.transforms.BboxBase` or None + clip_on: bool + clip_path: Patch or (Path, Transform) or None + cmap: `.Colormap` or str or None + color: :mpltype:`color` or list of RGBA tuples + edgecolor or ec or edgecolors: :mpltype:`color` or list of :mpltype:`color` or 'face' + facecolor or facecolors or fc: :mpltype:`color` or list of :mpltype:`color` + figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + gid: str + hatch: {'/', '\\\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'} + hatch_linewidth: unknown + in_layout: bool + joinstyle: `.JoinStyle` or {'miter', 'round', 'bevel'} + label: object + linestyle or dashes or linestyles or ls: str or tuple or list thereof + linewidth or linewidths or lw: float or list of floats + mouseover: bool + norm: `.Normalize` or str or None + offset_transform or transOffset: `.Transform` + offsets: (N, 2) or (2,) array-like + path_effects: list of `.AbstractPathEffect` + paths: list of array-like + picker: None or bool or float or callable + pickradius: float + rasterized: bool + sizes: `numpy.ndarray` or None + sketch_params: (scale: float, length: float, randomness: float) + snap: bool or None + transform: `~matplotlib.transforms.Transform` + url: str + urls: list of str or None + verts: list of array-like + verts_and_codes: unknown + visible: bool + zorder: float + +Returns +------- +`~matplotlib.quiver.Quiver` + +See Also -------- -PlotAxes.barbs -PlotAxes.quiver -PlotAxes.stream -PlotAxes.streamplot -matplotlib.axes.Axes.quiver""" +.Axes.quiverkey : Add a key to a quiver plot. + +Notes +----- + +**Arrow shape** + +The arrow is drawn as a polygon using the nodes as shown below. The values +*headwidth*, *headlength*, and *headaxislength* are in units of *width*. + +.. image:: /_static/quiver_sizes.svg + :width: 500px + +The defaults give a slightly swept-back arrow. Here are some guidelines how to +get other head shapes: + +- To make the head a triangle, make *headaxislength* the same as *headlength*. +- To make the arrow more pointed, reduce *headwidth* or increase *headlength* + and *headaxislength*. +- To make the head smaller relative to the shaft, scale down all the head + parameters proportionally. +- To remove the head completely, set all *head* parameters to 0. +- To get a diamond-shaped head, make *headaxislength* larger than *headlength*. +- Warning: For *headaxislength* < (*headlength* / *headwidth*), the "headaxis" + nodes (i.e. the ones connecting the head with the shaft) will protrude out + of the head in forward direction so that the arrow head looks broken.""" ... def stream(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -8556,7 +12383,80 @@ PlotAxes.barbs PlotAxes.quiver PlotAxes.stream PlotAxes.streamplot -matplotlib.axes.Axes.streamplot""" +matplotlib.axes.Axes.streamplot + +Matplotlib documentation + + +Draw streamlines of a vector flow. + +Parameters +---------- +x, y : 1D/2D arrays + Evenly spaced strictly increasing arrays to make a grid. If 2D, all + rows of *x* must be equal and all columns of *y* must be equal; i.e., + they must be as if generated by ``np.meshgrid(x_1d, y_1d)``. +u, v : 2D arrays + *x* and *y*-velocities. The number of rows and columns must match + the length of *y* and *x*, respectively. +density : float or (float, float) + Controls the closeness of streamlines. When ``density = 1``, the domain + is divided into a 30x30 grid. *density* linearly scales this grid. + Each cell in the grid can have, at most, one traversing streamline. + For different densities in each direction, use a tuple + (density_x, density_y). +linewidth : float or 2D array + The width of the streamlines. With a 2D array the line width can be + varied across the grid. The array must have the same shape as *u* + and *v*. +color : :mpltype:`color` or 2D array + The streamline color. If given an array, its values are converted to + colors using *cmap* and *norm*. The array must have the same shape + as *u* and *v*. +cmap, norm + Data normalization and colormapping parameters for *color*; only used + if *color* is an array of floats. See `~.Axes.imshow` for a detailed + description. +arrowsize : float + Scaling factor for the arrow size. +arrowstyle : str + Arrow style specification. + See `~matplotlib.patches.FancyArrowPatch`. +minlength : float + Minimum length of streamline in axes coordinates. +start_points : (N, 2) array + Coordinates of starting points for the streamlines in data coordinates + (the same coordinates as the *x* and *y* arrays). +zorder : float + The zorder of the streamlines and arrows. + Artists with lower zorder values are drawn first. +maxlength : float + Maximum length of streamline in axes coordinates. +integration_direction : {'forward', 'backward', 'both'}, default: 'both' + Integrate the streamline in forward, backward or both directions. +data : indexable object, optional + If given, the following parameters also accept a string ``s``, which is + interpreted as ``data[s]`` if ``s`` is a key in ``data``: + + *x*, *y*, *u*, *v*, *start_points* +broken_streamlines : boolean, default: True + If False, forces streamlines to continue until they + leave the plot domain. If True, they may be terminated if they + come too close to another streamline. + +Returns +------- +StreamplotSet + Container object with attributes + + - ``lines``: `.LineCollection` of streamlines + + - ``arrows``: `.PatchCollection` containing `.FancyArrowPatch` + objects representing the arrows half-way along streamlines. + + This container will probably change in the future to allow changes + to the colormap, alpha, etc. for both lines and arrows, but these + changes should be backward compatible.""" ... def tricontour(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -8763,7 +12663,184 @@ PlotAxes.contour PlotAxes.contourf PlotAxes.tricontour PlotAxes.tricontourf -matplotlib.axes.Axes.tricontour""" +matplotlib.axes.Axes.tricontour + +Matplotlib documentation + + +Draw contour lines on an unstructured triangular grid. + +Call signatures:: + + tricontour(triangulation, z, [levels], ...) + tricontour(x, y, z, [levels], *, [triangles=triangles], [mask=mask], ...) + +The triangular grid can be specified either by passing a `.Triangulation` +object as the first parameter, or by passing the points *x*, *y* and +optionally the *triangles* and a *mask*. See `.Triangulation` for an +explanation of these parameters. If neither of *triangulation* or +*triangles* are given, the triangulation is calculated on the fly. + +It is possible to pass *triangles* positionally, i.e. +``tricontour(x, y, triangles, z, ...)``. However, this is discouraged. For more +clarity, pass *triangles* via keyword argument. + +Parameters +---------- +triangulation : `.Triangulation`, optional + An already created triangular grid. + +x, y, triangles, mask + Parameters defining the triangular grid. See `.Triangulation`. + This is mutually exclusive with specifying *triangulation*. + +z : array-like + The height values over which the contour is drawn. Color-mapping is + controlled by *cmap*, *norm*, *vmin*, and *vmax*. + + .. note:: + All values in *z* must be finite. Hence, nan and inf values must + either be removed or `~.Triangulation.set_mask` be used. + +levels : int or array-like, optional + Determines the number and positions of the contour lines / regions. + + If an int *n*, use `~matplotlib.ticker.MaxNLocator`, which tries to + automatically choose no more than *n+1* "nice" contour levels between + between minimum and maximum numeric values of *Z*. + + If array-like, draw contour lines at the specified levels. The values must + be in increasing order. + +Returns +------- +`~matplotlib.tri.TriContourSet` + +Other Parameters +---------------- +colors : :mpltype:`color` or list of :mpltype:`color`, optional + The colors of the levels, i.e., the contour lines. + + The sequence is cycled for the levels in ascending order. If the sequence + is shorter than the number of levels, it is repeated. + + As a shortcut, single color strings may be used in place of one-element + lists, i.e. ``'red'`` instead of ``['red']`` to color all levels with the + same color. This shortcut does only work for color strings, not for other + ways of specifying colors. + + By default (value *None*), the colormap specified by *cmap* will be used. + +alpha : float, default: 1 + The alpha blending value, between 0 (transparent) and 1 (opaque). + +cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap` + The Colormap instance or registered colormap name used to map scalar data + to colors. + + This parameter is ignored if *colors* is set. + +norm : str or `~matplotlib.colors.Normalize`, optional + The normalization method used to scale scalar data to the [0, 1] range + before mapping to colors using *cmap*. By default, a linear scaling is + used, mapping the lowest value to 0 and the highest to 1. + + If given, this can be one of the following: + + - An instance of `.Normalize` or one of its subclasses + (see :ref:`colormapnorms`). + - A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For a + list of available scales, call `matplotlib.scale.get_scale_names()`. + In that case, a suitable `.Normalize` subclass is dynamically generated + and instantiated. + + This parameter is ignored if *colors* is set. + +vmin, vmax : float, optional + When using scalar data and no explicit *norm*, *vmin* and *vmax* define + the data range that the colormap covers. By default, the colormap covers + the complete value range of the supplied data. It is an error to use + *vmin*/*vmax* when a *norm* instance is given (but using a `str` *norm* + name together with *vmin*/*vmax* is acceptable). + + If *vmin* or *vmax* are not given, the default color scaling is based on + *levels*. + + This parameter is ignored if *colors* is set. + +origin : {*None*, 'upper', 'lower', 'image'}, default: None + Determines the orientation and exact position of *z* by specifying the + position of ``z[0, 0]``. This is only relevant, if *X*, *Y* are not given. + + - *None*: ``z[0, 0]`` is at X=0, Y=0 in the lower left corner. + - 'lower': ``z[0, 0]`` is at X=0.5, Y=0.5 in the lower left corner. + - 'upper': ``z[0, 0]`` is at X=N+0.5, Y=0.5 in the upper left corner. + - 'image': Use the value from :rc:`image.origin`. + +extent : (x0, x1, y0, y1), optional + If *origin* is not *None*, then *extent* is interpreted as in `.imshow`: it + gives the outer pixel boundaries. In this case, the position of z[0, 0] is + the center of the pixel, not a corner. If *origin* is *None*, then + (*x0*, *y0*) is the position of z[0, 0], and (*x1*, *y1*) is the position + of z[-1, -1]. + + This argument is ignored if *X* and *Y* are specified in the call to + contour. + +locator : ticker.Locator subclass, optional + The locator is used to determine the contour levels if they are not given + explicitly via *levels*. + Defaults to `~.ticker.MaxNLocator`. + +extend : {'neither', 'both', 'min', 'max'}, default: 'neither' + Determines the ``tricontour``-coloring of values that are outside the + *levels* range. + + If 'neither', values outside the *levels* range are not colored. If 'min', + 'max' or 'both', color the values below, above or below and above the + *levels* range. + + Values below ``min(levels)`` and above ``max(levels)`` are mapped to the + under/over values of the `.Colormap`. Note that most colormaps do not have + dedicated colors for these by default, so that the over and under values + are the edge values of the colormap. You may want to set these values + explicitly using `.Colormap.set_under` and `.Colormap.set_over`. + + .. note:: + + An existing `.TriContourSet` does not get notified if properties of its + colormap are changed. Therefore, an explicit call to + `.ContourSet.changed()` is needed after modifying the colormap. The + explicit call can be left out, if a colorbar is assigned to the + `.TriContourSet` because it internally calls `.ContourSet.changed()`. + +xunits, yunits : registered units, optional + Override axis units by specifying an instance of a + :class:`matplotlib.units.ConversionInterface`. + +antialiased : bool, optional + Enable antialiasing, overriding the defaults. For + filled contours, the default is *True*. For line contours, + it is taken from :rc:`lines.antialiased`. + +linewidths : float or array-like, default: :rc:`contour.linewidth` + The line width of the contour lines. + + If a number, all levels will be plotted with this linewidth. + + If a sequence, the levels in ascending order will be plotted with + the linewidths in the order specified. + + If None, this falls back to :rc:`lines.linewidth`. + +linestyles : {*None*, 'solid', 'dashed', 'dashdot', 'dotted'}, optional + If *linestyles* is *None*, the default is 'solid' unless the lines are + monochrome. In that case, negative contours will take their linestyle + from :rc:`contour.negative_linestyle` setting. + + *linestyles* can also be an iterable of the above strings specifying a + set of linestyles to be used. If this iterable is shorter than the + number of contour levels it will be repeated as necessary.""" ... def tricontourf(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -8978,7 +13055,179 @@ PlotAxes.contour PlotAxes.contourf PlotAxes.tricontour PlotAxes.tricontourf -matplotlib.axes.Axes.tricontourf""" +matplotlib.axes.Axes.tricontourf + +Matplotlib documentation + + +Draw contour regions on an unstructured triangular grid. + +Call signatures:: + + tricontourf(triangulation, z, [levels], ...) + tricontourf(x, y, z, [levels], *, [triangles=triangles], [mask=mask], ...) + +The triangular grid can be specified either by passing a `.Triangulation` +object as the first parameter, or by passing the points *x*, *y* and +optionally the *triangles* and a *mask*. See `.Triangulation` for an +explanation of these parameters. If neither of *triangulation* or +*triangles* are given, the triangulation is calculated on the fly. + +It is possible to pass *triangles* positionally, i.e. +``tricontourf(x, y, triangles, z, ...)``. However, this is discouraged. For more +clarity, pass *triangles* via keyword argument. + +Parameters +---------- +triangulation : `.Triangulation`, optional + An already created triangular grid. + +x, y, triangles, mask + Parameters defining the triangular grid. See `.Triangulation`. + This is mutually exclusive with specifying *triangulation*. + +z : array-like + The height values over which the contour is drawn. Color-mapping is + controlled by *cmap*, *norm*, *vmin*, and *vmax*. + + .. note:: + All values in *z* must be finite. Hence, nan and inf values must + either be removed or `~.Triangulation.set_mask` be used. + +levels : int or array-like, optional + Determines the number and positions of the contour lines / regions. + + If an int *n*, use `~matplotlib.ticker.MaxNLocator`, which tries to + automatically choose no more than *n+1* "nice" contour levels between + between minimum and maximum numeric values of *Z*. + + If array-like, draw contour lines at the specified levels. The values must + be in increasing order. + +Returns +------- +`~matplotlib.tri.TriContourSet` + +Other Parameters +---------------- +colors : :mpltype:`color` or list of :mpltype:`color`, optional + The colors of the levels, i.e., the contour regions. + + The sequence is cycled for the levels in ascending order. If the sequence + is shorter than the number of levels, it is repeated. + + As a shortcut, single color strings may be used in place of one-element + lists, i.e. ``'red'`` instead of ``['red']`` to color all levels with the + same color. This shortcut does only work for color strings, not for other + ways of specifying colors. + + By default (value *None*), the colormap specified by *cmap* will be used. + +alpha : float, default: 1 + The alpha blending value, between 0 (transparent) and 1 (opaque). + +cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap` + The Colormap instance or registered colormap name used to map scalar data + to colors. + + This parameter is ignored if *colors* is set. + +norm : str or `~matplotlib.colors.Normalize`, optional + The normalization method used to scale scalar data to the [0, 1] range + before mapping to colors using *cmap*. By default, a linear scaling is + used, mapping the lowest value to 0 and the highest to 1. + + If given, this can be one of the following: + + - An instance of `.Normalize` or one of its subclasses + (see :ref:`colormapnorms`). + - A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For a + list of available scales, call `matplotlib.scale.get_scale_names()`. + In that case, a suitable `.Normalize` subclass is dynamically generated + and instantiated. + + This parameter is ignored if *colors* is set. + +vmin, vmax : float, optional + When using scalar data and no explicit *norm*, *vmin* and *vmax* define + the data range that the colormap covers. By default, the colormap covers + the complete value range of the supplied data. It is an error to use + *vmin*/*vmax* when a *norm* instance is given (but using a `str` *norm* + name together with *vmin*/*vmax* is acceptable). + + If *vmin* or *vmax* are not given, the default color scaling is based on + *levels*. + + This parameter is ignored if *colors* is set. + +origin : {*None*, 'upper', 'lower', 'image'}, default: None + Determines the orientation and exact position of *z* by specifying the + position of ``z[0, 0]``. This is only relevant, if *X*, *Y* are not given. + + - *None*: ``z[0, 0]`` is at X=0, Y=0 in the lower left corner. + - 'lower': ``z[0, 0]`` is at X=0.5, Y=0.5 in the lower left corner. + - 'upper': ``z[0, 0]`` is at X=N+0.5, Y=0.5 in the upper left corner. + - 'image': Use the value from :rc:`image.origin`. + +extent : (x0, x1, y0, y1), optional + If *origin* is not *None*, then *extent* is interpreted as in `.imshow`: it + gives the outer pixel boundaries. In this case, the position of z[0, 0] is + the center of the pixel, not a corner. If *origin* is *None*, then + (*x0*, *y0*) is the position of z[0, 0], and (*x1*, *y1*) is the position + of z[-1, -1]. + + This argument is ignored if *X* and *Y* are specified in the call to + contour. + +locator : ticker.Locator subclass, optional + The locator is used to determine the contour levels if they are not given + explicitly via *levels*. + Defaults to `~.ticker.MaxNLocator`. + +extend : {'neither', 'both', 'min', 'max'}, default: 'neither' + Determines the ``tricontourf``-coloring of values that are outside the + *levels* range. + + If 'neither', values outside the *levels* range are not colored. If 'min', + 'max' or 'both', color the values below, above or below and above the + *levels* range. + + Values below ``min(levels)`` and above ``max(levels)`` are mapped to the + under/over values of the `.Colormap`. Note that most colormaps do not have + dedicated colors for these by default, so that the over and under values + are the edge values of the colormap. You may want to set these values + explicitly using `.Colormap.set_under` and `.Colormap.set_over`. + + .. note:: + + An existing `.TriContourSet` does not get notified if properties of its + colormap are changed. Therefore, an explicit call to + `.ContourSet.changed()` is needed after modifying the colormap. The + explicit call can be left out, if a colorbar is assigned to the + `.TriContourSet` because it internally calls `.ContourSet.changed()`. + +xunits, yunits : registered units, optional + Override axis units by specifying an instance of a + :class:`matplotlib.units.ConversionInterface`. + +antialiased : bool, optional + Enable antialiasing, overriding the defaults. For + filled contours, the default is *True*. For line contours, + it is taken from :rc:`lines.antialiased`. + +hatches : list[str], optional + A list of crosshatch patterns to use on the filled areas. + If None, no hatching will be added to the contour. + +Notes +----- +`.tricontourf` fills intervals that are closed at the top; that is, for +boundaries *z1* and *z2*, the filled region is:: + + z1 < Z <= z2 + +except for the lowest interval, which is closed on both sides (i.e. it +includes the lowest value).""" ... def tripcolor(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -9192,7 +13441,136 @@ PlotAxes.pcolormesh PlotAxes.pcolorfast PlotAxes.heatmap PlotAxes.tripcolor -matplotlib.axes.Axes.tripcolor""" +matplotlib.axes.Axes.tripcolor + +Matplotlib documentation + + +Create a pseudocolor plot of an unstructured triangular grid. + +Call signatures:: + + tripcolor(triangulation, c, *, ...) + tripcolor(x, y, c, *, [triangles=triangles], [mask=mask], ...) + +The triangular grid can be specified either by passing a `.Triangulation` +object as the first parameter, or by passing the points *x*, *y* and +optionally the *triangles* and a *mask*. See `.Triangulation` for an +explanation of these parameters. + +It is possible to pass the triangles positionally, i.e. +``tripcolor(x, y, triangles, c, ...)``. However, this is discouraged. +For more clarity, pass *triangles* via keyword argument. + +If neither of *triangulation* or *triangles* are given, the triangulation +is calculated on the fly. In this case, it does not make sense to provide +colors at the triangle faces via *c* or *facecolors* because there are +multiple possible triangulations for a group of points and you don't know +which triangles will be constructed. + +Parameters +---------- +triangulation : `.Triangulation` + An already created triangular grid. +x, y, triangles, mask + Parameters defining the triangular grid. See `.Triangulation`. + This is mutually exclusive with specifying *triangulation*. +c : array-like + The color values, either for the points or for the triangles. Which one + is automatically inferred from the length of *c*, i.e. does it match + the number of points or the number of triangles. If there are the same + number of points and triangles in the triangulation it is assumed that + color values are defined at points; to force the use of color values at + triangles use the keyword argument ``facecolors=c`` instead of just + ``c``. + This parameter is position-only. +facecolors : array-like, optional + Can be used alternatively to *c* to specify colors at the triangle + faces. This parameter takes precedence over *c*. +shading : {'flat', 'gouraud'}, default: 'flat' + If 'flat' and the color values *c* are defined at points, the color + values used for each triangle are from the mean c of the triangle's + three points. If *shading* is 'gouraud' then color values must be + defined at points. +cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap` + The Colormap instance or registered colormap name used to map scalar data + to colors. + +norm : str or `~matplotlib.colors.Normalize`, optional + The normalization method used to scale scalar data to the [0, 1] range + before mapping to colors using *cmap*. By default, a linear scaling is + used, mapping the lowest value to 0 and the highest to 1. + + If given, this can be one of the following: + + - An instance of `.Normalize` or one of its subclasses + (see :ref:`colormapnorms`). + - A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For a + list of available scales, call `matplotlib.scale.get_scale_names()`. + In that case, a suitable `.Normalize` subclass is dynamically generated + and instantiated. + +vmin, vmax : float, optional + When using scalar data and no explicit *norm*, *vmin* and *vmax* define + the data range that the colormap covers. By default, the colormap covers + the complete value range of the supplied data. It is an error to use + *vmin*/*vmax* when a *norm* instance is given (but using a `str` *norm* + name together with *vmin*/*vmax* is acceptable). + +colorizer : `~matplotlib.colorizer.Colorizer` or None, default: None + The Colorizer object used to map color to data. If None, a Colorizer + object is created from a *norm* and *cmap*. + +Returns +------- +`~matplotlib.collections.PolyCollection` or `~matplotlib.collections.TriMesh` + The result depends on *shading*: For ``shading='flat'`` the result is a + `.PolyCollection`, for ``shading='gouraud'`` the result is a `.TriMesh`. + +Other Parameters +---------------- +**kwargs : `~matplotlib.collections.Collection` properties + + Properties: + agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image + alpha: array-like or float or None + animated: bool + antialiased or aa or antialiaseds: bool or list of bools + array: array-like or None + capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} + clim: (vmin: float, vmax: float) + clip_box: `~matplotlib.transforms.BboxBase` or None + clip_on: bool + clip_path: Patch or (Path, Transform) or None + cmap: `.Colormap` or str or None + color: :mpltype:`color` or list of RGBA tuples + edgecolor or ec or edgecolors: :mpltype:`color` or list of :mpltype:`color` or 'face' + facecolor or facecolors or fc: :mpltype:`color` or list of :mpltype:`color` + figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + gid: str + hatch: {'/', '\\\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'} + hatch_linewidth: unknown + in_layout: bool + joinstyle: `.JoinStyle` or {'miter', 'round', 'bevel'} + label: object + linestyle or dashes or linestyles or ls: str or tuple or list thereof + linewidth or linewidths or lw: float or list of floats + mouseover: bool + norm: `.Normalize` or str or None + offset_transform or transOffset: `.Transform` + offsets: (N, 2) or (2,) array-like + path_effects: list of `.AbstractPathEffect` + paths: unknown + picker: None or bool or float or callable + pickradius: float + rasterized: bool + sketch_params: (scale: float, length: float, randomness: float) + snap: bool or None + transform: `~matplotlib.transforms.Transform` + url: str + urls: list of str or None + visible: bool + zorder: float""" ... def imshow(self, z: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -9333,7 +13711,242 @@ legend_kw : dict-like, optional See also -------- ultraplot.axes.PlotAxes -matplotlib.axes.Axes.imshow""" +matplotlib.axes.Axes.imshow + +Matplotlib documentation + + +Display data as an image, i.e., on a 2D regular raster. + +The input may either be actual RGB(A) data, or 2D scalar data, which +will be rendered as a pseudocolor image. For displaying a grayscale +image, set up the colormapping using the parameters +``cmap='gray', vmin=0, vmax=255``. + +The number of pixels used to render an image is set by the Axes size +and the figure *dpi*. This can lead to aliasing artifacts when +the image is resampled, because the displayed image size will usually +not match the size of *X* (see +:doc:`/gallery/images_contours_and_fields/image_antialiasing`). +The resampling can be controlled via the *interpolation* parameter +and/or :rc:`image.interpolation`. + +Parameters +---------- +X : array-like or PIL image + The image data. Supported array shapes are: + + - (M, N): an image with scalar data. The values are mapped to + colors using normalization and a colormap. See parameters *norm*, + *cmap*, *vmin*, *vmax*. + - (M, N, 3): an image with RGB values (0-1 float or 0-255 int). + - (M, N, 4): an image with RGBA values (0-1 float or 0-255 int), + i.e. including transparency. + + The first two dimensions (M, N) define the rows and columns of + the image. + + Out-of-range RGB(A) values are clipped. + +cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap` + The Colormap instance or registered colormap name used to map scalar data + to colors. + + This parameter is ignored if *X* is RGB(A). + +norm : str or `~matplotlib.colors.Normalize`, optional + The normalization method used to scale scalar data to the [0, 1] range + before mapping to colors using *cmap*. By default, a linear scaling is + used, mapping the lowest value to 0 and the highest to 1. + + If given, this can be one of the following: + + - An instance of `.Normalize` or one of its subclasses + (see :ref:`colormapnorms`). + - A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For a + list of available scales, call `matplotlib.scale.get_scale_names()`. + In that case, a suitable `.Normalize` subclass is dynamically generated + and instantiated. + + This parameter is ignored if *X* is RGB(A). + +vmin, vmax : float, optional + When using scalar data and no explicit *norm*, *vmin* and *vmax* define + the data range that the colormap covers. By default, the colormap covers + the complete value range of the supplied data. It is an error to use + *vmin*/*vmax* when a *norm* instance is given (but using a `str` *norm* + name together with *vmin*/*vmax* is acceptable). + + This parameter is ignored if *X* is RGB(A). + +colorizer : `~matplotlib.colorizer.Colorizer` or None, default: None + The Colorizer object used to map color to data. If None, a Colorizer + object is created from a *norm* and *cmap*. + + This parameter is ignored if *X* is RGB(A). + +aspect : {'equal', 'auto'} or float or None, default: None + The aspect ratio of the Axes. This parameter is particularly + relevant for images since it determines whether data pixels are + square. + + This parameter is a shortcut for explicitly calling + `.Axes.set_aspect`. See there for further details. + + - 'equal': Ensures an aspect ratio of 1. Pixels will be square + (unless pixel sizes are explicitly made non-square in data + coordinates using *extent*). + - 'auto': The Axes is kept fixed and the aspect is adjusted so + that the data fit in the Axes. In general, this will result in + non-square pixels. + + Normally, None (the default) means to use :rc:`image.aspect`. However, if + the image uses a transform that does not contain the axes data transform, + then None means to not modify the axes aspect at all (in that case, directly + call `.Axes.set_aspect` if desired). + +interpolation : str, default: :rc:`image.interpolation` + The interpolation method used. + + Supported values are 'none', 'auto', 'nearest', 'bilinear', + 'bicubic', 'spline16', 'spline36', 'hanning', 'hamming', 'hermite', + 'kaiser', 'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell', + 'sinc', 'lanczos', 'blackman'. + + The data *X* is resampled to the pixel size of the image on the + figure canvas, using the interpolation method to either up- or + downsample the data. + + If *interpolation* is 'none', then for the ps, pdf, and svg + backends no down- or upsampling occurs, and the image data is + passed to the backend as a native image. Note that different ps, + pdf, and svg viewers may display these raw pixels differently. On + other backends, 'none' is the same as 'nearest'. + + If *interpolation* is the default 'auto', then 'nearest' + interpolation is used if the image is upsampled by more than a + factor of three (i.e. the number of display pixels is at least + three times the size of the data array). If the upsampling rate is + smaller than 3, or the image is downsampled, then 'hanning' + interpolation is used to act as an anti-aliasing filter, unless the + image happens to be upsampled by exactly a factor of two or one. + + See + :doc:`/gallery/images_contours_and_fields/interpolation_methods` + for an overview of the supported interpolation methods, and + :doc:`/gallery/images_contours_and_fields/image_antialiasing` for + a discussion of image antialiasing. + + Some interpolation methods require an additional radius parameter, + which can be set by *filterrad*. Additionally, the antigrain image + resize filter is controlled by the parameter *filternorm*. + +interpolation_stage : {'auto', 'data', 'rgba'}, default: 'auto' + Supported values: + + - 'data': Interpolation is carried out on the data provided by the user + This is useful if interpolating between pixels during upsampling. + - 'rgba': The interpolation is carried out in RGBA-space after the + color-mapping has been applied. This is useful if downsampling and + combining pixels visually. + - 'auto': Select a suitable interpolation stage automatically. This uses + 'rgba' when downsampling, or upsampling at a rate less than 3, and + 'data' when upsampling at a higher rate. + + See :doc:`/gallery/images_contours_and_fields/image_antialiasing` for + a discussion of image antialiasing. + +alpha : float or array-like, optional + The alpha blending value, between 0 (transparent) and 1 (opaque). + If *alpha* is an array, the alpha blending values are applied pixel + by pixel, and *alpha* must have the same shape as *X*. + +origin : {'upper', 'lower'}, default: :rc:`image.origin` + Place the [0, 0] index of the array in the upper left or lower + left corner of the Axes. The convention (the default) 'upper' is + typically used for matrices and images. + + Note that the vertical axis points upward for 'lower' + but downward for 'upper'. + + See the :ref:`imshow_extent` tutorial for + examples and a more detailed description. + +extent : floats (left, right, bottom, top), optional + The bounding box in data coordinates that the image will fill. + These values may be unitful and match the units of the Axes. + The image is stretched individually along x and y to fill the box. + + The default extent is determined by the following conditions. + Pixels have unit size in data coordinates. Their centers are on + integer coordinates, and their center coordinates range from 0 to + columns-1 horizontally and from 0 to rows-1 vertically. + + Note that the direction of the vertical axis and thus the default + values for top and bottom depend on *origin*: + + - For ``origin == 'upper'`` the default is + ``(-0.5, numcols-0.5, numrows-0.5, -0.5)``. + - For ``origin == 'lower'`` the default is + ``(-0.5, numcols-0.5, -0.5, numrows-0.5)``. + + See the :ref:`imshow_extent` tutorial for + examples and a more detailed description. + +filternorm : bool, default: True + A parameter for the antigrain image resize filter (see the + antigrain documentation). If *filternorm* is set, the filter + normalizes integer values and corrects the rounding errors. It + doesn't do anything with the source floating point values, it + corrects only integers according to the rule of 1.0 which means + that any sum of pixel weights must be equal to 1.0. So, the + filter function must produce a graph of the proper shape. + +filterrad : float > 0, default: 4.0 + The filter radius for filters that have a radius parameter, i.e. + when interpolation is one of: 'sinc', 'lanczos' or 'blackman'. + +resample : bool, default: :rc:`image.resample` + When *True*, use a full resampling method. When *False*, only + resample when the output image is larger than the input image. + +url : str, optional + Set the url of the created `.AxesImage`. See `.Artist.set_url`. + +Returns +------- +`~matplotlib.image.AxesImage` + +Other Parameters +---------------- +data : indexable object, optional + If given, all parameters also accept a string ``s``, which is + interpreted as ``data[s]`` if ``s`` is a key in ``data``. + +**kwargs : `~matplotlib.artist.Artist` properties + These parameters are passed on to the constructor of the + `.AxesImage` artist. + +See Also +-------- +matshow : Plot a matrix or an array as an image. + +Notes +----- +Unless *extent* is used, pixel centers will be located at integer +coordinates. In other words: the origin will coincide with the center +of pixel (0, 0). + +There are two common representations for RGB images with an alpha +channel: + +- Straight (unassociated) alpha: R, G, and B channels represent the + color of the pixel, disregarding its opacity. +- Premultiplied (associated) alpha: R, G, and B channels represent + the color of the pixel, adjusted for its opacity by multiplication. + +`~matplotlib.pyplot.imshow` expects RGB images adopting the straight +(unassociated) alpha representation.""" ... def matshow(self, z: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -9474,7 +14087,43 @@ legend_kw : dict-like, optional See also -------- ultraplot.axes.PlotAxes -matplotlib.axes.Axes.matshow""" +matplotlib.axes.Axes.matshow + +Matplotlib documentation + + +Plot the values of a 2D matrix or array as color-coded image. + +The matrix will be shown the way it would be printed, with the first +row at the top. Row and column numbering is zero-based. + +Parameters +---------- +Z : (M, N) array-like + The matrix to be displayed. + +Returns +------- +`~matplotlib.image.AxesImage` + +Other Parameters +---------------- +**kwargs : `~matplotlib.axes.Axes.imshow` arguments + +See Also +-------- +imshow : More general function to plot data on a 2D regular raster. + +Notes +----- +This is just a convenience function wrapping `.imshow` to set useful +defaults for displaying a matrix. In particular: + +- Set ``origin='upper'``. +- Set ``interpolation='nearest'``. +- Set ``aspect='equal'``. +- Ticks are placed to the left and above. +- Ticks are formatted to show integer indices.""" ... def spy(self, z: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -9615,7 +14264,128 @@ legend_kw : dict-like, optional See also -------- ultraplot.axes.PlotAxes -matplotlib.axes.Axes.spy""" +matplotlib.axes.Axes.spy + +Matplotlib documentation + + +Plot the sparsity pattern of a 2D array. + +This visualizes the non-zero values of the array. + +Two plotting styles are available: image and marker. Both +are available for full arrays, but only the marker style +works for `scipy.sparse.spmatrix` instances. + +**Image style** + +If *marker* and *markersize* are *None*, `~.Axes.imshow` is used. Any +extra remaining keyword arguments are passed to this method. + +**Marker style** + +If *Z* is a `scipy.sparse.spmatrix` or *marker* or *markersize* are +*None*, a `.Line2D` object will be returned with the value of marker +determining the marker type, and any remaining keyword arguments +passed to `~.Axes.plot`. + +Parameters +---------- +Z : (M, N) array-like + The array to be plotted. + +precision : float or 'present', default: 0 + If *precision* is 0, any non-zero value will be plotted. Otherwise, + values of :math:`|Z| > precision` will be plotted. + + For `scipy.sparse.spmatrix` instances, you can also + pass 'present'. In this case any value present in the array + will be plotted, even if it is identically zero. + +aspect : {'equal', 'auto', None} or float, default: 'equal' + The aspect ratio of the Axes. This parameter is particularly + relevant for images since it determines whether data pixels are + square. + + This parameter is a shortcut for explicitly calling + `.Axes.set_aspect`. See there for further details. + + - 'equal': Ensures an aspect ratio of 1. Pixels will be square. + - 'auto': The Axes is kept fixed and the aspect is adjusted so + that the data fit in the Axes. In general, this will result in + non-square pixels. + - *None*: Use :rc:`image.aspect`. + +origin : {'upper', 'lower'}, default: :rc:`image.origin` + Place the [0, 0] index of the array in the upper left or lower left + corner of the Axes. The convention 'upper' is typically used for + matrices and images. + +Returns +------- +`~matplotlib.image.AxesImage` or `.Line2D` + The return type depends on the plotting style (see above). + +Other Parameters +---------------- +**kwargs + The supported additional parameters depend on the plotting style. + + For the image style, you can pass the following additional + parameters of `~.Axes.imshow`: + + - *cmap* + - *alpha* + - *url* + - any `.Artist` properties (passed on to the `.AxesImage`) + + For the marker style, you can pass any `.Line2D` property except + for *linestyle*: + + Properties: + agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image + alpha: float or None + animated: bool + antialiased or aa: bool + clip_box: `~matplotlib.transforms.BboxBase` or None + clip_on: bool + clip_path: Patch or (Path, Transform) or None + color or c: :mpltype:`color` + dash_capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} + dash_joinstyle: `.JoinStyle` or {'miter', 'round', 'bevel'} + dashes: sequence of floats (on/off ink in points) or (None, None) + data: (2, N) array or two 1D arrays + drawstyle or ds: {'default', 'steps', 'steps-pre', 'steps-mid', 'steps-post'}, default: 'default' + figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + fillstyle: {'full', 'left', 'right', 'bottom', 'top', 'none'} + gapcolor: :mpltype:`color` or None + gid: str + in_layout: bool + label: object + linestyle or ls: {'-', '--', '-.', ':', '', (offset, on-off-seq), ...} + linewidth or lw: float + marker: marker style string, `~.path.Path` or `~.markers.MarkerStyle` + markeredgecolor or mec: :mpltype:`color` + markeredgewidth or mew: float + markerfacecolor or mfc: :mpltype:`color` + markerfacecoloralt or mfcalt: :mpltype:`color` + markersize or ms: float + markevery: None or int or (int, int) or slice or list[int] or float or (float, float) or list[bool] + mouseover: bool + path_effects: list of `.AbstractPathEffect` + picker: float or callable[[Artist, Event], tuple[bool, dict]] + pickradius: float + rasterized: bool + sketch_params: (scale: float, length: float, randomness: float) + snap: bool or None + solid_capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} + solid_joinstyle: `.JoinStyle` or {'miter', 'round', 'bevel'} + transform: unknown + url: str + visible: bool + xdata: 1D array + ydata: 1D array + zorder: float""" ... def _iter_arg_pairs(self, *args: Incomplete) -> Incomplete: diff --git a/ultraplot/axes/plot_types/circlize.pyi b/ultraplot/axes/plot_types/circlize.pyi index 847567905..400802122 100644 --- a/ultraplot/axes/plot_types/circlize.pyi +++ b/ultraplot/axes/plot_types/circlize.pyi @@ -11,8 +11,19 @@ from typing import Any, Callable, Mapping, Optional, Sequence, Union from matplotlib.projections.polar import PolarAxes as MplPolarAxes from ... import constructor from ...config import rc +_PYCIRCLIZE_RC_LEAKS = ('savefig.bbox', 'savefig.pad_inches', 'svg.fonttype') def _import_pycirclize() -> Incomplete: + """Import pycirclize without letting it restyle the session. + +``pycirclize.config`` runs ``mpl.rcParams.update(...)`` at import time, +setting ``savefig.bbox='tight'`` and ``savefig.pad_inches=0.5``. Since the +import is lazy, the first chord, radar, phylogeny or circos plot in a +session would otherwise silently change the size and padding of every +figure saved afterwards.""" + ... + +def _import_pycirclize_unguarded() -> Incomplete: ... def _unwrap_axes(ax: Incomplete, label: str) -> Incomplete: diff --git a/ultraplot/axes/plot_types/curved_quiver.pyi b/ultraplot/axes/plot_types/curved_quiver.pyi index a9da2ba94..9647eaf00 100644 --- a/ultraplot/axes/plot_types/curved_quiver.pyi +++ b/ultraplot/axes/plot_types/curved_quiver.pyi @@ -22,23 +22,23 @@ class _CurvedQuiverTrajectory: class _DomainMap(object): """Map representing different coordinate systems. - Coordinate definitions: - * axes-coordinates goes from 0 to 1 in the domain. - * data-coordinates are specified by the input x-y coordinates. - * grid-coordinates goes from 0 to N and 0 to M for an N x M grid, - where N and M match the shape of the input data. - * mask-coordinates goes from 0 to N and 0 to M for an N x M mask, - where N and M are user-specified to control the density of - streamlines. - - This class also has methods for adding trajectories to the - StreamMask. Before adding a trajectory, run `start_trajectory` to - keep track of regions crossed by a given trajectory. Later, if you - decide the trajectory is bad (e.g., if the trajectory is very - short) just call `undo_trajectory`. - """ +Coordinate definitions: +* axes-coordinates goes from 0 to 1 in the domain. +* data-coordinates are specified by the input x-y coordinates. +* grid-coordinates goes from 0 to N and 0 to M for an N x M grid, + where N and M match the shape of the input data. +* mask-coordinates goes from 0 to N and 0 to M for an N x M mask, + where N and M are user-specified to control the density of + streamlines. + +This class also has methods for adding trajectories to the +StreamMask. Before adding a trajectory, run `start_trajectory` to +keep track of regions crossed by a given trajectory. Later, if you +decide the trajectory is bad (e.g., if the trajectory is very +short) just call `undo_trajectory`.""" def __init__(self, grid: Incomplete, mask: Incomplete) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def grid2mask(self, xi: float, yi: float) -> tuple[int, int]: @@ -70,6 +70,7 @@ class _CurvedQuiverGrid(object): """Grid of data.""" def __init__(self, x: np.ndarray, y: np.ndarray) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... @property @@ -83,13 +84,13 @@ class _CurvedQuiverGrid(object): class _StreamMask(object): """Mask to keep track of discrete regions crossed by streamlines. - The resolution of this grid determines the approximate spacing - between trajectories. Streamlines are only allowed to pass through - zeroed cells: When a streamline enters a cell, that cell is set to - 1, and no new streamlines are allowed to enter. - """ +The resolution of this grid determines the approximate spacing +between trajectories. Streamlines are only allowed to pass through +zeroed cells: When a streamline enters a cell, that cell is set to +1, and no new streamlines are allowed to enter.""" def __init__(self, density: float | int) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def __getitem__(self, *args: Incomplete) -> Incomplete: @@ -116,6 +117,7 @@ class _CurvedQuiverTerminateTrajectory(Exception): class CurvedQuiverSolver: def __init__(self, x: np.ndarray, y: np.ndarray, density: float | tuple[float, float]) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def get_integrator(self, u: np.ndarray, v: np.ndarray, minlength: float, resolution: float, magnitude: np.ndarray) -> Callable[[float, float], _CurvedQuiverTrajectory | None]: diff --git a/ultraplot/axes/polar.pyi b/ultraplot/axes/polar.pyi index d1ea27b18..7a3d027c2 100644 --- a/ultraplot/axes/polar.pyi +++ b/ultraplot/axes/polar.pyi @@ -25,16 +25,14 @@ _POLAR_LABEL_SECTOR_FRAC = 0.8 _format_docstring = ... class PolarAxes(shared._SharedAxes, plot.PlotAxes, mpolar.PolarAxes): - """ - Axes subclass for plotting in polar coordinates. Adds the `~PolarAxes.format` - method and overrides several existing methods. - - Important - --------- - This axes subclass can be used by passing ``proj='polar'`` - to axes-creation commands like `~ultraplot.figure.Figure.add_axes`, - `~ultraplot.figure.Figure.add_subplot`, and `~ultraplot.figure.Figure.subplots`. - """ + """Axes subclass for plotting in polar coordinates. Adds the `~PolarAxes.format` +method and overrides several existing methods. + +Important +--------- +This axes subclass can be used by passing ``proj='polar'`` +to axes-creation commands like `~ultraplot.figure.Figure.add_axes`, +`~ultraplot.figure.Figure.add_subplot`, and `~ultraplot.figure.Figure.subplots`.""" _name = 'polar' def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: @@ -305,10 +303,60 @@ along the radial spoke (`rlabel`), both via CurvedText.""" @override def draw(self, renderer: Incomplete=None, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Draw the Artist (and its children) using the given renderer. + +This has no effect if the artist is not visible (`.Artist.get_visible` +returns False). + +Parameters +---------- +renderer : `~matplotlib.backend_bases.RendererBase` subclass. + +Notes +----- +This method is overridden in the Artist subclasses.""" ... @override def get_tightbbox(self, renderer: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Return the tight bounding box of the Axes, including axis and their +decorators (xlabel, title, etc). + +Artists that have ``artist.set_in_layout(False)`` are not included +in the bbox. + +Parameters +---------- +renderer : `.RendererBase` subclass + renderer that will be used to draw the figures (i.e. + ``fig.canvas.get_renderer()``) + +bbox_extra_artists : list of `.Artist` or ``None`` + List of artists to include in the tight bounding box. If + ``None`` (default), then all artist children of the Axes are + included in the tight bounding box. + +call_axes_locator : bool, default: True + If *call_axes_locator* is ``False``, it does not call the + ``_axes_locator`` attribute, which is necessary to get the correct + bounding box. ``call_axes_locator=False`` can be used if the + caller is only interested in the relative size of the tightbbox + compared to the Axes bbox. + +for_layout_only : default: False + The bounding box will *not* include the x-extent of the title and + the xlabel, or the y-extent of the ylabel. + +Returns +------- +`.BboxBase` + Bounding box in figure pixel coordinates. + +See Also +-------- +matplotlib.axes.Axes.get_window_extent +matplotlib.axis.Axis.get_tightbbox +matplotlib.spines.Spine.get_window_extent""" ... def format(self, *, r0: Incomplete=None, theta0: Incomplete=None, thetadir: Incomplete=None, thetamin: Incomplete=None, thetamax: Incomplete=None, thetalim: Incomplete=None, rmin: Incomplete=None, rmax: Incomplete=None, rlim: Incomplete=None, thetagrid: Incomplete=None, rgrid: Incomplete=None, thetagridminor: Incomplete=None, rgridminor: Incomplete=None, thetagridcolor: Incomplete=None, rgridcolor: Incomplete=None, rlabelpos: Incomplete=None, rscale: Incomplete=None, rborder: Incomplete=None, thetalocator: Incomplete=None, rlocator: Incomplete=None, thetalines: Incomplete=None, rlines: Incomplete=None, thetalocator_kw: Incomplete=None, rlocator_kw: Incomplete=None, thetaminorlocator: Incomplete=None, rminorlocator: Incomplete=None, thetaminorlines: Incomplete=None, rminorlines: Incomplete=None, thetaminorlocator_kw: Incomplete=None, rminorlocator_kw: Incomplete=None, thetaformatter: Incomplete=None, rformatter: Incomplete=None, thetalabels: Incomplete=None, rlabels: Incomplete=None, thetaformatter_kw: Incomplete=None, rformatter_kw: Incomplete=None, labelpad: Incomplete=None, labelsize: Incomplete=None, labelcolor: Incomplete=None, labelweight: Incomplete=None, thetalabel: Incomplete=None, rlabel: Incomplete=None, thetalabelloc: Incomplete=None, rlabelloc: Incomplete=None, thetalabel_kw: Incomplete=None, rlabel_kw: Incomplete=None, **kwargs: Incomplete) -> None: diff --git a/ultraplot/axes/shared.pyi b/ultraplot/axes/shared.pyi index 5851fa129..5f6532adc 100644 --- a/ultraplot/axes/shared.pyi +++ b/ultraplot/axes/shared.pyi @@ -16,10 +16,8 @@ except ImportError: from typing_extensions import override class _SharedAxes(object): - """ - Mix-in class with methods shared between `~ultraplot.axes.CartesianAxes` - and :class:`~ultraplot.axes.PolarAxes`. - """ + """Mix-in class with methods shared between `~ultraplot.axes.CartesianAxes` +and :class:`~ultraplot.axes.PolarAxes`.""" @staticmethod def _min_max_lim(key: Incomplete, min_: Incomplete=None, max_: Incomplete=None, lim: Incomplete=None) -> Incomplete: diff --git a/ultraplot/axes/taylor.pyi b/ultraplot/axes/taylor.pyi index f33c1a575..8ab9db582 100644 --- a/ultraplot/axes/taylor.pyi +++ b/ultraplot/axes/taylor.pyi @@ -16,16 +16,14 @@ __all__ = ['TaylorAxes'] _format_docstring = ... class TaylorAxes(PolarAxes): - """ - Axes subclass for Taylor diagrams. - - Important - --------- - This axes subclass can be used by passing ``proj='taylor'`` to - axes-creation commands like `~ultraplot.figure.Figure.add_axes`, - `~ultraplot.figure.Figure.add_subplot`, and - `~ultraplot.figure.Figure.subplots`. - """ + """Axes subclass for Taylor diagrams. + +Important +--------- +This axes subclass can be used by passing ``proj='taylor'`` to +axes-creation commands like `~ultraplot.figure.Figure.add_axes`, +`~ultraplot.figure.Figure.add_subplot`, and +`~ultraplot.figure.Figure.subplots`.""" _name = 'taylor' _name_aliases = () _default_corrs = np.array((1.0, 0.95, 0.9, 0.8, 0.6, 0.4, 0.2, 0.0)) diff --git a/ultraplot/axes/three.pyi b/ultraplot/axes/three.pyi index 8c6de8291..959df8679 100644 --- a/ultraplot/axes/three.pyi +++ b/ultraplot/axes/three.pyi @@ -11,20 +11,19 @@ except ImportError: Axes3D = object class ThreeAxes(shared._SharedAxes, base.Axes, Axes3D): - """ - Simple mix-in of `ultraplot.axes.Axes` with `~mpl_toolkits.mplot3d.axes3d.Axes3D`. + """Simple mix-in of `ultraplot.axes.Axes` with `~mpl_toolkits.mplot3d.axes3d.Axes3D`. - Important - --------- - Note that this subclass does *not* implement the :class:`~ultraplot.axes.PlotAxes` - plotting overrides. This axes subclass can be used by passing ``proj='3d'`` or - ``proj='three'`` to axes-creation commands like `~ultraplot.figure.Figure.add_axes`, - `~ultraplot.figure.Figure.add_subplot`, and `~ultraplot.figure.Figure.subplots`. - """ +Important +--------- +Note that this subclass does *not* implement the :class:`~ultraplot.axes.PlotAxes` +plotting overrides. This axes subclass can be used by passing ``proj='3d'`` or +``proj='three'`` to axes-creation commands like `~ultraplot.figure.Figure.add_axes`, +`~ultraplot.figure.Figure.add_subplot`, and `~ultraplot.figure.Figure.subplots`.""" _name = 'three' _name_aliases = ('3d',) def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def graph(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: diff --git a/ultraplot/colorbar.pyi b/ultraplot/colorbar.pyi index 06ad52294..0ddf6640b 100644 --- a/ultraplot/colorbar.pyi +++ b/ultraplot/colorbar.pyi @@ -32,11 +32,10 @@ class _TextKw: kw_ticklabels: ColorbarTickKw class UltraColorbar: - """ - Centralized colorbar builder for axes. - """ + """Centralized colorbar builder for axes.""" def __init__(self, axes: maxes.Axes) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def add(self, mappable: Any, values: Optional[Iterable[float]]=None, *, loc: Optional[str]=None, align: Optional[str]=None, space: Optional[Union[float, str]]=None, pad: Optional[Union[float, str]]=None, width: Optional[Union[float, str]]=None, length: Optional[Union[float, str]]=None, span: Optional[Union[int, Tuple[int, int]]]=None, row: Optional[int]=None, col: Optional[int]=None, rows: Optional[Union[int, Tuple[int, int]]]=None, cols: Optional[Union[int, Tuple[int, int]]]=None, shrink: Optional[Union[float, str]]=None, label: Optional[str]=None, title: Optional[str]=None, reverse: bool=False, rotation: Optional[float]=None, grid: Optional[bool]=None, edges: Optional[bool]=None, drawedges: Optional[bool]=None, extend: Optional[str]=None, extendsize: Optional[Union[float, str]]=None, extendfrac: Optional[float]=None, ticks: Optional[Iterable[float]]=None, locator: Optional[Any]=None, locator_kw: Optional[dict[str, Any]]=None, format: Optional[str]=None, formatter: Optional[Any]=None, ticklabels: Optional[Iterable[str]]=None, formatter_kw: Optional[dict[str, Any]]=None, minorticks: Optional[bool]=None, minorlocator: Optional[Any]=None, minorlocator_kw: Optional[dict[str, Any]]=None, tickminor: Optional[bool]=None, ticklen: Optional[Union[float, str]]=None, ticklenratio: Optional[float]=None, tickdir: Optional[str]=None, tickdirection: Optional[str]=None, tickwidth: Optional[Union[float, str]]=None, tickwidthratio: Optional[float]=None, ticklabelsize: Optional[float]=None, ticklabelweight: Optional[str]=None, ticklabelcolor: Optional[str]=None, labelloc: Optional[str]=None, labellocation: Optional[str]=None, labelsize: Optional[float]=None, labelweight: Optional[str]=None, labelcolor: Optional[str]=None, c: Optional[str]=None, color: Optional[str]=None, lw: Optional[Union[float, str]]=None, linewidth: Optional[Union[float, str]]=None, edgefix: Optional[bool]=None, rasterized: Optional[bool]=None, frame: Optional[bool]=None, frameon: Optional[bool]=None, outline: Union[bool, None]=None, labelrotation: Optional[Union[str, float]]=None, center_levels: Optional[bool]=None, **kwargs: Incomplete) -> mcolorbar.Colorbar: @@ -91,6 +90,10 @@ def _register_inset_colorbar_reflow(fig: mfigure.Figure) -> None: def _solve_inset_colorbar_bounds(*, axes: maxes.Axes, loc: str, orientation: str, length: float, width: float, xpad: float, ypad: float, ticklocation: str, labelloc: Optional[str], label: Optional[str], labelrotation: Optional[Union[str, float]], tick_fontsize: float, label_fontsize: float) -> Tuple[list[float], list[float]]: ... +def _anchor_inset_colorbar_bounds(bounds_inset: list[float], bounds_frame: list[float], loc: str, bbox_to_anchor: Incomplete) -> Tuple[list[float], list[float]]: + """Align an inset colorbar footprint to a legend-style anchor box.""" + ... + def _legacy_inset_colorbar_bounds(*, axes: maxes.Axes, loc: str, orientation: str, length: float, width: float, xpad: float, ypad: float, ticklocation: str, labelloc: Optional[str], label: Optional[str], labelrotation: Optional[Union[str, float]], tick_fontsize: float, label_fontsize: float) -> Tuple[list[float], list[float]]: ... diff --git a/ultraplot/colors.pyi b/ultraplot/colors.pyi index 0bd6157b7..02d05a2ce 100644 --- a/ultraplot/colors.pyi +++ b/ultraplot/colors.pyi @@ -170,9 +170,7 @@ margin : optional ... class _Colormap(object): - """ - Mixin class used to add some helper methods. - """ + """Mixin class used to add some helper methods.""" def _get_data(self, ext: Incomplete, alpha: Incomplete=True) -> Incomplete: """Return a string containing the colormap colors for saving. @@ -216,14 +214,14 @@ algongside more intuitive ``Colormap(data, name, N)`` input.""" ... class ContinuousColormap(mcolors.LinearSegmentedColormap, _Colormap): - """ - Replacement for `~matplotlib.colors.LinearSegmentedColormap`. - """ + """Replacement for `~matplotlib.colors.LinearSegmentedColormap`.""" def __str__(self) -> str: + """Return str(self).""" ... def __repr__(self) -> str: + """Return repr(self).""" ... def __init__(self, *args: Incomplete, gamma: Incomplete=1, alpha: Incomplete=None, cyclic: Incomplete=False, **kwargs: Incomplete) -> None: @@ -564,14 +562,14 @@ PerceptualColormap.from_list""" ... class DiscreteColormap(mcolors.ListedColormap, _Colormap): - """ - Replacement for `~matplotlib.colors.ListedColormap`. - """ + """Replacement for `~matplotlib.colors.ListedColormap`.""" def __str__(self) -> str: + """Return str(self).""" ... def __repr__(self) -> str: + """Return repr(self).""" ... @property @@ -581,6 +579,7 @@ class DiscreteColormap(mcolors.ListedColormap, _Colormap): @monochrome.setter def monochrome(self, value: Incomplete) -> None: + """Whether every color is identical, normalized to a Python boolean.""" ... def __init__(self, colors: Incomplete, name: Incomplete=None, N: Incomplete=None, alpha: Incomplete=None, **kwargs: Incomplete) -> None: @@ -769,10 +768,8 @@ ContinuousColormap.from_file""" ... class PerceptualColormap(ContinuousColormap): - """ - A `ContinuousColormap` with linear transitions across hue, saturation, - and luminance rather than red, blue, and green. - """ + """A `ContinuousColormap` with linear transitions across hue, saturation, +and luminance rather than red, blue, and green.""" def __init__(self, *args: Incomplete, space: Incomplete=None, clip: Incomplete=True, gamma: Incomplete=None, gamma1: Incomplete=None, gamma2: Incomplete=None, **kwargs: Incomplete) -> None: """Parameters @@ -1063,10 +1060,8 @@ def _sanitize_levels(levels: Incomplete, minsize: Incomplete=2) -> Incomplete: ... class DiscreteNorm(mcolors.BoundaryNorm): - """ - Meta-normalizer that discretizes the possible color values returned by - arbitrary continuous normalizers given a sequence of level boundaries. - """ + """Meta-normalizer that discretizes the possible color values returned by +arbitrary continuous normalizers given a sequence of level boundaries.""" def __init__(self, levels: Incomplete, norm: Incomplete=None, unique: Incomplete=None, step: Incomplete=None, clip: Incomplete=False, ticks: Incomplete=None, labels: Incomplete=None) -> None: """Parameters @@ -1146,10 +1141,8 @@ ValueError ... class SegmentedNorm(mcolors.Normalize): - """ - Normalizer that scales data linearly with respect to the - interpolated index in an arbitrary monotonic level sequence. - """ + """Normalizer that scales data linearly with respect to the +interpolated index in an arbitrary monotonic level sequence.""" def __init__(self, levels: Incomplete, vmin: Incomplete=None, vmax: Incomplete=None, clip: Incomplete=False) -> None: """Parameters @@ -1214,12 +1207,11 @@ value : numeric ... class DivergingNorm(mcolors.Normalize): - """ - Normalizer that ensures some central data value lies at the central - colormap color. The default central value is ``0``. - """ + """Normalizer that ensures some central data value lies at the central +colormap color. The default central value is ``0``.""" def __str__(self) -> str: + """Return str(self).""" ... def __init__(self, vcenter: Incomplete=0, vmin: Incomplete=None, vmax: Incomplete=None, fair: Incomplete=True, clip: Incomplete=None) -> None: @@ -1279,9 +1271,7 @@ cyclic colormaps based on names and re-apply default lookup table size.""" ... class _ColorCache(dict): - """ - Replacement for the native color cache. - """ + """Replacement for the native color cache.""" def __getitem__(self, key: Incomplete) -> Incomplete: """Get the standard color, colormap color, or color cycle color.""" @@ -1292,13 +1282,12 @@ class _ColorCache(dict): ... class ColorDatabase(MutableMapping, dict): - """ - Dictionary subclass used to replace the builtin matplotlib color database. - See `~ColorDatabase.__getitem__` for details. - """ + """Dictionary subclass used to replace the builtin matplotlib color database. +See `~ColorDatabase.__getitem__` for details.""" _colors_replace = (('grey', 'gray'), ('ochre', 'ocher'), ('kelley', 'kelly')) def __delitem__(self, key: Incomplete) -> None: + """Delete self[key].""" ... def __init__(self, mapping: Incomplete=None) -> None: @@ -1336,11 +1325,9 @@ cache. The color must be a string.""" ... class ColormapDatabase(mcm.ColormapRegistry): - """ - Dictionary subclass used to replace the matplotlib - colormap registry. See `~ColormapDatabase.__getitem__` and - `~ColormapDatabase.__setitem__` for details. - """ + """Dictionary subclass used to replace the matplotlib +colormap registry. See `~ColormapDatabase.__getitem__` and +`~ColormapDatabase.__setitem__` for details.""" _regex_grays = re.compile('\\A(grays)(_r|_s)*\\Z', flags=re.IGNORECASE) _regex_suffix = re.compile('(_r|_s)*\\Z', flags=re.IGNORECASE) @@ -1367,6 +1354,19 @@ kwargs : dict-like ... def get_cmap(self, cmap: Incomplete) -> Incomplete: + """Return a color map specified through *cmap*. + +Parameters +---------- +cmap : str or `~matplotlib.colors.Colormap` or None + + - if a `.Colormap`, return it + - if a string, look it up in ``mpl.colormaps`` + - if None, return the Colormap defined in :rc:`image.cmap` + +Returns +------- +Colormap""" ... def __getitem__(self, key: Incomplete) -> Incomplete: diff --git a/ultraplot/config.pyi b/ultraplot/config.pyi index 06be2c244..b6b2f2e35 100644 --- a/ultraplot/config.pyi +++ b/ultraplot/config.pyi @@ -263,30 +263,34 @@ ultraplot.demos.show_fonts""" ... class Configurator(MutableMapping, dict): - """ - A dictionary-like class for managing `matplotlib settings - `__ - stored in `rc_matplotlib` and :ref:`ultraplot settings ` - stored in `rc_ultraplot`. This class is instantiated as the `rc` object - on import. See the :ref:`user guide ` for details. - """ + """A dictionary-like class for managing `matplotlib settings +`__ +stored in `rc_matplotlib` and :ref:`ultraplot settings ` +stored in `rc_ultraplot`. This class is instantiated as the `rc` object +on import. See the :ref:`user guide ` for details.""" def __repr__(self) -> str: + """Return repr(self).""" ... def __str__(self) -> str: + """Return str(self).""" ... def __iter__(self) -> Incomplete: + """Implement iter(self).""" ... def __len__(self) -> int: + """Return len(self).""" ... def __delitem__(self, key: Incomplete) -> Incomplete: + """Delete self[key].""" ... def __delattr__(self, attr: Incomplete) -> Incomplete: + """Implement delattr(self, name).""" ... def __init__(self, local: Incomplete=True, user: Incomplete=True, default: Incomplete=True, **kwargs: Incomplete) -> None: @@ -301,31 +305,30 @@ default : bool, default: True ... def register_handler(self, name: str, func: Callable[[Any], Dict[str, Any]]) -> None: - """ Register a callback function to be executed when a setting is modified. - - This is an extension point for "special" settings that require complex - logic or have side-effects, such as updating other matplotlib settings. - It is used internally to decouple the configuration system from other - subsystems and avoid circular imports. - - Parameters - ---------- - name : str - The name of the setting (e.g., ``'cycle'``). - func : callable - The handler function to be executed. The function must accept a - single positional argument, which is the new `value` of the - setting, and must return a dictionary. The keys of the dictionary - should be valid ``matplotlib`` rc setting names, and the values - will be applied to the ``rc_matplotlib`` object. - - Example - ------- - >>> def _cycle_handler(value): - ... # ... logic to create a cycler object from the value ... - ... return {'axes.prop_cycle': new_cycler} - >>> rc.register_handler('cycle', _cycle_handler) - """ + """Register a callback function to be executed when a setting is modified. + +This is an extension point for "special" settings that require complex +logic or have side-effects, such as updating other matplotlib settings. +It is used internally to decouple the configuration system from other +subsystems and avoid circular imports. + +Parameters +---------- +name : str + The name of the setting (e.g., ``'cycle'``). +func : callable + The handler function to be executed. The function must accept a + single positional argument, which is the new `value` of the + setting, and must return a dictionary. The keys of the dictionary + should be valid ``matplotlib`` rc setting names, and the values + will be applied to the ``rc_matplotlib`` object. + +Example +------- +>>> def _cycle_handler(value): +... # ... logic to create a cycler object from the value ... +... return {'axes.prop_cycle': new_cycler} +>>> rc.register_handler('cycle', _cycle_handler)""" ... def __getitem__(self, key: Incomplete) -> Incomplete: diff --git a/ultraplot/constructor.pyi b/ultraplot/constructor.pyi index 95b071ea6..04334ce29 100644 --- a/ultraplot/constructor.pyi +++ b/ultraplot/constructor.pyi @@ -42,44 +42,52 @@ DEFAULT_CYCLE_LUMINANCE = 90 _RegistryValue = TypeVar('_RegistryValue') class _RefreshingRegistry(dict[str, _RegistryValue]): - """ - Dictionary-like registry that rebuilds itself before reads. + """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. - """ +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: + """Initialize self. See help(type(self)) for accurate signature.""" ... def _refresh(self) -> None: ... def __contains__(self, key: object) -> bool: + """True if the dictionary has the specified key, else False.""" ... def __getitem__(self, key: str) -> _RegistryValue: + """Return self[key].""" ... def __iter__(self) -> Iterator[str]: + """Implement iter(self).""" ... def __len__(self) -> int: + """Return len(self).""" ... def get(self, key: str, default: _RegistryValue | None=None) -> _RegistryValue | None: + """Return the value for key if key is in the dictionary, else default.""" ... def items(self) -> Incomplete: + """Return a set-like object providing a view on the dict's items.""" ... def keys(self) -> Incomplete: + """Return a set-like object providing a view on the dict's keys.""" ... def values(self) -> Incomplete: + """Return an object providing a view on the dict's values.""" ... def copy(self) -> dict[str, _RegistryValue]: + """Return a shallow copy of the dict.""" ... def _build_norm_registry() -> dict[str, type[mcolors.Normalize]]: @@ -283,79 +291,80 @@ ultraplot.utils.get_colors""" ... 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 `__, - the `marker reference `__, - and the `custom dashes reference `__. - 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 - """ + """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 `__, + the `marker reference `__, + and the `custom dashes reference `__. +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: Incomplete, N: Incomplete=None, samples: Incomplete=None, name: Incomplete=None, **kwargs: Incomplete) -> None: + """Semi-private init. + +Do not use this directly, use `cycler` function instead.""" ... def _parse_basic_properties(self, kwargs: Incomplete) -> Incomplete: @@ -387,6 +396,7 @@ class Cycle(cycler.Cycler): ... def __eq__(self, other: Incomplete) -> bool: + """Return self==value.""" ... def get_next(self) -> Incomplete: diff --git a/ultraplot/figure.pyi b/ultraplot/figure.pyi index f38fe9294..fcf55dde6 100644 --- a/ultraplot/figure.pyi +++ b/ultraplot/figure.pyi @@ -70,15 +70,14 @@ def _clear_border_cache(func: _F) -> _F: ... class Figure(mfigure.Figure): - """ - The `~matplotlib.figure.Figure` subclass used by ultraplot. - """ + """The `~matplotlib.figure.Figure` subclass used by ultraplot.""" _share_message = "Axis sharing level can be 0 or False (share nothing), 1 or 'labels' or 'labs' (share axis labels), 2 or 'limits' or 'lims' (share axis limits and axis labels), 3 or True (share axis limits, axis labels, and tick labels), 4 or 'all' (share axis labels and tick labels in the same gridspec rows and columns and share axis limits across all subplots), or 'auto' (start unshared and share only compatible axes)." _space_message = 'To set the left, right, bottom, top, wspace, or hspace gridspec values, pass them as keyword arguments to uplt.figure() or uplt.subplots(). Please note they are now specified in physical units, with strings interpreted by uplt.units() and floats interpreted as font size-widths.' _tight_message = "ultraplot uses its own tight layout algorithm that is activated by default. To disable it, set uplt.rc['subplots.tight'] to False or pass tight=False to uplt.subplots(). For details, see fig.auto_layout()." _warn_interactive = True def __repr__(self) -> str: + """Return repr(self).""" ... def __init__(self, *, refnum: Incomplete=None, refaspect: Incomplete=None, refwidth: Incomplete=None, refheight: Incomplete=None, figwidth: Incomplete=None, figheight: Incomplete=None, journal: Incomplete=None, sharex: Incomplete=None, sharey: Incomplete=None, share: Incomplete=None, spanx: Incomplete=None, spany: Incomplete=None, span: Incomplete=None, alignx: Incomplete=None, aligny: Incomplete=None, align: Incomplete=None, left: Incomplete=None, right: Incomplete=None, top: Incomplete=None, bottom: Incomplete=None, wspace: Incomplete=None, hspace: Incomplete=None, space: Incomplete=None, tight: Incomplete=None, outerpad: Incomplete=None, innerpad: Incomplete=None, panelpad: Incomplete=None, wpad: Incomplete=None, hpad: Incomplete=None, pad: Incomplete=None, wequal: Incomplete=None, hequal: Incomplete=None, equal: Incomplete=None, wgroup: Incomplete=None, hgroup: Incomplete=None, group: Incomplete=None, **kwargs: Incomplete) -> None: @@ -315,6 +314,18 @@ matplotlib.figure.Figure.clear""" @override def draw(self, renderer: Incomplete) -> Incomplete: + """Draw the Artist (and its children) using the given renderer. + +This has no effect if the artist is not visible (`.Artist.get_visible` +returns False). + +Parameters +---------- +renderer : `~matplotlib.backend_bases.RendererBase` subclass. + +Notes +----- +This method is overridden in the Artist subclasses.""" ... @override @@ -806,7 +817,144 @@ See also ultraplot.figure.Figure.subplot ultraplot.figure.Figure.add_subplot ultraplot.figure.Figure.subplots -ultraplot.figure.Figure.add_subplots""" +ultraplot.figure.Figure.add_subplots + +Matplotlib documentation + + +Add an `~.axes.Axes` to the figure. + +Call signatures:: + + add_axes(rect, projection=None, polar=False, **kwargs) + add_axes(ax) + +Parameters +---------- +rect : tuple (left, bottom, width, height) + The dimensions (left, bottom, width, height) of the new + `~.axes.Axes`. All quantities are in fractions of figure width and + height. + +projection : {None, 'aitoff', 'hammer', 'lambert', 'mollweide', 'polar', 'rectilinear', str}, optional + The projection type of the `~.axes.Axes`. *str* is the name of + a custom projection, see `~matplotlib.projections`. The default + None results in a 'rectilinear' projection. + +polar : bool, default: False + If True, equivalent to projection='polar'. + +axes_class : subclass type of `~.axes.Axes`, optional + The `.axes.Axes` subclass that is instantiated. This parameter + is incompatible with *projection* and *polar*. See + :ref:`axisartist_users-guide-index` for examples. + +sharex, sharey : `~matplotlib.axes.Axes`, optional + Share the x or y `~matplotlib.axis` with sharex and/or sharey. + The axis will have the same limits, ticks, and scale as the axis + of the shared Axes. + +label : str + A label for the returned Axes. + +Returns +------- +`~.axes.Axes`, or a subclass of `~.axes.Axes` + The returned Axes class depends on the projection used. It is + `~.axes.Axes` if rectilinear projection is used and + `.projections.polar.PolarAxes` if polar projection is used. + +Other Parameters +---------------- +**kwargs + This method also takes the keyword arguments for + the returned Axes class. The keyword arguments for the + rectilinear Axes class `~.axes.Axes` can be found in + the following table but there might also be other keyword + arguments if another projection is used, see the actual Axes + class. + + Properties: + adjustable: {'box', 'datalim'} + agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image + alpha: float or None + anchor: (float, float) or {'C', 'SW', 'S', 'SE', 'E', 'NE', ...} + animated: bool + aspect: {'auto', 'equal'} or float + autoscale_on: bool + autoscalex_on: unknown + autoscaley_on: unknown + axes_locator: Callable[[Axes, Renderer], Bbox] + axisbelow: bool or 'line' + box_aspect: float or None + clip_box: `~matplotlib.transforms.BboxBase` or None + clip_on: bool + clip_path: Patch or (Path, Transform) or None + facecolor or fc: :mpltype:`color` + figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + forward_navigation_events: bool or "auto" + frame_on: bool + gid: str + in_layout: bool + label: object + mouseover: bool + navigate: bool + navigate_mode: unknown + path_effects: list of `.AbstractPathEffect` + picker: None or bool or float or callable + position: [left, bottom, width, height] or `~matplotlib.transforms.Bbox` + prop_cycle: `~cycler.Cycler` + rasterization_zorder: float or None + rasterized: bool + sketch_params: (scale: float, length: float, randomness: float) + snap: bool or None + subplotspec: unknown + title: str + transform: `~matplotlib.transforms.Transform` + url: str + visible: bool + xbound: (lower: float, upper: float) + xlabel: str + xlim: (left: float, right: float) + xmargin: float greater than -0.5 + xscale: unknown + xticklabels: unknown + xticks: unknown + ybound: (lower: float, upper: float) + ylabel: str + ylim: (bottom: float, top: float) + ymargin: float greater than -0.5 + yscale: unknown + yticklabels: unknown + yticks: unknown + zorder: float + +Notes +----- +In rare circumstances, `.add_axes` may be called with a single +argument, an Axes instance already created in the present figure but +not in the figure's list of Axes. + +See Also +-------- +.Figure.add_subplot +.pyplot.subplot +.pyplot.axes +.Figure.subplots +.pyplot.subplots + +Examples +-------- +Some simple examples:: + + rect = l, b, w, h + fig = plt.figure() + fig.add_axes(rect) + fig.add_axes(rect, frameon=False, facecolor='g') + fig.add_axes(rect, polar=True) + ax = fig.add_axes(rect, projection='polar') + fig.delaxes(ax) + fig.add_axes(ax)""" ... def add_subplot(self, *args: Incomplete, **kwargs: Incomplete) -> paxes.Axes: @@ -875,7 +1023,160 @@ See also -------- ultraplot.figure.Figure.add_axes ultraplot.figure.Figure.subplots -ultraplot.figure.Figure.add_subplots""" +ultraplot.figure.Figure.add_subplots + +Matplotlib documentation + + +Add an `~.axes.Axes` to the figure as part of a subplot arrangement. + +Call signatures:: + + add_subplot(nrows, ncols, index, **kwargs) + add_subplot(pos, **kwargs) + add_subplot(ax) + add_subplot() + +Parameters +---------- +*args : int, (int, int, *index*), or `.SubplotSpec`, default: (1, 1, 1) + The position of the subplot described by one of + + - Three integers (*nrows*, *ncols*, *index*). The subplot will + take the *index* position on a grid with *nrows* rows and + *ncols* columns. *index* starts at 1 in the upper left corner + and increases to the right. *index* can also be a two-tuple + specifying the (*first*, *last*) indices (1-based, and including + *last*) of the subplot, e.g., ``fig.add_subplot(3, 1, (1, 2))`` + makes a subplot that spans the upper 2/3 of the figure. + - A 3-digit integer. The digits are interpreted as if given + separately as three single-digit integers, i.e. + ``fig.add_subplot(235)`` is the same as + ``fig.add_subplot(2, 3, 5)``. Note that this can only be used + if there are no more than 9 subplots. + - A `.SubplotSpec`. + + In rare circumstances, `.add_subplot` may be called with a single + argument, a subplot Axes instance already created in the + present figure but not in the figure's list of Axes. + +projection : {None, 'aitoff', 'hammer', 'lambert', 'mollweide', 'polar', 'rectilinear', str}, optional + The projection type of the subplot (`~.axes.Axes`). *str* is the + name of a custom projection, see `~matplotlib.projections`. The + default None results in a 'rectilinear' projection. + +polar : bool, default: False + If True, equivalent to projection='polar'. + +axes_class : subclass type of `~.axes.Axes`, optional + The `.axes.Axes` subclass that is instantiated. This parameter + is incompatible with *projection* and *polar*. See + :ref:`axisartist_users-guide-index` for examples. + +sharex, sharey : `~matplotlib.axes.Axes`, optional + Share the x or y `~matplotlib.axis` with sharex and/or sharey. + The axis will have the same limits, ticks, and scale as the axis + of the shared Axes. + +label : str + A label for the returned Axes. + +Returns +------- +`~.axes.Axes` + + The Axes of the subplot. The returned Axes can actually be an + instance of a subclass, such as `.projections.polar.PolarAxes` for + polar projections. + +Other Parameters +---------------- +**kwargs + This method also takes the keyword arguments for the returned Axes + base class; except for the *figure* argument. The keyword arguments + for the rectilinear base class `~.axes.Axes` can be found in + the following table but there might also be other keyword + arguments if another projection is used. + + Properties: + adjustable: {'box', 'datalim'} + agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image + alpha: float or None + anchor: (float, float) or {'C', 'SW', 'S', 'SE', 'E', 'NE', ...} + animated: bool + aspect: {'auto', 'equal'} or float + autoscale_on: bool + autoscalex_on: unknown + autoscaley_on: unknown + axes_locator: Callable[[Axes, Renderer], Bbox] + axisbelow: bool or 'line' + box_aspect: float or None + clip_box: `~matplotlib.transforms.BboxBase` or None + clip_on: bool + clip_path: Patch or (Path, Transform) or None + facecolor or fc: :mpltype:`color` + figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + forward_navigation_events: bool or "auto" + frame_on: bool + gid: str + in_layout: bool + label: object + mouseover: bool + navigate: bool + navigate_mode: unknown + path_effects: list of `.AbstractPathEffect` + picker: None or bool or float or callable + position: [left, bottom, width, height] or `~matplotlib.transforms.Bbox` + prop_cycle: `~cycler.Cycler` + rasterization_zorder: float or None + rasterized: bool + sketch_params: (scale: float, length: float, randomness: float) + snap: bool or None + subplotspec: unknown + title: str + transform: `~matplotlib.transforms.Transform` + url: str + visible: bool + xbound: (lower: float, upper: float) + xlabel: str + xlim: (left: float, right: float) + xmargin: float greater than -0.5 + xscale: unknown + xticklabels: unknown + xticks: unknown + ybound: (lower: float, upper: float) + ylabel: str + ylim: (bottom: float, top: float) + ymargin: float greater than -0.5 + yscale: unknown + yticklabels: unknown + yticks: unknown + zorder: float + +See Also +-------- +.Figure.add_axes +.pyplot.subplot +.pyplot.axes +.Figure.subplots +.pyplot.subplots + +Examples +-------- +:: + + fig = plt.figure() + + fig.add_subplot(231) + ax1 = fig.add_subplot(2, 3, 1) # equivalent but more general + + fig.add_subplot(232, frameon=False) # subplot with no frame + fig.add_subplot(233, projection='polar') # polar subplot + fig.add_subplot(234, sharex=ax1) # subplot sharing x-axis with ax1 + fig.add_subplot(235, facecolor="red") # red subplot + + ax1.remove() # delete ax1 from the figure + fig.add_subplot(ax1) # add ax1 back to the figure""" ... def subplot(self, *args: Incomplete, **kwargs: Incomplete) -> paxes.Axes: @@ -2269,7 +2570,163 @@ labelrotation : str, float, default: None See also -------- ultraplot.axes.Axes.colorbar -matplotlib.figure.Figure.colorbar""" +matplotlib.figure.Figure.colorbar + +Matplotlib documentation + + +Add a colorbar to a plot. + +Parameters +---------- +mappable + The `matplotlib.cm.ScalarMappable` (i.e., `.AxesImage`, + `.ContourSet`, etc.) described by this colorbar. This argument is + mandatory for the `.Figure.colorbar` method but optional for the + `.pyplot.colorbar` function, which sets the default to the current + image. + + Note that one can create a `.ScalarMappable` "on-the-fly" to + generate colorbars not attached to a previously drawn artist, e.g. + :: + + fig.colorbar(cm.ScalarMappable(norm=norm, cmap=cmap), ax=ax) + +cax : `~matplotlib.axes.Axes`, optional + Axes into which the colorbar will be drawn. If `None`, then a new + Axes is created and the space for it will be stolen from the Axes(s) + specified in *ax*. + +ax : `~matplotlib.axes.Axes` or iterable or `numpy.ndarray` of Axes, optional + The one or more parent Axes from which space for a new colorbar Axes + will be stolen. This parameter is only used if *cax* is not set. + + Defaults to the Axes that contains the mappable used to create the + colorbar. + +use_gridspec : bool, optional + If *cax* is ``None``, a new *cax* is created as an instance of + Axes. If *ax* is positioned with a subplotspec and *use_gridspec* + is ``True``, then *cax* is also positioned with a subplotspec. + +Returns +------- +colorbar : `~matplotlib.colorbar.Colorbar` + +Other Parameters +---------------- + +location : None or {'left', 'right', 'top', 'bottom'} + The location, relative to the parent Axes, where the colorbar Axes + is created. It also determines the *orientation* of the colorbar + (colorbars on the left and right are vertical, colorbars at the top + and bottom are horizontal). If None, the location will come from the + *orientation* if it is set (vertical colorbars on the right, horizontal + ones at the bottom), or default to 'right' if *orientation* is unset. + +orientation : None or {'vertical', 'horizontal'} + The orientation of the colorbar. It is preferable to set the *location* + of the colorbar, as that also determines the *orientation*; passing + incompatible values for *location* and *orientation* raises an exception. + +fraction : float, default: 0.15 + Fraction of original Axes to use for colorbar. + +shrink : float, default: 1.0 + Fraction by which to multiply the size of the colorbar. + +aspect : float, default: 20 + Ratio of long to short dimensions. + +pad : float, default: 0.05 if vertical, 0.15 if horizontal + Fraction of original Axes between colorbar and new image Axes. + +anchor : (float, float), optional + The anchor point of the colorbar Axes. + Defaults to (0.0, 0.5) if vertical; (0.5, 1.0) if horizontal. + +panchor : (float, float), or *False*, optional + The anchor point of the colorbar parent Axes. If *False*, the parent + axes' anchor will be unchanged. + Defaults to (1.0, 0.5) if vertical; (0.5, 0.0) if horizontal. + +extend : {'neither', 'both', 'min', 'max'} + Make pointed end(s) for out-of-range values (unless 'neither'). These are + set for a given colormap using the colormap set_under and set_over methods. + +extendfrac : {*None*, 'auto', length, lengths} + If set to *None*, both the minimum and maximum triangular colorbar + extensions will have a length of 5% of the interior colorbar length (this + is the default setting). + + If set to 'auto', makes the triangular colorbar extensions the same lengths + as the interior boxes (when *spacing* is set to 'uniform') or the same + lengths as the respective adjacent interior boxes (when *spacing* is set to + 'proportional'). + + If a scalar, indicates the length of both the minimum and maximum + triangular colorbar extensions as a fraction of the interior colorbar + length. A two-element sequence of fractions may also be given, indicating + the lengths of the minimum and maximum colorbar extensions respectively as + a fraction of the interior colorbar length. + +extendrect : bool + If *False* the minimum and maximum colorbar extensions will be triangular + (the default). If *True* the extensions will be rectangular. + +ticks : None or list of ticks or Locator + If None, ticks are determined automatically from the input. + +format : None or str or Formatter + If None, `~.ticker.ScalarFormatter` is used. + Format strings, e.g., ``"%4.2e"`` or ``"{x:.2e}"``, are supported. + An alternative `~.ticker.Formatter` may be given instead. + +drawedges : bool + Whether to draw lines at color boundaries. + +label : str + The label on the colorbar's long axis. + +boundaries, values : None or a sequence + If unset, the colormap will be displayed on a 0-1 scale. + If sequences, *values* must have a length 1 less than *boundaries*. For + each region delimited by adjacent entries in *boundaries*, the color mapped + to the corresponding value in *values* will be used. The size of each + region is determined by the *spacing* parameter. + Normally only useful for indexed colors (i.e. ``norm=NoNorm()``) or other + unusual circumstances. + +spacing : {'uniform', 'proportional'} + For discrete colorbars (`.BoundaryNorm` or contours), 'uniform' gives each + color the same space; 'proportional' makes the space proportional to the + data interval. + +Notes +----- +If *mappable* is a `~.contour.ContourSet`, its *extend* kwarg is +included automatically. + +The *shrink* kwarg provides a simple way to scale the colorbar with +respect to the Axes. Note that if *cax* is specified, it determines the +size of the colorbar, and *shrink* and *aspect* are ignored. + +For more precise control, you can manually specify the positions of the +axes objects in which the mappable and the colorbar are drawn. In this +case, do not use any of the Axes properties kwargs. + +It is known that some vector graphics viewers (svg and pdf) render +white gaps between segments of the colorbar. This is due to bugs in +the viewers, not Matplotlib. As a workaround, the colorbar can be +rendered with overlapping segments:: + + cbar = colorbar() + cbar.solids.set_edgecolor("face") + draw() + +However, this has negative consequences in other circumstances, e.g. +with semi-transparent images (alpha < 1) and colorbar extensions; +therefore, this workaround is not used by default (see issue #1188).""" ... def legend(self, handles: Incomplete=None, labels: Incomplete=None, loc: Incomplete=None, location: Incomplete=None, row: Incomplete=None, col: Incomplete=None, rows: Incomplete=None, cols: Incomplete=None, span: Incomplete=None, space: Incomplete=None, pad: Incomplete=None, width: Incomplete=None, **kwargs: Incomplete) -> Incomplete: @@ -2391,7 +2848,320 @@ handler_map : dict-like, optional See also -------- ultraplot.axes.Axes.legend -matplotlib.axes.Axes.legend""" +matplotlib.axes.Axes.legend + +Matplotlib documentation + + +Place a legend on the figure. + +Call signatures:: + + legend() + legend(handles, labels) + legend(handles=handles) + legend(labels) + +The call signatures correspond to the following different ways to use +this method: + +**1. Automatic detection of elements to be shown in the legend** + +The elements to be added to the legend are automatically determined, +when you do not pass in any extra arguments. + +In this case, the labels are taken from the artist. You can specify +them either at artist creation or by calling the +:meth:`~.Artist.set_label` method on the artist:: + + ax.plot([1, 2, 3], label='Inline label') + fig.legend() + +or:: + + line, = ax.plot([1, 2, 3]) + line.set_label('Label via method') + fig.legend() + +Specific lines can be excluded from the automatic legend element +selection by defining a label starting with an underscore. +This is default for all artists, so calling `.Figure.legend` without +any arguments and without setting the labels manually will result in +no legend being drawn. + + +**2. Explicitly listing the artists and labels in the legend** + +For full control of which artists have a legend entry, it is possible +to pass an iterable of legend artists followed by an iterable of +legend labels respectively:: + + fig.legend([line1, line2, line3], ['label1', 'label2', 'label3']) + + +**3. Explicitly listing the artists in the legend** + +This is similar to 2, but the labels are taken from the artists' +label properties. Example:: + + line1, = ax1.plot([1, 2, 3], label='label1') + line2, = ax2.plot([1, 2, 3], label='label2') + fig.legend(handles=[line1, line2]) + + +**4. Labeling existing plot elements** + +.. admonition:: Discouraged + + This call signature is discouraged, because the relation between + plot elements and labels is only implicit by their order and can + easily be mixed up. + +To make a legend for all artists on all Axes, call this function with +an iterable of strings, one for each legend item. For example:: + + fig, (ax1, ax2) = plt.subplots(1, 2) + ax1.plot([1, 3, 5], color='blue') + ax2.plot([2, 4, 6], color='red') + fig.legend(['the blues', 'the reds']) + + +Parameters +---------- +handles : list of `.Artist`, optional + A list of Artists (lines, patches) to be added to the legend. + Use this together with *labels*, if you need full control on what + is shown in the legend and the automatic mechanism described above + is not sufficient. + + The length of handles and labels should be the same in this + case. If they are not, they are truncated to the smaller length. + +labels : list of str, optional + A list of labels to show next to the artists. + Use this together with *handles*, if you need full control on what + is shown in the legend and the automatic mechanism described above + is not sufficient. + +Returns +------- +`~matplotlib.legend.Legend` + +Other Parameters +---------------- + +loc : str or pair of floats, default: 'upper right' + The location of the legend. + + The strings ``'upper left'``, ``'upper right'``, ``'lower left'``, + ``'lower right'`` place the legend at the corresponding corner of the + figure. + + The strings ``'upper center'``, ``'lower center'``, ``'center left'``, + ``'center right'`` place the legend at the center of the corresponding edge + of the figure. + + The string ``'center'`` places the legend at the center of the figure. + + The location can also be a 2-tuple giving the coordinates of the lower-left + corner of the legend in figure coordinates (in which case *bbox_to_anchor* + will be ignored). + + For back-compatibility, ``'center right'`` (but no other location) can also + be spelled ``'right'``, and each "string" location can also be given as a + numeric value: + + ================== ============= + Location String Location Code + ================== ============= + 'best' (Axes only) 0 + 'upper right' 1 + 'upper left' 2 + 'lower left' 3 + 'lower right' 4 + 'right' 5 + 'center left' 6 + 'center right' 7 + 'lower center' 8 + 'upper center' 9 + 'center' 10 + ================== ============= + + If a figure is using the constrained layout manager, the string codes + of the *loc* keyword argument can get better layout behaviour using the + prefix 'outside'. There is ambiguity at the corners, so 'outside + upper right' will make space for the legend above the rest of the + axes in the layout, and 'outside right upper' will make space on the + right side of the layout. In addition to the values of *loc* + listed above, we have 'outside right upper', 'outside right lower', + 'outside left upper', and 'outside left lower'. See + :ref:`legend_guide` for more details. + +bbox_to_anchor : `.BboxBase`, 2-tuple, or 4-tuple of floats + Box that is used to position the legend in conjunction with *loc*. + Defaults to ``axes.bbox`` (if called as a method to `.Axes.legend`) or + ``figure.bbox`` (if ``figure.legend``). This argument allows arbitrary + placement of the legend. + + Bbox coordinates are interpreted in the coordinate system given by + *bbox_transform*, with the default transform + Axes or Figure coordinates, depending on which ``legend`` is called. + + If a 4-tuple or `.BboxBase` is given, then it specifies the bbox + ``(x, y, width, height)`` that the legend is placed in. + To put the legend in the best location in the bottom right + quadrant of the Axes (or figure):: + + loc='best', bbox_to_anchor=(0.5, 0., 0.5, 0.5) + + A 2-tuple ``(x, y)`` places the corner of the legend specified by *loc* at + x, y. For example, to put the legend's upper right-hand corner in the + center of the Axes (or figure) the following keywords can be used:: + + loc='upper right', bbox_to_anchor=(0.5, 0.5) + +ncols : int, default: 1 + The number of columns that the legend has. + + For backward compatibility, the spelling *ncol* is also supported + but it is discouraged. If both are given, *ncols* takes precedence. + +prop : None or `~matplotlib.font_manager.FontProperties` or dict + The font properties of the legend. If None (default), the current + :data:`matplotlib.rcParams` will be used. + +fontsize : int or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'} + The font size of the legend. If the value is numeric the size will be the + absolute font size in points. String values are relative to the current + default font size. This argument is only used if *prop* is not specified. + +labelcolor : str or list, default: :rc:`legend.labelcolor` + The color of the text in the legend. Either a valid color string + (for example, 'red'), or a list of color strings. The labelcolor can + also be made to match the color of the line or marker using 'linecolor', + 'markerfacecolor' (or 'mfc'), or 'markeredgecolor' (or 'mec'). + + Labelcolor can be set globally using :rc:`legend.labelcolor`. If None, + use :rc:`text.color`. + +numpoints : int, default: :rc:`legend.numpoints` + The number of marker points in the legend when creating a legend + entry for a `.Line2D` (line). + +scatterpoints : int, default: :rc:`legend.scatterpoints` + The number of marker points in the legend when creating + a legend entry for a `.PathCollection` (scatter plot). + +scatteryoffsets : iterable of floats, default: ``[0.375, 0.5, 0.3125]`` + The vertical offset (relative to the font size) for the markers + created for a scatter plot legend entry. 0.0 is at the base the + legend text, and 1.0 is at the top. To draw all markers at the + same height, set to ``[0.5]``. + +markerscale : float, default: :rc:`legend.markerscale` + The relative size of legend markers compared to the originally drawn ones. + +markerfirst : bool, default: True + If *True*, legend marker is placed to the left of the legend label. + If *False*, legend marker is placed to the right of the legend label. + +reverse : bool, default: False + If *True*, the legend labels are displayed in reverse order from the input. + If *False*, the legend labels are displayed in the same order as the input. + + .. versionadded:: 3.7 + +frameon : bool, default: :rc:`legend.frameon` + Whether the legend should be drawn on a patch (frame). + +fancybox : bool, default: :rc:`legend.fancybox` + Whether round edges should be enabled around the `.FancyBboxPatch` which + makes up the legend's background. + +shadow : None, bool or dict, default: :rc:`legend.shadow` + Whether to draw a shadow behind the legend. + The shadow can be configured using `.Patch` keywords. + Customization via :rc:`legend.shadow` is currently not supported. + +framealpha : float, default: :rc:`legend.framealpha` + The alpha transparency of the legend's background. + If *shadow* is activated and *framealpha* is ``None``, the default value is + ignored. + +facecolor : "inherit" or color, default: :rc:`legend.facecolor` + The legend's background color. + If ``"inherit"``, use :rc:`axes.facecolor`. + +edgecolor : "inherit" or color, default: :rc:`legend.edgecolor` + The legend's background patch edge color. + If ``"inherit"``, use :rc:`axes.edgecolor`. + +mode : {"expand", None} + If *mode* is set to ``"expand"`` the legend will be horizontally + expanded to fill the Axes area (or *bbox_to_anchor* if defines + the legend's size). + +bbox_transform : None or `~matplotlib.transforms.Transform` + The transform for the bounding box (*bbox_to_anchor*). For a value + of ``None`` (default) the Axes' + :data:`~matplotlib.axes.Axes.transAxes` transform will be used. + +title : str or None + The legend's title. Default is no title (``None``). + +title_fontproperties : None or `~matplotlib.font_manager.FontProperties` or dict + The font properties of the legend's title. If None (default), the + *title_fontsize* argument will be used if present; if *title_fontsize* is + also None, the current :rc:`legend.title_fontsize` will be used. + +title_fontsize : int or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}, default: :rc:`legend.title_fontsize` + The font size of the legend's title. + Note: This cannot be combined with *title_fontproperties*. If you want + to set the fontsize alongside other font properties, use the *size* + parameter in *title_fontproperties*. + +alignment : {'center', 'left', 'right'}, default: 'center' + The alignment of the legend title and the box of entries. The entries + are aligned as a single block, so that markers always lined up. + +borderpad : float, default: :rc:`legend.borderpad` + The fractional whitespace inside the legend border, in font-size units. + +labelspacing : float, default: :rc:`legend.labelspacing` + The vertical space between the legend entries, in font-size units. + +handlelength : float, default: :rc:`legend.handlelength` + The length of the legend handles, in font-size units. + +handleheight : float, default: :rc:`legend.handleheight` + The height of the legend handles, in font-size units. + +handletextpad : float, default: :rc:`legend.handletextpad` + The pad between the legend handle and text, in font-size units. + +borderaxespad : float, default: :rc:`legend.borderaxespad` + The pad between the Axes and legend border, in font-size units. + +columnspacing : float, default: :rc:`legend.columnspacing` + The spacing between columns, in font-size units. + +handler_map : dict or None + The custom dictionary mapping instances or types to a legend + handler. This *handler_map* updates the default handler map + found at `matplotlib.legend.Legend.get_legend_handler_map`. + +draggable : bool, default: False + Whether the legend can be dragged with the mouse. + + +See Also +-------- +.Axes.legend + +Notes +----- +Some artists are not supported by this function. See +:ref:`legend_guide` for details.""" ... def save(self, filename: Incomplete, **kwargs: Incomplete) -> None: @@ -2425,7 +3195,125 @@ See also -------- Figure.save Figure.savefig -matplotlib.figure.Figure.savefig""" +matplotlib.figure.Figure.savefig + +Matplotlib documentation + + +Save the current figure as an image or vector graphic to a file. + +Call signature:: + + savefig(fname, *, transparent=None, dpi='figure', format=None, + metadata=None, bbox_inches=None, pad_inches=0.1, + facecolor='auto', edgecolor='auto', backend=None, + **kwargs + ) + +The available output formats depend on the backend being used. + +Parameters +---------- +fname : str or path-like or binary file-like + A path, or a Python file-like object, or + possibly some backend-dependent object such as + `matplotlib.backends.backend_pdf.PdfPages`. + + If *format* is set, it determines the output format, and the file + is saved as *fname*. Note that *fname* is used verbatim, and there + is no attempt to make the extension, if any, of *fname* match + *format*, and no extension is appended. + + If *format* is not set, then the format is inferred from the + extension of *fname*, if there is one. If *format* is not + set and *fname* has no extension, then the file is saved with + :rc:`savefig.format` and the appropriate extension is appended to + *fname*. + +Other Parameters +---------------- +transparent : bool, default: :rc:`savefig.transparent` + If *True*, the Axes patches will all be transparent; the + Figure patch will also be transparent unless *facecolor* + and/or *edgecolor* are specified via kwargs. + + If *False* has no effect and the color of the Axes and + Figure patches are unchanged (unless the Figure patch + is specified via the *facecolor* and/or *edgecolor* keyword + arguments in which case those colors are used). + + The transparency of these patches will be restored to their + original values upon exit of this function. + + This is useful, for example, for displaying + a plot on top of a colored background on a web page. + +dpi : float or 'figure', default: :rc:`savefig.dpi` + The resolution in dots per inch. If 'figure', use the figure's + dpi value. + +format : str + The file format, e.g. 'png', 'pdf', 'svg', ... The behavior when + this is unset is documented under *fname*. + +metadata : dict, optional + Key/value pairs to store in the image metadata. The supported keys + and defaults depend on the image format and backend: + + - 'png' with Agg backend: See the parameter ``metadata`` of + `~.FigureCanvasAgg.print_png`. + - 'pdf' with pdf backend: See the parameter ``metadata`` of + `~.backend_pdf.PdfPages`. + - 'svg' with svg backend: See the parameter ``metadata`` of + `~.FigureCanvasSVG.print_svg`. + - 'eps' and 'ps' with PS backend: Only 'Creator' is supported. + + Not supported for 'pgf', 'raw', and 'rgba' as those formats do not support + embedding metadata. + Does not currently support 'jpg', 'tiff', or 'webp', but may include + embedding EXIF metadata in the future. + +bbox_inches : str or `.Bbox`, default: :rc:`savefig.bbox` + Bounding box in inches: only the given portion of the figure is + saved. If 'tight', try to figure out the tight bbox of the figure. + +pad_inches : float or 'layout', default: :rc:`savefig.pad_inches` + Amount of padding in inches around the figure when bbox_inches is + 'tight'. If 'layout' use the padding from the constrained or + compressed layout engine; ignored if one of those engines is not in + use. + +facecolor : :mpltype:`color` or 'auto', default: :rc:`savefig.facecolor` + The facecolor of the figure. If 'auto', use the current figure + facecolor. + +edgecolor : :mpltype:`color` or 'auto', default: :rc:`savefig.edgecolor` + The edgecolor of the figure. If 'auto', use the current figure + edgecolor. + +backend : str, optional + Use a non-default backend to render the file, e.g. to render a + png file with the "cairo" backend rather than the default "agg", + or a pdf file with the "pgf" backend rather than the default + "pdf". Note that the default backend is normally sufficient. See + :ref:`the-builtin-backends` for a list of valid backends for each + file format. Custom backends can be referenced as "module://...". + +orientation : {'landscape', 'portrait'} + Currently only supported by the postscript backend. + +papertype : str + One of 'letter', 'legal', 'executive', 'ledger', 'a0' through + 'a10', 'b0' through 'b10'. Only supported for postscript + output. + +bbox_extra_artists : list of `~matplotlib.artist.Artist`, optional + A list of extra artists that will be considered when the + tight bbox is calculated. + +pil_kwargs : dict, optional + Additional keyword arguments that are passed to + `PIL.Image.Image.save` when saving the figure.""" ... def set_canvas(self, canvas: Incomplete) -> None: @@ -2440,7 +3328,16 @@ canvas : `~matplotlib.backend_bases.FigureCanvasBase` See also -------- -matplotlib.figure.Figure.set_canvas""" +matplotlib.figure.Figure.set_canvas + +Matplotlib documentation + + +Set the canvas that contains the figure + +Parameters +---------- +canvas : FigureCanvas""" ... def _is_same_size(self, figsize: Incomplete, eps: Incomplete=None) -> Incomplete: @@ -2466,7 +3363,38 @@ eps : float, optional See also -------- -matplotlib.figure.Figure.set_size_inches""" +matplotlib.figure.Figure.set_size_inches + +Matplotlib documentation + + +Set the figure size in inches. + +Call signatures:: + + fig.set_size_inches(w, h) # OR + fig.set_size_inches((w, h)) + +Parameters +---------- +w : (float, float) or float + Width and height in inches (if height not specified as a separate + argument) or width. +h : float + Height in inches. +forward : bool, default: True + If ``True``, the canvas size is automatically updated, e.g., + you can resize the figure window from the shell. + +See Also +-------- +matplotlib.figure.Figure.get_size_inches +matplotlib.figure.Figure.set_figwidth +matplotlib.figure.Figure.set_figheight + +Notes +----- +To transform from pixels to inches divide by `Figure.dpi`.""" ... def _iter_axes(self, hidden: Incomplete=False, children: Incomplete=False, panels: Incomplete=True) -> Incomplete: @@ -2497,6 +3425,14 @@ ultraplot.gridspec.SubplotGrid.gridspec""" @gridspec.setter def gridspec(self, gs: Incomplete) -> None: + """The single :class:`~ultraplot.gridspec.GridSpec` instance used for all +subplots in the figure. + +See also +-------- +ultraplot.figure.Figure.subplotgrid +ultraplot.gridspec.GridSpec.figure +ultraplot.gridspec.SubplotGrid.gridspec""" ... def _get_subplot(self, number: int) -> Incomplete: diff --git a/ultraplot/gridspec.py b/ultraplot/gridspec.py index df086ae60..a0386bb87 100644 --- a/ultraplot/gridspec.py +++ b/ultraplot/gridspec.py @@ -9,7 +9,7 @@ from collections.abc import MutableSequence from functools import wraps from numbers import Integral -from typing import Callable, List, Optional, Tuple, TypeVar, Union, cast, overload +from typing import Any, Callable, List, Optional, Tuple, TypeVar, Union, cast, overload import matplotlib.axes as maxes import matplotlib.gridspec as mgridspec @@ -1832,7 +1832,7 @@ def locally_modified_subplot_params(self): wpad_total = property(lambda self: list(self._wpad_total)) -class SubplotGrid(MutableSequence, list): +class SubplotGrid(MutableSequence[paxes.Axes], list[paxes.Axes]): """ List-like, array-like object used to store subplots returned by `~ultraplot.figure.Figure.subplots`. 1D indexing uses the underlying list of @@ -1883,7 +1883,7 @@ def __init__(self, sequence=None, **kwargs): sequence = self._validate_item(sequence, scalar=False) super().__init__(sequence, **kwargs) - def __getattr__(self, attr): + def __getattr__(self, attr: str) -> Any: """ Get a missing attribute. Simply redirects to the axes if the `SubplotGrid` is singleton and raises an error otherwise. This can be convenient for @@ -1926,7 +1926,19 @@ def _iterate_subplots(*args, **kwargs): else: raise AttributeError(f"Found mixed types for attribute {attr!r}.") - def __getitem__(self, key): + @overload + def __getitem__(self, key: int) -> paxes.Axes: ... + + @overload + def __getitem__( + self, + key: Union[slice, List[int], np.ndarray, Tuple[Union[int, slice], ...]], + ) -> "SubplotGrid": ... + + def __getitem__( + self, + key: Union[int, slice, List[int], np.ndarray, Tuple[Union[int, slice], ...]], + ) -> Union[paxes.Axes, "SubplotGrid"]: """ Get an axes. diff --git a/ultraplot/gridspec.pyi b/ultraplot/gridspec.pyi index e03cad427..cdf6fe659 100644 --- a/ultraplot/gridspec.pyi +++ b/ultraplot/gridspec.pyi @@ -10,7 +10,7 @@ import re from collections.abc import MutableSequence from functools import wraps from numbers import Integral -from typing import Callable, List, Optional, Tuple, TypeVar, Union, cast, overload +from typing import Any, Callable, List, Optional, Tuple, TypeVar, Union, cast, overload import matplotlib.axes as maxes import matplotlib.gridspec as mgridspec import matplotlib.transforms as mtransforms @@ -46,12 +46,11 @@ def _apply_to_all(func: None=None, *, doc_key: Optional[str]=None) -> Callable[[ ... class _SubplotSpec(mgridspec.SubplotSpec): - """ - A thin `~matplotlib.gridspec.SubplotSpec` subclass with a nice string - representation and a few helper methods. - """ + """A thin `~matplotlib.gridspec.SubplotSpec` subclass with a nice string +representation and a few helper methods.""" def __repr__(self) -> Incomplete: + """Return repr(self).""" ... def _get_geometry(self) -> Incomplete: @@ -71,15 +70,15 @@ the main plots, not the panels or colorbars.""" ... def get_position(self, figure: Incomplete, return_all: Incomplete=False) -> Incomplete: + """Update the subplot position from ``figure.subplotpars``.""" ... class GridSpec(mgridspec.GridSpec): - """ - A `~matplotlib.gridspec.GridSpec` subclass that permits variable spacing - between successive rows and columns and hides "panel slots" from indexing. - """ + """A `~matplotlib.gridspec.GridSpec` subclass that permits variable spacing +between successive rows and columns and hides "panel slots" from indexing.""" def __repr__(self) -> str: + """Return repr(self).""" ... def __getattr__(self, attr: Incomplete) -> None: @@ -488,6 +487,13 @@ ultraplot.figure.Figure.gridspec""" @figure.setter def figure(self, fig: Incomplete) -> None: + """The `ultraplot.figure.Figure` uniquely associated with this `GridSpec`. +On assignment the gridspec parameters and figure size are updated. + +See also +-------- +ultraplot.gridspec.SubplotGrid.figure +ultraplot.figure.Figure.gridspec""" ... tight_layout = _disable_method('tight_layout') subgridspec = _disable_method('subgridspec') @@ -497,9 +503,22 @@ ultraplot.figure.Figure.gridspec""" set_height_ratios = _disable_method('set_height_ratios') def get_subplot_params(self, figure: Incomplete=None) -> Incomplete: + """Return the `.SubplotParams` for the GridSpec. + +In order of precedence the values are taken from + +- non-*None* attributes of the GridSpec +- the provided *figure* +- :rc:`figure.subplot.*` + +Note that the ``figure`` attribute of the GridSpec is always ignored.""" ... def locally_modified_subplot_params(self) -> Incomplete: + """Return a list of the names of the subplot parameters explicitly set +in the GridSpec. + +This is a subset of the attributes of `.SubplotParams`.""" ... gridheight = ... gridwidth = ... @@ -536,24 +555,26 @@ ultraplot.figure.Figure.gridspec""" hpad_total = ... wpad_total = ... -class SubplotGrid(MutableSequence, list): - """ - List-like, array-like object used to store subplots returned by - `~ultraplot.figure.Figure.subplots`. 1D indexing uses the underlying list of - `~ultraplot.axes.Axes` while 2D indexing uses the `~SubplotGrid.gridspec`. - See `~SubplotGrid.__getitem__` for details. - """ +class SubplotGrid(MutableSequence[paxes.Axes], list[paxes.Axes], paxes.PlotAxes): + """List-like, array-like object used to store subplots returned by +`~ultraplot.figure.Figure.subplots`. 1D indexing uses the underlying list of +`~ultraplot.axes.Axes` while 2D indexing uses the `~SubplotGrid.gridspec`. +See `~SubplotGrid.__getitem__` for details.""" def __repr__(self) -> str: + """Return repr(self).""" ... def __str__(self) -> str: + """Return str(self).""" ... def __len__(self) -> int: + """Return len(self).""" ... def insert(self, key: Incomplete, value: Incomplete) -> None: + """S.insert(index, value) -- insert value before index""" ... def __init__(self, sequence: Incomplete=None, **kwargs: Incomplete) -> None: @@ -569,13 +590,40 @@ ultraplot.figure.Figure.subplots ultraplot.figure.Figure.add_subplots""" ... - def __getattr__(self, attr: Incomplete) -> Incomplete: + def __getattr__(self, attr: str) -> Any: """Get a missing attribute. Simply redirects to the axes if the `SubplotGrid` is singleton and raises an error otherwise. This can be convenient for single-axes figures generated with `~ultraplot.figure.Figure.subplots`.""" ... - def __getitem__(self, key: Incomplete) -> Incomplete: + @overload + def __getitem__(self, key: int) -> paxes.Axes: + """Get an axes. + +Parameters +---------- +key : int, slice, or 2-tuple + The index. If 1D then the axes in the corresponding + sublist are returned. If 2D then the axes that intersect + the corresponding `~SubplotGrid.gridspec` slots are returned. + +Returns +------- +axs : ultraplot.axes.Axes or SubplotGrid + The axes. If the index included slices then + another `SubplotGrid` is returned. + +Example +------- +>>> import ultraplot as uplt +>>> fig, axs = uplt.subplots(nrows=3, ncols=3) +>>> axs[5] # the subplot in the second row, third column +>>> axs[1, 2] # the subplot in the second row, third column +>>> axs[:, 0] # a SubplotGrid containing the subplots in the first column""" + ... + + @overload + def __getitem__(self, key: Union[slice, List[int], np.ndarray, Tuple[Union[int, slice], ...]]) -> 'SubplotGrid': """Get an axes. Parameters @@ -1227,60 +1275,353 @@ list ... def altx(self, *args: Incomplete, **kwargs: Incomplete) -> 'SubplotGrid': - """Call `altx()` for every axes in the grid. + """Add an axis locked to the same location with a +distinct x axis for every axes in the grid. +This is an alias and arguably more intuitive name for +`~ultraplot.axes.CartesianAxes.twiny`, which generates +two x axes with a shared ("twin") y axes. + +Parameters +---------- +**kwargs + Passed to `~ultraplot.axes.CartesianAxes`. Supports all valid + `~ultraplot.axes.CartesianAxes.format` keywords. You can optionally + omit the x from keywords beginning with ``x`` -- for example + ``ax.altx(lim=(0, 10))`` is equivalent to ``ax.altx(xlim=(0, 10))``. + You can also change the default side for the axis spine, axis tick marks, + axis tick labels, and/or axis labels by passing ``loc`` keywords. For example, + ``ax.altx(loc='bottom')`` changes the default side from top to bottom. Returns ------- -SubplotGrid - A grid of the resulting axes.""" +SubplotGridultraplot.axes.CartesianAxesA grid of the resulting axes. + +Note +---- +This enforces the following default settings: + +* Places the old x axis on the bottom and the new x + axis on the top. +* Makes the old top spine invisible and the new bottom, left, + and right spines invisible. +* Adjusts the x axis tick, tick label, and axis label positions + according to the visible spine positions. +* Syncs the old and new y axis limits and scales, and makes the + new y axis labels invisible.""" ... def dualx(self, *args: Incomplete, **kwargs: Incomplete) -> 'SubplotGrid': - """Call `dualx()` for every axes in the grid. + """Add an axes locked to the same location whose x axis denotes +equivalent coordinates in alternate units for every axes in the grid. +This is an alternative to `matplotlib.axes.Axes.secondary_xaxis` with +additional convenience features. + +Parameters +---------- +funcscale : callable, 2-tuple of callables, or scale-spec + The scale used to transform units from the parent axis to the secondary + axis. This can be a `~ultraplot.scale.FuncScale` itself or a function, + (function, function) tuple, or an axis scale specification interpreted + by the `~ultraplot.constructor.Scale` constructor function, any of which + will be used to build a `~ultraplot.scale.FuncScale` and applied + to the dual axis (see `~ultraplot.scale.FuncScale` for details). +**kwargs + Passed to `~ultraplot.axes.CartesianAxes`. Supports all valid + `~ultraplot.axes.CartesianAxes.format` keywords. You can optionally + omit the x from keywords beginning with ``x`` -- for example + ``ax.altx(lim=(0, 10))`` is equivalent to ``ax.altx(xlim=(0, 10))``. + You can also change the default side for the axis spine, axis tick marks, + axis tick labels, and/or axis labels by passing ``loc`` keywords. For example, + ``ax.altx(loc='bottom')`` changes the default side from top to bottom. Returns ------- -SubplotGrid - A grid of the resulting axes.""" +SubplotGridultraplot.axes.CartesianAxesA grid of the resulting axes. + +Note +---- +This enforces the following default settings: + +* Places the old x axis on the bottom and the new x + axis on the top. +* Makes the old top spine invisible and the new bottom, left, + and right spines invisible. +* Adjusts the x axis tick, tick label, and axis label positions + according to the visible spine positions. +* Syncs the old and new y axis limits and scales, and makes the + new y axis labels invisible.""" ... def twinx(self, *args: Incomplete, **kwargs: Incomplete) -> 'SubplotGrid': - """Call `twinx()` for every axes in the grid. + """Add an axis locked to the same location with a +distinct y axis for every axes in the grid. +This builds upon `matplotlib.axes.Axes.twinx`. + +Parameters +---------- +**kwargs + Passed to `~ultraplot.axes.CartesianAxes`. Supports all valid + `~ultraplot.axes.CartesianAxes.format` keywords. You can optionally + omit the y from keywords beginning with ``y`` -- for example + ``ax.alty(lim=(0, 10))`` is equivalent to ``ax.alty(ylim=(0, 10))``. + You can also change the default side for the axis spine, axis tick marks, + axis tick labels, and/or axis labels by passing ``loc`` keywords. For example, + ``ax.alty(loc='left')`` changes the default side from right to left. Returns ------- -SubplotGrid - A grid of the resulting axes.""" +SubplotGridultraplot.axes.CartesianAxesA grid of the resulting axes. + +Note +---- +This enforces the following default settings: + +* Places the old y axis on the left and the new y + axis on the right. +* Makes the old right spine invisible and the new left, bottom, + and top spines invisible. +* Adjusts the y axis tick, tick label, and axis label positions + according to the visible spine positions. +* Syncs the old and new x axis limits and scales, and makes the + new x axis labels invisible.""" ... def alty(self, *args: Incomplete, **kwargs: Incomplete) -> 'SubplotGrid': - """Call `alty()` for every axes in the grid. + """Add an axis locked to the same location with a +distinct y axis for every axes in the grid. +This is an alias and arguably more intuitive name for +`~ultraplot.axes.CartesianAxes.twinx`, which generates +two y axes with a shared ("twin") x axes. + +Parameters +---------- +**kwargs + Passed to `~ultraplot.axes.CartesianAxes`. Supports all valid + `~ultraplot.axes.CartesianAxes.format` keywords. You can optionally + omit the y from keywords beginning with ``y`` -- for example + ``ax.alty(lim=(0, 10))`` is equivalent to ``ax.alty(ylim=(0, 10))``. + You can also change the default side for the axis spine, axis tick marks, + axis tick labels, and/or axis labels by passing ``loc`` keywords. For example, + ``ax.alty(loc='left')`` changes the default side from right to left. Returns ------- -SubplotGrid - A grid of the resulting axes.""" +SubplotGridultraplot.axes.CartesianAxesA grid of the resulting axes. + +Note +---- +This enforces the following default settings: + +* Places the old y axis on the left and the new y + axis on the right. +* Makes the old right spine invisible and the new left, bottom, + and top spines invisible. +* Adjusts the y axis tick, tick label, and axis label positions + according to the visible spine positions. +* Syncs the old and new x axis limits and scales, and makes the + new x axis labels invisible.""" ... def dualy(self, *args: Incomplete, **kwargs: Incomplete) -> 'SubplotGrid': - """Call `dualy()` for every axes in the grid. + """Add an axes locked to the same location whose y axis denotes +equivalent coordinates in alternate units for every axes in the grid. +This is an alternative to `matplotlib.axes.Axes.secondary_yaxis` with +additional convenience features. + +Parameters +---------- +funcscale : callable, 2-tuple of callables, or scale-spec + The scale used to transform units from the parent axis to the secondary + axis. This can be a `~ultraplot.scale.FuncScale` itself or a function, + (function, function) tuple, or an axis scale specification interpreted + by the `~ultraplot.constructor.Scale` constructor function, any of which + will be used to build a `~ultraplot.scale.FuncScale` and applied + to the dual axis (see `~ultraplot.scale.FuncScale` for details). +**kwargs + Passed to `~ultraplot.axes.CartesianAxes`. Supports all valid + `~ultraplot.axes.CartesianAxes.format` keywords. You can optionally + omit the y from keywords beginning with ``y`` -- for example + ``ax.alty(lim=(0, 10))`` is equivalent to ``ax.alty(ylim=(0, 10))``. + You can also change the default side for the axis spine, axis tick marks, + axis tick labels, and/or axis labels by passing ``loc`` keywords. For example, + ``ax.alty(loc='left')`` changes the default side from right to left. Returns ------- -SubplotGrid - A grid of the resulting axes.""" +SubplotGridultraplot.axes.CartesianAxesA grid of the resulting axes. + +Note +---- +This enforces the following default settings: + +* Places the old y axis on the left and the new y + axis on the right. +* Makes the old right spine invisible and the new left, bottom, + and top spines invisible. +* Adjusts the y axis tick, tick label, and axis label positions + according to the visible spine positions. +* Syncs the old and new x axis limits and scales, and makes the + new x axis labels invisible.""" ... def twiny(self, *args: Incomplete, **kwargs: Incomplete) -> 'SubplotGrid': + """Add an axis locked to the same location with a +distinct x axis for every axes in the grid. +This builds upon `matplotlib.axes.Axes.twiny`. + +Parameters +---------- +**kwargs + Passed to `~ultraplot.axes.CartesianAxes`. Supports all valid + `~ultraplot.axes.CartesianAxes.format` keywords. You can optionally + omit the x from keywords beginning with ``x`` -- for example + ``ax.altx(lim=(0, 10))`` is equivalent to ``ax.altx(xlim=(0, 10))``. + You can also change the default side for the axis spine, axis tick marks, + axis tick labels, and/or axis labels by passing ``loc`` keywords. For example, + ``ax.altx(loc='bottom')`` changes the default side from top to bottom. + +Returns +------- +SubplotGridultraplot.axes.CartesianAxesA grid of the resulting axes. + +Note +---- +This enforces the following default settings: + +* Places the old x axis on the bottom and the new x + axis on the top. +* Makes the old top spine invisible and the new bottom, left, + and right spines invisible. +* Adjusts the x axis tick, tick label, and axis label positions + according to the visible spine positions. +* Syncs the old and new y axis limits and scales, and makes the + new y axis labels invisible.""" ... def panel(self, *args: Incomplete, **kwargs: Incomplete) -> 'SubplotGrid': + """Add a panel axes for every axes in the grid. + +Parameters +----------- +side : str, optional + The panel location. Valid location keys are as follows. + + ========== ===================== + Location Valid keys + ========== ===================== + left ``'left'``, ``'l'`` + right ``'right'``, ``'r'`` + bottom ``'bottom'``, ``'b'`` + top ``'top'``, ``'t'`` + ========== ===================== + +width : unit-spec, default: :rc:`subplots.panelwidth` + The panel width. + If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. +space : unit-spec, default: None + The fixed space between the panel and the subplot edge. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + When the :ref:`tight layout algorithm ` is active for the figure, + `space` is computed automatically (see `pad`). Otherwise, `space` is set to + a suitable default. +pad : unit-spec, default: :rc:`subplots.panelpad` + The :ref:`tight layout padding ` between the panel and the subplot. + If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +row, rows + Aliases for `span` for panels on the left or right side (vertical panels). +col, cols + Aliases for `span` for panels on the top or bottom side (horizontal panels). +span : int or 2-tuple of int, default: None + Integer(s) indicating the span of the panel across rows and columns of + subplots. For panels on the left or right side, use `rows` or `row` to + specify which rows the panel should span. For panels on the top or bottom + side, use `cols` or `col` to specify which columns the panel should span. + For example, ``ax.panel('b', col=1)`` draws a panel beneath only the + leftmost column, and ``ax.panel('b', cols=(1, 2))`` draws a panel beneath + the left two columns. By default the panel will span all rows or columns + aligned with the parent axes. +share : bool, default: True + Whether to enable axis sharing between the *x* and *y* axes of the + main subplot and the panel long axes for each panel in the "stack". + Sharing between the panel short axis and other panel short axes + is determined by figure-wide `sharex` and `sharey` settings. + +Other parameters +----------------- +**kwargs + Passed to `ultraplot.axes.CartesianAxes`. Supports all valid + `~ultraplot.axes.CartesianAxes.format` keywords. + +Returns +-------- +ultraplot.axes.CartesianAxes + The panel axes.""" ... def panel_axes(self, *args: Incomplete, **kwargs: Incomplete) -> 'SubplotGrid': ... def inset(self, *args: Incomplete, **kwargs: Incomplete) -> 'SubplotGrid': + """Add an inset axes for every axes in the grid. +This is similar to `matplotlib.axes.Axes.inset_axes`. + +Parameters +----------- +bounds : 4-tuple of float or (4-tuple, transform) + The (left, bottom, width, height) coordinates for the axes. To specify the + coordinate system alongside the coordinates, pass ``(bounds, transform)``. +transform : {'data', 'axes', 'figure', 'subfigure'} or `~matplotlib.transforms.Transform`, optional + The transform used to interpret the bounds. Can be a + :class:`~matplotlib.transforms.Transform` instance or a string representing + the :class:`~matplotlib.axes.Axes.transData`, :class:`~matplotlib.axes.Axes.transAxes`, + :class:`~matplotlib.figure.Figure.transFigure`, or + :class:`~matplotlib.figure.Figure.transSubfigure`, transforms. + Default is to use the same projection as the current axes. +proj, projection : +str, `cartopy.crs.Projection`, or `~mpl_toolkits.basemap.Basemap`, optional + The map projection specification(s). If ``'cart'`` or ``'cartesian'`` + (the default), a `~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, + a :class:`~ultraplot.axes.PolarAxes` is created. Otherwise, the argument is + interpreted by `~ultraplot.constructor.Proj`, and the result is used + to make a `~ultraplot.axes.GeoAxes` (in this case the argument can be + a `cartopy.crs.Projection` instance, a `~mpl_toolkits.basemap.Basemap` + instance, or a projection name listed in :ref:`this table `). +proj_kw, projection_kw : dict-like, optional + Keyword arguments passed to `~mpl_toolkits.basemap.Basemap` or + cartopy `~cartopy.crs.Projection` classes on instantiation. +backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` + Whether to use `~mpl_toolkits.basemap.Basemap` or + `~cartopy.crs.Projection` for map projections. + + .. deprecated:: 3.0.0 + The ``'basemap'`` backend is deprecated and may be removed in a + future release. Please use the ``'cartopy'`` backend instead. +zorder : float, default: 4 + The `zorder `__ + of the axes. Should be greater than the zorder of elements in the parent axes. +zoom : bool, default: True or False + Whether to draw lines indicating the inset zoom using `~Axes.indicate_inset_zoom`. + The line positions will automatically adjust when the parent or inset axes limits + change. Default is ``True`` only if both axes are `~ultraplot.axes.CartesianAxes`. +zoom_kw : dict, optional + Passed to `~Axes.indicate_inset_zoom`. + +Other parameters +----------------- +**kwargs + Passed to `ultraplot.axes.Axes`. + +Returns +-------- +ultraplot.axes.Axes + The inset axes. + +See also +--------- +Axes.indicate_inset_zoom +matplotlib.axes.Axes.inset_axes +matplotlib.axes.Axes.indicate_inset +matplotlib.axes.Axes.indicate_inset_zoom""" ... def inset_axes(self, *args: Incomplete, **kwargs: Incomplete) -> 'SubplotGrid': diff --git a/ultraplot/internals/benchmarks.pyi b/ultraplot/internals/benchmarks.pyi index fa75c4195..74469f100 100644 --- a/ultraplot/internals/benchmarks.pyi +++ b/ultraplot/internals/benchmarks.pyi @@ -9,11 +9,10 @@ from . import ic BENCHMARK = False class _benchmark(object): - """ - Context object for timing arbitrary blocks of code. - """ + """Context object for timing arbitrary blocks of code.""" def __init__(self, message: Incomplete) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def __enter__(self) -> None: diff --git a/ultraplot/internals/context.pyi b/ultraplot/internals/context.pyi index 3e973d5d2..ee40f8095 100644 --- a/ultraplot/internals/context.pyi +++ b/ultraplot/internals/context.pyi @@ -7,11 +7,10 @@ from _typeshed import Incomplete from . import ic class _empty_context(object): - """ - A dummy context manager. - """ + """A dummy context manager.""" def __init__(self) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def __enter__(self) -> None: @@ -21,11 +20,10 @@ class _empty_context(object): ... class _state_context(object): - """ - Temporarily modify attribute(s) for an arbitrary object. - """ + """Temporarily modify attribute(s) for an arbitrary object.""" def __init__(self, obj: Incomplete, **kwargs: Incomplete) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def __enter__(self) -> None: diff --git a/ultraplot/internals/docstring.pyi b/ultraplot/internals/docstring.pyi index 94284fe52..490eb362b 100644 --- a/ultraplot/internals/docstring.pyi +++ b/ultraplot/internals/docstring.pyi @@ -32,9 +32,7 @@ axes method and mark its generated-documentation signature as compact.""" ... class _SnippetManager(dict): - """ - A simple database for handling documentation snippets. - """ + """A simple database for handling documentation snippets.""" _lazy_modules = {'axes': 'ultraplot.axes.base', 'cartesian': 'ultraplot.axes.cartesian', 'polar': 'ultraplot.axes.polar', 'geo': 'ultraplot.axes.geo', 'plot': 'ultraplot.axes.plot', 'figure': 'ultraplot.figure', 'gridspec': 'ultraplot.gridspec', 'legend': 'ultraplot.legend', 'ticker': 'ultraplot.ticker', 'proj': 'ultraplot.proj', 'colors': 'ultraplot.colors', 'utils': 'ultraplot.utils', 'config': 'ultraplot.config', 'demos': 'ultraplot.demos', 'rc': 'ultraplot.axes.base'} def __missing__(self, key: Incomplete) -> Incomplete: @@ -43,10 +41,14 @@ class _SnippetManager(dict): @overload def __call__(self, obj: str) -> str: + """Add snippets to the string or object using ``%(name)s`` substitution. Here +``%(name)s`` is used rather than ``.format`` to support invalid identifiers.""" ... @overload def __call__(self, obj: _T) -> _T: + """Add snippets to the string or object using ``%(name)s`` substitution. Here +``%(name)s`` is used rather than ``.format`` to support invalid identifiers.""" ... def __setitem__(self, key: Incomplete, value: Incomplete) -> None: diff --git a/ultraplot/internals/fonts.pyi b/ultraplot/internals/fonts.pyi index cad696f3c..675433009 100644 --- a/ultraplot/internals/fonts.pyi +++ b/ultraplot/internals/fonts.pyi @@ -24,21 +24,27 @@ def _clear_math_parse_cache() -> None: ... class _UnicodeFonts(UnicodeFonts): - """ - A simple `~matplotlib._mathtext.UnicodeFonts` subclass that - interprets ``rc['mathtext.default'] != 'regular'`` in the presence of - ``rc['mathtext.fontset'] == 'custom'`` as possibly modifying the active font. + """A simple `~matplotlib._mathtext.UnicodeFonts` subclass that +interprets ``rc['mathtext.default'] != 'regular'`` in the presence of +``rc['mathtext.fontset'] == 'custom'`` as possibly modifying the active font. - Works by permitting the ``rc['mathtext.rm']``, ``rc['mathtext.it']``, - etc. settings to have the dummy value ``'regular'`` instead of a valid family - name, e.g. ``rc['mathtext.it'] == 'regular:italic'`` (permitted through an - override of the `~matplotlib.rcsetup.validate_font_properties` validator). - When this dummy value is detected then the font properties passed to - `~matplotlib._mathtext.TrueTypeFont` are taken by replacing ``'regular'`` - in the "math" fontset with the active font name. - """ +Works by permitting the ``rc['mathtext.rm']``, ``rc['mathtext.it']``, +etc. settings to have the dummy value ``'regular'`` instead of a valid family +name, e.g. ``rc['mathtext.it'] == 'regular:italic'`` (permitted through an +override of the `~matplotlib.rcsetup.validate_font_properties` validator). +When this dummy value is detected then the font properties passed to +`~matplotlib._mathtext.TrueTypeFont` are taken by replacing ``'regular'`` +in the "math" fontset with the active font name.""" def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: + """Parameters +---------- +default_font_prop : `~.font_manager.FontProperties` + The default non-math font, or the base font for Unicode (generic) + font rendering. +load_glyph_flags : `.ft2font.LoadFlags` + Flags passed to the glyph loader (e.g. ``FT_Load_Glyph`` and + ``FT_Load_Char`` for FreeType-based fonts).""" ... def _init_computer_modern_fonts(self, *args: Incomplete, **kwargs: Incomplete) -> None: @@ -57,6 +63,10 @@ class _UnicodeFonts(UnicodeFonts): ... def get_sized_alternatives_for_symbol(self, fontname: str, sym: str) -> Incomplete: + """Override if your font provides multiple sizes of the same +symbol. Should return a list of symbols matching *sym* in +various sizes. The expression renderer will select the most +appropriate size for a given situation from this list.""" ... try: mapping = MathTextParser._font_type_mapping diff --git a/ultraplot/internals/guides.pyi b/ultraplot/internals/guides.pyi index cb432a99a..6125dd80e 100644 --- a/ultraplot/internals/guides.pyi +++ b/ultraplot/internals/guides.pyi @@ -45,11 +45,7 @@ def _update_ticks(self, manual_only: Incomplete=False) -> None: ... class _InsetColorbar(martist.Artist): - """ - Legend-like class for managing inset colorbars. - """ + """Legend-like class for managing inset colorbars.""" class _CenteredLegend(martist.Artist): - """ - Legend-like class for managing centered-row legends. - """ + """Legend-like class for managing centered-row legends.""" diff --git a/ultraplot/internals/rcsetup.pyi b/ultraplot/internals/rcsetup.pyi index 29c400bcb..ab30584ce 100644 --- a/ultraplot/internals/rcsetup.pyi +++ b/ultraplot/internals/rcsetup.pyi @@ -153,29 +153,34 @@ def _yaml_table(rcdict: Incomplete, comment: Incomplete=True, description: Incom ... class _RcParams(MutableMapping, dict): - """ - A simple dictionary with locked inputs and validated assignments. - """ + """A simple dictionary with locked inputs and validated assignments.""" def __init__(self, source: Incomplete, validate: Incomplete) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def __repr__(self) -> Incomplete: + """Return repr(self).""" ... def __str__(self) -> Incomplete: + """Return str(self).""" ... def __len__(self) -> Incomplete: + """Return len(self).""" ... def __iter__(self) -> Incomplete: + """Implement iter(self).""" ... def __getitem__(self, key: Incomplete) -> Incomplete: + """Return self[key].""" ... def __setitem__(self, key: Incomplete, value: Incomplete) -> Incomplete: + """Set self[key] to value.""" ... @staticmethod @@ -183,6 +188,7 @@ class _RcParams(MutableMapping, dict): ... def copy(self) -> Incomplete: + """Return a shallow copy of the dict.""" ... _validate_pt = _validate_units('pt') _validate_em = _validate_units('em') diff --git a/ultraplot/internals/versions.pyi b/ultraplot/internals/versions.pyi index b3afe0c82..067121744 100644 --- a/ultraplot/internals/versions.pyi +++ b/ultraplot/internals/versions.pyi @@ -8,36 +8,43 @@ from . import ic from . import warnings class _version(list): - """ - Casual parser for ``major.minor`` style version strings. We do not want to - add a 'packaging' dependency and only care about major and minor tags. - """ + """Casual parser for ``major.minor`` style version strings. We do not want to +add a 'packaging' dependency and only care about major and minor tags.""" def __str__(self) -> str: + """Return str(self).""" ... def __repr__(self) -> str: + """Return repr(self).""" ... def __init__(self, version: Incomplete) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def __eq__(self, other: Incomplete) -> bool: + """Return self==value.""" ... def __ne__(self, other: Incomplete) -> bool: + """Return self!=value.""" ... def __gt__(self, other: Incomplete) -> bool: + """Return self>value.""" ... def __lt__(self, other: Incomplete) -> bool: + """Return self bool: + """Return self>=value.""" ... def __le__(self, other: Incomplete) -> bool: + """Return self<=value.""" ... import matplotlib _version_mpl = _version(matplotlib.__version__) diff --git a/ultraplot/legend.pyi b/ultraplot/legend.pyi index 830cd505a..53e1726a8 100644 --- a/ultraplot/legend.pyi +++ b/ultraplot/legend.pyi @@ -46,15 +46,66 @@ def _wedge_legend_patch(legend: Incomplete, orig_handle: Incomplete, xdescent: I ... class LegendEntry(mlines.Line2D): - """ - Convenience artist for custom legend entries. + """Convenience artist for custom legend entries. - This is a lightweight wrapper around `matplotlib.lines.Line2D` that - initializes with empty data so it can be passed directly to - `Axes.legend()` or `Figure.legend()` handles. - """ +This is a lightweight wrapper around `matplotlib.lines.Line2D` that +initializes with empty data so it can be passed directly to +`Axes.legend()` or `Figure.legend()` handles.""" def __init__(self, label: Incomplete=None, *, color: Incomplete=None, line: Incomplete=True, marker: Incomplete=None, linestyle: Incomplete='-', linewidth: Incomplete=2, markersize: Incomplete=6, markerfacecolor: Incomplete=None, markeredgecolor: Incomplete=None, markeredgewidth: Incomplete=None, alpha: Incomplete=None, marker_capstyle: Incomplete=None, marker_joinstyle: Incomplete=None, marker_transform: Incomplete=None, **kwargs: Incomplete) -> None: + """Create a `.Line2D` instance with *x* and *y* data in sequences of +*xdata*, *ydata*. + +Additional keyword arguments are `.Line2D` properties: + +Properties: + agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image + alpha: float or None + animated: bool + antialiased or aa: bool + clip_box: `~matplotlib.transforms.BboxBase` or None + clip_on: bool + clip_path: Patch or (Path, Transform) or None + color or c: :mpltype:`color` + dash_capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} + dash_joinstyle: `.JoinStyle` or {'miter', 'round', 'bevel'} + dashes: sequence of floats (on/off ink in points) or (None, None) + data: (2, N) array or two 1D arrays + drawstyle or ds: {'default', 'steps', 'steps-pre', 'steps-mid', 'steps-post'}, default: 'default' + figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + fillstyle: {'full', 'left', 'right', 'bottom', 'top', 'none'} + gapcolor: :mpltype:`color` or None + gid: str + in_layout: bool + label: object + linestyle or ls: {'-', '--', '-.', ':', '', (offset, on-off-seq), ...} + linewidth or lw: float + marker: marker style string, `~.path.Path` or `~.markers.MarkerStyle` + markeredgecolor or mec: :mpltype:`color` + markeredgewidth or mew: float + markerfacecolor or mfc: :mpltype:`color` + markerfacecoloralt or mfcalt: :mpltype:`color` + markersize or ms: float + markevery: None or int or (int, int) or slice or list[int] or float or (float, float) or list[bool] + mouseover: bool + path_effects: list of `.AbstractPathEffect` + picker: float or callable[[Artist, Event], tuple[bool, dict]] + pickradius: float + rasterized: bool + sketch_params: (scale: float, length: float, randomness: float) + snap: bool or None + solid_capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} + solid_joinstyle: `.JoinStyle` or {'miter', 'round', 'bevel'} + transform: unknown + url: str + visible: bool + xdata: 1D array + ydata: 1D array + zorder: float + +See :meth:`set_linestyle` for a description of the line styles, +:meth:`set_marker` for a description of the markers, and +:meth:`set_drawstyle` for a description of the draw styles.""" ... @classmethod @@ -68,11 +119,27 @@ class LegendEntry(mlines.Line2D): ... class _Line2DLegendHandler(mhandler.HandlerLine2D): - """ - Match single-point marker plots by hiding the legend connector line. - """ + """Match single-point marker plots by hiding the legend connector line.""" def create_artists(self, legend: Incomplete, orig_handle: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Return the legend artists generated. + +Parameters +---------- +legend : `~matplotlib.legend.Legend` + The legend for which these legend artists are being created. +orig_handle : `~matplotlib.artist.Artist` or similar + The object for which these legend artists are being created. +xdescent, ydescent, width, height : int + The rectangle (*xdescent*, *ydescent*, *width*, *height*) that the + legend artists being created should fit within. +fontsize : int + The fontsize in pixels. The legend artists being created should + be scaled according to the given fontsize. +trans : `~matplotlib.transforms.Transform` + The transform that is applied to the legend artists being created. + Typically from unit coordinates in the handler box to screen + coordinates.""" ... _GEOMETRY_SHAPE_PATHS = {'circle': mpath.Path.unit_circle(), 'square': mpath.Path.unit_rectangle(), 'triangle': mpath.Path.unit_regular_polygon(3), 'diamond': mpath.Path.unit_regular_polygon(4), 'pentagon': mpath.Path.unit_regular_polygon(5), 'hexagon': mpath.Path.unit_regular_polygon(6), 'star': mpath.Path.unit_regular_star(5), 'rectangle': mpath.Path([[0, 0], [2, 0], [2, 1], [0, 1], [0, 0]], closed=True, readonly=True), 'line': mpath.Path([[0, 0], [1, 0]], readonly=True)} _GEOMETRY_SHAPE_ALIASES = {'box': 'square', 'rect': 'rectangle', 'rec': 'rectangle', 'tri': 'triangle', 'pent': 'pentagon', 'hex': 'hexagon'} @@ -158,50 +225,123 @@ def _geometry_entry_patch(legend: Incomplete, orig_handle: Incomplete, xdescent: ... class _FeatureArtistLegendHandler(mhandler.HandlerPatch): - """ - Legend handler for cartopy FeatureArtist instances. - """ + """Legend handler for cartopy FeatureArtist instances.""" def __init__(self) -> None: + """Parameters +---------- +patch_func : callable, optional + The function that creates the legend key artist. + *patch_func* should have the signature:: + + def patch_func(legend=legend, orig_handle=orig_handle, + xdescent=xdescent, ydescent=ydescent, + width=width, height=height, fontsize=fontsize) + + Subsequently, the created artist will have its ``update_prop`` + method called and the appropriate transform will be applied. + +**kwargs + Keyword arguments forwarded to `.HandlerBase`.""" ... def update_prop(self, legend_handle: Incomplete, orig_handle: Incomplete, legend: Incomplete) -> Incomplete: ... class _ShapelyGeometryLegendHandler(mhandler.HandlerPatch): - """ - Legend handler for raw shapely geometries. - """ + """Legend handler for raw shapely geometries.""" def __init__(self) -> None: + """Parameters +---------- +patch_func : callable, optional + The function that creates the legend key artist. + *patch_func* should have the signature:: + + def patch_func(legend=legend, orig_handle=orig_handle, + xdescent=xdescent, ydescent=ydescent, + width=width, height=height, fontsize=fontsize) + + Subsequently, the created artist will have its ``update_prop`` + method called and the appropriate transform will be applied. + +**kwargs + Keyword arguments forwarded to `.HandlerBase`.""" ... def update_prop(self, legend_handle: Incomplete, orig_handle: Incomplete, legend: Incomplete) -> Incomplete: ... class _GeometryEntryLegendHandler(mhandler.HandlerPatch): - """ - Legend handler for `GeometryEntry` custom handles. - """ + """Legend handler for `GeometryEntry` custom handles.""" def __init__(self) -> None: + """Parameters +---------- +patch_func : callable, optional + The function that creates the legend key artist. + *patch_func* should have the signature:: + + def patch_func(legend=legend, orig_handle=orig_handle, + xdescent=xdescent, ydescent=ydescent, + width=width, height=height, fontsize=fontsize) + + Subsequently, the created artist will have its ``update_prop`` + method called and the appropriate transform will be applied. + +**kwargs + Keyword arguments forwarded to `.HandlerBase`.""" ... def update_prop(self, legend_handle: Incomplete, orig_handle: Incomplete, legend: Incomplete) -> Incomplete: ... class GeometryEntry(mpatches.PathPatch): - """ - Convenience geometry legend entry. + """Convenience geometry legend entry. - Parameters - ---------- - geometry - Geometry shorthand (e.g. ``'triangle'`` or ``'country:AU'``), - shapely geometry, or `matplotlib.path.Path`. - """ +Parameters +---------- +geometry + Geometry shorthand (e.g. ``'triangle'`` or ``'country:AU'``), + shapely geometry, or `matplotlib.path.Path`.""" def __init__(self, geometry: Any='square', *, country_reso: str='110m', country_territories: bool=False, country_proj: Any=None, label: Optional[str]=None, facecolor: Any='none', edgecolor: Any='0.25', linewidth: float=1.0, joinstyle: str=_DEFAULT_GEO_JOINSTYLE, alpha: Optional[float]=None, fill: Optional[bool]=None, **kwargs: Any) -> None: + """*path* is a `.Path` object. + +Valid keyword arguments are: + +Properties: + agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image + alpha: unknown + animated: bool + antialiased or aa: bool or None + capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} + clip_box: `~matplotlib.transforms.BboxBase` or None + clip_on: bool + clip_path: Patch or (Path, Transform) or None + color: :mpltype:`color` + edgecolor or ec: :mpltype:`color` or None + facecolor or fc: :mpltype:`color` or None + figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + fill: bool + gid: str + hatch: {'/', '\\\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'} + hatch_linewidth: unknown + in_layout: bool + joinstyle: `.JoinStyle` or {'miter', 'round', 'bevel'} + label: object + linestyle or ls: {'-', '--', '-.', ':', '', (offset, on-off-seq), ...} + linewidth or lw: float or None + mouseover: bool + path_effects: list of `.AbstractPathEffect` + picker: None or bool or float or callable + rasterized: bool + sketch_params: (scale: float, length: float, randomness: float) + snap: bool or None + transform: `~matplotlib.transforms.Transform` + url: str + visible: bool + zorder: float""" ... def _geometry_default_label(geometry: Any, index: int) -> str: @@ -379,6 +519,237 @@ class _LegendInputs: class Legend(mlegend.Legend): def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: + """Parameters +---------- +parent : `~matplotlib.axes.Axes` or `.Figure` + The artist that contains the legend. + +handles : list of (`.Artist` or tuple of `.Artist`) + A list of Artists (lines, patches) to be added to the legend. + +labels : list of str + A list of labels to show next to the artists. The length of handles + and labels should be the same. If they are not, they are truncated + to the length of the shorter list. + +Other Parameters +---------------- + +loc : str or pair of floats, default: :rc:`legend.loc` for Axes, 'upper right' for Figure + The location of the legend. + + The strings ``'upper left'``, ``'upper right'``, ``'lower left'``, + ``'lower right'`` place the legend at the corresponding corner of the + axes/figure. + + The strings ``'upper center'``, ``'lower center'``, ``'center left'``, + ``'center right'`` place the legend at the center of the corresponding edge + of the axes/figure. + + The string ``'center'`` places the legend at the center of the axes/figure. + + The string ``'best'`` places the legend at the location, among the nine + locations defined so far, with the minimum overlap with other drawn + artists. This option can be quite slow for plots with large amounts of + data; your plotting speed may benefit from providing a specific location. + + The location can also be a 2-tuple giving the coordinates of the lower-left + corner of the legend in axes/figure coordinates (in which case *bbox_to_anchor* + will be ignored). + + For back-compatibility, ``'center right'`` (but no other location) can also + be spelled ``'right'``, and each "string" location can also be given as a + numeric value: + + ================== ============= + Location String Location Code + ================== ============= + 'best' (Axes only) 0 + 'upper right' 1 + 'upper left' 2 + 'lower left' 3 + 'lower right' 4 + 'right' 5 + 'center left' 6 + 'center right' 7 + 'lower center' 8 + 'upper center' 9 + 'center' 10 + ================== ============= + + If a figure is using the constrained layout manager, the string codes + of the *loc* keyword argument can get better layout behaviour using the + prefix 'outside'. There is ambiguity at the corners, so 'outside + upper right' will make space for the legend above the rest of the + axes in the layout, and 'outside right upper' will make space on the + right side of the layout. In addition to the values of *loc* + listed above, we have 'outside right upper', 'outside right lower', + 'outside left upper', and 'outside left lower'. See + :ref:`legend_guide` for more details. + +bbox_to_anchor : `.BboxBase`, 2-tuple, or 4-tuple of floats + Box that is used to position the legend in conjunction with *loc*. + Defaults to ``axes.bbox`` (if called as a method to `.Axes.legend`) or + ``figure.bbox`` (if ``figure.legend``). This argument allows arbitrary + placement of the legend. + + Bbox coordinates are interpreted in the coordinate system given by + *bbox_transform*, with the default transform + Axes or Figure coordinates, depending on which ``legend`` is called. + + If a 4-tuple or `.BboxBase` is given, then it specifies the bbox + ``(x, y, width, height)`` that the legend is placed in. + To put the legend in the best location in the bottom right + quadrant of the Axes (or figure):: + + loc='best', bbox_to_anchor=(0.5, 0., 0.5, 0.5) + + A 2-tuple ``(x, y)`` places the corner of the legend specified by *loc* at + x, y. For example, to put the legend's upper right-hand corner in the + center of the Axes (or figure) the following keywords can be used:: + + loc='upper right', bbox_to_anchor=(0.5, 0.5) + +ncols : int, default: 1 + The number of columns that the legend has. + + For backward compatibility, the spelling *ncol* is also supported + but it is discouraged. If both are given, *ncols* takes precedence. + +prop : None or `~matplotlib.font_manager.FontProperties` or dict + The font properties of the legend. If None (default), the current + :data:`matplotlib.rcParams` will be used. + +fontsize : int or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'} + The font size of the legend. If the value is numeric the size will be the + absolute font size in points. String values are relative to the current + default font size. This argument is only used if *prop* is not specified. + +labelcolor : str or list, default: :rc:`legend.labelcolor` + The color of the text in the legend. Either a valid color string + (for example, 'red'), or a list of color strings. The labelcolor can + also be made to match the color of the line or marker using 'linecolor', + 'markerfacecolor' (or 'mfc'), or 'markeredgecolor' (or 'mec'). + + Labelcolor can be set globally using :rc:`legend.labelcolor`. If None, + use :rc:`text.color`. + +numpoints : int, default: :rc:`legend.numpoints` + The number of marker points in the legend when creating a legend + entry for a `.Line2D` (line). + +scatterpoints : int, default: :rc:`legend.scatterpoints` + The number of marker points in the legend when creating + a legend entry for a `.PathCollection` (scatter plot). + +scatteryoffsets : iterable of floats, default: ``[0.375, 0.5, 0.3125]`` + The vertical offset (relative to the font size) for the markers + created for a scatter plot legend entry. 0.0 is at the base the + legend text, and 1.0 is at the top. To draw all markers at the + same height, set to ``[0.5]``. + +markerscale : float, default: :rc:`legend.markerscale` + The relative size of legend markers compared to the originally drawn ones. + +markerfirst : bool, default: True + If *True*, legend marker is placed to the left of the legend label. + If *False*, legend marker is placed to the right of the legend label. + +reverse : bool, default: False + If *True*, the legend labels are displayed in reverse order from the input. + If *False*, the legend labels are displayed in the same order as the input. + + .. versionadded:: 3.7 + +frameon : bool, default: :rc:`legend.frameon` + Whether the legend should be drawn on a patch (frame). + +fancybox : bool, default: :rc:`legend.fancybox` + Whether round edges should be enabled around the `.FancyBboxPatch` which + makes up the legend's background. + +shadow : None, bool or dict, default: :rc:`legend.shadow` + Whether to draw a shadow behind the legend. + The shadow can be configured using `.Patch` keywords. + Customization via :rc:`legend.shadow` is currently not supported. + +framealpha : float, default: :rc:`legend.framealpha` + The alpha transparency of the legend's background. + If *shadow* is activated and *framealpha* is ``None``, the default value is + ignored. + +facecolor : "inherit" or color, default: :rc:`legend.facecolor` + The legend's background color. + If ``"inherit"``, use :rc:`axes.facecolor`. + +edgecolor : "inherit" or color, default: :rc:`legend.edgecolor` + The legend's background patch edge color. + If ``"inherit"``, use :rc:`axes.edgecolor`. + +mode : {"expand", None} + If *mode* is set to ``"expand"`` the legend will be horizontally + expanded to fill the Axes area (or *bbox_to_anchor* if defines + the legend's size). + +bbox_transform : None or `~matplotlib.transforms.Transform` + The transform for the bounding box (*bbox_to_anchor*). For a value + of ``None`` (default) the Axes' + :data:`~matplotlib.axes.Axes.transAxes` transform will be used. + +title : str or None + The legend's title. Default is no title (``None``). + +title_fontproperties : None or `~matplotlib.font_manager.FontProperties` or dict + The font properties of the legend's title. If None (default), the + *title_fontsize* argument will be used if present; if *title_fontsize* is + also None, the current :rc:`legend.title_fontsize` will be used. + +title_fontsize : int or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}, default: :rc:`legend.title_fontsize` + The font size of the legend's title. + Note: This cannot be combined with *title_fontproperties*. If you want + to set the fontsize alongside other font properties, use the *size* + parameter in *title_fontproperties*. + +alignment : {'center', 'left', 'right'}, default: 'center' + The alignment of the legend title and the box of entries. The entries + are aligned as a single block, so that markers always lined up. + +borderpad : float, default: :rc:`legend.borderpad` + The fractional whitespace inside the legend border, in font-size units. + +labelspacing : float, default: :rc:`legend.labelspacing` + The vertical space between the legend entries, in font-size units. + +handlelength : float, default: :rc:`legend.handlelength` + The length of the legend handles, in font-size units. + +handleheight : float, default: :rc:`legend.handleheight` + The height of the legend handles, in font-size units. + +handletextpad : float, default: :rc:`legend.handletextpad` + The pad between the legend handle and text, in font-size units. + +borderaxespad : float, default: :rc:`legend.borderaxespad` + The pad between the Axes and legend border, in font-size units. + +columnspacing : float, default: :rc:`legend.columnspacing` + The spacing between columns, in font-size units. + +handler_map : dict or None + The custom dictionary mapping instances or types to a legend + handler. This *handler_map* updates the default handler map + found at `matplotlib.legend.Legend.get_legend_handler_map`. + +draggable : bool, default: False + Whether the legend can be dragged with the mouse. + + +Attributes +---------- +legend_handles + List of `.Artist` objects added as legend entries. + + .. versionadded:: 3.7""" ... @classmethod @@ -388,6 +759,64 @@ class Legend(mlegend.Legend): @override def set_loc(self, loc: Incomplete=None) -> Incomplete: + """Set the location of the legend. + +.. versionadded:: 3.8 + +Parameters +---------- + +loc : str or pair of floats, default: :rc:`legend.loc` for Axes, 'upper right' for Figure + The location of the legend. + + The strings ``'upper left'``, ``'upper right'``, ``'lower left'``, + ``'lower right'`` place the legend at the corresponding corner of the + axes/figure. + + The strings ``'upper center'``, ``'lower center'``, ``'center left'``, + ``'center right'`` place the legend at the center of the corresponding edge + of the axes/figure. + + The string ``'center'`` places the legend at the center of the axes/figure. + + The string ``'best'`` places the legend at the location, among the nine + locations defined so far, with the minimum overlap with other drawn + artists. This option can be quite slow for plots with large amounts of + data; your plotting speed may benefit from providing a specific location. + + The location can also be a 2-tuple giving the coordinates of the lower-left + corner of the legend in axes/figure coordinates (in which case *bbox_to_anchor* + will be ignored). + + For back-compatibility, ``'center right'`` (but no other location) can also + be spelled ``'right'``, and each "string" location can also be given as a + numeric value: + + ================== ============= + Location String Location Code + ================== ============= + 'best' (Axes only) 0 + 'upper right' 1 + 'upper left' 2 + 'lower left' 3 + 'lower right' 4 + 'right' 5 + 'center left' 6 + 'center right' 7 + 'lower center' 8 + 'upper center' 9 + 'center' 10 + ================== ============= + + If a figure is using the constrained layout manager, the string codes + of the *loc* keyword argument can get better layout behaviour using the + prefix 'outside'. There is ambiguity at the corners, so 'outside + upper right' will make space for the legend above the rest of the + axes in the layout, and 'outside right upper' will make space on the + right side of the layout. In addition to the values of *loc* + listed above, we have 'outside right upper', 'outside right lower', + 'outside left upper', and 'outside left lower'. See + :ref:`legend_guide` for more details.""" ... def remove(self) -> None: @@ -409,11 +838,10 @@ _semantic_num_style_kwargs_docstring = ... _semantic_handle_kw_docstring = ... class UltraLegend: - """ - Centralized legend builder for axes. - """ + """Centralized legend builder for axes.""" def __init__(self, axes: Incomplete) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... @staticmethod diff --git a/ultraplot/proj.pyi b/ultraplot/proj.pyi index 3b1b61687..a3024adce 100644 --- a/ultraplot/proj.pyi +++ b/ultraplot/proj.pyi @@ -17,9 +17,7 @@ _reso_docstring = ... _init_docstring = ... class Aitoff(_WarpedRectangularProjection): - """ - The `Aitoff `__ projection. - """ + """The `Aitoff `__ projection.""" name = 'aitoff' def __init__(self, central_longitude: Incomplete=0, globe: Incomplete=None, false_easting: Incomplete=None, false_northing: Incomplete=None) -> None: @@ -41,9 +39,7 @@ globe : `~cartopy.crs.Globe`, optional ... class Hammer(_WarpedRectangularProjection): - """ - The `Hammer `__ projection. - """ + """The `Hammer `__ projection.""" name = 'hammer' def __init__(self, central_longitude: Incomplete=0, globe: Incomplete=None, false_easting: Incomplete=None, false_northing: Incomplete=None) -> None: @@ -65,9 +61,7 @@ globe : `~cartopy.crs.Globe`, optional ... class KavrayskiyVII(_WarpedRectangularProjection): - """ - The `Kavrayskiy VII `__ projection. - """ + """The `Kavrayskiy VII `__ projection.""" name = 'kavrayskiyVII' def __init__(self, central_longitude: Incomplete=0, globe: Incomplete=None, false_easting: Incomplete=None, false_northing: Incomplete=None) -> None: @@ -89,9 +83,7 @@ globe : `~cartopy.crs.Globe`, optional ... class WinkelTripel(_WarpedRectangularProjection): - """ - The `Winkel tripel (Winkel III) `__ projection. - """ + """The `Winkel tripel (Winkel III) `__ projection.""" name = 'winkeltripel' def __init__(self, central_longitude: Incomplete=0, globe: Incomplete=None, false_easting: Incomplete=None, false_northing: Incomplete=None) -> None: @@ -113,9 +105,7 @@ globe : `~cartopy.crs.Globe`, optional ... class NorthPolarAzimuthalEquidistant(AzimuthalEquidistant): - """ - Analogous to `~cartopy.crs.NorthPolarStereo`. - """ + """Analogous to `~cartopy.crs.NorthPolarStereo`.""" def __init__(self, central_longitude: Incomplete=0.0, globe: Incomplete=None) -> None: """Parameters @@ -131,9 +121,7 @@ globe : `~cartopy.crs.Globe`, optional ... class SouthPolarAzimuthalEquidistant(AzimuthalEquidistant): - """ - Analogous to `~cartopy.crs.SouthPolarStereo`. - """ + """Analogous to `~cartopy.crs.SouthPolarStereo`.""" def __init__(self, central_longitude: Incomplete=0.0, globe: Incomplete=None) -> None: """Parameters @@ -149,9 +137,7 @@ globe : `~cartopy.crs.Globe`, optional ... class NorthPolarLambertAzimuthalEqualArea(LambertAzimuthalEqualArea): - """ - Analogous to `~cartopy.crs.NorthPolarStereo`. - """ + """Analogous to `~cartopy.crs.NorthPolarStereo`.""" def __init__(self, central_longitude: Incomplete=0.0, globe: Incomplete=None) -> None: """Parameters @@ -167,9 +153,7 @@ globe : `~cartopy.crs.Globe`, optional ... class SouthPolarLambertAzimuthalEqualArea(LambertAzimuthalEqualArea): - """ - Analogous to `~cartopy.crs.SouthPolarStereo`. - """ + """Analogous to `~cartopy.crs.SouthPolarStereo`.""" def __init__(self, central_longitude: Incomplete=0.0, globe: Incomplete=None) -> None: """Parameters @@ -185,9 +169,7 @@ globe : `~cartopy.crs.Globe`, optional ... class NorthPolarGnomonic(Gnomonic): - """ - Analogous to `~cartopy.crs.NorthPolarStereo`. - """ + """Analogous to `~cartopy.crs.NorthPolarStereo`.""" def __init__(self, central_longitude: Incomplete=0.0, globe: Incomplete=None) -> None: """Parameters @@ -203,9 +185,7 @@ globe : `~cartopy.crs.Globe`, optional ... class SouthPolarGnomonic(Gnomonic): - """ - Analogous to `~cartopy.crs.SouthPolarStereo`. - """ + """Analogous to `~cartopy.crs.SouthPolarStereo`.""" def __init__(self, central_longitude: Incomplete=0.0, globe: Incomplete=None) -> None: """Parameters diff --git a/ultraplot/scale.pyi b/ultraplot/scale.pyi index 653bbb3ea..1cfc9893d 100644 --- a/ultraplot/scale.pyi +++ b/ultraplot/scale.pyi @@ -21,15 +21,14 @@ change the default `linthresh` to ``1``.""" ... class _Scale(object): - """ - Mix-in class that standardizes the behavior of - `~matplotlib.scale.ScaleBase.set_default_locators_and_formatters` - and `~matplotlib.scale.ScaleBase.get_transform`. Also overrides - `__init__` so you no longer have to instantiate scales with an - `~matplotlib.axis.Axis` instance. - """ + """Mix-in class that standardizes the behavior of +`~matplotlib.scale.ScaleBase.set_default_locators_and_formatters` +and `~matplotlib.scale.ScaleBase.get_transform`. Also overrides +`__init__` so you no longer have to instantiate scales with an +`~matplotlib.axis.Axis` instance.""" def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def set_default_locators_and_formatters(self, axis: Incomplete, only_if_default: Incomplete=False) -> Incomplete: @@ -51,10 +50,8 @@ only_if_default : bool, optional ... class LinearScale(_Scale, mscale.LinearScale): - """ - As with `~matplotlib.scale.LinearScale` but with - `~ultraplot.ticker.AutoFormatter` as the default major formatter. - """ + """As with `~matplotlib.scale.LinearScale` but with +`~ultraplot.ticker.AutoFormatter` as the default major formatter.""" name = 'linear' def __init__(self, **kwargs: Incomplete) -> None: @@ -64,10 +61,8 @@ ultraplot.constructor.Scale""" ... class LogitScale(_Scale, mscale.LogitScale): - """ - As with `~matplotlib.scale.LogitScale` but with `~ultraplot.ticker.AutoFormatter` - as the default major formatter. - """ + """As with `~matplotlib.scale.LogitScale` but with `~ultraplot.ticker.AutoFormatter` +as the default major formatter.""" name = 'logit' def __init__(self, **kwargs: Incomplete) -> None: @@ -83,11 +78,9 @@ ultraplot.constructor.Scale""" ... class LogScale(_Scale, mscale.LogScale): - """ - As with `~matplotlib.scale.LogScale` but with `~ultraplot.ticker.AutoFormatter` - as the default major formatter. `x` and `y` versions of each keyword - argument are no longer required. - """ + """As with `~matplotlib.scale.LogScale` but with `~ultraplot.ticker.AutoFormatter` +as the default major formatter. `x` and `y` versions of each keyword +argument are no longer required.""" name = 'log' def __init__(self, **kwargs: Incomplete) -> None: @@ -112,12 +105,10 @@ ultraplot.constructor.Scale""" ... class SymmetricalLogScale(_Scale, mscale.SymmetricalLogScale): - """ - As with `~matplotlib.scale.SymmetricalLogScale` but with - `~ultraplot.ticker.AutoFormatter` as the default major formatter. - `x` and `y` versions of each keyword argument are no longer - required. - """ + """As with `~matplotlib.scale.SymmetricalLogScale` but with +`~ultraplot.ticker.AutoFormatter` as the default major formatter. +`x` and `y` versions of each keyword argument are no longer +required.""" name = 'symlog' def __init__(self, **kwargs: Incomplete) -> None: @@ -149,9 +140,7 @@ ultraplot.constructor.Scale""" ... class FuncScale(_Scale, mscale.ScaleBase): - """ - Axis scale composed of arbitrary forward and inverse transformations. - """ + """Axis scale composed of arbitrary forward and inverse transformations.""" name = 'function' def __init__(self, transform: Incomplete=None, invert: Incomplete=False, parent_scale: Incomplete=None, **kwargs: Incomplete) -> None: @@ -208,23 +197,53 @@ class FuncTransform(mtransforms.Transform): has_inverse = True def __init__(self, forward: Incomplete, inverse: Incomplete) -> None: + """Parameters +---------- +shorthand_name : str + A string representing the "name" of the transform. The name carries + no significance other than to improve the readability of + ``str(transform)`` when DEBUG=True.""" ... def inverted(self) -> Incomplete: + """Return the corresponding inverse transformation. + +It holds ``x == self.inverted().transform(self.transform(x))``. + +The return value of this method should be treated as +temporary. An update to *self* does not cause a corresponding +update to its inverted copy.""" ... def transform_non_affine(self, values: Incomplete) -> Incomplete: + """Apply only the non-affine part of this transformation. + +``transform(values)`` is always equivalent to +``transform_affine(transform_non_affine(values))``. + +In non-affine transformations, this is generally equivalent to +``transform(values)``. In affine transformations, this is +always a no-op. + +Parameters +---------- +values : array + The input values as an array of length :attr:`input_dims` or + shape (N, :attr:`input_dims`). + +Returns +------- +array + The output values as an array of length :attr:`output_dims` or + shape (N, :attr:`output_dims`), depending on the input.""" ... class PowerScale(_Scale, mscale.ScaleBase): - """ - "Power scale" that performs the transformation - - .. math:: + """"Power scale" that performs the transformation - x^{c} +.. math:: - """ + x^{c}""" name = 'power' def __init__(self, power: Incomplete=1, inverse: Incomplete=False) -> None: @@ -247,12 +266,45 @@ class PowerTransform(mtransforms.Transform): is_separable = True def __init__(self, power: Incomplete) -> None: + """Parameters +---------- +shorthand_name : str + A string representing the "name" of the transform. The name carries + no significance other than to improve the readability of + ``str(transform)`` when DEBUG=True.""" ... def inverted(self) -> Incomplete: + """Return the corresponding inverse transformation. + +It holds ``x == self.inverted().transform(self.transform(x))``. + +The return value of this method should be treated as +temporary. An update to *self* does not cause a corresponding +update to its inverted copy.""" ... def transform_non_affine(self, a: Incomplete) -> Incomplete: + """Apply only the non-affine part of this transformation. + +``transform(values)`` is always equivalent to +``transform_affine(transform_non_affine(values))``. + +In non-affine transformations, this is generally equivalent to +``transform(values)``. In affine transformations, this is +always a no-op. + +Parameters +---------- +values : array + The input values as an array of length :attr:`input_dims` or + shape (N, :attr:`input_dims`). + +Returns +------- +array + The output values as an array of length :attr:`output_dims` or + shape (N, :attr:`output_dims`), depending on the input.""" ... class InvertedPowerTransform(mtransforms.Transform): @@ -262,34 +314,65 @@ class InvertedPowerTransform(mtransforms.Transform): is_separable = True def __init__(self, power: Incomplete) -> None: + """Parameters +---------- +shorthand_name : str + A string representing the "name" of the transform. The name carries + no significance other than to improve the readability of + ``str(transform)`` when DEBUG=True.""" ... def inverted(self) -> Incomplete: + """Return the corresponding inverse transformation. + +It holds ``x == self.inverted().transform(self.transform(x))``. + +The return value of this method should be treated as +temporary. An update to *self* does not cause a corresponding +update to its inverted copy.""" ... def transform_non_affine(self, a: Incomplete) -> Incomplete: + """Apply only the non-affine part of this transformation. + +``transform(values)`` is always equivalent to +``transform_affine(transform_non_affine(values))``. + +In non-affine transformations, this is generally equivalent to +``transform(values)``. In affine transformations, this is +always a no-op. + +Parameters +---------- +values : array + The input values as an array of length :attr:`input_dims` or + shape (N, :attr:`input_dims`). + +Returns +------- +array + The output values as an array of length :attr:`output_dims` or + shape (N, :attr:`output_dims`), depending on the input.""" ... class ExpScale(_Scale, mscale.ScaleBase): - """ - "Exponential scale" that performs either of two transformations. When - `inverse` is ``False`` (the default), performs the transformation + """"Exponential scale" that performs either of two transformations. When +`inverse` is ``False`` (the default), performs the transformation - .. math:: +.. math:: - Ca^{bx} + Ca^{bx} - where the constants :math:`a`, :math:`b`, and :math:`C` are set by the - input (see below). When `inverse` is ``True``, this performs the inverse - transformation +where the constants :math:`a`, :math:`b`, and :math:`C` are set by the +input (see below). When `inverse` is ``True``, this performs the inverse +transformation - .. math:: +.. math:: - (\\log_a(x) - \\log_a(C))/b + (\\log_a(x) - \\log_a(C))/b - which in appearance is equivalent to `LogScale` since it is just a linear - transformation of the logarithm. - """ +which in appearance is equivalent to `LogScale` since it is just a linear +transformation of the logarithm.""" name = 'exp' def __init__(self, a: Incomplete=np.e, b: Incomplete=1, c: Incomplete=1, inverse: Incomplete=False) -> None: @@ -320,12 +403,45 @@ class ExpTransform(mtransforms.Transform): is_separable = True def __init__(self, a: Incomplete, b: Incomplete, c: Incomplete) -> None: + """Parameters +---------- +shorthand_name : str + A string representing the "name" of the transform. The name carries + no significance other than to improve the readability of + ``str(transform)`` when DEBUG=True.""" ... def inverted(self) -> Incomplete: + """Return the corresponding inverse transformation. + +It holds ``x == self.inverted().transform(self.transform(x))``. + +The return value of this method should be treated as +temporary. An update to *self* does not cause a corresponding +update to its inverted copy.""" ... def transform_non_affine(self, a: Incomplete) -> Incomplete: + """Apply only the non-affine part of this transformation. + +``transform(values)`` is always equivalent to +``transform_affine(transform_non_affine(values))``. + +In non-affine transformations, this is generally equivalent to +``transform(values)``. In affine transformations, this is +always a no-op. + +Parameters +---------- +values : array + The input values as an array of length :attr:`input_dims` or + shape (N, :attr:`input_dims`). + +Returns +------- +array + The output values as an array of length :attr:`output_dims` or + shape (N, :attr:`output_dims`), depending on the input.""" ... class InvertedExpTransform(mtransforms.Transform): @@ -335,30 +451,60 @@ class InvertedExpTransform(mtransforms.Transform): is_separable = True def __init__(self, a: Incomplete, b: Incomplete, c: Incomplete) -> None: + """Parameters +---------- +shorthand_name : str + A string representing the "name" of the transform. The name carries + no significance other than to improve the readability of + ``str(transform)`` when DEBUG=True.""" ... def inverted(self) -> Incomplete: + """Return the corresponding inverse transformation. + +It holds ``x == self.inverted().transform(self.transform(x))``. + +The return value of this method should be treated as +temporary. An update to *self* does not cause a corresponding +update to its inverted copy.""" ... def transform_non_affine(self, a: Incomplete) -> Incomplete: + """Apply only the non-affine part of this transformation. + +``transform(values)`` is always equivalent to +``transform_affine(transform_non_affine(values))``. + +In non-affine transformations, this is generally equivalent to +``transform(values)``. In affine transformations, this is +always a no-op. + +Parameters +---------- +values : array + The input values as an array of length :attr:`input_dims` or + shape (N, :attr:`input_dims`). + +Returns +------- +array + The output values as an array of length :attr:`output_dims` or + shape (N, :attr:`output_dims`), depending on the input.""" ... class MercatorLatitudeScale(_Scale, mscale.ScaleBase): - """ - Axis scale that is linear in the `Mercator projection latitude `__. Adapted from `this example `__. - The scale function is as follows: - - .. math:: + """Axis scale that is linear in the `Mercator projection latitude `__. Adapted from `this example `__. +The scale function is as follows: - y = \\ln(\\tan(\\pi x \\,/\\, 180) + \\sec(\\pi x \\,/\\, 180)) +.. math:: - The inverse scale function is as follows: + y = \\ln(\\tan(\\pi x \\,/\\, 180) + \\sec(\\pi x \\,/\\, 180)) - .. math:: +The inverse scale function is as follows: - x = 180\\,\\arctan(\\sinh(y)) \\,/\\, \\pi +.. math:: - """ + x = 180\\,\\arctan(\\sinh(y)) \\,/\\, \\pi""" name = 'mercator' def __init__(self, thresh: Incomplete=85.0) -> None: @@ -385,12 +531,45 @@ class MercatorLatitudeTransform(mtransforms.Transform): has_inverse = True def __init__(self, thresh: Incomplete) -> None: + """Parameters +---------- +shorthand_name : str + A string representing the "name" of the transform. The name carries + no significance other than to improve the readability of + ``str(transform)`` when DEBUG=True.""" ... def inverted(self) -> Incomplete: + """Return the corresponding inverse transformation. + +It holds ``x == self.inverted().transform(self.transform(x))``. + +The return value of this method should be treated as +temporary. An update to *self* does not cause a corresponding +update to its inverted copy.""" ... def transform_non_affine(self, a: Incomplete) -> Incomplete: + """Apply only the non-affine part of this transformation. + +``transform(values)`` is always equivalent to +``transform_affine(transform_non_affine(values))``. + +In non-affine transformations, this is generally equivalent to +``transform(values)``. In affine transformations, this is +always a no-op. + +Parameters +---------- +values : array + The input values as an array of length :attr:`input_dims` or + shape (N, :attr:`input_dims`). + +Returns +------- +array + The output values as an array of length :attr:`output_dims` or + shape (N, :attr:`output_dims`), depending on the input.""" ... class InvertedMercatorLatitudeTransform(mtransforms.Transform): @@ -400,30 +579,61 @@ class InvertedMercatorLatitudeTransform(mtransforms.Transform): has_inverse = True def __init__(self, thresh: Incomplete) -> None: + """Parameters +---------- +shorthand_name : str + A string representing the "name" of the transform. The name carries + no significance other than to improve the readability of + ``str(transform)`` when DEBUG=True.""" ... def inverted(self) -> Incomplete: + """Return the corresponding inverse transformation. + +It holds ``x == self.inverted().transform(self.transform(x))``. + +The return value of this method should be treated as +temporary. An update to *self* does not cause a corresponding +update to its inverted copy.""" ... def transform_non_affine(self, a: Incomplete) -> Incomplete: + """Apply only the non-affine part of this transformation. + +``transform(values)`` is always equivalent to +``transform_affine(transform_non_affine(values))``. + +In non-affine transformations, this is generally equivalent to +``transform(values)``. In affine transformations, this is +always a no-op. + +Parameters +---------- +values : array + The input values as an array of length :attr:`input_dims` or + shape (N, :attr:`input_dims`). + +Returns +------- +array + The output values as an array of length :attr:`output_dims` or + shape (N, :attr:`output_dims`), depending on the input.""" ... class SineLatitudeScale(_Scale, mscale.ScaleBase): - """ - Axis scale that is linear in the sine transformation of *x*. The axis - limits are constrained to fall between ``-90`` and ``+90`` degrees. - The scale function is as follows: + """Axis scale that is linear in the sine transformation of *x*. The axis +limits are constrained to fall between ``-90`` and ``+90`` degrees. +The scale function is as follows: - .. math:: +.. math:: - y = \\sin(\\pi x/180) + y = \\sin(\\pi x/180) - The inverse scale function is as follows: +The inverse scale function is as follows: - .. math:: +.. math:: - x = 180\\arcsin(y)/\\pi - """ + x = 180\\arcsin(y)/\\pi""" name = 'sine' def __init__(self) -> None: @@ -444,12 +654,45 @@ class SineLatitudeTransform(mtransforms.Transform): has_inverse = True def __init__(self) -> None: + """Parameters +---------- +shorthand_name : str + A string representing the "name" of the transform. The name carries + no significance other than to improve the readability of + ``str(transform)`` when DEBUG=True.""" ... def inverted(self) -> Incomplete: + """Return the corresponding inverse transformation. + +It holds ``x == self.inverted().transform(self.transform(x))``. + +The return value of this method should be treated as +temporary. An update to *self* does not cause a corresponding +update to its inverted copy.""" ... def transform_non_affine(self, a: Incomplete) -> Incomplete: + """Apply only the non-affine part of this transformation. + +``transform(values)`` is always equivalent to +``transform_affine(transform_non_affine(values))``. + +In non-affine transformations, this is generally equivalent to +``transform(values)``. In affine transformations, this is +always a no-op. + +Parameters +---------- +values : array + The input values as an array of length :attr:`input_dims` or + shape (N, :attr:`input_dims`). + +Returns +------- +array + The output values as an array of length :attr:`output_dims` or + shape (N, :attr:`output_dims`), depending on the input.""" ... class InvertedSineLatitudeTransform(mtransforms.Transform): @@ -459,20 +702,51 @@ class InvertedSineLatitudeTransform(mtransforms.Transform): has_inverse = True def __init__(self) -> None: + """Parameters +---------- +shorthand_name : str + A string representing the "name" of the transform. The name carries + no significance other than to improve the readability of + ``str(transform)`` when DEBUG=True.""" ... def inverted(self) -> Incomplete: + """Return the corresponding inverse transformation. + +It holds ``x == self.inverted().transform(self.transform(x))``. + +The return value of this method should be treated as +temporary. An update to *self* does not cause a corresponding +update to its inverted copy.""" ... def transform_non_affine(self, a: Incomplete) -> Incomplete: + """Apply only the non-affine part of this transformation. + +``transform(values)`` is always equivalent to +``transform_affine(transform_non_affine(values))``. + +In non-affine transformations, this is generally equivalent to +``transform(values)``. In affine transformations, this is +always a no-op. + +Parameters +---------- +values : array + The input values as an array of length :attr:`input_dims` or + shape (N, :attr:`input_dims`). + +Returns +------- +array + The output values as an array of length :attr:`output_dims` or + shape (N, :attr:`output_dims`), depending on the input.""" ... class CutoffScale(_Scale, mscale.ScaleBase): - """ - Axis scale composed of arbitrary piecewise linear transformations. - The axis can undergo discrete jumps, "accelerations", or "decelerations" - between successive thresholds. - """ + """Axis scale composed of arbitrary piecewise linear transformations. +The axis can undergo discrete jumps, "accelerations", or "decelerations" +between successive thresholds.""" name = 'cutoff' def __init__(self, *args: Incomplete) -> None: @@ -514,24 +788,54 @@ class CutoffTransform(mtransforms.Transform): is_separable = True def __init__(self, threshs: Incomplete, scales: Incomplete, zero_dists: Incomplete=None) -> None: + """Parameters +---------- +shorthand_name : str + A string representing the "name" of the transform. The name carries + no significance other than to improve the readability of + ``str(transform)`` when DEBUG=True.""" ... def inverted(self) -> Incomplete: + """Return the corresponding inverse transformation. + +It holds ``x == self.inverted().transform(self.transform(x))``. + +The return value of this method should be treated as +temporary. An update to *self* does not cause a corresponding +update to its inverted copy.""" ... def transform_non_affine(self, a: Incomplete) -> Incomplete: + """Apply only the non-affine part of this transformation. + +``transform(values)`` is always equivalent to +``transform_affine(transform_non_affine(values))``. + +In non-affine transformations, this is generally equivalent to +``transform(values)``. In affine transformations, this is +always a no-op. + +Parameters +---------- +values : array + The input values as an array of length :attr:`input_dims` or + shape (N, :attr:`input_dims`). + +Returns +------- +array + The output values as an array of length :attr:`output_dims` or + shape (N, :attr:`output_dims`), depending on the input.""" ... class InverseScale(_Scale, mscale.ScaleBase): - """ - Axis scale that is linear in the *inverse* of *x*. The forward and inverse - scale functions are as follows: - - .. math:: + """Axis scale that is linear in the *inverse* of *x*. The forward and inverse +scale functions are as follows: - y = x^{-1} +.. math:: - """ + y = x^{-1}""" name = 'inverse' def __init__(self) -> None: @@ -551,12 +855,45 @@ class InverseTransform(mtransforms.Transform): has_inverse = True def __init__(self) -> None: + """Parameters +---------- +shorthand_name : str + A string representing the "name" of the transform. The name carries + no significance other than to improve the readability of + ``str(transform)`` when DEBUG=True.""" ... def inverted(self) -> Incomplete: + """Return the corresponding inverse transformation. + +It holds ``x == self.inverted().transform(self.transform(x))``. + +The return value of this method should be treated as +temporary. An update to *self* does not cause a corresponding +update to its inverted copy.""" ... def transform_non_affine(self, a: Incomplete) -> Incomplete: + """Apply only the non-affine part of this transformation. + +``transform(values)`` is always equivalent to +``transform_affine(transform_non_affine(values))``. + +In non-affine transformations, this is generally equivalent to +``transform(values)``. In affine transformations, this is +always a no-op. + +Parameters +---------- +values : array + The input values as an array of length :attr:`input_dims` or + shape (N, :attr:`input_dims`). + +Returns +------- +array + The output values as an array of length :attr:`output_dims` or + shape (N, :attr:`output_dims`), depending on the input.""" ... def _scale_factory(scale: Incomplete, axis: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: diff --git a/ultraplot/tests/test_stubs.py b/ultraplot/tests/test_stubs.py index 3d978009a..fe02f57a0 100644 --- a/ultraplot/tests/test_stubs.py +++ b/ultraplot/tests/test_stubs.py @@ -136,3 +136,48 @@ def test_root_stub_exposes_lazy_public_imports(): assert source_names assert not source_names - stub_names + + +def test_generated_stubs_include_runtime_docstrings(): + plot_stub = PACKAGE / "axes" / "plot.pyi" + plot_tree = ast.parse(plot_stub.read_text(encoding="utf-8")) + plot_doc = "" + for node in ast.walk(plot_tree): + if isinstance(node, ast.FunctionDef) and node.name == "plot": + plot_doc = ast.get_docstring(node) or "" + break + assert "Matplotlib documentation" in plot_doc + assert "Plot standard lines" in plot_doc + assert "=====================\nultraplot documentation" not in plot_doc + + grid_stub = PACKAGE / "gridspec.pyi" + grid_tree = ast.parse(grid_stub.read_text(encoding="utf-8")) + twiny_doc = "" + for node in ast.walk(grid_tree): + if isinstance(node, ast.FunctionDef) and node.name == "twiny": + twiny_doc = ast.get_docstring(node) or "" + break + assert "for every axes in the grid" in twiny_doc + + +def test_subplot_grid_stub_preserves_axes_indexing_chain(): + """Integer indexing must lead static analyzers from a grid to an axes.""" + grid_stub = PACKAGE / "gridspec.pyi" + tree = ast.parse(grid_stub.read_text(encoding="utf-8")) + grid = next( + node + for node in tree.body + if isinstance(node, ast.ClassDef) and node.name == "SubplotGrid" + ) + assert "paxes.PlotAxes" in {ast.unparse(base) for base in grid.bases} + getitems = [ + node + for node in grid.body + if isinstance(node, ast.FunctionDef) and node.name == "__getitem__" + ] + assert len(getitems) >= 2 + assert any( + ast.unparse(node.args.args[1].annotation) == "int" + and ast.unparse(node.returns) == "paxes.Axes" + for node in getitems + ) diff --git a/ultraplot/text.pyi b/ultraplot/text.pyi index f7495f27d..94db2be44 100644 --- a/ultraplot/text.pyi +++ b/ultraplot/text.pyi @@ -11,34 +11,91 @@ from .internals import labels __all__ = ['CurvedText'] class CurvedText(mtext.Text): - """ - A text object that follows an arbitrary curve. - - Parameters - ---------- - x, y : array-like - Curve coordinates. - text : str - Text to render along the curve. - axes : matplotlib.axes.Axes - Target axes. - upright : bool, default: True - Whether to flip the curve direction to keep text upright. - ellipsis : bool, default: False - Whether to show an ellipsis when the text exceeds curve length. - avoid_overlap : bool, default: True - Whether to hide glyphs that overlap after rotation. - overlap_tol : float, default: 0.1 - Fractional overlap area (0–1) required before hiding a glyph. - curvature_pad : float, default: 2.0 - Extra spacing in pixels per radian of local curvature. - min_advance : float, default: 1.0 - Minimum additional spacing (pixels) enforced between glyph centers. - **kwargs - Passed to `matplotlib.text.Text` for character styling. - """ + """A text object that follows an arbitrary curve. + +Parameters +---------- +x, y : array-like + Curve coordinates. +text : str + Text to render along the curve. +axes : matplotlib.axes.Axes + Target axes. +upright : bool, default: True + Whether to flip the curve direction to keep text upright. +ellipsis : bool, default: False + Whether to show an ellipsis when the text exceeds curve length. + avoid_overlap : bool, default: True + Whether to hide glyphs that overlap after rotation. +overlap_tol : float, default: 0.1 + Fractional overlap area (0–1) required before hiding a glyph. +curvature_pad : float, default: 2.0 + Extra spacing in pixels per radian of local curvature. +min_advance : float, default: 1.0 + Minimum additional spacing (pixels) enforced between glyph centers. +**kwargs + Passed to `matplotlib.text.Text` for character styling.""" def __init__(self, x: Incomplete, y: Incomplete, text: Incomplete, axes: Incomplete, *, upright: Incomplete=True, ellipsis: Incomplete=False, avoid_overlap: Incomplete=True, overlap_tol: Incomplete=0.1, curvature_pad: Incomplete=2.0, min_advance: Incomplete=1.0, **kwargs: Incomplete) -> None: + """Create a `.Text` instance at *x*, *y* with string *text*. + +The text is aligned relative to the anchor point (*x*, *y*) according +to ``horizontalalignment`` (default: 'left') and ``verticalalignment`` +(default: 'baseline'). See also +:doc:`/gallery/text_labels_and_annotations/text_alignment`. + +While Text accepts the 'label' keyword argument, by default it is not +added to the handles of a legend. + +Valid keyword arguments are: + +Properties: + agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image + alpha: float or None + animated: bool + antialiased: bool + backgroundcolor: :mpltype:`color` + bbox: dict with properties for `.patches.FancyBboxPatch` + clip_box: unknown + clip_on: unknown + clip_path: unknown + color or c: :mpltype:`color` + figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + fontfamily or family or fontname: {FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'} + fontproperties or font or font_properties: `.font_manager.FontProperties` or `str` or `pathlib.Path` + fontsize or size: float or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'} + fontstretch or stretch: {a numeric value in range 0-1000, 'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', 'expanded', 'extra-expanded', 'ultra-expanded'} + fontstyle or style: {'normal', 'italic', 'oblique'} + fontvariant or variant: {'normal', 'small-caps'} + fontweight or weight: {a numeric value in range 0-1000, 'ultralight', 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black'} + gid: str + horizontalalignment or ha: {'left', 'center', 'right'} + in_layout: bool + label: object + linespacing: float (multiple of font size) + math_fontfamily: str + mouseover: bool + multialignment or ma: {'left', 'right', 'center'} + parse_math: bool + path_effects: list of `.AbstractPathEffect` + picker: None or bool or float or callable + position: (float, float) + rasterized: bool + rotation: float or {'vertical', 'horizontal'} + rotation_mode: {None, 'default', 'anchor'} + sketch_params: (scale: float, length: float, randomness: float) + snap: bool or None + text: object + transform: `~matplotlib.transforms.Transform` + transform_rotates_text: bool + url: str + usetex: bool, default: :rc:`text.usetex` + verticalalignment or va: {'baseline', 'bottom', 'center', 'center_baseline', 'top'} + visible: bool + wrap: bool + x: float + y: float + zorder: float""" ... def _restore_clip_on(self, t: Incomplete) -> None: @@ -49,9 +106,19 @@ class CurvedText(mtext.Text): ... def set_text(self, s: Incomplete) -> None: + """Set the text string *s*. + +It may contain newlines (``\\n``) or math in LaTeX syntax. + +Parameters +---------- +s : object + Any object gets converted to its `str` representation, except for + ``None`` which is converted to an empty string.""" ... def get_text(self) -> str: + """Return the text string.""" ... def set_curve(self, x: Iterable[float], y: Iterable[float]) -> None: @@ -64,9 +131,20 @@ class CurvedText(mtext.Text): ... def set_zorder(self, zorder: Incomplete) -> None: + """Set the zorder for the artist. Artists with lower zorder +values are drawn first. + +Parameters +---------- +level : float""" ... def set_transform(self, transform: Incomplete) -> None: + """Set the artist transform. + +Parameters +---------- +t : `~matplotlib.transforms.Transform`""" ... def draw(self, renderer: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> None: diff --git a/ultraplot/ticker.pyi b/ultraplot/ticker.pyi index 6fa4b1c66..9e1ebda73 100644 --- a/ultraplot/ticker.pyi +++ b/ultraplot/ticker.pyi @@ -42,31 +42,42 @@ def _default_precision_zerotrim(precision: Incomplete=None, zerotrim: Incomplete ... class IndexLocator(mticker.Locator): - """ - Format numbers by assigning fixed strings to non-negative indices. The ticks - are restricted to the extent of plotted content when content is present. - """ + """Format numbers by assigning fixed strings to non-negative indices. The ticks +are restricted to the extent of plotted content when content is present.""" def __init__(self, base: Incomplete=1, offset: Incomplete=0) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def set_params(self, base: Incomplete=None, offset: Incomplete=None) -> None: + """Do nothing, and raise a warning. Any locator class not supporting the +set_params() function will call this.""" ... def __call__(self) -> Incomplete: + """Return the locations of the ticks.""" ... def tick_values(self, vmin: Incomplete, vmax: Incomplete) -> Incomplete: + """Return the values of the located ticks given **vmin** and **vmax**. + +.. note:: + To get tick locations with the vmin and vmax values defined + automatically for the associated ``axis`` simply call + the Locator instance:: + + >>> print(type(loc)) + + >>> print(loc()) + [1, 2, 3, 4]""" ... class DiscreteLocator(mticker.Locator): - """ - A tick locator suitable for discretized colorbars. Adds ticks to some - subset of the location list depending on the available space determined from - `~matplotlib.axis.Axis.get_tick_space`. Zero will be used if it appears in the - location list, and step sizes along the location list are restricted to "nice" - intervals by default. - """ + """A tick locator suitable for discretized colorbars. Adds ticks to some +subset of the location list depending on the available space determined from +`~matplotlib.axis.Axis.get_tick_space`. Zero will be used if it appears in the +location list, and step sizes along the location list are restricted to "nice" +intervals by default.""" default_params = {'nbins': None, 'minor': False, 'steps': np.array([1, 2, 3, 4, 5, 6, 8, 10]), 'min_n_ticks': 2} def __init__(self, locs: Incomplete, **kwargs: Incomplete) -> None: @@ -100,10 +111,8 @@ min_n_ticks : int, default: 1 ... class DegreeLocator(mticker.MaxNLocator): - """ - Locate geographic gridlines with degree-minute-second support. - Adapted from cartopy. - """ + """Locate geographic gridlines with degree-minute-second support. +Adapted from cartopy.""" default_params = mticker.MaxNLocator.default_params.copy() def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: @@ -115,22 +124,40 @@ dms : bool, default: False ... def set_params(self, **kwargs: Incomplete) -> None: + """Set parameters for this locator. + +Parameters +---------- +nbins : int or 'auto', optional + see `.MaxNLocator` +steps : array-like, optional + see `.MaxNLocator` +integer : bool, optional + see `.MaxNLocator` +symmetric : bool, optional + see `.MaxNLocator` +prune : {'lower', 'upper', 'both', None}, optional + see `.MaxNLocator` +min_n_ticks : int, optional + see `.MaxNLocator`""" ... def _guess_steps(self, vmin: Incomplete, vmax: Incomplete) -> None: ... def _raw_ticks(self, vmin: Incomplete, vmax: Incomplete) -> Incomplete: + """Generate a list of tick locations including the range *vmin* to +*vmax*. In some applications, one or both of the end locations +will not be needed, in which case they are trimmed off +elsewhere.""" ... def bin_boundaries(self, vmin: Incomplete, vmax: Incomplete) -> Incomplete: ... class LongitudeLocator(DegreeLocator): - """ - Locate longitude gridlines with degree-minute-second support. - Adapted from cartopy. - """ + """Locate longitude gridlines with degree-minute-second support. +Adapted from cartopy.""" def __init__(self, lon0: Incomplete=0, *args: Incomplete, **kwargs: Incomplete) -> None: """Parameters @@ -148,10 +175,8 @@ lon0 : float, default=0 ... class LatitudeLocator(DegreeLocator): - """ - Locate latitude gridlines with degree-minute-second support. - Adapted from cartopy. - """ + """Locate latitude gridlines with degree-minute-second support. +Adapted from cartopy.""" def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: """Parameters @@ -162,19 +187,32 @@ dms : bool, default: False ... def tick_values(self, vmin: Incomplete, vmax: Incomplete) -> Incomplete: + """Return the values of the located ticks given **vmin** and **vmax**. + +.. note:: + To get tick locations with the vmin and vmax values defined + automatically for the associated ``axis`` simply call + the Locator instance:: + + >>> print(type(loc)) + + >>> print(loc()) + [1, 2, 3, 4]""" ... def _guess_steps(self, vmin: Incomplete, vmax: Incomplete) -> None: ... def _raw_ticks(self, vmin: Incomplete, vmax: Incomplete) -> Incomplete: + """Generate a list of tick locations including the range *vmin* to +*vmax*. In some applications, one or both of the end locations +will not be needed, in which case they are trimmed off +elsewhere.""" ... class AutoFormatter(mticker.ScalarFormatter): - """ - The default formatter used for ultraplot tick labels. - Replaces `~matplotlib.ticker.ScalarFormatter`. - """ + """The default formatter used for ultraplot tick labels. +Replaces `~matplotlib.ticker.ScalarFormatter`.""" def __init__(self, zerotrim: Incomplete=None, tickrange: Incomplete=None, wraprange: Incomplete=None, prefix: Incomplete=None, suffix: Incomplete=None, negpos: Incomplete=None, **kwargs: Incomplete) -> None: """Parameters @@ -279,11 +317,9 @@ from true floating point precision at which we want to limit string precision."" ... class SimpleFormatter(mticker.Formatter): - """ - A general purpose number formatter. This is similar to `AutoFormatter` - but suitable for arbitrary formatting not necessarily associated with - an `~matplotlib.axis.Axis` instance. - """ + """A general purpose number formatter. This is similar to `AutoFormatter` +but suitable for arbitrary formatting not necessarily associated with +an `~matplotlib.axis.Axis` instance.""" def __init__(self, precision: Incomplete=None, zerotrim: Incomplete=None, tickrange: Incomplete=None, wraprange: Incomplete=None, prefix: Incomplete=None, suffix: Incomplete=None, negpos: Incomplete=None) -> None: """Parameters @@ -324,21 +360,20 @@ pos : float, optional ... class IndexFormatter(mticker.Formatter): - """ - Format numbers by assigning fixed strings to non-negative indices. Generally - paired with `IndexLocator` or `~matplotlib.ticker.FixedLocator`. - """ + """Format numbers by assigning fixed strings to non-negative indices. Generally +paired with `IndexLocator` or `~matplotlib.ticker.FixedLocator`.""" def __init__(self, labels: Incomplete) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def __call__(self, x: Incomplete, pos: Incomplete=None) -> Incomplete: + """Return the format for tick value *x* at position pos. +``pos=None`` indicates an unspecified location.""" ... class SciFormatter(mticker.Formatter): - """ - Format numbers with scientific notation. - """ + """Format numbers with scientific notation.""" def __init__(self, precision: Incomplete=None, zerotrim: Incomplete=None) -> None: """Parameters @@ -367,9 +402,7 @@ pos : float, optional ... class SigFigFormatter(mticker.Formatter): - """ - Format numbers by retaining the specified number of significant digits. - """ + """Format numbers by retaining the specified number of significant digits.""" def __init__(self, sigfig: Incomplete=None, zerotrim: Incomplete=None, base: Incomplete=None) -> None: """Parameters @@ -400,10 +433,8 @@ pos : float, optional ... class FracFormatter(mticker.Formatter): - """ - Format numbers as integers or integer fractions. Optionally express the - values relative to some constant like `numpy.pi`. - """ + """Format numbers as integers or integer fractions. Optionally express the +values relative to some constant like `numpy.pi`.""" def __init__(self, symbol: Incomplete='', number: Incomplete=1) -> None: """Parameters @@ -436,9 +467,7 @@ pos : float, optional ... class CFDatetimeFormatter(mticker.Formatter): - """ - Format dates using `cftime.datetime.strftime` format strings. - """ + """Format dates using `cftime.datetime.strftime` format strings.""" def __init__(self, fmt: Incomplete, calendar: Incomplete='standard', units: Incomplete='days since 2000-01-01') -> None: """Parameters @@ -452,18 +481,23 @@ units : str, default: 'days since 2000-01-01' ... def __call__(self, x: Incomplete, pos: Incomplete=None) -> Incomplete: + """Return the format for tick value *x* at position pos. +``pos=None`` indicates an unspecified location.""" ... class AutoCFDatetimeFormatter(mticker.Formatter): """Automatic formatter for `cftime.datetime` data.""" def __init__(self, locator: Incomplete, calendar: Incomplete, time_units: Incomplete=None) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def pick_format(self, resolution: Incomplete) -> Incomplete: ... def __call__(self, x: Incomplete, pos: Incomplete=0) -> Incomplete: + """Return the format for tick value *x* at position pos. +``pos=None`` indicates an unspecified location.""" ... class AutoCFDatetimeLocator(mticker.Locator): @@ -474,6 +508,7 @@ class AutoCFDatetimeLocator(mticker.Locator): real_world_calendars = () def __init__(self, maxticks: Incomplete=None, calendar: Incomplete='standard', date_unit: Incomplete=None, minticks: Incomplete=3) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def set_params(self, maxticks: Incomplete=None, minticks: Incomplete=None, max_display_ticks: Incomplete=None) -> None: @@ -486,9 +521,21 @@ Also updates self.calendar from date1 for consistency.""" ... def __call__(self) -> Incomplete: + """Return the locations of the ticks.""" ... def tick_values(self, vmin: Incomplete, vmax: Incomplete) -> Incomplete: + """Return the values of the located ticks given **vmin** and **vmax**. + +.. note:: + To get tick locations with the vmin and vmax values defined + automatically for the associated ``axis`` simply call + the Locator instance:: + + >>> print(type(loc)) + + >>> print(loc()) + [1, 2, 3, 4]""" ... def _safe_num2date(self, value: Incomplete, vmax: Incomplete=None) -> Incomplete: @@ -520,21 +567,19 @@ it returns None.""" ... class _CartopyFormatter(object): - """ - Mixin class for cartopy formatters. - """ + """Mixin class for cartopy formatters.""" def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def __call__(self, value: Incomplete, pos: Incomplete=None) -> Incomplete: + """Call self as a function.""" ... class DegreeFormatter(_CartopyFormatter, _PlateCarreeFormatter): - """ - Formatter for longitude and latitude gridline labels. - Adapted from cartopy. - """ + """Formatter for longitude and latitude gridline labels. +Adapted from cartopy.""" def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: """Parameters @@ -545,17 +590,23 @@ dms : bool, default: False ... def _apply_transform(self, value: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Given a single value, a target projection and a source CRS, +transform the value from the source CRS to the target +projection, returning a single value.""" ... def _hemisphere(self, value: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + """Given both a tick value in the Plate Carree projection and the +same value in the source CRS, return a string indicating the +hemisphere that the value is in. + +Must be over-ridden by the derived class.""" ... class LongitudeFormatter(_CartopyFormatter, LongitudeFormatter): - """ - Format longitude gridline labels. Adapted from - `cartopy.mpl.ticker.LongitudeFormatter` with support for - proper centering based on lon0. - """ + """Format longitude gridline labels. Adapted from +`cartopy.mpl.ticker.LongitudeFormatter` with support for +proper centering based on lon0.""" def __init__(self, lon0: Incomplete=0, *args: Incomplete, **kwargs: Incomplete) -> None: """Parameters @@ -571,10 +622,8 @@ dms : bool, default: False ... class LatitudeFormatter(_CartopyFormatter, LatitudeFormatter): - """ - Format latitude gridline labels. Adapted from - `cartopy.mpl.ticker.LatitudeFormatter`. - """ + """Format latitude gridline labels. Adapted from +`cartopy.mpl.ticker.LatitudeFormatter`.""" def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: """Parameters @@ -585,9 +634,7 @@ dms : bool, default: False ... class CFTimeConverter(mdates.DateConverter): - """ - Converter for cftime.datetime data. - """ + """Converter for cftime.datetime data.""" @staticmethod def axisinfo(unit: Incomplete, axis: Incomplete) -> Incomplete: diff --git a/ultraplot/ui.py b/ultraplot/ui.py index 6a5a3136f..aa773502a 100644 --- a/ultraplot/ui.py +++ b/ultraplot/ui.py @@ -9,6 +9,7 @@ from . import figure as pfigure from . import gridspec as pgridspec from ._subplots import SubplotManager +from .figure import Figure from .internals import ( _not_none, _pop_params, @@ -125,7 +126,7 @@ def isinteractive(): @docstring._snippet_manager -def figure(**kwargs) -> pfigure.Figure: +def figure(**kwargs) -> Figure: """ Create an empty figure. Subplots can be subsequently added using `~ultraplot.figure.Figure.add_subplot` or `~ultraplot.figure.Figure.subplots`. @@ -153,7 +154,7 @@ def figure(**kwargs) -> pfigure.Figure: @docstring._snippet_manager -def subplot(**kwargs) -> tuple[pfigure.Figure, paxes.Axes]: +def subplot(**kwargs) -> tuple[Figure, paxes.Axes]: """ Return a figure and a single subplot. This command is analogous to `matplotlib.pyplot.subplot`, @@ -196,7 +197,7 @@ def subplot(**kwargs) -> tuple[pfigure.Figure, paxes.Axes]: @docstring._snippet_manager -def subplots(*args, **kwargs) -> tuple[pfigure.Figure, pgridspec.SubplotGrid]: +def subplots(*args, **kwargs) -> tuple[Figure, pgridspec.SubplotGrid]: """ Return a figure and an arbitrary grid of subplots. This command is analogous to `matplotlib.pyplot.subplots`, diff --git a/ultraplot/ui.pyi b/ultraplot/ui.pyi index 0a57111b3..d04ee399a 100644 --- a/ultraplot/ui.pyi +++ b/ultraplot/ui.pyi @@ -9,6 +9,7 @@ from . import axes as paxes from . import figure as pfigure from . import gridspec as pgridspec from ._subplots import SubplotManager +from .figure import Figure from .internals import _not_none, _pop_params, _pop_props, _pop_rc, docstring, ic __all__ = ['figure', 'subplot', 'subplots', 'show', 'close', 'switch_backend', 'ion', 'ioff', 'isinteractive'] _pyplot_docstring = ... @@ -62,7 +63,7 @@ def isinteractive() -> bool: This is included so you don't have to import `~matplotlib.pyplot`.""" ... -def figure(**kwargs: Incomplete) -> pfigure.Figure: +def figure(**kwargs: Incomplete) -> Figure: """Create an empty figure. Subplots can be subsequently added using `~ultraplot.figure.Figure.add_subplot` or `~ultraplot.figure.Figure.subplots`. This command is analogous to `matplotlib.pyplot.figure`. @@ -213,7 +214,7 @@ ultraplot.figure.Figure matplotlib.figure.Figure""" ... -def subplot(**kwargs: Incomplete) -> tuple[pfigure.Figure, paxes.Axes]: +def subplot(**kwargs: Incomplete) -> tuple[Figure, paxes.Axes]: """Return a figure and a single subplot. This command is analogous to `matplotlib.pyplot.subplot`, except the figure instance is also returned. @@ -368,7 +369,7 @@ ultraplot.figure.Figure matplotlib.figure.Figure""" ... -def subplots(*args: Incomplete, **kwargs: Incomplete) -> tuple[pfigure.Figure, pgridspec.SubplotGrid]: +def subplots(*args: Incomplete, **kwargs: Incomplete) -> tuple[Figure, pgridspec.SubplotGrid]: """Return a figure and an arbitrary grid of subplots. This command is analogous to `matplotlib.pyplot.subplots`, except the subplots are stored in a :class:`~ultraplot.gridspec.SubplotGrid`. diff --git a/ultraplot/ultralayout.pyi b/ultraplot/ultralayout.pyi index ab1eceedf..7efa04010 100644 --- a/ultraplot/ultralayout.pyi +++ b/ultraplot/ultralayout.pyi @@ -37,13 +37,11 @@ bool ... class UltraLayoutSolver: - """ - UltraLayout: Constraint-based layout solver using kiwisolver for subplot positioning. + """UltraLayout: Constraint-based layout solver using kiwisolver for subplot positioning. - This solver computes aesthetically pleasing positions for subplots in - non-orthogonal arrangements by using constraint satisfaction, providing - a superior layout experience for complex subplot arrangements. - """ +This solver computes aesthetically pleasing positions for subplots in +non-orthogonal arrangements by using constraint satisfaction, providing +a superior layout experience for complex subplot arrangements.""" def __init__(self, array: np.ndarray, figwidth: float=10.0, figheight: float=8.0, wspace: Optional[List[float]]=None, hspace: Optional[List[float]]=None, left: float=0.125, right: float=0.125, top: float=0.125, bottom: float=0.125, wratios: Optional[List[float]]=None, hratios: Optional[List[float]]=None, wpanels: Optional[List[bool]]=None, hpanels: Optional[List[bool]]=None) -> None: """Initialize the UltraLayout solver. @@ -83,11 +81,10 @@ dict ... class ColorbarLayoutSolver: - """ - Constraint-based solver for inset colorbar frame alignment. - """ + """Constraint-based solver for inset colorbar frame alignment.""" def __init__(self, loc: str, cb_width: float, cb_height: float, pad_left: float, pad_right: float, pad_bottom: float, pad_top: float) -> None: + """Initialize self. See help(type(self)) for accurate signature.""" ... def _setup_constraints(self) -> None: diff --git a/ultraplot/utils.pyi b/ultraplot/utils.pyi index d4e9fdbae..d80f8f2fc 100644 --- a/ultraplot/utils.pyi +++ b/ultraplot/utils.pyi @@ -579,17 +579,15 @@ the layout of axes in a GridSpec.""" @dataclass class _Crawler: - """ - A crawler is used to find edges of axes in a grid layout. - This is useful for determining whether to turn shared labels - on or depending on the position of an axis in the gridspec. - It crawls over the grid in all four cardinal directions and - checks whether it reaches a border of the grid or an axis of - a different type. It was created as adding colorbars will - change the underlying gridspec and therefore we cannot rely - on the original gridspec to determine whether an axis is a - border or not. - """ + """A crawler is used to find edges of axes in a grid layout. +This is useful for determining whether to turn shared labels +on or depending on the position of an axis in the gridspec. +It crawls over the grid in all four cardinal directions and +checks whether it reaches a border of the grid or an axis of +a different type. It was created as adding colorbars will +change the underlying gridspec and therefore we cannot rely +on the original gridspec to determine whether an axis is a +border or not.""" ax: object grid: np.ndarray[int, int] grid_axis_type: np.ndarray[int, int] From 590c221ce5a0629d2c1ed226efeeed03b4a94e2c Mon Sep 17 00:00:00 2001 From: cvanelteren Date: Fri, 4 Sep 2026 12:26:33 +1000 Subject: [PATCH 6/9] update pyi and fix some formatting in docs --- docs/projections.py | 6 +- docs/sphinxext/custom_roles.py | 14 ++- tools/generate_stubs.py | 41 ++++++-- ultraplot/_animation.pyi | 2 - ultraplot/_interaction.pyi | 2 - ultraplot/_layout.pyi | 3 - ultraplot/_lazy.pyi | 2 - ultraplot/_subplots.pyi | 1 - ultraplot/animation.pyi | 3 - ultraplot/axes/base.py | 20 ++-- ultraplot/axes/base.pyi | 44 ++++----- ultraplot/axes/container.pyi | 5 +- ultraplot/axes/geo.pyi | 84 ++++++++-------- ultraplot/axes/plot.py | 19 ++-- ultraplot/axes/plot.pyi | 54 ++++++----- ultraplot/axes/plot_types/curved_quiver.pyi | 4 - ultraplot/axes/three.pyi | 100 +++++++++++++++++++- ultraplot/colorbar.pyi | 1 - ultraplot/colors.pyi | 6 -- ultraplot/config.pyi | 6 -- ultraplot/constructor.pyi | 14 --- ultraplot/figure.pyi | 92 +++++++++--------- ultraplot/gridspec.pyi | 22 ++--- ultraplot/internals/benchmarks.pyi | 1 - ultraplot/internals/context.pyi | 2 - ultraplot/internals/rcsetup.pyi | 8 -- ultraplot/internals/versions.pyi | 9 -- ultraplot/legend.pyi | 1 - ultraplot/scale.pyi | 1 - ultraplot/ticker.pyi | 14 --- ultraplot/ui.pyi | 18 ++-- ultraplot/ultralayout.pyi | 1 - 32 files changed, 319 insertions(+), 281 deletions(-) diff --git a/docs/projections.py b/docs/projections.py index 66dc30c37..d285e3dc1 100644 --- a/docs/projections.py +++ b/docs/projections.py @@ -273,13 +273,13 @@ # projections global extent by calling :meth:`~cartopy.mpl.geoaxes.GeoAxes.set_global`. # This is a deviation from cartopy, which determines map boundaries automatically # based on the coordinates of the plotted content. To revert to cartopy's -# default behavior, set :rcraw:`geo.extent` to ``'auto`` or pass ``extent='auto'`` +# default behavior, set :rcraw:`geo.extent` to ``'auto'`` or pass ``extent='auto'`` # to :func:`~ultraplot.axes.GeoAxes.format`. # * By default, UltraPlot gives circular boundaries to polar cartopy and basemap # projections like :class:`~cartopy.crs.NorthPolarStereo` (see `this example # `__ # from the cartopy website). To disable this feature, set :rcraw:`geo.round` to -# ``False`` or pass ``round=False` to :func:`~ultraplot.axes.GeoAxes.format`. Please note +# ``False`` or pass ``round=False`` to :func:`~ultraplot.axes.GeoAxes.format`. Please note # that older versions of cartopy cannot add gridlines to maps bounded by circles. # * To make things more consistent, the :class:`~ultraplot.constructor.Proj` constructor # function lets you supply native `PROJ `__ keyword names @@ -332,7 +332,7 @@ # (i.e., Plate Carrée) coordinates the *default* coordinate system for all plotting # commands by internally passing ``transform=ccrs.PlateCarree()`` to cartopy commands # and ``latlon=True`` to basemap commands. And again, when `basemap`_ is the backend, -# plotting is done "cartopy-style" by calling methods from the `ultraplot.axes.GeoAxes` +# plotting is done "cartopy-style" by calling methods from the :class:`~ultraplot.axes.GeoAxes` # instance rather than the :class:`~mpl_toolkits.basemap.Basemap` instance. # # To ensure that a 2D :class:`~ultraplot.axes.PlotAxes` command like diff --git a/docs/sphinxext/custom_roles.py b/docs/sphinxext/custom_roles.py index a4d8488e6..719ce6ac0 100644 --- a/docs/sphinxext/custom_roles.py +++ b/docs/sphinxext/custom_roles.py @@ -1,6 +1,6 @@ #!/usr/bin/env python3 """ -Custom :rc: and :rcraw: roles for rc settings. +Custom roles used by UltraPlot documentation. """ import os @@ -57,10 +57,22 @@ def rc_role(name, rawtext, text, lineno, inliner, options={}, content=[]): # no return node_list, [] +def mpltype_role(name, rawtext, text, lineno, inliner, options={}, content=[]): # noqa: U100 + """ + Render Matplotlib's ``:mpltype:`` annotations as inline literals. + + Matplotlib uses this role in inherited docstrings, but its documentation + extension is not loaded by this project. Registering it locally prevents + unresolved-role warnings and visibly broken API markup. + """ + return [nodes.literal(rawtext, text)], [] + + def setup(app): """ Set up the roles. """ app.add_role("rc", rc_role) app.add_role("rcraw", rc_raw_role) + app.add_role("mpltype", mpltype_role) return {"parallel_read_safe": True, "parallel_write_safe": True} diff --git a/tools/generate_stubs.py b/tools/generate_stubs.py index d976a3bb9..48f6c9cd0 100644 --- a/tools/generate_stubs.py +++ b/tools/generate_stubs.py @@ -453,17 +453,43 @@ def _resolve_runtime_doc(module: Any, qualname: str) -> str | None: return None try: obj = module + member_class = None + member_name = None for part in qualname.split("."): - if isinstance(obj, type) and part in obj.__dict__: + if isinstance(obj, type): + # A source declaration may override an optional dependency's + # member only in one environment. Never borrow an inherited + # runtime docstring: it makes generated stubs dependency-specific. + if part not in obj.__dict__: + return None + member_class = obj + member_name = part candidate = obj.__dict__[part] if isinstance(candidate, property): - doc = inspect.getdoc(candidate) or inspect.getdoc(candidate.fget) + if getattr(candidate.fget, "__module__", None) != module.__name__: + return None + doc = candidate.__doc__ or getattr(candidate.fget, "__doc__", None) if doc: - return _clean_runtime_doc(doc) + return _clean_runtime_doc(inspect.cleandoc(doc)) obj = getattr(obj, part) - doc = inspect.getdoc(obj) + # Conditional placeholders such as ``SomeOptionalClass = None`` and + # imported dependency objects are not the source declaration represented + # by this AST node. Fall back to its static docstring in those cases. + if getattr(obj, "__module__", None) != module.__name__: + return None + # Use inherited documentation only from required Matplotlib bases. + # ``inspect.getdoc`` also searches optional Cartopy bases, which made + # local and clean-CI output differ depending on whether Cartopy existed. + doc = getattr(obj, "__doc__", None) + if not doc and member_class is not None and member_name is not None: + for base in member_class.__mro__[1:]: + if member_name not in base.__dict__: + continue + if base.__module__.startswith("matplotlib."): + doc = inspect.getdoc(base.__dict__[member_name]) + break if doc: - return _clean_runtime_doc(doc) + return _clean_runtime_doc(inspect.cleandoc(doc)) except Exception: pass return None @@ -562,9 +588,10 @@ def visit_ClassDef(self, node: ast.ClassDef) -> ast.ClassDef: if node.body and _is_docstring_statement(node.body[0]): qualname = ".".join((*self._scope, node.name)) doc = _resolve_runtime_doc(self._module, qualname) + if not doc: + doc = ast.get_docstring(node, clean=True) if doc: - if "%(" in doc: - doc = self._expand_docstring(doc) + doc = self._expand_docstring(doc) node.body[0] = ast.Expr(value=ast.Constant(doc)) if not node.body: node.body = [ast.Expr(value=ast.Constant(Ellipsis))] diff --git a/ultraplot/_animation.pyi b/ultraplot/_animation.pyi index 3734e42f6..8c247090c 100644 --- a/ultraplot/_animation.pyi +++ b/ultraplot/_animation.pyi @@ -40,7 +40,6 @@ is always untouched; a later complete draw primes the retained layers.""" _min_axes_for_view_redraw = 3 def __init__(self, canvas: Incomplete, figure: Incomplete=None) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... @staticmethod @@ -231,7 +230,6 @@ Managed artists are drawn above the cached static background, matching Matplotlib's standard blitting behavior.""" def __init__(self, canvas: Incomplete, artists: Iterable[martist.Artist]=(), bbox: Incomplete=None) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... @property diff --git a/ultraplot/_interaction.pyi b/ultraplot/_interaction.pyi index 5939a5659..dfccd1ed2 100644 --- a/ultraplot/_interaction.pyi +++ b/ultraplot/_interaction.pyi @@ -121,7 +121,6 @@ class _FramePacer: _interval = 1 / _TARGET_FRAME_RATE def __init__(self, canvas: Incomplete, is_active: Incomplete) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def cancel(self) -> None: @@ -145,7 +144,6 @@ class _NavigationInteractionManager: _scatter_limit = 2000 def __init__(self, canvas: Incomplete, figure: Incomplete, selective: Incomplete) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def _is_active(self) -> Incomplete: diff --git a/ultraplot/_layout.pyi b/ultraplot/_layout.pyi index ba9effa86..e3f40c325 100644 --- a/ultraplot/_layout.pyi +++ b/ultraplot/_layout.pyi @@ -64,7 +64,6 @@ cache because they may rely on repeated side effects.""" _MAX_STATES_PER_AXIS = 4 def __init__(self, figure: Incomplete) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def __enter__(self) -> Incomplete: @@ -122,7 +121,6 @@ measurements. Position-sensitive axes and extra artists automatically add the absolute origin to their state key.""" def __init__(self, figure: Incomplete) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def __enter__(self) -> Incomplete: @@ -189,7 +187,6 @@ Figure code only needs to know whether a transaction is active. Cache setup, dynamic-axes refresh, and exception-safe cleanup stay private to this object.""" def __init__(self, figure: Incomplete, *, cache_ticks: Incomplete=True, cache_extents: Incomplete=True) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def __enter__(self) -> Incomplete: diff --git a/ultraplot/_lazy.pyi b/ultraplot/_lazy.pyi index a87412add..91a4214cc 100644 --- a/ultraplot/_lazy.pyi +++ b/ultraplot/_lazy.pyi @@ -15,7 +15,6 @@ class LazyLoader: """Encapsulates lazy-loading mechanics for the ultraplot top-level module.""" def __init__(self, *, package: str, package_path: Path, exceptions: Mapping[str, tuple[str, Optional[str]]], setup_callback: Callable[[], None], registry_attr_callback: Callable[[str], Optional[type]], registry_build_callback: Callable[[], None], registry_names_callback: Callable[[], Optional[Mapping[str, type]]], attr_map_key: str='_ATTR_MAP', eager_key: str='_EAGER_DONE') -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def _import_module(self, module_name: str) -> types.ModuleType: @@ -55,7 +54,6 @@ class LazyLoader: class _UltraPlotModule(types.ModuleType): def __setattr__(self, name: str, value: Any) -> None: - """Implement setattr(self, name, value).""" ... def install_module_proxy(module: Optional[types.ModuleType]) -> None: diff --git a/ultraplot/_subplots.pyi b/ultraplot/_subplots.pyi index de3465ef6..bcfa9a24b 100644 --- a/ultraplot/_subplots.pyi +++ b/ultraplot/_subplots.pyi @@ -26,7 +26,6 @@ figure : `~ultraplot.figure.Figure` The parent figure.""" def __init__(self, figure: 'Figure') -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def reset(self) -> None: diff --git a/ultraplot/animation.pyi b/ultraplot/animation.pyi index 134176144..aaf440b05 100644 --- a/ultraplot/animation.pyi +++ b/ultraplot/animation.pyi @@ -49,7 +49,6 @@ deleted unless `finish` completed, so an animation that fails halfway through never leaves a truncated movie that looks like a whole one.""" def __init__(self, filename: Incomplete, fps: Incomplete) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def setup(self, width: Incomplete, height: Incomplete) -> Incomplete: @@ -76,7 +75,6 @@ class _RawFFMpegWriter(_RawWriter): """Pipe raw ``RGBA`` frames into ``ffmpeg`` with no intermediate encoding.""" def __init__(self, filename: Incomplete, fps: Incomplete, *, codec: Incomplete=None, bitrate: Incomplete=None, extra_args: Incomplete=None, metadata: Incomplete=None) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... @staticmethod @@ -106,7 +104,6 @@ class _RawPillowWriter(_RawWriter): """Collect raw ``RGBA`` frames and write an animated image with Pillow.""" def __init__(self, filename: Incomplete, fps: Incomplete) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def write(self, buffer: Incomplete) -> Incomplete: diff --git a/ultraplot/axes/base.py b/ultraplot/axes/base.py index c08c93d41..39e64c1a6 100644 --- a/ultraplot/axes/base.py +++ b/ultraplot/axes/base.py @@ -87,24 +87,24 @@ # Projection docstring _proj_docstring = """ proj, projection : -str, `cartopy.crs.Projection`, or `~mpl_toolkits.basemap.Basemap`, optional +str, :class:`cartopy.crs.Projection`, or :class:`~mpl_toolkits.basemap.Basemap`, optional The map projection specification(s). If ``'cart'`` or ``'cartesian'`` - (the default), a `~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, + (the default), a :class:`~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, a :class:`~ultraplot.axes.PolarAxes` is created. Otherwise, the argument is - interpreted by `~ultraplot.constructor.Proj`, and the result is used - to make a `~ultraplot.axes.GeoAxes` (in this case the argument can be - a `cartopy.crs.Projection` instance, a `~mpl_toolkits.basemap.Basemap` + interpreted by :class:`~ultraplot.constructor.Proj`, and the result is used + to make a :class:`~ultraplot.axes.GeoAxes` (in this case the argument can be + a :class:`cartopy.crs.Projection` instance, a :class:`~mpl_toolkits.basemap.Basemap` instance, or a projection name listed in :ref:`this table `). """ _proj_kw_docstring = """ proj_kw, projection_kw : dict-like, optional - Keyword arguments passed to `~mpl_toolkits.basemap.Basemap` or - cartopy `~cartopy.crs.Projection` classes on instantiation. + Keyword arguments passed to :class:`~mpl_toolkits.basemap.Basemap` or + :class:`~cartopy.crs.Projection` classes on instantiation. """ _backend_docstring = """ backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` - Whether to use `~mpl_toolkits.basemap.Basemap` or - `~cartopy.crs.Projection` for map projections. + Whether to use :class:`~mpl_toolkits.basemap.Basemap` or + :class:`~cartopy.crs.Projection` for map projections. .. deprecated:: 3.0.0 The ``'basemap'`` backend is deprecated and may be removed in a @@ -615,7 +615,7 @@ group of artists, the tuple group is expanded into unique legend entries -- otherwise, the tuple group elements are drawn on top of eachother). For details on matplotlib legend handlers and tuple groups, see the matplotlib `legend guide --`__. +`__. """ _legend_kwargs_docstring = """ frame, frameon : bool, optional diff --git a/ultraplot/axes/base.pyi b/ultraplot/axes/base.pyi index 260bcea0f..37422eeb5 100644 --- a/ultraplot/axes/base.pyi +++ b/ultraplot/axes/base.pyi @@ -95,29 +95,24 @@ class _TransformedBoundsLocator: """Axes locator for `~Axes.inset_axes` and other axes.""" def __init__(self, bounds: Incomplete, transform: Incomplete) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def __call__(self, ax: Incomplete, renderer: Incomplete) -> Incomplete: - """Call self as a function.""" ... class _AspectAwareTransformedBoundsLocator(_TransformedBoundsLocator): """Preserve an inset's lower-left anchor after box-aspect adjustment.""" def __call__(self, ax: Incomplete, renderer: Incomplete) -> Incomplete: - """Call self as a function.""" ... class _SideColorbarLocator: """Position a side colorbar beyond its parent axes decorations.""" def __init__(self, parent: Incomplete, side: Incomplete, bounds: Incomplete, pad: Incomplete, previous: Incomplete=()) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def __call__(self, ax: Incomplete, renderer: Incomplete) -> Incomplete: - """Call self as a function.""" ... class _ExternalModeMixin: @@ -134,7 +129,6 @@ value: class _ExternalContext: def __init__(self, ax: Incomplete, value: Incomplete=True) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def __enter__(self) -> Incomplete: @@ -796,20 +790,20 @@ transform : {'data', 'axes', 'figure', 'subfigure'} or `~matplotlib.transforms.T :class:`~matplotlib.figure.Figure.transSubfigure`, transforms. Default is to use the same projection as the current axes. proj, projection : -str, `cartopy.crs.Projection`, or `~mpl_toolkits.basemap.Basemap`, optional +str, :class:`cartopy.crs.Projection`, or :class:`~mpl_toolkits.basemap.Basemap`, optional The map projection specification(s). If ``'cart'`` or ``'cartesian'`` - (the default), a `~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, + (the default), a :class:`~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, a :class:`~ultraplot.axes.PolarAxes` is created. Otherwise, the argument is - interpreted by `~ultraplot.constructor.Proj`, and the result is used - to make a `~ultraplot.axes.GeoAxes` (in this case the argument can be - a `cartopy.crs.Projection` instance, a `~mpl_toolkits.basemap.Basemap` + interpreted by :class:`~ultraplot.constructor.Proj`, and the result is used + to make a :class:`~ultraplot.axes.GeoAxes` (in this case the argument can be + a :class:`cartopy.crs.Projection` instance, a :class:`~mpl_toolkits.basemap.Basemap` instance, or a projection name listed in :ref:`this table `). proj_kw, projection_kw : dict-like, optional - Keyword arguments passed to `~mpl_toolkits.basemap.Basemap` or - cartopy `~cartopy.crs.Projection` classes on instantiation. + Keyword arguments passed to :class:`~mpl_toolkits.basemap.Basemap` or + :class:`~cartopy.crs.Projection` classes on instantiation. backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` - Whether to use `~mpl_toolkits.basemap.Basemap` or - `~cartopy.crs.Projection` for map projections. + Whether to use :class:`~mpl_toolkits.basemap.Basemap` or + :class:`~cartopy.crs.Projection` for map projections. .. deprecated:: 3.0.0 The ``'basemap'`` backend is deprecated and may be removed in a @@ -859,20 +853,20 @@ transform : {'data', 'axes', 'figure', 'subfigure'} or `~matplotlib.transforms.T :class:`~matplotlib.figure.Figure.transSubfigure`, transforms. Default is to use the same projection as the current axes. proj, projection : -str, `cartopy.crs.Projection`, or `~mpl_toolkits.basemap.Basemap`, optional +str, :class:`cartopy.crs.Projection`, or :class:`~mpl_toolkits.basemap.Basemap`, optional The map projection specification(s). If ``'cart'`` or ``'cartesian'`` - (the default), a `~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, + (the default), a :class:`~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, a :class:`~ultraplot.axes.PolarAxes` is created. Otherwise, the argument is - interpreted by `~ultraplot.constructor.Proj`, and the result is used - to make a `~ultraplot.axes.GeoAxes` (in this case the argument can be - a `cartopy.crs.Projection` instance, a `~mpl_toolkits.basemap.Basemap` + interpreted by :class:`~ultraplot.constructor.Proj`, and the result is used + to make a :class:`~ultraplot.axes.GeoAxes` (in this case the argument can be + a :class:`cartopy.crs.Projection` instance, a :class:`~mpl_toolkits.basemap.Basemap` instance, or a projection name listed in :ref:`this table `). proj_kw, projection_kw : dict-like, optional - Keyword arguments passed to `~mpl_toolkits.basemap.Basemap` or - cartopy `~cartopy.crs.Projection` classes on instantiation. + Keyword arguments passed to :class:`~mpl_toolkits.basemap.Basemap` or + :class:`~cartopy.crs.Projection` classes on instantiation. backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` - Whether to use `~mpl_toolkits.basemap.Basemap` or - `~cartopy.crs.Projection` for map projections. + Whether to use :class:`~mpl_toolkits.basemap.Basemap` or + :class:`~cartopy.crs.Projection` for map projections. .. deprecated:: 3.0.0 The ``'basemap'`` backend is deprecated and may be removed in a @@ -1311,7 +1305,7 @@ labels : list of str, optional group of artists, the tuple group is expanded into unique legend entries -- otherwise, the tuple group elements are drawn on top of eachother). For details on matplotlib legend handlers and tuple groups, see the matplotlib `legend guide --`__. +`__. loc, location : int or str, default: :rc:`legend.loc` The legend location. Valid location keys are shown in the below table. diff --git a/ultraplot/axes/container.pyi b/ultraplot/axes/container.pyi index a6287bab6..e3c75e764 100644 --- a/ultraplot/axes/container.pyi +++ b/ultraplot/axes/container.pyi @@ -91,12 +91,11 @@ allocated space and overlap with adjacent subplots.""" ... def _reposition_subplot(self) -> None: - """Reposition the subplot axes.""" ... def _update_title_position(self, renderer: Incomplete) -> None: - """Update the position of inset titles and outer titles. This is called -by matplotlib at drawtime.""" + """Update the title position based on the bounding box enclosing +all the ticklabels and x-axis spine and xlabel...""" ... def _title_reserves_external_space(self, loc: Incomplete) -> bool: diff --git a/ultraplot/axes/geo.pyi b/ultraplot/axes/geo.pyi index df392269e..e8c2434af 100644 --- a/ultraplot/axes/geo.pyi +++ b/ultraplot/axes/geo.pyi @@ -60,11 +60,9 @@ class _AnchoredInsetLocator: """Locate an inset by anchoring one of its points to a parent coordinate.""" def __init__(self, parent: Incomplete, xy: Incomplete, size: Incomplete, transform: Incomplete, anchor: Incomplete, square: Incomplete=False) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def __call__(self, ax: Incomplete, renderer: Incomplete) -> Incomplete: - """Call self as a function.""" ... _HAWKEYE_TRANSFORM_NAMES = frozenset({'axes', 'data', 'figure', 'subfigure', 'map'}) @@ -224,20 +222,9 @@ if cgridliner is not None and hasattr(cgridliner, 'Label'): ... def _axes_domain(self, *args: Any, **kwargs: Any) -> tuple[Any, Any]: - """Return lon_range, lat_range""" ... def _draw_gridliner(self, *args: Any, **kwargs: Any) -> Any: - """Create Artists for all visible elements and add to our Axes. - -The following rules apply for the visibility of labels: - -- X-type labels are plotted along the bottom, top and geo spines. -- Y-type labels are plotted along the left, right and geo spines. -- A label must not overlap another label marked as visible. -- A label must not overlap the map boundary. -- When a label is about to be hidden, its padding is slightly - increase until it can be drawn or until a padding limit is reached.""" ... else: _CartopyGridliner = None @@ -248,7 +235,6 @@ longitude and latitude coordinates. Modeled after how `matplotlib.ticker._DummyA and `matplotlib.ticker.TickHelper` are used to control tick locations and labels.""" def __init__(self, axes: 'GeoAxes') -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def _get_extent(self) -> tuple[float, float, float, float]: @@ -350,7 +336,6 @@ class _CartopyGridlinerAdapter(_GridlinerAdapter): into the Gridliner API while hiding cartopy version differences.""" def __init__(self, gridliner: Optional[_CartopyGridlinerProtocol]) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... @staticmethod @@ -377,7 +362,6 @@ class _BasemapGridlinerAdapter(_GridlinerAdapter): of cartopy Gridliner behavior needed by GeoAxes (labels, toggles, styling).""" def __init__(self, lonlines: GridlineDict | None, latlines: GridlineDict | None) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def labels_for_sides(self, *, bottom: bool | str | None=None, top: bool | str | None=None, left: bool | str | None=None, right: bool | str | None=None) -> dict[str, list[mtext.Text]]: @@ -400,7 +384,6 @@ class _LonAxis(_GeoAxis): axis_name = 'lon' def __init__(self, axes: 'GeoAxes') -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def _get_ticklocs(self, locator: mticker.Locator) -> np.ndarray: @@ -414,7 +397,6 @@ class _LatAxis(_GeoAxis): axis_name = 'lat' def __init__(self, axes: 'GeoAxes', latmax: float=90) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def _get_ticklocs(self, locator: mticker.Locator) -> np.ndarray: @@ -855,7 +837,6 @@ projected coordinates.""" @override def _sharex_setup(self, sharex: 'GeoAxes', *, labels: bool=True, limits: bool=True) -> None: - """Configure x-axis sharing for panels. See also `~CartesianAxes._sharex_setup`.""" ... def _toggle_ticks(self, label: Any, which: str) -> None: @@ -1524,11 +1505,6 @@ projections. This was developed from `this cartopy example Sequence[float]: - """Get the extent (x0, x1, y0, y1) of the map in the given coordinate -system. - -If no crs is given, the returned extents' coordinate system will be -the CRS of this Axes.""" ... @override @@ -1541,36 +1517,50 @@ after the main axes has applied its aspect but before the panel axes are drawn." ... def get_tightbbox(self, renderer: Any, *args: Any, **kwargs: Any) -> Any: - """Extend the standard behaviour of -:func:`matplotlib.axes.Axes.get_tightbbox`. + """Return the tight bounding box of the Axes, including axis and their +decorators (xlabel, title, etc). -Adjust the axes aspect ratio and background patch location before -calculating the tight bounding box.""" - ... - - def set_extent(self, extent: Sequence[float], crs: Any=None) -> Any: - """Set the extent (x0, x1, y0, y1) of the map in the given -coordinate system. - -If no crs is given, the extents' coordinate system will be assumed -to be the Geodetic version of this axes' projection. +Artists that have ``artist.set_in_layout(False)`` are not included +in the bbox. Parameters ---------- -extents - Tuple of floats representing the required extent (x0, x1, y0, y1).""" +renderer : `.RendererBase` subclass + renderer that will be used to draw the figures (i.e. + ``fig.canvas.get_renderer()``) + +bbox_extra_artists : list of `.Artist` or ``None`` + List of artists to include in the tight bounding box. If + ``None`` (default), then all artist children of the Axes are + included in the tight bounding box. + +call_axes_locator : bool, default: True + If *call_axes_locator* is ``False``, it does not call the + ``_axes_locator`` attribute, which is necessary to get the correct + bounding box. ``call_axes_locator=False`` can be used if the + caller is only interested in the relative size of the tightbbox + compared to the Axes bbox. + +for_layout_only : default: False + The bounding box will *not* include the x-extent of the title and + the xlabel, or the y-extent of the ylabel. + +Returns +------- +`.BboxBase` + Bounding box in figure pixel coordinates. + +See Also +-------- +matplotlib.axes.Axes.get_window_extent +matplotlib.axis.Axis.get_tightbbox +matplotlib.spines.Spine.get_window_extent""" ... - def set_global(self) -> Any: - """Set the extent of the Axes to the limits of the projection. + def set_extent(self, extent: Sequence[float], crs: Any=None) -> Any: + ... -Note ----- - In some cases where the projection has a limited sensible range - the ``set_global`` method does not actually make the whole globe - visible. Instead, the most appropriate extents will be used (e.g. - Ordnance Survey UK will set the extents to be around the British - Isles.""" + def set_global(self) -> Any: ... class _BasemapAxes(GeoAxes): diff --git a/ultraplot/axes/plot.py b/ultraplot/axes/plot.py index 06c5ee361..e2a615d03 100644 --- a/ultraplot/axes/plot.py +++ b/ultraplot/axes/plot.py @@ -111,7 +111,7 @@ coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` and the `x` coordinates are ``np.arange(0, y.shape[1])``. * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using - `~ultraplot.utils.edges` or `:func:`~ultraplot.utils.edges2d`` if *centers* were provided. + `~ultraplot.utils.edges` or :func:`~ultraplot.utils.edges2d` if *centers* were provided. For all other methods, calculate coordinate *centers* if *edges* were provided. * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the @@ -1185,11 +1185,12 @@ Parameters ---------- %(plot.args_1d_{which})s -stemlinewdith: str, default `rc["lollipop.stemlinewidth"]` -stemcolor: str, default `rc["lollipop.stemcolor"]` - Line color of the lines connecting the dots to the {which}-axis. Defaults to `rc["lollipop.linecolor"]`. -stemlinestyle: str, default: `rc["lollipop.stemlinestyle"]` - The style of the lines connecting the dots to the {which}-axis. Defaults to `rc["lollipop.linestyle"]`. +stemlinewidth : str, default: :rc:`lollipop.stemlinewidth` + The width of the lines connecting the dots to the {which}-axis. +stemcolor : str, default: :rc:`lollipop.stemcolor` + Line color of the lines connecting the dots to the {which}-axis. Defaults to :rc:`lollipop.linecolor`. +stemlinestyle : str, default: :rc:`lollipop.stemlinestyle` + The style of the lines connecting the dots to the {which}-axis. Defaults to :rc:`lollipop.linestyle`. s, size, ms, markersize : float or array-like or unit-spec, optional The marker size area(s). If this is an array matching the shape of `x` and `y`, the units are scaled by `smin` and `smax`. If this contains unit string(s), it @@ -1695,13 +1696,13 @@ layout : callable or dict, optional A layout function or a precomputed dict mapping nodes to 2D positions. If a function is given, it is called as ``layout(g, **layout_kw)`` to compute positions. See :func:`networkx.drawing.nx_pylab.draw` for more information. -nodes : bool or iterable, default: rc["graph.draw_nodes"] +nodes : bool or iterable, default: :rc:`graph.draw_nodes` Which nodes to draw. If `True`, all nodes are drawn. If an iterable is provided, only the specified nodes are included. This effectively acts as `nodelist` in :func:`networkx.drawing.nx_pylab.draw_networkx_nodes`. -edges : bool or iterable, default: rc["graph.draw_edges"] +edges : bool or iterable, default: :rc:`graph.draw_edges` Which edges to draw. If `True`, all edges are drawn. If an iterable of edge tuples is provided, only those edges are included. This effectively acts as `edgelist` in :func:`networkx.drawing.nx_pylab.draw_networkx_edges`. -labels : bool or iterable, default: `rc["graph.draw_labels`] +labels : bool or iterable, default: :rc:`graph.draw_labels` Whether to show node labels. If `True`, labels are drawn using node names. If an iterable is given, only those nodes are labeled. layout_kw : dict, default: {} diff --git a/ultraplot/axes/plot.pyi b/ultraplot/axes/plot.pyi index 450cf496a..2831d50d9 100644 --- a/ultraplot/axes/plot.pyi +++ b/ultraplot/axes/plot.pyi @@ -1608,11 +1608,12 @@ Parameters * If any arguments are `pint.Quantity`, auto-add the pint unit registry to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. -stemlinewdith: str, default `rc["lollipop.stemlinewidth"]` -stemcolor: str, default `rc["lollipop.stemcolor"]` - Line color of the lines connecting the dots to the x-axis. Defaults to `rc["lollipop.linecolor"]`. -stemlinestyle: str, default: `rc["lollipop.stemlinestyle"]` - The style of the lines connecting the dots to the x-axis. Defaults to `rc["lollipop.linestyle"]`. +stemlinewidth : str, default: :rc:`lollipop.stemlinewidth` + The width of the lines connecting the dots to the x-axis. +stemcolor : str, default: :rc:`lollipop.stemcolor` + Line color of the lines connecting the dots to the x-axis. Defaults to :rc:`lollipop.linecolor`. +stemlinestyle : str, default: :rc:`lollipop.stemlinestyle` + The style of the lines connecting the dots to the x-axis. Defaults to :rc:`lollipop.linestyle`. s, size, ms, markersize : float or array-like or unit-spec, optional The marker size area(s). If this is an array matching the shape of `x` and `y`, the units are scaled by `smin` and `smax`. If this contains unit string(s), it @@ -1893,11 +1894,12 @@ Parameters * If any arguments are `pint.Quantity`, auto-add the pint unit registry to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. -stemlinewdith: str, default `rc["lollipop.stemlinewidth"]` -stemcolor: str, default `rc["lollipop.stemcolor"]` - Line color of the lines connecting the dots to the x-axis. Defaults to `rc["lollipop.linecolor"]`. -stemlinestyle: str, default: `rc["lollipop.stemlinestyle"]` - The style of the lines connecting the dots to the x-axis. Defaults to `rc["lollipop.linestyle"]`. +stemlinewidth : str, default: :rc:`lollipop.stemlinewidth` + The width of the lines connecting the dots to the x-axis. +stemcolor : str, default: :rc:`lollipop.stemcolor` + Line color of the lines connecting the dots to the x-axis. Defaults to :rc:`lollipop.linecolor`. +stemlinestyle : str, default: :rc:`lollipop.stemlinestyle` + The style of the lines connecting the dots to the x-axis. Defaults to :rc:`lollipop.linestyle`. s, size, ms, markersize : float or array-like or unit-spec, optional The marker size area(s). If this is an array matching the shape of `x` and `y`, the units are scaled by `smin` and `smax`. If this contains unit string(s), it @@ -5269,13 +5271,13 @@ g : networkx.Graph layout : callable or dict, optional A layout function or a precomputed dict mapping nodes to 2D positions. If a function is given, it is called as ``layout(g, **layout_kw)`` to compute positions. See :func:`networkx.drawing.nx_pylab.draw` for more information. -nodes : bool or iterable, default: rc["graph.draw_nodes"] +nodes : bool or iterable, default: :rc:`graph.draw_nodes` Which nodes to draw. If `True`, all nodes are drawn. If an iterable is provided, only the specified nodes are included. This effectively acts as `nodelist` in :func:`networkx.drawing.nx_pylab.draw_networkx_nodes`. -edges : bool or iterable, default: rc["graph.draw_edges"] +edges : bool or iterable, default: :rc:`graph.draw_edges` Which edges to draw. If `True`, all edges are drawn. If an iterable of edge tuples is provided, only those edges are included. This effectively acts as `edgelist` in :func:`networkx.drawing.nx_pylab.draw_networkx_edges`. -labels : bool or iterable, default: `rc["graph.draw_labels`] +labels : bool or iterable, default: :rc:`graph.draw_labels` Whether to show node labels. If `True`, labels are drawn using node names. If an iterable is given, only those nodes are labeled. layout_kw : dict, default: {} @@ -8841,7 +8843,7 @@ Parameters coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` and the `x` coordinates are ``np.arange(0, y.shape[1])``. * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using - `~ultraplot.utils.edges` or `:func:`~ultraplot.utils.edges2d`` if *centers* were provided. + `~ultraplot.utils.edges` or :func:`~ultraplot.utils.edges2d` if *centers* were provided. For all other methods, calculate coordinate *centers* if *edges* were provided. * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the @@ -9324,7 +9326,7 @@ Parameters coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` and the `x` coordinates are ``np.arange(0, y.shape[1])``. * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using - `~ultraplot.utils.edges` or `:func:`~ultraplot.utils.edges2d`` if *centers* were provided. + `~ultraplot.utils.edges` or :func:`~ultraplot.utils.edges2d` if *centers* were provided. For all other methods, calculate coordinate *centers* if *edges* were provided. * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the @@ -9815,7 +9817,7 @@ Parameters coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` and the `x` coordinates are ``np.arange(0, y.shape[1])``. * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using - `~ultraplot.utils.edges` or `:func:`~ultraplot.utils.edges2d`` if *centers* were provided. + `~ultraplot.utils.edges` or :func:`~ultraplot.utils.edges2d` if *centers* were provided. For all other methods, calculate coordinate *centers* if *edges* were provided. * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the @@ -10241,7 +10243,7 @@ Parameters coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` and the `x` coordinates are ``np.arange(0, y.shape[1])``. * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using - `~ultraplot.utils.edges` or `:func:`~ultraplot.utils.edges2d`` if *centers* were provided. + `~ultraplot.utils.edges` or :func:`~ultraplot.utils.edges2d` if *centers* were provided. For all other methods, calculate coordinate *centers* if *edges* were provided. * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the @@ -10702,7 +10704,7 @@ Parameters coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` and the `x` coordinates are ``np.arange(0, y.shape[1])``. * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using - `~ultraplot.utils.edges` or `:func:`~ultraplot.utils.edges2d`` if *centers* were provided. + `~ultraplot.utils.edges` or :func:`~ultraplot.utils.edges2d` if *centers* were provided. For all other methods, calculate coordinate *centers* if *edges* were provided. * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the @@ -11055,7 +11057,7 @@ Parameters coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` and the `x` coordinates are ``np.arange(0, y.shape[1])``. * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using - `~ultraplot.utils.edges` or `:func:`~ultraplot.utils.edges2d`` if *centers* were provided. + `~ultraplot.utils.edges` or :func:`~ultraplot.utils.edges2d` if *centers* were provided. For all other methods, calculate coordinate *centers* if *edges* were provided. * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the @@ -11278,7 +11280,7 @@ Parameters coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` and the `x` coordinates are ``np.arange(0, y.shape[1])``. * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using - `~ultraplot.utils.edges` or `:func:`~ultraplot.utils.edges2d`` if *centers* were provided. + `~ultraplot.utils.edges` or :func:`~ultraplot.utils.edges2d` if *centers* were provided. For all other methods, calculate coordinate *centers* if *edges* were provided. * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the @@ -11622,7 +11624,7 @@ Parameters coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` and the `x` coordinates are ``np.arange(0, y.shape[1])``. * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using - `~ultraplot.utils.edges` or `:func:`~ultraplot.utils.edges2d`` if *centers* were provided. + `~ultraplot.utils.edges` or :func:`~ultraplot.utils.edges2d` if *centers* were provided. For all other methods, calculate coordinate *centers* if *edges* were provided. * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the @@ -12073,7 +12075,7 @@ Parameters coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` and the `x` coordinates are ``np.arange(0, y.shape[1])``. * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using - `~ultraplot.utils.edges` or `:func:`~ultraplot.utils.edges2d`` if *centers* were provided. + `~ultraplot.utils.edges` or :func:`~ultraplot.utils.edges2d` if *centers* were provided. For all other methods, calculate coordinate *centers* if *edges* were provided. * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the @@ -12236,7 +12238,7 @@ Parameters coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` and the `x` coordinates are ``np.arange(0, y.shape[1])``. * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using - `~ultraplot.utils.edges` or `:func:`~ultraplot.utils.edges2d`` if *centers* were provided. + `~ultraplot.utils.edges` or :func:`~ultraplot.utils.edges2d` if *centers* were provided. For all other methods, calculate coordinate *centers* if *edges* were provided. * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the @@ -12472,7 +12474,7 @@ Parameters coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` and the `x` coordinates are ``np.arange(0, y.shape[1])``. * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using - `~ultraplot.utils.edges` or `:func:`~ultraplot.utils.edges2d`` if *centers* were provided. + `~ultraplot.utils.edges` or :func:`~ultraplot.utils.edges2d` if *centers* were provided. For all other methods, calculate coordinate *centers* if *edges* were provided. * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the @@ -12856,7 +12858,7 @@ Parameters coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` and the `x` coordinates are ``np.arange(0, y.shape[1])``. * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using - `~ultraplot.utils.edges` or `:func:`~ultraplot.utils.edges2d`` if *centers* were provided. + `~ultraplot.utils.edges` or :func:`~ultraplot.utils.edges2d` if *centers* were provided. For all other methods, calculate coordinate *centers* if *edges* were provided. * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the @@ -13243,7 +13245,7 @@ Parameters coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` and the `x` coordinates are ``np.arange(0, y.shape[1])``. * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using - `~ultraplot.utils.edges` or `:func:`~ultraplot.utils.edges2d`` if *centers* were provided. + `~ultraplot.utils.edges` or :func:`~ultraplot.utils.edges2d` if *centers* were provided. For all other methods, calculate coordinate *centers* if *edges* were provided. * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the diff --git a/ultraplot/axes/plot_types/curved_quiver.pyi b/ultraplot/axes/plot_types/curved_quiver.pyi index 9647eaf00..a23c31ba1 100644 --- a/ultraplot/axes/plot_types/curved_quiver.pyi +++ b/ultraplot/axes/plot_types/curved_quiver.pyi @@ -38,7 +38,6 @@ decide the trajectory is bad (e.g., if the trajectory is very short) just call `undo_trajectory`.""" def __init__(self, grid: Incomplete, mask: Incomplete) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def grid2mask(self, xi: float, yi: float) -> tuple[int, int]: @@ -70,7 +69,6 @@ class _CurvedQuiverGrid(object): """Grid of data.""" def __init__(self, x: np.ndarray, y: np.ndarray) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... @property @@ -90,7 +88,6 @@ zeroed cells: When a streamline enters a cell, that cell is set to 1, and no new streamlines are allowed to enter.""" def __init__(self, density: float | int) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def __getitem__(self, *args: Incomplete) -> Incomplete: @@ -117,7 +114,6 @@ class _CurvedQuiverTerminateTrajectory(Exception): class CurvedQuiverSolver: def __init__(self, x: np.ndarray, y: np.ndarray, density: float | tuple[float, float]) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def get_integrator(self, u: np.ndarray, v: np.ndarray, minlength: float, resolution: float, magnitude: np.ndarray) -> Callable[[float, float], _CurvedQuiverTrajectory | None]: diff --git a/ultraplot/axes/three.pyi b/ultraplot/axes/three.pyi index 959df8679..8200a2f69 100644 --- a/ultraplot/axes/three.pyi +++ b/ultraplot/axes/three.pyi @@ -23,7 +23,105 @@ plotting overrides. This axes subclass can be used by passing ``proj='3d'`` or _name_aliases = ('3d',) def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" + """Build an Axes in a figure. + +Parameters +---------- +fig : `~matplotlib.figure.Figure` + The Axes is built in the `.Figure` *fig*. + +*args + ``*args`` can be a single ``(left, bottom, width, height)`` + rectangle or a single `.Bbox`. This specifies the rectangle (in + figure coordinates) where the Axes is positioned. + + ``*args`` can also consist of three numbers or a single three-digit + number; in the latter case, the digits are considered as + independent numbers. The numbers are interpreted as ``(nrows, + ncols, index)``: ``(nrows, ncols)`` specifies the size of an array + of subplots, and ``index`` is the 1-based index of the subplot + being created. Finally, ``*args`` can also directly be a + `.SubplotSpec` instance. + +sharex, sharey : `~matplotlib.axes.Axes`, optional + The x- or y-`~.matplotlib.axis` is shared with the x- or y-axis in + the input `~.axes.Axes`. Note that it is not possible to unshare + axes. + +frameon : bool, default: True + Whether the Axes frame is visible. + +box_aspect : float, optional + Set a fixed aspect for the Axes box, i.e. the ratio of height to + width. See `~.axes.Axes.set_box_aspect` for details. + +forward_navigation_events : bool or "auto", default: "auto" + Control whether pan/zoom events are passed through to Axes below + this one. "auto" is *True* for axes with an invisible patch and + *False* otherwise. + +**kwargs + Other optional keyword arguments: + + Properties: + adjustable: {'box', 'datalim'} + agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image + alpha: float or None + anchor: (float, float) or {'C', 'SW', 'S', 'SE', 'E', 'NE', ...} + animated: bool + aspect: {'auto', 'equal'} or float + autoscale_on: bool + autoscalex_on: unknown + autoscaley_on: unknown + axes_locator: Callable[[Axes, Renderer], Bbox] + axisbelow: bool or 'line' + box_aspect: float or None + clip_box: `~matplotlib.transforms.BboxBase` or None + clip_on: bool + clip_path: Patch or (Path, Transform) or None + facecolor or fc: :mpltype:`color` + figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + forward_navigation_events: bool or "auto" + frame_on: bool + gid: str + in_layout: bool + label: object + mouseover: bool + navigate: bool + navigate_mode: unknown + path_effects: list of `.AbstractPathEffect` + picker: None or bool or float or callable + position: [left, bottom, width, height] or `~matplotlib.transforms.Bbox` + prop_cycle: `~cycler.Cycler` + rasterization_zorder: float or None + rasterized: bool + sketch_params: (scale: float, length: float, randomness: float) + snap: bool or None + subplotspec: unknown + title: str + transform: `~matplotlib.transforms.Transform` + url: str + visible: bool + xbound: (lower: float, upper: float) + xlabel: str + xlim: (left: float, right: float) + xmargin: float greater than -0.5 + xscale: unknown + xticklabels: unknown + xticks: unknown + ybound: (lower: float, upper: float) + ylabel: str + ylim: (bottom: float, top: float) + ymargin: float greater than -0.5 + yscale: unknown + yticklabels: unknown + yticks: unknown + zorder: float + +Returns +------- +`~.axes.Axes` + The new `~.axes.Axes` object.""" ... def graph(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: diff --git a/ultraplot/colorbar.pyi b/ultraplot/colorbar.pyi index 0ddf6640b..4c6c9fcd7 100644 --- a/ultraplot/colorbar.pyi +++ b/ultraplot/colorbar.pyi @@ -35,7 +35,6 @@ class UltraColorbar: """Centralized colorbar builder for axes.""" def __init__(self, axes: maxes.Axes) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def add(self, mappable: Any, values: Optional[Iterable[float]]=None, *, loc: Optional[str]=None, align: Optional[str]=None, space: Optional[Union[float, str]]=None, pad: Optional[Union[float, str]]=None, width: Optional[Union[float, str]]=None, length: Optional[Union[float, str]]=None, span: Optional[Union[int, Tuple[int, int]]]=None, row: Optional[int]=None, col: Optional[int]=None, rows: Optional[Union[int, Tuple[int, int]]]=None, cols: Optional[Union[int, Tuple[int, int]]]=None, shrink: Optional[Union[float, str]]=None, label: Optional[str]=None, title: Optional[str]=None, reverse: bool=False, rotation: Optional[float]=None, grid: Optional[bool]=None, edges: Optional[bool]=None, drawedges: Optional[bool]=None, extend: Optional[str]=None, extendsize: Optional[Union[float, str]]=None, extendfrac: Optional[float]=None, ticks: Optional[Iterable[float]]=None, locator: Optional[Any]=None, locator_kw: Optional[dict[str, Any]]=None, format: Optional[str]=None, formatter: Optional[Any]=None, ticklabels: Optional[Iterable[str]]=None, formatter_kw: Optional[dict[str, Any]]=None, minorticks: Optional[bool]=None, minorlocator: Optional[Any]=None, minorlocator_kw: Optional[dict[str, Any]]=None, tickminor: Optional[bool]=None, ticklen: Optional[Union[float, str]]=None, ticklenratio: Optional[float]=None, tickdir: Optional[str]=None, tickdirection: Optional[str]=None, tickwidth: Optional[Union[float, str]]=None, tickwidthratio: Optional[float]=None, ticklabelsize: Optional[float]=None, ticklabelweight: Optional[str]=None, ticklabelcolor: Optional[str]=None, labelloc: Optional[str]=None, labellocation: Optional[str]=None, labelsize: Optional[float]=None, labelweight: Optional[str]=None, labelcolor: Optional[str]=None, c: Optional[str]=None, color: Optional[str]=None, lw: Optional[Union[float, str]]=None, linewidth: Optional[Union[float, str]]=None, edgefix: Optional[bool]=None, rasterized: Optional[bool]=None, frame: Optional[bool]=None, frameon: Optional[bool]=None, outline: Union[bool, None]=None, labelrotation: Optional[Union[str, float]]=None, center_levels: Optional[bool]=None, **kwargs: Incomplete) -> mcolorbar.Colorbar: diff --git a/ultraplot/colors.pyi b/ultraplot/colors.pyi index 02d05a2ce..250169ee6 100644 --- a/ultraplot/colors.pyi +++ b/ultraplot/colors.pyi @@ -217,11 +217,9 @@ class ContinuousColormap(mcolors.LinearSegmentedColormap, _Colormap): """Replacement for `~matplotlib.colors.LinearSegmentedColormap`.""" def __str__(self) -> str: - """Return str(self).""" ... def __repr__(self) -> str: - """Return repr(self).""" ... def __init__(self, *args: Incomplete, gamma: Incomplete=1, alpha: Incomplete=None, cyclic: Incomplete=False, **kwargs: Incomplete) -> None: @@ -565,11 +563,9 @@ class DiscreteColormap(mcolors.ListedColormap, _Colormap): """Replacement for `~matplotlib.colors.ListedColormap`.""" def __str__(self) -> str: - """Return str(self).""" ... def __repr__(self) -> str: - """Return repr(self).""" ... @property @@ -1211,7 +1207,6 @@ class DivergingNorm(mcolors.Normalize): colormap color. The default central value is ``0``.""" def __str__(self) -> str: - """Return str(self).""" ... def __init__(self, vcenter: Incomplete=0, vmin: Incomplete=None, vmax: Incomplete=None, fair: Incomplete=True, clip: Incomplete=None) -> None: @@ -1287,7 +1282,6 @@ See `~ColorDatabase.__getitem__` for details.""" _colors_replace = (('grey', 'gray'), ('ochre', 'ocher'), ('kelley', 'kelly')) def __delitem__(self, key: Incomplete) -> None: - """Delete self[key].""" ... def __init__(self, mapping: Incomplete=None) -> None: diff --git a/ultraplot/config.pyi b/ultraplot/config.pyi index b6b2f2e35..aa4397d9d 100644 --- a/ultraplot/config.pyi +++ b/ultraplot/config.pyi @@ -270,27 +270,21 @@ stored in `rc_ultraplot`. This class is instantiated as the `rc` object on import. See the :ref:`user guide ` for details.""" def __repr__(self) -> str: - """Return repr(self).""" ... def __str__(self) -> str: - """Return str(self).""" ... def __iter__(self) -> Incomplete: - """Implement iter(self).""" ... def __len__(self) -> int: - """Return len(self).""" ... def __delitem__(self, key: Incomplete) -> Incomplete: - """Delete self[key].""" ... def __delattr__(self, attr: Incomplete) -> Incomplete: - """Implement delattr(self, name).""" ... def __init__(self, local: Incomplete=True, user: Incomplete=True, default: Incomplete=True, **kwargs: Incomplete) -> None: diff --git a/ultraplot/constructor.pyi b/ultraplot/constructor.pyi index 04334ce29..fddcf8d42 100644 --- a/ultraplot/constructor.pyi +++ b/ultraplot/constructor.pyi @@ -48,46 +48,36 @@ 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: - """Initialize self. See help(type(self)) for accurate signature.""" ... def _refresh(self) -> None: ... def __contains__(self, key: object) -> bool: - """True if the dictionary has the specified key, else False.""" ... def __getitem__(self, key: str) -> _RegistryValue: - """Return self[key].""" ... def __iter__(self) -> Iterator[str]: - """Implement iter(self).""" ... def __len__(self) -> int: - """Return len(self).""" ... def get(self, key: str, default: _RegistryValue | None=None) -> _RegistryValue | None: - """Return the value for key if key is in the dictionary, else default.""" ... def items(self) -> Incomplete: - """Return a set-like object providing a view on the dict's items.""" ... def keys(self) -> Incomplete: - """Return a set-like object providing a view on the dict's keys.""" ... def values(self) -> Incomplete: - """Return an object providing a view on the dict's values.""" ... def copy(self) -> dict[str, _RegistryValue]: - """Return a shallow copy of the dict.""" ... def _build_norm_registry() -> dict[str, type[mcolors.Normalize]]: @@ -362,9 +352,6 @@ ultraplot.constructor.Norm ultraplot.utils.get_colors""" def __init__(self, *args: Incomplete, N: Incomplete=None, samples: Incomplete=None, name: Incomplete=None, **kwargs: Incomplete) -> None: - """Semi-private init. - -Do not use this directly, use `cycler` function instead.""" ... def _parse_basic_properties(self, kwargs: Incomplete) -> Incomplete: @@ -396,7 +383,6 @@ Do not use this directly, use `cycler` function instead.""" ... def __eq__(self, other: Incomplete) -> bool: - """Return self==value.""" ... def get_next(self) -> Incomplete: diff --git a/ultraplot/figure.pyi b/ultraplot/figure.pyi index fcf55dde6..03c1534b0 100644 --- a/ultraplot/figure.pyi +++ b/ultraplot/figure.pyi @@ -786,20 +786,20 @@ rect : 4-tuple of float The (left, bottom, width, height) dimensions of the axes in figure-relative coordinates. proj, projection : -str, `cartopy.crs.Projection`, or `~mpl_toolkits.basemap.Basemap`, optional +str, :class:`cartopy.crs.Projection`, or :class:`~mpl_toolkits.basemap.Basemap`, optional The map projection specification(s). If ``'cart'`` or ``'cartesian'`` - (the default), a `~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, + (the default), a :class:`~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, a :class:`~ultraplot.axes.PolarAxes` is created. Otherwise, the argument is - interpreted by `~ultraplot.constructor.Proj`, and the result is used - to make a `~ultraplot.axes.GeoAxes` (in this case the argument can be - a `cartopy.crs.Projection` instance, a `~mpl_toolkits.basemap.Basemap` + interpreted by :class:`~ultraplot.constructor.Proj`, and the result is used + to make a :class:`~ultraplot.axes.GeoAxes` (in this case the argument can be + a :class:`cartopy.crs.Projection` instance, a :class:`~mpl_toolkits.basemap.Basemap` instance, or a projection name listed in :ref:`this table `). proj_kw, projection_kw : dict-like, optional - Keyword arguments passed to `~mpl_toolkits.basemap.Basemap` or - cartopy `~cartopy.crs.Projection` classes on instantiation. + Keyword arguments passed to :class:`~mpl_toolkits.basemap.Basemap` or + :class:`~cartopy.crs.Projection` classes on instantiation. backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` - Whether to use `~mpl_toolkits.basemap.Basemap` or - `~cartopy.crs.Projection` for map projections. + Whether to use :class:`~mpl_toolkits.basemap.Basemap` or + :class:`~cartopy.crs.Projection` for map projections. .. deprecated:: 3.0.0 The ``'basemap'`` backend is deprecated and may be removed in a @@ -993,20 +993,20 @@ autoshare : bool, default: True This has no effect if :rcraw:`subplots.share` is ``False`` or if ``sharex=False`` or ``sharey=False`` were passed to the figure. proj, projection : -str, `cartopy.crs.Projection`, or `~mpl_toolkits.basemap.Basemap`, optional +str, :class:`cartopy.crs.Projection`, or :class:`~mpl_toolkits.basemap.Basemap`, optional The map projection specification(s). If ``'cart'`` or ``'cartesian'`` - (the default), a `~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, + (the default), a :class:`~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, a :class:`~ultraplot.axes.PolarAxes` is created. Otherwise, the argument is - interpreted by `~ultraplot.constructor.Proj`, and the result is used - to make a `~ultraplot.axes.GeoAxes` (in this case the argument can be - a `cartopy.crs.Projection` instance, a `~mpl_toolkits.basemap.Basemap` + interpreted by :class:`~ultraplot.constructor.Proj`, and the result is used + to make a :class:`~ultraplot.axes.GeoAxes` (in this case the argument can be + a :class:`cartopy.crs.Projection` instance, a :class:`~mpl_toolkits.basemap.Basemap` instance, or a projection name listed in :ref:`this table `). proj_kw, projection_kw : dict-like, optional - Keyword arguments passed to `~mpl_toolkits.basemap.Basemap` or - cartopy `~cartopy.crs.Projection` classes on instantiation. + Keyword arguments passed to :class:`~mpl_toolkits.basemap.Basemap` or + :class:`~cartopy.crs.Projection` classes on instantiation. backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` - Whether to use `~mpl_toolkits.basemap.Basemap` or - `~cartopy.crs.Projection` for map projections. + Whether to use :class:`~mpl_toolkits.basemap.Basemap` or + :class:`~cartopy.crs.Projection` for map projections. .. deprecated:: 3.0.0 The ``'basemap'`` backend is deprecated and may be removed in a @@ -1215,20 +1215,20 @@ autoshare : bool, default: True This has no effect if :rcraw:`subplots.share` is ``False`` or if ``sharex=False`` or ``sharey=False`` were passed to the figure. proj, projection : -str, `cartopy.crs.Projection`, or `~mpl_toolkits.basemap.Basemap`, optional +str, :class:`cartopy.crs.Projection`, or :class:`~mpl_toolkits.basemap.Basemap`, optional The map projection specification(s). If ``'cart'`` or ``'cartesian'`` - (the default), a `~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, + (the default), a :class:`~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, a :class:`~ultraplot.axes.PolarAxes` is created. Otherwise, the argument is - interpreted by `~ultraplot.constructor.Proj`, and the result is used - to make a `~ultraplot.axes.GeoAxes` (in this case the argument can be - a `cartopy.crs.Projection` instance, a `~mpl_toolkits.basemap.Basemap` + interpreted by :class:`~ultraplot.constructor.Proj`, and the result is used + to make a :class:`~ultraplot.axes.GeoAxes` (in this case the argument can be + a :class:`cartopy.crs.Projection` instance, a :class:`~mpl_toolkits.basemap.Basemap` instance, or a projection name listed in :ref:`this table `). proj_kw, projection_kw : dict-like, optional - Keyword arguments passed to `~mpl_toolkits.basemap.Basemap` or - cartopy `~cartopy.crs.Projection` classes on instantiation. + Keyword arguments passed to :class:`~mpl_toolkits.basemap.Basemap` or + :class:`~cartopy.crs.Projection` classes on instantiation. backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` - Whether to use `~mpl_toolkits.basemap.Basemap` or - `~cartopy.crs.Projection` for map projections. + Whether to use :class:`~mpl_toolkits.basemap.Basemap` or + :class:`~cartopy.crs.Projection` for map projections. .. deprecated:: 3.0.0 The ``'basemap'`` backend is deprecated and may be removed in a @@ -1271,13 +1271,13 @@ order : {'C', 'F'}, default: 'C' subplots appear in the `SubplotGrid` returned by this function, and the order of subplot a-b-c labels (see `~ultraplot.axes.Axes.format`). proj, projection : -str, `cartopy.crs.Projection`, or `~mpl_toolkits.basemap.Basemap`, optional +str, :class:`cartopy.crs.Projection`, or :class:`~mpl_toolkits.basemap.Basemap`, optional The map projection specification(s). If ``'cart'`` or ``'cartesian'`` - (the default), a `~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, + (the default), a :class:`~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, a :class:`~ultraplot.axes.PolarAxes` is created. Otherwise, the argument is - interpreted by `~ultraplot.constructor.Proj`, and the result is used - to make a `~ultraplot.axes.GeoAxes` (in this case the argument can be - a `cartopy.crs.Projection` instance, a `~mpl_toolkits.basemap.Basemap` + interpreted by :class:`~ultraplot.constructor.Proj`, and the result is used + to make a :class:`~ultraplot.axes.GeoAxes` (in this case the argument can be + a :class:`cartopy.crs.Projection` instance, a :class:`~mpl_toolkits.basemap.Basemap` instance, or a projection name listed in :ref:`this table `). To use different projections for different subplots, you have @@ -1295,16 +1295,16 @@ str, `cartopy.crs.Projection`, or `~mpl_toolkits.basemap.Basemap`, optional for the third and fourth subplots. proj_kw, projection_kw : dict-like, optional - Keyword arguments passed to `~mpl_toolkits.basemap.Basemap` or - cartopy `~cartopy.crs.Projection` classes on instantiation. + Keyword arguments passed to :class:`~mpl_toolkits.basemap.Basemap` or + :class:`~cartopy.crs.Projection` classes on instantiation. If dictionary of properties, applies globally. If list or dictionary of dictionaries, applies to specific subplots, as with `proj`. For example, ``uplt.subplots(ncols=2, proj='cyl', proj_kw=({'lon_0': 0}, {'lon_0': 180})`` centers the projection in the left subplot on the prime meridian and in the right subplot on the international dateline. backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` - Whether to use `~mpl_toolkits.basemap.Basemap` or - `~cartopy.crs.Projection` for map projections. + Whether to use :class:`~mpl_toolkits.basemap.Basemap` or + :class:`~cartopy.crs.Projection` for map projections. .. deprecated:: 3.0.0 The ``'basemap'`` backend is deprecated and may be removed in a @@ -1535,13 +1535,13 @@ order : {'C', 'F'}, default: 'C' subplots appear in the `SubplotGrid` returned by this function, and the order of subplot a-b-c labels (see `~ultraplot.axes.Axes.format`). proj, projection : -str, `cartopy.crs.Projection`, or `~mpl_toolkits.basemap.Basemap`, optional +str, :class:`cartopy.crs.Projection`, or :class:`~mpl_toolkits.basemap.Basemap`, optional The map projection specification(s). If ``'cart'`` or ``'cartesian'`` - (the default), a `~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, + (the default), a :class:`~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, a :class:`~ultraplot.axes.PolarAxes` is created. Otherwise, the argument is - interpreted by `~ultraplot.constructor.Proj`, and the result is used - to make a `~ultraplot.axes.GeoAxes` (in this case the argument can be - a `cartopy.crs.Projection` instance, a `~mpl_toolkits.basemap.Basemap` + interpreted by :class:`~ultraplot.constructor.Proj`, and the result is used + to make a :class:`~ultraplot.axes.GeoAxes` (in this case the argument can be + a :class:`cartopy.crs.Projection` instance, a :class:`~mpl_toolkits.basemap.Basemap` instance, or a projection name listed in :ref:`this table `). To use different projections for different subplots, you have @@ -1559,16 +1559,16 @@ str, `cartopy.crs.Projection`, or `~mpl_toolkits.basemap.Basemap`, optional for the third and fourth subplots. proj_kw, projection_kw : dict-like, optional - Keyword arguments passed to `~mpl_toolkits.basemap.Basemap` or - cartopy `~cartopy.crs.Projection` classes on instantiation. + Keyword arguments passed to :class:`~mpl_toolkits.basemap.Basemap` or + :class:`~cartopy.crs.Projection` classes on instantiation. If dictionary of properties, applies globally. If list or dictionary of dictionaries, applies to specific subplots, as with `proj`. For example, ``uplt.subplots(ncols=2, proj='cyl', proj_kw=({'lon_0': 0}, {'lon_0': 180})`` centers the projection in the left subplot on the prime meridian and in the right subplot on the international dateline. backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` - Whether to use `~mpl_toolkits.basemap.Basemap` or - `~cartopy.crs.Projection` for map projections. + Whether to use :class:`~mpl_toolkits.basemap.Basemap` or + :class:`~cartopy.crs.Projection` for map projections. .. deprecated:: 3.0.0 The ``'basemap'`` backend is deprecated and may be removed in a @@ -2753,7 +2753,7 @@ labels : list of str, optional group of artists, the tuple group is expanded into unique legend entries -- otherwise, the tuple group elements are drawn on top of eachother). For details on matplotlib legend handlers and tuple groups, see the matplotlib `legend guide --`__. +`__. loc : str, optional The legend location. Valid location keys are as follows. diff --git a/ultraplot/gridspec.pyi b/ultraplot/gridspec.pyi index cdf6fe659..7a084571a 100644 --- a/ultraplot/gridspec.pyi +++ b/ultraplot/gridspec.pyi @@ -562,19 +562,15 @@ class SubplotGrid(MutableSequence[paxes.Axes], list[paxes.Axes], paxes.PlotAxes) See `~SubplotGrid.__getitem__` for details.""" def __repr__(self) -> str: - """Return repr(self).""" ... def __str__(self) -> str: - """Return str(self).""" ... def __len__(self) -> int: - """Return len(self).""" ... def insert(self, key: Incomplete, value: Incomplete) -> None: - """S.insert(index, value) -- insert value before index""" ... def __init__(self, sequence: Incomplete=None, **kwargs: Incomplete) -> None: @@ -1578,20 +1574,20 @@ transform : {'data', 'axes', 'figure', 'subfigure'} or `~matplotlib.transforms.T :class:`~matplotlib.figure.Figure.transSubfigure`, transforms. Default is to use the same projection as the current axes. proj, projection : -str, `cartopy.crs.Projection`, or `~mpl_toolkits.basemap.Basemap`, optional +str, :class:`cartopy.crs.Projection`, or :class:`~mpl_toolkits.basemap.Basemap`, optional The map projection specification(s). If ``'cart'`` or ``'cartesian'`` - (the default), a `~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, + (the default), a :class:`~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, a :class:`~ultraplot.axes.PolarAxes` is created. Otherwise, the argument is - interpreted by `~ultraplot.constructor.Proj`, and the result is used - to make a `~ultraplot.axes.GeoAxes` (in this case the argument can be - a `cartopy.crs.Projection` instance, a `~mpl_toolkits.basemap.Basemap` + interpreted by :class:`~ultraplot.constructor.Proj`, and the result is used + to make a :class:`~ultraplot.axes.GeoAxes` (in this case the argument can be + a :class:`cartopy.crs.Projection` instance, a :class:`~mpl_toolkits.basemap.Basemap` instance, or a projection name listed in :ref:`this table `). proj_kw, projection_kw : dict-like, optional - Keyword arguments passed to `~mpl_toolkits.basemap.Basemap` or - cartopy `~cartopy.crs.Projection` classes on instantiation. + Keyword arguments passed to :class:`~mpl_toolkits.basemap.Basemap` or + :class:`~cartopy.crs.Projection` classes on instantiation. backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` - Whether to use `~mpl_toolkits.basemap.Basemap` or - `~cartopy.crs.Projection` for map projections. + Whether to use :class:`~mpl_toolkits.basemap.Basemap` or + :class:`~cartopy.crs.Projection` for map projections. .. deprecated:: 3.0.0 The ``'basemap'`` backend is deprecated and may be removed in a diff --git a/ultraplot/internals/benchmarks.pyi b/ultraplot/internals/benchmarks.pyi index 74469f100..dd8b9c740 100644 --- a/ultraplot/internals/benchmarks.pyi +++ b/ultraplot/internals/benchmarks.pyi @@ -12,7 +12,6 @@ class _benchmark(object): """Context object for timing arbitrary blocks of code.""" def __init__(self, message: Incomplete) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def __enter__(self) -> None: diff --git a/ultraplot/internals/context.pyi b/ultraplot/internals/context.pyi index ee40f8095..f73ed60fb 100644 --- a/ultraplot/internals/context.pyi +++ b/ultraplot/internals/context.pyi @@ -10,7 +10,6 @@ class _empty_context(object): """A dummy context manager.""" def __init__(self) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def __enter__(self) -> None: @@ -23,7 +22,6 @@ class _state_context(object): """Temporarily modify attribute(s) for an arbitrary object.""" def __init__(self, obj: Incomplete, **kwargs: Incomplete) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def __enter__(self) -> None: diff --git a/ultraplot/internals/rcsetup.pyi b/ultraplot/internals/rcsetup.pyi index ab30584ce..b867076a4 100644 --- a/ultraplot/internals/rcsetup.pyi +++ b/ultraplot/internals/rcsetup.pyi @@ -156,31 +156,24 @@ class _RcParams(MutableMapping, dict): """A simple dictionary with locked inputs and validated assignments.""" def __init__(self, source: Incomplete, validate: Incomplete) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def __repr__(self) -> Incomplete: - """Return repr(self).""" ... def __str__(self) -> Incomplete: - """Return str(self).""" ... def __len__(self) -> Incomplete: - """Return len(self).""" ... def __iter__(self) -> Incomplete: - """Implement iter(self).""" ... def __getitem__(self, key: Incomplete) -> Incomplete: - """Return self[key].""" ... def __setitem__(self, key: Incomplete, value: Incomplete) -> Incomplete: - """Set self[key] to value.""" ... @staticmethod @@ -188,7 +181,6 @@ class _RcParams(MutableMapping, dict): ... def copy(self) -> Incomplete: - """Return a shallow copy of the dict.""" ... _validate_pt = _validate_units('pt') _validate_em = _validate_units('em') diff --git a/ultraplot/internals/versions.pyi b/ultraplot/internals/versions.pyi index 067121744..3d96f6cb5 100644 --- a/ultraplot/internals/versions.pyi +++ b/ultraplot/internals/versions.pyi @@ -12,39 +12,30 @@ class _version(list): add a 'packaging' dependency and only care about major and minor tags.""" def __str__(self) -> str: - """Return str(self).""" ... def __repr__(self) -> str: - """Return repr(self).""" ... def __init__(self, version: Incomplete) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def __eq__(self, other: Incomplete) -> bool: - """Return self==value.""" ... def __ne__(self, other: Incomplete) -> bool: - """Return self!=value.""" ... def __gt__(self, other: Incomplete) -> bool: - """Return self>value.""" ... def __lt__(self, other: Incomplete) -> bool: - """Return self bool: - """Return self>=value.""" ... def __le__(self, other: Incomplete) -> bool: - """Return self<=value.""" ... import matplotlib _version_mpl = _version(matplotlib.__version__) diff --git a/ultraplot/legend.pyi b/ultraplot/legend.pyi index 53e1726a8..62fd8164d 100644 --- a/ultraplot/legend.pyi +++ b/ultraplot/legend.pyi @@ -841,7 +841,6 @@ class UltraLegend: """Centralized legend builder for axes.""" def __init__(self, axes: Incomplete) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... @staticmethod diff --git a/ultraplot/scale.pyi b/ultraplot/scale.pyi index 1cfc9893d..c079b8a27 100644 --- a/ultraplot/scale.pyi +++ b/ultraplot/scale.pyi @@ -28,7 +28,6 @@ and `~matplotlib.scale.ScaleBase.get_transform`. Also overrides `~matplotlib.axis.Axis` instance.""" def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def set_default_locators_and_formatters(self, axis: Incomplete, only_if_default: Incomplete=False) -> Incomplete: diff --git a/ultraplot/ticker.pyi b/ultraplot/ticker.pyi index 9e1ebda73..61555a5a0 100644 --- a/ultraplot/ticker.pyi +++ b/ultraplot/ticker.pyi @@ -46,7 +46,6 @@ class IndexLocator(mticker.Locator): are restricted to the extent of plotted content when content is present.""" def __init__(self, base: Incomplete=1, offset: Incomplete=0) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def set_params(self, base: Incomplete=None, offset: Incomplete=None) -> None: @@ -364,7 +363,6 @@ class IndexFormatter(mticker.Formatter): paired with `IndexLocator` or `~matplotlib.ticker.FixedLocator`.""" def __init__(self, labels: Incomplete) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def __call__(self, x: Incomplete, pos: Incomplete=None) -> Incomplete: @@ -489,7 +487,6 @@ class AutoCFDatetimeFormatter(mticker.Formatter): """Automatic formatter for `cftime.datetime` data.""" def __init__(self, locator: Incomplete, calendar: Incomplete, time_units: Incomplete=None) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def pick_format(self, resolution: Incomplete) -> Incomplete: @@ -508,7 +505,6 @@ class AutoCFDatetimeLocator(mticker.Locator): real_world_calendars = () def __init__(self, maxticks: Incomplete=None, calendar: Incomplete='standard', date_unit: Incomplete=None, minticks: Incomplete=3) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def set_params(self, maxticks: Incomplete=None, minticks: Incomplete=None, max_display_ticks: Incomplete=None) -> None: @@ -570,11 +566,9 @@ class _CartopyFormatter(object): """Mixin class for cartopy formatters.""" def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def __call__(self, value: Incomplete, pos: Incomplete=None) -> Incomplete: - """Call self as a function.""" ... class DegreeFormatter(_CartopyFormatter, _PlateCarreeFormatter): @@ -590,17 +584,9 @@ dms : bool, default: False ... def _apply_transform(self, value: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: - """Given a single value, a target projection and a source CRS, -transform the value from the source CRS to the target -projection, returning a single value.""" ... def _hemisphere(self, value: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: - """Given both a tick value in the Plate Carree projection and the -same value in the source CRS, return a string indicating the -hemisphere that the value is in. - -Must be over-ridden by the derived class.""" ... class LongitudeFormatter(_CartopyFormatter, LongitudeFormatter): diff --git a/ultraplot/ui.pyi b/ultraplot/ui.pyi index d04ee399a..790900686 100644 --- a/ultraplot/ui.pyi +++ b/ultraplot/ui.pyi @@ -394,13 +394,13 @@ order : {'C', 'F'}, default: 'C' subplots appear in the `SubplotGrid` returned by this function, and the order of subplot a-b-c labels (see `~ultraplot.axes.Axes.format`). proj, projection : -str, `cartopy.crs.Projection`, or `~mpl_toolkits.basemap.Basemap`, optional +str, :class:`cartopy.crs.Projection`, or :class:`~mpl_toolkits.basemap.Basemap`, optional The map projection specification(s). If ``'cart'`` or ``'cartesian'`` - (the default), a `~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, + (the default), a :class:`~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, a :class:`~ultraplot.axes.PolarAxes` is created. Otherwise, the argument is - interpreted by `~ultraplot.constructor.Proj`, and the result is used - to make a `~ultraplot.axes.GeoAxes` (in this case the argument can be - a `cartopy.crs.Projection` instance, a `~mpl_toolkits.basemap.Basemap` + interpreted by :class:`~ultraplot.constructor.Proj`, and the result is used + to make a :class:`~ultraplot.axes.GeoAxes` (in this case the argument can be + a :class:`cartopy.crs.Projection` instance, a :class:`~mpl_toolkits.basemap.Basemap` instance, or a projection name listed in :ref:`this table `). To use different projections for different subplots, you have @@ -418,16 +418,16 @@ str, `cartopy.crs.Projection`, or `~mpl_toolkits.basemap.Basemap`, optional for the third and fourth subplots. proj_kw, projection_kw : dict-like, optional - Keyword arguments passed to `~mpl_toolkits.basemap.Basemap` or - cartopy `~cartopy.crs.Projection` classes on instantiation. + Keyword arguments passed to :class:`~mpl_toolkits.basemap.Basemap` or + :class:`~cartopy.crs.Projection` classes on instantiation. If dictionary of properties, applies globally. If list or dictionary of dictionaries, applies to specific subplots, as with `proj`. For example, ``uplt.subplots(ncols=2, proj='cyl', proj_kw=({'lon_0': 0}, {'lon_0': 180})`` centers the projection in the left subplot on the prime meridian and in the right subplot on the international dateline. backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` - Whether to use `~mpl_toolkits.basemap.Basemap` or - `~cartopy.crs.Projection` for map projections. + Whether to use :class:`~mpl_toolkits.basemap.Basemap` or + :class:`~cartopy.crs.Projection` for map projections. .. deprecated:: 3.0.0 The ``'basemap'`` backend is deprecated and may be removed in a diff --git a/ultraplot/ultralayout.pyi b/ultraplot/ultralayout.pyi index 7efa04010..293b15e5b 100644 --- a/ultraplot/ultralayout.pyi +++ b/ultraplot/ultralayout.pyi @@ -84,7 +84,6 @@ class ColorbarLayoutSolver: """Constraint-based solver for inset colorbar frame alignment.""" def __init__(self, loc: str, cb_width: float, cb_height: float, pad_left: float, pad_right: float, pad_bottom: float, pad_top: float) -> None: - """Initialize self. See help(type(self)) for accurate signature.""" ... def _setup_constraints(self) -> None: From 3930ec1d0d0103d5e3cc8ab32db7d0ec7e4e8d3f Mon Sep 17 00:00:00 2001 From: cvanelteren Date: Fri, 4 Sep 2026 12:30:43 +1000 Subject: [PATCH 7/9] fix ci --- .github/workflows/main.yml | 11 +++++++++++ tools/ci/stub_consumer.py | 11 +++-------- 2 files changed, 14 insertions(+), 8 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 3744db5b7..153bfb0d1 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -173,6 +173,17 @@ jobs: --search-path . \ --python-interpreter-path "$(command -v python)" \ --ignore-missing-imports icecream \ + --ignore-missing-imports cartopy \ + --ignore-missing-imports cartopy.crs \ + --ignore-missing-imports cartopy.feature \ + --ignore-missing-imports cartopy.io \ + --ignore-missing-imports cartopy.mpl.feature_artist \ + --ignore-missing-imports cartopy.mpl.geoaxes \ + --ignore-missing-imports cartopy.mpl.gridliner \ + --ignore-missing-imports cartopy.mpl.path \ + --ignore-missing-imports cartopy.mpl.ticker \ + --ignore-missing-imports cftime \ + --ignore-missing-imports mpl_toolkits.basemap \ --ignore-missing-imports matplotlib.fontconfig_pattern \ --progress-bar no diff --git a/tools/ci/stub_consumer.py b/tools/ci/stub_consumer.py index 1129ebf3a..1209bd54d 100644 --- a/tools/ci/stub_consumer.py +++ b/tools/ci/stub_consumer.py @@ -1,18 +1,13 @@ """Representative lazy public imports consumed by static type checkers.""" -from collections.abc import Callable -from typing import Any, assert_type - import ultraplot as uplt reveal_type(uplt.subplots) reveal_type(uplt.Axes.format) figure, axes = uplt.subplots() -assert_type(figure, uplt.Figure) -assert_type(axes, uplt.SubplotGrid) -assert_type(axes[0], uplt.Axes) +figure_check: uplt.Figure = figure +axes_check: uplt.SubplotGrid = axes +axis_check: uplt.Axes = axes[0] axes[0].format(title="Static typing") -assert_type(axes.plot, Callable[..., Any]) -_ = axes.plot([0, 1], [0, 1]) reveal_type(axes.plot) From 142614ca71c2ea1d40f100191f71b6d5c9094cc4 Mon Sep 17 00:00:00 2001 From: cvanelteren Date: Fri, 4 Sep 2026 13:55:05 +1000 Subject: [PATCH 8/9] add rst support --- tools/generate_stubs.py | 96 + ultraplot/__init__.pyi | 2 +- ultraplot/_animation.pyi | 6 +- ultraplot/_lazy.pyi | 2 +- ultraplot/_subplots.pyi | 4 +- ultraplot/animation.pyi | 38 +- ultraplot/axes/base.pyi | 680 ++-- ultraplot/axes/cartesian.pyi | 350 +- ultraplot/axes/container.pyi | 2 +- ultraplot/axes/geo.pyi | 306 +- ultraplot/axes/plot.pyi | 5128 +++++++++++++++--------------- ultraplot/axes/polar.pyi | 160 +- ultraplot/axes/shared.pyi | 4 +- ultraplot/axes/taylor.pyi | 160 +- ultraplot/axes/three.pyi | 22 +- ultraplot/colors.pyi | 60 +- ultraplot/config.pyi | 53 +- ultraplot/constructor.pyi | 385 ++- ultraplot/demos.pyi | 56 +- ultraplot/externals/hsluv.pyi | 18 +- ultraplot/figure.pyi | 1049 +++--- ultraplot/gridspec.pyi | 500 +-- ultraplot/internals/__init__.pyi | 4 +- ultraplot/internals/fonts.pyi | 6 +- ultraplot/internals/inputs.pyi | 14 +- ultraplot/legend.pyi | 122 +- ultraplot/proj.pyi | 8 +- ultraplot/scale.pyi | 132 +- ultraplot/tests/test_stubs.py | 9 + ultraplot/text.pyi | 16 +- ultraplot/textalign.pyi | 8 +- ultraplot/ticker.pyi | 32 +- ultraplot/ui.pyi | 258 +- ultraplot/utils.pyi | 44 +- 34 files changed, 4888 insertions(+), 4846 deletions(-) diff --git a/tools/generate_stubs.py b/tools/generate_stubs.py index 48f6c9cd0..32d051e2f 100644 --- a/tools/generate_stubs.py +++ b/tools/generate_stubs.py @@ -18,6 +18,7 @@ from collections import defaultdict, deque from collections.abc import Iterable from pathlib import Path +from urllib.parse import quote_plus ROOT = Path(__file__).resolve().parents[1] PACKAGE = ROOT / "ultraplot" @@ -50,6 +51,25 @@ RUNTIME_DOC_BANNERS = re.compile( r"(?m)^=+\n(ultraplot documentation|Matplotlib documentation)\n=+\n?" ) +RST_LINK_PATTERN = re.compile(r"`([^`<>]+?)\s*<(https?://[^>]+)>`__?") +SPHINX_ROLE_PATTERN = re.compile( + r":(?:(?:py):)?(class|func|meth|attr|obj|mod|data|ref|doc|rc|rcraw|mpltype):" + r"`([^`]+)`" +) +SPHINX_TARGET_PATTERN = re.compile( + r"(? str | None: @@ -506,6 +526,78 @@ def replace(match: re.Match) -> str: return doc.strip() +def _split_sphinx_target(value: str) -> tuple[str, str]: + """Return the display label and canonical target from a Sphinx role body.""" + match = re.fullmatch(r"(.+?)\s*<([^>]+)>", value.strip()) + if match: + return match.group(1).strip(), match.group(2).strip().lstrip("~") + target = value.strip() + shortened = target.startswith("~") + target = target.lstrip("~") + return (target.rsplit(".", 1)[-1] if shortened else target), target + + +def _ultraplot_doc_url(target: str) -> str: + """Return the autosummary URL generated for an UltraPlot API target.""" + parts = target.split(".") + class_index = next( + (index for index, part in enumerate(parts) if part[:1].isupper()), None + ) + if class_index is not None and class_index < len(parts) - 1: + page = ".".join(parts[: class_index + 1]) + return f"https://ultraplot.readthedocs.io/en/stable/api/{page}.html#{target}" + return f"https://ultraplot.readthedocs.io/en/stable/api/{target}.html" + + +def _api_doc_url(target: str, role: str = "obj") -> str | None: + """Resolve common Sphinx API targets without loading remote inventories.""" + if target.startswith("ultraplot."): + return _ultraplot_doc_url(target) + templates = { + "matplotlib.": "https://matplotlib.org/stable/api/_as_gen/{target}.html", + "numpy.": "https://numpy.org/doc/stable/reference/generated/{target}.html", + "scipy.": "https://docs.scipy.org/doc/scipy/reference/generated/{target}.html", + "pandas.": "https://pandas.pydata.org/pandas-docs/stable/reference/api/{target}.html", + "xarray.": "https://docs.xarray.dev/en/stable/generated/{target}.html", + } + for prefix, template in templates.items(): + if target.startswith(prefix): + return template.format(target=target) + if role in {"rc", "rcraw"}: + return DOC_SEARCH_URLS["ultraplot"].format(query=quote_plus(target)) + if role in {"ref", "doc"}: + return DOC_SEARCH_URLS["ultraplot"].format(query=quote_plus(target)) + if role == "mpltype": + return DOC_SEARCH_URLS["matplotlib"].format(query=quote_plus(target)) + project = target.split(".", 1)[0] + if project in DOC_SEARCH_URLS: + return DOC_SEARCH_URLS[project].format(query=quote_plus(target)) + return None + + +def _markdown_api_link(label: str, target: str, role: str = "obj") -> str: + """Render a resolved target as a Markdown link or readable inline code.""" + url = _api_doc_url(target, role) + return f"[{label}]({url})" if url else f"`{label}`" + + +def _linkify_docstring(doc: str) -> str: + """Convert Sphinx links and API roles into LSP-friendly Markdown links.""" + doc = RST_LINK_PATTERN.sub(lambda match: f"[{match.group(1)}]({match.group(2)})", doc) + + def replace_role(match: re.Match) -> str: + role = match.group(1) + label, target = _split_sphinx_target(match.group(2)) + return _markdown_api_link(label, target, role) + + def replace_target(match: re.Match) -> str: + label, target = _split_sphinx_target(match.group(1)) + return _markdown_api_link(label, target) + + doc = SPHINX_ROLE_PATTERN.sub(replace_role, doc) + return SPHINX_TARGET_PATTERN.sub(replace_target, doc) + + class _StubTransformer(ast.NodeTransformer): """Reduce implementation syntax to declarations suitable for ``.pyi`` files.""" @@ -534,6 +626,8 @@ def _doc_body( doc = self._expand_docstring(ast_doc) elif "%(" in doc: doc = self._expand_docstring(doc) + if doc: + doc = _linkify_docstring(doc) body = [] if doc: @@ -592,6 +686,7 @@ def visit_ClassDef(self, node: ast.ClassDef) -> ast.ClassDef: doc = ast.get_docstring(node, clean=True) if doc: doc = self._expand_docstring(doc) + doc = _linkify_docstring(doc) node.body[0] = ast.Expr(value=ast.Constant(doc)) if not node.body: node.body = [ast.Expr(value=ast.Constant(Ellipsis))] @@ -614,6 +709,7 @@ def visit_AsyncFunctionDef( def visit_Expr(self, node: ast.Expr) -> ast.Expr | None: if isinstance(node.value, ast.Constant) and isinstance(node.value.value, str): value = self._expand_docstring(node.value.value) + value = _linkify_docstring(value) return ast.Expr(value=ast.Constant(value)) return None diff --git a/ultraplot/__init__.pyi b/ultraplot/__init__.pyi index 3ed33ba41..8cb79c01a 100644 --- a/ultraplot/__init__.pyi +++ b/ultraplot/__init__.pyi @@ -169,7 +169,7 @@ def __dir__() -> list[str]: ... def _patch_seaborn_move_legend() -> None: - """Let ``sns.move_legend(ax, ...)`` accept singleton :class:`SubplotGrid` objects. + """Let ``sns.move_legend(ax, ...)`` accept singleton `SubplotGrid` objects. Seaborn only accepts native Matplotlib axes, figures, and its own grids. The wrapper unwraps a singleton grid to its underlying axes; callers can avoid diff --git a/ultraplot/_animation.pyi b/ultraplot/_animation.pyi index 8c247090c..22c4c6b33 100644 --- a/ultraplot/_animation.pyi +++ b/ultraplot/_animation.pyi @@ -215,11 +215,11 @@ Backends without blitting support safely fall back to ``draw_idle()``. Parameters ---------- -canvas : `~matplotlib.backend_bases.FigureCanvasBase` +canvas : [FigureCanvasBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.backend_bases.FigureCanvasBase.html) Canvas containing the artists. -artists : iterable of `~matplotlib.artist.Artist`, optional +artists : iterable of [Artist](https://matplotlib.org/stable/api/_as_gen/matplotlib.artist.Artist.html), optional Artists that will change between updates. -bbox : `~matplotlib.transforms.Bbox` or object with a ``bbox`` attribute, optional +bbox : [Bbox](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Bbox.html) or object with a ``bbox`` attribute, optional Region to cache and blit. By default, the union of the managed artists' axes bounding boxes is used. Figure-level artists fall back to the full figure bounding box. diff --git a/ultraplot/_lazy.pyi b/ultraplot/_lazy.pyi index 91a4214cc..2e70a32c7 100644 --- a/ultraplot/_lazy.pyi +++ b/ultraplot/_lazy.pyi @@ -1,7 +1,7 @@ # @generated by tools/generate_stubs.py; do not edit # fmt: off """ -Helpers for lazy attribute loading in :mod:`ultraplot`. +Helpers for lazy attribute loading in [ultraplot](https://ultraplot.readthedocs.io/en/stable/search.html?q=ultraplot). """ from _typeshed import Incomplete import ast diff --git a/ultraplot/_subplots.pyi b/ultraplot/_subplots.pyi index bcfa9a24b..18711a6ef 100644 --- a/ultraplot/_subplots.pyi +++ b/ultraplot/_subplots.pyi @@ -22,7 +22,7 @@ for a Figure instance. Parameters ---------- -figure : `~ultraplot.figure.Figure` +figure : [Figure](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html) The parent figure.""" def __init__(self, figure: 'Figure') -> None: @@ -31,7 +31,7 @@ figure : `~ultraplot.figure.Figure` def reset(self) -> None: """Forget every subplot and release the gridspec. -Called by `~ultraplot.figure.Figure.clear`, which destroys the axes this +Called by [clear](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.clear), which destroys the axes this manager tracks. Without this the figure keeps handing out axes that are no longer attached to it.""" ... diff --git a/ultraplot/animation.pyi b/ultraplot/animation.pyi index aaf440b05..7023116bc 100644 --- a/ultraplot/animation.pyi +++ b/ultraplot/animation.pyi @@ -1,14 +1,14 @@ # @generated by tools/generate_stubs.py; do not edit # fmt: off """ -Fast drop-in replacements for the `matplotlib.animation` classes. +Fast drop-in replacements for the [matplotlib.animation](https://matplotlib.org/stable/api/_as_gen/matplotlib.animation.html) classes. The classes here subclass their Matplotlib counterparts, so the constructor signatures, the attributes, and the notebook representations are unchanged. What differs is how frames are rendered: -* `~ultraplot.animation.FuncAnimation.save` bypasses the per-frame - `~matplotlib.figure.Figure.savefig` call used by Matplotlib's writers and +* [save](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.animation.FuncAnimation.html#ultraplot.animation.FuncAnimation.save) bypasses the per-frame + [savefig](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.savefig.html) call used by Matplotlib's writers and instead renders straight into the Agg buffer, piping raw ``RGBA`` bytes to the encoder. No PNG round-trip, no ``print_figure`` machinery. * The expensive UltraPlot tight-layout pass runs once, for the first frame, @@ -152,7 +152,7 @@ return a different set of artists as the animation goes on.""" def _suspended_event_source(self) -> Incomplete: """Keep the interactive timer from starting on the frames drawn here. -`matplotlib.animation.Animation` starts itself from the figure's first +[matplotlib.animation.Animation](https://matplotlib.org/stable/api/_as_gen/matplotlib.animation.Animation.html) starts itself from the figure's first ``draw_event``. The draws below are for the movie file, not the screen.""" ... @@ -160,8 +160,8 @@ return a different set of artists as the animation goes on.""" def _suspended_figure_blitting(self) -> Incomplete: """Stand down the figure's own retained-draw machinery while saving. -`~ultraplot.figure.Figure.savefig` does the same before printing. A live -`~ultraplot._animation._BlitManager` keeps its artists flagged animated +[savefig](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.savefig) does the same before printing. A live +[_BlitManager](https://ultraplot.readthedocs.io/en/stable/api/ultraplot._animation._BlitManager.html) keeps its artists flagged animated and repaints them from a ``draw_event`` handler, which would fight the frames drawn here.""" ... @@ -193,15 +193,15 @@ Parameters ---------- filename : path-like The output file, e.g. ``'movie.mp4'`` or ``'movie.gif'``. -writer : str or `~matplotlib.animation.AbstractMovieWriter`, optional - Same meaning as in `matplotlib.animation.Animation.save`. Passing a +writer : str or [AbstractMovieWriter](https://matplotlib.org/stable/api/_as_gen/matplotlib.animation.AbstractMovieWriter.html), optional + Same meaning as in [matplotlib.animation.Animation.save](https://matplotlib.org/stable/api/_as_gen/matplotlib.animation.Animation.save.html). Passing a writer *instance*, or a writer the fast path does not implement, transparently falls back to Matplotlib's implementation. fps : int, optional Frames per second. Defaults to the animation interval. dpi : float, optional Resolution of the saved frames. Unlike Matplotlib, which uses - :rc:`savefig.dpi`, this defaults to the figure's own dpi. UltraPlot + [savefig.dpi](https://ultraplot.readthedocs.io/en/stable/search.html?q=savefig.dpi), this defaults to the figure's own dpi. UltraPlot sets ``savefig.dpi`` to 1000 for publication-quality stills, which for a movie means hundredfold larger frames and a hundredfold slower encode. @@ -210,7 +210,7 @@ codec, bitrate, extra_args, metadata : optional extra_anim : list, optional Additional animations to composite. Forces the Matplotlib path. savefig_kwargs : dict, optional - Extra `~matplotlib.figure.Figure.savefig` arguments. Any value here + Extra [savefig](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.savefig.html) arguments. Any value here forces the Matplotlib path, since the fast path skips ``savefig``. progress_callback : callable, optional Called as ``progress_callback(current_frame, total_frames)``. @@ -226,7 +226,7 @@ blit : bool, optional Other Parameters ---------------- -See `matplotlib.animation.Animation.save`. +See [matplotlib.animation.Animation.save](https://matplotlib.org/stable/api/_as_gen/matplotlib.animation.Animation.save.html). See also -------- @@ -234,17 +234,17 @@ matplotlib.animation.Animation.save""" ... class FuncAnimation(_FastSaveMixin, manimation.FuncAnimation): - """A faster drop-in replacement for `matplotlib.animation.FuncAnimation`. + """A faster drop-in replacement for [matplotlib.animation.FuncAnimation](https://matplotlib.org/stable/api/_as_gen/matplotlib.animation.FuncAnimation.html). The signature matches Matplotlib's, with two differences: `blit` defaults to ``True`` instead of ``False``, and `freeze_layout` is added. Saving renders frames directly into the Agg buffer instead of calling -`~matplotlib.figure.Figure.savefig` once per frame, which removes the +[savefig](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.savefig.html) once per frame, which removes the per-frame PNG round-trip and the repeated UltraPlot tight-layout pass. Parameters ---------- -fig : `~ultraplot.figure.Figure` +fig : [Figure](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html) The figure to animate. func : callable The update function, called as ``func(frame, *fargs)``. It should @@ -267,7 +267,7 @@ blit : bool, default: True cache_frame_data : bool, default: True Whether to cache frame data, as in Matplotlib. **kwargs - Passed to `matplotlib.animation.TimedAnimation`, e.g. `interval`, + Passed to [matplotlib.animation.TimedAnimation](https://matplotlib.org/stable/api/_as_gen/matplotlib.animation.TimedAnimation.html), e.g. `interval`, `repeat`, and `repeat_delay`. Examples @@ -303,19 +303,19 @@ ultraplot.animation.ArtistAnimation""" ... class ArtistAnimation(_FastSaveMixin, manimation.ArtistAnimation): - """A faster drop-in replacement for `matplotlib.animation.ArtistAnimation`. + """A faster drop-in replacement for [matplotlib.animation.ArtistAnimation](https://matplotlib.org/stable/api/_as_gen/matplotlib.animation.ArtistAnimation.html). Frames are lists of artists that are made visible in turn. Saving uses the same direct-to-buffer renderer as `FuncAnimation`. Parameters ---------- -fig : `~ultraplot.figure.Figure` +fig : [Figure](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html) The figure to animate. -artists : list of list of `~matplotlib.artist.Artist` +artists : list of list of [Artist](https://matplotlib.org/stable/api/_as_gen/matplotlib.artist.Artist.html) Each entry is the collection of artists making up one frame. **kwargs - Passed to `matplotlib.animation.TimedAnimation`. + Passed to [matplotlib.animation.TimedAnimation](https://matplotlib.org/stable/api/_as_gen/matplotlib.animation.TimedAnimation.html). See also -------- diff --git a/ultraplot/axes/base.pyi b/ultraplot/axes/base.pyi index 37422eeb5..2587cff68 100644 --- a/ultraplot/axes/base.pyi +++ b/ultraplot/axes/base.pyi @@ -146,7 +146,7 @@ value: ... class Axes(_ExternalModeMixin, maxes.Axes): - """The lowest-level `~matplotlib.axes.Axes` subclass used by ultraplot. + """The lowest-level [Axes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html) subclass used by ultraplot. Implements basic universal features.""" _name = None _name_aliases = () @@ -164,18 +164,18 @@ Implements basic universal features.""" """Parameters ---------- *args - Passed to `matplotlib.axes.Axes`. + Passed to [matplotlib.axes.Axes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html). title : str or sequence, optional The axes title. Can optionally be a sequence strings, in which case the title will be selected from the sequence according to `~Axes.number`. -abc : bool or str or sequence, default: :rc:`abc` +abc : bool or str or sequence, default: [abc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc) The "a-b-c" subplot label style. Must contain the character `a` or `A`, for example ``'a.'``, or ``'A'``. If ``True`` then the default style of ``'a'`` is used. The `a` or ``A`` is replaced with the alphabetic character matching the `~Axes.number`. If `~Axes.number` is greater than 26, the characters loop around to a, ..., z, aa, ..., zz, aaa, ..., zzz, etc. Can also be a sequence of strings, in which case the "a-b-c" label will be selected sequentially from the list. For example `axs.format(abc = ["X", "Y"])` for a two-panel figure, and `axes[3:5].format(abc = ["X", "Y"])` for a two-panel subset of a larger figure. -abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` +abcloc, titleloc : str, default: [abc.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.loc), [title.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.loc) Strings indicating the location for the a-b-c label and main title. The following locations are valid: @@ -197,31 +197,31 @@ abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` right of y axis ``'outer right'``, ``'or'`` ======================== ============================ -abcborder, titleborder : bool, default: :rc:`abc.border` and :rc:`title.border` +abcborder, titleborder : bool, default: [abc.border](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.border) and [title.border](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.border) Whether to draw a white border around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes. -abcbbox, titlebbox : bool, default: :rc:`abc.bbox` and :rc:`title.bbox` +abcbbox, titlebbox : bool, default: [abc.bbox](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.bbox) and [title.bbox](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.bbox) Whether to draw a white bbox around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes. -abcpad : float or unit-spec, default: :rc:`abc.pad` +abcpad : float or unit-spec, default: [abc.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.pad) Horizontal offset to shift the a-b-c label position. Positive values move the label right, negative values move it left. This is separate from `abctitlepad`, which controls spacing between abc and title when co-located. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). abc_kw, title_kw : dict-like, optional Additional settings used to update the a-b-c label and title with ``text.update()``. -titlepad : float, default: :rc:`title.pad` +titlepad : float, default: [title.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.pad) The padding for the inner and outer titles and a-b-c labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -titleabove : bool, default: :rc:`title.above` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +titleabove : bool, default: [title.above](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.above) Whether to try to put outer titles and a-b-c labels above panels, colorbars, or legends that are above the axes. -abctitlepad : float, default: :rc:`abc.titlepad` +abctitlepad : float, default: [abc.titlepad](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.titlepad) The horizontal padding between a-b-c labels and titles in the same location. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle : str or sequence, optional Shorthands for the below keywords. lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle : str or sequence, optional @@ -230,25 +230,25 @@ lowerlefttitle, lowercentertitle, lowerrighttitle : str or sequence, optional an alternative to the ``ax.format(title='Title', titleloc=loc)`` workflow and permits adding more than one title-like label for a single axes. a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle : default: - :rc:`axes.alpha` (default: 1.0), :rc:`axes.facecolor` (default: white), :rc:`axes.edgecolor` (default: black), :rc:`axes.linewidth` (default: 0.6), - + [axes.alpha](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.alpha) (default: 1.0), [axes.facecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.facecolor) (default: white), [axes.edgecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.edgecolor) (default: black), [axes.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.linewidth) (default: 0.6), - Additional settings applied to the background patch, and their shorthands. Their defaults values are the ``'axes'`` properties. Other parameters ---------------- rc_mode : int, optional - The context mode passed to `~ultraplot.config.Configurator.context`. + The context mode passed to [context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context). rc_kw : dict-like, optional An alternative to passing extra keyword arguments. See below. **kwargs - Remaining keyword arguments are passed to `matplotlib.axes.Axes`.\\n Keyword arguments that match the name of an `~ultraplot.config.rc` setting are - passed to `ultraplot.config.Configurator.context` and used to update the axes. + Remaining keyword arguments are passed to [matplotlib.axes.Axes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html).\\n Keyword arguments that match the name of an [rc](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.rc.html) setting are + passed to [ultraplot.config.Configurator.context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context) and used to update the axes. If the setting name has "dots" you can simply omit the dots. For example, - ``abc='A.'`` modifies the :rcraw:`abc` setting, ``titleloc='left'`` modifies the - :rcraw:`title.loc` setting, ``gridminor=True`` modifies the :rcraw:`gridminor` - setting, and ``gridbelow=True`` modifies the :rcraw:`grid.below` setting. Many + ``abc='A.'`` modifies the [abc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc) setting, ``titleloc='left'`` modifies the + [title.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.loc) setting, ``gridminor=True`` modifies the [gridminor](https://ultraplot.readthedocs.io/en/stable/search.html?q=gridminor) + setting, and ``gridbelow=True`` modifies the [grid.below](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.below) setting. Many of the keyword arguments documented above are internally applied by retrieving - settings passed to `~ultraplot.config.Configurator.context`. + settings passed to [context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context). See also -------- @@ -476,21 +476,21 @@ target : {'x', 'y'}, optional def format(self, *, title: Incomplete=None, title_kw: Incomplete=None, abc_kw: Incomplete=None, ltitle: Incomplete=None, lefttitle: Incomplete=None, ctitle: Incomplete=None, centertitle: Incomplete=None, rtitle: Incomplete=None, righttitle: Incomplete=None, ultitle: Incomplete=None, upperlefttitle: Incomplete=None, uctitle: Incomplete=None, uppercentertitle: Incomplete=None, urtitle: Incomplete=None, upperrighttitle: Incomplete=None, lltitle: Incomplete=None, lowerlefttitle: Incomplete=None, lctitle: Incomplete=None, lowercentertitle: Incomplete=None, lrtitle: Incomplete=None, lowerrighttitle: Incomplete=None, share_xlabels: Incomplete=None, share_ylabels: Incomplete=None, **kwargs: Incomplete) -> None: """Modify the a-b-c label, axes title(s), and background patch, -and call `ultraplot.figure.Figure.format` on the axes figure. +and call [ultraplot.figure.Figure.format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.format) on the axes figure. Parameters ---------- title : str or sequence, optional The axes title. Can optionally be a sequence strings, in which case the title will be selected from the sequence according to `~Axes.number`. -abc : bool or str or sequence, default: :rc:`abc` +abc : bool or str or sequence, default: [abc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc) The "a-b-c" subplot label style. Must contain the character `a` or `A`, for example ``'a.'``, or ``'A'``. If ``True`` then the default style of ``'a'`` is used. The `a` or ``A`` is replaced with the alphabetic character matching the `~Axes.number`. If `~Axes.number` is greater than 26, the characters loop around to a, ..., z, aa, ..., zz, aaa, ..., zzz, etc. Can also be a sequence of strings, in which case the "a-b-c" label will be selected sequentially from the list. For example `axs.format(abc = ["X", "Y"])` for a two-panel figure, and `axes[3:5].format(abc = ["X", "Y"])` for a two-panel subset of a larger figure. -abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` +abcloc, titleloc : str, default: [abc.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.loc), [title.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.loc) Strings indicating the location for the a-b-c label and main title. The following locations are valid: @@ -512,31 +512,31 @@ abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` right of y axis ``'outer right'``, ``'or'`` ======================== ============================ -abcborder, titleborder : bool, default: :rc:`abc.border` and :rc:`title.border` +abcborder, titleborder : bool, default: [abc.border](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.border) and [title.border](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.border) Whether to draw a white border around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes. -abcbbox, titlebbox : bool, default: :rc:`abc.bbox` and :rc:`title.bbox` +abcbbox, titlebbox : bool, default: [abc.bbox](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.bbox) and [title.bbox](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.bbox) Whether to draw a white bbox around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes. -abcpad : float or unit-spec, default: :rc:`abc.pad` +abcpad : float or unit-spec, default: [abc.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.pad) Horizontal offset to shift the a-b-c label position. Positive values move the label right, negative values move it left. This is separate from `abctitlepad`, which controls spacing between abc and title when co-located. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). abc_kw, title_kw : dict-like, optional Additional settings used to update the a-b-c label and title with ``text.update()``. -titlepad : float, default: :rc:`title.pad` +titlepad : float, default: [title.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.pad) The padding for the inner and outer titles and a-b-c labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -titleabove : bool, default: :rc:`title.above` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +titleabove : bool, default: [title.above](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.above) Whether to try to put outer titles and a-b-c labels above panels, colorbars, or legends that are above the axes. -abctitlepad : float, default: :rc:`abc.titlepad` +abctitlepad : float, default: [abc.titlepad](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.titlepad) The horizontal padding between a-b-c labels and titles in the same location. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle : str or sequence, optional Shorthands for the below keywords. lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle : str or sequence, optional @@ -545,17 +545,17 @@ lowerlefttitle, lowercentertitle, lowerrighttitle : str or sequence, optional an alternative to the ``ax.format(title='Title', titleloc=loc)`` workflow and permits adding more than one title-like label for a single axes. a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle : default: - :rc:`axes.alpha` (default: 1.0), :rc:`axes.facecolor` (default: white), :rc:`axes.edgecolor` (default: black), :rc:`axes.linewidth` (default: 0.6), - + [axes.alpha](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.alpha) (default: 1.0), [axes.facecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.facecolor) (default: white), [axes.edgecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.edgecolor) (default: black), [axes.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.linewidth) (default: 0.6), - Additional settings applied to the background patch, and their shorthands. Their defaults values are the ``'axes'`` properties. Important --------- `abc`, `abcloc`, `titleloc`, `titleabove`, `titlepad`, and -`abctitlepad` are actually :ref:`configuration settings `. +`abctitlepad` are actually [configuration settings](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_config). We explicitly document these arguments here because it is common to -change them for specific axes. But many :ref:`other configuration -settings ` can be passed to ``format`` too. +change them for specific axes. But many [other configuration +settings ](https://ultraplot.readthedocs.io/en/stable/search.html?q=other+configuration%0Asettings+%3Cug_format%3E) can be passed to ``format`` too. Other parameters ---------------- @@ -567,14 +567,14 @@ leftlabels, toplabels, rightlabels, bottomlabels : sequence of str, optional bottom edges of the figure. The length of each list must match the number of subplots along the corresponding edge. leftlabelpad, toplabelpad, rightlabelpad, bottomlabelpad : float or unit-spec, default -: :rc:`leftlabel.pad`, :rc:`toplabel.pad`, :rc:`rightlabel.pad`, :rc:`bottomlabel.pad` +: [leftlabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=leftlabel.pad), [toplabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=toplabel.pad), [rightlabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=rightlabel.pad), [bottomlabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=bottomlabel.pad) The padding between the labels and the axes content. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). leftlabelsharedpad, toplabelsharedpad, rightlabelsharedpad, bottomlabelsharedpad : float or unit-spec, default -: :rc:`leftlabel.sharedpad`, :rc:`toplabel.sharedpad`, :rc:`rightlabel.sharedpad`, :rc:`bottomlabel.sharedpad` +: [leftlabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=leftlabel.sharedpad), [toplabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=toplabel.sharedpad), [rightlabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=rightlabel.sharedpad), [bottomlabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=bottomlabel.sharedpad) The padding between side labels and a shared spanning axis label on the same side. The spanning label is placed outside the side labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). leftlabels_kw, toplabels_kw, rightlabels_kw, bottomlabels_kw : dict-like, optional Additional settings used to update the labels with ``text.update()``. figtitle @@ -582,9 +582,9 @@ figtitle suptitle : str, optional The figure "super" title, centered between the left edge of the leftmost subplot and the right edge of the rightmost subplot. -suptitlepad : float, default: :rc:`suptitle.pad` +suptitlepad : float, default: [suptitle.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=suptitle.pad) The padding between the super title and the axes content. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). suptitle_kw : optional Additional settings used to update the super title with ``text.update()``. includepanels : bool, default: False @@ -592,18 +592,18 @@ includepanels : bool, default: False of the subplot grid and when aligning the `spanx` *x* axis labels and `spany` *y* axis labels along the sides of the subplot grid. rc_mode : int, optional - The context mode passed to `~ultraplot.config.Configurator.context`. + The context mode passed to [context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context). rc_kw : dict-like, optional An alternative to passing extra keyword arguments. See below. **kwargs - Keyword arguments that match the name of an `~ultraplot.config.rc` setting are - passed to `ultraplot.config.Configurator.context` and used to update the axes. + Keyword arguments that match the name of an [rc](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.rc.html) setting are + passed to [ultraplot.config.Configurator.context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context) and used to update the axes. If the setting name has "dots" you can simply omit the dots. For example, - ``abc='A.'`` modifies the :rcraw:`abc` setting, ``titleloc='left'`` modifies the - :rcraw:`title.loc` setting, ``gridminor=True`` modifies the :rcraw:`gridminor` - setting, and ``gridbelow=True`` modifies the :rcraw:`grid.below` setting. Many + ``abc='A.'`` modifies the [abc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc) setting, ``titleloc='left'`` modifies the + [title.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.loc) setting, ``gridminor=True`` modifies the [gridminor](https://ultraplot.readthedocs.io/en/stable/search.html?q=gridminor) + setting, and ``gridbelow=True`` modifies the [grid.below](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.below) setting. Many of the keyword arguments documented above are internally applied by retrieving - settings passed to `~ultraplot.config.Configurator.context`. + settings passed to [context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context). See also -------- @@ -623,7 +623,7 @@ returns False). Parameters ---------- -renderer : `~matplotlib.backend_bases.RendererBase` subclass. +renderer : [RendererBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.backend_bases.RendererBase.html) subclass. Notes ----- @@ -775,53 +775,53 @@ labelright/labelleft respectively.""" def inset(self, *args: Incomplete, **kwargs: Incomplete) -> Axes: """Add an inset axes. -This is similar to `matplotlib.axes.Axes.inset_axes`. +This is similar to [matplotlib.axes.Axes.inset_axes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.inset_axes.html). Parameters ----------- bounds : 4-tuple of float or (4-tuple, transform) The (left, bottom, width, height) coordinates for the axes. To specify the coordinate system alongside the coordinates, pass ``(bounds, transform)``. -transform : {'data', 'axes', 'figure', 'subfigure'} or `~matplotlib.transforms.Transform`, optional +transform : {'data', 'axes', 'figure', 'subfigure'} or [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html), optional The transform used to interpret the bounds. Can be a - :class:`~matplotlib.transforms.Transform` instance or a string representing - the :class:`~matplotlib.axes.Axes.transData`, :class:`~matplotlib.axes.Axes.transAxes`, - :class:`~matplotlib.figure.Figure.transFigure`, or - :class:`~matplotlib.figure.Figure.transSubfigure`, transforms. + [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html) instance or a string representing + the [transData](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.transData.html), [transAxes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.transAxes.html), + [transFigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.transFigure.html), or + [transSubfigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.transSubfigure.html), transforms. Default is to use the same projection as the current axes. proj, projection : -str, :class:`cartopy.crs.Projection`, or :class:`~mpl_toolkits.basemap.Basemap`, optional +str, `cartopy.crs.Projection`, or `Basemap`, optional The map projection specification(s). If ``'cart'`` or ``'cartesian'`` - (the default), a :class:`~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, - a :class:`~ultraplot.axes.PolarAxes` is created. Otherwise, the argument is - interpreted by :class:`~ultraplot.constructor.Proj`, and the result is used - to make a :class:`~ultraplot.axes.GeoAxes` (in this case the argument can be - a :class:`cartopy.crs.Projection` instance, a :class:`~mpl_toolkits.basemap.Basemap` - instance, or a projection name listed in :ref:`this table `). + (the default), a [CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html) is created. If ``'polar'``, + a [PolarAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PolarAxes.html) is created. Otherwise, the argument is + interpreted by [Proj](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Proj.html), and the result is used + to make a [GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.GeoAxes.html) (in this case the argument can be + a `cartopy.crs.Projection` instance, a `Basemap` + instance, or a projection name listed in [this table](https://ultraplot.readthedocs.io/en/stable/search.html?q=proj_table)). proj_kw, projection_kw : dict-like, optional - Keyword arguments passed to :class:`~mpl_toolkits.basemap.Basemap` or - :class:`~cartopy.crs.Projection` classes on instantiation. -backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` - Whether to use :class:`~mpl_toolkits.basemap.Basemap` or - :class:`~cartopy.crs.Projection` for map projections. + Keyword arguments passed to `Basemap` or + `Projection` classes on instantiation. +backend : {'cartopy', 'basemap'}, default: [geo.backend](https://ultraplot.readthedocs.io/en/stable/search.html?q=geo.backend) + Whether to use `Basemap` or + `Projection` for map projections. .. deprecated:: 3.0.0 The ``'basemap'`` backend is deprecated and may be removed in a future release. Please use the ``'cartopy'`` backend instead. zorder : float, default: 4 - The `zorder `__ + The [zorder](https://matplotlib.org/stable/gallery/misc/zorder_demo.html) of the axes. Should be greater than the zorder of elements in the parent axes. zoom : bool, default: True or False Whether to draw lines indicating the inset zoom using `~Axes.indicate_inset_zoom`. The line positions will automatically adjust when the parent or inset axes limits - change. Default is ``True`` only if both axes are `~ultraplot.axes.CartesianAxes`. + change. Default is ``True`` only if both axes are [CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html). zoom_kw : dict, optional Passed to `~Axes.indicate_inset_zoom`. Other parameters ----------------- **kwargs - Passed to `ultraplot.axes.Axes`. + Passed to [ultraplot.axes.Axes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html). Returns -------- @@ -838,53 +838,53 @@ matplotlib.axes.Axes.indicate_inset_zoom""" def inset_axes(self, *args: Incomplete, **kwargs: Incomplete) -> Axes: """Add an inset axes. -This is similar to `matplotlib.axes.Axes.inset_axes`. +This is similar to [matplotlib.axes.Axes.inset_axes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.inset_axes.html). Parameters ----------- bounds : 4-tuple of float or (4-tuple, transform) The (left, bottom, width, height) coordinates for the axes. To specify the coordinate system alongside the coordinates, pass ``(bounds, transform)``. -transform : {'data', 'axes', 'figure', 'subfigure'} or `~matplotlib.transforms.Transform`, optional +transform : {'data', 'axes', 'figure', 'subfigure'} or [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html), optional The transform used to interpret the bounds. Can be a - :class:`~matplotlib.transforms.Transform` instance or a string representing - the :class:`~matplotlib.axes.Axes.transData`, :class:`~matplotlib.axes.Axes.transAxes`, - :class:`~matplotlib.figure.Figure.transFigure`, or - :class:`~matplotlib.figure.Figure.transSubfigure`, transforms. + [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html) instance or a string representing + the [transData](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.transData.html), [transAxes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.transAxes.html), + [transFigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.transFigure.html), or + [transSubfigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.transSubfigure.html), transforms. Default is to use the same projection as the current axes. proj, projection : -str, :class:`cartopy.crs.Projection`, or :class:`~mpl_toolkits.basemap.Basemap`, optional +str, `cartopy.crs.Projection`, or `Basemap`, optional The map projection specification(s). If ``'cart'`` or ``'cartesian'`` - (the default), a :class:`~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, - a :class:`~ultraplot.axes.PolarAxes` is created. Otherwise, the argument is - interpreted by :class:`~ultraplot.constructor.Proj`, and the result is used - to make a :class:`~ultraplot.axes.GeoAxes` (in this case the argument can be - a :class:`cartopy.crs.Projection` instance, a :class:`~mpl_toolkits.basemap.Basemap` - instance, or a projection name listed in :ref:`this table `). + (the default), a [CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html) is created. If ``'polar'``, + a [PolarAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PolarAxes.html) is created. Otherwise, the argument is + interpreted by [Proj](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Proj.html), and the result is used + to make a [GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.GeoAxes.html) (in this case the argument can be + a `cartopy.crs.Projection` instance, a `Basemap` + instance, or a projection name listed in [this table](https://ultraplot.readthedocs.io/en/stable/search.html?q=proj_table)). proj_kw, projection_kw : dict-like, optional - Keyword arguments passed to :class:`~mpl_toolkits.basemap.Basemap` or - :class:`~cartopy.crs.Projection` classes on instantiation. -backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` - Whether to use :class:`~mpl_toolkits.basemap.Basemap` or - :class:`~cartopy.crs.Projection` for map projections. + Keyword arguments passed to `Basemap` or + `Projection` classes on instantiation. +backend : {'cartopy', 'basemap'}, default: [geo.backend](https://ultraplot.readthedocs.io/en/stable/search.html?q=geo.backend) + Whether to use `Basemap` or + `Projection` for map projections. .. deprecated:: 3.0.0 The ``'basemap'`` backend is deprecated and may be removed in a future release. Please use the ``'cartopy'`` backend instead. zorder : float, default: 4 - The `zorder `__ + The [zorder](https://matplotlib.org/stable/gallery/misc/zorder_demo.html) of the axes. Should be greater than the zorder of elements in the parent axes. zoom : bool, default: True or False Whether to draw lines indicating the inset zoom using `~Axes.indicate_inset_zoom`. The line positions will automatically adjust when the parent or inset axes limits - change. Default is ``True`` only if both axes are `~ultraplot.axes.CartesianAxes`. + change. Default is ``True`` only if both axes are [CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html). zoom_kw : dict, optional Passed to `~Axes.indicate_inset_zoom`. Other parameters ----------------- **kwargs - Passed to `ultraplot.axes.Axes`. + Passed to [ultraplot.axes.Axes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html). Returns -------- @@ -906,9 +906,9 @@ This will replace previously drawn zoom indicators. Parameters ----------- -linewidth : unit-spec, default: :rc:`patch.linewidth` +linewidth : unit-spec, default: [patch.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.linewidth) The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). linestyle : str, default: '-' The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. edgecolor : color-spec, default: 'none' @@ -918,13 +918,13 @@ facecolor : color-spec, optional alpha : float, optional The opacity of the patch(es). Inferred from `facecolor` and `edgecolor` by default. Aliases: ``a``, ``alphas``. zorder : float, default: 3.5 - The `zorder `__ of + The [zorder](https://matplotlib.org/stable/gallery/misc/zorder_demo.html) of the indicators. Should be greater than the zorder of elements in the parent axes. Other parameters ----------------- **kwargs - Passed to `~matplotlib.patches.Patch`. + Passed to [Patch](https://matplotlib.org/stable/api/_as_gen/matplotlib.patches.Patch.html). Note ----- @@ -956,18 +956,18 @@ side : str, optional top ``'top'``, ``'t'`` ========== ===================== -width : unit-spec, default: :rc:`subplots.panelwidth` +width : unit-spec, default: [subplots.panelwidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.panelwidth) The panel width. - If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + If float, units are inches. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). space : unit-spec, default: None The fixed space between the panel and the subplot edge. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. - When the :ref:`tight layout algorithm ` is active for the figure, + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). + When the [tight layout algorithm](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_tight) is active for the figure, `space` is computed automatically (see `pad`). Otherwise, `space` is set to a suitable default. -pad : unit-spec, default: :rc:`subplots.panelpad` - The :ref:`tight layout padding ` between the panel and the subplot. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +pad : unit-spec, default: [subplots.panelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.panelpad) + The [tight layout padding](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_tight) between the panel and the subplot. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). row, rows Aliases for `span` for panels on the left or right side (vertical panels). col, cols @@ -990,8 +990,8 @@ share : bool, default: True Other parameters ----------------- **kwargs - Passed to `ultraplot.axes.CartesianAxes`. Supports all valid - `~ultraplot.axes.CartesianAxes.format` keywords. + Passed to [ultraplot.axes.CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html). Supports all valid + [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html#ultraplot.axes.CartesianAxes.format) keywords. Returns -------- @@ -1016,18 +1016,18 @@ side : str, optional top ``'top'``, ``'t'`` ========== ===================== -width : unit-spec, default: :rc:`subplots.panelwidth` +width : unit-spec, default: [subplots.panelwidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.panelwidth) The panel width. - If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + If float, units are inches. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). space : unit-spec, default: None The fixed space between the panel and the subplot edge. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. - When the :ref:`tight layout algorithm ` is active for the figure, + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). + When the [tight layout algorithm](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_tight) is active for the figure, `space` is computed automatically (see `pad`). Otherwise, `space` is set to a suitable default. -pad : unit-spec, default: :rc:`subplots.panelpad` - The :ref:`tight layout padding ` between the panel and the subplot. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +pad : unit-spec, default: [subplots.panelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.panelpad) + The [tight layout padding](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_tight) between the panel and the subplot. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). row, rows Aliases for `span` for panels on the left or right side (vertical panels). col, cols @@ -1050,8 +1050,8 @@ share : bool, default: True Other parameters ----------------- **kwargs - Passed to `ultraplot.axes.CartesianAxes`. Supports all valid - `~ultraplot.axes.CartesianAxes.format` keywords. + Passed to [ultraplot.axes.CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html). Supports all valid + [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html#ultraplot.axes.CartesianAxes.format) keywords. Returns -------- @@ -1065,37 +1065,37 @@ ultraplot.axes.CartesianAxes Parameters ---------- mappable : mappable, colormap-spec, sequence of color-spec, - or sequence of :class:`~matplotlib.artist.Artist` + or sequence of [Artist](https://matplotlib.org/stable/api/_as_gen/matplotlib.artist.Artist.html) There are four options here: - 1. A `~matplotlib.cm.ScalarMappable` (e.g., an object returned by - `~ultraplot.axes.PlotAxes.contourf` or `~ultraplot.axes.PlotAxes.pcolormesh`). - 2. A `~matplotlib.colors.Colormap` or registered colormap name used to build a - `~matplotlib.cm.ScalarMappable` on-the-fly. The colorbar range and ticks depend + 1. A [ScalarMappable](https://matplotlib.org/stable/api/_as_gen/matplotlib.cm.ScalarMappable.html) (e.g., an object returned by + [contourf](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PlotAxes.html#ultraplot.axes.PlotAxes.contourf) or [pcolormesh](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PlotAxes.html#ultraplot.axes.PlotAxes.pcolormesh)). + 2. A [Colormap](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Colormap.html) or registered colormap name used to build a + [ScalarMappable](https://matplotlib.org/stable/api/_as_gen/matplotlib.cm.ScalarMappable.html) on-the-fly. The colorbar range and ticks depend on the arguments `values`, `vmin`, `vmax`, and `norm`. The default for a - :class:`~ultraplot.colors.ContinuousColormap` is ``vmin=0`` and ``vmax=1`` (note that + [ContinuousColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html) is ``vmin=0`` and ``vmax=1`` (note that passing `values` will "discretize" the colormap). The default for a - :class:`~ultraplot.colors.DiscreteColormap` is ``values=np.arange(0, cmap.N)``. + [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html) is ``values=np.arange(0, cmap.N)``. 3. A sequence of hex strings, color names, or RGB[A] tuples. A - :class:`~ultraplot.colors.DiscreteColormap` will be generated from these colors and - used to build a `~matplotlib.cm.ScalarMappable` on-the-fly. The colorbar + [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html) will be generated from these colors and + used to build a [ScalarMappable](https://matplotlib.org/stable/api/_as_gen/matplotlib.cm.ScalarMappable.html) on-the-fly. The colorbar range and ticks depend on the arguments `values`, `norm`, and `norm_kw`. The default is ``values=np.arange(0, len(mappable))``. - 4. A sequence of `matplotlib.artist.Artist` instances (e.g., a list of - `~matplotlib.lines.Line2D` instances returned by `~ultraplot.axes.PlotAxes.plot`). + 4. A sequence of [matplotlib.artist.Artist](https://matplotlib.org/stable/api/_as_gen/matplotlib.artist.Artist.html) instances (e.g., a list of + [Line2D](https://matplotlib.org/stable/api/_as_gen/matplotlib.lines.Line2D.html) instances returned by [plot](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PlotAxes.html#ultraplot.axes.PlotAxes.plot)). A colormap will be generated from the colors of these objects (where the color is determined by ``get_color``, if available, or ``get_facecolor``). The colorbar range and ticks depend on the arguments `values`, `norm`, and `norm_kw`. The default is to infer colorbar ticks and tick labels - by calling `~matplotlib.artist.Artist.get_label` on each artist. + by calling [get_label](https://matplotlib.org/stable/api/_as_gen/matplotlib.artist.Artist.get_label.html) on each artist. values : sequence of float or str, optional - Ignored if `mappable` is a `~matplotlib.cm.ScalarMappable`. This maps the colormap - colors to numeric values using `~ultraplot.colors.DiscreteNorm`. If the colormap is - a :class:`~ultraplot.colors.ContinuousColormap` then its colors will be "discretized". + Ignored if `mappable` is a [ScalarMappable](https://matplotlib.org/stable/api/_as_gen/matplotlib.cm.ScalarMappable.html). This maps the colormap + colors to numeric values using [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html). If the colormap is + a [ContinuousColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html) then its colors will be "discretized". These These can also be strings, in which case the list indices are used for tick locations and the strings are applied as tick labels. - loc, location : int or str, default: :rc:`colorbar.loc` + loc, location : int or str, default: [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) The colorbar location. Valid location keys are shown in the below table. .. _colorbar_table: @@ -1117,17 +1117,17 @@ Parameters shrink Alias for `length`. This is included for consistency with - `matplotlib.figure.Figure.colorbar`. - length : float or unit-spec, default: :rc:`colorbar.length` or :rc:`colorbar.insetlength` + [matplotlib.figure.Figure.colorbar](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.colorbar.html). + length : float or unit-spec, default: [colorbar.length](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.length) or [colorbar.insetlength](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.insetlength) The colorbar length. For outer colorbars, units are relative to the axes - width or height (default is :rcraw:`colorbar.length`). For inset + width or height (default is [colorbar.length](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.length)). For inset colorbars, floats interpreted as em-widths and strings interpreted - by `~ultraplot.utils.units` (default is :rcraw:`colorbar.insetlength`). - width : unit-spec, default: :rc:`colorbar.width` or :rc:`colorbar.insetwidth` + by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html) (default is [colorbar.insetlength](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.insetlength)). + width : unit-spec, default: [colorbar.width](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.width) or [colorbar.insetwidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.insetwidth) The colorbar width. For outer colorbars, floats are interpreted as inches - (default is :rcraw:`colorbar.width`). For inset colorbars, floats are - interpreted as em-widths (default is :rcraw:`colorbar.insetwidth`). - Strings are interpreted by `~ultraplot.utils.units`. + (default is [colorbar.width](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.width)). For inset colorbars, floats are + interpreted as em-widths (default is [colorbar.insetwidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.insetwidth)). + Strings are interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). queue : bool, optional If ``True`` and `loc` is the same as an existing colorbar, the input arguments are added to a queue and this function returns ``None``. @@ -1137,25 +1137,25 @@ Parameters *outer* colorbar, the colorbars are "stacked". space : unit-spec, default: None For outer colorbars only. The fixed space between the colorbar and the subplot - edge. If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. - When the :ref:`tight layout algorithm ` is active for the figure, + edge. If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). + When the [tight layout algorithm](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_tight) is active for the figure, `space` is computed automatically (see `pad`). Otherwise, `space` is set to a suitable default. -pad : unit-spec, default: :rc:`subplots.panelpad` or :rc:`colorbar.insetpad` - For outer colorbars, this is the :ref:`tight layout padding ` - between the colorbar and the subplot (default is :rcraw:`subplots.panelpad`). +pad : unit-spec, default: [subplots.panelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.panelpad) or [colorbar.insetpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.insetpad) + For outer colorbars, this is the [tight layout padding](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_tight) + between the colorbar and the subplot (default is [subplots.panelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.panelpad)). For inset colorbars, this is the fixed space between the axes - edge and the colorbar (default is :rcraw:`colorbar.insetpad`). - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + edge and the colorbar (default is [colorbar.insetpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.insetpad)). + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). align : {'center', 'top', 'bottom', 'left', 'right', 't', 'b', 'l', 'r'}, optional For outer colorbars only. How to align the colorbar against the subplot edge. The values ``'top'`` and ``'bottom'`` are valid for left and right colorbars and ``'left'`` and ``'right'`` are valid for top and bottom colorbars. The default is always ``'center'``. Has no visible effect if `length` is ``1``. - bbox_to_anchor : 2-tuple, 4-tuple, or `matplotlib.transforms.Bbox`, optional + bbox_to_anchor : 2-tuple, 4-tuple, or [matplotlib.transforms.Bbox](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Bbox.html), optional For inset colorbars, anchor the full colorbar footprint using the - same semantics as `~matplotlib.axes.Axes.legend`. The colorbar + same semantics as [legend](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.legend.html). The colorbar `loc` selects the corresponding anchor corner. Outer colorbar placement is unchanged. Other parameters @@ -1164,25 +1164,25 @@ align : {'center', 'top', 'bottom', 'left', 'right', 't', 'b', 'l', 'r'}, option The colorbar orientation. By default this depends on the "side" of the subplot or figure where the colorbar is drawn. Inset colorbars are always horizontal. norm : norm-spec, optional - Ignored if `mappable` is a `~matplotlib.cm.ScalarMappable`. This is the continuous - normalizer used to scale the :class:`~ultraplot.colors.ContinuousColormap` (or passed - to `~ultraplot.colors.DiscreteNorm` if `values` was passed). Passed to the - `~ultraplot.constructor.Norm` constructor function. + Ignored if `mappable` is a [ScalarMappable](https://matplotlib.org/stable/api/_as_gen/matplotlib.cm.ScalarMappable.html). This is the continuous + normalizer used to scale the [ContinuousColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html) (or passed + to [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) if `values` was passed). Passed to the + [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html) constructor function. norm_kw : dict-like, optional - Ignored if `mappable` is a `~matplotlib.cm.ScalarMappable`. These are the - normalizer keyword arguments. Passed to `~ultraplot.constructor.Norm`. + Ignored if `mappable` is a [ScalarMappable](https://matplotlib.org/stable/api/_as_gen/matplotlib.cm.ScalarMappable.html). These are the + normalizer keyword arguments. Passed to [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html). vmin, vmax : float, optional - Ignored if `mappable` is a `~matplotlib.cm.ScalarMappable`. These are the minimum - and maximum colorbar values. Passed to `~ultraplot.constructor.Norm`. + Ignored if `mappable` is a [ScalarMappable](https://matplotlib.org/stable/api/_as_gen/matplotlib.cm.ScalarMappable.html). These are the minimum + and maximum colorbar values. Passed to [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html). label, title : str, optional The colorbar label. The `title` keyword is also accepted for - consistency with `~matplotlib.axes.Axes.legend`. + consistency with [legend](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.legend.html). reverse : bool, optional Whether to reverse the direction of the colorbar. This is done automatically - when descending levels are used with `~ultraplot.colors.DiscreteNorm`. + when descending levels are used with [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html). rotation : float, default: 0 The tick label rotation. -grid, edges, drawedges : bool, default: :rc:`colorbar.grid` +grid, edges, drawedges : bool, default: [colorbar.grid](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.grid) Whether to draw "grid" dividers between each distinct color. extend : {'neither', 'both', 'min', 'max'}, optional Direction for drawing colorbar "extensions" (i.e. color keys for out-of-bounds @@ -1190,76 +1190,76 @@ extend : {'neither', 'both', 'min', 'max'}, optional passed to the plotting command or use ``'neither'`` if the value is unknown. extendfrac : float, optional The length of the colorbar "extensions" relative to the length of the colorbar. - This is a native matplotlib `~matplotlib.figure.Figure.colorbar` keyword. -extendsize : unit-spec, default: :rc:`colorbar.extend` or :rc:`colorbar.insetextend` + This is a native matplotlib [colorbar](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.colorbar.html) keyword. +extendsize : unit-spec, default: [colorbar.extend](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.extend) or [colorbar.insetextend](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.insetextend) The length of the colorbar "extensions" in physical units. Default is - :rcraw:`colorbar.extend` for outer colorbars and :rcraw:`colorbar.insetextend` - for inset colorbars. If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + [colorbar.extend](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.extend) for outer colorbars and [colorbar.insetextend](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.insetextend) + for inset colorbars. If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). extendrect : bool, default: False Whether to draw colorbar "extensions" as rectangles. If ``False`` then the extensions are drawn as triangles. locator, ticks : locator-spec, optional Used to determine the colorbar tick positions. Passed to the - `~ultraplot.constructor.Locator` constructor function. By default - `~matplotlib.ticker.AutoLocator` is used for continuous color levels - and `~ultraplot.ticker.DiscreteLocator` is used for discrete color levels. + [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor function. By default + [AutoLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.AutoLocator.html) is used for continuous color levels + and [DiscreteLocator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.DiscreteLocator.html) is used for discrete color levels. locator_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Locator` class. + Keyword arguments passed to [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. minorlocator, minorticks As with `locator`, `ticks` but for the minor ticks. By default - `~matplotlib.ticker.AutoMinorLocator` is used for continuous color levels - and `~ultraplot.ticker.DiscreteLocator` is used for discrete color levels. + [AutoMinorLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.AutoMinorLocator.html) is used for continuous color levels + and [DiscreteLocator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.DiscreteLocator.html) is used for discrete color levels. minorlocator_kw As with `locator_kw`, but for the minor ticks. format, formatter, ticklabels : formatter-spec, optional - The tick label format. Passed to the `~ultraplot.constructor.Formatter` + The tick label format. Passed to the [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html) constructor function. formatter_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Formatter` class. + Keyword arguments passed to [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) class. frame, frameon : bool, optional For inset colorbars, indicates whether to draw a background "frame", - just like `~matplotlib.axes.Axes.legend`. Defaults to - :rc:`colorbar.frameon` for inset colorbars. For outer colorbars, this is a + just like [legend](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.legend.html). Defaults to + [colorbar.frameon](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.frameon) for inset colorbars. For outer colorbars, this is a backwards-compatible alias for `outline`; when omitted, outer colorbars - still default to :rc:`colorbar.outline`. + still default to [colorbar.outline](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.outline). tickminor : bool, optional - Whether to add minor ticks using `~matplotlib.colorbar.ColorbarBase.minorticks_on`. + Whether to add minor ticks using [minorticks_on](https://matplotlib.org/stable/api/_as_gen/matplotlib.colorbar.ColorbarBase.minorticks_on.html). tickloc, ticklocation : {'bottom', 'top', 'left', 'right'}, optional Where to draw tick marks on the colorbar. Default is toward the outside of the subplot for outer colorbars and ``'bottom'`` for inset colorbars. -tickdir, tickdirection : {'out', 'in', 'inout'}, default: :rc:`tick.dir` +tickdir, tickdirection : {'out', 'in', 'inout'}, default: [tick.dir](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.dir) Direction of major and minor colorbar ticks. -ticklen : unit-spec, default: :rc:`tick.len` +ticklen : unit-spec, default: [tick.len](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.len) Major tick lengths for the colorbar ticks. -ticklenratio : float, default: :rc:`tick.lenratio` +ticklenratio : float, default: [tick.lenratio](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.lenratio) Relative scaling of `ticklen` used to determine minor tick lengths. tickwidth : unit-spec, default: `linewidth` Major tick widths for the colorbar ticks. - or :rc:`tick.width` if `linewidth` was not passed. -tickwidthratio : float, default: :rc:`tick.widthratio` + or [tick.width](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.width) if `linewidth` was not passed. +tickwidthratio : float, default: [tick.widthratio](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.widthratio) Relative scaling of `tickwidth` used to determine minor tick widths. -ticklabelcolor, ticklabelsize, ticklabelweight: default: :rc:`tick.labelcolor`, :rc:`tick.labelsize`, :rc:`tick.labelweight`. +ticklabelcolor, ticklabelsize, ticklabelweight: default: [tick.labelcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.labelcolor), [tick.labelsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.labelsize), [tick.labelweight](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.labelweight). The font color, size, and weight for colorbar tick labels labelloc, labellocation : {'bottom', 'top', 'left', 'right'} The colorbar label location. Inherits from `tickloc` by default. Default is toward the outside of the subplot for outer colorbars and ``'bottom'`` for inset colorbars. -labelcolor, labelsize, labelweight: default: :rc:`label.color`, :rc:`label.size`, and :rc:`label.weight`. +labelcolor, labelsize, labelweight: default: [label.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=label.color), [label.size](https://ultraplot.readthedocs.io/en/stable/search.html?q=label.size), and [label.weight](https://ultraplot.readthedocs.io/en/stable/search.html?q=label.weight). The font color, size, and weight for the colorbar label. -a, alpha, framealpha, fc, facecolor, framecolor, ec, edgecolor, ew, edgewidth : default: :rc:`colorbar.framealpha`, :rc:`colorbar.framecolor` +a, alpha, framealpha, fc, facecolor, framecolor, ec, edgecolor, ew, edgewidth : default: [colorbar.framealpha](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.framealpha), [colorbar.framecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.framecolor) For inset colorbars only. Controls the transparency and color of the background frame. lw, linewidth, c, color : optional Controls the line width and edge color for both the colorbar outline and the level dividers. -edgefix : bool or float, default: :rc:`edgefix` +edgefix : bool or float, default: [edgefix](https://ultraplot.readthedocs.io/en/stable/search.html?q=edgefix) Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). - See this `github repo `__ for a + See this [github repo](https://github.com/jklymak/contourfIssues) for a demonstration of the problem. If ``True``, a small default linewidth of ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), this specific linewidth is used to cover up the white lines. This feature is automatically disabled when the patches have transparency. -rasterize : bool, default: :rc:`colorbar.rasterized` +rasterize : bool, default: [colorbar.rasterized](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.rasterized) Whether to rasterize the colorbar solids. The matplotlib default was ``True`` but ultraplot changes this to ``False`` since rasterization can cause misalignment between the color patches and the colorbar outline. @@ -1273,7 +1273,7 @@ labelrotation : str, float, default: None **kwargs - Passed to `~matplotlib.figure.Figure.colorbar`. + Passed to [colorbar](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.colorbar.html). See also -------- @@ -1289,24 +1289,23 @@ Parameters handles : list of artist, optional List of matplotlib artists, or a list of lists of artist instances (see the `center` keyword). If not passed, artists with valid labels (applied by passing `label` or - `labels` to a plotting command or calling `~matplotlib.artist.Artist.set_label`) - are retrieved automatically. If the object is a `~matplotlib.contour.ContourSet`, - `~matplotlib.contour.ContourSet.legend_elements` is used to select the central + `labels` to a plotting command or calling [set_label](https://matplotlib.org/stable/api/_as_gen/matplotlib.artist.Artist.set_label.html)) + are retrieved automatically. If the object is a [ContourSet](https://matplotlib.org/stable/api/_as_gen/matplotlib.contour.ContourSet.html), + [legend_elements](https://matplotlib.org/stable/api/_as_gen/matplotlib.contour.ContourSet.legend_elements.html) is used to select the central artist in the list (generally useful for single-color contour plots). Note that - ultraplot's `~ultraplot.axes.PlotAxes.contour` and `~ultraplot.axes.PlotAxes.contourf` + ultraplot's [contour](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PlotAxes.html#ultraplot.axes.PlotAxes.contour) and [contourf](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PlotAxes.html#ultraplot.axes.PlotAxes.contourf) accept a legend `label` keyword argument. labels : list of str, optional A matching list of string labels or ``None`` placeholders, or a matching list of lists (see the `center` keyword). Wherever ``None`` appears in the list (or if no labels were passed at all), labels are retrieved by calling - `~matplotlib.artist.Artist.get_label` on each `~matplotlib.artist.Artist` in the + [get_label](https://matplotlib.org/stable/api/_as_gen/matplotlib.artist.Artist.get_label.html) on each [Artist](https://matplotlib.org/stable/api/_as_gen/matplotlib.artist.Artist.html) in the handle list. If a handle consists of a tuple group of artists, labels are inferred from the artists in the tuple (if there are multiple unique labels in the tuple group of artists, the tuple group is expanded into unique legend entries -- otherwise, the tuple group elements are drawn on top of eachother). For details - on matplotlib legend handlers and tuple groups, see the matplotlib `legend guide -`__. -loc, location : int or str, default: :rc:`legend.loc` + on matplotlib legend handlers and tuple groups, see the matplotlib [legend guide](https://matplotlib.org/stable/tutorials/intermediate/legend_guide.html). +loc, location : int or str, default: [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) The legend location. Valid location keys are shown in the below table. .. _legend_table: @@ -1333,9 +1332,8 @@ loc, location : int or str, default: :rc:`legend.loc` width : unit-spec, optional For outer legends only. The space allocated for the legend - box. This does nothing if the :ref:`tight layout algorithm - ` is active for the figure. - If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + box. This does nothing if the [tight layout algorithm](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_tight) is active for the figure. + If float, units are inches. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). queue : bool, optional If ``True`` and `loc` is the same as an existing legend, the input arguments are added to a queue and this function returns ``None``. @@ -1345,16 +1343,16 @@ queue : bool, optional *outer* legend, the legends are "stacked". space : unit-spec, default: None For outer legends only. The fixed space between the legend and the subplot - edge. If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. - When the :ref:`tight layout algorithm ` is active for the figure, + edge. If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). + When the [tight layout algorithm](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_tight) is active for the figure, `space` is computed automatically (see `pad`). Otherwise, `space` is set to a suitable default. -pad : unit-spec, default: :rc:`subplots.panelpad` or :rc:`legend.borderaxespad` - For outer legends, this is the :ref:`tight layout padding ` - between the legend and the subplot (default is :rcraw:`subplots.panelpad`). +pad : unit-spec, default: [subplots.panelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.panelpad) or [legend.borderaxespad](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.borderaxespad) + For outer legends, this is the [tight layout padding](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_tight) + between the legend and the subplot (default is [subplots.panelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.panelpad)). For inset legends, this is the fixed space between the axes - edge and the legend (default is :rcraw:`legend.borderaxespad`). - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + edge and the legend (default is [legend.borderaxespad](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.borderaxespad)). + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). align : {'center', 'top', 'bottom', 'left', 'right', 't', 'b', 'l', 'r'}, optional For outer legends only. How to align the legend against the subplot edge. The values ``'top'`` and ``'bottom'`` are valid for left and right legends @@ -1368,10 +1366,10 @@ frame, frameon : bool, optional independent from matplotlib's built-in legend frame is created. ncol, ncols : int, optional The number of columns. `ncols` is an alias, added - for consistency with `~matplotlib.pyplot.subplots`. + for consistency with [subplots](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.subplots.html). order : {'C', 'F'}, optional Whether legend handles are drawn in row-major (``'C'``) or column-major - (``'F'``) order. Analagous to `numpy.array` ordering. The matplotlib + (``'F'``) order. Analagous to [numpy.array](https://numpy.org/doc/stable/reference/generated/numpy.array.html) ordering. The matplotlib default was ``'F'`` but ultraplot changes this to ``'C'``. center : bool, optional Whether to center each legend row individually. If ``True``, we draw @@ -1383,17 +1381,17 @@ alphabetize : bool, default: False the legend labels. title, label : str, optional The legend title. The `label` keyword is also accepted, for consistency - with `~matplotlib.figure.Figure.colorbar`. + with [colorbar](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.colorbar.html). fontsize, fontweight, fontcolor : optional The font size, weight, and color for the legend text. Font size is interpreted - by `~ultraplot.utils.units`. The default font size is :rcraw:`legend.fontsize`. + by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). The default font size is [legend.fontsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.fontsize). titlefontsize, titlefontweight, titlefontcolor : optional The font size, weight, and color for the legend title. Font size is interpreted - by `~ultraplot.utils.units`. The default size is `fontsize`. + by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). The default size is `fontsize`. borderpad, borderaxespad, handlelength, handleheight, handletextpad, labelspacing, columnspacing : unit-spec, optional - Various matplotlib `~matplotlib.axes.Axes.legend` spacing arguments. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -a, alpha, framealpha, fc, facecolor, framecolor, ec, edgecolor, ew, edgewidth: default: :rc:`legend.framealpha`, :rc:`legend.facecolor`, :rc:`legend.edgecolor`, :rc:`axes.linewidth` The opacity, face color, edge color, and edge width for the legend frame. + Various matplotlib [legend](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.legend.html) spacing arguments. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +a, alpha, framealpha, fc, facecolor, framecolor, ec, edgecolor, ew, edgewidth: default: [legend.framealpha](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.framealpha), [legend.facecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.facecolor), [legend.edgecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.edgecolor), [axes.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.linewidth) The opacity, face color, edge color, and edge width for the legend frame. c, color, lw, linewidth, m, marker, ls, linestyle, dashes, ms, markersize : optional Properties used to override the legend handles. For example, for a legend describing variations in line style ignoring variations @@ -1405,9 +1403,9 @@ handle_kw : dict-like, optional handler_map : dict-like, optional A dictionary mapping instances or types to a legend handler. This `handler_map` updates the default handler map found at - `matplotlib.legend.Legend.get_legend_handler_map`. + [matplotlib.legend.Legend.get_legend_handler_map](https://matplotlib.org/stable/api/_as_gen/matplotlib.legend.Legend.get_legend_handler_map.html). **kwargs - Passed to `~matplotlib.axes.Axes.legend`. + Passed to [legend](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.legend.html). See also -------- @@ -1436,7 +1434,7 @@ when you do not pass in any extra arguments. In this case, the labels are taken from the artist. You can specify them either at artist creation or by calling the -:meth:`~.Artist.set_label` method on the artist:: +`set_label` method on the artist:: ax.plot([1, 2, 3], label='Inline label') ax.legend() @@ -1513,12 +1511,12 @@ labels : list of str, optional Returns ------- -`~matplotlib.legend.Legend` +[Legend](https://matplotlib.org/stable/api/_as_gen/matplotlib.legend.Legend.html) Other Parameters ---------------- -loc : str or pair of floats, default: :rc:`legend.loc` +loc : str or pair of floats, default: [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) The location of the legend. The strings ``'upper left'``, ``'upper right'``, ``'lower left'``, @@ -1589,29 +1587,29 @@ ncols : int, default: 1 For backward compatibility, the spelling *ncol* is also supported but it is discouraged. If both are given, *ncols* takes precedence. -prop : None or `~matplotlib.font_manager.FontProperties` or dict +prop : None or [FontProperties](https://matplotlib.org/stable/api/_as_gen/matplotlib.font_manager.FontProperties.html) or dict The font properties of the legend. If None (default), the current - :data:`matplotlib.rcParams` will be used. + [matplotlib.rcParams](https://matplotlib.org/stable/api/_as_gen/matplotlib.rcParams.html) will be used. fontsize : int or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'} The font size of the legend. If the value is numeric the size will be the absolute font size in points. String values are relative to the current default font size. This argument is only used if *prop* is not specified. -labelcolor : str or list, default: :rc:`legend.labelcolor` +labelcolor : str or list, default: [legend.labelcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.labelcolor) The color of the text in the legend. Either a valid color string (for example, 'red'), or a list of color strings. The labelcolor can also be made to match the color of the line or marker using 'linecolor', 'markerfacecolor' (or 'mfc'), or 'markeredgecolor' (or 'mec'). - Labelcolor can be set globally using :rc:`legend.labelcolor`. If None, - use :rc:`text.color`. + Labelcolor can be set globally using [legend.labelcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.labelcolor). If None, + use [text.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=text.color). -numpoints : int, default: :rc:`legend.numpoints` +numpoints : int, default: [legend.numpoints](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.numpoints) The number of marker points in the legend when creating a legend entry for a `.Line2D` (line). -scatterpoints : int, default: :rc:`legend.scatterpoints` +scatterpoints : int, default: [legend.scatterpoints](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.scatterpoints) The number of marker points in the legend when creating a legend entry for a `.PathCollection` (scatter plot). @@ -1621,7 +1619,7 @@ scatteryoffsets : iterable of floats, default: ``[0.375, 0.5, 0.3125]`` legend text, and 1.0 is at the top. To draw all markers at the same height, set to ``[0.5]``. -markerscale : float, default: :rc:`legend.markerscale` +markerscale : float, default: [legend.markerscale](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.markerscale) The relative size of legend markers compared to the originally drawn ones. markerfirst : bool, default: True @@ -1634,50 +1632,50 @@ reverse : bool, default: False .. versionadded:: 3.7 -frameon : bool, default: :rc:`legend.frameon` +frameon : bool, default: [legend.frameon](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.frameon) Whether the legend should be drawn on a patch (frame). -fancybox : bool, default: :rc:`legend.fancybox` +fancybox : bool, default: [legend.fancybox](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.fancybox) Whether round edges should be enabled around the `.FancyBboxPatch` which makes up the legend's background. -shadow : None, bool or dict, default: :rc:`legend.shadow` +shadow : None, bool or dict, default: [legend.shadow](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.shadow) Whether to draw a shadow behind the legend. The shadow can be configured using `.Patch` keywords. - Customization via :rc:`legend.shadow` is currently not supported. + Customization via [legend.shadow](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.shadow) is currently not supported. -framealpha : float, default: :rc:`legend.framealpha` +framealpha : float, default: [legend.framealpha](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.framealpha) The alpha transparency of the legend's background. If *shadow* is activated and *framealpha* is ``None``, the default value is ignored. -facecolor : "inherit" or color, default: :rc:`legend.facecolor` +facecolor : "inherit" or color, default: [legend.facecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.facecolor) The legend's background color. - If ``"inherit"``, use :rc:`axes.facecolor`. + If ``"inherit"``, use [axes.facecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.facecolor). -edgecolor : "inherit" or color, default: :rc:`legend.edgecolor` +edgecolor : "inherit" or color, default: [legend.edgecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.edgecolor) The legend's background patch edge color. - If ``"inherit"``, use :rc:`axes.edgecolor`. + If ``"inherit"``, use [axes.edgecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.edgecolor). mode : {"expand", None} If *mode* is set to ``"expand"`` the legend will be horizontally expanded to fill the Axes area (or *bbox_to_anchor* if defines the legend's size). -bbox_transform : None or `~matplotlib.transforms.Transform` +bbox_transform : None or [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html) The transform for the bounding box (*bbox_to_anchor*). For a value of ``None`` (default) the Axes' - :data:`~matplotlib.axes.Axes.transAxes` transform will be used. + [transAxes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.transAxes.html) transform will be used. title : str or None The legend's title. Default is no title (``None``). -title_fontproperties : None or `~matplotlib.font_manager.FontProperties` or dict +title_fontproperties : None or [FontProperties](https://matplotlib.org/stable/api/_as_gen/matplotlib.font_manager.FontProperties.html) or dict The font properties of the legend's title. If None (default), the *title_fontsize* argument will be used if present; if *title_fontsize* is - also None, the current :rc:`legend.title_fontsize` will be used. + also None, the current [legend.title_fontsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.title_fontsize) will be used. -title_fontsize : int or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}, default: :rc:`legend.title_fontsize` +title_fontsize : int or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}, default: [legend.title_fontsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.title_fontsize) The font size of the legend's title. Note: This cannot be combined with *title_fontproperties*. If you want to set the fontsize alongside other font properties, use the *size* @@ -1687,31 +1685,31 @@ alignment : {'center', 'left', 'right'}, default: 'center' The alignment of the legend title and the box of entries. The entries are aligned as a single block, so that markers always lined up. -borderpad : float, default: :rc:`legend.borderpad` +borderpad : float, default: [legend.borderpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.borderpad) The fractional whitespace inside the legend border, in font-size units. -labelspacing : float, default: :rc:`legend.labelspacing` +labelspacing : float, default: [legend.labelspacing](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.labelspacing) The vertical space between the legend entries, in font-size units. -handlelength : float, default: :rc:`legend.handlelength` +handlelength : float, default: [legend.handlelength](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.handlelength) The length of the legend handles, in font-size units. -handleheight : float, default: :rc:`legend.handleheight` +handleheight : float, default: [legend.handleheight](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.handleheight) The height of the legend handles, in font-size units. -handletextpad : float, default: :rc:`legend.handletextpad` +handletextpad : float, default: [legend.handletextpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.handletextpad) The pad between the legend handle and text, in font-size units. -borderaxespad : float, default: :rc:`legend.borderaxespad` +borderaxespad : float, default: [legend.borderaxespad](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.borderaxespad) The pad between the Axes and legend border, in font-size units. -columnspacing : float, default: :rc:`legend.columnspacing` +columnspacing : float, default: [legend.columnspacing](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.columnspacing) The spacing between columns, in font-size units. handler_map : dict or None The custom dictionary mapping instances or types to a legend handler. This *handler_map* updates the default handler map - found at `matplotlib.legend.Legend.get_legend_handler_map`. + found at [matplotlib.legend.Legend.get_legend_handler_map](https://matplotlib.org/stable/api/_as_gen/matplotlib.legend.Legend.get_legend_handler_map.html). draggable : bool, default: False Whether the legend can be dragged with the mouse. @@ -1724,7 +1722,7 @@ See Also Notes ----- Some artists are not supported by this function. See -:ref:`legend_guide` for details. +[legend_guide](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend_guide) for details. Examples -------- @@ -1735,7 +1733,7 @@ Examples """Back-compatibility alias for older Matplotlib/Seaborn integrations that call ``add_legend``. -Newer code should call :meth:`legend`, but some callers still rely on this +Newer code should call `legend`, but some callers still rely on this Matplotlib-internal entry point.""" ... @@ -1758,10 +1756,10 @@ color, marker rather than as per-entry values, so ``color=[0.5, 0.5, 0.5]`` and ``color=(0.5, 0.5, 0.5)`` behave the same. Defaults to ultraplot's color cycle for ``color`` and ``"o"`` for - ``marker`` (or :rc:`legend.cat.marker` when set). + ``marker`` (or [legend.cat.marker](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.cat.marker) when set). line : bool, optional Whether to render connector lines through the markers. Falls back - to :rc:`legend.cat.line`. Setting a non-default ``linestyle`` + to [legend.cat.line](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.cat.line). Setting a non-default ``linestyle`` implicitly enables this. Other parameters ---------------- @@ -1802,7 +1800,7 @@ Each value accepts the scalar / sequence / mapping forms described in handle_kw : dict, optional Style overrides applied to each generated handle. Same vocabulary as ``**kwargs``; useful when style kwargs would otherwise collide with - matplotlib's :class:`~matplotlib.legend.Legend` keywords (``loc``, + matplotlib's [Legend](https://matplotlib.org/stable/api/_as_gen/matplotlib.legend.Legend.html) keywords (``loc``, ``title``, …). add : bool, default: True When ``True`` (default), draw the legend on the axes and return the @@ -1810,7 +1808,7 @@ add : bool, default: True drawing — useful for composing into a parent legend. **kwargs Style keywords applied per entry (see above), plus any - :class:`~matplotlib.legend.Legend` keyword. + [Legend](https://matplotlib.org/stable/api/_as_gen/matplotlib.legend.Legend.html) keyword. See also -------- @@ -1830,7 +1828,7 @@ entries : iterable or mapping to style-kwargs dict. line : bool, optional Whether each entry shows a connector line. Falls back to - :rc:`legend.cat.line`. + [legend.cat.line](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.cat.line). marker, color A style value resolved per legend entry. Accepts a **scalar** (applied to every entry), a **list / tuple / ndarray** (one value per entry, @@ -1879,7 +1877,7 @@ Each value accepts the scalar / sequence / mapping forms described in handle_kw : dict, optional Style overrides applied to each generated handle. Same vocabulary as ``**kwargs``; useful when style kwargs would otherwise collide with - matplotlib's :class:`~matplotlib.legend.Legend` keywords (``loc``, + matplotlib's [Legend](https://matplotlib.org/stable/api/_as_gen/matplotlib.legend.Legend.html) keywords (``loc``, ``title``, …). add : bool, default: True When ``True`` (default), draw the legend on the axes and return the @@ -1887,7 +1885,7 @@ add : bool, default: True drawing — useful for composing into a parent legend. **kwargs Style keywords applied per entry (see above), plus any - :class:`~matplotlib.legend.Legend` keyword. + [Legend](https://matplotlib.org/stable/api/_as_gen/matplotlib.legend.Legend.html) keyword. See also -------- @@ -1916,17 +1914,17 @@ color, marker sequence of floats in ``[0, 1]`` is treated as a single RGB(A) color rather than as per-entry values, so ``color=[0.5, 0.5, 0.5]`` and ``color=(0.5, 0.5, 0.5)`` behave the same. - Defaults to :rc:`legend.size.color` and :rc:`legend.size.marker`. + Defaults to [legend.size.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.size.color) and [legend.size.marker](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.size.marker). area : bool, optional Treat ``levels`` as marker areas (``True``, default) or diameters (``False``). Areas are converted with - ``ms = sqrt(level) * scale``. Falls back to :rc:`legend.size.area`. + ``ms = sqrt(level) * scale``. Falls back to [legend.size.area](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.size.area). values : array-like, optional Full scatter-size data used to infer the scaling range for ``levels``. When provided, or when any of ``vmin``, ``vmax``, ``smin``, ``smax``, ``area_size``, or ``absolute_size`` are provided, ``levels`` are transformed with the same size scaling - rules used by :meth:`~ultraplot.axes.PlotAxes.scatter` while + rules used by [scatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PlotAxes.html#ultraplot.axes.PlotAxes.scatter) while labels remain based on the original ``levels``. When these options are omitted and a compatible UltraPlot scatter artist already exists on the axes, its size scale is inferred automatically. @@ -1935,21 +1933,21 @@ vmin, vmax : float, optional finite range of ``values`` or ``levels``. smin, smax : float, optional Minimum and maximum scaled marker sizes, with the same meaning as - in :meth:`~ultraplot.axes.PlotAxes.scatter`. + in [scatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PlotAxes.html#ultraplot.axes.PlotAxes.scatter). area_size, absolute_size : bool, optional Scatter-style size scaling switches. Defaults match - :meth:`~ultraplot.axes.PlotAxes.scatter` when scatter-style scaling + [scatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PlotAxes.html#ultraplot.axes.PlotAxes.scatter) when scatter-style scaling is active. When scatter-style scaling is active and ``area_size`` is omitted, an explicit ``area=False`` is treated like ``area_size=False``. scale : float, optional Multiplier applied after area/diameter conversion. - Falls back to :rc:`legend.size.scale`. + Falls back to [legend.size.scale](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.size.scale). minsize : float, optional Lower bound on rendered marker size. - Falls back to :rc:`legend.size.minsize`. + Falls back to [legend.size.minsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.size.minsize). fmt : str or callable, optional - Format used to label levels. Falls back to :rc:`legend.size.format`. + Format used to label levels. Falls back to [legend.size.format](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.size.format). Other parameters ---------------- @@ -1990,7 +1988,7 @@ Each value accepts the scalar / sequence / mapping forms described in handle_kw : dict, optional Style overrides applied to each generated handle. Same vocabulary as ``**kwargs``; useful when style kwargs would otherwise collide with - matplotlib's :class:`~matplotlib.legend.Legend` keywords (``loc``, + matplotlib's [Legend](https://matplotlib.org/stable/api/_as_gen/matplotlib.legend.Legend.html) keywords (``loc``, ``title``, …). add : bool, default: True When ``True`` (default), draw the legend on the axes and return the @@ -1998,7 +1996,7 @@ add : bool, default: True drawing — useful for composing into a parent legend. **kwargs Style keywords applied per entry (see above), plus any - :class:`~matplotlib.legend.Legend` keyword. + [Legend](https://matplotlib.org/stable/api/_as_gen/matplotlib.legend.Legend.html) keyword. See also -------- @@ -2019,15 +2017,15 @@ vmin, vmax : float, optional Limits for sampling ``cmap`` when ``norm`` is not provided. n : int, optional Number of levels to sample when ``levels`` is omitted. - Falls back to :rc:`legend.num.n`. -cmap : str or `~matplotlib.colors.Colormap`, optional + Falls back to [legend.num.n](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.num.n). +cmap : str or [Colormap](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Colormap.html), optional Colormap used to color the patches. - Falls back to :rc:`legend.num.cmap`. -norm : `~matplotlib.colors.Normalize`, optional + Falls back to [legend.num.cmap](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.num.cmap). +norm : [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html), optional Normalization applied to ``levels`` before colormap lookup. fmt : str or callable, optional Format used to label levels. - Falls back to :rc:`legend.num.format`. + Falls back to [legend.num.format](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.num.format). facecolor, edgecolor A style value resolved per legend entry. Accepts a **scalar** (applied to every entry), a **list / tuple / ndarray** (one value per entry, @@ -2038,11 +2036,11 @@ facecolor, edgecolor rather than as per-entry values, so ``color=[0.5, 0.5, 0.5]`` and ``color=(0.5, 0.5, 0.5)`` behave the same. ``facecolor`` defaults to colormap-derived values; ``edgecolor`` - falls back to :rc:`legend.num.edgecolor`. + falls back to [legend.num.edgecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.num.edgecolor). linewidth, linestyle, alpha Patch outline width, style, and transparency. ``linewidth`` / - ``alpha`` fall back to :rc:`legend.num.linewidth` / - :rc:`legend.num.alpha`. + ``alpha`` fall back to [legend.num.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.num.linewidth) / + [legend.num.alpha](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.num.alpha). Other parameters ---------------- @@ -2070,7 +2068,7 @@ Each value accepts the scalar / sequence / mapping forms described in handle_kw : dict, optional Style overrides applied to each generated handle. Same vocabulary as ``**kwargs``; useful when style kwargs would otherwise collide with - matplotlib's :class:`~matplotlib.legend.Legend` keywords (``loc``, + matplotlib's [Legend](https://matplotlib.org/stable/api/_as_gen/matplotlib.legend.Legend.html) keywords (``loc``, ``title``, …). add : bool, default: True When ``True`` (default), draw the legend on the axes and return the @@ -2078,7 +2076,7 @@ add : bool, default: True drawing — useful for composing into a parent legend. **kwargs Style keywords applied per entry (see above), plus any - :class:`~matplotlib.legend.Legend` keyword. + [Legend](https://matplotlib.org/stable/api/_as_gen/matplotlib.legend.Legend.html) keyword. See also -------- @@ -2101,17 +2099,17 @@ labels : iterable, optional Labels overriding those derived from ``entries``. country_reso : str, optional Natural Earth resolution for country geometries (e.g. ``"110m"``). - Falls back to :rc:`legend.geo.country_reso`. + Falls back to [legend.geo.country_reso](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.geo.country_reso). country_territories : bool, optional Whether country lookups include overseas territories. - Falls back to :rc:`legend.geo.country_territories`. + Falls back to [legend.geo.country_territories](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.geo.country_territories). country_proj : any, optional Projection used to render country geometries; ignored for non- - country entries. Falls back to :rc:`legend.geo.country_proj`. + country entries. Falls back to [legend.geo.country_proj](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.geo.country_proj). handlesize : float, optional Multiplier applied to legend ``handlelength`` / ``handleheight`` to enlarge geometry handles. Falls back to - :rc:`legend.geo.handlesize`. Must be positive. + [legend.geo.handlesize](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.geo.handlesize). Must be positive. facecolor, edgecolor A style value resolved per legend entry. Accepts a **scalar** (applied to every entry), a **list / tuple / ndarray** (one value per entry, @@ -2121,11 +2119,11 @@ facecolor, edgecolor sequence of floats in ``[0, 1]`` is treated as a single RGB(A) color rather than as per-entry values, so ``color=[0.5, 0.5, 0.5]`` and ``color=(0.5, 0.5, 0.5)`` behave the same. - Default to :rc:`legend.geo.facecolor` / :rc:`legend.geo.edgecolor`. + Default to [legend.geo.facecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.geo.facecolor) / [legend.geo.edgecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.geo.edgecolor). linewidth, alpha, fill Patch outline width, transparency, and fill toggle. - Defaults from :rc:`legend.geo.linewidth` / :rc:`legend.geo.alpha` / - :rc:`legend.geo.fill`. + Defaults from [legend.geo.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.geo.linewidth) / [legend.geo.alpha](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.geo.alpha) / + [legend.geo.fill](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.geo.fill). Other parameters ---------------- @@ -2153,7 +2151,7 @@ Each value accepts the scalar / sequence / mapping forms described in handle_kw : dict, optional Style overrides applied to each generated handle. Same vocabulary as ``**kwargs``; useful when style kwargs would otherwise collide with - matplotlib's :class:`~matplotlib.legend.Legend` keywords (``loc``, + matplotlib's [Legend](https://matplotlib.org/stable/api/_as_gen/matplotlib.legend.Legend.html) keywords (``loc``, ``title``, …). add : bool, default: True When ``True`` (default), draw the legend on the axes and return the @@ -2161,7 +2159,7 @@ add : bool, default: True drawing — useful for composing into a parent legend. **kwargs Style keywords applied per entry (see above), plus any - :class:`~matplotlib.legend.Legend` keyword. + [Legend](https://matplotlib.org/stable/api/_as_gen/matplotlib.legend.Legend.html) keyword. Notes ----- @@ -2197,24 +2195,24 @@ Axes.numlegend""" Parameters ---------- x, y, [z] : float - The coordinates for the text. `~ultraplot.axes.ThreeAxes` accept an + The coordinates for the text. [ThreeAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.ThreeAxes.html) accept an optional third coordinate. If only two are provided this automatically redirects to the `~mpl_toolkits.mplot3d.Axes3D.text2D` method. s, text : str The string for the text. -transform : {'data', 'axes', 'figure', 'subfigure'} or `~matplotlib.transforms.Transform`, optional +transform : {'data', 'axes', 'figure', 'subfigure'} or [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html), optional The transform used to interpret the bounds. Can be a - :class:`~matplotlib.transforms.Transform` instance or a string representing - the :class:`~matplotlib.axes.Axes.transData`, :class:`~matplotlib.axes.Axes.transAxes`, - :class:`~matplotlib.figure.Figure.transFigure`, or - :class:`~matplotlib.figure.Figure.transSubfigure`, transforms. + [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html) instance or a string representing + the [transData](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.transData.html), [transAxes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.transAxes.html), + [transFigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.transFigure.html), or + [transSubfigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.transSubfigure.html), transforms. Other parameters ---------------- -avoid_overlap : bool, default: :rc:`text.align` +avoid_overlap : bool, default: [text.align](https://ultraplot.readthedocs.io/en/stable/search.html?q=text.align) Whether to automatically nudge this text at draw time so it does not overlap other auto-aligned text or the plotted data. See - `~ultraplot.axes.Axes.auto_align_text` for the solver settings. + [auto_align_text](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.auto_align_text) for the solver settings. border : bool, default: False Whether to draw border around text. borderwidth : float, default: 2 @@ -2223,8 +2221,8 @@ bordercolor : color-spec, default: 'w' The color of the text border. borderinvert : bool, optional If ``True``, the text and border colors are swapped. -borderstyle : {'miter', 'round', 'bevel'}, default: :rc:`text.borderstyle` - The `line join style `__ +borderstyle : {'miter', 'round', 'bevel'}, default: [text.borderstyle](https://ultraplot.readthedocs.io/en/stable/search.html?q=text.borderstyle) + The [line join style](https://matplotlib.org/stable/gallery/lines_bars_and_markers/joinstyle.html) used for the border. bbox : bool, default: False Whether to draw a bounding box around text. @@ -2234,15 +2232,15 @@ bboxstyle : boxstyle, default: 'round' The style of the bounding box. bboxalpha : float, default: 0.5 The alpha for the bounding box. -bboxpad : float, default: :rc:`title.bboxpad` +bboxpad : float, default: [title.bboxpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.bboxpad) The padding for the bounding box. fontfamily : str, optional The font typeface name (e.g., ``'Fira Math'``) or font family name (e.g., ``'serif'``). Matplotlib falls back to the system default if not found. Aliases: ``family``, ``name``, ``fontname``. fontsize : unit-spec or str, optional - The font size. Aliases: ``size``. If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + The font size. Aliases: ``size``. If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). This can also be a string indicating some scaling relative to - :rcraw:`font.size`. The sizes and scalings are shown below. The + [font.size](https://ultraplot.readthedocs.io/en/stable/search.html?q=font.size). The sizes and scalings are shown below. The scalings ``'med'``, ``'med-small'``, and ``'med-large'`` are added by ultraplot while the rest are native matplotlib sizes. @@ -2264,7 +2262,7 @@ fontsize : unit-spec or str, optional ========================== ===== **kwargs - Passed to `matplotlib.axes.Axes.text`. + Passed to [matplotlib.axes.Axes.text](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.text.html). See also -------- @@ -2279,7 +2277,7 @@ Add text to the Axes. Add the text *s* to the Axes at location *x*, *y* in data coordinates, with a default ``horizontalalignment`` on the ``left`` and ``verticalalignment`` at the ``baseline``. See -:doc:`/gallery/text_labels_and_annotations/text_alignment`. +[/gallery/text_labels_and_annotations/text_alignment](https://ultraplot.readthedocs.io/en/stable/search.html?q=%2Fgallery%2Ftext_labels_and_annotations%2Ftext_alignment). Parameters ---------- @@ -2309,7 +2307,7 @@ Returns Other Parameters ---------------- -**kwargs : `~matplotlib.text.Text` properties. +**kwargs : [Text](https://matplotlib.org/stable/api/_as_gen/matplotlib.text.Text.html) properties. Other miscellaneous text parameters. Properties: @@ -2317,13 +2315,13 @@ Other Parameters alpha: float or None animated: bool antialiased: bool - backgroundcolor: :mpltype:`color` + backgroundcolor: [color](https://matplotlib.org/stable/search.html?q=color) bbox: dict with properties for `.patches.FancyBboxPatch` clip_box: unknown clip_on: unknown clip_path: unknown - color or c: :mpltype:`color` - figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + color or c: [color](https://matplotlib.org/stable/search.html?q=color) + figure: [Figure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html) or [SubFigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.SubFigure.html) fontfamily or family or fontname: {FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'} fontproperties or font or font_properties: `.font_manager.FontProperties` or `str` or `pathlib.Path` fontsize or size: float or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'} @@ -2349,10 +2347,10 @@ Other Parameters sketch_params: (scale: float, length: float, randomness: float) snap: bool or None text: object - transform: `~matplotlib.transforms.Transform` + transform: [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html) transform_rotates_text: bool url: str - usetex: bool, default: :rc:`text.usetex` + usetex: bool, default: [text.usetex](https://ultraplot.readthedocs.io/en/stable/search.html?q=text.usetex) verticalalignment or va: {'baseline', 'bottom', 'center', 'center_baseline', 'top'} visible: bool wrap: bool @@ -2377,7 +2375,7 @@ text in the center of the Axes:: You can put a rectangular box around the text instance (e.g., to set a background color) by using the keyword *bbox*. *bbox* is -a dictionary of `~matplotlib.patches.Rectangle` +a dictionary of [Rectangle](https://matplotlib.org/stable/api/_as_gen/matplotlib.patches.Rectangle.html) properties. For example:: >>> text(x, y, s, bbox=dict(facecolor='red', alpha=0.5))""" @@ -2397,20 +2395,20 @@ figure is resized or the data limits change. Parameters ---------- -*objs : `~matplotlib.text.Text`, optional +*objs : [Text](https://matplotlib.org/stable/api/_as_gen/matplotlib.text.Text.html), optional The text or annotation objects to align. Default is every text created with ``avoid_overlap=True`` plus, if none were, all the text you added to the axes. -pad : float, default: :rc:`text.align.pad` +pad : float, default: [text.align.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=text.align.pad) Padding in points kept around each label. avoid_points : bool, default: True Whether labels also repel the data points of lines and scatter plots. -avoid : sequence of `~matplotlib.artist.Artist`, optional +avoid : sequence of [Artist](https://matplotlib.org/stable/api/_as_gen/matplotlib.artist.Artist.html), optional Extra artists whose bounding boxes the labels must stay clear of. only_move : {'xy', 'x', 'y'}, default: 'xy' Restrict movement to one axis. Use ``'y'`` when the horizontal position of a label carries meaning, as on a time series. -max_iter : int, default: :rc:`text.align.maxiter` +max_iter : int, default: [text.align.maxiter](https://ultraplot.readthedocs.io/en/stable/search.html?q=text.align.maxiter) Maximum number of relaxation iterations. spring : float, default: 0.05 Strength of the pull back towards the original position. Larger @@ -2419,9 +2417,9 @@ step : float, default: 0.6 Damping applied to each iteration's displacement. clip : bool, default: True Whether to keep labels inside the axes. -arrows : bool or dict, default: :rc:`text.align.arrows` +arrows : bool or dict, default: [text.align.arrows](https://ultraplot.readthedocs.io/en/stable/search.html?q=text.align.arrows) Whether to draw a connector from each displaced label back to the - point it labels. A dict is passed to `~matplotlib.patches.FancyArrowPatch`. + point it labels. A dict is passed to [FancyArrowPatch](https://matplotlib.org/stable/api/_as_gen/matplotlib.patches.FancyArrowPatch.html). min_arrow_dist : float, default: 8.0 Only draw connectors for labels displaced further than this, in points. @@ -2451,10 +2449,10 @@ For curved input with `arrowprops`, the arrow points to the curve center. Parameters ---------- -avoid_overlap : bool, default: :rc:`text.align` +avoid_overlap : bool, default: [text.align](https://ultraplot.readthedocs.io/en/stable/search.html?q=text.align) Whether to automatically nudge this annotation at draw time so it does not overlap other auto-aligned text or the plotted data. See - `~ultraplot.axes.Axes.auto_align_text`. + [auto_align_text](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.auto_align_text). Matplotlib documentation @@ -2510,7 +2508,7 @@ xycoords : single or two-tuple of str or `.Artist` or `.Transform` or callable, a subfigure can use 'subfigure pixels'. - An `.Artist`: *xy* is interpreted as a fraction of the artist's - `~matplotlib.transforms.Bbox`. E.g. *(0, 0)* would be the lower + [Bbox](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Bbox.html). E.g. *(0, 0)* would be the lower left corner of the bounding box and *(0.5, 1)* would be the center top of the bounding box. @@ -2530,7 +2528,7 @@ xycoords : single or two-tuple of str or `.Artist` or `.Transform` or callable, systems for *x* and *y*. *xcoords* and *ycoords* must each be of one of the above described types. - See :ref:`plotting-guide-annotation` for more details. + See [plotting-guide-annotation](https://ultraplot.readthedocs.io/en/stable/search.html?q=plotting-guide-annotation) for more details. textcoords : single or two-tuple of str or `.Artist` or `.Transform` or callable, default: value of *xycoords* The coordinate system that *xytext* is given in. @@ -2618,7 +2616,7 @@ Returns See Also -------- -:ref:`annotations`""" +[annotations](https://ultraplot.readthedocs.io/en/stable/search.html?q=annotations)""" ... def curvedtext(self, x: Incomplete, y: Incomplete, text: Incomplete, *, upright: Incomplete=None, ellipsis: Incomplete=None, avoid_overlap: Incomplete=None, overlap_tol: Incomplete=None, curvature_pad: Incomplete=None, min_advance: Incomplete=None, border: Incomplete=False, bbox: Incomplete=False, bordercolor: Incomplete='w', borderwidth: Incomplete=2, borderinvert: Incomplete=False, borderstyle: Incomplete='miter', bboxcolor: Incomplete='w', bboxstyle: Incomplete='round', bboxalpha: Incomplete=0.5, bboxpad: Incomplete=None, **kwargs: Incomplete) -> Incomplete: @@ -2630,12 +2628,12 @@ x, y : array-like Curve coordinates. text : str The string for the text. -transform : {'data', 'axes', 'figure', 'subfigure'} or `~matplotlib.transforms.Transform`, optional +transform : {'data', 'axes', 'figure', 'subfigure'} or [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html), optional The transform used to interpret the bounds. Can be a - :class:`~matplotlib.transforms.Transform` instance or a string representing - the :class:`~matplotlib.axes.Axes.transData`, :class:`~matplotlib.axes.Axes.transAxes`, - :class:`~matplotlib.figure.Figure.transFigure`, or - :class:`~matplotlib.figure.Figure.transSubfigure`, transforms. + [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html) instance or a string representing + the [transData](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.transData.html), [transAxes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.transAxes.html), + [transFigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.transFigure.html), or + [transSubfigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.transSubfigure.html), transforms. Other parameters ---------------- @@ -2647,20 +2645,20 @@ bordercolor : color-spec, default: 'w' The color of the text border. borderinvert : bool, optional If ``True``, the text and border colors are swapped. -upright : bool, default: :rc:`text.curved.upright` +upright : bool, default: [text.curved.upright](https://ultraplot.readthedocs.io/en/stable/search.html?q=text.curved.upright) Whether to flip the curve direction to keep text upright. -ellipsis : bool, default: :rc:`text.curved.ellipsis` +ellipsis : bool, default: [text.curved.ellipsis](https://ultraplot.readthedocs.io/en/stable/search.html?q=text.curved.ellipsis) Whether to show an ellipsis when the text exceeds curve length. -avoid_overlap : bool, default: :rc:`text.curved.avoid_overlap` +avoid_overlap : bool, default: [text.curved.avoid_overlap](https://ultraplot.readthedocs.io/en/stable/search.html?q=text.curved.avoid_overlap) Whether to hide glyphs that overlap after rotation. -overlap_tol : float, default: :rc:`text.curved.overlap_tol` +overlap_tol : float, default: [text.curved.overlap_tol](https://ultraplot.readthedocs.io/en/stable/search.html?q=text.curved.overlap_tol) Fractional overlap area (0–1) required before hiding a glyph. -curvature_pad : float, default: :rc:`text.curved.curvature_pad` +curvature_pad : float, default: [text.curved.curvature_pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=text.curved.curvature_pad) Extra spacing in pixels per radian of local curvature. -min_advance : float, default: :rc:`text.curved.min_advance` +min_advance : float, default: [text.curved.min_advance](https://ultraplot.readthedocs.io/en/stable/search.html?q=text.curved.min_advance) Minimum additional spacing (pixels) enforced between glyph centers. borderstyle : {'miter', 'round', 'bevel'}, default: 'miter' - The `line join style `__ + The [line join style](https://matplotlib.org/stable/gallery/lines_bars_and_markers/joinstyle.html) used for the border. bbox : bool, default: False Whether to draw a bounding box around text. @@ -2670,15 +2668,15 @@ bboxstyle : boxstyle, default: 'round' The style of the bounding box. bboxalpha : float, default: 0.5 The alpha for the bounding box. -bboxpad : float, default: :rc:`title.bboxpad` +bboxpad : float, default: [title.bboxpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.bboxpad) The padding for the bounding box. fontfamily : str, optional The font typeface name (e.g., ``'Fira Math'``) or font family name (e.g., ``'serif'``). Matplotlib falls back to the system default if not found. Aliases: ``family``, ``name``, ``fontname``. fontsize : unit-spec or str, optional - The font size. Aliases: ``size``. If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + The font size. Aliases: ``size``. If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). This can also be a string indicating some scaling relative to - :rcraw:`font.size`. The sizes and scalings are shown below. The + [font.size](https://ultraplot.readthedocs.io/en/stable/search.html?q=font.size). The sizes and scalings are shown below. The scalings ``'med'``, ``'med-small'``, and ``'med-large'`` are added by ultraplot while the rest are native matplotlib sizes. @@ -2700,7 +2698,7 @@ fontsize : unit-spec or str, optional ========================== ===== **kwargs - Passed to `matplotlib.text.Text`.""" + Passed to [matplotlib.text.Text](https://matplotlib.org/stable/api/_as_gen/matplotlib.text.Text.html).""" ... def _toggle_spines(self, spines: Union[bool, Iterable, str]) -> None: @@ -2723,15 +2721,15 @@ panels : bool or str or sequence of str, optional @property def number(self) -> Incomplete: """The axes number. This controls the order of a-b-c labels and the -order of appearance in the :class:`~ultraplot.gridspec.SubplotGrid` returned -by `~ultraplot.figure.Figure.subplots`.""" +order of appearance in the [SubplotGrid](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.gridspec.SubplotGrid.html) returned +by [subplots](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.subplots).""" ... @number.setter def number(self, num: Incomplete) -> None: """The axes number. This controls the order of a-b-c labels and the -order of appearance in the :class:`~ultraplot.gridspec.SubplotGrid` returned -by `~ultraplot.figure.Figure.subplots`.""" +order of appearance in the [SubplotGrid](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.gridspec.SubplotGrid.html) returned +by [subplots](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.subplots).""" ... @property @@ -2739,7 +2737,7 @@ by `~ultraplot.figure.Figure.subplots`.""" """Whether plotting commands like `plot`, `plotx`, `vlines`, `hlines`, `fill_between`, and `fill_betweenx` add "sticky" edges to their artists, i.e. whether the default axis limits are the artist bounds with no padding. -Initialized from :rcraw:`axes.sticky_edges`.""" +Initialized from [axes.sticky_edges](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.sticky_edges).""" ... @use_sticky_edges.setter @@ -2747,7 +2745,7 @@ Initialized from :rcraw:`axes.sticky_edges`.""" """Whether plotting commands like `plot`, `plotx`, `vlines`, `hlines`, `fill_between`, and `fill_betweenx` add "sticky" edges to their artists, i.e. whether the default axis limits are the artist bounds with no padding. -Initialized from :rcraw:`axes.sticky_edges`.""" +Initialized from [axes.sticky_edges](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.sticky_edges).""" ... def _get_pos_from_locator(loc: str, x_pad: float, y_pad: float) -> tuple[float, float]: diff --git a/ultraplot/axes/cartesian.pyi b/ultraplot/axes/cartesian.pyi index d2bf86e20..5f4fe4a1a 100644 --- a/ultraplot/axes/cartesian.pyi +++ b/ultraplot/axes/cartesian.pyi @@ -95,8 +95,8 @@ Important --------- This is the default axes subclass. It can be specified explicitly by passing ``proj='cart'``, ``proj='cartesian'``, ``proj='rect'``, or ``proj='rectilinear'`` -to axes-creation commands like `~ultraplot.figure.Figure.add_axes`, -`~ultraplot.figure.Figure.add_subplot`, and `~ultraplot.figure.Figure.subplots`.""" +to axes-creation commands like [add_axes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.add_axes), +[add_subplot](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.add_subplot), and [subplots](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.subplots).""" _name = 'cartesian' _name_aliases = ('cart', 'rect', 'rectilinar') @@ -104,20 +104,20 @@ to axes-creation commands like `~ultraplot.figure.Figure.add_axes`, """Parameters ---------- *args - Passed to `matplotlib.axes.Axes`. + Passed to [matplotlib.axes.Axes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html). aspect : {'auto', 'equal'} or float, optional - The data aspect ratio. See :func:`~matplotlib.axes.Axes.set_aspect` + The data aspect ratio. See [set_aspect](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_aspect.html) for details. xlabel, ylabel : str, optional - The x and y axis labels. Applied with `~matplotlib.axes.Axes.set_xlabel` - and `~matplotlib.axes.Axes.set_ylabel`. + The x and y axis labels. Applied with [set_xlabel](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlabel.html) + and [set_ylabel](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylabel.html). xlabel_kw, ylabel_kw : dict-like, optional - Additional axis label settings applied with `~matplotlib.axes.Axes.set_xlabel` - and `~matplotlib.axes.Axes.set_ylabel`. See also `labelpad`, `labelcolor`, + Additional axis label settings applied with [set_xlabel](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlabel.html) + and [set_ylabel](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylabel.html). See also `labelpad`, `labelcolor`, `labelsize`, and `labelweight` below. xlim, ylim : 2-tuple of floats or None, optional - The x and y axis data limits. Applied with :func:`~matplotlib.axes.Axes.set_xlim` - and :func:`~matplotlib.axes.Axes.set_ylim`. + The x and y axis data limits. Applied with [set_xlim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlim.html) + and [set_ylim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylim.html). xmin, ymin : float, optional The x and y minimum data limits. Useful if you do not want to set the maximum limits. @@ -128,12 +128,12 @@ xreverse, yreverse : bool, optional Whether to "reverse" the x and y axis direction. Makes the x and y axes ascend left-to-right and top-to-bottom, respectively. xscale, yscale : scale-spec, optional - The x and y axis scales. Passed to the `~ultraplot.scale.Scale` constructor. + The x and y axis scales. Passed to the [Scale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.Scale.html) constructor. For example, ``xscale='log'`` applies logarithmic scaling, and - ``xscale=('cutoff', 100, 2)`` applies a `~ultraplot.scale.CutoffScale`. + ``xscale=('cutoff', 100, 2)`` applies a [CutoffScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.CutoffScale.html). xscale_kw, yscale_kw : dict-like, optional - The x and y axis scale settings. Passed to `~ultraplot.scale.Scale`. -xmargin, ymargin, margin : float, default: :rc:`margin` + The x and y axis scale settings. Passed to [Scale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.Scale.html). +xmargin, ymargin, margin : float, default: [margin](https://ultraplot.readthedocs.io/en/stable/search.html?q=margin) The default margin between plotted content and the x and y axis spines in axes-relative coordinates. This is useful if you don't witch to explicitly set axis limits. Use the keyword `margin` to set both at once. @@ -146,16 +146,16 @@ xtickrange, ytickrange : 2-tuple of float, optional The x and y axis data ranges within which major tick marks are labelled. For example, ``xlim=(-5, 5)`` combined with ``xtickrange=(-1, 1)`` and a tick interval of 1 will only label the ticks marks at -1, 0, and 1. See - `~ultraplot.ticker.AutoFormatter` for details. + [AutoFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.AutoFormatter.html) for details. xwraprange, ywraprange : 2-tuple of float, optional The x and y axis data ranges with which major tick mark values are wrapped. For example, ``xwraprange=(0, 3)`` causes the values 0 through 9 to be formatted as - 0, 1, 2, 0, 1, 2, 0, 1, 2, 0. See `~ultraplot.ticker.AutoFormatter` for details. This + 0, 1, 2, 0, 1, 2, 0, 1, 2, 0. See [AutoFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.AutoFormatter.html) for details. This can be combined with `xtickrange` and `ytickrange` to make "stacked" line plots. xloc, yloc : optional Shorthands for `xspineloc`, `yspineloc`. xspineloc, yspineloc : {'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right', 'both', 'neither', 'none', 'zero', 'center'} or 2-tuple, optional - The x and y spine locations. Applied with `~matplotlib.spines.Spine.set_position`. + The x and y spine locations. Applied with [set_position](https://matplotlib.org/stable/api/_as_gen/matplotlib.spines.Spine.set_position.html). Propagates to `tickloc` unless specified otherwise. xtickloc, ytickloc : {'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right', 'both', 'neither', 'none'}, optional Which x and y axis spines should have major and minor tick marks. Inherits from @@ -177,25 +177,25 @@ xticklabeldir, yticklabeldir : {'in', 'out'}, optional Propagates to `xtickdir` and `ytickdir` unless specified otherwise. xrotation, yrotation : float, default: 0 The rotation for x and y axis tick labels. - for normal axes, :rc:`formatter.timerotation` for time x axes. -xgrid, ygrid, grid : bool, default: :rc:`grid` + for normal axes, [formatter.timerotation](https://ultraplot.readthedocs.io/en/stable/search.html?q=formatter.timerotation) for time x axes. +xgrid, ygrid, grid : bool, default: [grid](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid) Whether to draw major gridlines on the x and y axis. Use the keyword `grid` to toggle both. -xgridminor, ygridminor, gridminor : bool, default: :rc:`gridminor` +xgridminor, ygridminor, gridminor : bool, default: [gridminor](https://ultraplot.readthedocs.io/en/stable/search.html?q=gridminor) Whether to draw minor gridlines for the x and y axis. Use the keyword `gridminor` to toggle both. -xtickminor, ytickminor, tickminor : bool, default: :rc:`tick.minor` +xtickminor, ytickminor, tickminor : bool, default: [tick.minor](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.minor) Whether to draw minor ticks on the x and y axes. Use the keyword `tickminor` to toggle both. xticks, yticks : optional Aliases for `xlocator`, `ylocator`. xlocator, ylocator : locator-spec, optional Used to determine the x and y axis tick mark positions. Passed - to the `~ultraplot.constructor.Locator` constructor. Can be float, - list of float, string, or `matplotlib.ticker.Locator` instance. + to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. Can be float, + list of float, string, or [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) instance. Use ``[]``, ``'null'``, or ``'none'`` for no ticks. xlocator_kw, ylocator_kw : dict-like, optional - Keyword arguments passed to the `matplotlib.ticker.Locator` class. + Keyword arguments passed to the [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. xminorticks, yminorticks : optional Aliases for `xminorlocator`, `yminorlocator`. xminorlocator, yminorlocator : optional @@ -206,66 +206,66 @@ xticklabels, yticklabels : optional Aliases for `xformatter`, `yformatter`. xformatter, yformatter : formatter-spec, optional Used to determine the x and y axis tick label string format. - Passed to the `~ultraplot.constructor.Formatter` constructor. - Can be string, list of strings, or `matplotlib.ticker.Formatter` instance. + Passed to the [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html) constructor. + Can be string, list of strings, or [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) instance. Use ``[]``, ``'null'``, or ``'none'`` for no labels. xformatter_kw, yformatter_kw : dict-like, optional - Keyword arguments passed to the `matplotlib.ticker.Formatter` class. -xcolor, ycolor, color : color-spec, default: :rc:`meta.color` + Keyword arguments passed to the [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) class. +xcolor, ycolor, color : color-spec, default: [meta.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=meta.color) Color for the x and y axis spines, ticks, tick labels, and axis labels. Use the keyword `color` to set both at once. -xgridcolor, ygridcolor, gridcolor : color-spec, default: :rc:`grid.color` +xgridcolor, ygridcolor, gridcolor : color-spec, default: [grid.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.color) Color for the x and y axis major and minor gridlines. Use the keyword `gridcolor` to set both at once. -xlinewidth, ylinewidth, linewidth : color-spec, default: :rc:`meta.width` +xlinewidth, ylinewidth, linewidth : color-spec, default: [meta.width](https://ultraplot.readthedocs.io/en/stable/search.html?q=meta.width) Line width for the x and y axis spines and major ticks. Propagates to `tickwidth` unless specified otherwise. Use the keyword `linewidth` to set both at once. -xtickcolor, ytickcolor, tickcolor : color-spec, default: :rc:`tick.color` +xtickcolor, ytickcolor, tickcolor : color-spec, default: [tick.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.color) Color for the x and y axis ticks. Defaults are `xcolor`, `ycolor`, and `color` if they were passed. Use the keyword `tickcolor` to set both at once. -xticklen, yticklen, ticklen : unit-spec, default: :rc:`tick.len` +xticklen, yticklen, ticklen : unit-spec, default: [tick.len](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.len) Major tick lengths for the x and y axis. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Use the keyword `ticklen` to set both at once. -xticklenratio, yticklenratio, ticklenratio : float, default: :rc:`tick.lenratio` +xticklenratio, yticklenratio, ticklenratio : float, default: [tick.lenratio](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.lenratio) Relative scaling of `xticklen` and `yticklen` used to determine minor tick lengths. Use the keyword `ticklenratio` to set both at once. -xtickwidth, ytickwidth, tickwidth, : unit-spec, default: :rc:`tick.width` +xtickwidth, ytickwidth, tickwidth, : unit-spec, default: [tick.width](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.width) Major tick widths for the x ans y axis. Default is `linewidth` if it was passed. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Use the keyword `tickwidth` to set both at once. -xtickwidthratio, ytickwidthratio, tickwidthratio : float, default: :rc:`tick.widthratio` +xtickwidthratio, ytickwidthratio, tickwidthratio : float, default: [tick.widthratio](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.widthratio) Relative scaling of `xtickwidth` and `ytickwidth` used to determine minor tick widths. Use the keyword `tickwidthratio` to set both at once. -xticklabelpad, yticklabelpad, ticklabelpad : unit-spec, default: :rc:`tick.labelpad` +xticklabelpad, yticklabelpad, ticklabelpad : unit-spec, default: [tick.labelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.labelpad) The padding between the x and y axis ticks and tick labels. Use the keyword `ticklabelpad` to set both at once. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -xticklabelcolor, yticklabelcolor, ticklabelcolor : color-spec, default: :rc:`tick.labelcolor` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +xticklabelcolor, yticklabelcolor, ticklabelcolor : color-spec, default: [tick.labelcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.labelcolor) Color for the x and y tick labels. Defaults are `xcolor`, `ycolor`, and `color` if they were passed. Use the keyword `ticklabelcolor` to set both at once. -xticklabelsize, yticklabelsize, ticklabelsize : unit-spec or str, default: :rc:`tick.labelsize` +xticklabelsize, yticklabelsize, ticklabelsize : unit-spec or str, default: [tick.labelsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.labelsize) Font size for the x and y tick labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Use the keyword `ticklabelsize` to set both at once. -xticklabelweight, yticklabelweight, ticklabelweight : str, default: :rc:`tick.labelweight` +xticklabelweight, yticklabelweight, ticklabelweight : str, default: [tick.labelweight](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.labelweight) Font weight for the x and y tick labels. Use the keyword `ticklabelweight` to set both at once. -xlabelpad, ylabelpad : unit-spec, default: :rc:`label.pad` +xlabelpad, ylabelpad : unit-spec, default: [label.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=label.pad) The padding between the x and y axis bounding box and the x and y axis labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -xlabelcolor, ylabelcolor, labelcolor : color-spec, default: :rc:`label.color` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +xlabelcolor, ylabelcolor, labelcolor : color-spec, default: [label.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=label.color) Color for the x and y axis labels. Defaults are `xcolor`, `ycolor`, and `color` if they were passed. Use the keyword `labelcolor` to set both at once. -xlabelsize, ylabelsize, labelsize : unit-spec or str, default: :rc:`label.size` +xlabelsize, ylabelsize, labelsize : unit-spec or str, default: [label.size](https://ultraplot.readthedocs.io/en/stable/search.html?q=label.size) Font size for the x and y axis labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Use the keyword `labelsize` to set both at once. -xlabelweight, ylabelweight, labelweight : str, default: :rc:`label.weight` +xlabelweight, ylabelweight, labelweight : str, default: [label.weight](https://ultraplot.readthedocs.io/en/stable/search.html?q=label.weight) Font weight for the x and y axis labels. Use the keyword `labelweight` to set both at once. fixticks : bool, default: False - Whether to transform the tick locators to a `~matplotlib.ticker.FixedLocator`. + Whether to transform the tick locators to a [FixedLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.FixedLocator.html). If your axis ticks are doing weird things (for example, ticks are drawn outside of the axis spine) you can try setting this to ``True``. @@ -274,14 +274,14 @@ Other parameters title : str or sequence, optional The axes title. Can optionally be a sequence strings, in which case the title will be selected from the sequence according to `~Axes.number`. -abc : bool or str or sequence, default: :rc:`abc` +abc : bool or str or sequence, default: [abc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc) The "a-b-c" subplot label style. Must contain the character `a` or `A`, for example ``'a.'``, or ``'A'``. If ``True`` then the default style of ``'a'`` is used. The `a` or ``A`` is replaced with the alphabetic character matching the `~Axes.number`. If `~Axes.number` is greater than 26, the characters loop around to a, ..., z, aa, ..., zz, aaa, ..., zzz, etc. Can also be a sequence of strings, in which case the "a-b-c" label will be selected sequentially from the list. For example `axs.format(abc = ["X", "Y"])` for a two-panel figure, and `axes[3:5].format(abc = ["X", "Y"])` for a two-panel subset of a larger figure. -abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` +abcloc, titleloc : str, default: [abc.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.loc), [title.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.loc) Strings indicating the location for the a-b-c label and main title. The following locations are valid: @@ -303,31 +303,31 @@ abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` right of y axis ``'outer right'``, ``'or'`` ======================== ============================ -abcborder, titleborder : bool, default: :rc:`abc.border` and :rc:`title.border` +abcborder, titleborder : bool, default: [abc.border](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.border) and [title.border](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.border) Whether to draw a white border around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes. -abcbbox, titlebbox : bool, default: :rc:`abc.bbox` and :rc:`title.bbox` +abcbbox, titlebbox : bool, default: [abc.bbox](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.bbox) and [title.bbox](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.bbox) Whether to draw a white bbox around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes. -abcpad : float or unit-spec, default: :rc:`abc.pad` +abcpad : float or unit-spec, default: [abc.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.pad) Horizontal offset to shift the a-b-c label position. Positive values move the label right, negative values move it left. This is separate from `abctitlepad`, which controls spacing between abc and title when co-located. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). abc_kw, title_kw : dict-like, optional Additional settings used to update the a-b-c label and title with ``text.update()``. -titlepad : float, default: :rc:`title.pad` +titlepad : float, default: [title.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.pad) The padding for the inner and outer titles and a-b-c labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -titleabove : bool, default: :rc:`title.above` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +titleabove : bool, default: [title.above](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.above) Whether to try to put outer titles and a-b-c labels above panels, colorbars, or legends that are above the axes. -abctitlepad : float, default: :rc:`abc.titlepad` +abctitlepad : float, default: [abc.titlepad](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.titlepad) The horizontal padding between a-b-c labels and titles in the same location. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle : str or sequence, optional Shorthands for the below keywords. lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle : str or sequence, optional @@ -336,22 +336,22 @@ lowerlefttitle, lowercentertitle, lowerrighttitle : str or sequence, optional an alternative to the ``ax.format(title='Title', titleloc=loc)`` workflow and permits adding more than one title-like label for a single axes. a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle : default: - :rc:`axes.alpha` (default: 1.0), :rc:`axes.facecolor` (default: white), :rc:`axes.edgecolor` (default: black), :rc:`axes.linewidth` (default: 0.6), - + [axes.alpha](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.alpha) (default: 1.0), [axes.facecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.facecolor) (default: white), [axes.edgecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.edgecolor) (default: black), [axes.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.linewidth) (default: 0.6), - Additional settings applied to the background patch, and their shorthands. Their defaults values are the ``'axes'`` properties. rc_mode : int, optional - The context mode passed to `~ultraplot.config.Configurator.context`. + The context mode passed to [context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context). rc_kw : dict-like, optional An alternative to passing extra keyword arguments. See below. **kwargs - Remaining keyword arguments are passed to `matplotlib.axes.Axes`.\\n Keyword arguments that match the name of an `~ultraplot.config.rc` setting are - passed to `ultraplot.config.Configurator.context` and used to update the axes. + Remaining keyword arguments are passed to [matplotlib.axes.Axes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html).\\n Keyword arguments that match the name of an [rc](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.rc.html) setting are + passed to [ultraplot.config.Configurator.context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context) and used to update the axes. If the setting name has "dots" you can simply omit the dots. For example, - ``abc='A.'`` modifies the :rcraw:`abc` setting, ``titleloc='left'`` modifies the - :rcraw:`title.loc` setting, ``gridminor=True`` modifies the :rcraw:`gridminor` - setting, and ``gridbelow=True`` modifies the :rcraw:`grid.below` setting. Many + ``abc='A.'`` modifies the [abc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc) setting, ``titleloc='left'`` modifies the + [title.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.loc) setting, ``gridminor=True`` modifies the [gridminor](https://ultraplot.readthedocs.io/en/stable/search.html?q=gridminor) + setting, and ``gridbelow=True`` modifies the [grid.below](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.below) setting. Many of the keyword arguments documented above are internally applied by retrieving - settings passed to `~ultraplot.config.Configurator.context`. + settings passed to [context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context). See also -------- @@ -424,7 +424,7 @@ dict def _fix_ticks(self, s: Incomplete, fixticks: Incomplete=False) -> None: """Ensure there are no out-of-bounds ticks. Mostly a brute-force version of -`~matplotlib.axis.Axis.set_smart_bounds` (which I couldn't get to work).""" +[set_smart_bounds](https://matplotlib.org/stable/api/_as_gen/matplotlib.axis.Axis.set_smart_bounds.html) (which I couldn't get to work).""" ... def _get_spine_side(self, s: Incomplete, loc: Incomplete) -> Incomplete: @@ -462,8 +462,8 @@ Parameters value : str or `.ScaleBase` The axis scale type to apply. Valid string values are the names of scale classes ("linear", "log", "function",...). These may be the names of any - of the :ref:`built-in scales` or of any custom scales - registered using `matplotlib.scale.register_scale`. + of the [built-in scales](https://ultraplot.readthedocs.io/en/stable/search.html?q=builtin_scales) or of any custom scales + registered using [matplotlib.scale.register_scale](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.register_scale.html). **kwargs If *value* is a string, keywords are passed to the instantiation method of @@ -478,8 +478,8 @@ Parameters value : str or `.ScaleBase` The axis scale type to apply. Valid string values are the names of scale classes ("linear", "log", "function",...). These may be the names of any - of the :ref:`built-in scales` or of any custom scales - registered using `matplotlib.scale.register_scale`. + of the [built-in scales](https://ultraplot.readthedocs.io/en/stable/search.html?q=builtin_scales) or of any custom scales + registered using [matplotlib.scale.register_scale](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.register_scale.html). **kwargs If *value* is a string, keywords are passed to the instantiation method of @@ -531,18 +531,18 @@ tick locations, tick labels, and more. Parameters ---------- aspect : {'auto', 'equal'} or float, optional - The data aspect ratio. See :func:`~matplotlib.axes.Axes.set_aspect` + The data aspect ratio. See [set_aspect](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_aspect.html) for details. xlabel, ylabel : str, optional - The x and y axis labels. Applied with `~matplotlib.axes.Axes.set_xlabel` - and `~matplotlib.axes.Axes.set_ylabel`. + The x and y axis labels. Applied with [set_xlabel](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlabel.html) + and [set_ylabel](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylabel.html). xlabel_kw, ylabel_kw : dict-like, optional - Additional axis label settings applied with `~matplotlib.axes.Axes.set_xlabel` - and `~matplotlib.axes.Axes.set_ylabel`. See also `labelpad`, `labelcolor`, + Additional axis label settings applied with [set_xlabel](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlabel.html) + and [set_ylabel](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylabel.html). See also `labelpad`, `labelcolor`, `labelsize`, and `labelweight` below. xlim, ylim : 2-tuple of floats or None, optional - The x and y axis data limits. Applied with :func:`~matplotlib.axes.Axes.set_xlim` - and :func:`~matplotlib.axes.Axes.set_ylim`. + The x and y axis data limits. Applied with [set_xlim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlim.html) + and [set_ylim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylim.html). xmin, ymin : float, optional The x and y minimum data limits. Useful if you do not want to set the maximum limits. @@ -553,12 +553,12 @@ xreverse, yreverse : bool, optional Whether to "reverse" the x and y axis direction. Makes the x and y axes ascend left-to-right and top-to-bottom, respectively. xscale, yscale : scale-spec, optional - The x and y axis scales. Passed to the `~ultraplot.scale.Scale` constructor. + The x and y axis scales. Passed to the [Scale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.Scale.html) constructor. For example, ``xscale='log'`` applies logarithmic scaling, and - ``xscale=('cutoff', 100, 2)`` applies a `~ultraplot.scale.CutoffScale`. + ``xscale=('cutoff', 100, 2)`` applies a [CutoffScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.CutoffScale.html). xscale_kw, yscale_kw : dict-like, optional - The x and y axis scale settings. Passed to `~ultraplot.scale.Scale`. -xmargin, ymargin, margin : float, default: :rc:`margin` + The x and y axis scale settings. Passed to [Scale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.Scale.html). +xmargin, ymargin, margin : float, default: [margin](https://ultraplot.readthedocs.io/en/stable/search.html?q=margin) The default margin between plotted content and the x and y axis spines in axes-relative coordinates. This is useful if you don't witch to explicitly set axis limits. Use the keyword `margin` to set both at once. @@ -571,16 +571,16 @@ xtickrange, ytickrange : 2-tuple of float, optional The x and y axis data ranges within which major tick marks are labelled. For example, ``xlim=(-5, 5)`` combined with ``xtickrange=(-1, 1)`` and a tick interval of 1 will only label the ticks marks at -1, 0, and 1. See - `~ultraplot.ticker.AutoFormatter` for details. + [AutoFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.AutoFormatter.html) for details. xwraprange, ywraprange : 2-tuple of float, optional The x and y axis data ranges with which major tick mark values are wrapped. For example, ``xwraprange=(0, 3)`` causes the values 0 through 9 to be formatted as - 0, 1, 2, 0, 1, 2, 0, 1, 2, 0. See `~ultraplot.ticker.AutoFormatter` for details. This + 0, 1, 2, 0, 1, 2, 0, 1, 2, 0. See [AutoFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.AutoFormatter.html) for details. This can be combined with `xtickrange` and `ytickrange` to make "stacked" line plots. xloc, yloc : optional Shorthands for `xspineloc`, `yspineloc`. xspineloc, yspineloc : {'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right', 'both', 'neither', 'none', 'zero', 'center'} or 2-tuple, optional - The x and y spine locations. Applied with `~matplotlib.spines.Spine.set_position`. + The x and y spine locations. Applied with [set_position](https://matplotlib.org/stable/api/_as_gen/matplotlib.spines.Spine.set_position.html). Propagates to `tickloc` unless specified otherwise. xtickloc, ytickloc : {'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right', 'both', 'neither', 'none'}, optional Which x and y axis spines should have major and minor tick marks. Inherits from @@ -602,25 +602,25 @@ xticklabeldir, yticklabeldir : {'in', 'out'}, optional Propagates to `xtickdir` and `ytickdir` unless specified otherwise. xrotation, yrotation : float, default: 0 The rotation for x and y axis tick labels. - for normal axes, :rc:`formatter.timerotation` for time x axes. -xgrid, ygrid, grid : bool, default: :rc:`grid` + for normal axes, [formatter.timerotation](https://ultraplot.readthedocs.io/en/stable/search.html?q=formatter.timerotation) for time x axes. +xgrid, ygrid, grid : bool, default: [grid](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid) Whether to draw major gridlines on the x and y axis. Use the keyword `grid` to toggle both. -xgridminor, ygridminor, gridminor : bool, default: :rc:`gridminor` +xgridminor, ygridminor, gridminor : bool, default: [gridminor](https://ultraplot.readthedocs.io/en/stable/search.html?q=gridminor) Whether to draw minor gridlines for the x and y axis. Use the keyword `gridminor` to toggle both. -xtickminor, ytickminor, tickminor : bool, default: :rc:`tick.minor` +xtickminor, ytickminor, tickminor : bool, default: [tick.minor](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.minor) Whether to draw minor ticks on the x and y axes. Use the keyword `tickminor` to toggle both. xticks, yticks : optional Aliases for `xlocator`, `ylocator`. xlocator, ylocator : locator-spec, optional Used to determine the x and y axis tick mark positions. Passed - to the `~ultraplot.constructor.Locator` constructor. Can be float, - list of float, string, or `matplotlib.ticker.Locator` instance. + to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. Can be float, + list of float, string, or [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) instance. Use ``[]``, ``'null'``, or ``'none'`` for no ticks. xlocator_kw, ylocator_kw : dict-like, optional - Keyword arguments passed to the `matplotlib.ticker.Locator` class. + Keyword arguments passed to the [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. xminorticks, yminorticks : optional Aliases for `xminorlocator`, `yminorlocator`. xminorlocator, yminorlocator : optional @@ -631,66 +631,66 @@ xticklabels, yticklabels : optional Aliases for `xformatter`, `yformatter`. xformatter, yformatter : formatter-spec, optional Used to determine the x and y axis tick label string format. - Passed to the `~ultraplot.constructor.Formatter` constructor. - Can be string, list of strings, or `matplotlib.ticker.Formatter` instance. + Passed to the [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html) constructor. + Can be string, list of strings, or [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) instance. Use ``[]``, ``'null'``, or ``'none'`` for no labels. xformatter_kw, yformatter_kw : dict-like, optional - Keyword arguments passed to the `matplotlib.ticker.Formatter` class. -xcolor, ycolor, color : color-spec, default: :rc:`meta.color` + Keyword arguments passed to the [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) class. +xcolor, ycolor, color : color-spec, default: [meta.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=meta.color) Color for the x and y axis spines, ticks, tick labels, and axis labels. Use the keyword `color` to set both at once. -xgridcolor, ygridcolor, gridcolor : color-spec, default: :rc:`grid.color` +xgridcolor, ygridcolor, gridcolor : color-spec, default: [grid.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.color) Color for the x and y axis major and minor gridlines. Use the keyword `gridcolor` to set both at once. -xlinewidth, ylinewidth, linewidth : color-spec, default: :rc:`meta.width` +xlinewidth, ylinewidth, linewidth : color-spec, default: [meta.width](https://ultraplot.readthedocs.io/en/stable/search.html?q=meta.width) Line width for the x and y axis spines and major ticks. Propagates to `tickwidth` unless specified otherwise. Use the keyword `linewidth` to set both at once. -xtickcolor, ytickcolor, tickcolor : color-spec, default: :rc:`tick.color` +xtickcolor, ytickcolor, tickcolor : color-spec, default: [tick.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.color) Color for the x and y axis ticks. Defaults are `xcolor`, `ycolor`, and `color` if they were passed. Use the keyword `tickcolor` to set both at once. -xticklen, yticklen, ticklen : unit-spec, default: :rc:`tick.len` +xticklen, yticklen, ticklen : unit-spec, default: [tick.len](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.len) Major tick lengths for the x and y axis. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Use the keyword `ticklen` to set both at once. -xticklenratio, yticklenratio, ticklenratio : float, default: :rc:`tick.lenratio` +xticklenratio, yticklenratio, ticklenratio : float, default: [tick.lenratio](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.lenratio) Relative scaling of `xticklen` and `yticklen` used to determine minor tick lengths. Use the keyword `ticklenratio` to set both at once. -xtickwidth, ytickwidth, tickwidth, : unit-spec, default: :rc:`tick.width` +xtickwidth, ytickwidth, tickwidth, : unit-spec, default: [tick.width](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.width) Major tick widths for the x ans y axis. Default is `linewidth` if it was passed. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Use the keyword `tickwidth` to set both at once. -xtickwidthratio, ytickwidthratio, tickwidthratio : float, default: :rc:`tick.widthratio` +xtickwidthratio, ytickwidthratio, tickwidthratio : float, default: [tick.widthratio](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.widthratio) Relative scaling of `xtickwidth` and `ytickwidth` used to determine minor tick widths. Use the keyword `tickwidthratio` to set both at once. -xticklabelpad, yticklabelpad, ticklabelpad : unit-spec, default: :rc:`tick.labelpad` +xticklabelpad, yticklabelpad, ticklabelpad : unit-spec, default: [tick.labelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.labelpad) The padding between the x and y axis ticks and tick labels. Use the keyword `ticklabelpad` to set both at once. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -xticklabelcolor, yticklabelcolor, ticklabelcolor : color-spec, default: :rc:`tick.labelcolor` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +xticklabelcolor, yticklabelcolor, ticklabelcolor : color-spec, default: [tick.labelcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.labelcolor) Color for the x and y tick labels. Defaults are `xcolor`, `ycolor`, and `color` if they were passed. Use the keyword `ticklabelcolor` to set both at once. -xticklabelsize, yticklabelsize, ticklabelsize : unit-spec or str, default: :rc:`tick.labelsize` +xticklabelsize, yticklabelsize, ticklabelsize : unit-spec or str, default: [tick.labelsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.labelsize) Font size for the x and y tick labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Use the keyword `ticklabelsize` to set both at once. -xticklabelweight, yticklabelweight, ticklabelweight : str, default: :rc:`tick.labelweight` +xticklabelweight, yticklabelweight, ticklabelweight : str, default: [tick.labelweight](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.labelweight) Font weight for the x and y tick labels. Use the keyword `ticklabelweight` to set both at once. -xlabelpad, ylabelpad : unit-spec, default: :rc:`label.pad` +xlabelpad, ylabelpad : unit-spec, default: [label.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=label.pad) The padding between the x and y axis bounding box and the x and y axis labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -xlabelcolor, ylabelcolor, labelcolor : color-spec, default: :rc:`label.color` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +xlabelcolor, ylabelcolor, labelcolor : color-spec, default: [label.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=label.color) Color for the x and y axis labels. Defaults are `xcolor`, `ycolor`, and `color` if they were passed. Use the keyword `labelcolor` to set both at once. -xlabelsize, ylabelsize, labelsize : unit-spec or str, default: :rc:`label.size` +xlabelsize, ylabelsize, labelsize : unit-spec or str, default: [label.size](https://ultraplot.readthedocs.io/en/stable/search.html?q=label.size) Font size for the x and y axis labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Use the keyword `labelsize` to set both at once. -xlabelweight, ylabelweight, labelweight : str, default: :rc:`label.weight` +xlabelweight, ylabelweight, labelweight : str, default: [label.weight](https://ultraplot.readthedocs.io/en/stable/search.html?q=label.weight) Font weight for the x and y axis labels. Use the keyword `labelweight` to set both at once. fixticks : bool, default: False - Whether to transform the tick locators to a `~matplotlib.ticker.FixedLocator`. + Whether to transform the tick locators to a [FixedLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.FixedLocator.html). If your axis ticks are doing weird things (for example, ticks are drawn outside of the axis spine) you can try setting this to ``True``. @@ -699,14 +699,14 @@ Other parameters title : str or sequence, optional The axes title. Can optionally be a sequence strings, in which case the title will be selected from the sequence according to `~Axes.number`. -abc : bool or str or sequence, default: :rc:`abc` +abc : bool or str or sequence, default: [abc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc) The "a-b-c" subplot label style. Must contain the character `a` or `A`, for example ``'a.'``, or ``'A'``. If ``True`` then the default style of ``'a'`` is used. The `a` or ``A`` is replaced with the alphabetic character matching the `~Axes.number`. If `~Axes.number` is greater than 26, the characters loop around to a, ..., z, aa, ..., zz, aaa, ..., zzz, etc. Can also be a sequence of strings, in which case the "a-b-c" label will be selected sequentially from the list. For example `axs.format(abc = ["X", "Y"])` for a two-panel figure, and `axes[3:5].format(abc = ["X", "Y"])` for a two-panel subset of a larger figure. -abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` +abcloc, titleloc : str, default: [abc.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.loc), [title.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.loc) Strings indicating the location for the a-b-c label and main title. The following locations are valid: @@ -728,31 +728,31 @@ abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` right of y axis ``'outer right'``, ``'or'`` ======================== ============================ -abcborder, titleborder : bool, default: :rc:`abc.border` and :rc:`title.border` +abcborder, titleborder : bool, default: [abc.border](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.border) and [title.border](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.border) Whether to draw a white border around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes. -abcbbox, titlebbox : bool, default: :rc:`abc.bbox` and :rc:`title.bbox` +abcbbox, titlebbox : bool, default: [abc.bbox](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.bbox) and [title.bbox](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.bbox) Whether to draw a white bbox around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes. -abcpad : float or unit-spec, default: :rc:`abc.pad` +abcpad : float or unit-spec, default: [abc.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.pad) Horizontal offset to shift the a-b-c label position. Positive values move the label right, negative values move it left. This is separate from `abctitlepad`, which controls spacing between abc and title when co-located. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). abc_kw, title_kw : dict-like, optional Additional settings used to update the a-b-c label and title with ``text.update()``. -titlepad : float, default: :rc:`title.pad` +titlepad : float, default: [title.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.pad) The padding for the inner and outer titles and a-b-c labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -titleabove : bool, default: :rc:`title.above` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +titleabove : bool, default: [title.above](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.above) Whether to try to put outer titles and a-b-c labels above panels, colorbars, or legends that are above the axes. -abctitlepad : float, default: :rc:`abc.titlepad` +abctitlepad : float, default: [abc.titlepad](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.titlepad) The horizontal padding between a-b-c labels and titles in the same location. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle : str or sequence, optional Shorthands for the below keywords. lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle : str or sequence, optional @@ -761,7 +761,7 @@ lowerlefttitle, lowercentertitle, lowerrighttitle : str or sequence, optional an alternative to the ``ax.format(title='Title', titleloc=loc)`` workflow and permits adding more than one title-like label for a single axes. a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle : default: - :rc:`axes.alpha` (default: 1.0), :rc:`axes.facecolor` (default: white), :rc:`axes.edgecolor` (default: black), :rc:`axes.linewidth` (default: 0.6), - + [axes.alpha](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.alpha) (default: 1.0), [axes.facecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.facecolor) (default: white), [axes.edgecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.edgecolor) (default: black), [axes.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.linewidth) (default: 0.6), - Additional settings applied to the background patch, and their shorthands. Their defaults values are the ``'axes'`` properties. rowlabels, collabels, llabels, tlabels, rlabels, blabels @@ -772,14 +772,14 @@ leftlabels, toplabels, rightlabels, bottomlabels : sequence of str, optional bottom edges of the figure. The length of each list must match the number of subplots along the corresponding edge. leftlabelpad, toplabelpad, rightlabelpad, bottomlabelpad : float or unit-spec, default -: :rc:`leftlabel.pad`, :rc:`toplabel.pad`, :rc:`rightlabel.pad`, :rc:`bottomlabel.pad` +: [leftlabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=leftlabel.pad), [toplabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=toplabel.pad), [rightlabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=rightlabel.pad), [bottomlabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=bottomlabel.pad) The padding between the labels and the axes content. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). leftlabelsharedpad, toplabelsharedpad, rightlabelsharedpad, bottomlabelsharedpad : float or unit-spec, default -: :rc:`leftlabel.sharedpad`, :rc:`toplabel.sharedpad`, :rc:`rightlabel.sharedpad`, :rc:`bottomlabel.sharedpad` +: [leftlabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=leftlabel.sharedpad), [toplabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=toplabel.sharedpad), [rightlabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=rightlabel.sharedpad), [bottomlabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=bottomlabel.sharedpad) The padding between side labels and a shared spanning axis label on the same side. The spanning label is placed outside the side labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). leftlabels_kw, toplabels_kw, rightlabels_kw, bottomlabels_kw : dict-like, optional Additional settings used to update the labels with ``text.update()``. figtitle @@ -787,9 +787,9 @@ figtitle suptitle : str, optional The figure "super" title, centered between the left edge of the leftmost subplot and the right edge of the rightmost subplot. -suptitlepad : float, default: :rc:`suptitle.pad` +suptitlepad : float, default: [suptitle.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=suptitle.pad) The padding between the super title and the axes content. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). suptitle_kw : optional Additional settings used to update the super title with ``text.update()``. includepanels : bool, default: False @@ -797,18 +797,18 @@ includepanels : bool, default: False of the subplot grid and when aligning the `spanx` *x* axis labels and `spany` *y* axis labels along the sides of the subplot grid. rc_mode : int, optional - The context mode passed to `~ultraplot.config.Configurator.context`. + The context mode passed to [context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context). rc_kw : dict-like, optional An alternative to passing extra keyword arguments. See below. **kwargs - Keyword arguments that match the name of an `~ultraplot.config.rc` setting are - passed to `ultraplot.config.Configurator.context` and used to update the axes. + Keyword arguments that match the name of an [rc](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.rc.html) setting are + passed to [ultraplot.config.Configurator.context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context) and used to update the axes. If the setting name has "dots" you can simply omit the dots. For example, - ``abc='A.'`` modifies the :rcraw:`abc` setting, ``titleloc='left'`` modifies the - :rcraw:`title.loc` setting, ``gridminor=True`` modifies the :rcraw:`gridminor` - setting, and ``gridbelow=True`` modifies the :rcraw:`grid.below` setting. Many + ``abc='A.'`` modifies the [abc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc) setting, ``titleloc='left'`` modifies the + [title.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.loc) setting, ``gridminor=True`` modifies the [gridminor](https://ultraplot.readthedocs.io/en/stable/search.html?q=gridminor) + setting, and ``gridbelow=True`` modifies the [grid.below](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.below) setting. Many of the keyword arguments documented above are internally applied by retrieving - settings passed to `~ultraplot.config.Configurator.context`. + settings passed to [context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context). See also -------- @@ -818,8 +818,8 @@ ultraplot.config.Configurator.context Note ---- -If you plot something with a `datetime64 `__, -`pandas.Timestamp`, `pandas.DatetimeIndex`, `datetime.date`, `datetime.time`, +If you plot something with a [datetime64](https://docs.scipy.org/doc/numpy/reference/arrays.datetime.html), +[pandas.Timestamp](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Timestamp.html), [pandas.DatetimeIndex](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DatetimeIndex.html), `datetime.date`, `datetime.time`, or `datetime.datetime` array as the x or y axis coordinate, the axis ticks and tick labels will be automatically formatted as dates.""" ... @@ -828,14 +828,14 @@ and tick labels will be automatically formatted as dates.""" """Add an axis locked to the same location with a distinct x axis. This is an alias and arguably more intuitive name for -`~ultraplot.axes.CartesianAxes.twiny`, which generates +[twiny](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html#ultraplot.axes.CartesianAxes.twiny), which generates two x axes with a shared ("twin") y axes. Parameters ---------- **kwargs - Passed to `~ultraplot.axes.CartesianAxes`. Supports all valid - `~ultraplot.axes.CartesianAxes.format` keywords. You can optionally + Passed to [CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html). Supports all valid + [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html#ultraplot.axes.CartesianAxes.format) keywords. You can optionally omit the x from keywords beginning with ``x`` -- for example ``ax.altx(lim=(0, 10))`` is equivalent to ``ax.altx(xlim=(0, 10))``. You can also change the default side for the axis spine, axis tick marks, @@ -865,14 +865,14 @@ This enforces the following default settings: """Add an axis locked to the same location with a distinct y axis. This is an alias and arguably more intuitive name for -`~ultraplot.axes.CartesianAxes.twinx`, which generates +[twinx](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html#ultraplot.axes.CartesianAxes.twinx), which generates two y axes with a shared ("twin") x axes. Parameters ---------- **kwargs - Passed to `~ultraplot.axes.CartesianAxes`. Supports all valid - `~ultraplot.axes.CartesianAxes.format` keywords. You can optionally + Passed to [CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html). Supports all valid + [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html#ultraplot.axes.CartesianAxes.format) keywords. You can optionally omit the y from keywords beginning with ``y`` -- for example ``ax.alty(lim=(0, 10))`` is equivalent to ``ax.alty(ylim=(0, 10))``. You can also change the default side for the axis spine, axis tick marks, @@ -901,21 +901,21 @@ This enforces the following default settings: def dualx(self, funcscale: Incomplete, **kwargs: Incomplete) -> CartesianAxes: """Add an axes locked to the same location whose x axis denotes equivalent coordinates in alternate units. -This is an alternative to `matplotlib.axes.Axes.secondary_xaxis` with +This is an alternative to [matplotlib.axes.Axes.secondary_xaxis](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.secondary_xaxis.html) with additional convenience features. Parameters ---------- funcscale : callable, 2-tuple of callables, or scale-spec The scale used to transform units from the parent axis to the secondary - axis. This can be a `~ultraplot.scale.FuncScale` itself or a function, + axis. This can be a [FuncScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.FuncScale.html) itself or a function, (function, function) tuple, or an axis scale specification interpreted - by the `~ultraplot.constructor.Scale` constructor function, any of which - will be used to build a `~ultraplot.scale.FuncScale` and applied - to the dual axis (see `~ultraplot.scale.FuncScale` for details). + by the [Scale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Scale.html) constructor function, any of which + will be used to build a [FuncScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.FuncScale.html) and applied + to the dual axis (see [FuncScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.FuncScale.html) for details). **kwargs - Passed to `~ultraplot.axes.CartesianAxes`. Supports all valid - `~ultraplot.axes.CartesianAxes.format` keywords. You can optionally + Passed to [CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html). Supports all valid + [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html#ultraplot.axes.CartesianAxes.format) keywords. You can optionally omit the x from keywords beginning with ``x`` -- for example ``ax.altx(lim=(0, 10))`` is equivalent to ``ax.altx(xlim=(0, 10))``. You can also change the default side for the axis spine, axis tick marks, @@ -944,21 +944,21 @@ This enforces the following default settings: def dualy(self, funcscale: Incomplete, **kwargs: Incomplete) -> CartesianAxes: """Add an axes locked to the same location whose y axis denotes equivalent coordinates in alternate units. -This is an alternative to `matplotlib.axes.Axes.secondary_yaxis` with +This is an alternative to [matplotlib.axes.Axes.secondary_yaxis](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.secondary_yaxis.html) with additional convenience features. Parameters ---------- funcscale : callable, 2-tuple of callables, or scale-spec The scale used to transform units from the parent axis to the secondary - axis. This can be a `~ultraplot.scale.FuncScale` itself or a function, + axis. This can be a [FuncScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.FuncScale.html) itself or a function, (function, function) tuple, or an axis scale specification interpreted - by the `~ultraplot.constructor.Scale` constructor function, any of which - will be used to build a `~ultraplot.scale.FuncScale` and applied - to the dual axis (see `~ultraplot.scale.FuncScale` for details). + by the [Scale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Scale.html) constructor function, any of which + will be used to build a [FuncScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.FuncScale.html) and applied + to the dual axis (see [FuncScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.FuncScale.html) for details). **kwargs - Passed to `~ultraplot.axes.CartesianAxes`. Supports all valid - `~ultraplot.axes.CartesianAxes.format` keywords. You can optionally + Passed to [CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html). Supports all valid + [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html#ultraplot.axes.CartesianAxes.format) keywords. You can optionally omit the y from keywords beginning with ``y`` -- for example ``ax.alty(lim=(0, 10))`` is equivalent to ``ax.alty(ylim=(0, 10))``. You can also change the default side for the axis spine, axis tick marks, @@ -987,13 +987,13 @@ This enforces the following default settings: def twinx(self, **kwargs: Incomplete) -> CartesianAxes: """Add an axis locked to the same location with a distinct y axis. -This builds upon `matplotlib.axes.Axes.twinx`. +This builds upon [matplotlib.axes.Axes.twinx](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.twinx.html). Parameters ---------- **kwargs - Passed to `~ultraplot.axes.CartesianAxes`. Supports all valid - `~ultraplot.axes.CartesianAxes.format` keywords. You can optionally + Passed to [CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html). Supports all valid + [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html#ultraplot.axes.CartesianAxes.format) keywords. You can optionally omit the y from keywords beginning with ``y`` -- for example ``ax.alty(lim=(0, 10))`` is equivalent to ``ax.alty(ylim=(0, 10))``. You can also change the default side for the axis spine, axis tick marks, @@ -1022,13 +1022,13 @@ This enforces the following default settings: def twiny(self, **kwargs: Incomplete) -> CartesianAxes: """Add an axis locked to the same location with a distinct x axis. -This builds upon `matplotlib.axes.Axes.twiny`. +This builds upon [matplotlib.axes.Axes.twiny](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.twiny.html). Parameters ---------- **kwargs - Passed to `~ultraplot.axes.CartesianAxes`. Supports all valid - `~ultraplot.axes.CartesianAxes.format` keywords. You can optionally + Passed to [CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html). Supports all valid + [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html#ultraplot.axes.CartesianAxes.format) keywords. You can optionally omit the x from keywords beginning with ``x`` -- for example ``ax.altx(lim=(0, 10))`` is equivalent to ``ax.altx(xlim=(0, 10))``. You can also change the default side for the axis spine, axis tick marks, @@ -1062,7 +1062,7 @@ returns False). Parameters ---------- -renderer : `~matplotlib.backend_bases.RendererBase` subclass. +renderer : [RendererBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.backend_bases.RendererBase.html) subclass. Notes ----- diff --git a/ultraplot/axes/container.pyi b/ultraplot/axes/container.pyi index e3c75e764..0bd891796 100644 --- a/ultraplot/axes/container.pyi +++ b/ultraplot/axes/container.pyi @@ -32,7 +32,7 @@ external_axes_class : type The external axes class to instantiate (e.g., mpltern.TernaryAxes) external_axes_kwargs : dict, optional Keyword arguments to pass to the external axes constructor -external_shrink_factor : float, optional, default: :rc:`external.shrink` +external_shrink_factor : float, optional, default: [external.shrink](https://ultraplot.readthedocs.io/en/stable/search.html?q=external.shrink) The factor by which to shrink the external axes within the container to leave room for labels. For ternary plots, labels extend significantly beyond the plot area, so a value of 0.90 (10% padding) helps prevent diff --git a/ultraplot/axes/geo.pyi b/ultraplot/axes/geo.pyi index e8c2434af..215b65a1f 100644 --- a/ultraplot/axes/geo.pyi +++ b/ultraplot/axes/geo.pyi @@ -170,16 +170,16 @@ matplotlib >= 3.10 the ``InsetIndicator`` resolves its connectors in its own @dataclass class _HawkeyeSpec: - """Validated inputs for :meth:`GeoAxes.hawkeye`. + """Validated inputs for `GeoAxes.hawkeye`. ``extent_transform`` and ``relation`` are only fully resolved when ``extent`` is not ``None`` (they require a geographic extent to normalize and infer); otherwise they retain their raw defaults and are never consumed. ``aspect`` is intentionally not stored here because ``'projection'`` can only be resolved -from the live inset axes (see :meth:`GeoAxes._build_hawkeye_inset`). When +from the live inset axes (see `GeoAxes._build_hawkeye_inset`). When ``anchor_transform`` is not ``None`` the ``anchor`` is a geographic/projected point rather than an axes fraction; it is converted to a fraction against the -live inset view limits in :meth:`GeoAxes._build_hawkeye_inset`.""" +live inset view limits in `GeoAxes._build_hawkeye_inset`.""" xy: tuple[float, float] size: tuple[float, float] anchor: tuple[float, float] @@ -231,8 +231,8 @@ else: class _GeoAxis(object): """Dummy axis used by longitude and latitude locators and for storing view limits on -longitude and latitude coordinates. Modeled after how `matplotlib.ticker._DummyAxis` -and `matplotlib.ticker.TickHelper` are used to control tick locations and labels.""" +longitude and latitude coordinates. Modeled after how [matplotlib.ticker._DummyAxis](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker._DummyAxis.html) +and [matplotlib.ticker.TickHelper](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.TickHelper.html) are used to control tick locations and labels.""" def __init__(self, axes: 'GeoAxes') -> None: ... @@ -439,9 +439,9 @@ the axes instance rather than the `~mpl_toolkits.basemap.Basemap` instance. Important --------- This axes subclass can be used by passing ``proj='proj_name'`` -to axes-creation commands like `~ultraplot.figure.Figure.add_axes`, -`~ultraplot.figure.Figure.add_subplot`, and `~ultraplot.figure.Figure.subplots`, -where ``proj_name`` is a registered :ref:`PROJ projection name `. +to axes-creation commands like [add_axes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.add_axes), +[add_subplot](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.add_subplot), and [subplots](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.subplots), +where ``proj_name`` is a registered [PROJ projection name](https://ultraplot.readthedocs.io/en/stable/search.html?q=proj_table). You can also pass a `~cartopy.crs.Projection` or `~mpl_toolkits.basemap.Basemap` instance instead of a projection name. Alternatively, you can pass any of the matplotlib-recognized axes subclass names ``proj='cartopy'``, ``proj='geo'``, or @@ -453,26 +453,26 @@ argument, or pass ``proj='basemap'`` with a `~mpl_toolkits.basemap.Basemap` """Parameters ---------- *args - Passed to `matplotlib.axes.Axes`. + Passed to [matplotlib.axes.Axes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html). map_projection : `~cartopy.crs.Projection` or `~mpl_toolkits.basemap.Basemap` The cartopy or basemap projection instance. This is passed automatically when calling axes-creation - commands like `~ultraplot.figure.Figure.add_subplot`. + commands like [add_subplot](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.add_subplot). aspect : {'auto', 'equal'} or float, optional The map aspect ratio. ``'auto'`` makes the map fill its subplot slot, which can be useful for aligning it with neighboring Cartesian axes but distorts - the projection. See :func:`~matplotlib.axes.Axes.set_aspect` for details. + the projection. See [set_aspect](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_aspect.html) for details. abcanchor : {'axes', 'slot'}, default: 'axes' The coordinate box used for the a-b-c label. ``'axes'`` attaches it to the visible map boundary. ``'slot'`` attaches it to the unadjusted GridSpec slot, keeping labels aligned with neighboring subplots when fixed map aspect leaves empty space inside a slot. -round : bool, default: :rc:`geo.round` +round : bool, default: [geo.round](https://ultraplot.readthedocs.io/en/stable/search.html?q=geo.round) *For polar cartopy axes only*. Whether to bound polar projections with circles rather than squares. Note that outer gridline labels cannot be added to circle-bounded polar projections. When basemap - is the backend this argument must be passed to `~ultraplot.constructor.Proj` instead. -extent : {'globe', 'auto'}, default: :rc:`geo.extent` + is the backend this argument must be passed to [Proj](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Proj.html) instead. +extent : {'globe', 'auto'}, default: [geo.extent](https://ultraplot.readthedocs.io/en/stable/search.html?q=geo.extent) *For cartopy axes only*. Whether to auto adjust the map bounds based on plotted content. If ``'globe'`` then non-polar projections are fixed with `~cartopy.mpl.geoaxes.GeoAxes.set_global`, @@ -482,42 +482,42 @@ lonlim, latlim : 2-tuple of float, optional *For cartopy axes only.* The approximate longitude and latitude boundaries of the map, applied with `~cartopy.mpl.geoaxes.GeoAxes.set_extent`. When basemap is the backend - this argument must be passed to `~ultraplot.constructor.Proj` instead. + this argument must be passed to [Proj](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Proj.html) instead. boundinglat : float, optional *For cartopy axes only.* The edge latitude for the circle bounding North Pole and South Pole-centered projections. When basemap is the backend this argument must be passed to - `~ultraplot.constructor.Proj` instead. -longrid, latgrid, grid : bool, default: :rc:`grid` + [Proj](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Proj.html) instead. +longrid, latgrid, grid : bool, default: [grid](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid) Whether to draw longitude and latitude gridlines. Use the keyword `grid` to toggle both at once. -longridminor, latgridminor, gridminor : bool, default: :rc:`gridminor` +longridminor, latgridminor, gridminor : bool, default: [gridminor](https://ultraplot.readthedocs.io/en/stable/search.html?q=gridminor) Whether to draw "minor" longitude and latitude lines. Use the keyword `gridminor` to toggle both at once. -lonticklen, latticklen, ticklen : unit-spec, default: :rc:`tick.len` +lonticklen, latticklen, ticklen : unit-spec, default: [tick.len](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.len) Major tick lengths for the longitudinal (x) and latitude (y) axis. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Use the keyword `ticklen` to set both at once. latmax : float, default: 80 The maximum absolute latitude for gridlines. Longitude gridlines are cut off poleward of this value (note this feature does not work in cartopy 0.18). -nsteps : int, default: :rc:`grid.nsteps` +nsteps : int, default: [grid.nsteps](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.nsteps) *For cartopy axes only.* The number of interpolation steps used to draw gridlines. lonlocator, latlocator : locator-spec, optional Used to determine the longitude and latitude gridline locations. Aliases: ``lonlines`` and ``latlines``, respectively. - Passed to the `~ultraplot.constructor.Locator` constructor. Can be - string, float, list of float, or `matplotlib.ticker.Locator` instance. + Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. Can be + string, float, list of float, or [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) instance. For basemap or cartopy < 0.18, the defaults are ``'deglon'`` and - ``'deglat'``, which correspond to the `~ultraplot.ticker.LongitudeLocator` - and `~ultraplot.ticker.LatitudeLocator` locators (adapted from cartopy). + ``'deglat'``, which correspond to the [LongitudeLocator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.LongitudeLocator.html) + and [LatitudeLocator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.LatitudeLocator.html) locators (adapted from cartopy). For cartopy >= 0.18, the defaults are ``'dmslon'`` and ``'dmslat'``, which uses the same locators with ``dms=True``. This selects gridlines at nice degree-minute-second intervals when the map extent is very small. lonlocator_kw, latlocator_kw : dict-like, optional - Keyword arguments passed to the `matplotlib.ticker.Locator` class. + Keyword arguments passed to the [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. Aliases: ``lonlines_kw`` and ``latlines_kw``, respectively. lonminorlocator, latminorlocator : optional As with `lonlocator` and `latlocator` but for the "minor" gridlines. @@ -525,7 +525,7 @@ lonminorlocator, latminorlocator : optional lonminorlocator_kw, latminorlocator_kw : optional As with `lonlocator_kw`, and `latlocator_kw` but for the "minor" gridlines. Aliases: ``lonminorlines_kw`` and ``latminorlines_kw``, respectively. -lonlabels, latlabels, labels : str, bool, or sequence, :rc:`grid.labels` +lonlabels, latlabels, labels : str, bool, or sequence, [grid.labels](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labels) Whether to add non-inline longitude and latitude gridline labels, and on which sides of the map. Use the keyword `labels` to set both at once. The argument must conform to one of the following options: @@ -544,14 +544,14 @@ lonlabels, latlabels, labels : str, bool, or sequence, :rc:`grid.labels` and the ``(left, right)`` sides for latitudes. * A boolean 4-tuple indicating whether to draw labels on the ``(left, right, bottom, top)`` sides, as with the basemap - :func:`~mpl_toolkits.basemap.Basemap.drawmeridians` and - :func:`~mpl_toolkits.basemap.Basemap.drawparallels` `labels` keyword. + `drawmeridians` and + `drawparallels` `labels` keyword. -loninline, latinline, inlinelabels : bool, default: :rc:`grid.inlinelabels` +loninline, latinline, inlinelabels : bool, default: [grid.inlinelabels](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.inlinelabels) *For cartopy axes only.* Whether to add inline longitude and latitude gridline labels. Use the keyword `inlinelabels` to set both at once. -rotatelabels : bool, default: :rc:`grid.rotatelabels` +rotatelabels : bool, default: [grid.rotatelabels](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.rotatelabels) *For cartopy axes only.* Whether to rotate non-inline gridline labels so that they automatically follow the map boundary curvature. @@ -564,11 +564,11 @@ lonlabelrotation : float, optional latlabelrotation : float, optional The rotation angle in degrees for latitude tick labels. Works for both cartopy and basemap backends. -labelpad : unit-spec, default: :rc:`grid.labelpad` +labelpad : unit-spec, default: [grid.labelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelpad) *For cartopy axes only.* The padding between non-inline gridline labels and the map boundary. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -dms : bool, default: :rc:`grid.dmslabels` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +dms : bool, default: [grid.dmslabels](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.dmslabels) *For cartopy axes only.* Whether the default locators and formatters should use "minutes" and "seconds" for gridline labels on small scales rather than decimal degrees. Setting this to @@ -576,11 +576,11 @@ dms : bool, default: :rc:`grid.dmslabels` and ``ax.format(lonformatter='deglon', latformatter='deglat')``. lonformatter, latformatter : formatter-spec, optional Formatter used to style longitude and latitude gridline labels. - Passed to the `~ultraplot.constructor.Formatter` constructor. Can be - string, list of string, or `matplotlib.ticker.Formatter` instance. + Passed to the [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html) constructor. Can be + string, list of string, or [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) instance. For basemap or cartopy < 0.18, the defaults are ``'deglon'`` and - ``'deglat'``, which correspond to `~ultraplot.ticker.SimpleFormatter` + ``'deglat'``, which correspond to [SimpleFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.SimpleFormatter.html) presets with degree symbols and cardinal direction suffixes. For cartopy >= 0.18, the defaults are ``'dmslon'`` and ``'dmslat'``, which uses cartopy's `~cartopy.mpl.ticker.LongitudeFormatter` and @@ -588,32 +588,32 @@ lonformatter, latformatter : formatter-spec, optional This formats gridlines that do not fall on whole degrees as "minutes" and "seconds" rather than decimal degrees. Use ``dms=False`` to disable this. lonformatter_kw, latformatter_kw : dict-like, optional - Keyword arguments passed to the `matplotlib.ticker.Formatter` class. + Keyword arguments passed to the [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) class. land, ocean, coast, rivers, lakes, borders, innerborders : bool, optional Toggles various geographic features. These are actually the - :rcraw:`land`, :rcraw:`ocean`, :rcraw:`coast`, :rcraw:`rivers`, - :rcraw:`lakes`, :rcraw:`borders`, and :rcraw:`innerborders` - settings passed to `~ultraplot.config.Configurator.context`. + [land](https://ultraplot.readthedocs.io/en/stable/search.html?q=land), [ocean](https://ultraplot.readthedocs.io/en/stable/search.html?q=ocean), [coast](https://ultraplot.readthedocs.io/en/stable/search.html?q=coast), [rivers](https://ultraplot.readthedocs.io/en/stable/search.html?q=rivers), + [lakes](https://ultraplot.readthedocs.io/en/stable/search.html?q=lakes), [borders](https://ultraplot.readthedocs.io/en/stable/search.html?q=borders), and [innerborders](https://ultraplot.readthedocs.io/en/stable/search.html?q=innerborders) + settings passed to [context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context). The style can be modified using additional `rc` settings. - For example, to change :rcraw:`land.color`, use + For example, to change [land.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=land.color), use ``ax.format(landcolor='green')``, and to change - :rcraw:`land.zorder`, use ``ax.format(landzorder=4)``. + [land.zorder](https://ultraplot.readthedocs.io/en/stable/search.html?q=land.zorder), use ``ax.format(landzorder=4)``. reso : {'lo', 'med', 'hi', 'x-hi', 'xx-hi'}, optional *For cartopy axes only.* The resolution of geographic features. When basemap is the backend this - must be passed to `~ultraplot.constructor.Proj` instead. -color : color-spec, default: :rc:`meta.color` + must be passed to [Proj](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Proj.html) instead. +color : color-spec, default: [meta.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=meta.color) The color for the axes edge. Propagates to `labelcolor` unless specified - otherwise (similar to :func:`~ultraplot.axes.CartesianAxes.format`). -gridcolor : color-spec, default: :rc:`grid.color` + otherwise (similar to [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html#ultraplot.axes.CartesianAxes.format)). +gridcolor : color-spec, default: [grid.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.color) The color for the gridline labels. -labelcolor : color-spec, default: `color` or :rc:`grid.labelcolor` +labelcolor : color-spec, default: `color` or [grid.labelcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelcolor) The color for the gridline labels (`gridlabelcolor` is also allowed). -labelsize : unit-spec or str, default: :rc:`grid.labelsize` +labelsize : unit-spec or str, default: [grid.labelsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelsize) The font size for the gridline labels (`gridlabelsize` is also allowed). - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -labelweight : str, default: :rc:`grid.labelweight` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +labelweight : str, default: [grid.labelweight](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelweight) The font weight for the gridline labels (`gridlabelweight` is also allowed). Other parameters @@ -621,14 +621,14 @@ Other parameters title : str or sequence, optional The axes title. Can optionally be a sequence strings, in which case the title will be selected from the sequence according to `~Axes.number`. -abc : bool or str or sequence, default: :rc:`abc` +abc : bool or str or sequence, default: [abc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc) The "a-b-c" subplot label style. Must contain the character `a` or `A`, for example ``'a.'``, or ``'A'``. If ``True`` then the default style of ``'a'`` is used. The `a` or ``A`` is replaced with the alphabetic character matching the `~Axes.number`. If `~Axes.number` is greater than 26, the characters loop around to a, ..., z, aa, ..., zz, aaa, ..., zzz, etc. Can also be a sequence of strings, in which case the "a-b-c" label will be selected sequentially from the list. For example `axs.format(abc = ["X", "Y"])` for a two-panel figure, and `axes[3:5].format(abc = ["X", "Y"])` for a two-panel subset of a larger figure. -abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` +abcloc, titleloc : str, default: [abc.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.loc), [title.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.loc) Strings indicating the location for the a-b-c label and main title. The following locations are valid: @@ -650,31 +650,31 @@ abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` right of y axis ``'outer right'``, ``'or'`` ======================== ============================ -abcborder, titleborder : bool, default: :rc:`abc.border` and :rc:`title.border` +abcborder, titleborder : bool, default: [abc.border](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.border) and [title.border](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.border) Whether to draw a white border around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes. -abcbbox, titlebbox : bool, default: :rc:`abc.bbox` and :rc:`title.bbox` +abcbbox, titlebbox : bool, default: [abc.bbox](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.bbox) and [title.bbox](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.bbox) Whether to draw a white bbox around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes. -abcpad : float or unit-spec, default: :rc:`abc.pad` +abcpad : float or unit-spec, default: [abc.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.pad) Horizontal offset to shift the a-b-c label position. Positive values move the label right, negative values move it left. This is separate from `abctitlepad`, which controls spacing between abc and title when co-located. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). abc_kw, title_kw : dict-like, optional Additional settings used to update the a-b-c label and title with ``text.update()``. -titlepad : float, default: :rc:`title.pad` +titlepad : float, default: [title.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.pad) The padding for the inner and outer titles and a-b-c labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -titleabove : bool, default: :rc:`title.above` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +titleabove : bool, default: [title.above](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.above) Whether to try to put outer titles and a-b-c labels above panels, colorbars, or legends that are above the axes. -abctitlepad : float, default: :rc:`abc.titlepad` +abctitlepad : float, default: [abc.titlepad](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.titlepad) The horizontal padding between a-b-c labels and titles in the same location. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle : str or sequence, optional Shorthands for the below keywords. lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle : str or sequence, optional @@ -683,22 +683,22 @@ lowerlefttitle, lowercentertitle, lowerrighttitle : str or sequence, optional an alternative to the ``ax.format(title='Title', titleloc=loc)`` workflow and permits adding more than one title-like label for a single axes. a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle : default: - :rc:`axes.alpha` (default: 1.0), :rc:`axes.facecolor` (default: white), :rc:`axes.edgecolor` (default: black), :rc:`axes.linewidth` (default: 0.6), - + [axes.alpha](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.alpha) (default: 1.0), [axes.facecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.facecolor) (default: white), [axes.edgecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.edgecolor) (default: black), [axes.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.linewidth) (default: 0.6), - Additional settings applied to the background patch, and their shorthands. Their defaults values are the ``'axes'`` properties. rc_mode : int, optional - The context mode passed to `~ultraplot.config.Configurator.context`. + The context mode passed to [context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context). rc_kw : dict-like, optional An alternative to passing extra keyword arguments. See below. **kwargs - Remaining keyword arguments are passed to `matplotlib.axes.Axes`.\\n Keyword arguments that match the name of an `~ultraplot.config.rc` setting are - passed to `ultraplot.config.Configurator.context` and used to update the axes. + Remaining keyword arguments are passed to [matplotlib.axes.Axes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html).\\n Keyword arguments that match the name of an [rc](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.rc.html) setting are + passed to [ultraplot.config.Configurator.context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context) and used to update the axes. If the setting name has "dots" you can simply omit the dots. For example, - ``abc='A.'`` modifies the :rcraw:`abc` setting, ``titleloc='left'`` modifies the - :rcraw:`title.loc` setting, ``gridminor=True`` modifies the :rcraw:`gridminor` - setting, and ``gridbelow=True`` modifies the :rcraw:`grid.below` setting. Many + ``abc='A.'`` modifies the [abc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc) setting, ``titleloc='left'`` modifies the + [title.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.loc) setting, ``gridminor=True`` modifies the [gridminor](https://ultraplot.readthedocs.io/en/stable/search.html?q=gridminor) + setting, and ``gridbelow=True`` modifies the [grid.below](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.below) setting. Many of the keyword arguments documented above are internally applied by retrieving - settings passed to `~ultraplot.config.Configurator.context`. + settings passed to [context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context). See also -------- @@ -727,16 +727,16 @@ size : float or 2-tuple of float transform : coordinate system, default: 'axes' Coordinate system for *xy*. One of: - * ``'axes'`` -- parent axes fractions (`~matplotlib.axes.Axes.transAxes`). + * ``'axes'`` -- parent axes fractions ([transAxes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.transAxes.html)). * ``'data'`` -- parent *projected* coordinates - (`~matplotlib.axes.Axes.transData`), i.e. the parent projection's native + ([transData](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.transData.html)), i.e. the parent projection's native units (metres for most projections). This coincides with longitude-latitude only for a default `~cartopy.crs.PlateCarree` parent, so it is rarely what you want on a map; use ``'map'`` for longitude-latitude. * ``'figure'`` / ``'subfigure'`` -- figure or subfigure fractions. * ``'map'`` -- longitude-latitude degrees (`~cartopy.crs.PlateCarree`). * a projection name (e.g. ``'cyl'``, ``'moll'``), a `~cartopy.crs.Projection`, - or a `~matplotlib.transforms.Transform` -- *xy* in arbitrary projected + or a [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html) -- *xy* in arbitrary projected coordinates. anchor : str or 2-tuple of float, default: 'upper right' The inset point placed at *xy*. String aliases include ``'ul'``, ``'ur'``, @@ -790,7 +790,7 @@ GeoAxes ... def _resolve_hawkeye_spec(self, xy: Sequence[float], size: float | Sequence[float], transform: Any, anchor: str | Sequence[float], anchor_transform: Any, extent: Optional[Sequence[float]], extent_transform: Any, relation: str, connector: bool | str, shape: str, target: str) -> '_HawkeyeSpec': - """Validate and normalize raw hawkeye arguments into a :class:`_HawkeyeSpec`.""" + """Validate and normalize raw hawkeye arguments into a `_HawkeyeSpec`.""" ... def _resolve_hawkeye_xy_transform(self, transform: Any) -> Any: @@ -798,7 +798,7 @@ GeoAxes Reserved names (``'axes'``, ``'data'``, ``'figure'``, ``'subfigure'``, ``'map'``), matplotlib transforms, and cartopy CRS instances are handled -by :meth:`_get_transform`. Any other string is treated as a projection +by `_get_transform`. Any other string is treated as a projection name and resolved to a cartopy CRS so *xy* can be given in arbitrary projected coordinates.""" ... @@ -966,7 +966,7 @@ returns False). Parameters ---------- -renderer : `~matplotlib.backend_bases.RendererBase` subclass. +renderer : [RendererBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.backend_bases.RendererBase.html) subclass. Notes ----- @@ -1046,18 +1046,18 @@ Parameters aspect : {'auto', 'equal'} or float, optional The map aspect ratio. ``'auto'`` makes the map fill its subplot slot, which can be useful for aligning it with neighboring Cartesian axes but distorts - the projection. See :func:`~matplotlib.axes.Axes.set_aspect` for details. + the projection. See [set_aspect](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_aspect.html) for details. abcanchor : {'axes', 'slot'}, default: 'axes' The coordinate box used for the a-b-c label. ``'axes'`` attaches it to the visible map boundary. ``'slot'`` attaches it to the unadjusted GridSpec slot, keeping labels aligned with neighboring subplots when fixed map aspect leaves empty space inside a slot. -round : bool, default: :rc:`geo.round` +round : bool, default: [geo.round](https://ultraplot.readthedocs.io/en/stable/search.html?q=geo.round) *For polar cartopy axes only*. Whether to bound polar projections with circles rather than squares. Note that outer gridline labels cannot be added to circle-bounded polar projections. When basemap - is the backend this argument must be passed to `~ultraplot.constructor.Proj` instead. -extent : {'globe', 'auto'}, default: :rc:`geo.extent` + is the backend this argument must be passed to [Proj](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Proj.html) instead. +extent : {'globe', 'auto'}, default: [geo.extent](https://ultraplot.readthedocs.io/en/stable/search.html?q=geo.extent) *For cartopy axes only*. Whether to auto adjust the map bounds based on plotted content. If ``'globe'`` then non-polar projections are fixed with `~cartopy.mpl.geoaxes.GeoAxes.set_global`, @@ -1067,42 +1067,42 @@ lonlim, latlim : 2-tuple of float, optional *For cartopy axes only.* The approximate longitude and latitude boundaries of the map, applied with `~cartopy.mpl.geoaxes.GeoAxes.set_extent`. When basemap is the backend - this argument must be passed to `~ultraplot.constructor.Proj` instead. + this argument must be passed to [Proj](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Proj.html) instead. boundinglat : float, optional *For cartopy axes only.* The edge latitude for the circle bounding North Pole and South Pole-centered projections. When basemap is the backend this argument must be passed to - `~ultraplot.constructor.Proj` instead. -longrid, latgrid, grid : bool, default: :rc:`grid` + [Proj](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Proj.html) instead. +longrid, latgrid, grid : bool, default: [grid](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid) Whether to draw longitude and latitude gridlines. Use the keyword `grid` to toggle both at once. -longridminor, latgridminor, gridminor : bool, default: :rc:`gridminor` +longridminor, latgridminor, gridminor : bool, default: [gridminor](https://ultraplot.readthedocs.io/en/stable/search.html?q=gridminor) Whether to draw "minor" longitude and latitude lines. Use the keyword `gridminor` to toggle both at once. -lonticklen, latticklen, ticklen : unit-spec, default: :rc:`tick.len` +lonticklen, latticklen, ticklen : unit-spec, default: [tick.len](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.len) Major tick lengths for the longitudinal (x) and latitude (y) axis. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Use the keyword `ticklen` to set both at once. latmax : float, default: 80 The maximum absolute latitude for gridlines. Longitude gridlines are cut off poleward of this value (note this feature does not work in cartopy 0.18). -nsteps : int, default: :rc:`grid.nsteps` +nsteps : int, default: [grid.nsteps](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.nsteps) *For cartopy axes only.* The number of interpolation steps used to draw gridlines. lonlocator, latlocator : locator-spec, optional Used to determine the longitude and latitude gridline locations. Aliases: ``lonlines`` and ``latlines``, respectively. - Passed to the `~ultraplot.constructor.Locator` constructor. Can be - string, float, list of float, or `matplotlib.ticker.Locator` instance. + Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. Can be + string, float, list of float, or [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) instance. For basemap or cartopy < 0.18, the defaults are ``'deglon'`` and - ``'deglat'``, which correspond to the `~ultraplot.ticker.LongitudeLocator` - and `~ultraplot.ticker.LatitudeLocator` locators (adapted from cartopy). + ``'deglat'``, which correspond to the [LongitudeLocator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.LongitudeLocator.html) + and [LatitudeLocator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.LatitudeLocator.html) locators (adapted from cartopy). For cartopy >= 0.18, the defaults are ``'dmslon'`` and ``'dmslat'``, which uses the same locators with ``dms=True``. This selects gridlines at nice degree-minute-second intervals when the map extent is very small. lonlocator_kw, latlocator_kw : dict-like, optional - Keyword arguments passed to the `matplotlib.ticker.Locator` class. + Keyword arguments passed to the [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. Aliases: ``lonlines_kw`` and ``latlines_kw``, respectively. lonminorlocator, latminorlocator : optional As with `lonlocator` and `latlocator` but for the "minor" gridlines. @@ -1110,7 +1110,7 @@ lonminorlocator, latminorlocator : optional lonminorlocator_kw, latminorlocator_kw : optional As with `lonlocator_kw`, and `latlocator_kw` but for the "minor" gridlines. Aliases: ``lonminorlines_kw`` and ``latminorlines_kw``, respectively. -lonlabels, latlabels, labels : str, bool, or sequence, :rc:`grid.labels` +lonlabels, latlabels, labels : str, bool, or sequence, [grid.labels](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labels) Whether to add non-inline longitude and latitude gridline labels, and on which sides of the map. Use the keyword `labels` to set both at once. The argument must conform to one of the following options: @@ -1129,14 +1129,14 @@ lonlabels, latlabels, labels : str, bool, or sequence, :rc:`grid.labels` and the ``(left, right)`` sides for latitudes. * A boolean 4-tuple indicating whether to draw labels on the ``(left, right, bottom, top)`` sides, as with the basemap - :func:`~mpl_toolkits.basemap.Basemap.drawmeridians` and - :func:`~mpl_toolkits.basemap.Basemap.drawparallels` `labels` keyword. + `drawmeridians` and + `drawparallels` `labels` keyword. -loninline, latinline, inlinelabels : bool, default: :rc:`grid.inlinelabels` +loninline, latinline, inlinelabels : bool, default: [grid.inlinelabels](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.inlinelabels) *For cartopy axes only.* Whether to add inline longitude and latitude gridline labels. Use the keyword `inlinelabels` to set both at once. -rotatelabels : bool, default: :rc:`grid.rotatelabels` +rotatelabels : bool, default: [grid.rotatelabels](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.rotatelabels) *For cartopy axes only.* Whether to rotate non-inline gridline labels so that they automatically follow the map boundary curvature. @@ -1149,11 +1149,11 @@ lonlabelrotation : float, optional latlabelrotation : float, optional The rotation angle in degrees for latitude tick labels. Works for both cartopy and basemap backends. -labelpad : unit-spec, default: :rc:`grid.labelpad` +labelpad : unit-spec, default: [grid.labelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelpad) *For cartopy axes only.* The padding between non-inline gridline labels and the map boundary. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -dms : bool, default: :rc:`grid.dmslabels` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +dms : bool, default: [grid.dmslabels](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.dmslabels) *For cartopy axes only.* Whether the default locators and formatters should use "minutes" and "seconds" for gridline labels on small scales rather than decimal degrees. Setting this to @@ -1161,11 +1161,11 @@ dms : bool, default: :rc:`grid.dmslabels` and ``ax.format(lonformatter='deglon', latformatter='deglat')``. lonformatter, latformatter : formatter-spec, optional Formatter used to style longitude and latitude gridline labels. - Passed to the `~ultraplot.constructor.Formatter` constructor. Can be - string, list of string, or `matplotlib.ticker.Formatter` instance. + Passed to the [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html) constructor. Can be + string, list of string, or [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) instance. For basemap or cartopy < 0.18, the defaults are ``'deglon'`` and - ``'deglat'``, which correspond to `~ultraplot.ticker.SimpleFormatter` + ``'deglat'``, which correspond to [SimpleFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.SimpleFormatter.html) presets with degree symbols and cardinal direction suffixes. For cartopy >= 0.18, the defaults are ``'dmslon'`` and ``'dmslat'``, which uses cartopy's `~cartopy.mpl.ticker.LongitudeFormatter` and @@ -1173,32 +1173,32 @@ lonformatter, latformatter : formatter-spec, optional This formats gridlines that do not fall on whole degrees as "minutes" and "seconds" rather than decimal degrees. Use ``dms=False`` to disable this. lonformatter_kw, latformatter_kw : dict-like, optional - Keyword arguments passed to the `matplotlib.ticker.Formatter` class. + Keyword arguments passed to the [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) class. land, ocean, coast, rivers, lakes, borders, innerborders : bool, optional Toggles various geographic features. These are actually the - :rcraw:`land`, :rcraw:`ocean`, :rcraw:`coast`, :rcraw:`rivers`, - :rcraw:`lakes`, :rcraw:`borders`, and :rcraw:`innerborders` - settings passed to `~ultraplot.config.Configurator.context`. + [land](https://ultraplot.readthedocs.io/en/stable/search.html?q=land), [ocean](https://ultraplot.readthedocs.io/en/stable/search.html?q=ocean), [coast](https://ultraplot.readthedocs.io/en/stable/search.html?q=coast), [rivers](https://ultraplot.readthedocs.io/en/stable/search.html?q=rivers), + [lakes](https://ultraplot.readthedocs.io/en/stable/search.html?q=lakes), [borders](https://ultraplot.readthedocs.io/en/stable/search.html?q=borders), and [innerborders](https://ultraplot.readthedocs.io/en/stable/search.html?q=innerborders) + settings passed to [context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context). The style can be modified using additional `rc` settings. - For example, to change :rcraw:`land.color`, use + For example, to change [land.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=land.color), use ``ax.format(landcolor='green')``, and to change - :rcraw:`land.zorder`, use ``ax.format(landzorder=4)``. + [land.zorder](https://ultraplot.readthedocs.io/en/stable/search.html?q=land.zorder), use ``ax.format(landzorder=4)``. reso : {'lo', 'med', 'hi', 'x-hi', 'xx-hi'}, optional *For cartopy axes only.* The resolution of geographic features. When basemap is the backend this - must be passed to `~ultraplot.constructor.Proj` instead. -color : color-spec, default: :rc:`meta.color` + must be passed to [Proj](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Proj.html) instead. +color : color-spec, default: [meta.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=meta.color) The color for the axes edge. Propagates to `labelcolor` unless specified - otherwise (similar to :func:`~ultraplot.axes.CartesianAxes.format`). -gridcolor : color-spec, default: :rc:`grid.color` + otherwise (similar to [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html#ultraplot.axes.CartesianAxes.format)). +gridcolor : color-spec, default: [grid.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.color) The color for the gridline labels. -labelcolor : color-spec, default: `color` or :rc:`grid.labelcolor` +labelcolor : color-spec, default: `color` or [grid.labelcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelcolor) The color for the gridline labels (`gridlabelcolor` is also allowed). -labelsize : unit-spec or str, default: :rc:`grid.labelsize` +labelsize : unit-spec or str, default: [grid.labelsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelsize) The font size for the gridline labels (`gridlabelsize` is also allowed). - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -labelweight : str, default: :rc:`grid.labelweight` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +labelweight : str, default: [grid.labelweight](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelweight) The font weight for the gridline labels (`gridlabelweight` is also allowed). Other parameters @@ -1206,14 +1206,14 @@ Other parameters title : str or sequence, optional The axes title. Can optionally be a sequence strings, in which case the title will be selected from the sequence according to `~Axes.number`. -abc : bool or str or sequence, default: :rc:`abc` +abc : bool or str or sequence, default: [abc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc) The "a-b-c" subplot label style. Must contain the character `a` or `A`, for example ``'a.'``, or ``'A'``. If ``True`` then the default style of ``'a'`` is used. The `a` or ``A`` is replaced with the alphabetic character matching the `~Axes.number`. If `~Axes.number` is greater than 26, the characters loop around to a, ..., z, aa, ..., zz, aaa, ..., zzz, etc. Can also be a sequence of strings, in which case the "a-b-c" label will be selected sequentially from the list. For example `axs.format(abc = ["X", "Y"])` for a two-panel figure, and `axes[3:5].format(abc = ["X", "Y"])` for a two-panel subset of a larger figure. -abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` +abcloc, titleloc : str, default: [abc.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.loc), [title.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.loc) Strings indicating the location for the a-b-c label and main title. The following locations are valid: @@ -1235,31 +1235,31 @@ abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` right of y axis ``'outer right'``, ``'or'`` ======================== ============================ -abcborder, titleborder : bool, default: :rc:`abc.border` and :rc:`title.border` +abcborder, titleborder : bool, default: [abc.border](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.border) and [title.border](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.border) Whether to draw a white border around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes. -abcbbox, titlebbox : bool, default: :rc:`abc.bbox` and :rc:`title.bbox` +abcbbox, titlebbox : bool, default: [abc.bbox](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.bbox) and [title.bbox](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.bbox) Whether to draw a white bbox around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes. -abcpad : float or unit-spec, default: :rc:`abc.pad` +abcpad : float or unit-spec, default: [abc.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.pad) Horizontal offset to shift the a-b-c label position. Positive values move the label right, negative values move it left. This is separate from `abctitlepad`, which controls spacing between abc and title when co-located. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). abc_kw, title_kw : dict-like, optional Additional settings used to update the a-b-c label and title with ``text.update()``. -titlepad : float, default: :rc:`title.pad` +titlepad : float, default: [title.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.pad) The padding for the inner and outer titles and a-b-c labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -titleabove : bool, default: :rc:`title.above` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +titleabove : bool, default: [title.above](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.above) Whether to try to put outer titles and a-b-c labels above panels, colorbars, or legends that are above the axes. -abctitlepad : float, default: :rc:`abc.titlepad` +abctitlepad : float, default: [abc.titlepad](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.titlepad) The horizontal padding between a-b-c labels and titles in the same location. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle : str or sequence, optional Shorthands for the below keywords. lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle : str or sequence, optional @@ -1268,7 +1268,7 @@ lowerlefttitle, lowercentertitle, lowerrighttitle : str or sequence, optional an alternative to the ``ax.format(title='Title', titleloc=loc)`` workflow and permits adding more than one title-like label for a single axes. a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle : default: - :rc:`axes.alpha` (default: 1.0), :rc:`axes.facecolor` (default: white), :rc:`axes.edgecolor` (default: black), :rc:`axes.linewidth` (default: 0.6), - + [axes.alpha](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.alpha) (default: 1.0), [axes.facecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.facecolor) (default: white), [axes.edgecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.edgecolor) (default: black), [axes.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.linewidth) (default: 0.6), - Additional settings applied to the background patch, and their shorthands. Their defaults values are the ``'axes'`` properties. rowlabels, collabels, llabels, tlabels, rlabels, blabels @@ -1279,14 +1279,14 @@ leftlabels, toplabels, rightlabels, bottomlabels : sequence of str, optional bottom edges of the figure. The length of each list must match the number of subplots along the corresponding edge. leftlabelpad, toplabelpad, rightlabelpad, bottomlabelpad : float or unit-spec, default -: :rc:`leftlabel.pad`, :rc:`toplabel.pad`, :rc:`rightlabel.pad`, :rc:`bottomlabel.pad` +: [leftlabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=leftlabel.pad), [toplabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=toplabel.pad), [rightlabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=rightlabel.pad), [bottomlabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=bottomlabel.pad) The padding between the labels and the axes content. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). leftlabelsharedpad, toplabelsharedpad, rightlabelsharedpad, bottomlabelsharedpad : float or unit-spec, default -: :rc:`leftlabel.sharedpad`, :rc:`toplabel.sharedpad`, :rc:`rightlabel.sharedpad`, :rc:`bottomlabel.sharedpad` +: [leftlabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=leftlabel.sharedpad), [toplabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=toplabel.sharedpad), [rightlabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=rightlabel.sharedpad), [bottomlabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=bottomlabel.sharedpad) The padding between side labels and a shared spanning axis label on the same side. The spanning label is placed outside the side labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). leftlabels_kw, toplabels_kw, rightlabels_kw, bottomlabels_kw : dict-like, optional Additional settings used to update the labels with ``text.update()``. figtitle @@ -1294,9 +1294,9 @@ figtitle suptitle : str, optional The figure "super" title, centered between the left edge of the leftmost subplot and the right edge of the rightmost subplot. -suptitlepad : float, default: :rc:`suptitle.pad` +suptitlepad : float, default: [suptitle.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=suptitle.pad) The padding between the super title and the axes content. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). suptitle_kw : optional Additional settings used to update the super title with ``text.update()``. includepanels : bool, default: False @@ -1304,18 +1304,18 @@ includepanels : bool, default: False of the subplot grid and when aligning the `spanx` *x* axis labels and `spany` *y* axis labels along the sides of the subplot grid. rc_mode : int, optional - The context mode passed to `~ultraplot.config.Configurator.context`. + The context mode passed to [context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context). rc_kw : dict-like, optional An alternative to passing extra keyword arguments. See below. **kwargs - Keyword arguments that match the name of an `~ultraplot.config.rc` setting are - passed to `ultraplot.config.Configurator.context` and used to update the axes. + Keyword arguments that match the name of an [rc](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.rc.html) setting are + passed to [ultraplot.config.Configurator.context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context) and used to update the axes. If the setting name has "dots" you can simply omit the dots. For example, - ``abc='A.'`` modifies the :rcraw:`abc` setting, ``titleloc='left'`` modifies the - :rcraw:`title.loc` setting, ``gridminor=True`` modifies the :rcraw:`gridminor` - setting, and ``gridbelow=True`` modifies the :rcraw:`grid.below` setting. Many + ``abc='A.'`` modifies the [abc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc) setting, ``titleloc='left'`` modifies the + [title.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.loc) setting, ``gridminor=True`` modifies the [gridminor](https://ultraplot.readthedocs.io/en/stable/search.html?q=gridminor) + setting, and ``gridbelow=True`` modifies the [grid.below](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.below) setting. Many of the keyword arguments documented above are internally applied by retrieving - settings passed to `~ultraplot.config.Configurator.context`. + settings passed to [context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context). See also -------- @@ -1347,13 +1347,13 @@ country : bool, optional Natural Earth polygons before plotting. country_reso : {'110m', '50m', '10m'}, optional The Natural Earth country resolution used when `country=True`. - Defaults to :rc:`geo.choropleth.country_reso`. + Defaults to [geo.choropleth.country_reso](https://ultraplot.readthedocs.io/en/stable/search.html?q=geo.choropleth.country_reso). country_territories : bool, optional Whether to keep distant territories for multi-part country geometries when `country=True`. Defaults to - :rc:`geo.choropleth.country_territories`. + [geo.choropleth.country_territories](https://ultraplot.readthedocs.io/en/stable/search.html?q=geo.choropleth.country_territories). colorbar, colorbar_kw - Passed to `~ultraplot.axes.Axes.colorbar`. + Passed to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). missing_kw : dict-like, optional Style applied to geometries whose values are missing or non-finite. If omitted, missing geometries are skipped. @@ -1378,9 +1378,9 @@ Parameters ---------- x_or_y : {'x', 'y'} The axis to add ticks to ('x' for longitude, 'y' for latitude). -itick, ticklen : unit-spec, default: :rc:`tick.len` +itick, ticklen : unit-spec, default: [tick.len](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.len) Major tick lengths for the x and y axis. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Use the argument `ticklen` to set both at once. Notes @@ -1400,8 +1400,8 @@ See: https://cartopy.readthedocs.io/stable/reference/generated/cartopy.mpl.gridl """The cartopy `~cartopy.mpl.gridliner.Gridliner` used for major gridlines or a 2-tuple containing the (longitude, latitude) major gridlines returned by -basemap's :func:`~mpl_toolkits.basemap.Basemap.drawmeridians` -and :func:`~mpl_toolkits.basemap.Basemap.drawparallels`. +basemap's `drawmeridians` +and `drawparallels`. This can be used for customization and debugging.""" ... @@ -1410,8 +1410,8 @@ This can be used for customization and debugging.""" """The cartopy `~cartopy.mpl.gridliner.Gridliner` used for minor gridlines or a 2-tuple containing the (longitude, latitude) minor gridlines returned by -basemap's :func:`~mpl_toolkits.basemap.Basemap.drawmeridians` -and :func:`~mpl_toolkits.basemap.Basemap.drawparallels`. +basemap's `drawmeridians` +and `drawparallels`. This can be used for customization and debugging.""" ... @@ -1448,9 +1448,9 @@ map_projection : ~cartopy.crs.Projection @staticmethod def _get_circle_path(N: int=100) -> mpath.Path: - """Return a circle `~matplotlib.path.Path` used as the outline for polar + """Return a circle [Path](https://matplotlib.org/stable/api/_as_gen/matplotlib.path.Path.html) used as the outline for polar stereographic, azimuthal equidistant, Lambert conformal, and gnomonic -projections. This was developed from `this cartopy example `__.""" +projections. This was developed from [this cartopy example](https://cartopy.readthedocs.io/v0.25.0.post2/gallery/lines_and_polygons/always_circular_stereo.html).""" ... def _get_global_extent(self) -> list[float]: diff --git a/ultraplot/axes/plot.pyi b/ultraplot/axes/plot.pyi index 2831d50d9..1b0a5f3ac 100644 --- a/ultraplot/axes/plot.pyi +++ b/ultraplot/axes/plot.pyi @@ -113,18 +113,18 @@ if a default is provided.""" def _parse_kde_kw(kde_kw: Incomplete=None, *, points: Incomplete=None, weights: Incomplete=None) -> Incomplete: """Split `kde_kw` into the keyword arguments that control the kernel density -estimate, i.e. those accepted by `~ultraplot.internals.inputs._dist_kde`, and -the remaining line properties meant for `~matplotlib.axes.Axes.plot`. The +estimate, i.e. those accepted by [_dist_kde](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.internals.inputs._dist_kde.html), and +the remaining line properties meant for [plot](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.plot.html). The `points` and `weights` arguments supply defaults from the parent command.""" ... def _get_hist_colors(res: Incomplete, n: Incomplete) -> Incomplete: """Return one color per column of a histogram drawn by -`~matplotlib.axes.Axes.hist`, so that overlays can be colored to match.""" +[hist](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.hist.html), so that overlays can be colored to match.""" ... class PlotAxes(base.Axes): - """The second lowest-level `~matplotlib.axes.Axes` subclass used by ultraplot. + """The second lowest-level [Axes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html) subclass used by ultraplot. Implements all plotting overrides.""" def curved_quiver(self, x: np.ndarray, y: np.ndarray, u: np.ndarray, v: np.ndarray, linewidth: Optional[float]=None, color: Optional[Union[str, Any]]=None, cmap: Optional[Any]=None, norm: Optional[Any]=None, arrowsize: Optional[float]=None, arrowstyle: Optional[str]=None, transform: Optional[Any]=None, zorder: Optional[int]=None, start_points: Optional[np.ndarray]=None, scale: Optional[float]=None, grains: Optional[int]=None, density: Optional[int]=None, arrow_at_end: Optional[bool]=None, colorbar: Optional[str]=None, colorbar_kw: Optional[dict[str, Any]]=None) -> Incomplete: @@ -189,22 +189,22 @@ orientations : sequence of int, optional Flow orientations (-1: down, 0: right, 1: up) for Matplotlib's Sankey. pathlengths : float or sequence of float, optional Path lengths for each flow in Matplotlib's Sankey. Defaults to - :rc:`sankey.pathlengths` when omitted. + [sankey.pathlengths](https://ultraplot.readthedocs.io/en/stable/search.html?q=sankey.pathlengths) when omitted. trunklength : float, optional Length of the trunk between the input and output flows. Defaults to - :rc:`sankey.trunklength` when omitted. + [sankey.trunklength](https://ultraplot.readthedocs.io/en/stable/search.html?q=sankey.trunklength) when omitted. patchlabel : str, optional Label for the main patch in Matplotlib's Sankey mode. Defaults to - :rc:`sankey.pathlabel` when omitted. + [sankey.pathlabel](https://ultraplot.readthedocs.io/en/stable/search.html?q=sankey.pathlabel) when omitted. scale, unit, format, gap, radius, shoulder, offset, head_angle, margin, tolerance : optional - Passed to `matplotlib.sankey.Sankey`. + Passed to [matplotlib.sankey.Sankey](https://matplotlib.org/stable/api/_as_gen/matplotlib.sankey.Sankey.html). prior : int, optional Index of a prior diagram to connect to. connect : (int, int), optional Flow indices for the prior and current diagram connection. Defaults to - :rc:`sankey.connect` when omitted. + [sankey.connect](https://ultraplot.readthedocs.io/en/stable/search.html?q=sankey.connect) when omitted. rotation : float, optional - Rotation angle in degrees. Defaults to :rc:`sankey.rotation` when omitted. + Rotation angle in degrees. Defaults to [sankey.rotation](https://ultraplot.readthedocs.io/en/stable/search.html?q=sankey.rotation) when omitted. node_kw, flow_kw, label_kw : dict-like, optional Style dictionaries for the layered Sankey renderer. node_label_kw, flow_label_kw : dict-like, optional @@ -223,45 +223,45 @@ group_cycle : sequence, optional flow_other : float, optional Aggregate flows below this threshold into a single ``other_label``. other_label : str, optional - Label for the aggregated flow target. Defaults to :rc:`sankey.other_label` + Label for the aggregated flow target. Defaults to [sankey.other_label](https://ultraplot.readthedocs.io/en/stable/search.html?q=sankey.other_label) when omitted. value_format : str or callable, optional Formatter for flow labels when not explicitly provided. node_label_outside : {'auto', True, False}, optional Place node labels outside narrow nodes. Defaults to - :rc:`sankey.node_label_outside` when omitted. + [sankey.node_label_outside](https://ultraplot.readthedocs.io/en/stable/search.html?q=sankey.node_label_outside) when omitted. node_label_offset : float, optional Offset for outside node labels (axes-relative units). Defaults to - :rc:`sankey.node_label_offset` when omitted. + [sankey.node_label_offset](https://ultraplot.readthedocs.io/en/stable/search.html?q=sankey.node_label_offset) when omitted. flow_sort : bool, optional Whether to sort flows by target position to reduce crossings. Defaults to - :rc:`sankey.flow_sort` when omitted. + [sankey.flow_sort](https://ultraplot.readthedocs.io/en/stable/search.html?q=sankey.flow_sort) when omitted. flow_label_pos : float, optional Horizontal placement for single flow labels (0 to 1 along the ribbon). - Defaults to :rc:`sankey.flow_label_pos` when omitted. + Defaults to [sankey.flow_label_pos](https://ultraplot.readthedocs.io/en/stable/search.html?q=sankey.flow_label_pos) when omitted. When flow labels overlap, positions are redistributed between 0.25 and 0.75. node_labels, flow_labels : bool, optional Whether to draw node or flow labels in layered mode. Defaults to - :rc:`sankey.node_labels` and :rc:`sankey.flow_labels` when omitted. + [sankey.node_labels](https://ultraplot.readthedocs.io/en/stable/search.html?q=sankey.node_labels) and [sankey.flow_labels](https://ultraplot.readthedocs.io/en/stable/search.html?q=sankey.flow_labels) when omitted. align : {'center', 'top', 'bottom'}, optional Vertical alignment for nodes within each layer in layered mode. Defaults to - :rc:`sankey.align` when omitted. + [sankey.align](https://ultraplot.readthedocs.io/en/stable/search.html?q=sankey.align) when omitted. layers : dict-like, optional Manual layer assignments for nodes in layered mode. **kwargs - Patch properties passed to `matplotlib.sankey.Sankey.add` in Matplotlib mode. + Patch properties passed to [matplotlib.sankey.Sankey.add](https://matplotlib.org/stable/api/_as_gen/matplotlib.sankey.Sankey.add.html) in Matplotlib mode. Layered defaults ---------------- -Layered mode uses :rc:`sankey.nodepad`, :rc:`sankey.nodewidth`, -:rc:`sankey.margin`, :rc:`sankey.flow.alpha`, :rc:`sankey.flow.curvature`, -and :rc:`sankey.node.facecolor` when not set explicitly. +Layered mode uses [sankey.nodepad](https://ultraplot.readthedocs.io/en/stable/search.html?q=sankey.nodepad), [sankey.nodewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=sankey.nodewidth), +[sankey.margin](https://ultraplot.readthedocs.io/en/stable/search.html?q=sankey.margin), [sankey.flow.alpha](https://ultraplot.readthedocs.io/en/stable/search.html?q=sankey.flow.alpha), [sankey.flow.curvature](https://ultraplot.readthedocs.io/en/stable/search.html?q=sankey.flow.curvature), +and [sankey.node.facecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=sankey.node.facecolor) when not set explicitly. Returns ------- matplotlib.sankey.Sankey or list or SankeyDiagram The Sankey diagram instance, or a list for multi-diagram usage. For layered - mode, returns a `~ultraplot.axes.plot_types.sankey.SankeyDiagram`.""" + mode, returns a [SankeyDiagram](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.plot_types.sankey.SankeyDiagram.html).""" ... def ribbon(self, data: Any, *, id_col: str='id', period_col: str='period', topic_col: str='topic', value_col: str | None=None, period_order: Sequence[Any] | None=None, topic_order: Sequence[Any] | None=None, group_map: Mapping[Any, Any] | None=None, group_order: Sequence[Any] | None=None, group_colors: Mapping[Any, Any] | None=None, xmargin: Optional[float]=None, ymargin: Optional[float]=None, row_height_ratio: Optional[float]=None, node_width: Optional[float]=None, flow_curvature: Optional[float]=None, flow_alpha: Optional[float]=None, show_topic_labels: Optional[bool]=None, topic_label_offset: Optional[float]=None, topic_label_size: Optional[float]=None, topic_label_box: Optional[bool]=None) -> dict[str, Any]: @@ -681,7 +681,7 @@ pycirclize.Circos ... def _add_auto_labels(self, obj: Incomplete, cobj: Incomplete=None, labels: Incomplete=False, labels_kw: Incomplete=None, fmt: Incomplete=None, formatter: Incomplete=None, formatter_kw: Incomplete=None, precision: Incomplete=None) -> None: - """Add number labels. Default formatter is `~ultraplot.ticker.SimpleFormatter` + """Add number labels. Default formatter is [SimpleFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.SimpleFormatter.html) with a default maximum precision of ``3`` decimal places.""" ... @@ -752,13 +752,13 @@ the mutable input `extents` to support iteration over columns.""" def _add_kde_lines(self, xs: Incomplete, *, edges: Incomplete, colors: Incomplete, density: Incomplete=None, stack: Incomplete=False, orientation: Incomplete='vertical', points: Incomplete=None, bw_method: Incomplete=None, weights: Incomplete=None, **kwargs: Incomplete) -> Incomplete: """Add a gaussian kernel density estimate line for each column of `xs`, drawn -in `colors` and passing `**kwargs` to `~matplotlib.axes.Axes.plot`. +in `colors` and passing `**kwargs` to [plot](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.plot.html). Unless `density` is ``True`` each estimate is rescaled from a probability density to the bin counts implied by the histogram bin `edges`. Stacked histograms share a single evaluation grid so that the estimates accumulate the way the bin counts do. Remaining arguments go to -`~ultraplot.internals.inputs._dist_kde`.""" +[_dist_kde](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.internals.inputs._dist_kde.html).""" ... def _parse_1d_args(self, x: Incomplete, *ys: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -937,16 +937,16 @@ explicit_limits : bool @staticmethod def _parse_level_norm(levels: Incomplete, norm: Incomplete, cmap: Incomplete, *, extend: Incomplete=None, min_levels: Incomplete=None, discrete_ticks: Incomplete=None, discrete_labels: Incomplete=None, center_levels: Incomplete=None, explicit_limits: Incomplete=False, **kwargs: Incomplete) -> Incomplete: - """Create a `~ultraplot.colors.DiscreteNorm` or `~ultraplot.colors.BoundaryNorm` + """Create a [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) or [BoundaryNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.BoundaryNorm.html) from the input colormap and normalizer. Parameters ---------- levels : sequence of float The level boundaries. -norm : `~matplotlib.colors.Normalize` +norm : [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) The continuous normalizer. -cmap : `~matplotlib.colors.Colormap` +cmap : [Colormap](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Colormap.html) The colormap. extend : str, optional The extend setting. @@ -961,10 +961,10 @@ explicit_limits : bool, optional Returns ------- -norm : `~ultraplot.colors.DiscreteNorm` or `~matplotlib.colors.Normalize` +norm : [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) or [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) The discrete normalizer, or the original continuous normalizer when line contours have explicit limits or use qualitative color lists. -cmap : `~matplotlib.colors.Colormap` +cmap : [Colormap](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Colormap.html) The possibly-modified colormap. kwargs Unused arguments.""" @@ -983,43 +983,42 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `y` coordinates are passed, try to infer the `x` coordinates - from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the - :class:`~xarray.DataArray` coordinates. Otherwise, the `x` coordinates + from the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the + [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `x` coordinates are ``np.arange(0, y.shape[0])``. * If the `y` coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. -linewidth : unit-spec, default: :rc:`lines.linewidth` + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). +linewidth : unit-spec, default: [lines.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.linewidth) The width of the line(s). Aliases: ``lw``, ``linewidths``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -linestyle : str, default: :rc:`lines.linestyle` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +linestyle : str, default: [lines.linestyle](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.linestyle) The style of the line(s). Aliases: ``ls``, ``linestyles``. color : color-spec, optional The color of the line(s). The property `cycle` is used by default. Aliases: ``c``, ``colors``. @@ -1027,11 +1026,11 @@ alpha : float, optional The opacity of the line(s). Inferred from `color` by default. Aliases: ``a``, ``alphas``. mean, means : bool, default: False Whether to plot the means of each column for 2D `y` coordinates. Means - are calculated with `numpy.nanmean`. If no other arguments are specified, + are calculated with [numpy.nanmean](https://numpy.org/doc/stable/reference/generated/numpy.nanmean.html). If no other arguments are specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). median, medians : bool, default: False Whether to plot the medians of each column for 2D `y` coordinates. Medians - are calculated with `numpy.nanmedian`. If no other arguments arguments are + are calculated with [numpy.nanmedian](https://numpy.org/doc/stable/reference/generated/numpy.nanmedian.html). If no other arguments arguments are specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). bars : bool, default: None Shorthand for `barstd`, `barstds`. @@ -1057,15 +1056,15 @@ boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional is ``True``, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When "boxes" and "bars" are combined, this has the effect of drawing miniature box-and-whisker plots. -capsize : float, default: :rc:`errorbar.capsize` +capsize : float, default: [errorbar.capsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=errorbar.capsize) The cap size for thin error bars in points. barz, barzorder, boxz, boxzorder : float, default: 2.5 The "zorder" for the thin and thick error bars. -barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` +barc, barcolor, boxc, boxcolor : color-spec, default: [boxplot.whiskerprops.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.color) Colors for the thin and thick error bars. -barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` +barlw, barlinewidth, boxlw, boxlinewidth : float, default: [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth) Line widths for the thin and thick error bars, in points. The default for boxes - is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. + is 4 times [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth). boxm, boxmarker : bool or marker-spec, default: 'o' Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if `boxes` is ``False``. @@ -1093,7 +1092,7 @@ shadez, shadezorder, fadez, fadezorder : float, default: 1.5 The "zorder" for the different shaded regions. shadea, shadealpha, fadea, fadealpha : float, default: 0.4, 0.2 The opacity for the different shaded regions. -shadelw, shadelinewidth, fadelw, fadelinewidth : float, default: :rc:`patch.linewidth`. +shadelw, shadelinewidth, fadelw, fadelinewidth : float, default: [patch.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.linewidth). The edge line width for the shading patches. shdeec, shadeedgecolor, fadeec, fadeedgecolor : float, default: 'none' The edge color for the shading patches. @@ -1102,10 +1101,10 @@ shadelabel, fadelabel : bool or str, optional labels "on" and apply a *default* label, use e.g. ``shadelabel=True``. To apply a *custom* label, use e.g. ``shadelabel='label'``. Otherwise, the shading is drawn underneath the line and/or marker in the legend entry. -inbounds : bool, default: :rc:`axes.inbounds` +inbounds : bool, default: [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) Whether to restrict the default `y` (`x`) axis limits to account for only in-bounds data when the `x` (`y`) axis limits have been locked. - See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. + See also [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) and [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds). label, value : float or str, optional The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally @@ -1117,22 +1116,22 @@ labels, values : sequence of float or sequence of str, optional colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to :func:`~matplotlib.axes.Axes.plot`. + Passed to [plot](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.plot.html). See also -------- @@ -1150,43 +1149,42 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `x` coordinates are passed, try to infer the `y` coordinates - from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the - :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + from the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the + [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, x.shape[0])``. * If the `x` coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. -linewidth : unit-spec, default: :rc:`lines.linewidth` + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). +linewidth : unit-spec, default: [lines.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.linewidth) The width of the line(s). Aliases: ``lw``, ``linewidths``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -linestyle : str, default: :rc:`lines.linestyle` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +linestyle : str, default: [lines.linestyle](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.linestyle) The style of the line(s). Aliases: ``ls``, ``linestyles``. color : color-spec, optional The color of the line(s). The property `cycle` is used by default. Aliases: ``c``, ``colors``. @@ -1194,11 +1192,11 @@ alpha : float, optional The opacity of the line(s). Inferred from `color` by default. Aliases: ``a``, ``alphas``. mean, means : bool, default: False Whether to plot the means of each column for 2D `x` coordinates. Means - are calculated with `numpy.nanmean`. If no other arguments are specified, + are calculated with [numpy.nanmean](https://numpy.org/doc/stable/reference/generated/numpy.nanmean.html). If no other arguments are specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). median, medians : bool, default: False Whether to plot the medians of each column for 2D `x` coordinates. Medians - are calculated with `numpy.nanmedian`. If no other arguments arguments are + are calculated with [numpy.nanmedian](https://numpy.org/doc/stable/reference/generated/numpy.nanmedian.html). If no other arguments arguments are specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). bars : bool, default: None Shorthand for `barstd`, `barstds`. @@ -1224,15 +1222,15 @@ boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional is ``True``, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When "boxes" and "bars" are combined, this has the effect of drawing miniature box-and-whisker plots. -capsize : float, default: :rc:`errorbar.capsize` +capsize : float, default: [errorbar.capsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=errorbar.capsize) The cap size for thin error bars in points. barz, barzorder, boxz, boxzorder : float, default: 2.5 The "zorder" for the thin and thick error bars. -barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` +barc, barcolor, boxc, boxcolor : color-spec, default: [boxplot.whiskerprops.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.color) Colors for the thin and thick error bars. -barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` +barlw, barlinewidth, boxlw, boxlinewidth : float, default: [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth) Line widths for the thin and thick error bars, in points. The default for boxes - is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. + is 4 times [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth). boxm, boxmarker : bool or marker-spec, default: 'o' Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if `boxes` is ``False``. @@ -1260,7 +1258,7 @@ shadez, shadezorder, fadez, fadezorder : float, default: 1.5 The "zorder" for the different shaded regions. shadea, shadealpha, fadea, fadealpha : float, default: 0.4, 0.2 The opacity for the different shaded regions. -shadelw, shadelinewidth, fadelw, fadelinewidth : float, default: :rc:`patch.linewidth`. +shadelw, shadelinewidth, fadelw, fadelinewidth : float, default: [patch.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.linewidth). The edge line width for the shading patches. shdeec, shadeedgecolor, fadeec, fadeedgecolor : float, default: 'none' The edge color for the shading patches. @@ -1269,10 +1267,10 @@ shadelabel, fadelabel : bool or str, optional labels "on" and apply a *default* label, use e.g. ``shadelabel=True``. To apply a *custom* label, use e.g. ``shadelabel='label'``. Otherwise, the shading is drawn underneath the line and/or marker in the legend entry. -inbounds : bool, default: :rc:`axes.inbounds` +inbounds : bool, default: [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) Whether to restrict the default `y` (`x`) axis limits to account for only in-bounds data when the `x` (`y`) axis limits have been locked. - See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. + See also [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) and [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds). label, value : float or str, optional The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally @@ -1284,22 +1282,22 @@ labels, values : sequence of float or sequence of str, optional colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to :func:`~matplotlib.axes.Axes.plot`. + Passed to [plot](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.plot.html). See also -------- @@ -1313,7 +1311,7 @@ matplotlib.axes.Axes.plot""" ... def beeswarm(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: - """Beeswarm plot with `SHAP-style `_ feature value coloring. + """Beeswarm plot with [SHAP-style](https://shap.readthedocs.io/en/latest/generated/shap.plots.beeswarm.html#shap.plots.beeswarm) feature value coloring. Parameters ---------- @@ -1327,7 +1325,7 @@ n_bins: int or array-like, default: 50 s, size, ms, markersize : float or array-like or unit-spec, optional The marker size area(s). If this is an array matching the shape of `x` and `y`, the units are scaled by `smin` and `smax`. If this contains unit string(s), it - is processed by `~ultraplot.utils.units` and represents the width rather than area. + is processed by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html) and represents the width rather than area. c, color, colors, mc, markercolor, markercolors, fc, facecolor, facecolors : array-like or color-spec, optional The marker color(s). If this is an array matching the shape of `x` and `y`, the colors are generated using `cmap`, `norm`, `vmin`, and `vmax`. Otherwise, @@ -1335,7 +1333,7 @@ n_bins: int or array-like, default: 50 smin, smax : float, optional The minimum and maximum marker size area in units ``points ** 2``. Ignored if `absolute_size` is ``True``. Default value for `smin` is ``1`` and for - `smax` is the square of :rc:`lines.markersize`. + `smax` is the square of [lines.markersize](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.markersize). area_size : bool, default: True Whether the marker sizes `s` are scaled by area or by radius. The default ``True`` is consistent with matplotlib. When `absolute_size` is ``True``, @@ -1356,60 +1354,59 @@ n_bins: int or array-like, default: 50 and `vmax` are some percentile range of the data values. Otherwise, the default `vmin` and `vmax` are the minimum and maximum of the data values. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- - cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` - The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor - function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization - range contains negative and positive values then :rcraw:`cmap.diverging` is used. - Otherwise :rcraw:`cmap.sequential` is used. + cmap : colormap-spec, default: [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) or [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) + The colormap specifer, passed to the [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html) constructor + function. If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization + range contains negative and positive values then [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) is used. + Otherwise [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) is used. cmap_kw : dict-like, optional - Passed to :class:`~ultraplot.constructor.Colormap`. + Passed to [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html). c, color, colors : color-spec or sequence of color-spec, optional - The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + The color(s) used to create a [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html). If not passed, `cmap` is used. -norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` - The data value normalizer, passed to the `~ultraplot.constructor.Norm` +norm : norm-spec, default: [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) or [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) + The data value normalizer, passed to the [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html) constructor function. If `discrete` is ``True`` then 1) this affects the default level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and - 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they - are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). - If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains - negative and positive values then `~ultraplot.colors.DivergingNorm` is used. - Otherwise `~matplotlib.colors.Normalize` is used. + 2) this is passed to [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) to scale the colors before they + are discretized (if `norm` is not already a [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html)). + If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization range contains + negative and positive values then [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) is used. + Otherwise [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) is used. norm_kw : dict-like, optional - Passed to `~ultraplot.constructor.Norm`. + Passed to [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html). extend : {'neither', 'both', 'min', 'max'}, default: 'neither' Direction for drawing colorbar "extensions" indicating out-of-bounds data on the end of the colorbar. -discrete : bool, default: :rc:`cmap.discrete` - If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the +discrete : bool, default: [cmap.discrete](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.discrete) + If ``False``, then [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) is not applied to the colormap. Instead, for non-contour plots, the number of levels will be - roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + roughly controlled by [cmap.lut](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.lut). This has a similar effect to using `levels=large_number` but it may improve rendering speed. Default is - ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` - and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. + ``True`` only for contouring commands like [contourf](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.contourf) + and pseudocolor commands like [pcolor](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.pcolor). sequential, diverging, cyclic, qualitative : bool, default: None Boolean arguments used if `cmap` is not passed. Set these to ``True`` - to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, - :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. - The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + to use the default [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential), [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging), + [cmap.cyclic](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.cyclic), and [cmap.qualitative](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.qualitative) colormaps. + The `diverging` option also applies [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) as the default continuous normalizer. N Shorthand for `levels`. -levels : int or sequence of float, default: :rc:`cmap.levels` +levels : int or sequence of float, default: [cmap.levels](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.levels) The number of level edges or a sequence of level edges. If the former, `locator` is used to generate this many level edges at "nice" intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing @@ -1417,31 +1414,31 @@ levels : int or sequence of float, default: :rc:`cmap.levels` values : int or sequence of float, default: None The number of level centers or a sequence of level centers. If the former, `locator` is used to generate this many level centers at "nice" intervals. - If the latter, levels are inferred using `~ultraplot.utils.edges`. + If the latter, levels are inferred using [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html). This will override any `levels` input. center_levels : bool, default False If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented. - robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` + robust : bool, float, or 2-tuple, default: [cmap.robust](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.robust) If ``True`` and `vmin` or `vmax` were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers. -inbounds : bool, default: :rc:`cmap.inbounds` +inbounds : bool, default: [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) If ``True`` and `vmin` or `vmax` were not provided, when axis limits - have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` - or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. - See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. -locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + have been explicitly restricted with [set_xlim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlim.html) + or [set_ylim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylim.html), out-of-bounds data is ignored. + See also [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) and [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds). +locator : locator-spec, default: [matplotlib.ticker.MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) The locator used to determine level locations if `levels` or `values` were not - already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. - Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. + already passed as lists. Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. + Default is [MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) with `levels` integer levels. locator_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Locator` class. + Keyword arguments passed to [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. symmetric : bool, default: False If ``True``, the normalization range or discrete colormap levels are symmetric about zero. @@ -1453,27 +1450,27 @@ negative : bool, default: False negative with a minimum at zero. nozero : bool, default: False If ``True``, ``0`` is removed from the level list. This is mainly useful for - single-color `~matplotlib.axes.Axes.contour` plots. + single-color [contour](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.contour.html) plots. cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). lw, linewidth, linewidths, mew, markeredgewidth, markeredgewidths : float or sequence, optional The marker edge width(s). edgecolors, markeredgecolor, markeredgecolors : color-spec or sequence, optional The marker edge color(s). mean, means : bool, default: False Whether to plot the means of each column for 2D `y` coordinates. Means - are calculated with `numpy.nanmean`. If no other arguments are specified, + are calculated with [numpy.nanmean](https://numpy.org/doc/stable/reference/generated/numpy.nanmean.html). If no other arguments are specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). median, medians : bool, default: False Whether to plot the medians of each column for 2D `y` coordinates. Medians - are calculated with `numpy.nanmedian`. If no other arguments arguments are + are calculated with [numpy.nanmedian](https://numpy.org/doc/stable/reference/generated/numpy.nanmedian.html). If no other arguments arguments are specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). bars : bool, default: None Shorthand for `barstd`, `barstds`. @@ -1499,15 +1496,15 @@ boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional is ``True``, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When "boxes" and "bars" are combined, this has the effect of drawing miniature box-and-whisker plots. -capsize : float, default: :rc:`errorbar.capsize` +capsize : float, default: [errorbar.capsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=errorbar.capsize) The cap size for thin error bars in points. barz, barzorder, boxz, boxzorder : float, default: 2.5 The "zorder" for the thin and thick error bars. -barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` +barc, barcolor, boxc, boxcolor : color-spec, default: [boxplot.whiskerprops.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.color) Colors for the thin and thick error bars. -barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` +barlw, barlinewidth, boxlw, boxlinewidth : float, default: [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth) Line widths for the thin and thick error bars, in points. The default for boxes - is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. + is 4 times [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth). boxm, boxmarker : bool or marker-spec, default: 'o' Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if `boxes` is ``False``. @@ -1535,7 +1532,7 @@ shadez, shadezorder, fadez, fadezorder : float, default: 1.5 The "zorder" for the different shaded regions. shadea, shadealpha, fadea, fadealpha : float, default: 0.4, 0.2 The opacity for the different shaded regions. -shadelw, shadelinewidth, fadelw, fadelinewidth : float, default: :rc:`patch.linewidth`. +shadelw, shadelinewidth, fadelw, fadelinewidth : float, default: [patch.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.linewidth). The edge line width for the shading patches. shdeec, shadeedgecolor, fadeec, fadeedgecolor : float, default: 'none' The edge color for the shading patches. @@ -1544,10 +1541,10 @@ shadelabel, fadelabel : bool or str, optional labels "on" and apply a *default* label, use e.g. ``shadelabel=True``. To apply a *custom* label, use e.g. ``shadelabel='label'``. Otherwise, the shading is drawn underneath the line and/or marker in the legend entry. - inbounds : bool, default: :rc:`axes.inbounds` + inbounds : bool, default: [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) Whether to restrict the default `y` (`x`) axis limits to account for only in-bounds data when the `x` (`y`) axis limits have been locked. - See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. + See also [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) and [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds). label, value : float or str, optional The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally @@ -1559,22 +1556,22 @@ labels, values : sequence of float or sequence of str, optional colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `~matplotlib.axes.Axes.scatter`. + Passed to [scatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.scatter.html). See also -------- @@ -1591,7 +1588,7 @@ legend_kw : dict-like, optional A lollipop graph is a bar graph with the bars replaced by dots connected to the x-axis by lines. -Inputs such as arrays (`x` or `y`) or dataframes (`pandas` or `xarray`) are passed through :func:`~ultraplot.PlotAxes.bar`. Colors are inferred from the bar objects and parsed automatically. Formatting of the lollipop consists of controlling the `stem` and the `marker`. The stem properties can be set for the width, size, or color. Marker formatting follows the same inputs to :func:`~ultraplot.PlotAxes.scatter`. +Inputs such as arrays (`x` or `y`) or dataframes (`pandas` or `xarray`) are passed through [bar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.PlotAxes.html#ultraplot.PlotAxes.bar). Colors are inferred from the bar objects and parsed automatically. Formatting of the lollipop consists of controlling the `stem` and the `marker`. The stem properties can be set for the width, size, or color. Marker formatting follows the same inputs to [scatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.PlotAxes.html#ultraplot.PlotAxes.scatter). Parameters ---------- @@ -1599,25 +1596,25 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `x` coordinates are passed, try to infer the `y` coordinates - from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the - :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + from the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the + [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, x.shape[0])``. * If the `x` coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. -stemlinewidth : str, default: :rc:`lollipop.stemlinewidth` + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. +stemlinewidth : str, default: [lollipop.stemlinewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=lollipop.stemlinewidth) The width of the lines connecting the dots to the x-axis. -stemcolor : str, default: :rc:`lollipop.stemcolor` - Line color of the lines connecting the dots to the x-axis. Defaults to :rc:`lollipop.linecolor`. -stemlinestyle : str, default: :rc:`lollipop.stemlinestyle` - The style of the lines connecting the dots to the x-axis. Defaults to :rc:`lollipop.linestyle`. +stemcolor : str, default: [lollipop.stemcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=lollipop.stemcolor) + Line color of the lines connecting the dots to the x-axis. Defaults to [lollipop.linecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=lollipop.linecolor). +stemlinestyle : str, default: [lollipop.stemlinestyle](https://ultraplot.readthedocs.io/en/stable/search.html?q=lollipop.stemlinestyle) + The style of the lines connecting the dots to the x-axis. Defaults to [lollipop.linestyle](https://ultraplot.readthedocs.io/en/stable/search.html?q=lollipop.linestyle). s, size, ms, markersize : float or array-like or unit-spec, optional The marker size area(s). If this is an array matching the shape of `x` and `y`, the units are scaled by `smin` and `smax`. If this contains unit string(s), it - is processed by `~ultraplot.utils.units` and represents the width rather than area. + is processed by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html) and represents the width rather than area. c, color, colors, mc, markercolor, markercolors, fc, facecolor, facecolors : array-like or color-spec, optional The marker color(s). If this is an array matching the shape of `x` and `y`, the colors are generated using `cmap`, `norm`, `vmin`, and `vmax`. Otherwise, @@ -1625,7 +1622,7 @@ c, color, colors, mc, markercolor, markercolors, fc, facecolor, facecolors : arr smin, smax : float, optional The minimum and maximum marker size area in units ``points ** 2``. Ignored if `absolute_size` is ``True``. Default value for `smin` is ``1`` and for - `smax` is the square of :rc:`lines.markersize`. + `smax` is the square of [lines.markersize](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.markersize). area_size : bool, default: True Whether the marker sizes `s` are scaled by area or by radius. The default ``True`` is consistent with matplotlib. When `absolute_size` is ``True``, @@ -1646,60 +1643,59 @@ vmin, vmax : float, optional and `vmax` are some percentile range of the data values. Otherwise, the default `vmin` and `vmax` are the minimum and maximum of the data values. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- -cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` - The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor - function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization - range contains negative and positive values then :rcraw:`cmap.diverging` is used. - Otherwise :rcraw:`cmap.sequential` is used. +cmap : colormap-spec, default: [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) or [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) + The colormap specifer, passed to the [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html) constructor + function. If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization + range contains negative and positive values then [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) is used. + Otherwise [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) is used. cmap_kw : dict-like, optional - Passed to :class:`~ultraplot.constructor.Colormap`. + Passed to [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html). c, color, colors : color-spec or sequence of color-spec, optional - The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + The color(s) used to create a [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html). If not passed, `cmap` is used. -norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` - The data value normalizer, passed to the `~ultraplot.constructor.Norm` +norm : norm-spec, default: [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) or [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) + The data value normalizer, passed to the [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html) constructor function. If `discrete` is ``True`` then 1) this affects the default level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and - 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they - are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). - If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains - negative and positive values then `~ultraplot.colors.DivergingNorm` is used. - Otherwise `~matplotlib.colors.Normalize` is used. + 2) this is passed to [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) to scale the colors before they + are discretized (if `norm` is not already a [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html)). + If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization range contains + negative and positive values then [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) is used. + Otherwise [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) is used. norm_kw : dict-like, optional - Passed to `~ultraplot.constructor.Norm`. + Passed to [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html). extend : {'neither', 'both', 'min', 'max'}, default: 'neither' Direction for drawing colorbar "extensions" indicating out-of-bounds data on the end of the colorbar. -discrete : bool, default: :rc:`cmap.discrete` - If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the +discrete : bool, default: [cmap.discrete](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.discrete) + If ``False``, then [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) is not applied to the colormap. Instead, for non-contour plots, the number of levels will be - roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + roughly controlled by [cmap.lut](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.lut). This has a similar effect to using `levels=large_number` but it may improve rendering speed. Default is - ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` - and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. + ``True`` only for contouring commands like [contourf](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.contourf) + and pseudocolor commands like [pcolor](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.pcolor). sequential, diverging, cyclic, qualitative : bool, default: None Boolean arguments used if `cmap` is not passed. Set these to ``True`` - to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, - :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. - The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + to use the default [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential), [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging), + [cmap.cyclic](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.cyclic), and [cmap.qualitative](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.qualitative) colormaps. + The `diverging` option also applies [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) as the default continuous normalizer. N Shorthand for `levels`. -levels : int or sequence of float, default: :rc:`cmap.levels` +levels : int or sequence of float, default: [cmap.levels](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.levels) The number of level edges or a sequence of level edges. If the former, `locator` is used to generate this many level edges at "nice" intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing @@ -1707,31 +1703,31 @@ levels : int or sequence of float, default: :rc:`cmap.levels` values : int or sequence of float, default: None The number of level centers or a sequence of level centers. If the former, `locator` is used to generate this many level centers at "nice" intervals. - If the latter, levels are inferred using `~ultraplot.utils.edges`. + If the latter, levels are inferred using [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html). This will override any `levels` input. center_levels : bool, default False If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented. -robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` +robust : bool, float, or 2-tuple, default: [cmap.robust](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.robust) If ``True`` and `vmin` or `vmax` were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers. -inbounds : bool, default: :rc:`cmap.inbounds` +inbounds : bool, default: [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) If ``True`` and `vmin` or `vmax` were not provided, when axis limits - have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` - or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. - See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. -locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + have been explicitly restricted with [set_xlim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlim.html) + or [set_ylim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylim.html), out-of-bounds data is ignored. + See also [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) and [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds). +locator : locator-spec, default: [matplotlib.ticker.MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) The locator used to determine level locations if `levels` or `values` were not - already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. - Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. + already passed as lists. Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. + Default is [MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) with `levels` integer levels. locator_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Locator` class. + Keyword arguments passed to [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. symmetric : bool, default: False If ``True``, the normalization range or discrete colormap levels are symmetric about zero. @@ -1743,27 +1739,27 @@ negative : bool, default: False negative with a minimum at zero. nozero : bool, default: False If ``True``, ``0`` is removed from the level list. This is mainly useful for - single-color `~matplotlib.axes.Axes.contour` plots. + single-color [contour](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.contour.html) plots. cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). lw, linewidth, linewidths, mew, markeredgewidth, markeredgewidths : float or sequence, optional The marker edge width(s). edgecolors, markeredgecolor, markeredgecolors : color-spec or sequence, optional The marker edge color(s). mean, means : bool, default: False Whether to plot the means of each column for 2D `x` coordinates. Means - are calculated with `numpy.nanmean`. If no other arguments are specified, + are calculated with [numpy.nanmean](https://numpy.org/doc/stable/reference/generated/numpy.nanmean.html). If no other arguments are specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). median, medians : bool, default: False Whether to plot the medians of each column for 2D `x` coordinates. Medians - are calculated with `numpy.nanmedian`. If no other arguments arguments are + are calculated with [numpy.nanmedian](https://numpy.org/doc/stable/reference/generated/numpy.nanmedian.html). If no other arguments arguments are specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). bars : bool, default: None Shorthand for `barstd`, `barstds`. @@ -1789,15 +1785,15 @@ boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional is ``True``, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When "boxes" and "bars" are combined, this has the effect of drawing miniature box-and-whisker plots. -capsize : float, default: :rc:`errorbar.capsize` +capsize : float, default: [errorbar.capsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=errorbar.capsize) The cap size for thin error bars in points. barz, barzorder, boxz, boxzorder : float, default: 2.5 The "zorder" for the thin and thick error bars. -barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` +barc, barcolor, boxc, boxcolor : color-spec, default: [boxplot.whiskerprops.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.color) Colors for the thin and thick error bars. -barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` +barlw, barlinewidth, boxlw, boxlinewidth : float, default: [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth) Line widths for the thin and thick error bars, in points. The default for boxes - is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. + is 4 times [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth). boxm, boxmarker : bool or marker-spec, default: 'o' Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if `boxes` is ``False``. @@ -1825,7 +1821,7 @@ shadez, shadezorder, fadez, fadezorder : float, default: 1.5 The "zorder" for the different shaded regions. shadea, shadealpha, fadea, fadealpha : float, default: 0.4, 0.2 The opacity for the different shaded regions. -shadelw, shadelinewidth, fadelw, fadelinewidth : float, default: :rc:`patch.linewidth`. +shadelw, shadelinewidth, fadelw, fadelinewidth : float, default: [patch.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.linewidth). The edge line width for the shading patches. shdeec, shadeedgecolor, fadeec, fadeedgecolor : float, default: 'none' The edge color for the shading patches. @@ -1834,10 +1830,10 @@ shadelabel, fadelabel : bool or str, optional labels "on" and apply a *default* label, use e.g. ``shadelabel=True``. To apply a *custom* label, use e.g. ``shadelabel='label'``. Otherwise, the shading is drawn underneath the line and/or marker in the legend entry. -inbounds : bool, default: :rc:`axes.inbounds` +inbounds : bool, default: [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) Whether to restrict the default `y` (`x`) axis limits to account for only in-bounds data when the `x` (`y`) axis limits have been locked. - See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. + See also [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) and [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds). label, value : float or str, optional The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally @@ -1849,24 +1845,24 @@ labels, values : sequence of float or sequence of str, optional colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `~matplotlib.axes.Axes.scatter`. + Passed to [scatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.scatter.html). -See for more info on the grouping behavior :func:`~ultraplot.PlotAxes.bar`, and for formatting :func:`~ultraplot.PlotAxes.scatter`. +See for more info on the grouping behavior [bar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.PlotAxes.html#ultraplot.PlotAxes.bar), and for formatting [scatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.PlotAxes.html#ultraplot.PlotAxes.scatter). Returns ------- List of ~matplotlib.collections.PatchCollection, and a ~matplotlib.collections.LineCollection""" @@ -1877,7 +1873,7 @@ List of ~matplotlib.collections.PatchCollection, and a ~matplotlib.collections.L A lollipop graph is a bar graph with the bars replaced by dots connected to the x-axis by lines. -Inputs such as arrays (`x` or `y`) or dataframes (`pandas` or `xarray`) are passed through :func:`~ultraplot.PlotAxes.bar`. Colors are inferred from the bar objects and parsed automatically. Formatting of the lollipop consists of controlling the `stem` and the `marker`. The stem properties can be set for the width, size, or color. Marker formatting follows the same inputs to :func:`~ultraplot.PlotAxes.scatter`. +Inputs such as arrays (`x` or `y`) or dataframes (`pandas` or `xarray`) are passed through [bar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.PlotAxes.html#ultraplot.PlotAxes.bar). Colors are inferred from the bar objects and parsed automatically. Formatting of the lollipop consists of controlling the `stem` and the `marker`. The stem properties can be set for the width, size, or color. Marker formatting follows the same inputs to [scatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.PlotAxes.html#ultraplot.PlotAxes.scatter). Parameters ---------- @@ -1885,25 +1881,25 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `x` coordinates are passed, try to infer the `y` coordinates - from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the - :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + from the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the + [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, x.shape[0])``. * If the `x` coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. -stemlinewidth : str, default: :rc:`lollipop.stemlinewidth` + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. +stemlinewidth : str, default: [lollipop.stemlinewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=lollipop.stemlinewidth) The width of the lines connecting the dots to the x-axis. -stemcolor : str, default: :rc:`lollipop.stemcolor` - Line color of the lines connecting the dots to the x-axis. Defaults to :rc:`lollipop.linecolor`. -stemlinestyle : str, default: :rc:`lollipop.stemlinestyle` - The style of the lines connecting the dots to the x-axis. Defaults to :rc:`lollipop.linestyle`. +stemcolor : str, default: [lollipop.stemcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=lollipop.stemcolor) + Line color of the lines connecting the dots to the x-axis. Defaults to [lollipop.linecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=lollipop.linecolor). +stemlinestyle : str, default: [lollipop.stemlinestyle](https://ultraplot.readthedocs.io/en/stable/search.html?q=lollipop.stemlinestyle) + The style of the lines connecting the dots to the x-axis. Defaults to [lollipop.linestyle](https://ultraplot.readthedocs.io/en/stable/search.html?q=lollipop.linestyle). s, size, ms, markersize : float or array-like or unit-spec, optional The marker size area(s). If this is an array matching the shape of `x` and `y`, the units are scaled by `smin` and `smax`. If this contains unit string(s), it - is processed by `~ultraplot.utils.units` and represents the width rather than area. + is processed by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html) and represents the width rather than area. c, color, colors, mc, markercolor, markercolors, fc, facecolor, facecolors : array-like or color-spec, optional The marker color(s). If this is an array matching the shape of `x` and `y`, the colors are generated using `cmap`, `norm`, `vmin`, and `vmax`. Otherwise, @@ -1911,7 +1907,7 @@ c, color, colors, mc, markercolor, markercolors, fc, facecolor, facecolors : arr smin, smax : float, optional The minimum and maximum marker size area in units ``points ** 2``. Ignored if `absolute_size` is ``True``. Default value for `smin` is ``1`` and for - `smax` is the square of :rc:`lines.markersize`. + `smax` is the square of [lines.markersize](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.markersize). area_size : bool, default: True Whether the marker sizes `s` are scaled by area or by radius. The default ``True`` is consistent with matplotlib. When `absolute_size` is ``True``, @@ -1932,60 +1928,59 @@ vmin, vmax : float, optional and `vmax` are some percentile range of the data values. Otherwise, the default `vmin` and `vmax` are the minimum and maximum of the data values. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- -cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` - The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor - function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization - range contains negative and positive values then :rcraw:`cmap.diverging` is used. - Otherwise :rcraw:`cmap.sequential` is used. +cmap : colormap-spec, default: [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) or [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) + The colormap specifer, passed to the [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html) constructor + function. If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization + range contains negative and positive values then [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) is used. + Otherwise [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) is used. cmap_kw : dict-like, optional - Passed to :class:`~ultraplot.constructor.Colormap`. + Passed to [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html). c, color, colors : color-spec or sequence of color-spec, optional - The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + The color(s) used to create a [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html). If not passed, `cmap` is used. -norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` - The data value normalizer, passed to the `~ultraplot.constructor.Norm` +norm : norm-spec, default: [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) or [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) + The data value normalizer, passed to the [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html) constructor function. If `discrete` is ``True`` then 1) this affects the default level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and - 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they - are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). - If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains - negative and positive values then `~ultraplot.colors.DivergingNorm` is used. - Otherwise `~matplotlib.colors.Normalize` is used. + 2) this is passed to [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) to scale the colors before they + are discretized (if `norm` is not already a [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html)). + If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization range contains + negative and positive values then [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) is used. + Otherwise [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) is used. norm_kw : dict-like, optional - Passed to `~ultraplot.constructor.Norm`. + Passed to [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html). extend : {'neither', 'both', 'min', 'max'}, default: 'neither' Direction for drawing colorbar "extensions" indicating out-of-bounds data on the end of the colorbar. -discrete : bool, default: :rc:`cmap.discrete` - If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the +discrete : bool, default: [cmap.discrete](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.discrete) + If ``False``, then [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) is not applied to the colormap. Instead, for non-contour plots, the number of levels will be - roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + roughly controlled by [cmap.lut](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.lut). This has a similar effect to using `levels=large_number` but it may improve rendering speed. Default is - ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` - and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. + ``True`` only for contouring commands like [contourf](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.contourf) + and pseudocolor commands like [pcolor](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.pcolor). sequential, diverging, cyclic, qualitative : bool, default: None Boolean arguments used if `cmap` is not passed. Set these to ``True`` - to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, - :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. - The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + to use the default [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential), [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging), + [cmap.cyclic](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.cyclic), and [cmap.qualitative](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.qualitative) colormaps. + The `diverging` option also applies [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) as the default continuous normalizer. N Shorthand for `levels`. -levels : int or sequence of float, default: :rc:`cmap.levels` +levels : int or sequence of float, default: [cmap.levels](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.levels) The number of level edges or a sequence of level edges. If the former, `locator` is used to generate this many level edges at "nice" intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing @@ -1993,31 +1988,31 @@ levels : int or sequence of float, default: :rc:`cmap.levels` values : int or sequence of float, default: None The number of level centers or a sequence of level centers. If the former, `locator` is used to generate this many level centers at "nice" intervals. - If the latter, levels are inferred using `~ultraplot.utils.edges`. + If the latter, levels are inferred using [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html). This will override any `levels` input. center_levels : bool, default False If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented. -robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` +robust : bool, float, or 2-tuple, default: [cmap.robust](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.robust) If ``True`` and `vmin` or `vmax` were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers. -inbounds : bool, default: :rc:`cmap.inbounds` +inbounds : bool, default: [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) If ``True`` and `vmin` or `vmax` were not provided, when axis limits - have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` - or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. - See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. -locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + have been explicitly restricted with [set_xlim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlim.html) + or [set_ylim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylim.html), out-of-bounds data is ignored. + See also [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) and [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds). +locator : locator-spec, default: [matplotlib.ticker.MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) The locator used to determine level locations if `levels` or `values` were not - already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. - Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. + already passed as lists. Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. + Default is [MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) with `levels` integer levels. locator_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Locator` class. + Keyword arguments passed to [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. symmetric : bool, default: False If ``True``, the normalization range or discrete colormap levels are symmetric about zero. @@ -2029,27 +2024,27 @@ negative : bool, default: False negative with a minimum at zero. nozero : bool, default: False If ``True``, ``0`` is removed from the level list. This is mainly useful for - single-color `~matplotlib.axes.Axes.contour` plots. + single-color [contour](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.contour.html) plots. cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). lw, linewidth, linewidths, mew, markeredgewidth, markeredgewidths : float or sequence, optional The marker edge width(s). edgecolors, markeredgecolor, markeredgecolors : color-spec or sequence, optional The marker edge color(s). mean, means : bool, default: False Whether to plot the means of each column for 2D `x` coordinates. Means - are calculated with `numpy.nanmean`. If no other arguments are specified, + are calculated with [numpy.nanmean](https://numpy.org/doc/stable/reference/generated/numpy.nanmean.html). If no other arguments are specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). median, medians : bool, default: False Whether to plot the medians of each column for 2D `x` coordinates. Medians - are calculated with `numpy.nanmedian`. If no other arguments arguments are + are calculated with [numpy.nanmedian](https://numpy.org/doc/stable/reference/generated/numpy.nanmedian.html). If no other arguments arguments are specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). bars : bool, default: None Shorthand for `barstd`, `barstds`. @@ -2075,15 +2070,15 @@ boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional is ``True``, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When "boxes" and "bars" are combined, this has the effect of drawing miniature box-and-whisker plots. -capsize : float, default: :rc:`errorbar.capsize` +capsize : float, default: [errorbar.capsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=errorbar.capsize) The cap size for thin error bars in points. barz, barzorder, boxz, boxzorder : float, default: 2.5 The "zorder" for the thin and thick error bars. -barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` +barc, barcolor, boxc, boxcolor : color-spec, default: [boxplot.whiskerprops.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.color) Colors for the thin and thick error bars. -barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` +barlw, barlinewidth, boxlw, boxlinewidth : float, default: [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth) Line widths for the thin and thick error bars, in points. The default for boxes - is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. + is 4 times [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth). boxm, boxmarker : bool or marker-spec, default: 'o' Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if `boxes` is ``False``. @@ -2111,7 +2106,7 @@ shadez, shadezorder, fadez, fadezorder : float, default: 1.5 The "zorder" for the different shaded regions. shadea, shadealpha, fadea, fadealpha : float, default: 0.4, 0.2 The opacity for the different shaded regions. -shadelw, shadelinewidth, fadelw, fadelinewidth : float, default: :rc:`patch.linewidth`. +shadelw, shadelinewidth, fadelw, fadelinewidth : float, default: [patch.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.linewidth). The edge line width for the shading patches. shdeec, shadeedgecolor, fadeec, fadeedgecolor : float, default: 'none' The edge color for the shading patches. @@ -2120,10 +2115,10 @@ shadelabel, fadelabel : bool or str, optional labels "on" and apply a *default* label, use e.g. ``shadelabel=True``. To apply a *custom* label, use e.g. ``shadelabel='label'``. Otherwise, the shading is drawn underneath the line and/or marker in the legend entry. -inbounds : bool, default: :rc:`axes.inbounds` +inbounds : bool, default: [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) Whether to restrict the default `y` (`x`) axis limits to account for only in-bounds data when the `x` (`y`) axis limits have been locked. - See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. + See also [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) and [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds). label, value : float or str, optional The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally @@ -2135,24 +2130,24 @@ labels, values : sequence of float or sequence of str, optional colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `~matplotlib.axes.Axes.scatter`. + Passed to [scatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.scatter.html). -See for more info on the grouping behavior :func:`~ultraplot.PlotAxes.bar`, and for formatting :func:`~ultraplot.PlotAxes.scatter`. +See for more info on the grouping behavior [bar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.PlotAxes.html#ultraplot.PlotAxes.bar), and for formatting [scatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.PlotAxes.html#ultraplot.PlotAxes.scatter). Returns ------- List of ~matplotlib.collections.PatchCollection, and a ~matplotlib.collections.LineCollection (horizontal lollipop)""" @@ -2207,7 +2202,7 @@ Notes .. note:: - This is the :ref:`pyplot wrapper ` for `.axes.Axes.loglog`.""" + This is the [pyplot wrapper](https://ultraplot.readthedocs.io/en/stable/search.html?q=pyplot_interface) for `.axes.Axes.loglog`.""" ... def semilogy(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -2256,7 +2251,7 @@ Notes .. note:: - This is the :ref:`pyplot wrapper ` for `.axes.Axes.semilogy`.""" + This is the [pyplot wrapper](https://ultraplot.readthedocs.io/en/stable/search.html?q=pyplot_interface) for `.axes.Axes.semilogy`.""" ... def semilogx(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -2305,7 +2300,7 @@ Notes .. note:: - This is the :ref:`pyplot wrapper ` for `.axes.Axes.semilogx`.""" + This is the [pyplot wrapper](https://ultraplot.readthedocs.io/en/stable/search.html?q=pyplot_interface) for `.axes.Axes.semilogx`.""" ... def plot(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -2317,43 +2312,42 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `y` coordinates are passed, try to infer the `x` coordinates - from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the - :class:`~xarray.DataArray` coordinates. Otherwise, the `x` coordinates + from the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the + [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `x` coordinates are ``np.arange(0, y.shape[0])``. * If the `y` coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. -linewidth : unit-spec, default: :rc:`lines.linewidth` + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). +linewidth : unit-spec, default: [lines.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.linewidth) The width of the line(s). Aliases: ``lw``, ``linewidths``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -linestyle : str, default: :rc:`lines.linestyle` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +linestyle : str, default: [lines.linestyle](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.linestyle) The style of the line(s). Aliases: ``ls``, ``linestyles``. color : color-spec, optional The color of the line(s). The property `cycle` is used by default. Aliases: ``c``, ``colors``. @@ -2361,11 +2355,11 @@ alpha : float, optional The opacity of the line(s). Inferred from `color` by default. Aliases: ``a``, ``alphas``. mean, means : bool, default: False Whether to plot the means of each column for 2D `y` coordinates. Means - are calculated with `numpy.nanmean`. If no other arguments are specified, + are calculated with [numpy.nanmean](https://numpy.org/doc/stable/reference/generated/numpy.nanmean.html). If no other arguments are specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). median, medians : bool, default: False Whether to plot the medians of each column for 2D `y` coordinates. Medians - are calculated with `numpy.nanmedian`. If no other arguments arguments are + are calculated with [numpy.nanmedian](https://numpy.org/doc/stable/reference/generated/numpy.nanmedian.html). If no other arguments arguments are specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). bars : bool, default: None Shorthand for `barstd`, `barstds`. @@ -2391,15 +2385,15 @@ boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional is ``True``, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When "boxes" and "bars" are combined, this has the effect of drawing miniature box-and-whisker plots. -capsize : float, default: :rc:`errorbar.capsize` +capsize : float, default: [errorbar.capsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=errorbar.capsize) The cap size for thin error bars in points. barz, barzorder, boxz, boxzorder : float, default: 2.5 The "zorder" for the thin and thick error bars. -barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` +barc, barcolor, boxc, boxcolor : color-spec, default: [boxplot.whiskerprops.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.color) Colors for the thin and thick error bars. -barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` +barlw, barlinewidth, boxlw, boxlinewidth : float, default: [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth) Line widths for the thin and thick error bars, in points. The default for boxes - is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. + is 4 times [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth). boxm, boxmarker : bool or marker-spec, default: 'o' Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if `boxes` is ``False``. @@ -2427,7 +2421,7 @@ shadez, shadezorder, fadez, fadezorder : float, default: 1.5 The "zorder" for the different shaded regions. shadea, shadealpha, fadea, fadealpha : float, default: 0.4, 0.2 The opacity for the different shaded regions. -shadelw, shadelinewidth, fadelw, fadelinewidth : float, default: :rc:`patch.linewidth`. +shadelw, shadelinewidth, fadelw, fadelinewidth : float, default: [patch.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.linewidth). The edge line width for the shading patches. shdeec, shadeedgecolor, fadeec, fadeedgecolor : float, default: 'none' The edge color for the shading patches. @@ -2436,10 +2430,10 @@ shadelabel, fadelabel : bool or str, optional labels "on" and apply a *default* label, use e.g. ``shadelabel=True``. To apply a *custom* label, use e.g. ``shadelabel='label'``. Otherwise, the shading is drawn underneath the line and/or marker in the legend entry. -inbounds : bool, default: :rc:`axes.inbounds` +inbounds : bool, default: [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) Whether to restrict the default `y` (`x`) axis limits to account for only in-bounds data when the `x` (`y`) axis limits have been locked. - See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. + See also [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) and [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds). label, value : float or str, optional The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally @@ -2451,22 +2445,22 @@ labels, values : sequence of float or sequence of str, optional colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to :func:`~matplotlib.axes.Axes.plot`. + Passed to [plot](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.plot.html). See also -------- @@ -2516,7 +2510,7 @@ parameter and just give the labels for *x* and *y*:: >>> plot('xlabel', 'ylabel', data=obj) All indexable objects are supported. This could e.g. be a `dict`, a -`pandas.DataFrame` or a structured numpy array. +[pandas.DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or a structured numpy array. **Plotting multiple sets of data** @@ -2558,7 +2552,7 @@ By default, each line is assigned a different style specified by a 'style cycle'. The *fmt* and line property parameters are only necessary if you want explicit deviations from these defaults. Alternatively, you can also change the style cycle using -:rc:`axes.prop_cycle`. +[axes.prop_cycle](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.prop_cycle). Parameters @@ -2608,7 +2602,7 @@ scalex, scaley : bool, default: True data limits. The values are passed on to `~.axes.Axes.autoscale_view`. -**kwargs : `~matplotlib.lines.Line2D` properties, optional +**kwargs : [Line2D](https://matplotlib.org/stable/api/_as_gen/matplotlib.lines.Line2D.html) properties, optional *kwargs* are used to specify properties like a line label (for auto legends), linewidth, antialiasing, marker face color. Example:: @@ -2627,28 +2621,28 @@ scalex, scaley : bool, default: True alpha: float or None animated: bool antialiased or aa: bool - clip_box: `~matplotlib.transforms.BboxBase` or None + clip_box: [BboxBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.BboxBase.html) or None clip_on: bool clip_path: Patch or (Path, Transform) or None - color or c: :mpltype:`color` + color or c: [color](https://matplotlib.org/stable/search.html?q=color) dash_capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} dash_joinstyle: `.JoinStyle` or {'miter', 'round', 'bevel'} dashes: sequence of floats (on/off ink in points) or (None, None) data: (2, N) array or two 1D arrays drawstyle or ds: {'default', 'steps', 'steps-pre', 'steps-mid', 'steps-post'}, default: 'default' - figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + figure: [Figure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html) or [SubFigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.SubFigure.html) fillstyle: {'full', 'left', 'right', 'bottom', 'top', 'none'} - gapcolor: :mpltype:`color` or None + gapcolor: [color](https://matplotlib.org/stable/search.html?q=color) or None gid: str in_layout: bool label: object linestyle or ls: {'-', '--', '-.', ':', '', (offset, on-off-seq), ...} linewidth or lw: float marker: marker style string, `~.path.Path` or `~.markers.MarkerStyle` - markeredgecolor or mec: :mpltype:`color` + markeredgecolor or mec: [color](https://matplotlib.org/stable/search.html?q=color) markeredgewidth or mew: float - markerfacecolor or mfc: :mpltype:`color` - markerfacecoloralt or mfcalt: :mpltype:`color` + markerfacecolor or mfc: [color](https://matplotlib.org/stable/search.html?q=color) + markerfacecoloralt or mfcalt: [color](https://matplotlib.org/stable/search.html?q=color) markersize or ms: float markevery: None or int or (int, int) or slice or list[int] or float or (float, float) or list[bool] mouseover: bool @@ -2758,7 +2752,7 @@ character color and the ``'CN'`` colors that index into the default property cycle. If the color is the only part of the format string, you can -additionally use any `matplotlib.colors` spec, e.g. full names +additionally use any [matplotlib.colors](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.html) spec, e.g. full names (``'green'``) or hex strings (``'#008000'``).""" ... @@ -2771,43 +2765,42 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `x` coordinates are passed, try to infer the `y` coordinates - from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the - :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + from the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the + [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, x.shape[0])``. * If the `x` coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. -linewidth : unit-spec, default: :rc:`lines.linewidth` + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). +linewidth : unit-spec, default: [lines.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.linewidth) The width of the line(s). Aliases: ``lw``, ``linewidths``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -linestyle : str, default: :rc:`lines.linestyle` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +linestyle : str, default: [lines.linestyle](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.linestyle) The style of the line(s). Aliases: ``ls``, ``linestyles``. color : color-spec, optional The color of the line(s). The property `cycle` is used by default. Aliases: ``c``, ``colors``. @@ -2815,11 +2808,11 @@ alpha : float, optional The opacity of the line(s). Inferred from `color` by default. Aliases: ``a``, ``alphas``. mean, means : bool, default: False Whether to plot the means of each column for 2D `x` coordinates. Means - are calculated with `numpy.nanmean`. If no other arguments are specified, + are calculated with [numpy.nanmean](https://numpy.org/doc/stable/reference/generated/numpy.nanmean.html). If no other arguments are specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). median, medians : bool, default: False Whether to plot the medians of each column for 2D `x` coordinates. Medians - are calculated with `numpy.nanmedian`. If no other arguments arguments are + are calculated with [numpy.nanmedian](https://numpy.org/doc/stable/reference/generated/numpy.nanmedian.html). If no other arguments arguments are specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). bars : bool, default: None Shorthand for `barstd`, `barstds`. @@ -2845,15 +2838,15 @@ boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional is ``True``, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When "boxes" and "bars" are combined, this has the effect of drawing miniature box-and-whisker plots. -capsize : float, default: :rc:`errorbar.capsize` +capsize : float, default: [errorbar.capsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=errorbar.capsize) The cap size for thin error bars in points. barz, barzorder, boxz, boxzorder : float, default: 2.5 The "zorder" for the thin and thick error bars. -barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` +barc, barcolor, boxc, boxcolor : color-spec, default: [boxplot.whiskerprops.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.color) Colors for the thin and thick error bars. -barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` +barlw, barlinewidth, boxlw, boxlinewidth : float, default: [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth) Line widths for the thin and thick error bars, in points. The default for boxes - is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. + is 4 times [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth). boxm, boxmarker : bool or marker-spec, default: 'o' Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if `boxes` is ``False``. @@ -2881,7 +2874,7 @@ shadez, shadezorder, fadez, fadezorder : float, default: 1.5 The "zorder" for the different shaded regions. shadea, shadealpha, fadea, fadealpha : float, default: 0.4, 0.2 The opacity for the different shaded regions. -shadelw, shadelinewidth, fadelw, fadelinewidth : float, default: :rc:`patch.linewidth`. +shadelw, shadelinewidth, fadelw, fadelinewidth : float, default: [patch.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.linewidth). The edge line width for the shading patches. shdeec, shadeedgecolor, fadeec, fadeedgecolor : float, default: 'none' The edge color for the shading patches. @@ -2890,10 +2883,10 @@ shadelabel, fadelabel : bool or str, optional labels "on" and apply a *default* label, use e.g. ``shadelabel=True``. To apply a *custom* label, use e.g. ``shadelabel='label'``. Otherwise, the shading is drawn underneath the line and/or marker in the legend entry. -inbounds : bool, default: :rc:`axes.inbounds` +inbounds : bool, default: [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) Whether to restrict the default `y` (`x`) axis limits to account for only in-bounds data when the `x` (`y`) axis limits have been locked. - See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. + See also [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) and [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds). label, value : float or str, optional The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally @@ -2905,22 +2898,22 @@ labels, values : sequence of float or sequence of str, optional colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to :func:`~matplotlib.axes.Axes.plot`. + Passed to [plot](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.plot.html). See also -------- @@ -2942,52 +2935,51 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `y` coordinates are passed, try to infer the `x` coordinates - from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the - :class:`~xarray.DataArray` coordinates. Otherwise, the `x` coordinates + from the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the + [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `x` coordinates are ``np.arange(0, y.shape[0])``. * If the `y` coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. -linewidth : unit-spec, default: :rc:`lines.linewidth` + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). +linewidth : unit-spec, default: [lines.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.linewidth) The width of the line(s). Aliases: ``lw``, ``linewidths``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -linestyle : str, default: :rc:`lines.linestyle` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +linestyle : str, default: [lines.linestyle](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.linestyle) The style of the line(s). Aliases: ``ls``, ``linestyles``. color : color-spec, optional The color of the line(s). The property `cycle` is used by default. Aliases: ``c``, ``colors``. alpha : float, optional The opacity of the line(s). Inferred from `color` by default. Aliases: ``a``, ``alphas``. -inbounds : bool, default: :rc:`axes.inbounds` +inbounds : bool, default: [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) Whether to restrict the default `y` (`x`) axis limits to account for only in-bounds data when the `x` (`y`) axis limits have been locked. - See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. + See also [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) and [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds). label, value : float or str, optional The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally @@ -2999,22 +2991,22 @@ labels, values : sequence of float or sequence of str, optional colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `~matplotlib.axes.Axes.step`. + Passed to [step](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.step.html). See also -------- @@ -3097,52 +3089,51 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `x` coordinates are passed, try to infer the `y` coordinates - from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the - :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + from the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the + [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, x.shape[0])``. * If the `x` coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. -linewidth : unit-spec, default: :rc:`lines.linewidth` + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). +linewidth : unit-spec, default: [lines.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.linewidth) The width of the line(s). Aliases: ``lw``, ``linewidths``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -linestyle : str, default: :rc:`lines.linestyle` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +linestyle : str, default: [lines.linestyle](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.linestyle) The style of the line(s). Aliases: ``ls``, ``linestyles``. color : color-spec, optional The color of the line(s). The property `cycle` is used by default. Aliases: ``c``, ``colors``. alpha : float, optional The opacity of the line(s). Inferred from `color` by default. Aliases: ``a``, ``alphas``. -inbounds : bool, default: :rc:`axes.inbounds` +inbounds : bool, default: [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) Whether to restrict the default `y` (`x`) axis limits to account for only in-bounds data when the `x` (`y`) axis limits have been locked. - See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. + See also [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) and [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds). label, value : float or str, optional The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally @@ -3154,22 +3145,22 @@ labels, values : sequence of float or sequence of str, optional colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `~matplotlib.axes.Axes.step`. + Passed to [step](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.step.html). See also -------- @@ -3191,62 +3182,61 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `x` coordinates are passed, try to infer the `y` coordinates - from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the - :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + from the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the + [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, x.shape[0])``. * If the `x` coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. -inbounds : bool, default: :rc:`axes.inbounds` + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). +inbounds : bool, default: [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) Whether to restrict the default `y` (`x`) axis limits to account for only in-bounds data when the `x` (`y`) axis limits have been locked. - See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. + See also [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) and [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds). colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `~matplotlib.axes.Axes.stem`. + Passed to [stem](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.stem.html). Matplotlib documentation @@ -3327,7 +3317,7 @@ Notes ----- .. seealso:: The MATLAB function - `stem `_ + [stem](https://www.mathworks.com/help/matlab/ref/stem.html) which inspired this method.""" ... @@ -3340,62 +3330,61 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `x` coordinates are passed, try to infer the `y` coordinates - from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the - :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + from the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the + [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, x.shape[0])``. * If the `x` coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. -inbounds : bool, default: :rc:`axes.inbounds` + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). +inbounds : bool, default: [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) Whether to restrict the default `y` (`x`) axis limits to account for only in-bounds data when the `x` (`y`) axis limits have been locked. - See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. + See also [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) and [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds). colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `~matplotlib.axes.Axes.stem`.""" + Passed to [stem](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.stem.html).""" ... def parametric(self, x: Incomplete, y: Incomplete, c: Incomplete, *, interp: Incomplete=0, scalex: Incomplete=True, scaley: Incomplete=True, **kwargs: Incomplete) -> Incomplete: @@ -3407,15 +3396,15 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `y` coordinates are passed, try to infer the `x` coordinates - from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the - :class:`~xarray.DataArray` coordinates. Otherwise, the `x` coordinates + from the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the + [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `x` coordinates are ``np.arange(0, y.shape[0])``. * If the `y` coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. c, color, colors, values, labels : sequence of float, str, or color-spec, optional The parametric coordinate(s). These can be passed as a third positional argument or as a keyword argument. If they are float, the colors will be @@ -3429,56 +3418,55 @@ interp : int, default: 0 coordinates. This can be increased to make the color gradations between a small number of coordinates appear "smooth". data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- -cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` - The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor - function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization - range contains negative and positive values then :rcraw:`cmap.diverging` is used. - Otherwise :rcraw:`cmap.sequential` is used. +cmap : colormap-spec, default: [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) or [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) + The colormap specifer, passed to the [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html) constructor + function. If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization + range contains negative and positive values then [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) is used. + Otherwise [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) is used. cmap_kw : dict-like, optional - Passed to :class:`~ultraplot.constructor.Colormap`. + Passed to [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html). c, color, colors : color-spec or sequence of color-spec, optional - The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + The color(s) used to create a [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html). If not passed, `cmap` is used. -norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` - The data value normalizer, passed to the `~ultraplot.constructor.Norm` +norm : norm-spec, default: [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) or [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) + The data value normalizer, passed to the [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html) constructor function. If `discrete` is ``True`` then 1) this affects the default level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and - 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they - are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). - If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains - negative and positive values then `~ultraplot.colors.DivergingNorm` is used. - Otherwise `~matplotlib.colors.Normalize` is used. + 2) this is passed to [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) to scale the colors before they + are discretized (if `norm` is not already a [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html)). + If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization range contains + negative and positive values then [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) is used. + Otherwise [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) is used. norm_kw : dict-like, optional - Passed to `~ultraplot.constructor.Norm`. + Passed to [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html). extend : {'neither', 'both', 'min', 'max'}, default: 'neither' Direction for drawing colorbar "extensions" indicating out-of-bounds data on the end of the colorbar. -discrete : bool, default: :rc:`cmap.discrete` - If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the +discrete : bool, default: [cmap.discrete](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.discrete) + If ``False``, then [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) is not applied to the colormap. Instead, for non-contour plots, the number of levels will be - roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + roughly controlled by [cmap.lut](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.lut). This has a similar effect to using `levels=large_number` but it may improve rendering speed. Default is - ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` - and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. + ``True`` only for contouring commands like [contourf](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.contourf) + and pseudocolor commands like [pcolor](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.pcolor). sequential, diverging, cyclic, qualitative : bool, default: None Boolean arguments used if `cmap` is not passed. Set these to ``True`` - to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, - :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. - The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + to use the default [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential), [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging), + [cmap.cyclic](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.cyclic), and [cmap.qualitative](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.qualitative) colormaps. + The `diverging` option also applies [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) as the default continuous normalizer. vmin, vmax : float, optional The minimum and maximum color scale values used with the `norm` normalizer. @@ -3489,13 +3477,13 @@ vmin, vmax : float, optional the minimum and maximum of the lists. If `robust` was passed, the default `vmin` and `vmax` are some percentile range of the data values. Otherwise, the default `vmin` and `vmax` are the minimum and maximum of the data values. -inbounds : bool, default: :rc:`axes.inbounds` +inbounds : bool, default: [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) Whether to restrict the default `y` (`x`) axis limits to account for only in-bounds data when the `x` (`y`) axis limits have been locked. - See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. + See also [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) and [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds). scalex, scaley : bool, optional Whether the view limits are adapted to the data limits. The values are - passed on to `~matplotlib.axes.Axes.autoscale_view`. + passed on to [autoscale_view](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.autoscale_view.html). label, value : float or str, optional The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally @@ -3503,27 +3491,27 @@ label, value : float or str, optional colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Valid :class:`~matplotlib.collections.LineCollection` properties. + Valid [LineCollection](https://matplotlib.org/stable/api/_as_gen/matplotlib.collections.LineCollection.html) properties. Returns ------- -:class:`~matplotlib.collections.LineCollection` - The parametric line. See `this matplotlib example `__. +[LineCollection](https://matplotlib.org/stable/api/_as_gen/matplotlib.collections.LineCollection.html) + The parametric line. See [this matplotlib example](https://matplotlib.org/stable/gallery/lines_bars_and_markers/multicolored_line). See also -------- @@ -3545,27 +3533,26 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `y` coordinates are passed, try to infer the `x` coordinates from - the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the :class:`~xarray.DataArray` + the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `x` coordinates are ``np.arange(0, y2.shape[0])``. * If only `x` and `y2` coordinates are passed, set the `y1` coordinates to zero. This draws elements originating from the zero line. * If both `y1` and `y2` are provided, draw elements between these points. If either are 2D, draw elements by iterating over each column. - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- @@ -3573,18 +3560,18 @@ stack, stacked : bool, default: False Whether to "stack" lines from successive columns of y data or plot lines on top of each other. cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. -linewidth : unit-spec, default: :rc:`lines.linewidth` + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). +linewidth : unit-spec, default: [lines.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.linewidth) The width of the line(s). Aliases: ``lw``, ``linewidths``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -linestyle : str, default: :rc:`lines.linestyle` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +linestyle : str, default: [lines.linestyle](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.linestyle) The style of the line(s). Aliases: ``ls``, ``linestyles``. color : color-spec, optional The color of the line(s). The property `cycle` is used by default. Aliases: ``c``, ``colors``. @@ -3594,13 +3581,13 @@ negpos : bool, default: False Whether to shade lines where ``ymax >= ymin`` with `poscolor` and where ``ymax < ymin`` with `negcolor`. If ``True`` this function will return a length-2 silent list of handles. -negcolor, poscolor : color-spec, default: :rc:`negcolor`, :rc:`poscolor` +negcolor, poscolor : color-spec, default: [negcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=negcolor), [poscolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=poscolor) Colors to use for the negative and positive lines. Ignored if `negpos` is ``False``. -inbounds : bool, default: :rc:`axes.inbounds` +inbounds : bool, default: [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) Whether to restrict the default `y` (`x`) axis limits to account for only in-bounds data when the `x` (`y`) axis limits have been locked. - See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. + See also [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) and [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds). label, value : float or str, optional The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally @@ -3612,22 +3599,22 @@ labels, values : sequence of float or sequence of str, optional colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `~matplotlib.axes.Axes.vlines`. + Passed to [vlines](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.vlines.html). See also -------- @@ -3646,27 +3633,26 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `x` coordinates are passed, try to infer the `y` coordinates from - the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the :class:`~xarray.DataArray` + the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, x2.shape[0])``. * If only `y` and `x2` coordinates are passed, set the `x1` coordinates to zero. This draws elements originating from the zero line. * If both `x1` and `x2` are provided, draw elements between these points. If either are 2D, draw elements by iterating over each column. - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- @@ -3674,18 +3660,18 @@ stack, stacked : bool, default: False Whether to "stack" lines from successive columns of x data or plot lines on top of each other. cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. -linewidth : unit-spec, default: :rc:`lines.linewidth` + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). +linewidth : unit-spec, default: [lines.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.linewidth) The width of the line(s). Aliases: ``lw``, ``linewidths``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -linestyle : str, default: :rc:`lines.linestyle` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +linestyle : str, default: [lines.linestyle](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.linestyle) The style of the line(s). Aliases: ``ls``, ``linestyles``. color : color-spec, optional The color of the line(s). The property `cycle` is used by default. Aliases: ``c``, ``colors``. @@ -3695,13 +3681,13 @@ negpos : bool, default: False Whether to shade lines where ``ymax >= ymin`` with `poscolor` and where ``ymax < ymin`` with `negcolor`. If ``True`` this function will return a length-2 silent list of handles. -negcolor, poscolor : color-spec, default: :rc:`negcolor`, :rc:`poscolor` +negcolor, poscolor : color-spec, default: [negcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=negcolor), [poscolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=poscolor) Colors to use for the negative and positive lines. Ignored if `negpos` is ``False``. -inbounds : bool, default: :rc:`axes.inbounds` +inbounds : bool, default: [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) Whether to restrict the default `y` (`x`) axis limits to account for only in-bounds data when the `x` (`y`) axis limits have been locked. - See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. + See also [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) and [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds). label, value : float or str, optional The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally @@ -3713,22 +3699,22 @@ labels, values : sequence of float or sequence of str, optional colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `~matplotlib.axes.Axes.hlines`. + Passed to [hlines](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.hlines.html). See also -------- @@ -3755,19 +3741,19 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `y` coordinates are passed, try to infer the `x` coordinates - from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the - :class:`~xarray.DataArray` coordinates. Otherwise, the `x` coordinates + from the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the + [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `x` coordinates are ``np.arange(0, y.shape[0])``. * If the `y` coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. s, size, ms, markersize : float or array-like or unit-spec, optional The marker size area(s). If this is an array matching the shape of `x` and `y`, the units are scaled by `smin` and `smax`. If this contains unit string(s), it - is processed by `~ultraplot.utils.units` and represents the width rather than area. + is processed by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html) and represents the width rather than area. c, color, colors, mc, markercolor, markercolors, fc, facecolor, facecolors : array-like or color-spec, optional The marker color(s). If this is an array matching the shape of `x` and `y`, the colors are generated using `cmap`, `norm`, `vmin`, and `vmax`. Otherwise, @@ -3778,7 +3764,7 @@ c, color, colors, mc, markercolor, markercolors, fc, facecolor, facecolors : arr smin, smax : float, optional The minimum and maximum marker size area in units ``points ** 2``. Ignored if `absolute_size` is ``True``. Default value for `smin` is ``1`` and for - `smax` is the square of :rc:`lines.markersize`. + `smax` is the square of [lines.markersize](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.markersize). area_size : bool, default: True Whether the marker sizes `s` are scaled by area or by radius. The default ``True`` is consistent with matplotlib. When `absolute_size` is ``True``, @@ -3799,60 +3785,59 @@ vmin, vmax : float, optional and `vmax` are some percentile range of the data values. Otherwise, the default `vmin` and `vmax` are the minimum and maximum of the data values. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- -cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` - The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor - function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization - range contains negative and positive values then :rcraw:`cmap.diverging` is used. - Otherwise :rcraw:`cmap.sequential` is used. +cmap : colormap-spec, default: [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) or [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) + The colormap specifer, passed to the [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html) constructor + function. If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization + range contains negative and positive values then [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) is used. + Otherwise [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) is used. cmap_kw : dict-like, optional - Passed to :class:`~ultraplot.constructor.Colormap`. + Passed to [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html). c, color, colors : color-spec or sequence of color-spec, optional - The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + The color(s) used to create a [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html). If not passed, `cmap` is used. -norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` - The data value normalizer, passed to the `~ultraplot.constructor.Norm` +norm : norm-spec, default: [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) or [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) + The data value normalizer, passed to the [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html) constructor function. If `discrete` is ``True`` then 1) this affects the default level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and - 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they - are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). - If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains - negative and positive values then `~ultraplot.colors.DivergingNorm` is used. - Otherwise `~matplotlib.colors.Normalize` is used. + 2) this is passed to [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) to scale the colors before they + are discretized (if `norm` is not already a [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html)). + If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization range contains + negative and positive values then [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) is used. + Otherwise [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) is used. norm_kw : dict-like, optional - Passed to `~ultraplot.constructor.Norm`. + Passed to [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html). extend : {'neither', 'both', 'min', 'max'}, default: 'neither' Direction for drawing colorbar "extensions" indicating out-of-bounds data on the end of the colorbar. -discrete : bool, default: :rc:`cmap.discrete` - If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the +discrete : bool, default: [cmap.discrete](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.discrete) + If ``False``, then [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) is not applied to the colormap. Instead, for non-contour plots, the number of levels will be - roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + roughly controlled by [cmap.lut](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.lut). This has a similar effect to using `levels=large_number` but it may improve rendering speed. Default is - ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` - and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. + ``True`` only for contouring commands like [contourf](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.contourf) + and pseudocolor commands like [pcolor](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.pcolor). sequential, diverging, cyclic, qualitative : bool, default: None Boolean arguments used if `cmap` is not passed. Set these to ``True`` - to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, - :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. - The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + to use the default [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential), [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging), + [cmap.cyclic](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.cyclic), and [cmap.qualitative](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.qualitative) colormaps. + The `diverging` option also applies [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) as the default continuous normalizer. N Shorthand for `levels`. -levels : int or sequence of float, default: :rc:`cmap.levels` +levels : int or sequence of float, default: [cmap.levels](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.levels) The number of level edges or a sequence of level edges. If the former, `locator` is used to generate this many level edges at "nice" intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing @@ -3860,31 +3845,31 @@ levels : int or sequence of float, default: :rc:`cmap.levels` values : int or sequence of float, default: None The number of level centers or a sequence of level centers. If the former, `locator` is used to generate this many level centers at "nice" intervals. - If the latter, levels are inferred using `~ultraplot.utils.edges`. + If the latter, levels are inferred using [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html). This will override any `levels` input. center_levels : bool, default False If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented. -robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` +robust : bool, float, or 2-tuple, default: [cmap.robust](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.robust) If ``True`` and `vmin` or `vmax` were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers. -inbounds : bool, default: :rc:`cmap.inbounds` +inbounds : bool, default: [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) If ``True`` and `vmin` or `vmax` were not provided, when axis limits - have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` - or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. - See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. -locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + have been explicitly restricted with [set_xlim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlim.html) + or [set_ylim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylim.html), out-of-bounds data is ignored. + See also [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) and [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds). +locator : locator-spec, default: [matplotlib.ticker.MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) The locator used to determine level locations if `levels` or `values` were not - already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. - Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. + already passed as lists. Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. + Default is [MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) with `levels` integer levels. locator_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Locator` class. + Keyword arguments passed to [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. symmetric : bool, default: False If ``True``, the normalization range or discrete colormap levels are symmetric about zero. @@ -3896,27 +3881,27 @@ negative : bool, default: False negative with a minimum at zero. nozero : bool, default: False If ``True``, ``0`` is removed from the level list. This is mainly useful for - single-color `~matplotlib.axes.Axes.contour` plots. + single-color [contour](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.contour.html) plots. cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). lw, linewidth, linewidths, mew, markeredgewidth, markeredgewidths : float or sequence, optional The marker edge width(s). edgecolors, markeredgecolor, markeredgecolors : color-spec or sequence, optional The marker edge color(s). mean, means : bool, default: False Whether to plot the means of each column for 2D `y` coordinates. Means - are calculated with `numpy.nanmean`. If no other arguments are specified, + are calculated with [numpy.nanmean](https://numpy.org/doc/stable/reference/generated/numpy.nanmean.html). If no other arguments are specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). median, medians : bool, default: False Whether to plot the medians of each column for 2D `y` coordinates. Medians - are calculated with `numpy.nanmedian`. If no other arguments arguments are + are calculated with [numpy.nanmedian](https://numpy.org/doc/stable/reference/generated/numpy.nanmedian.html). If no other arguments arguments are specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). bars : bool, default: None Shorthand for `barstd`, `barstds`. @@ -3942,15 +3927,15 @@ boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional is ``True``, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When "boxes" and "bars" are combined, this has the effect of drawing miniature box-and-whisker plots. -capsize : float, default: :rc:`errorbar.capsize` +capsize : float, default: [errorbar.capsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=errorbar.capsize) The cap size for thin error bars in points. barz, barzorder, boxz, boxzorder : float, default: 2.5 The "zorder" for the thin and thick error bars. -barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` +barc, barcolor, boxc, boxcolor : color-spec, default: [boxplot.whiskerprops.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.color) Colors for the thin and thick error bars. -barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` +barlw, barlinewidth, boxlw, boxlinewidth : float, default: [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth) Line widths for the thin and thick error bars, in points. The default for boxes - is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. + is 4 times [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth). boxm, boxmarker : bool or marker-spec, default: 'o' Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if `boxes` is ``False``. @@ -3978,7 +3963,7 @@ shadez, shadezorder, fadez, fadezorder : float, default: 1.5 The "zorder" for the different shaded regions. shadea, shadealpha, fadea, fadealpha : float, default: 0.4, 0.2 The opacity for the different shaded regions. -shadelw, shadelinewidth, fadelw, fadelinewidth : float, default: :rc:`patch.linewidth`. +shadelw, shadelinewidth, fadelw, fadelinewidth : float, default: [patch.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.linewidth). The edge line width for the shading patches. shdeec, shadeedgecolor, fadeec, fadeedgecolor : float, default: 'none' The edge color for the shading patches. @@ -3987,10 +3972,10 @@ shadelabel, fadelabel : bool or str, optional labels "on" and apply a *default* label, use e.g. ``shadelabel=True``. To apply a *custom* label, use e.g. ``shadelabel='label'``. Otherwise, the shading is drawn underneath the line and/or marker in the legend entry. -inbounds : bool, default: :rc:`axes.inbounds` +inbounds : bool, default: [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) Whether to restrict the default `y` (`x`) axis limits to account for only in-bounds data when the `x` (`y`) axis limits have been locked. - See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. + See also [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) and [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds). label, value : float or str, optional The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally @@ -4002,22 +3987,22 @@ labels, values : sequence of float or sequence of str, optional colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `~matplotlib.axes.Axes.scatter`. + Passed to [scatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.scatter.html). See also -------- @@ -4051,7 +4036,7 @@ s : float or array-like, shape (n, ), optional To eliminate the marker edge either set *linewidth=0* or *edgecolor='none'*. -c : array-like or list of :mpltype:`color` or :mpltype:`color`, optional +c : array-like or list of [color](https://matplotlib.org/stable/search.html?q=color) or [color](https://matplotlib.org/stable/search.html?q=color), optional The marker colors. Possible values: - A scalar or sequence of n numbers to be mapped to colors using @@ -4074,21 +4059,21 @@ c : array-like or list of :mpltype:`color` or :mpltype:`color`, optional by the value of *color*, *facecolor* or *facecolors*. In case those are not specified or `None`, the marker color is determined by the next color of the ``Axes``' current "shape and fill" color - cycle. This cycle defaults to :rc:`axes.prop_cycle`. + cycle. This cycle defaults to [axes.prop_cycle](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.prop_cycle). -marker : `~.markers.MarkerStyle`, default: :rc:`scatter.marker` +marker : `~.markers.MarkerStyle`, default: [scatter.marker](https://ultraplot.readthedocs.io/en/stable/search.html?q=scatter.marker) The marker style. *marker* can be either an instance of the class or the text shorthand for a particular marker. - See :mod:`matplotlib.markers` for more information about marker + See [matplotlib.markers](https://matplotlib.org/stable/api/_as_gen/matplotlib.markers.html) for more information about marker styles. -cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap` +cmap : str or [Colormap](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Colormap.html), default: [image.cmap](https://ultraplot.readthedocs.io/en/stable/search.html?q=image.cmap) The Colormap instance or registered colormap name used to map scalar data to colors. This parameter is ignored if *c* is RGB(A). -norm : str or `~matplotlib.colors.Normalize`, optional +norm : str or [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html), optional The normalization method used to scale scalar data to the [0, 1] range before mapping to colors using *cmap*. By default, a linear scaling is used, mapping the lowest value to 0 and the highest to 1. @@ -4096,9 +4081,9 @@ norm : str or `~matplotlib.colors.Normalize`, optional If given, this can be one of the following: - An instance of `.Normalize` or one of its subclasses - (see :ref:`colormapnorms`). + (see [colormapnorms](https://ultraplot.readthedocs.io/en/stable/search.html?q=colormapnorms)). - A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For a - list of available scales, call `matplotlib.scale.get_scale_names()`. + list of available scales, call [matplotlib.scale.get_scale_names()](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.get_scale_names().html). In that case, a suitable `.Normalize` subclass is dynamically generated and instantiated. @@ -4116,11 +4101,11 @@ vmin, vmax : float, optional alpha : float, default: None The alpha blending value, between 0 (transparent) and 1 (opaque). -linewidths : float or array-like, default: :rc:`lines.linewidth` +linewidths : float or array-like, default: [lines.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.linewidth) The linewidth of the marker edges. Note: The default *edgecolors* is 'face'. You may want to change this as well. -edgecolors : {'face', 'none', *None*} or :mpltype:`color` or list of :mpltype:`color`, default: :rc:`scatter.edgecolors` +edgecolors : {'face', 'none', *None*} or [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color), default: [scatter.edgecolors](https://ultraplot.readthedocs.io/en/stable/search.html?q=scatter.edgecolors) The edge color of the marker. Possible values: - 'face': The edge color will always be the same as the face color. @@ -4131,7 +4116,7 @@ edgecolors : {'face', 'none', *None*} or :mpltype:`color` or list of :mpltype:`c is determined like with 'face', i.e. from *c*, *colors*, or *facecolors*. -colorizer : `~matplotlib.colorizer.Colorizer` or None, default: None +colorizer : [Colorizer](https://matplotlib.org/stable/api/_as_gen/matplotlib.colorizer.Colorizer.html) or None, default: None The Colorizer object used to map color to data. If None, a Colorizer object is created from a *norm* and *cmap*. @@ -4144,7 +4129,7 @@ plotnonfinite : bool, default: False Returns ------- -`~matplotlib.collections.PathCollection` +[PathCollection](https://matplotlib.org/stable/api/_as_gen/matplotlib.collections.PathCollection.html) Other Parameters ---------------- @@ -4153,7 +4138,7 @@ data : indexable object, optional interpreted as ``data[s]`` if ``s`` is a key in ``data``: *x*, *y*, *s*, *linewidths*, *edgecolors*, *c*, *facecolor*, *facecolors*, *color* -**kwargs : `~matplotlib.collections.PathCollection` properties +**kwargs : [PathCollection](https://matplotlib.org/stable/api/_as_gen/matplotlib.collections.PathCollection.html) properties Properties: agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image alpha: array-like or float or None @@ -4162,14 +4147,14 @@ data : indexable object, optional array: array-like or None capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} clim: (vmin: float, vmax: float) - clip_box: `~matplotlib.transforms.BboxBase` or None + clip_box: [BboxBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.BboxBase.html) or None clip_on: bool clip_path: Patch or (Path, Transform) or None cmap: `.Colormap` or str or None - color: :mpltype:`color` or list of RGBA tuples - edgecolor or ec or edgecolors: :mpltype:`color` or list of :mpltype:`color` or 'face' - facecolor or facecolors or fc: :mpltype:`color` or list of :mpltype:`color` - figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + color: [color](https://matplotlib.org/stable/search.html?q=color) or list of RGBA tuples + edgecolor or ec or edgecolors: [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color) or 'face' + facecolor or facecolors or fc: [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color) + figure: [Figure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html) or [SubFigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.SubFigure.html) gid: str hatch: {'/', '\\\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'} hatch_linewidth: unknown @@ -4187,10 +4172,10 @@ data : indexable object, optional picker: None or bool or float or callable pickradius: float rasterized: bool - sizes: `numpy.ndarray` or None + sizes: [numpy.ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html) or None sketch_params: (scale: float, length: float, randomness: float) snap: bool or None - transform: `~matplotlib.transforms.Transform` + transform: [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html) url: str urls: list of str or None visible: bool @@ -4225,19 +4210,19 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `x` coordinates are passed, try to infer the `y` coordinates - from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the - :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + from the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the + [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, x.shape[0])``. * If the `x` coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. s, size, ms, markersize : float or array-like or unit-spec, optional The marker size area(s). If this is an array matching the shape of `x` and `y`, the units are scaled by `smin` and `smax`. If this contains unit string(s), it - is processed by `~ultraplot.utils.units` and represents the width rather than area. + is processed by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html) and represents the width rather than area. c, color, colors, mc, markercolor, markercolors, fc, facecolor, facecolors : array-like or color-spec, optional The marker color(s). If this is an array matching the shape of `x` and `y`, the colors are generated using `cmap`, `norm`, `vmin`, and `vmax`. Otherwise, @@ -4248,7 +4233,7 @@ c, color, colors, mc, markercolor, markercolors, fc, facecolor, facecolors : arr smin, smax : float, optional The minimum and maximum marker size area in units ``points ** 2``. Ignored if `absolute_size` is ``True``. Default value for `smin` is ``1`` and for - `smax` is the square of :rc:`lines.markersize`. + `smax` is the square of [lines.markersize](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.markersize). area_size : bool, default: True Whether the marker sizes `s` are scaled by area or by radius. The default ``True`` is consistent with matplotlib. When `absolute_size` is ``True``, @@ -4269,60 +4254,59 @@ vmin, vmax : float, optional and `vmax` are some percentile range of the data values. Otherwise, the default `vmin` and `vmax` are the minimum and maximum of the data values. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- -cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` - The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor - function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization - range contains negative and positive values then :rcraw:`cmap.diverging` is used. - Otherwise :rcraw:`cmap.sequential` is used. +cmap : colormap-spec, default: [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) or [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) + The colormap specifer, passed to the [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html) constructor + function. If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization + range contains negative and positive values then [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) is used. + Otherwise [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) is used. cmap_kw : dict-like, optional - Passed to :class:`~ultraplot.constructor.Colormap`. + Passed to [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html). c, color, colors : color-spec or sequence of color-spec, optional - The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + The color(s) used to create a [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html). If not passed, `cmap` is used. -norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` - The data value normalizer, passed to the `~ultraplot.constructor.Norm` +norm : norm-spec, default: [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) or [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) + The data value normalizer, passed to the [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html) constructor function. If `discrete` is ``True`` then 1) this affects the default level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and - 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they - are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). - If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains - negative and positive values then `~ultraplot.colors.DivergingNorm` is used. - Otherwise `~matplotlib.colors.Normalize` is used. + 2) this is passed to [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) to scale the colors before they + are discretized (if `norm` is not already a [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html)). + If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization range contains + negative and positive values then [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) is used. + Otherwise [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) is used. norm_kw : dict-like, optional - Passed to `~ultraplot.constructor.Norm`. + Passed to [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html). extend : {'neither', 'both', 'min', 'max'}, default: 'neither' Direction for drawing colorbar "extensions" indicating out-of-bounds data on the end of the colorbar. -discrete : bool, default: :rc:`cmap.discrete` - If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the +discrete : bool, default: [cmap.discrete](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.discrete) + If ``False``, then [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) is not applied to the colormap. Instead, for non-contour plots, the number of levels will be - roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + roughly controlled by [cmap.lut](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.lut). This has a similar effect to using `levels=large_number` but it may improve rendering speed. Default is - ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` - and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. + ``True`` only for contouring commands like [contourf](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.contourf) + and pseudocolor commands like [pcolor](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.pcolor). sequential, diverging, cyclic, qualitative : bool, default: None Boolean arguments used if `cmap` is not passed. Set these to ``True`` - to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, - :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. - The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + to use the default [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential), [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging), + [cmap.cyclic](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.cyclic), and [cmap.qualitative](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.qualitative) colormaps. + The `diverging` option also applies [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) as the default continuous normalizer. N Shorthand for `levels`. -levels : int or sequence of float, default: :rc:`cmap.levels` +levels : int or sequence of float, default: [cmap.levels](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.levels) The number of level edges or a sequence of level edges. If the former, `locator` is used to generate this many level edges at "nice" intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing @@ -4330,31 +4314,31 @@ levels : int or sequence of float, default: :rc:`cmap.levels` values : int or sequence of float, default: None The number of level centers or a sequence of level centers. If the former, `locator` is used to generate this many level centers at "nice" intervals. - If the latter, levels are inferred using `~ultraplot.utils.edges`. + If the latter, levels are inferred using [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html). This will override any `levels` input. center_levels : bool, default False If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented. -robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` +robust : bool, float, or 2-tuple, default: [cmap.robust](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.robust) If ``True`` and `vmin` or `vmax` were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers. -inbounds : bool, default: :rc:`cmap.inbounds` +inbounds : bool, default: [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) If ``True`` and `vmin` or `vmax` were not provided, when axis limits - have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` - or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. - See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. -locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + have been explicitly restricted with [set_xlim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlim.html) + or [set_ylim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylim.html), out-of-bounds data is ignored. + See also [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) and [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds). +locator : locator-spec, default: [matplotlib.ticker.MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) The locator used to determine level locations if `levels` or `values` were not - already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. - Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. + already passed as lists. Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. + Default is [MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) with `levels` integer levels. locator_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Locator` class. + Keyword arguments passed to [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. symmetric : bool, default: False If ``True``, the normalization range or discrete colormap levels are symmetric about zero. @@ -4366,27 +4350,27 @@ negative : bool, default: False negative with a minimum at zero. nozero : bool, default: False If ``True``, ``0`` is removed from the level list. This is mainly useful for - single-color `~matplotlib.axes.Axes.contour` plots. + single-color [contour](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.contour.html) plots. cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). lw, linewidth, linewidths, mew, markeredgewidth, markeredgewidths : float or sequence, optional The marker edge width(s). edgecolors, markeredgecolor, markeredgecolors : color-spec or sequence, optional The marker edge color(s). mean, means : bool, default: False Whether to plot the means of each column for 2D `x` coordinates. Means - are calculated with `numpy.nanmean`. If no other arguments are specified, + are calculated with [numpy.nanmean](https://numpy.org/doc/stable/reference/generated/numpy.nanmean.html). If no other arguments are specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). median, medians : bool, default: False Whether to plot the medians of each column for 2D `x` coordinates. Medians - are calculated with `numpy.nanmedian`. If no other arguments arguments are + are calculated with [numpy.nanmedian](https://numpy.org/doc/stable/reference/generated/numpy.nanmedian.html). If no other arguments arguments are specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). bars : bool, default: None Shorthand for `barstd`, `barstds`. @@ -4412,15 +4396,15 @@ boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional is ``True``, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When "boxes" and "bars" are combined, this has the effect of drawing miniature box-and-whisker plots. -capsize : float, default: :rc:`errorbar.capsize` +capsize : float, default: [errorbar.capsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=errorbar.capsize) The cap size for thin error bars in points. barz, barzorder, boxz, boxzorder : float, default: 2.5 The "zorder" for the thin and thick error bars. -barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` +barc, barcolor, boxc, boxcolor : color-spec, default: [boxplot.whiskerprops.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.color) Colors for the thin and thick error bars. -barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` +barlw, barlinewidth, boxlw, boxlinewidth : float, default: [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth) Line widths for the thin and thick error bars, in points. The default for boxes - is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. + is 4 times [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth). boxm, boxmarker : bool or marker-spec, default: 'o' Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if `boxes` is ``False``. @@ -4448,7 +4432,7 @@ shadez, shadezorder, fadez, fadezorder : float, default: 1.5 The "zorder" for the different shaded regions. shadea, shadealpha, fadea, fadealpha : float, default: 0.4, 0.2 The opacity for the different shaded regions. -shadelw, shadelinewidth, fadelw, fadelinewidth : float, default: :rc:`patch.linewidth`. +shadelw, shadelinewidth, fadelw, fadelinewidth : float, default: [patch.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.linewidth). The edge line width for the shading patches. shdeec, shadeedgecolor, fadeec, fadeedgecolor : float, default: 'none' The edge color for the shading patches. @@ -4457,10 +4441,10 @@ shadelabel, fadelabel : bool or str, optional labels "on" and apply a *default* label, use e.g. ``shadelabel=True``. To apply a *custom* label, use e.g. ``shadelabel='label'``. Otherwise, the shading is drawn underneath the line and/or marker in the legend entry. -inbounds : bool, default: :rc:`axes.inbounds` +inbounds : bool, default: [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) Whether to restrict the default `y` (`x`) axis limits to account for only in-bounds data when the `x` (`y`) axis limits have been locked. - See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. + See also [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) and [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds). label, value : float or str, optional The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally @@ -4472,22 +4456,22 @@ labels, values : sequence of float or sequence of str, optional colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `~matplotlib.axes.Axes.scatter`. + Passed to [scatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.scatter.html). See also -------- @@ -4547,48 +4531,47 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `y` coordinates are passed, try to infer the `x` coordinates from - the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the :class:`~xarray.DataArray` + the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `x` coordinates are ``np.arange(0, y2.shape[0])``. * If only `x` and `y2` coordinates are passed, set the `y1` coordinates to zero. This draws elements originating from the zero line. * If both `y1` and `y2` are provided, draw elements between these points. If either are 2D, draw elements by iterating over each column. - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. stack, stacked : bool, default: False Whether to "stack" area patches from successive columns of y data or plot area patches on top of each other. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- where : ndarray, optional A boolean mask for the points that should be shaded. - See `this matplotlib example `__. + See [this matplotlib example](https://matplotlib.org/stable/gallery/pyplots/whats_new_98_4_fill_between.html). cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. -linewidth : unit-spec, default: :rc:`patch.linewidth` + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). +linewidth : unit-spec, default: [patch.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.linewidth) The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). linestyle : str, default: '-' The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. edgecolor : color-spec, default: 'none' @@ -4601,21 +4584,21 @@ negpos : bool, default: False Whether to shade patches where ``y2 >= y1`` with `poscolor` and where ``y2 < y1`` with `negcolor`. If ``True`` this function will return a length-2 silent list of handles. -negcolor, poscolor : color-spec, default: :rc:`negcolor`, :rc:`poscolor` +negcolor, poscolor : color-spec, default: [negcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=negcolor), [poscolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=poscolor) Colors to use for the negative and positive patches. Ignored if `negpos` is ``False``. -edgefix : bool or float, default: :rc:`edgefix` +edgefix : bool or float, default: [edgefix](https://ultraplot.readthedocs.io/en/stable/search.html?q=edgefix) Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). - See this `github repo `__ for a + See this [github repo](https://github.com/jklymak/contourfIssues) for a demonstration of the problem. If ``True``, a small default linewidth of ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), this specific linewidth is used to cover up the white lines. This feature is automatically disabled when the patches have transparency. -inbounds : bool, default: :rc:`axes.inbounds` +inbounds : bool, default: [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) Whether to restrict the default `y` (`x`) axis limits to account for only in-bounds data when the `x` (`y`) axis limits have been locked. - See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. + See also [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) and [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds). label, value : float or str, optional The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally @@ -4627,22 +4610,22 @@ labels, values : sequence of float or sequence of str, optional colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `~matplotlib.axes.Axes.fill_between`. + Passed to [fill_between](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.fill_between.html). See also -------- @@ -4663,48 +4646,47 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `x` coordinates are passed, try to infer the `y` coordinates from - the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the :class:`~xarray.DataArray` + the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, x2.shape[0])``. * If only `y` and `x2` coordinates are passed, set the `x1` coordinates to zero. This draws elements originating from the zero line. * If both `x1` and `x2` are provided, draw elements between these points. If either are 2D, draw elements by iterating over each column. - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. stack, stacked : bool, default: False Whether to "stack" area patches from successive columns of x data or plot area patches on top of each other. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- where : ndarray, optional A boolean mask for the points that should be shaded. - See `this matplotlib example `__. + See [this matplotlib example](https://matplotlib.org/stable/gallery/pyplots/whats_new_98_4_fill_between.html). cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. -linewidth : unit-spec, default: :rc:`patch.linewidth` + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). +linewidth : unit-spec, default: [patch.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.linewidth) The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). linestyle : str, default: '-' The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. edgecolor : color-spec, default: 'none' @@ -4717,21 +4699,21 @@ negpos : bool, default: False Whether to shade patches where ``y2 >= y1`` with `poscolor` and where ``y2 < y1`` with `negcolor`. If ``True`` this function will return a length-2 silent list of handles. -negcolor, poscolor : color-spec, default: :rc:`negcolor`, :rc:`poscolor` +negcolor, poscolor : color-spec, default: [negcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=negcolor), [poscolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=poscolor) Colors to use for the negative and positive patches. Ignored if `negpos` is ``False``. -edgefix : bool or float, default: :rc:`edgefix` +edgefix : bool or float, default: [edgefix](https://ultraplot.readthedocs.io/en/stable/search.html?q=edgefix) Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). - See this `github repo `__ for a + See this [github repo](https://github.com/jklymak/contourfIssues) for a demonstration of the problem. If ``True``, a small default linewidth of ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), this specific linewidth is used to cover up the white lines. This feature is automatically disabled when the patches have transparency. -inbounds : bool, default: :rc:`axes.inbounds` +inbounds : bool, default: [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) Whether to restrict the default `y` (`x`) axis limits to account for only in-bounds data when the `x` (`y`) axis limits have been locked. - See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. + See also [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) and [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds). label, value : float or str, optional The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally @@ -4743,22 +4725,22 @@ labels, values : sequence of float or sequence of str, optional colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `~matplotlib.axes.Axes.fill_betweenx`. + Passed to [fill_betweenx](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.fill_betweenx.html). See also -------- @@ -4779,48 +4761,47 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `y` coordinates are passed, try to infer the `x` coordinates from - the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the :class:`~xarray.DataArray` + the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `x` coordinates are ``np.arange(0, y2.shape[0])``. * If only `x` and `y2` coordinates are passed, set the `y1` coordinates to zero. This draws elements originating from the zero line. * If both `y1` and `y2` are provided, draw elements between these points. If either are 2D, draw elements by iterating over each column. - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. stack, stacked : bool, default: False Whether to "stack" area patches from successive columns of y data or plot area patches on top of each other. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- where : ndarray, optional A boolean mask for the points that should be shaded. - See `this matplotlib example `__. + See [this matplotlib example](https://matplotlib.org/stable/gallery/pyplots/whats_new_98_4_fill_between.html). cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. -linewidth : unit-spec, default: :rc:`patch.linewidth` + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). +linewidth : unit-spec, default: [patch.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.linewidth) The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). linestyle : str, default: '-' The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. edgecolor : color-spec, default: 'none' @@ -4833,21 +4814,21 @@ negpos : bool, default: False Whether to shade patches where ``y2 >= y1`` with `poscolor` and where ``y2 < y1`` with `negcolor`. If ``True`` this function will return a length-2 silent list of handles. -negcolor, poscolor : color-spec, default: :rc:`negcolor`, :rc:`poscolor` +negcolor, poscolor : color-spec, default: [negcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=negcolor), [poscolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=poscolor) Colors to use for the negative and positive patches. Ignored if `negpos` is ``False``. -edgefix : bool or float, default: :rc:`edgefix` +edgefix : bool or float, default: [edgefix](https://ultraplot.readthedocs.io/en/stable/search.html?q=edgefix) Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). - See this `github repo `__ for a + See this [github repo](https://github.com/jklymak/contourfIssues) for a demonstration of the problem. If ``True``, a small default linewidth of ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), this specific linewidth is used to cover up the white lines. This feature is automatically disabled when the patches have transparency. -inbounds : bool, default: :rc:`axes.inbounds` +inbounds : bool, default: [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) Whether to restrict the default `y` (`x`) axis limits to account for only in-bounds data when the `x` (`y`) axis limits have been locked. - See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. + See also [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) and [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds). label, value : float or str, optional The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally @@ -4859,22 +4840,22 @@ labels, values : sequence of float or sequence of str, optional colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `~matplotlib.axes.Axes.fill_between`. + Passed to [fill_between](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.fill_between.html). See also -------- @@ -4972,15 +4953,15 @@ data : indexable object, optional array: array-like or None capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} clim: (vmin: float, vmax: float) - clip_box: `~matplotlib.transforms.BboxBase` or None + clip_box: [BboxBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.BboxBase.html) or None clip_on: bool clip_path: Patch or (Path, Transform) or None cmap: `.Colormap` or str or None - color: :mpltype:`color` or list of RGBA tuples + color: [color](https://matplotlib.org/stable/search.html?q=color) or list of RGBA tuples data: array-like - edgecolor or ec or edgecolors: :mpltype:`color` or list of :mpltype:`color` or 'face' - facecolor or facecolors or fc: :mpltype:`color` or list of :mpltype:`color` - figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + edgecolor or ec or edgecolors: [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color) or 'face' + facecolor or facecolors or fc: [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color) + figure: [Figure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html) or [SubFigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.SubFigure.html) gid: str hatch: {'/', '\\\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'} hatch_linewidth: unknown @@ -4998,10 +4979,10 @@ data : indexable object, optional picker: None or bool or float or callable pickradius: float rasterized: bool - sizes: `numpy.ndarray` or None + sizes: [numpy.ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html) or None sketch_params: (scale: float, length: float, randomness: float) snap: bool or None - transform: `~matplotlib.transforms.Transform` + transform: [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html) url: str urls: list of str or None verts: list of array-like @@ -5024,48 +5005,47 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `x` coordinates are passed, try to infer the `y` coordinates from - the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the :class:`~xarray.DataArray` + the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, x2.shape[0])``. * If only `y` and `x2` coordinates are passed, set the `x1` coordinates to zero. This draws elements originating from the zero line. * If both `x1` and `x2` are provided, draw elements between these points. If either are 2D, draw elements by iterating over each column. - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. stack, stacked : bool, default: False Whether to "stack" area patches from successive columns of x data or plot area patches on top of each other. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- where : ndarray, optional A boolean mask for the points that should be shaded. - See `this matplotlib example `__. + See [this matplotlib example](https://matplotlib.org/stable/gallery/pyplots/whats_new_98_4_fill_between.html). cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. -linewidth : unit-spec, default: :rc:`patch.linewidth` + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). +linewidth : unit-spec, default: [patch.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.linewidth) The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). linestyle : str, default: '-' The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. edgecolor : color-spec, default: 'none' @@ -5078,21 +5058,21 @@ negpos : bool, default: False Whether to shade patches where ``y2 >= y1`` with `poscolor` and where ``y2 < y1`` with `negcolor`. If ``True`` this function will return a length-2 silent list of handles. -negcolor, poscolor : color-spec, default: :rc:`negcolor`, :rc:`poscolor` +negcolor, poscolor : color-spec, default: [negcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=negcolor), [poscolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=poscolor) Colors to use for the negative and positive patches. Ignored if `negpos` is ``False``. -edgefix : bool or float, default: :rc:`edgefix` +edgefix : bool or float, default: [edgefix](https://ultraplot.readthedocs.io/en/stable/search.html?q=edgefix) Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). - See this `github repo `__ for a + See this [github repo](https://github.com/jklymak/contourfIssues) for a demonstration of the problem. If ``True``, a small default linewidth of ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), this specific linewidth is used to cover up the white lines. This feature is automatically disabled when the patches have transparency. -inbounds : bool, default: :rc:`axes.inbounds` +inbounds : bool, default: [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) Whether to restrict the default `y` (`x`) axis limits to account for only in-bounds data when the `x` (`y`) axis limits have been locked. - See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. + See also [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) and [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds). label, value : float or str, optional The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally @@ -5104,22 +5084,22 @@ labels, values : sequence of float or sequence of str, optional colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `~matplotlib.axes.Axes.fill_betweenx`. + Passed to [fill_betweenx](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.fill_betweenx.html). See also -------- @@ -5217,15 +5197,15 @@ data : indexable object, optional array: array-like or None capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} clim: (vmin: float, vmax: float) - clip_box: `~matplotlib.transforms.BboxBase` or None + clip_box: [BboxBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.BboxBase.html) or None clip_on: bool clip_path: Patch or (Path, Transform) or None cmap: `.Colormap` or str or None - color: :mpltype:`color` or list of RGBA tuples + color: [color](https://matplotlib.org/stable/search.html?q=color) or list of RGBA tuples data: array-like - edgecolor or ec or edgecolors: :mpltype:`color` or list of :mpltype:`color` or 'face' - facecolor or facecolors or fc: :mpltype:`color` or list of :mpltype:`color` - figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + edgecolor or ec or edgecolors: [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color) or 'face' + facecolor or facecolors or fc: [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color) + figure: [Figure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html) or [SubFigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.SubFigure.html) gid: str hatch: {'/', '\\\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'} hatch_linewidth: unknown @@ -5243,10 +5223,10 @@ data : indexable object, optional picker: None or bool or float or callable pickradius: float rasterized: bool - sizes: `numpy.ndarray` or None + sizes: [numpy.ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html) or None sketch_params: (scale: float, length: float, randomness: float) snap: bool or None - transform: `~matplotlib.transforms.Transform` + transform: [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html) url: str urls: list of str or None verts: list of array-like @@ -5266,31 +5246,31 @@ fill_betweenx : Fill between two sets of x-values.""" Parameters ---------- g : networkx.Graph - The graph object to be plotted. Can be any subclass of :class:`~networkx.Graph`, such as - :class:`~networkx.DiGraph` or :class:`~networkx.MultiGraph`. + The graph object to be plotted. Can be any subclass of [Graph](https://networkx.org/documentation/stable/search.html?q=networkx.Graph), such as + [DiGraph](https://networkx.org/documentation/stable/search.html?q=networkx.DiGraph) or [MultiGraph](https://networkx.org/documentation/stable/search.html?q=networkx.MultiGraph). layout : callable or dict, optional A layout function or a precomputed dict mapping nodes to 2D positions. If a function - is given, it is called as ``layout(g, **layout_kw)`` to compute positions. See :func:`networkx.drawing.nx_pylab.draw` for more information. -nodes : bool or iterable, default: :rc:`graph.draw_nodes` + is given, it is called as ``layout(g, **layout_kw)`` to compute positions. See [networkx.drawing.nx_pylab.draw](https://networkx.org/documentation/stable/search.html?q=networkx.drawing.nx_pylab.draw) for more information. +nodes : bool or iterable, default: [graph.draw_nodes](https://ultraplot.readthedocs.io/en/stable/search.html?q=graph.draw_nodes) Which nodes to draw. If `True`, all nodes are drawn. If an iterable is provided, only - the specified nodes are included. This effectively acts as `nodelist` in :func:`networkx.drawing.nx_pylab.draw_networkx_nodes`. -edges : bool or iterable, default: :rc:`graph.draw_edges` + the specified nodes are included. This effectively acts as `nodelist` in [networkx.drawing.nx_pylab.draw_networkx_nodes](https://networkx.org/documentation/stable/search.html?q=networkx.drawing.nx_pylab.draw_networkx_nodes). +edges : bool or iterable, default: [graph.draw_edges](https://ultraplot.readthedocs.io/en/stable/search.html?q=graph.draw_edges) Which edges to draw. If `True`, all edges are drawn. If an iterable of edge tuples is - provided, only those edges are included. This effectively acts as `edgelist` in :func:`networkx.drawing.nx_pylab.draw_networkx_edges`. -labels : bool or iterable, default: :rc:`graph.draw_labels` + provided, only those edges are included. This effectively acts as `edgelist` in [networkx.drawing.nx_pylab.draw_networkx_edges](https://networkx.org/documentation/stable/search.html?q=networkx.drawing.nx_pylab.draw_networkx_edges). +labels : bool or iterable, default: [graph.draw_labels](https://ultraplot.readthedocs.io/en/stable/search.html?q=graph.draw_labels) Whether to show node labels. If `True`, labels are drawn using node names. If an iterable is given, only those nodes are labeled. layout_kw : dict, default: {} - Keyword arguments passed to the layout function, if `layout` is callable, see `networkx's drawing functions `_ for more information. + Keyword arguments passed to the layout function, if `layout` is callable, see [networkx's drawing functions](https://networkx.org/documentation/stable/reference/drawing.html) for more information. node_kw : dict, default: {} - Additional keyword arguments passed to the node drawing function (see :func:`networkx.drawing.nx_pylab.draw_networkx_nodes`). These can include - size, color, edgecolor, cmap, alpha, etc., depending on the backend used, see :func:`networkx.drawing.nx_pylab.draw_networkx_nodes`. + Additional keyword arguments passed to the node drawing function (see [networkx.drawing.nx_pylab.draw_networkx_nodes](https://networkx.org/documentation/stable/search.html?q=networkx.drawing.nx_pylab.draw_networkx_nodes)). These can include + size, color, edgecolor, cmap, alpha, etc., depending on the backend used, see [networkx.drawing.nx_pylab.draw_networkx_nodes](https://networkx.org/documentation/stable/search.html?q=networkx.drawing.nx_pylab.draw_networkx_nodes). edge_kw : dict, default: {} Additional keyword arguments passed to the edge drawing function. These can include - width, color, style, alpha, arrows, etc (see :func:`networkx.drawing.nx_pylab.draw_networkx_edges`). + width, color, style, alpha, arrows, etc (see [networkx.drawing.nx_pylab.draw_networkx_edges](https://networkx.org/documentation/stable/search.html?q=networkx.drawing.nx_pylab.draw_networkx_edges)). label_kw : dict, default: {} Additional keyword arguments passed to the label drawing function, such as font size, - font color, background color, alignment, etc (see :func:`networkx.drawing.nx_pylab.draw_networkx_labels`). + font color, background color, alignment, etc (see [networkx.drawing.nx_pylab.draw_networkx_labels](https://networkx.org/documentation/stable/search.html?q=networkx.drawing.nx_pylab.draw_networkx_labels)). rescale : bool, None, default: None. When set to none it checks for `rc["graph.rescale"]` which defaults to `True`. This performs a rescale such that the node position is within a [0, 1] x [0, 1] box. Returns @@ -5330,15 +5310,15 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `y` coordinates are passed, try to infer the `x` coordinates - from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the - :class:`~xarray.DataArray` coordinates. Otherwise, the `x` coordinates + from the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the + [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `x` coordinates are ``np.arange(0, y.shape[0])``. * If the `y` coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. width : float or array-like, default: 0.8 The width(s) of the bars. Can be passed as a third positional argument. If `absolute_width` is ``True`` (the default) these are in units relative to the @@ -5355,34 +5335,33 @@ stack, stacked : bool, default: False bar_labels : bool, default rc["bar.bar_labels"] Whether to show the height values for vertical bars or width values for horizontal bars. bar_labels_kw : dict, default None - Keywords to format the bar_labels, see :func:`~matplotlib.pyplot.bar_label`. + Keywords to format the bar_labels, see [bar_label](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.bar_label.html). data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. -linewidth : unit-spec, default: :rc:`patch.linewidth` + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). +linewidth : unit-spec, default: [patch.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.linewidth) The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). linestyle : str, default: '-' The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. edgecolor : color-spec, default: 'none' @@ -5395,24 +5374,24 @@ negpos : bool, default: False Whether to shade bars where ``height >= 0`` with `poscolor` and where ``height < 0`` with `negcolor`. If ``True`` this function will return a length-2 silent list of handles. -negcolor, poscolor : color-spec, default: :rc:`negcolor`, :rc:`poscolor` +negcolor, poscolor : color-spec, default: [negcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=negcolor), [poscolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=poscolor) Colors to use for the negative and positive bars. Ignored if `negpos` is ``False``. -edgefix : bool or float, default: :rc:`edgefix` +edgefix : bool or float, default: [edgefix](https://ultraplot.readthedocs.io/en/stable/search.html?q=edgefix) Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). - See this `github repo `__ for a + See this [github repo](https://github.com/jklymak/contourfIssues) for a demonstration of the problem. If ``True``, a small default linewidth of ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), this specific linewidth is used to cover up the white lines. This feature is automatically disabled when the patches have transparency. mean, means : bool, default: False Whether to plot the means of each column for 2D `y` coordinates. Means - are calculated with `numpy.nanmean`. If no other arguments are specified, + are calculated with [numpy.nanmean](https://numpy.org/doc/stable/reference/generated/numpy.nanmean.html). If no other arguments are specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). median, medians : bool, default: False Whether to plot the medians of each column for 2D `y` coordinates. Medians - are calculated with `numpy.nanmedian`. If no other arguments arguments are + are calculated with [numpy.nanmedian](https://numpy.org/doc/stable/reference/generated/numpy.nanmedian.html). If no other arguments arguments are specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). bars : bool, default: None Shorthand for `barstd`, `barstds`. @@ -5438,15 +5417,15 @@ boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional is ``True``, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When "boxes" and "bars" are combined, this has the effect of drawing miniature box-and-whisker plots. -capsize : float, default: :rc:`errorbar.capsize` +capsize : float, default: [errorbar.capsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=errorbar.capsize) The cap size for thin error bars in points. barz, barzorder, boxz, boxzorder : float, default: 2.5 The "zorder" for the thin and thick error bars. -barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` +barc, barcolor, boxc, boxcolor : color-spec, default: [boxplot.whiskerprops.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.color) Colors for the thin and thick error bars. -barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` +barlw, barlinewidth, boxlw, boxlinewidth : float, default: [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth) Line widths for the thin and thick error bars, in points. The default for boxes - is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. + is 4 times [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth). boxm, boxmarker : bool or marker-spec, default: 'o' Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if `boxes` is ``False``. @@ -5454,10 +5433,10 @@ boxms, boxmarkersize : size-spec, default: ``(2 * boxlinewidth) ** 2`` The marker size for the `boxmarker` marker in points ** 2. boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor : color-spec, default: 'w' Color, face color, and edge color for the `boxmarker` marker. -inbounds : bool, default: :rc:`axes.inbounds` +inbounds : bool, default: [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) Whether to restrict the default `y` (`x`) axis limits to account for only in-bounds data when the `x` (`y`) axis limits have been locked. - See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. + See also [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) and [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds). label, value : float or str, optional The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally @@ -5469,22 +5448,22 @@ labels, values : sequence of float or sequence of str, optional colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `~matplotlib.axes.Axes.bar`. + Passed to [bar](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.bar.html). See also -------- @@ -5556,15 +5535,15 @@ Returns Other Parameters ---------------- -color : :mpltype:`color` or list of :mpltype:`color`, optional +color : [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color), optional The colors of the bar faces. This is an alias for *facecolor*. If both are given, *facecolor* takes precedence. -facecolor : :mpltype:`color` or list of :mpltype:`color`, optional +facecolor : [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color), optional The colors of the bar faces. If both *color* and *facecolor are given, *facecolor* takes precedence. -edgecolor : :mpltype:`color` or list of :mpltype:`color`, optional +edgecolor : [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color), optional The colors of the bar edges. linewidth : float or array-like, optional @@ -5593,13 +5572,13 @@ xerr, yerr : float or array-like of shape(N,) or shape(2, N), optional errors. - *None*: No errorbar. (Default) - See :doc:`/gallery/statistics/errorbar_features` for an example on + See [/gallery/statistics/errorbar_features](https://ultraplot.readthedocs.io/en/stable/search.html?q=%2Fgallery%2Fstatistics%2Ferrorbar_features) for an example on the usage of *xerr* and *yerr*. -ecolor : :mpltype:`color` or list of :mpltype:`color`, default: 'black' +ecolor : [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color), default: 'black' The line color of the errorbars. -capsize : float, default: :rc:`errorbar.capsize` +capsize : float, default: [errorbar.capsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=errorbar.capsize) The length of the error bar caps in points. error_kw : dict, optional @@ -5624,13 +5603,13 @@ Properties: antialiased or aa: bool or None bounds: (left, bottom, width, height) capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} - clip_box: `~matplotlib.transforms.BboxBase` or None + clip_box: [BboxBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.BboxBase.html) or None clip_on: bool clip_path: Patch or (Path, Transform) or None - color: :mpltype:`color` - edgecolor or ec: :mpltype:`color` or None - facecolor or fc: :mpltype:`color` or None - figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + color: [color](https://matplotlib.org/stable/search.html?q=color) + edgecolor or ec: [color](https://matplotlib.org/stable/search.html?q=color) or None + facecolor or fc: [color](https://matplotlib.org/stable/search.html?q=color) or None + figure: [Figure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html) or [SubFigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.SubFigure.html) fill: bool gid: str hatch: {'/', '\\\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'} @@ -5647,7 +5626,7 @@ Properties: rasterized: bool sketch_params: (scale: float, length: float, randomness: float) snap: bool or None - transform: `~matplotlib.transforms.Transform` + transform: [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html) url: str visible: bool width: unknown @@ -5663,7 +5642,7 @@ barh : Plot a horizontal bar plot. Notes ----- Stacked bars can be achieved by passing individual *bottom* values per -bar. See :doc:`/gallery/lines_bars_and_markers/bar_stacked`.""" +bar. See [/gallery/lines_bars_and_markers/bar_stacked](https://ultraplot.readthedocs.io/en/stable/search.html?q=%2Fgallery%2Flines_bars_and_markers%2Fbar_stacked).""" ... def barh(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -5675,15 +5654,15 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `x` coordinates are passed, try to infer the `y` coordinates - from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the - :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + from the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the + [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, x.shape[0])``. * If the `x` coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. width : float or array-like, default: 0.8 The width(s) of the bars. Can be passed as a third positional argument. If `absolute_width` is ``True`` (the default) these are in units relative to the @@ -5700,34 +5679,33 @@ stack, stacked : bool, default: False bar_labels : bool, default rc["bar.bar_labels"] Whether to show the height values for vertical bars or width values for horizontal bars. bar_labels_kw : dict, default None - Keywords to format the bar_labels, see :func:`~matplotlib.pyplot.bar_label`. + Keywords to format the bar_labels, see [bar_label](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.bar_label.html). data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. -linewidth : unit-spec, default: :rc:`patch.linewidth` + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). +linewidth : unit-spec, default: [patch.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.linewidth) The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). linestyle : str, default: '-' The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. edgecolor : color-spec, default: 'none' @@ -5740,24 +5718,24 @@ negpos : bool, default: False Whether to shade bars where ``height >= 0`` with `poscolor` and where ``height < 0`` with `negcolor`. If ``True`` this function will return a length-2 silent list of handles. -negcolor, poscolor : color-spec, default: :rc:`negcolor`, :rc:`poscolor` +negcolor, poscolor : color-spec, default: [negcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=negcolor), [poscolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=poscolor) Colors to use for the negative and positive bars. Ignored if `negpos` is ``False``. -edgefix : bool or float, default: :rc:`edgefix` +edgefix : bool or float, default: [edgefix](https://ultraplot.readthedocs.io/en/stable/search.html?q=edgefix) Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). - See this `github repo `__ for a + See this [github repo](https://github.com/jklymak/contourfIssues) for a demonstration of the problem. If ``True``, a small default linewidth of ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), this specific linewidth is used to cover up the white lines. This feature is automatically disabled when the patches have transparency. mean, means : bool, default: False Whether to plot the means of each column for 2D `x` coordinates. Means - are calculated with `numpy.nanmean`. If no other arguments are specified, + are calculated with [numpy.nanmean](https://numpy.org/doc/stable/reference/generated/numpy.nanmean.html). If no other arguments are specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). median, medians : bool, default: False Whether to plot the medians of each column for 2D `x` coordinates. Medians - are calculated with `numpy.nanmedian`. If no other arguments arguments are + are calculated with [numpy.nanmedian](https://numpy.org/doc/stable/reference/generated/numpy.nanmedian.html). If no other arguments arguments are specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots). bars : bool, default: None Shorthand for `barstd`, `barstds`. @@ -5783,15 +5761,15 @@ boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional is ``True``, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When "boxes" and "bars" are combined, this has the effect of drawing miniature box-and-whisker plots. -capsize : float, default: :rc:`errorbar.capsize` +capsize : float, default: [errorbar.capsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=errorbar.capsize) The cap size for thin error bars in points. barz, barzorder, boxz, boxzorder : float, default: 2.5 The "zorder" for the thin and thick error bars. -barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` +barc, barcolor, boxc, boxcolor : color-spec, default: [boxplot.whiskerprops.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.color) Colors for the thin and thick error bars. -barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` +barlw, barlinewidth, boxlw, boxlinewidth : float, default: [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth) Line widths for the thin and thick error bars, in points. The default for boxes - is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. + is 4 times [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth). boxm, boxmarker : bool or marker-spec, default: 'o' Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if `boxes` is ``False``. @@ -5799,10 +5777,10 @@ boxms, boxmarkersize : size-spec, default: ``(2 * boxlinewidth) ** 2`` The marker size for the `boxmarker` marker in points ** 2. boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor : color-spec, default: 'w' Color, face color, and edge color for the `boxmarker` marker. -inbounds : bool, default: :rc:`axes.inbounds` +inbounds : bool, default: [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) Whether to restrict the default `y` (`x`) axis limits to account for only in-bounds data when the `x` (`y`) axis limits have been locked. - See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`. + See also [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds) and [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds). label, value : float or str, optional The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally @@ -5814,22 +5792,22 @@ labels, values : sequence of float or sequence of str, optional colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `~matplotlib.axes.Axes.barh`. + Passed to [barh](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.barh.html). See also -------- @@ -5902,10 +5880,10 @@ Returns Other Parameters ---------------- -color : :mpltype:`color` or list of :mpltype:`color`, optional +color : [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color), optional The colors of the bar faces. -edgecolor : :mpltype:`color` or list of :mpltype:`color`, optional +edgecolor : [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color), optional The colors of the bar edges. linewidth : float or array-like, optional @@ -5934,13 +5912,13 @@ xerr, yerr : float or array-like of shape(N,) or shape(2, N), optional errors. - *None*: No errorbar. (default) - See :doc:`/gallery/statistics/errorbar_features` for an example on + See [/gallery/statistics/errorbar_features](https://ultraplot.readthedocs.io/en/stable/search.html?q=%2Fgallery%2Fstatistics%2Ferrorbar_features) for an example on the usage of *xerr* and *yerr*. -ecolor : :mpltype:`color` or list of :mpltype:`color`, default: 'black' +ecolor : [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color), default: 'black' The line color of the errorbars. -capsize : float, default: :rc:`errorbar.capsize` +capsize : float, default: [errorbar.capsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=errorbar.capsize) The length of the error bar caps in points. error_kw : dict, optional @@ -5965,13 +5943,13 @@ Properties: antialiased or aa: bool or None bounds: (left, bottom, width, height) capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} - clip_box: `~matplotlib.transforms.BboxBase` or None + clip_box: [BboxBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.BboxBase.html) or None clip_on: bool clip_path: Patch or (Path, Transform) or None - color: :mpltype:`color` - edgecolor or ec: :mpltype:`color` or None - facecolor or fc: :mpltype:`color` or None - figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + color: [color](https://matplotlib.org/stable/search.html?q=color) + edgecolor or ec: [color](https://matplotlib.org/stable/search.html?q=color) or None + facecolor or fc: [color](https://matplotlib.org/stable/search.html?q=color) or None + figure: [Figure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html) or [SubFigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.SubFigure.html) fill: bool gid: str hatch: {'/', '\\\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'} @@ -5988,7 +5966,7 @@ Properties: rasterized: bool sketch_params: (scale: float, length: float, randomness: float) snap: bool or None - transform: `~matplotlib.transforms.Transform` + transform: [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html) url: str visible: bool width: unknown @@ -6005,7 +5983,7 @@ Notes ----- Stacked bars can be achieved by passing individual *left* values per bar. See -:doc:`/gallery/lines_bars_and_markers/horizontal_barchart_distribution`.""" +[/gallery/lines_bars_and_markers/horizontal_barchart_distribution](https://ultraplot.readthedocs.io/en/stable/search.html?q=%2Fgallery%2Flines_bars_and_markers%2Fhorizontal_barchart_distribution).""" ... def pie(self, x: Incomplete, explode: Incomplete, *, labelpad: Incomplete=None, labeldistance: Incomplete=None, **kwargs: Incomplete) -> Incomplete: @@ -6017,42 +5995,41 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `y` coordinates are passed, try to infer the `x` coordinates - from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the - :class:`~xarray.DataArray` coordinates. Otherwise, the `x` coordinates + from the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the + [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `x` coordinates are ``np.arange(0, y.shape[0])``. * If the `y` coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. -linewidth : unit-spec, default: :rc:`patch.linewidth` + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). +linewidth : unit-spec, default: [patch.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.linewidth) The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). linestyle : str, default: '-' The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. edgecolor : color-spec, default: 'none' @@ -6061,10 +6038,10 @@ facecolor : color-spec, optional The face color of the patch(es). The property `cycle` is used by default. Aliases: ``fc``, ``facecolors``, ``fillcolor``, ``fillcolors``. alpha : float, optional The opacity of the patch(es). Inferred from `facecolor` and `edgecolor` by default. Aliases: ``a``, ``alphas``. -edgefix : bool or float, default: :rc:`edgefix` +edgefix : bool or float, default: [edgefix](https://ultraplot.readthedocs.io/en/stable/search.html?q=edgefix) Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). - See this `github repo `__ for a + See this [github repo](https://github.com/jklymak/contourfIssues) for a demonstration of the problem. If ``True``, a small default linewidth of ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), this specific linewidth is used to cover up the white lines. This feature is @@ -6107,14 +6084,14 @@ explode : array-like, default: None labels : list, default: None A sequence of strings providing the labels for each wedge -colors : :mpltype:`color` or list of :mpltype:`color`, default: None +colors : [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color), default: None A sequence of colors through which the pie chart will cycle. If *None*, will use the colors in the currently active cycle. hatch : str or list, default: None Hatching pattern applied to all pie wedges or sequence of patterns through which the chart will cycle. For a list of valid patterns, - see :doc:`/gallery/shapes_and_collections/hatch_style_reference`. + see [/gallery/shapes_and_collections/hatch_style_reference](https://ultraplot.readthedocs.io/en/stable/search.html?q=%2Fgallery%2Fshapes_and_collections%2Fhatch_style_reference). .. versionadded:: 3.7 @@ -6186,7 +6163,7 @@ data : indexable object, optional Returns ------- patches : list - A sequence of `matplotlib.patches.Wedge` instances + A sequence of [matplotlib.patches.Wedge](https://matplotlib.org/stable/api/_as_gen/matplotlib.patches.Wedge.html) instances texts : list A list of the label `.Text` instances. @@ -6229,27 +6206,26 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `y` coordinates are passed, try to infer the `x` coordinates - from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the - :class:`~xarray.DataArray` coordinates. Otherwise, the `x` coordinates + from the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the + [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `x` coordinates are ``np.arange(0, y.shape[0])``. * If the `y` coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- @@ -6257,19 +6233,19 @@ fill : bool, default: True Whether to fill the box with a color. mean, means : bool, default: False If ``True``, this passes ``showmeans=True`` and ``meanline=True`` to - `matplotlib.axes.Axes.boxplot`. Adds mean lines alongside the median. + [matplotlib.axes.Axes.boxplot](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.boxplot.html). Adds mean lines alongside the median. cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. -linewidth : unit-spec, default: :rc:`patch.linewidth` + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). +linewidth : unit-spec, default: [patch.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.linewidth) The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). linestyle : str, default: '-' The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. edgecolor : color-spec, default: 'black' @@ -6280,23 +6256,23 @@ alpha : float, optional The opacity of the patch(es). Inferred from `facecolor` and `edgecolor` by default. Aliases: ``a``, ``alphas``. m, marker, ms, markersize : float or str, optional Marker style and size for the 'fliers', i.e. outliers. See the - ``boxplot.flierprops`` `~matplotlib.rcParams` settings. + ``boxplot.flierprops`` [rcParams](https://matplotlib.org/stable/api/_as_gen/matplotlib.rcParams.html) settings. meanls, medianls, meanlinestyle, medianlinestyle, meanlinestyles, medianlinestyles : str, optional Line style for the mean and median lines drawn across the box. See the ``boxplot.meanprops`` and ``boxplot.medianprops`` - `~matplotlib.rcParams` settings. + [rcParams](https://matplotlib.org/stable/api/_as_gen/matplotlib.rcParams.html) settings. boxc, capc, whiskerc, flierc, meanc, medianc, boxcolor, capcolor, whiskercolor, fliercolor, meancolor, mediancolor boxcolors, capcolors, whiskercolors, fliercolors, meancolors, mediancolors : color-spec or sequence, optional Color of various boxplot components. If a sequence, should be the same length as the number of boxes. These are shorthands so you don't have to pass e.g. a `boxprops` dictionary keyword. See the ``boxplot.boxprops``, ``boxplot.capprops``, ``boxplot.whiskerprops``, ``boxplot.flierprops``, ``boxplot.meanprops``, and - ``boxplot.medianprops`` `~matplotlib.rcParams` settings. + ``boxplot.medianprops`` [rcParams](https://matplotlib.org/stable/api/_as_gen/matplotlib.rcParams.html) settings. boxlw, caplw, whiskerlw, flierlw, meanlw, medianlw, boxlinewidth, caplinewidth, meanlinewidth, medianlinewidth, whiskerlinewidth, flierlinewidth, boxlinewidths, caplinewidths, meanlinewidths, medianlinewidths, whiskerlinewidths, flierlinewidths : float, optional Line width of various boxplot components. These are shorthands so you don't have to pass e.g. a `boxprops` dictionary keyword. See the ``boxplot.boxprops``, ``boxplot.capprops``, ``boxplot.whiskerprops``, ``boxplot.flierprops``, ``boxplot.meanprops``, and ``boxplot.medianprops`` - `~matplotlib.rcParams` settings. + [rcParams](https://matplotlib.org/stable/api/_as_gen/matplotlib.rcParams.html) settings. label, value : float or str, optional The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally @@ -6306,7 +6282,7 @@ labels, values : sequence of float or sequence of str, optional Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments. **kwargs - Passed to `matplotlib.axes.Axes.boxplot`. + Passed to [matplotlib.axes.Axes.boxplot](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.boxplot.html). See also -------- @@ -6326,27 +6302,26 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `x` coordinates are passed, try to infer the `y` coordinates - from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the - :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + from the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the + [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, x.shape[0])``. * If the `x` coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- @@ -6354,19 +6329,19 @@ fill : bool, default: True Whether to fill the box with a color. mean, means : bool, default: False If ``True``, this passes ``showmeans=True`` and ``meanline=True`` to - `matplotlib.axes.Axes.boxplot`. Adds mean lines alongside the median. + [matplotlib.axes.Axes.boxplot](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.boxplot.html). Adds mean lines alongside the median. cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. -linewidth : unit-spec, default: :rc:`patch.linewidth` + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). +linewidth : unit-spec, default: [patch.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.linewidth) The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). linestyle : str, default: '-' The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. edgecolor : color-spec, default: 'black' @@ -6377,23 +6352,23 @@ alpha : float, optional The opacity of the patch(es). Inferred from `facecolor` and `edgecolor` by default. Aliases: ``a``, ``alphas``. m, marker, ms, markersize : float or str, optional Marker style and size for the 'fliers', i.e. outliers. See the - ``boxplot.flierprops`` `~matplotlib.rcParams` settings. + ``boxplot.flierprops`` [rcParams](https://matplotlib.org/stable/api/_as_gen/matplotlib.rcParams.html) settings. meanls, medianls, meanlinestyle, medianlinestyle, meanlinestyles, medianlinestyles : str, optional Line style for the mean and median lines drawn across the box. See the ``boxplot.meanprops`` and ``boxplot.medianprops`` - `~matplotlib.rcParams` settings. + [rcParams](https://matplotlib.org/stable/api/_as_gen/matplotlib.rcParams.html) settings. boxc, capc, whiskerc, flierc, meanc, medianc, boxcolor, capcolor, whiskercolor, fliercolor, meancolor, mediancolor boxcolors, capcolors, whiskercolors, fliercolors, meancolors, mediancolors : color-spec or sequence, optional Color of various boxplot components. If a sequence, should be the same length as the number of boxes. These are shorthands so you don't have to pass e.g. a `boxprops` dictionary keyword. See the ``boxplot.boxprops``, ``boxplot.capprops``, ``boxplot.whiskerprops``, ``boxplot.flierprops``, ``boxplot.meanprops``, and - ``boxplot.medianprops`` `~matplotlib.rcParams` settings. + ``boxplot.medianprops`` [rcParams](https://matplotlib.org/stable/api/_as_gen/matplotlib.rcParams.html) settings. boxlw, caplw, whiskerlw, flierlw, meanlw, medianlw, boxlinewidth, caplinewidth, meanlinewidth, medianlinewidth, whiskerlinewidth, flierlinewidth, boxlinewidths, caplinewidths, meanlinewidths, medianlinewidths, whiskerlinewidths, flierlinewidths : float, optional Line width of various boxplot components. These are shorthands so you don't have to pass e.g. a `boxprops` dictionary keyword. See the ``boxplot.boxprops``, ``boxplot.capprops``, ``boxplot.whiskerprops``, ``boxplot.flierprops``, ``boxplot.meanprops``, and ``boxplot.medianprops`` - `~matplotlib.rcParams` settings. + [rcParams](https://matplotlib.org/stable/api/_as_gen/matplotlib.rcParams.html) settings. label, value : float or str, optional The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally @@ -6403,7 +6378,7 @@ labels, values : sequence of float or sequence of str, optional Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments. **kwargs - Passed to `matplotlib.axes.Axes.boxplot`. + Passed to [matplotlib.axes.Axes.boxplot](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.boxplot.html). See also -------- @@ -6423,27 +6398,26 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `y` coordinates are passed, try to infer the `x` coordinates - from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the - :class:`~xarray.DataArray` coordinates. Otherwise, the `x` coordinates + from the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the + [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `x` coordinates are ``np.arange(0, y.shape[0])``. * If the `y` coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- @@ -6451,19 +6425,19 @@ fill : bool, default: True Whether to fill the box with a color. mean, means : bool, default: False If ``True``, this passes ``showmeans=True`` and ``meanline=True`` to - `matplotlib.axes.Axes.boxplot`. Adds mean lines alongside the median. + [matplotlib.axes.Axes.boxplot](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.boxplot.html). Adds mean lines alongside the median. cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. -linewidth : unit-spec, default: :rc:`patch.linewidth` + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). +linewidth : unit-spec, default: [patch.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.linewidth) The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). linestyle : str, default: '-' The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. edgecolor : color-spec, default: 'black' @@ -6474,23 +6448,23 @@ alpha : float, optional The opacity of the patch(es). Inferred from `facecolor` and `edgecolor` by default. Aliases: ``a``, ``alphas``. m, marker, ms, markersize : float or str, optional Marker style and size for the 'fliers', i.e. outliers. See the - ``boxplot.flierprops`` `~matplotlib.rcParams` settings. + ``boxplot.flierprops`` [rcParams](https://matplotlib.org/stable/api/_as_gen/matplotlib.rcParams.html) settings. meanls, medianls, meanlinestyle, medianlinestyle, meanlinestyles, medianlinestyles : str, optional Line style for the mean and median lines drawn across the box. See the ``boxplot.meanprops`` and ``boxplot.medianprops`` - `~matplotlib.rcParams` settings. + [rcParams](https://matplotlib.org/stable/api/_as_gen/matplotlib.rcParams.html) settings. boxc, capc, whiskerc, flierc, meanc, medianc, boxcolor, capcolor, whiskercolor, fliercolor, meancolor, mediancolor boxcolors, capcolors, whiskercolors, fliercolors, meancolors, mediancolors : color-spec or sequence, optional Color of various boxplot components. If a sequence, should be the same length as the number of boxes. These are shorthands so you don't have to pass e.g. a `boxprops` dictionary keyword. See the ``boxplot.boxprops``, ``boxplot.capprops``, ``boxplot.whiskerprops``, ``boxplot.flierprops``, ``boxplot.meanprops``, and - ``boxplot.medianprops`` `~matplotlib.rcParams` settings. + ``boxplot.medianprops`` [rcParams](https://matplotlib.org/stable/api/_as_gen/matplotlib.rcParams.html) settings. boxlw, caplw, whiskerlw, flierlw, meanlw, medianlw, boxlinewidth, caplinewidth, meanlinewidth, medianlinewidth, whiskerlinewidth, flierlinewidth, boxlinewidths, caplinewidths, meanlinewidths, medianlinewidths, whiskerlinewidths, flierlinewidths : float, optional Line width of various boxplot components. These are shorthands so you don't have to pass e.g. a `boxprops` dictionary keyword. See the ``boxplot.boxprops``, ``boxplot.capprops``, ``boxplot.whiskerprops``, ``boxplot.flierprops``, ``boxplot.meanprops``, and ``boxplot.medianprops`` - `~matplotlib.rcParams` settings. + [rcParams](https://matplotlib.org/stable/api/_as_gen/matplotlib.rcParams.html) settings. label, value : float or str, optional The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally @@ -6500,7 +6474,7 @@ labels, values : sequence of float or sequence of str, optional Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments. **kwargs - Passed to `matplotlib.axes.Axes.boxplot`. + Passed to [matplotlib.axes.Axes.boxplot](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.boxplot.html). See also -------- @@ -6539,7 +6513,7 @@ x : Array or a sequence of vectors. in *x*. If a sequence of 1D arrays, a boxplot is drawn for each array in *x*. -notch : bool, default: :rc:`boxplot.notch` +notch : bool, default: [boxplot.notch](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.notch) Whether to draw a notched boxplot (`True`), or a rectangular boxplot (`False`). The notches represent the confidence interval (CI) around the median. The documentation for *bootstrap* @@ -6632,7 +6606,7 @@ widths : float or array-like The widths of the boxes. The default is 0.5, or ``0.15*(distance between extreme positions)``, if that is smaller. -patch_artist : bool, default: :rc:`boxplot.patchartist` +patch_artist : bool, default: [boxplot.patchartist](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.patchartist) If `False` produces boxes with the Line2D artist. Otherwise, boxes are drawn with Patch artists. @@ -6655,7 +6629,7 @@ autorange : bool, default: False 75th percentiles are equal, *whis* is set to (0, 100) such that the whisker ends are at the minimum and maximum of the data. -meanline : bool, default: :rc:`boxplot.meanline` +meanline : bool, default: [boxplot.meanline](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.meanline) If `True` (and *showmeans* is `True`), will try to render the mean as a line spanning the full width of the box according to *meanprops* (see below). Not recommended if *shownotches* is also @@ -6690,13 +6664,13 @@ dict Other Parameters ---------------- -showcaps : bool, default: :rc:`boxplot.showcaps` +showcaps : bool, default: [boxplot.showcaps](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.showcaps) Show the caps on the ends of whiskers. -showbox : bool, default: :rc:`boxplot.showbox` +showbox : bool, default: [boxplot.showbox](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.showbox) Show the central box. -showfliers : bool, default: :rc:`boxplot.showfliers` +showfliers : bool, default: [boxplot.showfliers](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.showfliers) Show the outliers beyond the caps. -showmeans : bool, default: :rc:`boxplot.showmeans` +showmeans : bool, default: [boxplot.showmeans](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.showmeans) Show the arithmetic means. capprops : dict, default: None The style of the caps. @@ -6717,7 +6691,7 @@ label : str or list of str, optional you only want a single legend entry for them. Use a list of strings to label all boxes individually. To be distinguishable, the boxes should be styled individually, which is currently only possible by modifying the - returned artists, see e.g. :doc:`/gallery/statistics/boxplot_demo`. + returned artists, see e.g. [/gallery/statistics/boxplot_demo](https://ultraplot.readthedocs.io/en/stable/search.html?q=%2Fgallery%2Fstatistics%2Fboxplot_demo). In the case of a single string, the legend entry will technically be associated with the first box only. By default, the legend will show the @@ -6745,27 +6719,26 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `x` coordinates are passed, try to infer the `y` coordinates - from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the - :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + from the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the + [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, x.shape[0])``. * If the `x` coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- @@ -6773,19 +6746,19 @@ fill : bool, default: True Whether to fill the box with a color. mean, means : bool, default: False If ``True``, this passes ``showmeans=True`` and ``meanline=True`` to - `matplotlib.axes.Axes.boxplot`. Adds mean lines alongside the median. + [matplotlib.axes.Axes.boxplot](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.boxplot.html). Adds mean lines alongside the median. cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. -linewidth : unit-spec, default: :rc:`patch.linewidth` + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). +linewidth : unit-spec, default: [patch.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.linewidth) The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). linestyle : str, default: '-' The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. edgecolor : color-spec, default: 'black' @@ -6796,23 +6769,23 @@ alpha : float, optional The opacity of the patch(es). Inferred from `facecolor` and `edgecolor` by default. Aliases: ``a``, ``alphas``. m, marker, ms, markersize : float or str, optional Marker style and size for the 'fliers', i.e. outliers. See the - ``boxplot.flierprops`` `~matplotlib.rcParams` settings. + ``boxplot.flierprops`` [rcParams](https://matplotlib.org/stable/api/_as_gen/matplotlib.rcParams.html) settings. meanls, medianls, meanlinestyle, medianlinestyle, meanlinestyles, medianlinestyles : str, optional Line style for the mean and median lines drawn across the box. See the ``boxplot.meanprops`` and ``boxplot.medianprops`` - `~matplotlib.rcParams` settings. + [rcParams](https://matplotlib.org/stable/api/_as_gen/matplotlib.rcParams.html) settings. boxc, capc, whiskerc, flierc, meanc, medianc, boxcolor, capcolor, whiskercolor, fliercolor, meancolor, mediancolor boxcolors, capcolors, whiskercolors, fliercolors, meancolors, mediancolors : color-spec or sequence, optional Color of various boxplot components. If a sequence, should be the same length as the number of boxes. These are shorthands so you don't have to pass e.g. a `boxprops` dictionary keyword. See the ``boxplot.boxprops``, ``boxplot.capprops``, ``boxplot.whiskerprops``, ``boxplot.flierprops``, ``boxplot.meanprops``, and - ``boxplot.medianprops`` `~matplotlib.rcParams` settings. + ``boxplot.medianprops`` [rcParams](https://matplotlib.org/stable/api/_as_gen/matplotlib.rcParams.html) settings. boxlw, caplw, whiskerlw, flierlw, meanlw, medianlw, boxlinewidth, caplinewidth, meanlinewidth, medianlinewidth, whiskerlinewidth, flierlinewidth, boxlinewidths, caplinewidths, meanlinewidths, medianlinewidths, whiskerlinewidths, flierlinewidths : float, optional Line width of various boxplot components. These are shorthands so you don't have to pass e.g. a `boxprops` dictionary keyword. See the ``boxplot.boxprops``, ``boxplot.capprops``, ``boxplot.whiskerprops``, ``boxplot.flierprops``, ``boxplot.meanprops``, and ``boxplot.medianprops`` - `~matplotlib.rcParams` settings. + [rcParams](https://matplotlib.org/stable/api/_as_gen/matplotlib.rcParams.html) settings. label, value : float or str, optional The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally @@ -6822,7 +6795,7 @@ labels, values : sequence of float or sequence of str, optional Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments. **kwargs - Passed to `matplotlib.axes.Axes.boxplot`. + Passed to [matplotlib.axes.Axes.boxplot](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.boxplot.html). See also -------- @@ -6839,7 +6812,7 @@ matplotlib.axes.Axes.boxplot""" def violin(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: """Plot vertical violins with a nice default style matching -`this matplotlib example `__. +[this matplotlib example](https://matplotlib.org/stable/gallery/statistics/customized_violin.html). Parameters ---------- @@ -6847,42 +6820,41 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `y` coordinates are passed, try to infer the `x` coordinates - from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the - :class:`~xarray.DataArray` coordinates. Otherwise, the `x` coordinates + from the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the + [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `x` coordinates are ``np.arange(0, y.shape[0])``. * If the `y` coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. -linewidth : unit-spec, default: :rc:`patch.linewidth` + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). +linewidth : unit-spec, default: [patch.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.linewidth) The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). linestyle : str, default: '-' The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. edgecolor : color-spec, default: 'black' @@ -6927,15 +6899,15 @@ boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional is ``True``, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When "boxes" and "bars" are combined, this has the effect of drawing miniature box-and-whisker plots. -capsize : float, default: :rc:`errorbar.capsize` +capsize : float, default: [errorbar.capsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=errorbar.capsize) The cap size for thin error bars in points. barz, barzorder, boxz, boxzorder : float, default: 2.5 The "zorder" for the thin and thick error bars. -barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` +barc, barcolor, boxc, boxcolor : color-spec, default: [boxplot.whiskerprops.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.color) Colors for the thin and thick error bars. -barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` +barlw, barlinewidth, boxlw, boxlinewidth : float, default: [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth) Line widths for the thin and thick error bars, in points. The default for boxes - is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. + is 4 times [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth). boxm, boxmarker : bool or marker-spec, default: 'o' Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if `boxes` is ``False``. @@ -6944,7 +6916,7 @@ boxms, boxmarkersize : size-spec, default: ``(2 * boxlinewidth) ** 2`` boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor : color-spec, default: 'w' Color, face color, and edge color for the `boxmarker` marker. **kwargs - Passed to `matplotlib.axes.Axes.violinplot`. + Passed to [matplotlib.axes.Axes.violinplot](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.violinplot.html). See also -------- @@ -6957,7 +6929,7 @@ matplotlib.axes.Axes.violinplot""" def violinh(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: """Plot horizontal violins with a nice default style matching -`this matplotlib example `__. +[this matplotlib example](https://matplotlib.org/stable/gallery/statistics/customized_violin.html). Parameters ---------- @@ -6965,42 +6937,41 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `x` coordinates are passed, try to infer the `y` coordinates - from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the - :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + from the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the + [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, x.shape[0])``. * If the `x` coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. -linewidth : unit-spec, default: :rc:`patch.linewidth` + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). +linewidth : unit-spec, default: [patch.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.linewidth) The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). linestyle : str, default: '-' The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. edgecolor : color-spec, default: 'black' @@ -7045,15 +7016,15 @@ boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional is ``True``, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When "boxes" and "bars" are combined, this has the effect of drawing miniature box-and-whisker plots. -capsize : float, default: :rc:`errorbar.capsize` +capsize : float, default: [errorbar.capsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=errorbar.capsize) The cap size for thin error bars in points. barz, barzorder, boxz, boxzorder : float, default: 2.5 The "zorder" for the thin and thick error bars. -barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` +barc, barcolor, boxc, boxcolor : color-spec, default: [boxplot.whiskerprops.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.color) Colors for the thin and thick error bars. -barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` +barlw, barlinewidth, boxlw, boxlinewidth : float, default: [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth) Line widths for the thin and thick error bars, in points. The default for boxes - is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. + is 4 times [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth). boxm, boxmarker : bool or marker-spec, default: 'o' Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if `boxes` is ``False``. @@ -7062,7 +7033,7 @@ boxms, boxmarkersize : size-spec, default: ``(2 * boxlinewidth) ** 2`` boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor : color-spec, default: 'w' Color, face color, and edge color for the `boxmarker` marker. **kwargs - Passed to `matplotlib.axes.Axes.violinplot`. + Passed to [matplotlib.axes.Axes.violinplot](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.violinplot.html). See also -------- @@ -7075,7 +7046,7 @@ matplotlib.axes.Axes.violinplot""" def violinplot(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: """Plot vertical violins with a nice default style matching -`this matplotlib example `__. +[this matplotlib example](https://matplotlib.org/stable/gallery/statistics/customized_violin.html). Parameters ---------- @@ -7083,42 +7054,41 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `y` coordinates are passed, try to infer the `x` coordinates - from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the - :class:`~xarray.DataArray` coordinates. Otherwise, the `x` coordinates + from the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the + [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `x` coordinates are ``np.arange(0, y.shape[0])``. * If the `y` coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. -linewidth : unit-spec, default: :rc:`patch.linewidth` + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). +linewidth : unit-spec, default: [patch.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.linewidth) The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). linestyle : str, default: '-' The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. edgecolor : color-spec, default: 'black' @@ -7163,15 +7133,15 @@ boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional is ``True``, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When "boxes" and "bars" are combined, this has the effect of drawing miniature box-and-whisker plots. -capsize : float, default: :rc:`errorbar.capsize` +capsize : float, default: [errorbar.capsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=errorbar.capsize) The cap size for thin error bars in points. barz, barzorder, boxz, boxzorder : float, default: 2.5 The "zorder" for the thin and thick error bars. -barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` +barc, barcolor, boxc, boxcolor : color-spec, default: [boxplot.whiskerprops.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.color) Colors for the thin and thick error bars. -barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` +barlw, barlinewidth, boxlw, boxlinewidth : float, default: [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth) Line widths for the thin and thick error bars, in points. The default for boxes - is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. + is 4 times [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth). boxm, boxmarker : bool or marker-spec, default: 'o' Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if `boxes` is ``False``. @@ -7180,7 +7150,7 @@ boxms, boxmarkersize : size-spec, default: ``(2 * boxlinewidth) ** 2`` boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor : color-spec, default: 'w' Color, face color, and edge color for the `boxmarker` marker. **kwargs - Passed to `matplotlib.axes.Axes.violinplot`. + Passed to [matplotlib.axes.Axes.violinplot](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.violinplot.html). See also -------- @@ -7251,7 +7221,7 @@ points : int, default: 100 bw_method : {'scott', 'silverman'} or float or callable, default: 'scott' The method used to calculate the estimator bandwidth. If a float, this will be used directly as `kde.factor`. If a - callable, it should take a `matplotlib.mlab.GaussianKDE` instance as + callable, it should take a [matplotlib.mlab.GaussianKDE](https://matplotlib.org/stable/api/_as_gen/matplotlib.mlab.GaussianKDE.html) instance as its only parameter and return a float. side : {'both', 'low', 'high'}, default: 'both' @@ -7301,7 +7271,7 @@ boxplot : Draw a box and whisker plot.""" def violinploth(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: """Plot horizontal violins with a nice default style matching -`this matplotlib example `__. +[this matplotlib example](https://matplotlib.org/stable/gallery/statistics/customized_violin.html). Parameters ---------- @@ -7309,42 +7279,41 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `x` coordinates are passed, try to infer the `y` coordinates - from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the - :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + from the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the + [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, x.shape[0])``. * If the `x` coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. -linewidth : unit-spec, default: :rc:`patch.linewidth` + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). +linewidth : unit-spec, default: [patch.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.linewidth) The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). linestyle : str, default: '-' The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. edgecolor : color-spec, default: 'black' @@ -7389,15 +7358,15 @@ boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional is ``True``, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When "boxes" and "bars" are combined, this has the effect of drawing miniature box-and-whisker plots. -capsize : float, default: :rc:`errorbar.capsize` +capsize : float, default: [errorbar.capsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=errorbar.capsize) The cap size for thin error bars in points. barz, barzorder, boxz, boxzorder : float, default: 2.5 The "zorder" for the thin and thick error bars. -barc, barcolor, boxc, boxcolor : color-spec, default: :rc:`boxplot.whiskerprops.color` +barc, barcolor, boxc, boxcolor : color-spec, default: [boxplot.whiskerprops.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.color) Colors for the thin and thick error bars. -barlw, barlinewidth, boxlw, boxlinewidth : float, default: :rc:`boxplot.whiskerprops.linewidth` +barlw, barlinewidth, boxlw, boxlinewidth : float, default: [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth) Line widths for the thin and thick error bars, in points. The default for boxes - is 4 times :rcraw:`boxplot.whiskerprops.linewidth`. + is 4 times [boxplot.whiskerprops.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=boxplot.whiskerprops.linewidth). boxm, boxmarker : bool or marker-spec, default: 'o' Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if `boxes` is ``False``. @@ -7406,7 +7375,7 @@ boxms, boxmarkersize : size-spec, default: ``(2 * boxlinewidth) ** 2`` boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor : color-spec, default: 'w' Color, face color, and edge color for the `boxmarker` marker. **kwargs - Passed to `matplotlib.axes.Axes.violinplot`. + Passed to [matplotlib.axes.Axes.violinplot](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.violinplot.html). See also -------- @@ -7440,7 +7409,7 @@ kde_kw : dict, optional for the latter) control the estimate and the remaining keys style the resulting curve, e.g. ``color``, ``linestyle``, ``linewidth``. Only used when hist=False. -points : int, default: :rc:`kde.points` +points : int, default: [kde.points](https://ultraplot.readthedocs.io/en/stable/search.html?q=kde.points) Number of points to evaluate the KDE at. Higher values create smoother curves but take longer to compute. Only used when hist=False. hist : bool, default: False @@ -7506,7 +7475,7 @@ overlap : float, default: 0.5 positioning mode (when positions is None). kde_kw : dict, optional Settings for the kernel density estimate. The following keys control the - estimate itself and are passed to `scipy.stats.gaussian_kde`: + estimate itself and are passed to [scipy.stats.gaussian_kde](https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.gaussian_kde.html): * ``bw_method`` : Bandwidth selection method (scalar, 'scott', 'silverman', or callable) * ``weights`` : Array of weights for each data point @@ -7514,9 +7483,9 @@ kde_kw : dict, optional (``stepsize`` is accepted as an alias) The remaining keys style the resulting curve and are passed to - `matplotlib.axes.Axes.plot`, e.g. ``color``, ``linestyle``, ``linewidth``. + [matplotlib.axes.Axes.plot](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.plot.html), e.g. ``color``, ``linestyle``, ``linewidth``. Only used when hist=False. -points : int, default: :rc:`kde.points` +points : int, default: [kde.points](https://ultraplot.readthedocs.io/en/stable/search.html?q=kde.points) Number of evaluation points for KDE curves. Higher values create smoother curves but take longer to compute. Only used when hist=False. hist : bool, default: False @@ -7603,7 +7572,7 @@ overlap : float, default: 0.5 positioning mode (when positions is None). kde_kw : dict, optional Settings for the kernel density estimate. The following keys control the - estimate itself and are passed to `scipy.stats.gaussian_kde`: + estimate itself and are passed to [scipy.stats.gaussian_kde](https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.gaussian_kde.html): * ``bw_method`` : Bandwidth selection method (scalar, 'scott', 'silverman', or callable) * ``weights`` : Array of weights for each data point @@ -7611,9 +7580,9 @@ kde_kw : dict, optional (``stepsize`` is accepted as an alias) The remaining keys style the resulting curve and are passed to - `matplotlib.axes.Axes.plot`, e.g. ``color``, ``linestyle``, ``linewidth``. + [matplotlib.axes.Axes.plot](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.plot.html), e.g. ``color``, ``linestyle``, ``linewidth``. Only used when hist=False. -points : int, default: :rc:`kde.points` +points : int, default: [kde.points](https://ultraplot.readthedocs.io/en/stable/search.html?q=kde.points) Number of evaluation points for KDE curves. Higher values create smoother curves but take longer to compute. Only used when hist=False. hist : bool, default: False @@ -7683,22 +7652,22 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `x` coordinates are passed, try to infer the `y` coordinates - from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the - :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + from the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the + [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, x.shape[0])``. * If the `x` coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. bins : int or sequence of float, optional The bin count or exact bin edges. weights : array-like, optional The weights associated with each point. If string this can be retrieved from `data` (see below). histtype : {'bar', 'barstacked', 'step', 'stepfilled'}, optional - The histogram type. See `matplotlib.axes.Axes.hist` for details. + The histogram type. See [matplotlib.axes.Axes.hist](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.hist.html) for details. width, rwidth : float, default: 0.8 or 1 The bar width(s) for bar-type histograms relative to the bin size. Default is ``0.8`` for multiple columns of unstacked data and ``1`` otherwise. @@ -7710,50 +7679,49 @@ kde : bool, default: False Whether to overlay a gaussian kernel density estimate of each column of data. The curve tracks the histogram, i.e. it is scaled to the bin counts unless ``density=True`` and accumulated when the histogram is stacked. - Requires `scipy `__. + Requires [scipy](https://scipy.org). kde_kw : dict, optional Settings for the kernel density estimate. The following keys control the - estimate itself and are passed to `scipy.stats.gaussian_kde`: + estimate itself and are passed to [scipy.stats.gaussian_kde](https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.gaussian_kde.html): * ``bw_method`` : Bandwidth selection method (scalar, 'scott', 'silverman', or callable) * ``weights`` : Array of weights for each data point, defaults to `weights` - * ``points`` : Number of evaluation points, default :rc:`kde.points` + * ``points`` : Number of evaluation points, default [kde.points](https://ultraplot.readthedocs.io/en/stable/search.html?q=kde.points) (``stepsize`` is accepted as an alias) The remaining keys style the resulting curve and are passed to - `matplotlib.axes.Axes.plot`, e.g. ``color``, ``linestyle``, ``linewidth``. + [matplotlib.axes.Axes.plot](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.plot.html), e.g. ``color``, ``linestyle``, ``linewidth``. By default each curve takes the color of its histogram. fill, filled : bool, optional Whether to "fill" step-type histograms or just plot the edges. Setting this to ``False`` is equivalent to ``histtype='step'`` and to ``True`` is equivalent to ``histtype='stepfilled'``. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. -linewidth : unit-spec, default: :rc:`patch.linewidth` + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). +linewidth : unit-spec, default: [patch.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.linewidth) The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). linestyle : str, default: '-' The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. edgecolor : color-spec, default: 'none' @@ -7762,10 +7730,10 @@ facecolor : color-spec, optional The face color of the patch(es). The property `cycle` is used by default. Aliases: ``fc``, ``facecolors``, ``fillcolor``, ``fillcolors``. alpha : float, optional The opacity of the patch(es). Inferred from `facecolor` and `edgecolor` by default. Aliases: ``a``, ``alphas``. -edgefix : bool or float, default: :rc:`edgefix` +edgefix : bool or float, default: [edgefix](https://ultraplot.readthedocs.io/en/stable/search.html?q=edgefix) Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). - See this `github repo `__ for a + See this [github repo](https://github.com/jklymak/contourfIssues) for a demonstration of the problem. If ``True``, a small default linewidth of ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), this specific linewidth is used to cover up the white lines. This feature is @@ -7781,22 +7749,22 @@ labels, values : sequence of float or sequence of str, optional colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `~matplotlib.axes.Axes.hist`. + Passed to [hist](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.hist.html). See also -------- @@ -7809,10 +7777,10 @@ Matplotlib documentation Compute and plot a histogram. -This method uses `numpy.histogram` to bin the data in *x* and count the +This method uses [numpy.histogram](https://numpy.org/doc/stable/reference/generated/numpy.histogram.html) to bin the data in *x* and count the number of values in each bin, then draws the distribution either as a `.BarContainer` or `.Polygon`. The *bins*, *range*, *density*, and -*weights* parameters are forwarded to `numpy.histogram`. +*weights* parameters are forwarded to [numpy.histogram](https://numpy.org/doc/stable/reference/generated/numpy.histogram.html). If the data has already been binned and counted, use `~.bar` or `~.stairs` to plot the distribution:: @@ -7841,7 +7809,7 @@ x : (n,) array or sequence of (n,) arrays Input values, this takes either a single array or a sequence of arrays which are not required to be of the same length. -bins : int or sequence or str, default: :rc:`hist.bins` +bins : int or sequence or str, default: [hist.bins](https://ultraplot.readthedocs.io/en/stable/search.html?q=hist.bins) If *bins* is an integer, it defines the number of equal-width bins in the range. @@ -7857,7 +7825,7 @@ bins : int or sequence or str, default: :rc:`hist.bins` *includes* 4. If *bins* is a string, it is one of the binning strategies - supported by `numpy.histogram_bin_edges`: 'auto', 'fd', 'doane', + supported by [numpy.histogram_bin_edges](https://numpy.org/doc/stable/reference/generated/numpy.histogram_bin_edges.html): 'auto', 'fd', 'doane', 'scott', 'stone', 'rice', 'sturges', or 'sqrt'. range : tuple or None, default: None @@ -7937,7 +7905,7 @@ rwidth : float or None, default: None log : bool, default: False If ``True``, the histogram axis will be set to a log scale. -color : :mpltype:`color` or list of :mpltype:`color` or None, default: None +color : [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color) or None, default: None Color or sequence of colors, one per dataset. Default (``None``) uses the standard line color sequence. @@ -7980,7 +7948,7 @@ data : indexable object, optional *x*, *weights* **kwargs - `~matplotlib.patches.Patch` properties. The following properties + [Patch](https://matplotlib.org/stable/api/_as_gen/matplotlib.patches.Patch.html) properties. The following properties additionally accept a sequence of values corresponding to the datasets in *x*: *edgecolor*, *facecolor*, *linewidth*, *linestyle*, *hatch*. @@ -8012,22 +7980,22 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `x` coordinates are passed, try to infer the `y` coordinates - from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the - :class:`~xarray.DataArray` coordinates. Otherwise, the `y` coordinates + from the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the + [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, x.shape[0])``. * If the `x` coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. bins : int or sequence of float, optional The bin count or exact bin edges. weights : array-like, optional The weights associated with each point. If string this can be retrieved from `data` (see below). histtype : {'bar', 'barstacked', 'step', 'stepfilled'}, optional - The histogram type. See `matplotlib.axes.Axes.hist` for details. + The histogram type. See [matplotlib.axes.Axes.hist](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.hist.html) for details. width, rwidth : float, default: 0.8 or 1 The bar width(s) for bar-type histograms relative to the bin size. Default is ``0.8`` for multiple columns of unstacked data and ``1`` otherwise. @@ -8039,50 +8007,49 @@ kde : bool, default: False Whether to overlay a gaussian kernel density estimate of each column of data. The curve tracks the histogram, i.e. it is scaled to the bin counts unless ``density=True`` and accumulated when the histogram is stacked. - Requires `scipy `__. + Requires [scipy](https://scipy.org). kde_kw : dict, optional Settings for the kernel density estimate. The following keys control the - estimate itself and are passed to `scipy.stats.gaussian_kde`: + estimate itself and are passed to [scipy.stats.gaussian_kde](https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.gaussian_kde.html): * ``bw_method`` : Bandwidth selection method (scalar, 'scott', 'silverman', or callable) * ``weights`` : Array of weights for each data point, defaults to `weights` - * ``points`` : Number of evaluation points, default :rc:`kde.points` + * ``points`` : Number of evaluation points, default [kde.points](https://ultraplot.readthedocs.io/en/stable/search.html?q=kde.points) (``stepsize`` is accepted as an alias) The remaining keys style the resulting curve and are passed to - `matplotlib.axes.Axes.plot`, e.g. ``color``, ``linestyle``, ``linewidth``. + [matplotlib.axes.Axes.plot](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.plot.html), e.g. ``color``, ``linestyle``, ``linewidth``. By default each curve takes the color of its histogram. fill, filled : bool, optional Whether to "fill" step-type histograms or just plot the edges. Setting this to ``False`` is equivalent to ``histtype='step'`` and to ``True`` is equivalent to ``histtype='stepfilled'``. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- cycle : cycle-spec, optional - The cycle specifer, passed to the `~ultraplot.constructor.Cycle` constructor. + The cycle specifer, passed to the [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html) constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use ``cycle=False``, ``cycle='none'``, or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``). To restore the default property cycler, use ``cycle=True``. cycle_kw : dict-like, optional - Passed to `~ultraplot.constructor.Cycle`. -linewidth : unit-spec, default: :rc:`patch.linewidth` + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). +linewidth : unit-spec, default: [patch.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.linewidth) The edge width of the patch(es). Aliases: ``lw``, ``linewidths``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). linestyle : str, default: '-' The edge style of the patch(es). Aliases: ``ls``, ``linestyles``. edgecolor : color-spec, default: 'none' @@ -8091,10 +8058,10 @@ facecolor : color-spec, optional The face color of the patch(es). The property `cycle` is used by default. Aliases: ``fc``, ``facecolors``, ``fillcolor``, ``fillcolors``. alpha : float, optional The opacity of the patch(es). Inferred from `facecolor` and `edgecolor` by default. Aliases: ``a``, ``alphas``. -edgefix : bool or float, default: :rc:`edgefix` +edgefix : bool or float, default: [edgefix](https://ultraplot.readthedocs.io/en/stable/search.html?q=edgefix) Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). - See this `github repo `__ for a + See this [github repo](https://github.com/jklymak/contourfIssues) for a demonstration of the problem. If ``True``, a small default linewidth of ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), this specific linewidth is used to cover up the white lines. This feature is @@ -8110,22 +8077,22 @@ labels, values : sequence of float or sequence of str, optional colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `~matplotlib.axes.Axes.hist`. + Passed to [hist](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.hist.html). See also -------- @@ -8144,71 +8111,70 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `y` coordinates are passed, try to infer the `x` coordinates - from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the - :class:`~xarray.DataArray` coordinates. Otherwise, the `x` coordinates + from the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the + [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `x` coordinates are ``np.arange(0, y.shape[0])``. * If the `y` coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. bins : int or 2-tuple of int, or array-like or 2-tuple of array-like, optional The bin count or exact bin edges for each dimension or both dimensions. weights : array-like, optional The weights associated with each point. If string this can be retrieved from `data` (see below). data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- -cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` - The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor - function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization - range contains negative and positive values then :rcraw:`cmap.diverging` is used. - Otherwise :rcraw:`cmap.sequential` is used. +cmap : colormap-spec, default: [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) or [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) + The colormap specifer, passed to the [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html) constructor + function. If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization + range contains negative and positive values then [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) is used. + Otherwise [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) is used. cmap_kw : dict-like, optional - Passed to :class:`~ultraplot.constructor.Colormap`. + Passed to [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html). c, color, colors : color-spec or sequence of color-spec, optional - The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + The color(s) used to create a [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html). If not passed, `cmap` is used. -norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` - The data value normalizer, passed to the `~ultraplot.constructor.Norm` +norm : norm-spec, default: [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) or [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) + The data value normalizer, passed to the [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html) constructor function. If `discrete` is ``True`` then 1) this affects the default level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and - 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they - are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). - If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains - negative and positive values then `~ultraplot.colors.DivergingNorm` is used. - Otherwise `~matplotlib.colors.Normalize` is used. + 2) this is passed to [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) to scale the colors before they + are discretized (if `norm` is not already a [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html)). + If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization range contains + negative and positive values then [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) is used. + Otherwise [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) is used. norm_kw : dict-like, optional - Passed to `~ultraplot.constructor.Norm`. + Passed to [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html). extend : {'neither', 'both', 'min', 'max'}, default: 'neither' Direction for drawing colorbar "extensions" indicating out-of-bounds data on the end of the colorbar. -discrete : bool, default: :rc:`cmap.discrete` - If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the +discrete : bool, default: [cmap.discrete](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.discrete) + If ``False``, then [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) is not applied to the colormap. Instead, for non-contour plots, the number of levels will be - roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + roughly controlled by [cmap.lut](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.lut). This has a similar effect to using `levels=large_number` but it may improve rendering speed. Default is - ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` - and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. + ``True`` only for contouring commands like [contourf](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.contourf) + and pseudocolor commands like [pcolor](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.pcolor). sequential, diverging, cyclic, qualitative : bool, default: None Boolean arguments used if `cmap` is not passed. Set these to ``True`` - to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, - :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. - The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + to use the default [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential), [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging), + [cmap.cyclic](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.cyclic), and [cmap.qualitative](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.qualitative) colormaps. + The `diverging` option also applies [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) as the default continuous normalizer. vmin, vmax : float, optional The minimum and maximum color scale values used with the `norm` normalizer. @@ -8221,7 +8187,7 @@ vmin, vmax : float, optional `vmin` and `vmax` are the minimum and maximum of the data values. N Shorthand for `levels`. -levels : int or sequence of float, default: :rc:`cmap.levels` +levels : int or sequence of float, default: [cmap.levels](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.levels) The number of level edges or a sequence of level edges. If the former, `locator` is used to generate this many level edges at "nice" intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing @@ -8229,31 +8195,31 @@ levels : int or sequence of float, default: :rc:`cmap.levels` values : int or sequence of float, default: None The number of level centers or a sequence of level centers. If the former, `locator` is used to generate this many level centers at "nice" intervals. - If the latter, levels are inferred using `~ultraplot.utils.edges`. + If the latter, levels are inferred using [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html). This will override any `levels` input. center_levels : bool, default False If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented. -robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` +robust : bool, float, or 2-tuple, default: [cmap.robust](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.robust) If ``True`` and `vmin` or `vmax` were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers. -inbounds : bool, default: :rc:`cmap.inbounds` +inbounds : bool, default: [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) If ``True`` and `vmin` or `vmax` were not provided, when axis limits - have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` - or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. - See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. -locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + have been explicitly restricted with [set_xlim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlim.html) + or [set_ylim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylim.html), out-of-bounds data is ignored. + See also [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) and [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds). +locator : locator-spec, default: [matplotlib.ticker.MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) The locator used to determine level locations if `levels` or `values` were not - already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. - Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. + already passed as lists. Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. + Default is [MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) with `levels` integer levels. locator_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Locator` class. + Keyword arguments passed to [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. symmetric : bool, default: False If ``True``, the normalization range or discrete colormap levels are symmetric about zero. @@ -8265,46 +8231,46 @@ negative : bool, default: False negative with a minimum at zero. nozero : bool, default: False If ``True``, ``0`` is removed from the level list. This is mainly useful for - single-color `~matplotlib.axes.Axes.contour` plots. + single-color [contour](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.contour.html) plots. label : str, optional The legend label to be used for this object. In the case of contours, this is paired with the the central artist in the artist - list returned by `matplotlib.contour.ContourSet.legend_elements`. + list returned by [matplotlib.contour.ContourSet.legend_elements](https://matplotlib.org/stable/api/_as_gen/matplotlib.contour.ContourSet.legend_elements.html). labels : bool, optional Whether to apply labels to contours and grid boxes. The text will be white when the luminance of the underlying filled contour or grid box is less than 50 and black otherwise. labels_kw : dict-like, optional Ignored if `labels` is ``False``. Extra keyword args for the labels. - For contour plots, this is passed to `~matplotlib.axes.Axes.clabel`. - Otherwise, this is passed to `~matplotlib.axes.Axes.text`. + For contour plots, this is passed to [clabel](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.clabel.html). + Otherwise, this is passed to [text](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.text.html). formatter, fmt : formatter-spec, optional - The `~matplotlib.ticker.Formatter` used to format number labels. - Passed to the `~ultraplot.constructor.Formatter` constructor. + The [Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) used to format number labels. + Passed to the [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html) constructor. formatter_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Formatter` class. + Keyword arguments passed to [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) class. precision : int, optional The maximum number of decimal places for number labels generated - with the default formatter `~ultraplot.ticker.Simpleformatter`. + with the default formatter [Simpleformatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.Simpleformatter.html). colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `~matplotlib.axes.Axes.hist2d`. + Passed to [hist2d](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.hist2d.html). See also -------- @@ -8370,11 +8336,11 @@ image : `~.matplotlib.collections.QuadMesh` Other Parameters ---------------- -cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap` +cmap : str or [Colormap](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Colormap.html), default: [image.cmap](https://ultraplot.readthedocs.io/en/stable/search.html?q=image.cmap) The Colormap instance or registered colormap name used to map scalar data to colors. -norm : str or `~matplotlib.colors.Normalize`, optional +norm : str or [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html), optional The normalization method used to scale scalar data to the [0, 1] range before mapping to colors using *cmap*. By default, a linear scaling is used, mapping the lowest value to 0 and the highest to 1. @@ -8382,9 +8348,9 @@ norm : str or `~matplotlib.colors.Normalize`, optional If given, this can be one of the following: - An instance of `.Normalize` or one of its subclasses - (see :ref:`colormapnorms`). + (see [colormapnorms](https://ultraplot.readthedocs.io/en/stable/search.html?q=colormapnorms)). - A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For a - list of available scales, call `matplotlib.scale.get_scale_names()`. + list of available scales, call [matplotlib.scale.get_scale_names()](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.get_scale_names().html). In that case, a suitable `.Normalize` subclass is dynamically generated and instantiated. @@ -8395,7 +8361,7 @@ vmin, vmax : float, optional *vmin*/*vmax* when a *norm* instance is given (but using a `str` *norm* name together with *vmin*/*vmax* is acceptable). -colorizer : `~matplotlib.colorizer.Colorizer` or None, default: None +colorizer : [Colorizer](https://matplotlib.org/stable/api/_as_gen/matplotlib.colorizer.Colorizer.html) or None, default: None The Colorizer object used to map color to data. If None, a Colorizer object is created from a *norm* and *cmap*. @@ -8410,7 +8376,7 @@ data : indexable object, optional **kwargs Additional parameters are passed along to the - `~.Axes.pcolormesh` method and `~matplotlib.collections.QuadMesh` + `~.Axes.pcolormesh` method and [QuadMesh](https://matplotlib.org/stable/api/_as_gen/matplotlib.collections.QuadMesh.html) constructor. See Also @@ -8439,69 +8405,68 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `y` coordinates are passed, try to infer the `x` coordinates - from the `~pandas.Series` or :class:`~pandas.DataFrame` indices or the - :class:`~xarray.DataArray` coordinates. Otherwise, the `x` coordinates + from the [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html) or [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices or the + [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `x` coordinates are ``np.arange(0, y.shape[0])``. * If the `y` coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with ``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``). - * If any arguments are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. - A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If any arguments are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). + A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. weights : array-like, optional The weights associated with each point. If string this can be retrieved from `data` (see below). data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- -cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` - The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor - function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization - range contains negative and positive values then :rcraw:`cmap.diverging` is used. - Otherwise :rcraw:`cmap.sequential` is used. +cmap : colormap-spec, default: [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) or [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) + The colormap specifer, passed to the [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html) constructor + function. If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization + range contains negative and positive values then [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) is used. + Otherwise [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) is used. cmap_kw : dict-like, optional - Passed to :class:`~ultraplot.constructor.Colormap`. + Passed to [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html). c, color, colors : color-spec or sequence of color-spec, optional - The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + The color(s) used to create a [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html). If not passed, `cmap` is used. -norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` - The data value normalizer, passed to the `~ultraplot.constructor.Norm` +norm : norm-spec, default: [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) or [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) + The data value normalizer, passed to the [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html) constructor function. If `discrete` is ``True`` then 1) this affects the default level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and - 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they - are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). - If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains - negative and positive values then `~ultraplot.colors.DivergingNorm` is used. - Otherwise `~matplotlib.colors.Normalize` is used. + 2) this is passed to [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) to scale the colors before they + are discretized (if `norm` is not already a [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html)). + If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization range contains + negative and positive values then [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) is used. + Otherwise [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) is used. norm_kw : dict-like, optional - Passed to `~ultraplot.constructor.Norm`. + Passed to [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html). extend : {'neither', 'both', 'min', 'max'}, default: 'neither' Direction for drawing colorbar "extensions" indicating out-of-bounds data on the end of the colorbar. -discrete : bool, default: :rc:`cmap.discrete` - If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the +discrete : bool, default: [cmap.discrete](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.discrete) + If ``False``, then [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) is not applied to the colormap. Instead, for non-contour plots, the number of levels will be - roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + roughly controlled by [cmap.lut](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.lut). This has a similar effect to using `levels=large_number` but it may improve rendering speed. Default is - ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` - and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. + ``True`` only for contouring commands like [contourf](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.contourf) + and pseudocolor commands like [pcolor](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.pcolor). sequential, diverging, cyclic, qualitative : bool, default: None Boolean arguments used if `cmap` is not passed. Set these to ``True`` - to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, - :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. - The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + to use the default [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential), [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging), + [cmap.cyclic](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.cyclic), and [cmap.qualitative](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.qualitative) colormaps. + The `diverging` option also applies [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) as the default continuous normalizer. vmin, vmax : float, optional The minimum and maximum color scale values used with the `norm` normalizer. @@ -8514,7 +8479,7 @@ vmin, vmax : float, optional `vmin` and `vmax` are the minimum and maximum of the data values. N Shorthand for `levels`. -levels : int or sequence of float, default: :rc:`cmap.levels` +levels : int or sequence of float, default: [cmap.levels](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.levels) The number of level edges or a sequence of level edges. If the former, `locator` is used to generate this many level edges at "nice" intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing @@ -8522,31 +8487,31 @@ levels : int or sequence of float, default: :rc:`cmap.levels` values : int or sequence of float, default: None The number of level centers or a sequence of level centers. If the former, `locator` is used to generate this many level centers at "nice" intervals. - If the latter, levels are inferred using `~ultraplot.utils.edges`. + If the latter, levels are inferred using [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html). This will override any `levels` input. center_levels : bool, default False If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented. -robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` +robust : bool, float, or 2-tuple, default: [cmap.robust](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.robust) If ``True`` and `vmin` or `vmax` were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers. -inbounds : bool, default: :rc:`cmap.inbounds` +inbounds : bool, default: [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) If ``True`` and `vmin` or `vmax` were not provided, when axis limits - have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` - or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. - See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. -locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + have been explicitly restricted with [set_xlim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlim.html) + or [set_ylim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylim.html), out-of-bounds data is ignored. + See also [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) and [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds). +locator : locator-spec, default: [matplotlib.ticker.MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) The locator used to determine level locations if `levels` or `values` were not - already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. - Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. + already passed as lists. Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. + Default is [MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) with `levels` integer levels. locator_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Locator` class. + Keyword arguments passed to [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. symmetric : bool, default: False If ``True``, the normalization range or discrete colormap levels are symmetric about zero. @@ -8558,46 +8523,46 @@ negative : bool, default: False negative with a minimum at zero. nozero : bool, default: False If ``True``, ``0`` is removed from the level list. This is mainly useful for - single-color `~matplotlib.axes.Axes.contour` plots. + single-color [contour](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.contour.html) plots. label : str, optional The legend label to be used for this object. In the case of contours, this is paired with the the central artist in the artist - list returned by `matplotlib.contour.ContourSet.legend_elements`. + list returned by [matplotlib.contour.ContourSet.legend_elements](https://matplotlib.org/stable/api/_as_gen/matplotlib.contour.ContourSet.legend_elements.html). labels : bool, optional Whether to apply labels to contours and grid boxes. The text will be white when the luminance of the underlying filled contour or grid box is less than 50 and black otherwise. labels_kw : dict-like, optional Ignored if `labels` is ``False``. Extra keyword args for the labels. - For contour plots, this is passed to `~matplotlib.axes.Axes.clabel`. - Otherwise, this is passed to `~matplotlib.axes.Axes.text`. + For contour plots, this is passed to [clabel](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.clabel.html). + Otherwise, this is passed to [text](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.text.html). formatter, fmt : formatter-spec, optional - The `~matplotlib.ticker.Formatter` used to format number labels. - Passed to the `~ultraplot.constructor.Formatter` constructor. + The [Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) used to format number labels. + Passed to the [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html) constructor. formatter_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Formatter` class. + Keyword arguments passed to [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) class. precision : int, optional The maximum number of decimal places for number labels generated - with the default formatter `~ultraplot.ticker.Simpleformatter`. + with the default formatter [Simpleformatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.Simpleformatter.html). colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `~matplotlib.axes.Axes.hexbin`. + Passed to [hexbin](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.hexbin.html). See also -------- @@ -8697,7 +8662,7 @@ extent : 4-tuple of float, default: *None* Returns ------- -`~matplotlib.collections.PolyCollection` +[PolyCollection](https://matplotlib.org/stable/api/_as_gen/matplotlib.collections.PolyCollection.html) A `.PolyCollection` defining the hexagonal bins. - `.PolyCollection.get_offsets` contains a Mx2 array containing @@ -8711,11 +8676,11 @@ Returns Other Parameters ---------------- -cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap` +cmap : str or [Colormap](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Colormap.html), default: [image.cmap](https://ultraplot.readthedocs.io/en/stable/search.html?q=image.cmap) The Colormap instance or registered colormap name used to map scalar data to colors. -norm : str or `~matplotlib.colors.Normalize`, optional +norm : str or [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html), optional The normalization method used to scale scalar data to the [0, 1] range before mapping to colors using *cmap*. By default, a linear scaling is used, mapping the lowest value to 0 and the highest to 1. @@ -8723,9 +8688,9 @@ norm : str or `~matplotlib.colors.Normalize`, optional If given, this can be one of the following: - An instance of `.Normalize` or one of its subclasses - (see :ref:`colormapnorms`). + (see [colormapnorms](https://ultraplot.readthedocs.io/en/stable/search.html?q=colormapnorms)). - A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For a - list of available scales, call `matplotlib.scale.get_scale_names()`. + list of available scales, call [matplotlib.scale.get_scale_names()](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.get_scale_names().html). In that case, a suitable `.Normalize` subclass is dynamically generated and instantiated. @@ -8740,7 +8705,7 @@ alpha : float between 0 and 1, optional The alpha blending value, between 0 (transparent) and 1 (opaque). linewidths : float, default: *None* - If *None*, defaults to :rc:`patch.linewidth`. + If *None*, defaults to [patch.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.linewidth). edgecolors : {'face', 'none', *None*} or color, default: 'face' The color of the hexagon edges. Possible values are: @@ -8751,7 +8716,7 @@ edgecolors : {'face', 'none', *None*} or color, default: 'face' - *None*: Draw outlines in the default color. - An explicit color. -reduce_C_function : callable, default: `numpy.mean` +reduce_C_function : callable, default: [numpy.mean](https://numpy.org/doc/stable/reference/generated/numpy.mean.html) The function to aggregate *C* within the bins. It is ignored if *C* is not given. This must have the signature:: @@ -8759,16 +8724,16 @@ reduce_C_function : callable, default: `numpy.mean` Commonly used functions are: - - `numpy.mean`: average of the points - - `numpy.sum`: integral of the point values - - `numpy.amax`: value taken from the largest point + - [numpy.mean](https://numpy.org/doc/stable/reference/generated/numpy.mean.html): average of the points + - [numpy.sum](https://numpy.org/doc/stable/reference/generated/numpy.sum.html): integral of the point values + - [numpy.amax](https://numpy.org/doc/stable/reference/generated/numpy.amax.html): value taken from the largest point By default will only reduce cells with at least 1 point because some - reduction functions (such as `numpy.amax`) will error/warn with empty + reduction functions (such as [numpy.amax](https://numpy.org/doc/stable/reference/generated/numpy.amax.html)) will error/warn with empty input. Changing *mincnt* will adjust the cutoff, and if set to 0 will pass empty input to the reduction function. -colorizer : `~matplotlib.colorizer.Colorizer` or None, default: None +colorizer : [Colorizer](https://matplotlib.org/stable/api/_as_gen/matplotlib.colorizer.Colorizer.html) or None, default: None The Colorizer object used to map color to data. If None, a Colorizer object is created from a *norm* and *cmap*. @@ -8778,7 +8743,7 @@ data : indexable object, optional *x*, *y*, *C* -**kwargs : `~matplotlib.collections.PolyCollection` properties +**kwargs : [PolyCollection](https://matplotlib.org/stable/api/_as_gen/matplotlib.collections.PolyCollection.html) properties All other keyword arguments are passed on to `.PolyCollection`: Properties: @@ -8789,14 +8754,14 @@ data : indexable object, optional array: array-like or None capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} clim: (vmin: float, vmax: float) - clip_box: `~matplotlib.transforms.BboxBase` or None + clip_box: [BboxBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.BboxBase.html) or None clip_on: bool clip_path: Patch or (Path, Transform) or None cmap: `.Colormap` or str or None - color: :mpltype:`color` or list of RGBA tuples - edgecolor or ec or edgecolors: :mpltype:`color` or list of :mpltype:`color` or 'face' - facecolor or facecolors or fc: :mpltype:`color` or list of :mpltype:`color` - figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + color: [color](https://matplotlib.org/stable/search.html?q=color) or list of RGBA tuples + edgecolor or ec or edgecolors: [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color) or 'face' + facecolor or facecolors or fc: [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color) + figure: [Figure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html) or [SubFigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.SubFigure.html) gid: str hatch: {'/', '\\\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'} hatch_linewidth: unknown @@ -8814,10 +8779,10 @@ data : indexable object, optional picker: None or bool or float or callable pickradius: float rasterized: bool - sizes: `numpy.ndarray` or None + sizes: [numpy.ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html) or None sketch_params: (scale: float, length: float, randomness: float) snap: bool or None - transform: `~matplotlib.transforms.Transform` + transform: [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html) url: str urls: list of str or None verts: list of array-like @@ -8839,29 +8804,28 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `z` coordinates are passed, try to infer the `x` and `y` coordinates - from the :class:`~pandas.DataFrame` indices and columns or the :class:`~xarray.DataArray` + from the [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices and columns or the [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` and the `x` coordinates are ``np.arange(0, y.shape[1])``. * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using - `~ultraplot.utils.edges` or :func:`~ultraplot.utils.edges2d` if *centers* were provided. + [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html) or [edges2d](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges2d.html) if *centers* were provided. For all other methods, calculate coordinate *centers* if *edges* were provided. - * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the - `z` coordinates are `pint.Quantity`, pass the magnitude to the plotting - command. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If the `x` or `y` coordinates are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). If the + `z` coordinates are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), pass the magnitude to the plotting + command. A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). transpose : bool, default: False Whether to transpose the input data. This should be used when passing datasets with column-major dimension order ``(x, y)``. @@ -8871,7 +8835,7 @@ order : {'C', 'F'}, default: 'C' row-major ordering (equivalent to ``transpose=False``). ``'F'`` corresponds to Fortran-style column-major ordering (equivalent to ``transpose=True``). globe : bool, default: False - For `ultraplot.axes.GeoAxes` only. Whether to enforce global + For [ultraplot.axes.GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.GeoAxes.html) only. Whether to enforce global coverage. When set to ``True`` this does the following: #. Interpolates input data to the North and South poles by setting the data @@ -8884,42 +8848,42 @@ globe : bool, default: False Other parameters ---------------- -cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` - The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor - function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization - range contains negative and positive values then :rcraw:`cmap.diverging` is used. - Otherwise :rcraw:`cmap.sequential` is used. +cmap : colormap-spec, default: [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) or [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) + The colormap specifer, passed to the [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html) constructor + function. If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization + range contains negative and positive values then [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) is used. + Otherwise [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) is used. cmap_kw : dict-like, optional - Passed to :class:`~ultraplot.constructor.Colormap`. + Passed to [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html). c, color, colors : color-spec or sequence of color-spec, optional - The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + The color(s) used to create a [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html). If not passed, `cmap` is used. -norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` - The data value normalizer, passed to the `~ultraplot.constructor.Norm` +norm : norm-spec, default: [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) or [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) + The data value normalizer, passed to the [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html) constructor function. If `discrete` is ``True`` then 1) this affects the default level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and - 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they - are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). - If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains - negative and positive values then `~ultraplot.colors.DivergingNorm` is used. - Otherwise `~matplotlib.colors.Normalize` is used. + 2) this is passed to [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) to scale the colors before they + are discretized (if `norm` is not already a [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html)). + If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization range contains + negative and positive values then [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) is used. + Otherwise [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) is used. norm_kw : dict-like, optional - Passed to `~ultraplot.constructor.Norm`. + Passed to [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html). extend : {'neither', 'both', 'min', 'max'}, default: 'neither' Direction for drawing colorbar "extensions" indicating out-of-bounds data on the end of the colorbar. -discrete : bool, default: :rc:`cmap.discrete` - If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the +discrete : bool, default: [cmap.discrete](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.discrete) + If ``False``, then [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) is not applied to the colormap. Instead, for non-contour plots, the number of levels will be - roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + roughly controlled by [cmap.lut](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.lut). This has a similar effect to using `levels=large_number` but it may improve rendering speed. Default is - ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` - and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. + ``True`` only for contouring commands like [contourf](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.contourf) + and pseudocolor commands like [pcolor](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.pcolor). sequential, diverging, cyclic, qualitative : bool, default: None Boolean arguments used if `cmap` is not passed. Set these to ``True`` - to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, - :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. - The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + to use the default [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential), [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging), + [cmap.cyclic](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.cyclic), and [cmap.qualitative](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.qualitative) colormaps. + The `diverging` option also applies [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) as the default continuous normalizer. vmin, vmax : float, optional The minimum and maximum color scale values used with the `norm` normalizer. @@ -8932,7 +8896,7 @@ vmin, vmax : float, optional `vmin` and `vmax` are the minimum and maximum of the data values. N Shorthand for `levels`. -levels : int or sequence of float, default: :rc:`cmap.levels` +levels : int or sequence of float, default: [cmap.levels](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.levels) The number of level edges or a sequence of level edges. If the former, `locator` is used to generate this many level edges at "nice" intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing @@ -8940,31 +8904,31 @@ levels : int or sequence of float, default: :rc:`cmap.levels` values : int or sequence of float, default: None The number of level centers or a sequence of level centers. If the former, `locator` is used to generate this many level centers at "nice" intervals. - If the latter, levels are inferred using `~ultraplot.utils.edges`. + If the latter, levels are inferred using [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html). This will override any `levels` input. center_levels : bool, default False If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented. -robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` +robust : bool, float, or 2-tuple, default: [cmap.robust](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.robust) If ``True`` and `vmin` or `vmax` were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers. -inbounds : bool, default: :rc:`cmap.inbounds` +inbounds : bool, default: [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) If ``True`` and `vmin` or `vmax` were not provided, when axis limits - have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` - or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. - See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. -locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + have been explicitly restricted with [set_xlim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlim.html) + or [set_ylim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylim.html), out-of-bounds data is ignored. + See also [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) and [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds). +locator : locator-spec, default: [matplotlib.ticker.MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) The locator used to determine level locations if `levels` or `values` were not - already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. - Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. + already passed as lists. Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. + Default is [MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) with `levels` integer levels. locator_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Locator` class. + Keyword arguments passed to [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. symmetric : bool, default: False If ``True``, the normalization range or discrete colormap levels are symmetric about zero. @@ -8976,13 +8940,13 @@ negative : bool, default: False negative with a minimum at zero. nozero : bool, default: False If ``True``, ``0`` is removed from the level list. This is mainly useful for - single-color `~matplotlib.axes.Axes.contour` plots. -linewidths : unit-spec, default: 0.3 or :rc:`lines.linewidth` + single-color [contour](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.contour.html) plots. +linewidths : unit-spec, default: 0.3 or [lines.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.linewidth) The width of the line contours. Default is ``0.3`` when adding to filled contours - or :rc:`lines.linewidth` otherwise. Aliases: ``lw``, ``linewidth``. If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -linestyles : str, default: '-' or :rc:`contour.negative_linestyle` + or [lines.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.linewidth) otherwise. Aliases: ``lw``, ``linewidth``. If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +linestyles : str, default: '-' or [contour.negative_linestyle](https://ultraplot.readthedocs.io/en/stable/search.html?q=contour.negative_linestyle) The style of the line contours. Default is ``'-'`` for positive contours and - :rcraw:`contour.negative_linestyle` for negative contours. Aliases: ``ls``, ``linestyle``. + [contour.negative_linestyle](https://ultraplot.readthedocs.io/en/stable/search.html?q=contour.negative_linestyle) for negative contours. Aliases: ``ls``, ``linestyle``. edgecolors : color-spec, default: 'k' or inferred The color of the line contours. Default is ``'k'`` when adding to filled contours or inferred from `color` or `cmap` otherwise. Aliases: ``ec``, ``edgecolor``. @@ -8991,42 +8955,42 @@ alpha : float, optional label : str, optional The legend label to be used for this object. In the case of contours, this is paired with the the central artist in the artist - list returned by `matplotlib.contour.ContourSet.legend_elements`. + list returned by [matplotlib.contour.ContourSet.legend_elements](https://matplotlib.org/stable/api/_as_gen/matplotlib.contour.ContourSet.legend_elements.html). labels : bool, optional Whether to apply labels to contours and grid boxes. The text will be white when the luminance of the underlying filled contour or grid box is less than 50 and black otherwise. labels_kw : dict-like, optional Ignored if `labels` is ``False``. Extra keyword args for the labels. - For contour plots, this is passed to `~matplotlib.axes.Axes.clabel`. - Otherwise, this is passed to `~matplotlib.axes.Axes.text`. + For contour plots, this is passed to [clabel](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.clabel.html). + Otherwise, this is passed to [text](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.text.html). formatter, fmt : formatter-spec, optional - The `~matplotlib.ticker.Formatter` used to format number labels. - Passed to the `~ultraplot.constructor.Formatter` constructor. + The [Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) used to format number labels. + Passed to the [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html) constructor. formatter_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Formatter` class. + Keyword arguments passed to [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) class. precision : int, optional The maximum number of decimal places for number labels generated - with the default formatter `~ultraplot.ticker.Simpleformatter`. + with the default formatter [Simpleformatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.Simpleformatter.html). colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `matplotlib.axes.Axes.contour`. + Passed to [matplotlib.axes.Axes.contour](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.contour.html). See also -------- @@ -9057,7 +9021,7 @@ X, Y : array-like, optional The coordinates of the values in *Z*. *X* and *Y* must both be 2D with the same shape as *Z* (e.g. - created via `numpy.meshgrid`), or they must both be 1-D such + created via [numpy.meshgrid](https://numpy.org/doc/stable/reference/generated/numpy.meshgrid.html)), or they must both be 1-D such that ``len(X) == N`` is the number of columns in *Z* and ``len(Y) == M`` is the number of rows in *Z*. @@ -9073,7 +9037,7 @@ Z : (M, N) array-like levels : int or array-like, optional Determines the number and positions of the contour lines / regions. - If an int *n*, use `~matplotlib.ticker.MaxNLocator`, which tries + If an int *n*, use [MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html), which tries to automatically choose no more than *n+1* "nice" contour levels between minimum and maximum numeric values of *Z*. @@ -9086,14 +9050,14 @@ Returns Other Parameters ---------------- -corner_mask : bool, default: :rc:`contour.corner_mask` +corner_mask : bool, default: [contour.corner_mask](https://ultraplot.readthedocs.io/en/stable/search.html?q=contour.corner_mask) Enable/disable corner masking, which only has an effect if *Z* is a masked array. If ``False``, any quad touching a masked point is masked out. If ``True``, only the triangular corners of quads nearest those points are always masked out, other triangular corners comprising three unmasked points are contoured as usual. -colors : :mpltype:`color` or list of :mpltype:`color`, optional +colors : [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color), optional The colors of the levels, i.e. the lines for `.contour` and the areas for `.contourf`. @@ -9113,13 +9077,13 @@ colors : :mpltype:`color` or list of :mpltype:`color`, optional alpha : float, default: 1 The alpha blending value, between 0 (transparent) and 1 (opaque). -cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap` +cmap : str or [Colormap](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Colormap.html), default: [image.cmap](https://ultraplot.readthedocs.io/en/stable/search.html?q=image.cmap) The Colormap instance or registered colormap name used to map scalar data to colors. This parameter is ignored if *colors* is set. -norm : str or `~matplotlib.colors.Normalize`, optional +norm : str or [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html), optional The normalization method used to scale scalar data to the [0, 1] range before mapping to colors using *cmap*. By default, a linear scaling is used, mapping the lowest value to 0 and the highest to 1. @@ -9127,9 +9091,9 @@ norm : str or `~matplotlib.colors.Normalize`, optional If given, this can be one of the following: - An instance of `.Normalize` or one of its subclasses - (see :ref:`colormapnorms`). + (see [colormapnorms](https://ultraplot.readthedocs.io/en/stable/search.html?q=colormapnorms)). - A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For a - list of available scales, call `matplotlib.scale.get_scale_names()`. + list of available scales, call [matplotlib.scale.get_scale_names()](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.get_scale_names().html). In that case, a suitable `.Normalize` subclass is dynamically generated and instantiated. @@ -9147,7 +9111,7 @@ vmin, vmax : float, optional This parameter is ignored if *colors* is set. -colorizer : `~matplotlib.colorizer.Colorizer` or None, default: None +colorizer : [Colorizer](https://matplotlib.org/stable/api/_as_gen/matplotlib.colorizer.Colorizer.html) or None, default: None The Colorizer object used to map color to data. If None, a Colorizer object is created from a *norm* and *cmap*. @@ -9162,7 +9126,7 @@ origin : {*None*, 'upper', 'lower', 'image'}, default: None - 'lower': ``Z[0, 0]`` is at X=0.5, Y=0.5 in the lower left corner. - 'upper': ``Z[0, 0]`` is at X=N+0.5, Y=0.5 in the upper left corner. - - 'image': Use the value from :rc:`image.origin`. + - 'image': Use the value from [image.origin](https://ultraplot.readthedocs.io/en/stable/search.html?q=image.origin). extent : (x0, x1, y0, y1), optional If *origin* is not *None*, then *extent* is interpreted as in @@ -9217,12 +9181,12 @@ extend : {'neither', 'both', 'min', 'max'}, default: 'neither' xunits, yunits : registered units, optional Override axis units by specifying an instance of a - :class:`matplotlib.units.ConversionInterface`. + [matplotlib.units.ConversionInterface](https://matplotlib.org/stable/api/_as_gen/matplotlib.units.ConversionInterface.html). antialiased : bool, optional Enable antialiasing, overriding the defaults. For filled contours, the default is *False*. For line contours, - it is taken from :rc:`lines.antialiased`. + it is taken from [lines.antialiased](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.antialiased). nchunk : int >= 0, optional If 0, no subdivision of the domain. Specify a positive integer to @@ -9233,7 +9197,7 @@ nchunk : int >= 0, optional however introduce rendering artifacts at chunk boundaries depending on the backend, the *antialiased* flag and value of *alpha*. -linewidths : float or array-like, default: :rc:`contour.linewidth` +linewidths : float or array-like, default: [contour.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=contour.linewidth) *Only applies to* `.contour`. The line width of the contour lines. @@ -9243,7 +9207,7 @@ linewidths : float or array-like, default: :rc:`contour.linewidth` If a sequence, the levels in ascending order will be plotted with the linewidths in the order specified. - If None, this falls back to :rc:`lines.linewidth`. + If None, this falls back to [lines.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.linewidth). linestyles : {*None*, 'solid', 'dashed', 'dashdot', 'dotted'}, optional *Only applies to* `.contour`. @@ -9263,7 +9227,7 @@ negative_linestyles : {*None*, 'solid', 'dashed', 'dashdot', 'dotted'}, specifies the line style for negative contours. If *negative_linestyles* is *None*, the default is taken from - :rc:`contour.negative_linestyle`. + [contour.negative_linestyle](https://ultraplot.readthedocs.io/en/stable/search.html?q=contour.negative_linestyle). *negative_linestyles* can also be an iterable of the above strings specifying a set of linestyles to be used. If this iterable is shorter than @@ -9278,14 +9242,14 @@ hatches : list[str], optional algorithm : {'mpl2005', 'mpl2014', 'serial', 'threaded'}, optional Which contouring algorithm to use to calculate the contour lines and polygons. The algorithms are implemented in - `ContourPy `_, consult the - `ContourPy documentation `_ for + [ContourPy](https://github.com/contourpy/contourpy), consult the + [ContourPy documentation](https://contourpy.readthedocs.io) for further information. - The default is taken from :rc:`contour.algorithm`. + The default is taken from [contour.algorithm](https://ultraplot.readthedocs.io/en/stable/search.html?q=contour.algorithm). -clip_path : `~matplotlib.patches.Patch` or `.Path` or `.TransformedPath` - Set the clip path. See `~matplotlib.artist.Artist.set_clip_path`. +clip_path : [Patch](https://matplotlib.org/stable/api/_as_gen/matplotlib.patches.Patch.html) or `.Path` or `.TransformedPath` + Set the clip path. See [set_clip_path](https://matplotlib.org/stable/api/_as_gen/matplotlib.artist.Artist.set_clip_path.html). .. versionadded:: 3.8 @@ -9307,10 +9271,9 @@ Notes except for the lowest interval, which is closed on both sides (i.e. it includes the lowest value). -3. `.contour` and `.contourf` use a `marching squares - `_ algorithm to +3. `.contour` and `.contourf` use a [marching squares](https://en.wikipedia.org/wiki/Marching_squares) algorithm to compute contour locations. More information can be found in - `ContourPy documentation `_.""" + [ContourPy documentation](https://contourpy.readthedocs.io).""" ... def contourf(self, x: Incomplete, y: Incomplete, z: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -9322,29 +9285,28 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `z` coordinates are passed, try to infer the `x` and `y` coordinates - from the :class:`~pandas.DataFrame` indices and columns or the :class:`~xarray.DataArray` + from the [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices and columns or the [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` and the `x` coordinates are ``np.arange(0, y.shape[1])``. * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using - `~ultraplot.utils.edges` or :func:`~ultraplot.utils.edges2d` if *centers* were provided. + [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html) or [edges2d](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges2d.html) if *centers* were provided. For all other methods, calculate coordinate *centers* if *edges* were provided. - * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the - `z` coordinates are `pint.Quantity`, pass the magnitude to the plotting - command. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If the `x` or `y` coordinates are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). If the + `z` coordinates are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), pass the magnitude to the plotting + command. A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). transpose : bool, default: False Whether to transpose the input data. This should be used when passing datasets with column-major dimension order ``(x, y)``. @@ -9354,7 +9316,7 @@ order : {'C', 'F'}, default: 'C' row-major ordering (equivalent to ``transpose=False``). ``'F'`` corresponds to Fortran-style column-major ordering (equivalent to ``transpose=True``). globe : bool, default: False - For `ultraplot.axes.GeoAxes` only. Whether to enforce global + For [ultraplot.axes.GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.GeoAxes.html) only. Whether to enforce global coverage. When set to ``True`` this does the following: #. Interpolates input data to the North and South poles by setting the data @@ -9367,42 +9329,42 @@ globe : bool, default: False Other parameters ---------------- -cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` - The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor - function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization - range contains negative and positive values then :rcraw:`cmap.diverging` is used. - Otherwise :rcraw:`cmap.sequential` is used. +cmap : colormap-spec, default: [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) or [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) + The colormap specifer, passed to the [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html) constructor + function. If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization + range contains negative and positive values then [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) is used. + Otherwise [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) is used. cmap_kw : dict-like, optional - Passed to :class:`~ultraplot.constructor.Colormap`. + Passed to [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html). c, color, colors : color-spec or sequence of color-spec, optional - The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + The color(s) used to create a [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html). If not passed, `cmap` is used. -norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` - The data value normalizer, passed to the `~ultraplot.constructor.Norm` +norm : norm-spec, default: [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) or [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) + The data value normalizer, passed to the [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html) constructor function. If `discrete` is ``True`` then 1) this affects the default level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and - 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they - are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). - If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains - negative and positive values then `~ultraplot.colors.DivergingNorm` is used. - Otherwise `~matplotlib.colors.Normalize` is used. + 2) this is passed to [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) to scale the colors before they + are discretized (if `norm` is not already a [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html)). + If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization range contains + negative and positive values then [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) is used. + Otherwise [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) is used. norm_kw : dict-like, optional - Passed to `~ultraplot.constructor.Norm`. + Passed to [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html). extend : {'neither', 'both', 'min', 'max'}, default: 'neither' Direction for drawing colorbar "extensions" indicating out-of-bounds data on the end of the colorbar. -discrete : bool, default: :rc:`cmap.discrete` - If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the +discrete : bool, default: [cmap.discrete](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.discrete) + If ``False``, then [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) is not applied to the colormap. Instead, for non-contour plots, the number of levels will be - roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + roughly controlled by [cmap.lut](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.lut). This has a similar effect to using `levels=large_number` but it may improve rendering speed. Default is - ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` - and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. + ``True`` only for contouring commands like [contourf](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.contourf) + and pseudocolor commands like [pcolor](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.pcolor). sequential, diverging, cyclic, qualitative : bool, default: None Boolean arguments used if `cmap` is not passed. Set these to ``True`` - to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, - :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. - The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + to use the default [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential), [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging), + [cmap.cyclic](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.cyclic), and [cmap.qualitative](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.qualitative) colormaps. + The `diverging` option also applies [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) as the default continuous normalizer. vmin, vmax : float, optional The minimum and maximum color scale values used with the `norm` normalizer. @@ -9415,7 +9377,7 @@ vmin, vmax : float, optional `vmin` and `vmax` are the minimum and maximum of the data values. N Shorthand for `levels`. -levels : int or sequence of float, default: :rc:`cmap.levels` +levels : int or sequence of float, default: [cmap.levels](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.levels) The number of level edges or a sequence of level edges. If the former, `locator` is used to generate this many level edges at "nice" intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing @@ -9423,31 +9385,31 @@ levels : int or sequence of float, default: :rc:`cmap.levels` values : int or sequence of float, default: None The number of level centers or a sequence of level centers. If the former, `locator` is used to generate this many level centers at "nice" intervals. - If the latter, levels are inferred using `~ultraplot.utils.edges`. + If the latter, levels are inferred using [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html). This will override any `levels` input. center_levels : bool, default False If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented. -robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` +robust : bool, float, or 2-tuple, default: [cmap.robust](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.robust) If ``True`` and `vmin` or `vmax` were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers. -inbounds : bool, default: :rc:`cmap.inbounds` +inbounds : bool, default: [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) If ``True`` and `vmin` or `vmax` were not provided, when axis limits - have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` - or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. - See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. -locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + have been explicitly restricted with [set_xlim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlim.html) + or [set_ylim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylim.html), out-of-bounds data is ignored. + See also [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) and [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds). +locator : locator-spec, default: [matplotlib.ticker.MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) The locator used to determine level locations if `levels` or `values` were not - already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. - Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. + already passed as lists. Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. + Default is [MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) with `levels` integer levels. locator_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Locator` class. + Keyword arguments passed to [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. symmetric : bool, default: False If ``True``, the normalization range or discrete colormap levels are symmetric about zero. @@ -9459,21 +9421,21 @@ negative : bool, default: False negative with a minimum at zero. nozero : bool, default: False If ``True``, ``0`` is removed from the level list. This is mainly useful for - single-color `~matplotlib.axes.Axes.contour` plots. -linewidths : unit-spec, default: 0.3 or :rc:`lines.linewidth` + single-color [contour](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.contour.html) plots. +linewidths : unit-spec, default: 0.3 or [lines.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.linewidth) The width of the line contours. Default is ``0.3`` when adding to filled contours - or :rc:`lines.linewidth` otherwise. Aliases: ``lw``, ``linewidth``. If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -linestyles : str, default: '-' or :rc:`contour.negative_linestyle` + or [lines.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.linewidth) otherwise. Aliases: ``lw``, ``linewidth``. If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +linestyles : str, default: '-' or [contour.negative_linestyle](https://ultraplot.readthedocs.io/en/stable/search.html?q=contour.negative_linestyle) The style of the line contours. Default is ``'-'`` for positive contours and - :rcraw:`contour.negative_linestyle` for negative contours. Aliases: ``ls``, ``linestyle``. + [contour.negative_linestyle](https://ultraplot.readthedocs.io/en/stable/search.html?q=contour.negative_linestyle) for negative contours. Aliases: ``ls``, ``linestyle``. edgecolors : color-spec, default: 'k' or inferred The color of the line contours. Default is ``'k'`` when adding to filled contours or inferred from `color` or `cmap` otherwise. Aliases: ``ec``, ``edgecolor``. alpha : float, optional - The opacity of the contours. Inferred from `edgecolors` by default. Aliases: ``a``, ``alphas``.edgefix : bool or float, default: :rc:`edgefix` + The opacity of the contours. Inferred from `edgecolors` by default. Aliases: ``a``, ``alphas``.edgefix : bool or float, default: [edgefix](https://ultraplot.readthedocs.io/en/stable/search.html?q=edgefix) Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). - See this `github repo `__ for a + See this [github repo](https://github.com/jklymak/contourfIssues) for a demonstration of the problem. If ``True``, a small default linewidth of ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), this specific linewidth is used to cover up the white lines. This feature is @@ -9482,42 +9444,42 @@ alpha : float, optional label : str, optional The legend label to be used for this object. In the case of contours, this is paired with the the central artist in the artist - list returned by `matplotlib.contour.ContourSet.legend_elements`. + list returned by [matplotlib.contour.ContourSet.legend_elements](https://matplotlib.org/stable/api/_as_gen/matplotlib.contour.ContourSet.legend_elements.html). labels : bool, optional Whether to apply labels to contours and grid boxes. The text will be white when the luminance of the underlying filled contour or grid box is less than 50 and black otherwise. labels_kw : dict-like, optional Ignored if `labels` is ``False``. Extra keyword args for the labels. - For contour plots, this is passed to `~matplotlib.axes.Axes.clabel`. - Otherwise, this is passed to `~matplotlib.axes.Axes.text`. + For contour plots, this is passed to [clabel](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.clabel.html). + Otherwise, this is passed to [text](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.text.html). formatter, fmt : formatter-spec, optional - The `~matplotlib.ticker.Formatter` used to format number labels. - Passed to the `~ultraplot.constructor.Formatter` constructor. + The [Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) used to format number labels. + Passed to the [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html) constructor. formatter_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Formatter` class. + Keyword arguments passed to [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) class. precision : int, optional The maximum number of decimal places for number labels generated - with the default formatter `~ultraplot.ticker.Simpleformatter`. + with the default formatter [Simpleformatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.Simpleformatter.html). colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `matplotlib.axes.Axes.contourf`. + Passed to [matplotlib.axes.Axes.contourf](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.contourf.html). See also -------- @@ -9548,7 +9510,7 @@ X, Y : array-like, optional The coordinates of the values in *Z*. *X* and *Y* must both be 2D with the same shape as *Z* (e.g. - created via `numpy.meshgrid`), or they must both be 1-D such + created via [numpy.meshgrid](https://numpy.org/doc/stable/reference/generated/numpy.meshgrid.html)), or they must both be 1-D such that ``len(X) == N`` is the number of columns in *Z* and ``len(Y) == M`` is the number of rows in *Z*. @@ -9564,7 +9526,7 @@ Z : (M, N) array-like levels : int or array-like, optional Determines the number and positions of the contour lines / regions. - If an int *n*, use `~matplotlib.ticker.MaxNLocator`, which tries + If an int *n*, use [MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html), which tries to automatically choose no more than *n+1* "nice" contour levels between minimum and maximum numeric values of *Z*. @@ -9577,14 +9539,14 @@ Returns Other Parameters ---------------- -corner_mask : bool, default: :rc:`contour.corner_mask` +corner_mask : bool, default: [contour.corner_mask](https://ultraplot.readthedocs.io/en/stable/search.html?q=contour.corner_mask) Enable/disable corner masking, which only has an effect if *Z* is a masked array. If ``False``, any quad touching a masked point is masked out. If ``True``, only the triangular corners of quads nearest those points are always masked out, other triangular corners comprising three unmasked points are contoured as usual. -colors : :mpltype:`color` or list of :mpltype:`color`, optional +colors : [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color), optional The colors of the levels, i.e. the lines for `.contour` and the areas for `.contourf`. @@ -9604,13 +9566,13 @@ colors : :mpltype:`color` or list of :mpltype:`color`, optional alpha : float, default: 1 The alpha blending value, between 0 (transparent) and 1 (opaque). -cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap` +cmap : str or [Colormap](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Colormap.html), default: [image.cmap](https://ultraplot.readthedocs.io/en/stable/search.html?q=image.cmap) The Colormap instance or registered colormap name used to map scalar data to colors. This parameter is ignored if *colors* is set. -norm : str or `~matplotlib.colors.Normalize`, optional +norm : str or [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html), optional The normalization method used to scale scalar data to the [0, 1] range before mapping to colors using *cmap*. By default, a linear scaling is used, mapping the lowest value to 0 and the highest to 1. @@ -9618,9 +9580,9 @@ norm : str or `~matplotlib.colors.Normalize`, optional If given, this can be one of the following: - An instance of `.Normalize` or one of its subclasses - (see :ref:`colormapnorms`). + (see [colormapnorms](https://ultraplot.readthedocs.io/en/stable/search.html?q=colormapnorms)). - A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For a - list of available scales, call `matplotlib.scale.get_scale_names()`. + list of available scales, call [matplotlib.scale.get_scale_names()](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.get_scale_names().html). In that case, a suitable `.Normalize` subclass is dynamically generated and instantiated. @@ -9638,7 +9600,7 @@ vmin, vmax : float, optional This parameter is ignored if *colors* is set. -colorizer : `~matplotlib.colorizer.Colorizer` or None, default: None +colorizer : [Colorizer](https://matplotlib.org/stable/api/_as_gen/matplotlib.colorizer.Colorizer.html) or None, default: None The Colorizer object used to map color to data. If None, a Colorizer object is created from a *norm* and *cmap*. @@ -9653,7 +9615,7 @@ origin : {*None*, 'upper', 'lower', 'image'}, default: None - 'lower': ``Z[0, 0]`` is at X=0.5, Y=0.5 in the lower left corner. - 'upper': ``Z[0, 0]`` is at X=N+0.5, Y=0.5 in the upper left corner. - - 'image': Use the value from :rc:`image.origin`. + - 'image': Use the value from [image.origin](https://ultraplot.readthedocs.io/en/stable/search.html?q=image.origin). extent : (x0, x1, y0, y1), optional If *origin* is not *None*, then *extent* is interpreted as in @@ -9708,12 +9670,12 @@ extend : {'neither', 'both', 'min', 'max'}, default: 'neither' xunits, yunits : registered units, optional Override axis units by specifying an instance of a - :class:`matplotlib.units.ConversionInterface`. + [matplotlib.units.ConversionInterface](https://matplotlib.org/stable/api/_as_gen/matplotlib.units.ConversionInterface.html). antialiased : bool, optional Enable antialiasing, overriding the defaults. For filled contours, the default is *False*. For line contours, - it is taken from :rc:`lines.antialiased`. + it is taken from [lines.antialiased](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.antialiased). nchunk : int >= 0, optional If 0, no subdivision of the domain. Specify a positive integer to @@ -9724,7 +9686,7 @@ nchunk : int >= 0, optional however introduce rendering artifacts at chunk boundaries depending on the backend, the *antialiased* flag and value of *alpha*. -linewidths : float or array-like, default: :rc:`contour.linewidth` +linewidths : float or array-like, default: [contour.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=contour.linewidth) *Only applies to* `.contour`. The line width of the contour lines. @@ -9734,7 +9696,7 @@ linewidths : float or array-like, default: :rc:`contour.linewidth` If a sequence, the levels in ascending order will be plotted with the linewidths in the order specified. - If None, this falls back to :rc:`lines.linewidth`. + If None, this falls back to [lines.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.linewidth). linestyles : {*None*, 'solid', 'dashed', 'dashdot', 'dotted'}, optional *Only applies to* `.contour`. @@ -9754,7 +9716,7 @@ negative_linestyles : {*None*, 'solid', 'dashed', 'dashdot', 'dotted'}, specifies the line style for negative contours. If *negative_linestyles* is *None*, the default is taken from - :rc:`contour.negative_linestyle`. + [contour.negative_linestyle](https://ultraplot.readthedocs.io/en/stable/search.html?q=contour.negative_linestyle). *negative_linestyles* can also be an iterable of the above strings specifying a set of linestyles to be used. If this iterable is shorter than @@ -9769,14 +9731,14 @@ hatches : list[str], optional algorithm : {'mpl2005', 'mpl2014', 'serial', 'threaded'}, optional Which contouring algorithm to use to calculate the contour lines and polygons. The algorithms are implemented in - `ContourPy `_, consult the - `ContourPy documentation `_ for + [ContourPy](https://github.com/contourpy/contourpy), consult the + [ContourPy documentation](https://contourpy.readthedocs.io) for further information. - The default is taken from :rc:`contour.algorithm`. + The default is taken from [contour.algorithm](https://ultraplot.readthedocs.io/en/stable/search.html?q=contour.algorithm). -clip_path : `~matplotlib.patches.Patch` or `.Path` or `.TransformedPath` - Set the clip path. See `~matplotlib.artist.Artist.set_clip_path`. +clip_path : [Patch](https://matplotlib.org/stable/api/_as_gen/matplotlib.patches.Patch.html) or `.Path` or `.TransformedPath` + Set the clip path. See [set_clip_path](https://matplotlib.org/stable/api/_as_gen/matplotlib.artist.Artist.set_clip_path.html). .. versionadded:: 3.8 @@ -9798,10 +9760,9 @@ Notes except for the lowest interval, which is closed on both sides (i.e. it includes the lowest value). -3. `.contour` and `.contourf` use a `marching squares - `_ algorithm to +3. `.contour` and `.contourf` use a [marching squares](https://en.wikipedia.org/wiki/Marching_squares) algorithm to compute contour locations. More information can be found in - `ContourPy documentation `_.""" + [ContourPy documentation](https://contourpy.readthedocs.io).""" ... def pcolor(self, x: Incomplete, y: Incomplete, z: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -9813,29 +9774,28 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `z` coordinates are passed, try to infer the `x` and `y` coordinates - from the :class:`~pandas.DataFrame` indices and columns or the :class:`~xarray.DataArray` + from the [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices and columns or the [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` and the `x` coordinates are ``np.arange(0, y.shape[1])``. * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using - `~ultraplot.utils.edges` or :func:`~ultraplot.utils.edges2d` if *centers* were provided. + [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html) or [edges2d](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges2d.html) if *centers* were provided. For all other methods, calculate coordinate *centers* if *edges* were provided. - * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the - `z` coordinates are `pint.Quantity`, pass the magnitude to the plotting - command. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If the `x` or `y` coordinates are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). If the + `z` coordinates are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), pass the magnitude to the plotting + command. A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). transpose : bool, default: False Whether to transpose the input data. This should be used when passing datasets with column-major dimension order ``(x, y)``. @@ -9845,7 +9805,7 @@ order : {'C', 'F'}, default: 'C' row-major ordering (equivalent to ``transpose=False``). ``'F'`` corresponds to Fortran-style column-major ordering (equivalent to ``transpose=True``). globe : bool, default: False - For `ultraplot.axes.GeoAxes` only. Whether to enforce global + For [ultraplot.axes.GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.GeoAxes.html) only. Whether to enforce global coverage. When set to ``True`` this does the following: #. Interpolates input data to the North and South poles by setting the data @@ -9858,42 +9818,42 @@ globe : bool, default: False Other parameters ---------------- -cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` - The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor - function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization - range contains negative and positive values then :rcraw:`cmap.diverging` is used. - Otherwise :rcraw:`cmap.sequential` is used. +cmap : colormap-spec, default: [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) or [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) + The colormap specifer, passed to the [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html) constructor + function. If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization + range contains negative and positive values then [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) is used. + Otherwise [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) is used. cmap_kw : dict-like, optional - Passed to :class:`~ultraplot.constructor.Colormap`. + Passed to [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html). c, color, colors : color-spec or sequence of color-spec, optional - The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + The color(s) used to create a [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html). If not passed, `cmap` is used. -norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` - The data value normalizer, passed to the `~ultraplot.constructor.Norm` +norm : norm-spec, default: [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) or [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) + The data value normalizer, passed to the [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html) constructor function. If `discrete` is ``True`` then 1) this affects the default level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and - 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they - are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). - If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains - negative and positive values then `~ultraplot.colors.DivergingNorm` is used. - Otherwise `~matplotlib.colors.Normalize` is used. + 2) this is passed to [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) to scale the colors before they + are discretized (if `norm` is not already a [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html)). + If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization range contains + negative and positive values then [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) is used. + Otherwise [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) is used. norm_kw : dict-like, optional - Passed to `~ultraplot.constructor.Norm`. + Passed to [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html). extend : {'neither', 'both', 'min', 'max'}, default: 'neither' Direction for drawing colorbar "extensions" indicating out-of-bounds data on the end of the colorbar. -discrete : bool, default: :rc:`cmap.discrete` - If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the +discrete : bool, default: [cmap.discrete](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.discrete) + If ``False``, then [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) is not applied to the colormap. Instead, for non-contour plots, the number of levels will be - roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + roughly controlled by [cmap.lut](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.lut). This has a similar effect to using `levels=large_number` but it may improve rendering speed. Default is - ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` - and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. + ``True`` only for contouring commands like [contourf](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.contourf) + and pseudocolor commands like [pcolor](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.pcolor). sequential, diverging, cyclic, qualitative : bool, default: None Boolean arguments used if `cmap` is not passed. Set these to ``True`` - to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, - :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. - The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + to use the default [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential), [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging), + [cmap.cyclic](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.cyclic), and [cmap.qualitative](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.qualitative) colormaps. + The `diverging` option also applies [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) as the default continuous normalizer. vmin, vmax : float, optional The minimum and maximum color scale values used with the `norm` normalizer. @@ -9906,7 +9866,7 @@ vmin, vmax : float, optional `vmin` and `vmax` are the minimum and maximum of the data values. N Shorthand for `levels`. -levels : int or sequence of float, default: :rc:`cmap.levels` +levels : int or sequence of float, default: [cmap.levels](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.levels) The number of level edges or a sequence of level edges. If the former, `locator` is used to generate this many level edges at "nice" intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing @@ -9914,31 +9874,31 @@ levels : int or sequence of float, default: :rc:`cmap.levels` values : int or sequence of float, default: None The number of level centers or a sequence of level centers. If the former, `locator` is used to generate this many level centers at "nice" intervals. - If the latter, levels are inferred using `~ultraplot.utils.edges`. + If the latter, levels are inferred using [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html). This will override any `levels` input. center_levels : bool, default False If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented. -robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` +robust : bool, float, or 2-tuple, default: [cmap.robust](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.robust) If ``True`` and `vmin` or `vmax` were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers. -inbounds : bool, default: :rc:`cmap.inbounds` +inbounds : bool, default: [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) If ``True`` and `vmin` or `vmax` were not provided, when axis limits - have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` - or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. - See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. -locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + have been explicitly restricted with [set_xlim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlim.html) + or [set_ylim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylim.html), out-of-bounds data is ignored. + See also [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) and [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds). +locator : locator-spec, default: [matplotlib.ticker.MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) The locator used to determine level locations if `levels` or `values` were not - already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. - Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. + already passed as lists. Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. + Default is [MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) with `levels` integer levels. locator_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Locator` class. + Keyword arguments passed to [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. symmetric : bool, default: False If ``True``, the normalization range or discrete colormap levels are symmetric about zero. @@ -9950,20 +9910,20 @@ negative : bool, default: False negative with a minimum at zero. nozero : bool, default: False If ``True``, ``0`` is removed from the level list. This is mainly useful for - single-color `~matplotlib.axes.Axes.contour` plots. + single-color [contour](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.contour.html) plots. linewidths : unit-spec, default: 0.3 The width of lines between grid boxes. Aliases: ``lw``, ``linewidth``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). linestyles : str, default: '-' The style of lines between grid boxes. Aliases: ``ls``, ``linestyle``. edgecolors : color-spec, default: 'k' The color of lines between grid boxes. Aliases: ``ec``, ``edgecolor``. alpha : float, optional The opacity of the grid boxes. Inferred from `cmap` by default. Aliases: ``a``, ``alphas``. -edgefix : bool or float, default: :rc:`edgefix` +edgefix : bool or float, default: [edgefix](https://ultraplot.readthedocs.io/en/stable/search.html?q=edgefix) Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). - See this `github repo `__ for a + See this [github repo](https://github.com/jklymak/contourfIssues) for a demonstration of the problem. If ``True``, a small default linewidth of ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), this specific linewidth is used to cover up the white lines. This feature is @@ -9971,42 +9931,42 @@ edgefix : bool or float, default: :rc:`edgefix` label : str, optional The legend label to be used for this object. In the case of contours, this is paired with the the central artist in the artist - list returned by `matplotlib.contour.ContourSet.legend_elements`. + list returned by [matplotlib.contour.ContourSet.legend_elements](https://matplotlib.org/stable/api/_as_gen/matplotlib.contour.ContourSet.legend_elements.html). labels : bool, optional Whether to apply labels to contours and grid boxes. The text will be white when the luminance of the underlying filled contour or grid box is less than 50 and black otherwise. labels_kw : dict-like, optional Ignored if `labels` is ``False``. Extra keyword args for the labels. - For contour plots, this is passed to `~matplotlib.axes.Axes.clabel`. - Otherwise, this is passed to `~matplotlib.axes.Axes.text`. + For contour plots, this is passed to [clabel](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.clabel.html). + Otherwise, this is passed to [text](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.text.html). formatter, fmt : formatter-spec, optional - The `~matplotlib.ticker.Formatter` used to format number labels. - Passed to the `~ultraplot.constructor.Formatter` constructor. + The [Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) used to format number labels. + Passed to the [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html) constructor. formatter_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Formatter` class. + Keyword arguments passed to [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) class. precision : int, optional The maximum number of decimal places for number labels generated - with the default formatter `~ultraplot.ticker.Simpleformatter`. + with the default formatter [Simpleformatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.Simpleformatter.html). colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `matplotlib.axes.Axes.pcolor`. + Passed to [matplotlib.axes.Axes.pcolor](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.pcolor.html). See also -------- @@ -10035,8 +9995,7 @@ The arguments *X*, *Y*, *C* are positional-only. ``pcolor()`` can be very slow for large arrays. In most cases you should use the similar but much faster `~.Axes.pcolormesh` instead. See - :ref:`Differences between pcolor() and pcolormesh() - ` for a discussion of the + [Differences between pcolor() and pcolormesh()](https://ultraplot.readthedocs.io/en/stable/search.html?q=differences-pcolor-pcolormesh) for a discussion of the differences. Parameters @@ -10056,7 +10015,7 @@ X, Y : array-like, optional Note that the column index corresponds to the x-coordinate, and the row index corresponds to y. For details, see the - :ref:`Notes ` section below. + [Notes](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes-pcolormesh-grid-orientation) section below. If ``shading='flat'`` the dimensions of *X* and *Y* should be one greater than those of *C*, and the quadrilateral is colored due @@ -10072,7 +10031,7 @@ X, Y : array-like, optional expanded as needed into the appropriate 2D arrays, making a rectangular grid. -shading : {'flat', 'nearest', 'auto'}, default: :rc:`pcolor.shading` +shading : {'flat', 'nearest', 'auto'}, default: [pcolor.shading](https://ultraplot.readthedocs.io/en/stable/search.html?q=pcolor.shading) The fill style for the quadrilateral. Possible values: - 'flat': A solid color is used for each quad. The color of the @@ -10087,14 +10046,14 @@ shading : {'flat', 'nearest', 'auto'}, default: :rc:`pcolor.shading` - 'auto': Choose 'flat' if dimensions of *X* and *Y* are one larger than *C*. Choose 'nearest' if dimensions are the same. - See :doc:`/gallery/images_contours_and_fields/pcolormesh_grids` + See [/gallery/images_contours_and_fields/pcolormesh_grids](https://ultraplot.readthedocs.io/en/stable/search.html?q=%2Fgallery%2Fimages_contours_and_fields%2Fpcolormesh_grids) for more description. -cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap` +cmap : str or [Colormap](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Colormap.html), default: [image.cmap](https://ultraplot.readthedocs.io/en/stable/search.html?q=image.cmap) The Colormap instance or registered colormap name used to map scalar data to colors. -norm : str or `~matplotlib.colors.Normalize`, optional +norm : str or [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html), optional The normalization method used to scale scalar data to the [0, 1] range before mapping to colors using *cmap*. By default, a linear scaling is used, mapping the lowest value to 0 and the highest to 1. @@ -10102,9 +10061,9 @@ norm : str or `~matplotlib.colors.Normalize`, optional If given, this can be one of the following: - An instance of `.Normalize` or one of its subclasses - (see :ref:`colormapnorms`). + (see [colormapnorms](https://ultraplot.readthedocs.io/en/stable/search.html?q=colormapnorms)). - A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For a - list of available scales, call `matplotlib.scale.get_scale_names()`. + list of available scales, call [matplotlib.scale.get_scale_names()](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.get_scale_names().html). In that case, a suitable `.Normalize` subclass is dynamically generated and instantiated. @@ -10115,7 +10074,7 @@ vmin, vmax : float, optional *vmin*/*vmax* when a *norm* instance is given (but using a `str` *norm* name together with *vmin*/*vmax* is acceptable). -colorizer : `~matplotlib.colorizer.Colorizer` or None, default: None +colorizer : [Colorizer](https://matplotlib.org/stable/api/_as_gen/matplotlib.colorizer.Colorizer.html) or None, default: None The Colorizer object used to map color to data. If None, a Colorizer object is created from a *norm* and *cmap*. @@ -10123,8 +10082,8 @@ edgecolors : {'none', None, 'face', color, color sequence}, optional The color of the edges. Defaults to 'none'. Possible values: - 'none' or '': No edge. - - *None*: :rc:`patch.edgecolor` will be used. Note that currently - :rc:`patch.force_edgecolor` has to be True for this to work. + - *None*: [patch.edgecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.edgecolor) will be used. Note that currently + [patch.force_edgecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.force_edgecolor) has to be True for this to work. - 'face': Use the adjacent face color. - A color or sequence of colors will set the edge color. @@ -10140,7 +10099,7 @@ snap : bool, default: False Returns ------- -`matplotlib.collections.PolyQuadMesh` +[matplotlib.collections.PolyQuadMesh](https://matplotlib.org/stable/api/_as_gen/matplotlib.collections.PolyQuadMesh.html) Other Parameters ---------------- @@ -10149,7 +10108,7 @@ antialiaseds : bool, default: False *edgecolors*\\ ="none" is used. This eliminates artificial lines at patch boundaries, and works regardless of the value of alpha. If *edgecolors* is not "none", then the default *antialiaseds* - is taken from :rc:`patch.antialiased`. + is taken from [patch.antialiased](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.antialiased). Stroking the edges may be preferred if *alpha* is 1, but will cause artifacts otherwise. @@ -10159,7 +10118,7 @@ data : indexable object, optional **kwargs Additionally, the following arguments are allowed. They are passed - along to the `~matplotlib.collections.PolyQuadMesh` constructor: + along to the [PolyQuadMesh](https://matplotlib.org/stable/api/_as_gen/matplotlib.collections.PolyQuadMesh.html) constructor: Properties: agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image @@ -10169,14 +10128,14 @@ Properties: array: array-like or None capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} clim: (vmin: float, vmax: float) - clip_box: `~matplotlib.transforms.BboxBase` or None + clip_box: [BboxBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.BboxBase.html) or None clip_on: bool clip_path: Patch or (Path, Transform) or None cmap: `.Colormap` or str or None - color: :mpltype:`color` or list of RGBA tuples - edgecolor or ec or edgecolors: :mpltype:`color` or list of :mpltype:`color` or 'face' - facecolor or facecolors or fc: :mpltype:`color` or list of :mpltype:`color` - figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + color: [color](https://matplotlib.org/stable/search.html?q=color) or list of RGBA tuples + edgecolor or ec or edgecolors: [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color) or 'face' + facecolor or facecolors or fc: [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color) + figure: [Figure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html) or [SubFigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.SubFigure.html) gid: str hatch: {'/', '\\\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'} hatch_linewidth: unknown @@ -10194,10 +10153,10 @@ Properties: picker: None or bool or float or callable pickradius: float rasterized: bool - sizes: `numpy.ndarray` or None + sizes: [numpy.ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html) or None sketch_params: (scale: float, length: float, randomness: float) snap: bool or None - transform: `~matplotlib.transforms.Transform` + transform: [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html) url: str urls: list of str or None verts: list of array-like @@ -10239,29 +10198,28 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `z` coordinates are passed, try to infer the `x` and `y` coordinates - from the :class:`~pandas.DataFrame` indices and columns or the :class:`~xarray.DataArray` + from the [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices and columns or the [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` and the `x` coordinates are ``np.arange(0, y.shape[1])``. * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using - `~ultraplot.utils.edges` or :func:`~ultraplot.utils.edges2d` if *centers* were provided. + [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html) or [edges2d](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges2d.html) if *centers* were provided. For all other methods, calculate coordinate *centers* if *edges* were provided. - * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the - `z` coordinates are `pint.Quantity`, pass the magnitude to the plotting - command. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If the `x` or `y` coordinates are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). If the + `z` coordinates are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), pass the magnitude to the plotting + command. A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). transpose : bool, default: False Whether to transpose the input data. This should be used when passing datasets with column-major dimension order ``(x, y)``. @@ -10271,7 +10229,7 @@ order : {'C', 'F'}, default: 'C' row-major ordering (equivalent to ``transpose=False``). ``'F'`` corresponds to Fortran-style column-major ordering (equivalent to ``transpose=True``). globe : bool, default: False - For `ultraplot.axes.GeoAxes` only. Whether to enforce global + For [ultraplot.axes.GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.GeoAxes.html) only. Whether to enforce global coverage. When set to ``True`` this does the following: #. Interpolates input data to the North and South poles by setting the data @@ -10284,42 +10242,42 @@ globe : bool, default: False Other parameters ---------------- -cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` - The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor - function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization - range contains negative and positive values then :rcraw:`cmap.diverging` is used. - Otherwise :rcraw:`cmap.sequential` is used. +cmap : colormap-spec, default: [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) or [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) + The colormap specifer, passed to the [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html) constructor + function. If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization + range contains negative and positive values then [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) is used. + Otherwise [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) is used. cmap_kw : dict-like, optional - Passed to :class:`~ultraplot.constructor.Colormap`. + Passed to [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html). c, color, colors : color-spec or sequence of color-spec, optional - The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + The color(s) used to create a [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html). If not passed, `cmap` is used. -norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` - The data value normalizer, passed to the `~ultraplot.constructor.Norm` +norm : norm-spec, default: [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) or [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) + The data value normalizer, passed to the [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html) constructor function. If `discrete` is ``True`` then 1) this affects the default level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and - 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they - are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). - If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains - negative and positive values then `~ultraplot.colors.DivergingNorm` is used. - Otherwise `~matplotlib.colors.Normalize` is used. + 2) this is passed to [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) to scale the colors before they + are discretized (if `norm` is not already a [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html)). + If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization range contains + negative and positive values then [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) is used. + Otherwise [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) is used. norm_kw : dict-like, optional - Passed to `~ultraplot.constructor.Norm`. + Passed to [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html). extend : {'neither', 'both', 'min', 'max'}, default: 'neither' Direction for drawing colorbar "extensions" indicating out-of-bounds data on the end of the colorbar. -discrete : bool, default: :rc:`cmap.discrete` - If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the +discrete : bool, default: [cmap.discrete](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.discrete) + If ``False``, then [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) is not applied to the colormap. Instead, for non-contour plots, the number of levels will be - roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + roughly controlled by [cmap.lut](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.lut). This has a similar effect to using `levels=large_number` but it may improve rendering speed. Default is - ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` - and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. + ``True`` only for contouring commands like [contourf](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.contourf) + and pseudocolor commands like [pcolor](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.pcolor). sequential, diverging, cyclic, qualitative : bool, default: None Boolean arguments used if `cmap` is not passed. Set these to ``True`` - to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, - :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. - The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + to use the default [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential), [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging), + [cmap.cyclic](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.cyclic), and [cmap.qualitative](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.qualitative) colormaps. + The `diverging` option also applies [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) as the default continuous normalizer. vmin, vmax : float, optional The minimum and maximum color scale values used with the `norm` normalizer. @@ -10332,7 +10290,7 @@ vmin, vmax : float, optional `vmin` and `vmax` are the minimum and maximum of the data values. N Shorthand for `levels`. -levels : int or sequence of float, default: :rc:`cmap.levels` +levels : int or sequence of float, default: [cmap.levels](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.levels) The number of level edges or a sequence of level edges. If the former, `locator` is used to generate this many level edges at "nice" intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing @@ -10340,31 +10298,31 @@ levels : int or sequence of float, default: :rc:`cmap.levels` values : int or sequence of float, default: None The number of level centers or a sequence of level centers. If the former, `locator` is used to generate this many level centers at "nice" intervals. - If the latter, levels are inferred using `~ultraplot.utils.edges`. + If the latter, levels are inferred using [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html). This will override any `levels` input. center_levels : bool, default False If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented. -robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` +robust : bool, float, or 2-tuple, default: [cmap.robust](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.robust) If ``True`` and `vmin` or `vmax` were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers. -inbounds : bool, default: :rc:`cmap.inbounds` +inbounds : bool, default: [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) If ``True`` and `vmin` or `vmax` were not provided, when axis limits - have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` - or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. - See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. -locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + have been explicitly restricted with [set_xlim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlim.html) + or [set_ylim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylim.html), out-of-bounds data is ignored. + See also [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) and [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds). +locator : locator-spec, default: [matplotlib.ticker.MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) The locator used to determine level locations if `levels` or `values` were not - already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. - Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. + already passed as lists. Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. + Default is [MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) with `levels` integer levels. locator_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Locator` class. + Keyword arguments passed to [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. symmetric : bool, default: False If ``True``, the normalization range or discrete colormap levels are symmetric about zero. @@ -10376,20 +10334,20 @@ negative : bool, default: False negative with a minimum at zero. nozero : bool, default: False If ``True``, ``0`` is removed from the level list. This is mainly useful for - single-color `~matplotlib.axes.Axes.contour` plots. + single-color [contour](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.contour.html) plots. linewidths : unit-spec, default: 0.3 The width of lines between grid boxes. Aliases: ``lw``, ``linewidth``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). linestyles : str, default: '-' The style of lines between grid boxes. Aliases: ``ls``, ``linestyle``. edgecolors : color-spec, default: 'k' The color of lines between grid boxes. Aliases: ``ec``, ``edgecolor``. alpha : float, optional The opacity of the grid boxes. Inferred from `cmap` by default. Aliases: ``a``, ``alphas``. -edgefix : bool or float, default: :rc:`edgefix` +edgefix : bool or float, default: [edgefix](https://ultraplot.readthedocs.io/en/stable/search.html?q=edgefix) Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). - See this `github repo `__ for a + See this [github repo](https://github.com/jklymak/contourfIssues) for a demonstration of the problem. If ``True``, a small default linewidth of ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), this specific linewidth is used to cover up the white lines. This feature is @@ -10397,42 +10355,42 @@ edgefix : bool or float, default: :rc:`edgefix` label : str, optional The legend label to be used for this object. In the case of contours, this is paired with the the central artist in the artist - list returned by `matplotlib.contour.ContourSet.legend_elements`. + list returned by [matplotlib.contour.ContourSet.legend_elements](https://matplotlib.org/stable/api/_as_gen/matplotlib.contour.ContourSet.legend_elements.html). labels : bool, optional Whether to apply labels to contours and grid boxes. The text will be white when the luminance of the underlying filled contour or grid box is less than 50 and black otherwise. labels_kw : dict-like, optional Ignored if `labels` is ``False``. Extra keyword args for the labels. - For contour plots, this is passed to `~matplotlib.axes.Axes.clabel`. - Otherwise, this is passed to `~matplotlib.axes.Axes.text`. + For contour plots, this is passed to [clabel](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.clabel.html). + Otherwise, this is passed to [text](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.text.html). formatter, fmt : formatter-spec, optional - The `~matplotlib.ticker.Formatter` used to format number labels. - Passed to the `~ultraplot.constructor.Formatter` constructor. + The [Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) used to format number labels. + Passed to the [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html) constructor. formatter_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Formatter` class. + Keyword arguments passed to [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) class. precision : int, optional The maximum number of decimal places for number labels generated - with the default formatter `~ultraplot.ticker.Simpleformatter`. + with the default formatter [Simpleformatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.Simpleformatter.html). colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `matplotlib.axes.Axes.pcolormesh`. + Passed to [matplotlib.axes.Axes.pcolormesh](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.pcolormesh.html). See also -------- @@ -10460,8 +10418,7 @@ The arguments *X*, *Y*, *C* are positional-only. `~.Axes.pcolormesh` is similar to `~.Axes.pcolor`. It is much faster and preferred in most cases. For a detailed discussion on the - differences see :ref:`Differences between pcolor() and pcolormesh() - `. + differences see [Differences between pcolor() and pcolormesh()](https://ultraplot.readthedocs.io/en/stable/search.html?q=differences-pcolor-pcolormesh). Parameters ---------- @@ -10489,7 +10446,7 @@ X, Y : array-like, optional Note that the column index corresponds to the x-coordinate, and the row index corresponds to y. For details, see the - :ref:`Notes ` section below. + [Notes](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes-pcolormesh-grid-orientation) section below. If ``shading='flat'`` the dimensions of *X* and *Y* should be one greater than those of *C*, and the quadrilateral is colored due @@ -10507,11 +10464,11 @@ X, Y : array-like, optional expanded as needed into the appropriate 2D arrays, making a rectangular grid. -cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap` +cmap : str or [Colormap](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Colormap.html), default: [image.cmap](https://ultraplot.readthedocs.io/en/stable/search.html?q=image.cmap) The Colormap instance or registered colormap name used to map scalar data to colors. -norm : str or `~matplotlib.colors.Normalize`, optional +norm : str or [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html), optional The normalization method used to scale scalar data to the [0, 1] range before mapping to colors using *cmap*. By default, a linear scaling is used, mapping the lowest value to 0 and the highest to 1. @@ -10519,9 +10476,9 @@ norm : str or `~matplotlib.colors.Normalize`, optional If given, this can be one of the following: - An instance of `.Normalize` or one of its subclasses - (see :ref:`colormapnorms`). + (see [colormapnorms](https://ultraplot.readthedocs.io/en/stable/search.html?q=colormapnorms)). - A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For a - list of available scales, call `matplotlib.scale.get_scale_names()`. + list of available scales, call [matplotlib.scale.get_scale_names()](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.get_scale_names().html). In that case, a suitable `.Normalize` subclass is dynamically generated and instantiated. @@ -10532,7 +10489,7 @@ vmin, vmax : float, optional *vmin*/*vmax* when a *norm* instance is given (but using a `str` *norm* name together with *vmin*/*vmax* is acceptable). -colorizer : `~matplotlib.colorizer.Colorizer` or None, default: None +colorizer : [Colorizer](https://matplotlib.org/stable/api/_as_gen/matplotlib.colorizer.Colorizer.html) or None, default: None The Colorizer object used to map color to data. If None, a Colorizer object is created from a *norm* and *cmap*. @@ -10540,8 +10497,8 @@ edgecolors : {'none', None, 'face', color, color sequence}, optional The color of the edges. Defaults to 'none'. Possible values: - 'none' or '': No edge. - - *None*: :rc:`patch.edgecolor` will be used. Note that currently - :rc:`patch.force_edgecolor` has to be True for this to work. + - *None*: [patch.edgecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.edgecolor) will be used. Note that currently + [patch.force_edgecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=patch.force_edgecolor) has to be True for this to work. - 'face': Use the adjacent face color. - A color or sequence of colors will set the edge color. @@ -10552,7 +10509,7 @@ alpha : float, default: None shading : {'flat', 'nearest', 'gouraud', 'auto'}, optional The fill style for the quadrilateral; defaults to - :rc:`pcolor.shading`. Possible values: + [pcolor.shading](https://ultraplot.readthedocs.io/en/stable/search.html?q=pcolor.shading). Possible values: - 'flat': A solid color is used for each quad. The color of the quad (i, j), (i+1, j), (i, j+1), (i+1, j+1) is given by @@ -10571,7 +10528,7 @@ shading : {'flat', 'nearest', 'gouraud', 'auto'}, optional - 'auto': Choose 'flat' if dimensions of *X* and *Y* are one larger than *C*. Choose 'nearest' if dimensions are the same. - See :doc:`/gallery/images_contours_and_fields/pcolormesh_grids` + See [/gallery/images_contours_and_fields/pcolormesh_grids](https://ultraplot.readthedocs.io/en/stable/search.html?q=%2Fgallery%2Fimages_contours_and_fields%2Fpcolormesh_grids) for more description. snap : bool, default: False @@ -10580,11 +10537,11 @@ snap : bool, default: False rasterized : bool, optional Rasterize the pcolormesh when drawing vector graphics. This can speed up rendering and produce smaller files for large data sets. - See also :doc:`/gallery/misc/rasterization_demo`. + See also [/gallery/misc/rasterization_demo](https://ultraplot.readthedocs.io/en/stable/search.html?q=%2Fgallery%2Fmisc%2Frasterization_demo). Returns ------- -`matplotlib.collections.QuadMesh` +[matplotlib.collections.QuadMesh](https://matplotlib.org/stable/api/_as_gen/matplotlib.collections.QuadMesh.html) Other Parameters ---------------- @@ -10594,7 +10551,7 @@ data : indexable object, optional **kwargs Additionally, the following arguments are allowed. They are passed - along to the `~matplotlib.collections.QuadMesh` constructor: + along to the [QuadMesh](https://matplotlib.org/stable/api/_as_gen/matplotlib.collections.QuadMesh.html) constructor: Properties: agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image @@ -10604,14 +10561,14 @@ Properties: array: array-like capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} clim: (vmin: float, vmax: float) - clip_box: `~matplotlib.transforms.BboxBase` or None + clip_box: [BboxBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.BboxBase.html) or None clip_on: bool clip_path: Patch or (Path, Transform) or None cmap: `.Colormap` or str or None - color: :mpltype:`color` or list of RGBA tuples - edgecolor or ec or edgecolors: :mpltype:`color` or list of :mpltype:`color` or 'face' - facecolor or facecolors or fc: :mpltype:`color` or list of :mpltype:`color` - figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + color: [color](https://matplotlib.org/stable/search.html?q=color) or list of RGBA tuples + edgecolor or ec or edgecolors: [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color) or 'face' + facecolor or facecolors or fc: [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color) + figure: [Figure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html) or [SubFigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.SubFigure.html) gid: str hatch: {'/', '\\\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'} hatch_linewidth: unknown @@ -10630,7 +10587,7 @@ Properties: rasterized: bool sketch_params: (scale: float, length: float, randomness: float) snap: bool or None - transform: `~matplotlib.transforms.Transform` + transform: [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html) url: str urls: list of str or None visible: bool @@ -10640,8 +10597,7 @@ See Also -------- pcolor : An alternative implementation with slightly different features. For a detailed discussion on the differences see - :ref:`Differences between pcolor() and pcolormesh() - `. + [Differences between pcolor() and pcolormesh()](https://ultraplot.readthedocs.io/en/stable/search.html?q=differences-pcolor-pcolormesh). imshow : If *X* and *Y* are each equidistant, `~.Axes.imshow` can be a faster alternative. @@ -10700,29 +10656,28 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `z` coordinates are passed, try to infer the `x` and `y` coordinates - from the :class:`~pandas.DataFrame` indices and columns or the :class:`~xarray.DataArray` + from the [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices and columns or the [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` and the `x` coordinates are ``np.arange(0, y.shape[1])``. * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using - `~ultraplot.utils.edges` or :func:`~ultraplot.utils.edges2d` if *centers* were provided. + [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html) or [edges2d](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges2d.html) if *centers* were provided. For all other methods, calculate coordinate *centers* if *edges* were provided. - * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the - `z` coordinates are `pint.Quantity`, pass the magnitude to the plotting - command. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If the `x` or `y` coordinates are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). If the + `z` coordinates are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), pass the magnitude to the plotting + command. A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). transpose : bool, default: False Whether to transpose the input data. This should be used when passing datasets with column-major dimension order ``(x, y)``. @@ -10732,7 +10687,7 @@ order : {'C', 'F'}, default: 'C' row-major ordering (equivalent to ``transpose=False``). ``'F'`` corresponds to Fortran-style column-major ordering (equivalent to ``transpose=True``). globe : bool, default: False - For `ultraplot.axes.GeoAxes` only. Whether to enforce global + For [ultraplot.axes.GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.GeoAxes.html) only. Whether to enforce global coverage. When set to ``True`` this does the following: #. Interpolates input data to the North and South poles by setting the data @@ -10745,42 +10700,42 @@ globe : bool, default: False Other parameters ---------------- -cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` - The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor - function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization - range contains negative and positive values then :rcraw:`cmap.diverging` is used. - Otherwise :rcraw:`cmap.sequential` is used. +cmap : colormap-spec, default: [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) or [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) + The colormap specifer, passed to the [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html) constructor + function. If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization + range contains negative and positive values then [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) is used. + Otherwise [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) is used. cmap_kw : dict-like, optional - Passed to :class:`~ultraplot.constructor.Colormap`. + Passed to [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html). c, color, colors : color-spec or sequence of color-spec, optional - The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + The color(s) used to create a [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html). If not passed, `cmap` is used. -norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` - The data value normalizer, passed to the `~ultraplot.constructor.Norm` +norm : norm-spec, default: [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) or [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) + The data value normalizer, passed to the [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html) constructor function. If `discrete` is ``True`` then 1) this affects the default level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and - 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they - are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). - If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains - negative and positive values then `~ultraplot.colors.DivergingNorm` is used. - Otherwise `~matplotlib.colors.Normalize` is used. + 2) this is passed to [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) to scale the colors before they + are discretized (if `norm` is not already a [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html)). + If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization range contains + negative and positive values then [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) is used. + Otherwise [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) is used. norm_kw : dict-like, optional - Passed to `~ultraplot.constructor.Norm`. + Passed to [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html). extend : {'neither', 'both', 'min', 'max'}, default: 'neither' Direction for drawing colorbar "extensions" indicating out-of-bounds data on the end of the colorbar. -discrete : bool, default: :rc:`cmap.discrete` - If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the +discrete : bool, default: [cmap.discrete](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.discrete) + If ``False``, then [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) is not applied to the colormap. Instead, for non-contour plots, the number of levels will be - roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + roughly controlled by [cmap.lut](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.lut). This has a similar effect to using `levels=large_number` but it may improve rendering speed. Default is - ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` - and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. + ``True`` only for contouring commands like [contourf](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.contourf) + and pseudocolor commands like [pcolor](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.pcolor). sequential, diverging, cyclic, qualitative : bool, default: None Boolean arguments used if `cmap` is not passed. Set these to ``True`` - to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, - :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. - The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + to use the default [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential), [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging), + [cmap.cyclic](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.cyclic), and [cmap.qualitative](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.qualitative) colormaps. + The `diverging` option also applies [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) as the default continuous normalizer. vmin, vmax : float, optional The minimum and maximum color scale values used with the `norm` normalizer. @@ -10793,7 +10748,7 @@ vmin, vmax : float, optional `vmin` and `vmax` are the minimum and maximum of the data values. N Shorthand for `levels`. -levels : int or sequence of float, default: :rc:`cmap.levels` +levels : int or sequence of float, default: [cmap.levels](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.levels) The number of level edges or a sequence of level edges. If the former, `locator` is used to generate this many level edges at "nice" intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing @@ -10801,31 +10756,31 @@ levels : int or sequence of float, default: :rc:`cmap.levels` values : int or sequence of float, default: None The number of level centers or a sequence of level centers. If the former, `locator` is used to generate this many level centers at "nice" intervals. - If the latter, levels are inferred using `~ultraplot.utils.edges`. + If the latter, levels are inferred using [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html). This will override any `levels` input. center_levels : bool, default False If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented. -robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` +robust : bool, float, or 2-tuple, default: [cmap.robust](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.robust) If ``True`` and `vmin` or `vmax` were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers. -inbounds : bool, default: :rc:`cmap.inbounds` +inbounds : bool, default: [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) If ``True`` and `vmin` or `vmax` were not provided, when axis limits - have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` - or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. - See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. -locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + have been explicitly restricted with [set_xlim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlim.html) + or [set_ylim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylim.html), out-of-bounds data is ignored. + See also [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) and [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds). +locator : locator-spec, default: [matplotlib.ticker.MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) The locator used to determine level locations if `levels` or `values` were not - already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. - Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. + already passed as lists. Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. + Default is [MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) with `levels` integer levels. locator_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Locator` class. + Keyword arguments passed to [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. symmetric : bool, default: False If ``True``, the normalization range or discrete colormap levels are symmetric about zero. @@ -10837,20 +10792,20 @@ negative : bool, default: False negative with a minimum at zero. nozero : bool, default: False If ``True``, ``0`` is removed from the level list. This is mainly useful for - single-color `~matplotlib.axes.Axes.contour` plots. + single-color [contour](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.contour.html) plots. linewidths : unit-spec, default: 0.3 The width of lines between grid boxes. Aliases: ``lw``, ``linewidth``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). linestyles : str, default: '-' The style of lines between grid boxes. Aliases: ``ls``, ``linestyle``. edgecolors : color-spec, default: 'k' The color of lines between grid boxes. Aliases: ``ec``, ``edgecolor``. alpha : float, optional The opacity of the grid boxes. Inferred from `cmap` by default. Aliases: ``a``, ``alphas``. -edgefix : bool or float, default: :rc:`edgefix` +edgefix : bool or float, default: [edgefix](https://ultraplot.readthedocs.io/en/stable/search.html?q=edgefix) Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). - See this `github repo `__ for a + See this [github repo](https://github.com/jklymak/contourfIssues) for a demonstration of the problem. If ``True``, a small default linewidth of ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), this specific linewidth is used to cover up the white lines. This feature is @@ -10858,42 +10813,42 @@ edgefix : bool or float, default: :rc:`edgefix` label : str, optional The legend label to be used for this object. In the case of contours, this is paired with the the central artist in the artist - list returned by `matplotlib.contour.ContourSet.legend_elements`. + list returned by [matplotlib.contour.ContourSet.legend_elements](https://matplotlib.org/stable/api/_as_gen/matplotlib.contour.ContourSet.legend_elements.html). labels : bool, optional Whether to apply labels to contours and grid boxes. The text will be white when the luminance of the underlying filled contour or grid box is less than 50 and black otherwise. labels_kw : dict-like, optional Ignored if `labels` is ``False``. Extra keyword args for the labels. - For contour plots, this is passed to `~matplotlib.axes.Axes.clabel`. - Otherwise, this is passed to `~matplotlib.axes.Axes.text`. + For contour plots, this is passed to [clabel](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.clabel.html). + Otherwise, this is passed to [text](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.text.html). formatter, fmt : formatter-spec, optional - The `~matplotlib.ticker.Formatter` used to format number labels. - Passed to the `~ultraplot.constructor.Formatter` constructor. + The [Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) used to format number labels. + Passed to the [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html) constructor. formatter_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Formatter` class. + Keyword arguments passed to [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) class. precision : int, optional The maximum number of decimal places for number labels generated - with the default formatter `~ultraplot.ticker.Simpleformatter`. + with the default formatter [Simpleformatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.Simpleformatter.html). colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `matplotlib.axes.Axes.pcolorfast`. + Passed to [matplotlib.axes.Axes.pcolorfast](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.pcolorfast.html). See also -------- @@ -10979,13 +10934,13 @@ X, Y : tuple or array-like, default: ``(0, N)``, ``(0, M)`` These arguments can only be passed positionally. -cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap` +cmap : str or [Colormap](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Colormap.html), default: [image.cmap](https://ultraplot.readthedocs.io/en/stable/search.html?q=image.cmap) The Colormap instance or registered colormap name used to map scalar data to colors. This parameter is ignored if *C* is RGB(A). -norm : str or `~matplotlib.colors.Normalize`, optional +norm : str or [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html), optional The normalization method used to scale scalar data to the [0, 1] range before mapping to colors using *cmap*. By default, a linear scaling is used, mapping the lowest value to 0 and the highest to 1. @@ -10993,9 +10948,9 @@ norm : str or `~matplotlib.colors.Normalize`, optional If given, this can be one of the following: - An instance of `.Normalize` or one of its subclasses - (see :ref:`colormapnorms`). + (see [colormapnorms](https://ultraplot.readthedocs.io/en/stable/search.html?q=colormapnorms)). - A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For a - list of available scales, call `matplotlib.scale.get_scale_names()`. + list of available scales, call [matplotlib.scale.get_scale_names()](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.get_scale_names().html). In that case, a suitable `.Normalize` subclass is dynamically generated and instantiated. @@ -11010,7 +10965,7 @@ vmin, vmax : float, optional This parameter is ignored if *C* is RGB(A). -colorizer : `~matplotlib.colorizer.Colorizer` or None, default: None +colorizer : [Colorizer](https://matplotlib.org/stable/api/_as_gen/matplotlib.colorizer.Colorizer.html) or None, default: None The Colorizer object used to map color to data. If None, a Colorizer object is created from a *norm* and *cmap*. @@ -11045,7 +11000,7 @@ data : indexable object, optional def heatmap(self, *args: Incomplete, aspect: Incomplete=None, **kwargs: Incomplete) -> Incomplete: """Plot grid boxes with formatting suitable for heatmaps. Ensures square grid boxes, adds major ticks to the center of each grid box, disables minor -ticks and gridlines, and sets :rcraw:`cmap.discrete` to ``False`` by default. +ticks and gridlines, and sets [cmap.discrete](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.discrete) to ``False`` by default. Parameters ---------- @@ -11053,29 +11008,28 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `z` coordinates are passed, try to infer the `x` and `y` coordinates - from the :class:`~pandas.DataFrame` indices and columns or the :class:`~xarray.DataArray` + from the [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices and columns or the [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` and the `x` coordinates are ``np.arange(0, y.shape[1])``. * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using - `~ultraplot.utils.edges` or :func:`~ultraplot.utils.edges2d` if *centers* were provided. + [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html) or [edges2d](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges2d.html) if *centers* were provided. For all other methods, calculate coordinate *centers* if *edges* were provided. - * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the - `z` coordinates are `pint.Quantity`, pass the magnitude to the plotting - command. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If the `x` or `y` coordinates are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). If the + `z` coordinates are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), pass the magnitude to the plotting + command. A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). transpose : bool, default: False Whether to transpose the input data. This should be used when passing datasets with column-major dimension order ``(x, y)``. @@ -11085,7 +11039,7 @@ order : {'C', 'F'}, default: 'C' row-major ordering (equivalent to ``transpose=False``). ``'F'`` corresponds to Fortran-style column-major ordering (equivalent to ``transpose=True``). globe : bool, default: False - For `ultraplot.axes.GeoAxes` only. Whether to enforce global + For [ultraplot.axes.GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.GeoAxes.html) only. Whether to enforce global coverage. When set to ``True`` this does the following: #. Interpolates input data to the North and South poles by setting the data @@ -11095,10 +11049,10 @@ globe : bool, default: False #. When basemap is the backend, cycles 1D longitude vectors to fit within the map edges. For example, if the central longitude is 90°, the data is shifted so that it spans -90° to 270°. -aspect : {'equal', 'auto'} or float, default: :rc:`image.aspet` +aspect : {'equal', 'auto'} or float, default: [image.aspet](https://ultraplot.readthedocs.io/en/stable/search.html?q=image.aspet) Modify the axes aspect ratio. The aspect ratio is of particular relevance for heatmaps since it may lead to non-square grid boxes. This parameter is a shortcut - for calling `~matplotlib.axes.set_aspect`. The options are as follows: + for calling [set_aspect](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.set_aspect.html). The options are as follows: * Number: The data aspect ratio. * ``'equal'``: A data aspect ratio of 1. @@ -11107,42 +11061,42 @@ aspect : {'equal', 'auto'} or float, default: :rc:`image.aspet` Other parameters ---------------- -cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` - The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor - function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization - range contains negative and positive values then :rcraw:`cmap.diverging` is used. - Otherwise :rcraw:`cmap.sequential` is used. +cmap : colormap-spec, default: [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) or [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) + The colormap specifer, passed to the [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html) constructor + function. If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization + range contains negative and positive values then [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) is used. + Otherwise [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) is used. cmap_kw : dict-like, optional - Passed to :class:`~ultraplot.constructor.Colormap`. + Passed to [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html). c, color, colors : color-spec or sequence of color-spec, optional - The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + The color(s) used to create a [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html). If not passed, `cmap` is used. -norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` - The data value normalizer, passed to the `~ultraplot.constructor.Norm` +norm : norm-spec, default: [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) or [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) + The data value normalizer, passed to the [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html) constructor function. If `discrete` is ``True`` then 1) this affects the default level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and - 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they - are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). - If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains - negative and positive values then `~ultraplot.colors.DivergingNorm` is used. - Otherwise `~matplotlib.colors.Normalize` is used. + 2) this is passed to [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) to scale the colors before they + are discretized (if `norm` is not already a [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html)). + If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization range contains + negative and positive values then [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) is used. + Otherwise [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) is used. norm_kw : dict-like, optional - Passed to `~ultraplot.constructor.Norm`. + Passed to [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html). extend : {'neither', 'both', 'min', 'max'}, default: 'neither' Direction for drawing colorbar "extensions" indicating out-of-bounds data on the end of the colorbar. -discrete : bool, default: :rc:`cmap.discrete` - If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the +discrete : bool, default: [cmap.discrete](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.discrete) + If ``False``, then [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) is not applied to the colormap. Instead, for non-contour plots, the number of levels will be - roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + roughly controlled by [cmap.lut](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.lut). This has a similar effect to using `levels=large_number` but it may improve rendering speed. Default is - ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` - and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. + ``True`` only for contouring commands like [contourf](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.contourf) + and pseudocolor commands like [pcolor](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.pcolor). sequential, diverging, cyclic, qualitative : bool, default: None Boolean arguments used if `cmap` is not passed. Set these to ``True`` - to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, - :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. - The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + to use the default [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential), [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging), + [cmap.cyclic](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.cyclic), and [cmap.qualitative](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.qualitative) colormaps. + The `diverging` option also applies [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) as the default continuous normalizer. vmin, vmax : float, optional The minimum and maximum color scale values used with the `norm` normalizer. @@ -11155,7 +11109,7 @@ vmin, vmax : float, optional `vmin` and `vmax` are the minimum and maximum of the data values. N Shorthand for `levels`. -levels : int or sequence of float, default: :rc:`cmap.levels` +levels : int or sequence of float, default: [cmap.levels](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.levels) The number of level edges or a sequence of level edges. If the former, `locator` is used to generate this many level edges at "nice" intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing @@ -11163,31 +11117,31 @@ levels : int or sequence of float, default: :rc:`cmap.levels` values : int or sequence of float, default: None The number of level centers or a sequence of level centers. If the former, `locator` is used to generate this many level centers at "nice" intervals. - If the latter, levels are inferred using `~ultraplot.utils.edges`. + If the latter, levels are inferred using [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html). This will override any `levels` input. center_levels : bool, default False If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented. -robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` +robust : bool, float, or 2-tuple, default: [cmap.robust](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.robust) If ``True`` and `vmin` or `vmax` were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers. -inbounds : bool, default: :rc:`cmap.inbounds` +inbounds : bool, default: [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) If ``True`` and `vmin` or `vmax` were not provided, when axis limits - have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` - or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. - See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. -locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + have been explicitly restricted with [set_xlim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlim.html) + or [set_ylim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylim.html), out-of-bounds data is ignored. + See also [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) and [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds). +locator : locator-spec, default: [matplotlib.ticker.MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) The locator used to determine level locations if `levels` or `values` were not - already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. - Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. + already passed as lists. Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. + Default is [MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) with `levels` integer levels. locator_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Locator` class. + Keyword arguments passed to [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. symmetric : bool, default: False If ``True``, the normalization range or discrete colormap levels are symmetric about zero. @@ -11199,20 +11153,20 @@ negative : bool, default: False negative with a minimum at zero. nozero : bool, default: False If ``True``, ``0`` is removed from the level list. This is mainly useful for - single-color `~matplotlib.axes.Axes.contour` plots. + single-color [contour](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.contour.html) plots. linewidths : unit-spec, default: 0.3 The width of lines between grid boxes. Aliases: ``lw``, ``linewidth``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). linestyles : str, default: '-' The style of lines between grid boxes. Aliases: ``ls``, ``linestyle``. edgecolors : color-spec, default: 'k' The color of lines between grid boxes. Aliases: ``ec``, ``edgecolor``. alpha : float, optional The opacity of the grid boxes. Inferred from `cmap` by default. Aliases: ``a``, ``alphas``. -edgefix : bool or float, default: :rc:`edgefix` +edgefix : bool or float, default: [edgefix](https://ultraplot.readthedocs.io/en/stable/search.html?q=edgefix) Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). - See this `github repo `__ for a + See this [github repo](https://github.com/jklymak/contourfIssues) for a demonstration of the problem. If ``True``, a small default linewidth of ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), this specific linewidth is used to cover up the white lines. This feature is @@ -11220,42 +11174,42 @@ edgefix : bool or float, default: :rc:`edgefix` label : str, optional The legend label to be used for this object. In the case of contours, this is paired with the the central artist in the artist - list returned by `matplotlib.contour.ContourSet.legend_elements`. + list returned by [matplotlib.contour.ContourSet.legend_elements](https://matplotlib.org/stable/api/_as_gen/matplotlib.contour.ContourSet.legend_elements.html). labels : bool, optional Whether to apply labels to contours and grid boxes. The text will be white when the luminance of the underlying filled contour or grid box is less than 50 and black otherwise. labels_kw : dict-like, optional Ignored if `labels` is ``False``. Extra keyword args for the labels. - For contour plots, this is passed to `~matplotlib.axes.Axes.clabel`. - Otherwise, this is passed to `~matplotlib.axes.Axes.text`. + For contour plots, this is passed to [clabel](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.clabel.html). + Otherwise, this is passed to [text](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.text.html). formatter, fmt : formatter-spec, optional - The `~matplotlib.ticker.Formatter` used to format number labels. - Passed to the `~ultraplot.constructor.Formatter` constructor. + The [Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) used to format number labels. + Passed to the [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html) constructor. formatter_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Formatter` class. + Keyword arguments passed to [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) class. precision : int, optional The maximum number of decimal places for number labels generated - with the default formatter `~ultraplot.ticker.Simpleformatter`. + with the default formatter [Simpleformatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.Simpleformatter.html). colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `matplotlib.axes.Axes.pcolormesh`. + Passed to [matplotlib.axes.Axes.pcolormesh](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.pcolormesh.html). See also -------- @@ -11276,33 +11230,32 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `u` and `v` coordinates are passed, try to infer the `x` and `y` coordinates - from the :class:`~pandas.DataFrame` indices and columns or the :class:`~xarray.DataArray` + from the [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices and columns or the [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` and the `x` coordinates are ``np.arange(0, y.shape[1])``. * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using - `~ultraplot.utils.edges` or :func:`~ultraplot.utils.edges2d` if *centers* were provided. + [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html) or [edges2d](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges2d.html) if *centers* were provided. For all other methods, calculate coordinate *centers* if *edges* were provided. - * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the - `u` and `v` coordinates are `pint.Quantity`, pass the magnitude to the plotting - command. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If the `x` or `y` coordinates are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). If the + `u` and `v` coordinates are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), pass the magnitude to the plotting + command. A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. c, color, colors : array-like or color-spec, optional The colors of the wind barbs passed as either a keyword argument or a fifth positional argument. This can be a single color or a color array to be scaled by `cmap` and `norm`. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). transpose : bool, default: False Whether to transpose the input data. This should be used when passing datasets with column-major dimension order ``(x, y)``. @@ -11312,7 +11265,7 @@ order : {'C', 'F'}, default: 'C' row-major ordering (equivalent to ``transpose=False``). ``'F'`` corresponds to Fortran-style column-major ordering (equivalent to ``transpose=True``). globe : bool, default: False - For `ultraplot.axes.GeoAxes` only. Whether to enforce global + For [ultraplot.axes.GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.GeoAxes.html) only. Whether to enforce global coverage. When set to ``True`` this does the following: #. Interpolates input data to the North and South poles by setting the data @@ -11325,42 +11278,42 @@ globe : bool, default: False Other parameters ---------------- -cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` - The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor - function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization - range contains negative and positive values then :rcraw:`cmap.diverging` is used. - Otherwise :rcraw:`cmap.sequential` is used. +cmap : colormap-spec, default: [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) or [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) + The colormap specifer, passed to the [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html) constructor + function. If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization + range contains negative and positive values then [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) is used. + Otherwise [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) is used. cmap_kw : dict-like, optional - Passed to :class:`~ultraplot.constructor.Colormap`. + Passed to [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html). c, color, colors : color-spec or sequence of color-spec, optional - The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + The color(s) used to create a [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html). If not passed, `cmap` is used. -norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` - The data value normalizer, passed to the `~ultraplot.constructor.Norm` +norm : norm-spec, default: [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) or [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) + The data value normalizer, passed to the [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html) constructor function. If `discrete` is ``True`` then 1) this affects the default level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and - 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they - are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). - If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains - negative and positive values then `~ultraplot.colors.DivergingNorm` is used. - Otherwise `~matplotlib.colors.Normalize` is used. + 2) this is passed to [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) to scale the colors before they + are discretized (if `norm` is not already a [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html)). + If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization range contains + negative and positive values then [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) is used. + Otherwise [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) is used. norm_kw : dict-like, optional - Passed to `~ultraplot.constructor.Norm`. + Passed to [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html). extend : {'neither', 'both', 'min', 'max'}, default: 'neither' Direction for drawing colorbar "extensions" indicating out-of-bounds data on the end of the colorbar. -discrete : bool, default: :rc:`cmap.discrete` - If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the +discrete : bool, default: [cmap.discrete](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.discrete) + If ``False``, then [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) is not applied to the colormap. Instead, for non-contour plots, the number of levels will be - roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + roughly controlled by [cmap.lut](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.lut). This has a similar effect to using `levels=large_number` but it may improve rendering speed. Default is - ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` - and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. + ``True`` only for contouring commands like [contourf](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.contourf) + and pseudocolor commands like [pcolor](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.pcolor). sequential, diverging, cyclic, qualitative : bool, default: None Boolean arguments used if `cmap` is not passed. Set these to ``True`` - to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, - :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. - The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + to use the default [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential), [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging), + [cmap.cyclic](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.cyclic), and [cmap.qualitative](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.qualitative) colormaps. + The `diverging` option also applies [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) as the default continuous normalizer. vmin, vmax : float, optional The minimum and maximum color scale values used with the `norm` normalizer. @@ -11373,7 +11326,7 @@ vmin, vmax : float, optional `vmin` and `vmax` are the minimum and maximum of the data values. N Shorthand for `levels`. -levels : int or sequence of float, default: :rc:`cmap.levels` +levels : int or sequence of float, default: [cmap.levels](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.levels) The number of level edges or a sequence of level edges. If the former, `locator` is used to generate this many level edges at "nice" intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing @@ -11381,31 +11334,31 @@ levels : int or sequence of float, default: :rc:`cmap.levels` values : int or sequence of float, default: None The number of level centers or a sequence of level centers. If the former, `locator` is used to generate this many level centers at "nice" intervals. - If the latter, levels are inferred using `~ultraplot.utils.edges`. + If the latter, levels are inferred using [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html). This will override any `levels` input. center_levels : bool, default False If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented. -robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` +robust : bool, float, or 2-tuple, default: [cmap.robust](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.robust) If ``True`` and `vmin` or `vmax` were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers. -inbounds : bool, default: :rc:`cmap.inbounds` +inbounds : bool, default: [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) If ``True`` and `vmin` or `vmax` were not provided, when axis limits - have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` - or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. - See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. -locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + have been explicitly restricted with [set_xlim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlim.html) + or [set_ylim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylim.html), out-of-bounds data is ignored. + See also [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) and [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds). +locator : locator-spec, default: [matplotlib.ticker.MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) The locator used to determine level locations if `levels` or `values` were not - already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. - Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. + already passed as lists. Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. + Default is [MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) with `levels` integer levels. locator_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Locator` class. + Keyword arguments passed to [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. symmetric : bool, default: False If ``True``, the normalization range or discrete colormap levels are symmetric about zero. @@ -11417,9 +11370,9 @@ negative : bool, default: False negative with a minimum at zero. nozero : bool, default: False If ``True``, ``0`` is removed from the level list. This is mainly useful for - single-color `~matplotlib.axes.Axes.contour` plots. + single-color [contour](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.contour.html) plots. **kwargs - Passed to `matplotlib.axes.Axes.barbs` + Passed to [matplotlib.axes.Axes.barbs](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.barbs.html) See also -------- @@ -11502,12 +11455,12 @@ pivot : {'tip', 'middle'} or float, default: 'tip' rotates about this point. This can also be a number, which shifts the start of the barb that many points away from grid point. -barbcolor : :mpltype:`color` or color sequence +barbcolor : [color](https://matplotlib.org/stable/search.html?q=color) or color sequence The color of all parts of the barb except for the flags. This parameter is analogous to the *edgecolor* parameter for polygons, which can be used instead. However this parameter will override facecolor. -flagcolor : :mpltype:`color` or color sequence +flagcolor : [color](https://matplotlib.org/stable/search.html?q=color) or color sequence The color of any flags on the barb. This parameter is analogous to the *facecolor* parameter for polygons, which can be used instead. However, this parameter will override facecolor. If this is not set (and *C* has @@ -11554,7 +11507,7 @@ flip_barb : bool or array-like of bool, default: False Returns ------- -barbs : `~matplotlib.quiver.Barbs` +barbs : [Barbs](https://matplotlib.org/stable/api/_as_gen/matplotlib.quiver.Barbs.html) Other Parameters ---------------- @@ -11574,14 +11527,14 @@ data : indexable object, optional array: array-like or None capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} clim: (vmin: float, vmax: float) - clip_box: `~matplotlib.transforms.BboxBase` or None + clip_box: [BboxBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.BboxBase.html) or None clip_on: bool clip_path: Patch or (Path, Transform) or None cmap: `.Colormap` or str or None - color: :mpltype:`color` or list of RGBA tuples - edgecolor or ec or edgecolors: :mpltype:`color` or list of :mpltype:`color` or 'face' - facecolor or facecolors or fc: :mpltype:`color` or list of :mpltype:`color` - figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + color: [color](https://matplotlib.org/stable/search.html?q=color) or list of RGBA tuples + edgecolor or ec or edgecolors: [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color) or 'face' + facecolor or facecolors or fc: [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color) + figure: [Figure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html) or [SubFigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.SubFigure.html) gid: str hatch: {'/', '\\\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'} hatch_linewidth: unknown @@ -11599,10 +11552,10 @@ data : indexable object, optional picker: None or bool or float or callable pickradius: float rasterized: bool - sizes: `numpy.ndarray` or None + sizes: [numpy.ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html) or None sketch_params: (scale: float, length: float, randomness: float) snap: bool or None - transform: `~matplotlib.transforms.Transform` + transform: [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html) url: str urls: list of str or None verts: list of array-like @@ -11620,33 +11573,32 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `u` and `v` coordinates are passed, try to infer the `x` and `y` coordinates - from the :class:`~pandas.DataFrame` indices and columns or the :class:`~xarray.DataArray` + from the [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices and columns or the [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` and the `x` coordinates are ``np.arange(0, y.shape[1])``. * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using - `~ultraplot.utils.edges` or :func:`~ultraplot.utils.edges2d` if *centers* were provided. + [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html) or [edges2d](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges2d.html) if *centers* were provided. For all other methods, calculate coordinate *centers* if *edges* were provided. - * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the - `u` and `v` coordinates are `pint.Quantity`, pass the magnitude to the plotting - command. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If the `x` or `y` coordinates are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). If the + `u` and `v` coordinates are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), pass the magnitude to the plotting + command. A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. c, color, colors : array-like or color-spec, optional The colors of the quiver arrows passed as either a keyword argument or a fifth positional argument. This can be a single color or a color array to be scaled by `cmap` and `norm`. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). transpose : bool, default: False Whether to transpose the input data. This should be used when passing datasets with column-major dimension order ``(x, y)``. @@ -11656,7 +11608,7 @@ order : {'C', 'F'}, default: 'C' row-major ordering (equivalent to ``transpose=False``). ``'F'`` corresponds to Fortran-style column-major ordering (equivalent to ``transpose=True``). globe : bool, default: False - For `ultraplot.axes.GeoAxes` only. Whether to enforce global + For [ultraplot.axes.GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.GeoAxes.html) only. Whether to enforce global coverage. When set to ``True`` this does the following: #. Interpolates input data to the North and South poles by setting the data @@ -11669,42 +11621,42 @@ globe : bool, default: False Other parameters ---------------- -cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` - The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor - function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization - range contains negative and positive values then :rcraw:`cmap.diverging` is used. - Otherwise :rcraw:`cmap.sequential` is used. +cmap : colormap-spec, default: [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) or [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) + The colormap specifer, passed to the [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html) constructor + function. If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization + range contains negative and positive values then [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) is used. + Otherwise [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) is used. cmap_kw : dict-like, optional - Passed to :class:`~ultraplot.constructor.Colormap`. + Passed to [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html). c, color, colors : color-spec or sequence of color-spec, optional - The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + The color(s) used to create a [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html). If not passed, `cmap` is used. -norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` - The data value normalizer, passed to the `~ultraplot.constructor.Norm` +norm : norm-spec, default: [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) or [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) + The data value normalizer, passed to the [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html) constructor function. If `discrete` is ``True`` then 1) this affects the default level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and - 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they - are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). - If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains - negative and positive values then `~ultraplot.colors.DivergingNorm` is used. - Otherwise `~matplotlib.colors.Normalize` is used. + 2) this is passed to [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) to scale the colors before they + are discretized (if `norm` is not already a [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html)). + If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization range contains + negative and positive values then [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) is used. + Otherwise [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) is used. norm_kw : dict-like, optional - Passed to `~ultraplot.constructor.Norm`. + Passed to [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html). extend : {'neither', 'both', 'min', 'max'}, default: 'neither' Direction for drawing colorbar "extensions" indicating out-of-bounds data on the end of the colorbar. -discrete : bool, default: :rc:`cmap.discrete` - If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the +discrete : bool, default: [cmap.discrete](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.discrete) + If ``False``, then [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) is not applied to the colormap. Instead, for non-contour plots, the number of levels will be - roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + roughly controlled by [cmap.lut](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.lut). This has a similar effect to using `levels=large_number` but it may improve rendering speed. Default is - ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` - and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. + ``True`` only for contouring commands like [contourf](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.contourf) + and pseudocolor commands like [pcolor](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.pcolor). sequential, diverging, cyclic, qualitative : bool, default: None Boolean arguments used if `cmap` is not passed. Set these to ``True`` - to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, - :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. - The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + to use the default [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential), [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging), + [cmap.cyclic](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.cyclic), and [cmap.qualitative](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.qualitative) colormaps. + The `diverging` option also applies [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) as the default continuous normalizer. vmin, vmax : float, optional The minimum and maximum color scale values used with the `norm` normalizer. @@ -11717,7 +11669,7 @@ vmin, vmax : float, optional `vmin` and `vmax` are the minimum and maximum of the data values. N Shorthand for `levels`. -levels : int or sequence of float, default: :rc:`cmap.levels` +levels : int or sequence of float, default: [cmap.levels](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.levels) The number of level edges or a sequence of level edges. If the former, `locator` is used to generate this many level edges at "nice" intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing @@ -11725,31 +11677,31 @@ levels : int or sequence of float, default: :rc:`cmap.levels` values : int or sequence of float, default: None The number of level centers or a sequence of level centers. If the former, `locator` is used to generate this many level centers at "nice" intervals. - If the latter, levels are inferred using `~ultraplot.utils.edges`. + If the latter, levels are inferred using [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html). This will override any `levels` input. center_levels : bool, default False If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented. -robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` +robust : bool, float, or 2-tuple, default: [cmap.robust](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.robust) If ``True`` and `vmin` or `vmax` were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers. -inbounds : bool, default: :rc:`cmap.inbounds` +inbounds : bool, default: [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) If ``True`` and `vmin` or `vmax` were not provided, when axis limits - have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` - or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. - See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. -locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + have been explicitly restricted with [set_xlim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlim.html) + or [set_ylim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylim.html), out-of-bounds data is ignored. + See also [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) and [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds). +locator : locator-spec, default: [matplotlib.ticker.MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) The locator used to determine level locations if `levels` or `values` were not - already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. - Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. + already passed as lists. Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. + Default is [MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) with `levels` integer levels. locator_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Locator` class. + Keyword arguments passed to [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. symmetric : bool, default: False If ``True``, the normalization range or discrete colormap levels are symmetric about zero. @@ -11761,9 +11713,9 @@ negative : bool, default: False negative with a minimum at zero. nozero : bool, default: False If ``True``, ``0`` is removed from the level list. This is mainly useful for - single-color `~matplotlib.axes.Axes.contour` plots. + single-color [contour](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.contour.html) plots. **kwargs - Passed to `matplotlib.axes.Axes.quiver` + Passed to [matplotlib.axes.Axes.quiver](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.quiver.html) See also -------- @@ -11836,7 +11788,7 @@ angles : {'uv', 'xy'} or array-like, default: 'uv' Method for determining the angle of the arrows. - 'uv': Arrow directions are based on - :ref:`display coordinates `; i.e. a 45° angle will + [display coordinates](https://ultraplot.readthedocs.io/en/stable/search.html?q=coordinate-systems); i.e. a 45° angle will always show up as diagonal on the screen, irrespective of figure or Axes aspect ratio or Axes data ranges. This is useful when the arrows represent a quantity whose direction is not tied to the x and y data coordinates. @@ -11969,7 +11921,7 @@ minlength : float, default: 1 Minimum length as a multiple of shaft width; if an arrow length is less than this, plot a dot (hexagon) of this diameter instead. -color : :mpltype:`color` or list :mpltype:`color`, optional +color : [color](https://matplotlib.org/stable/search.html?q=color) or list [color](https://matplotlib.org/stable/search.html?q=color), optional Explicit color(s) for the arrows. If *C* has been set, *color* has no effect. @@ -11981,7 +11933,7 @@ data : indexable object, optional If given, all parameters also accept a string ``s``, which is interpreted as ``data[s]`` if ``s`` is a key in ``data``. -**kwargs : `~matplotlib.collections.PolyCollection` properties, optional +**kwargs : [PolyCollection](https://matplotlib.org/stable/api/_as_gen/matplotlib.collections.PolyCollection.html) properties, optional All other keyword arguments are passed on to `.PolyCollection`: Properties: @@ -11992,14 +11944,14 @@ data : indexable object, optional array: array-like or None capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} clim: (vmin: float, vmax: float) - clip_box: `~matplotlib.transforms.BboxBase` or None + clip_box: [BboxBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.BboxBase.html) or None clip_on: bool clip_path: Patch or (Path, Transform) or None cmap: `.Colormap` or str or None - color: :mpltype:`color` or list of RGBA tuples - edgecolor or ec or edgecolors: :mpltype:`color` or list of :mpltype:`color` or 'face' - facecolor or facecolors or fc: :mpltype:`color` or list of :mpltype:`color` - figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + color: [color](https://matplotlib.org/stable/search.html?q=color) or list of RGBA tuples + edgecolor or ec or edgecolors: [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color) or 'face' + facecolor or facecolors or fc: [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color) + figure: [Figure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html) or [SubFigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.SubFigure.html) gid: str hatch: {'/', '\\\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'} hatch_linewidth: unknown @@ -12017,10 +11969,10 @@ data : indexable object, optional picker: None or bool or float or callable pickradius: float rasterized: bool - sizes: `numpy.ndarray` or None + sizes: [numpy.ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html) or None sketch_params: (scale: float, length: float, randomness: float) snap: bool or None - transform: `~matplotlib.transforms.Transform` + transform: [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html) url: str urls: list of str or None verts: list of array-like @@ -12030,7 +11982,7 @@ data : indexable object, optional Returns ------- -`~matplotlib.quiver.Quiver` +[Quiver](https://matplotlib.org/stable/api/_as_gen/matplotlib.quiver.Quiver.html) See Also -------- @@ -12071,33 +12023,32 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `u` and `v` coordinates are passed, try to infer the `x` and `y` coordinates - from the :class:`~pandas.DataFrame` indices and columns or the :class:`~xarray.DataArray` + from the [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices and columns or the [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` and the `x` coordinates are ``np.arange(0, y.shape[1])``. * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using - `~ultraplot.utils.edges` or :func:`~ultraplot.utils.edges2d` if *centers* were provided. + [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html) or [edges2d](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges2d.html) if *centers* were provided. For all other methods, calculate coordinate *centers* if *edges* were provided. - * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the - `u` and `v` coordinates are `pint.Quantity`, pass the magnitude to the plotting - command. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If the `x` or `y` coordinates are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). If the + `u` and `v` coordinates are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), pass the magnitude to the plotting + command. A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. c, color, colors : array-like or color-spec, optional The colors of the streamlines passed as either a keyword argument or a fifth positional argument. This can be a single color or a color array to be scaled by `cmap` and `norm`. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). transpose : bool, default: False Whether to transpose the input data. This should be used when passing datasets with column-major dimension order ``(x, y)``. @@ -12107,7 +12058,7 @@ order : {'C', 'F'}, default: 'C' row-major ordering (equivalent to ``transpose=False``). ``'F'`` corresponds to Fortran-style column-major ordering (equivalent to ``transpose=True``). globe : bool, default: False - For `ultraplot.axes.GeoAxes` only. Whether to enforce global + For [ultraplot.axes.GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.GeoAxes.html) only. Whether to enforce global coverage. When set to ``True`` this does the following: #. Interpolates input data to the North and South poles by setting the data @@ -12120,42 +12071,42 @@ globe : bool, default: False Other parameters ---------------- -cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` - The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor - function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization - range contains negative and positive values then :rcraw:`cmap.diverging` is used. - Otherwise :rcraw:`cmap.sequential` is used. +cmap : colormap-spec, default: [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) or [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) + The colormap specifer, passed to the [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html) constructor + function. If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization + range contains negative and positive values then [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) is used. + Otherwise [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) is used. cmap_kw : dict-like, optional - Passed to :class:`~ultraplot.constructor.Colormap`. + Passed to [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html). c, color, colors : color-spec or sequence of color-spec, optional - The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + The color(s) used to create a [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html). If not passed, `cmap` is used. -norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` - The data value normalizer, passed to the `~ultraplot.constructor.Norm` +norm : norm-spec, default: [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) or [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) + The data value normalizer, passed to the [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html) constructor function. If `discrete` is ``True`` then 1) this affects the default level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and - 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they - are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). - If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains - negative and positive values then `~ultraplot.colors.DivergingNorm` is used. - Otherwise `~matplotlib.colors.Normalize` is used. + 2) this is passed to [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) to scale the colors before they + are discretized (if `norm` is not already a [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html)). + If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization range contains + negative and positive values then [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) is used. + Otherwise [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) is used. norm_kw : dict-like, optional - Passed to `~ultraplot.constructor.Norm`. + Passed to [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html). extend : {'neither', 'both', 'min', 'max'}, default: 'neither' Direction for drawing colorbar "extensions" indicating out-of-bounds data on the end of the colorbar. -discrete : bool, default: :rc:`cmap.discrete` - If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the +discrete : bool, default: [cmap.discrete](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.discrete) + If ``False``, then [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) is not applied to the colormap. Instead, for non-contour plots, the number of levels will be - roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + roughly controlled by [cmap.lut](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.lut). This has a similar effect to using `levels=large_number` but it may improve rendering speed. Default is - ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` - and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. + ``True`` only for contouring commands like [contourf](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.contourf) + and pseudocolor commands like [pcolor](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.pcolor). sequential, diverging, cyclic, qualitative : bool, default: None Boolean arguments used if `cmap` is not passed. Set these to ``True`` - to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, - :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. - The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + to use the default [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential), [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging), + [cmap.cyclic](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.cyclic), and [cmap.qualitative](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.qualitative) colormaps. + The `diverging` option also applies [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) as the default continuous normalizer. vmin, vmax : float, optional The minimum and maximum color scale values used with the `norm` normalizer. @@ -12168,7 +12119,7 @@ vmin, vmax : float, optional `vmin` and `vmax` are the minimum and maximum of the data values. N Shorthand for `levels`. -levels : int or sequence of float, default: :rc:`cmap.levels` +levels : int or sequence of float, default: [cmap.levels](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.levels) The number of level edges or a sequence of level edges. If the former, `locator` is used to generate this many level edges at "nice" intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing @@ -12176,31 +12127,31 @@ levels : int or sequence of float, default: :rc:`cmap.levels` values : int or sequence of float, default: None The number of level centers or a sequence of level centers. If the former, `locator` is used to generate this many level centers at "nice" intervals. - If the latter, levels are inferred using `~ultraplot.utils.edges`. + If the latter, levels are inferred using [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html). This will override any `levels` input. center_levels : bool, default False If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented. -robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` +robust : bool, float, or 2-tuple, default: [cmap.robust](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.robust) If ``True`` and `vmin` or `vmax` were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers. -inbounds : bool, default: :rc:`cmap.inbounds` +inbounds : bool, default: [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) If ``True`` and `vmin` or `vmax` were not provided, when axis limits - have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` - or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. - See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. -locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + have been explicitly restricted with [set_xlim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlim.html) + or [set_ylim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylim.html), out-of-bounds data is ignored. + See also [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) and [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds). +locator : locator-spec, default: [matplotlib.ticker.MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) The locator used to determine level locations if `levels` or `values` were not - already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. - Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. + already passed as lists. Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. + Default is [MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) with `levels` integer levels. locator_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Locator` class. + Keyword arguments passed to [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. symmetric : bool, default: False If ``True``, the normalization range or discrete colormap levels are symmetric about zero. @@ -12212,9 +12163,9 @@ negative : bool, default: False negative with a minimum at zero. nozero : bool, default: False If ``True``, ``0`` is removed from the level list. This is mainly useful for - single-color `~matplotlib.axes.Axes.contour` plots. + single-color [contour](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.contour.html) plots. **kwargs - Passed to `matplotlib.axes.Axes.streamplot` + Passed to [matplotlib.axes.Axes.streamplot](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.streamplot.html) See also -------- @@ -12234,33 +12185,32 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `u` and `v` coordinates are passed, try to infer the `x` and `y` coordinates - from the :class:`~pandas.DataFrame` indices and columns or the :class:`~xarray.DataArray` + from the [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices and columns or the [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` and the `x` coordinates are ``np.arange(0, y.shape[1])``. * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using - `~ultraplot.utils.edges` or :func:`~ultraplot.utils.edges2d` if *centers* were provided. + [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html) or [edges2d](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges2d.html) if *centers* were provided. For all other methods, calculate coordinate *centers* if *edges* were provided. - * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the - `u` and `v` coordinates are `pint.Quantity`, pass the magnitude to the plotting - command. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If the `x` or `y` coordinates are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). If the + `u` and `v` coordinates are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), pass the magnitude to the plotting + command. A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. c, color, colors : array-like or color-spec, optional The colors of the streamlines passed as either a keyword argument or a fifth positional argument. This can be a single color or a color array to be scaled by `cmap` and `norm`. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). transpose : bool, default: False Whether to transpose the input data. This should be used when passing datasets with column-major dimension order ``(x, y)``. @@ -12270,7 +12220,7 @@ order : {'C', 'F'}, default: 'C' row-major ordering (equivalent to ``transpose=False``). ``'F'`` corresponds to Fortran-style column-major ordering (equivalent to ``transpose=True``). globe : bool, default: False - For `ultraplot.axes.GeoAxes` only. Whether to enforce global + For [ultraplot.axes.GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.GeoAxes.html) only. Whether to enforce global coverage. When set to ``True`` this does the following: #. Interpolates input data to the North and South poles by setting the data @@ -12283,42 +12233,42 @@ globe : bool, default: False Other parameters ---------------- -cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` - The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor - function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization - range contains negative and positive values then :rcraw:`cmap.diverging` is used. - Otherwise :rcraw:`cmap.sequential` is used. +cmap : colormap-spec, default: [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) or [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) + The colormap specifer, passed to the [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html) constructor + function. If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization + range contains negative and positive values then [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) is used. + Otherwise [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) is used. cmap_kw : dict-like, optional - Passed to :class:`~ultraplot.constructor.Colormap`. + Passed to [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html). c, color, colors : color-spec or sequence of color-spec, optional - The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + The color(s) used to create a [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html). If not passed, `cmap` is used. -norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` - The data value normalizer, passed to the `~ultraplot.constructor.Norm` +norm : norm-spec, default: [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) or [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) + The data value normalizer, passed to the [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html) constructor function. If `discrete` is ``True`` then 1) this affects the default level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and - 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they - are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). - If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains - negative and positive values then `~ultraplot.colors.DivergingNorm` is used. - Otherwise `~matplotlib.colors.Normalize` is used. + 2) this is passed to [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) to scale the colors before they + are discretized (if `norm` is not already a [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html)). + If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization range contains + negative and positive values then [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) is used. + Otherwise [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) is used. norm_kw : dict-like, optional - Passed to `~ultraplot.constructor.Norm`. + Passed to [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html). extend : {'neither', 'both', 'min', 'max'}, default: 'neither' Direction for drawing colorbar "extensions" indicating out-of-bounds data on the end of the colorbar. -discrete : bool, default: :rc:`cmap.discrete` - If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the +discrete : bool, default: [cmap.discrete](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.discrete) + If ``False``, then [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) is not applied to the colormap. Instead, for non-contour plots, the number of levels will be - roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + roughly controlled by [cmap.lut](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.lut). This has a similar effect to using `levels=large_number` but it may improve rendering speed. Default is - ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` - and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. + ``True`` only for contouring commands like [contourf](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.contourf) + and pseudocolor commands like [pcolor](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.pcolor). sequential, diverging, cyclic, qualitative : bool, default: None Boolean arguments used if `cmap` is not passed. Set these to ``True`` - to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, - :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. - The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + to use the default [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential), [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging), + [cmap.cyclic](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.cyclic), and [cmap.qualitative](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.qualitative) colormaps. + The `diverging` option also applies [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) as the default continuous normalizer. vmin, vmax : float, optional The minimum and maximum color scale values used with the `norm` normalizer. @@ -12331,7 +12281,7 @@ vmin, vmax : float, optional `vmin` and `vmax` are the minimum and maximum of the data values. N Shorthand for `levels`. -levels : int or sequence of float, default: :rc:`cmap.levels` +levels : int or sequence of float, default: [cmap.levels](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.levels) The number of level edges or a sequence of level edges. If the former, `locator` is used to generate this many level edges at "nice" intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing @@ -12339,31 +12289,31 @@ levels : int or sequence of float, default: :rc:`cmap.levels` values : int or sequence of float, default: None The number of level centers or a sequence of level centers. If the former, `locator` is used to generate this many level centers at "nice" intervals. - If the latter, levels are inferred using `~ultraplot.utils.edges`. + If the latter, levels are inferred using [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html). This will override any `levels` input. center_levels : bool, default False If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented. -robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` +robust : bool, float, or 2-tuple, default: [cmap.robust](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.robust) If ``True`` and `vmin` or `vmax` were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers. -inbounds : bool, default: :rc:`cmap.inbounds` +inbounds : bool, default: [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) If ``True`` and `vmin` or `vmax` were not provided, when axis limits - have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` - or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. - See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. -locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + have been explicitly restricted with [set_xlim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlim.html) + or [set_ylim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylim.html), out-of-bounds data is ignored. + See also [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) and [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds). +locator : locator-spec, default: [matplotlib.ticker.MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) The locator used to determine level locations if `levels` or `values` were not - already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. - Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. + already passed as lists. Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. + Default is [MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) with `levels` integer levels. locator_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Locator` class. + Keyword arguments passed to [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. symmetric : bool, default: False If ``True``, the normalization range or discrete colormap levels are symmetric about zero. @@ -12375,9 +12325,9 @@ negative : bool, default: False negative with a minimum at zero. nozero : bool, default: False If ``True``, ``0`` is removed from the level list. This is mainly useful for - single-color `~matplotlib.axes.Axes.contour` plots. + single-color [contour](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.contour.html) plots. **kwargs - Passed to `matplotlib.axes.Axes.streamplot` + Passed to [matplotlib.axes.Axes.streamplot](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.streamplot.html) See also -------- @@ -12411,7 +12361,7 @@ linewidth : float or 2D array The width of the streamlines. With a 2D array the line width can be varied across the grid. The array must have the same shape as *u* and *v*. -color : :mpltype:`color` or 2D array +color : [color](https://matplotlib.org/stable/search.html?q=color) or 2D array The streamline color. If given an array, its values are converted to colors using *cmap* and *norm*. The array must have the same shape as *u* and *v*. @@ -12423,7 +12373,7 @@ arrowsize : float Scaling factor for the arrow size. arrowstyle : str Arrow style specification. - See `~matplotlib.patches.FancyArrowPatch`. + See [FancyArrowPatch](https://matplotlib.org/stable/api/_as_gen/matplotlib.patches.FancyArrowPatch.html). minlength : float Minimum length of streamline in axes coordinates. start_points : (N, 2) array @@ -12470,29 +12420,28 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `z` coordinates are passed, try to infer the `x` and `y` coordinates - from the :class:`~pandas.DataFrame` indices and columns or the :class:`~xarray.DataArray` + from the [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices and columns or the [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` and the `x` coordinates are ``np.arange(0, y.shape[1])``. * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using - `~ultraplot.utils.edges` or :func:`~ultraplot.utils.edges2d` if *centers* were provided. + [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html) or [edges2d](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges2d.html) if *centers* were provided. For all other methods, calculate coordinate *centers* if *edges* were provided. - * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the - `z` coordinates are `pint.Quantity`, pass the magnitude to the plotting - command. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If the `x` or `y` coordinates are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). If the + `z` coordinates are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), pass the magnitude to the plotting + command. A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). transpose : bool, default: False Whether to transpose the input data. This should be used when passing datasets with column-major dimension order ``(x, y)``. @@ -12502,7 +12451,7 @@ order : {'C', 'F'}, default: 'C' row-major ordering (equivalent to ``transpose=False``). ``'F'`` corresponds to Fortran-style column-major ordering (equivalent to ``transpose=True``). globe : bool, default: False - For `ultraplot.axes.GeoAxes` only. Whether to enforce global + For [ultraplot.axes.GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.GeoAxes.html) only. Whether to enforce global coverage. When set to ``True`` this does the following: #. Interpolates input data to the North and South poles by setting the data @@ -12515,42 +12464,42 @@ globe : bool, default: False Other parameters ---------------- -cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` - The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor - function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization - range contains negative and positive values then :rcraw:`cmap.diverging` is used. - Otherwise :rcraw:`cmap.sequential` is used. +cmap : colormap-spec, default: [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) or [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) + The colormap specifer, passed to the [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html) constructor + function. If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization + range contains negative and positive values then [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) is used. + Otherwise [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) is used. cmap_kw : dict-like, optional - Passed to :class:`~ultraplot.constructor.Colormap`. + Passed to [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html). c, color, colors : color-spec or sequence of color-spec, optional - The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + The color(s) used to create a [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html). If not passed, `cmap` is used. -norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` - The data value normalizer, passed to the `~ultraplot.constructor.Norm` +norm : norm-spec, default: [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) or [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) + The data value normalizer, passed to the [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html) constructor function. If `discrete` is ``True`` then 1) this affects the default level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and - 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they - are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). - If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains - negative and positive values then `~ultraplot.colors.DivergingNorm` is used. - Otherwise `~matplotlib.colors.Normalize` is used. + 2) this is passed to [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) to scale the colors before they + are discretized (if `norm` is not already a [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html)). + If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization range contains + negative and positive values then [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) is used. + Otherwise [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) is used. norm_kw : dict-like, optional - Passed to `~ultraplot.constructor.Norm`. + Passed to [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html). extend : {'neither', 'both', 'min', 'max'}, default: 'neither' Direction for drawing colorbar "extensions" indicating out-of-bounds data on the end of the colorbar. -discrete : bool, default: :rc:`cmap.discrete` - If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the +discrete : bool, default: [cmap.discrete](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.discrete) + If ``False``, then [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) is not applied to the colormap. Instead, for non-contour plots, the number of levels will be - roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + roughly controlled by [cmap.lut](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.lut). This has a similar effect to using `levels=large_number` but it may improve rendering speed. Default is - ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` - and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. + ``True`` only for contouring commands like [contourf](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.contourf) + and pseudocolor commands like [pcolor](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.pcolor). sequential, diverging, cyclic, qualitative : bool, default: None Boolean arguments used if `cmap` is not passed. Set these to ``True`` - to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, - :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. - The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + to use the default [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential), [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging), + [cmap.cyclic](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.cyclic), and [cmap.qualitative](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.qualitative) colormaps. + The `diverging` option also applies [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) as the default continuous normalizer. vmin, vmax : float, optional The minimum and maximum color scale values used with the `norm` normalizer. @@ -12563,7 +12512,7 @@ vmin, vmax : float, optional `vmin` and `vmax` are the minimum and maximum of the data values. N Shorthand for `levels`. -levels : int or sequence of float, default: :rc:`cmap.levels` +levels : int or sequence of float, default: [cmap.levels](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.levels) The number of level edges or a sequence of level edges. If the former, `locator` is used to generate this many level edges at "nice" intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing @@ -12571,31 +12520,31 @@ levels : int or sequence of float, default: :rc:`cmap.levels` values : int or sequence of float, default: None The number of level centers or a sequence of level centers. If the former, `locator` is used to generate this many level centers at "nice" intervals. - If the latter, levels are inferred using `~ultraplot.utils.edges`. + If the latter, levels are inferred using [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html). This will override any `levels` input. center_levels : bool, default False If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented. -robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` +robust : bool, float, or 2-tuple, default: [cmap.robust](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.robust) If ``True`` and `vmin` or `vmax` were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers. -inbounds : bool, default: :rc:`cmap.inbounds` +inbounds : bool, default: [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) If ``True`` and `vmin` or `vmax` were not provided, when axis limits - have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` - or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. - See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. -locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + have been explicitly restricted with [set_xlim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlim.html) + or [set_ylim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylim.html), out-of-bounds data is ignored. + See also [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) and [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds). +locator : locator-spec, default: [matplotlib.ticker.MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) The locator used to determine level locations if `levels` or `values` were not - already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. - Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. + already passed as lists. Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. + Default is [MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) with `levels` integer levels. locator_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Locator` class. + Keyword arguments passed to [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. symmetric : bool, default: False If ``True``, the normalization range or discrete colormap levels are symmetric about zero. @@ -12607,13 +12556,13 @@ negative : bool, default: False negative with a minimum at zero. nozero : bool, default: False If ``True``, ``0`` is removed from the level list. This is mainly useful for - single-color `~matplotlib.axes.Axes.contour` plots. -linewidths : unit-spec, default: 0.3 or :rc:`lines.linewidth` + single-color [contour](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.contour.html) plots. +linewidths : unit-spec, default: 0.3 or [lines.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.linewidth) The width of the line contours. Default is ``0.3`` when adding to filled contours - or :rc:`lines.linewidth` otherwise. Aliases: ``lw``, ``linewidth``. If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -linestyles : str, default: '-' or :rc:`contour.negative_linestyle` + or [lines.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.linewidth) otherwise. Aliases: ``lw``, ``linewidth``. If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +linestyles : str, default: '-' or [contour.negative_linestyle](https://ultraplot.readthedocs.io/en/stable/search.html?q=contour.negative_linestyle) The style of the line contours. Default is ``'-'`` for positive contours and - :rcraw:`contour.negative_linestyle` for negative contours. Aliases: ``ls``, ``linestyle``. + [contour.negative_linestyle](https://ultraplot.readthedocs.io/en/stable/search.html?q=contour.negative_linestyle) for negative contours. Aliases: ``ls``, ``linestyle``. edgecolors : color-spec, default: 'k' or inferred The color of the line contours. Default is ``'k'`` when adding to filled contours or inferred from `color` or `cmap` otherwise. Aliases: ``ec``, ``edgecolor``. @@ -12622,42 +12571,42 @@ alpha : float, optional label : str, optional The legend label to be used for this object. In the case of contours, this is paired with the the central artist in the artist - list returned by `matplotlib.contour.ContourSet.legend_elements`. + list returned by [matplotlib.contour.ContourSet.legend_elements](https://matplotlib.org/stable/api/_as_gen/matplotlib.contour.ContourSet.legend_elements.html). labels : bool, optional Whether to apply labels to contours and grid boxes. The text will be white when the luminance of the underlying filled contour or grid box is less than 50 and black otherwise. labels_kw : dict-like, optional Ignored if `labels` is ``False``. Extra keyword args for the labels. - For contour plots, this is passed to `~matplotlib.axes.Axes.clabel`. - Otherwise, this is passed to `~matplotlib.axes.Axes.text`. + For contour plots, this is passed to [clabel](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.clabel.html). + Otherwise, this is passed to [text](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.text.html). formatter, fmt : formatter-spec, optional - The `~matplotlib.ticker.Formatter` used to format number labels. - Passed to the `~ultraplot.constructor.Formatter` constructor. + The [Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) used to format number labels. + Passed to the [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html) constructor. formatter_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Formatter` class. + Keyword arguments passed to [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) class. precision : int, optional The maximum number of decimal places for number labels generated - with the default formatter `~ultraplot.ticker.Simpleformatter`. + with the default formatter [Simpleformatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.Simpleformatter.html). colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `matplotlib.axes.Axes.tricontour`. + Passed to [matplotlib.axes.Axes.tricontour](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.tricontour.html). See also -------- @@ -12707,7 +12656,7 @@ z : array-like levels : int or array-like, optional Determines the number and positions of the contour lines / regions. - If an int *n*, use `~matplotlib.ticker.MaxNLocator`, which tries to + If an int *n*, use [MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html), which tries to automatically choose no more than *n+1* "nice" contour levels between between minimum and maximum numeric values of *Z*. @@ -12716,11 +12665,11 @@ levels : int or array-like, optional Returns ------- -`~matplotlib.tri.TriContourSet` +[TriContourSet](https://matplotlib.org/stable/api/_as_gen/matplotlib.tri.TriContourSet.html) Other Parameters ---------------- -colors : :mpltype:`color` or list of :mpltype:`color`, optional +colors : [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color), optional The colors of the levels, i.e., the contour lines. The sequence is cycled for the levels in ascending order. If the sequence @@ -12736,13 +12685,13 @@ colors : :mpltype:`color` or list of :mpltype:`color`, optional alpha : float, default: 1 The alpha blending value, between 0 (transparent) and 1 (opaque). -cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap` +cmap : str or [Colormap](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Colormap.html), default: [image.cmap](https://ultraplot.readthedocs.io/en/stable/search.html?q=image.cmap) The Colormap instance or registered colormap name used to map scalar data to colors. This parameter is ignored if *colors* is set. -norm : str or `~matplotlib.colors.Normalize`, optional +norm : str or [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html), optional The normalization method used to scale scalar data to the [0, 1] range before mapping to colors using *cmap*. By default, a linear scaling is used, mapping the lowest value to 0 and the highest to 1. @@ -12750,9 +12699,9 @@ norm : str or `~matplotlib.colors.Normalize`, optional If given, this can be one of the following: - An instance of `.Normalize` or one of its subclasses - (see :ref:`colormapnorms`). + (see [colormapnorms](https://ultraplot.readthedocs.io/en/stable/search.html?q=colormapnorms)). - A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For a - list of available scales, call `matplotlib.scale.get_scale_names()`. + list of available scales, call [matplotlib.scale.get_scale_names()](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.get_scale_names().html). In that case, a suitable `.Normalize` subclass is dynamically generated and instantiated. @@ -12777,7 +12726,7 @@ origin : {*None*, 'upper', 'lower', 'image'}, default: None - *None*: ``z[0, 0]`` is at X=0, Y=0 in the lower left corner. - 'lower': ``z[0, 0]`` is at X=0.5, Y=0.5 in the lower left corner. - 'upper': ``z[0, 0]`` is at X=N+0.5, Y=0.5 in the upper left corner. - - 'image': Use the value from :rc:`image.origin`. + - 'image': Use the value from [image.origin](https://ultraplot.readthedocs.io/en/stable/search.html?q=image.origin). extent : (x0, x1, y0, y1), optional If *origin* is not *None*, then *extent* is interpreted as in `.imshow`: it @@ -12818,14 +12767,14 @@ extend : {'neither', 'both', 'min', 'max'}, default: 'neither' xunits, yunits : registered units, optional Override axis units by specifying an instance of a - :class:`matplotlib.units.ConversionInterface`. + [matplotlib.units.ConversionInterface](https://matplotlib.org/stable/api/_as_gen/matplotlib.units.ConversionInterface.html). antialiased : bool, optional Enable antialiasing, overriding the defaults. For filled contours, the default is *True*. For line contours, - it is taken from :rc:`lines.antialiased`. + it is taken from [lines.antialiased](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.antialiased). -linewidths : float or array-like, default: :rc:`contour.linewidth` +linewidths : float or array-like, default: [contour.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=contour.linewidth) The line width of the contour lines. If a number, all levels will be plotted with this linewidth. @@ -12833,12 +12782,12 @@ linewidths : float or array-like, default: :rc:`contour.linewidth` If a sequence, the levels in ascending order will be plotted with the linewidths in the order specified. - If None, this falls back to :rc:`lines.linewidth`. + If None, this falls back to [lines.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.linewidth). linestyles : {*None*, 'solid', 'dashed', 'dashdot', 'dotted'}, optional If *linestyles* is *None*, the default is 'solid' unless the lines are monochrome. In that case, negative contours will take their linestyle - from :rc:`contour.negative_linestyle` setting. + from [contour.negative_linestyle](https://ultraplot.readthedocs.io/en/stable/search.html?q=contour.negative_linestyle) setting. *linestyles* can also be an iterable of the above strings specifying a set of linestyles to be used. If this iterable is shorter than the @@ -12854,29 +12803,28 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `z` coordinates are passed, try to infer the `x` and `y` coordinates - from the :class:`~pandas.DataFrame` indices and columns or the :class:`~xarray.DataArray` + from the [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices and columns or the [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` and the `x` coordinates are ``np.arange(0, y.shape[1])``. * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using - `~ultraplot.utils.edges` or :func:`~ultraplot.utils.edges2d` if *centers* were provided. + [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html) or [edges2d](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges2d.html) if *centers* were provided. For all other methods, calculate coordinate *centers* if *edges* were provided. - * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the - `z` coordinates are `pint.Quantity`, pass the magnitude to the plotting - command. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If the `x` or `y` coordinates are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). If the + `z` coordinates are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), pass the magnitude to the plotting + command. A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). transpose : bool, default: False Whether to transpose the input data. This should be used when passing datasets with column-major dimension order ``(x, y)``. @@ -12886,7 +12834,7 @@ order : {'C', 'F'}, default: 'C' row-major ordering (equivalent to ``transpose=False``). ``'F'`` corresponds to Fortran-style column-major ordering (equivalent to ``transpose=True``). globe : bool, default: False - For `ultraplot.axes.GeoAxes` only. Whether to enforce global + For [ultraplot.axes.GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.GeoAxes.html) only. Whether to enforce global coverage. When set to ``True`` this does the following: #. Interpolates input data to the North and South poles by setting the data @@ -12899,42 +12847,42 @@ globe : bool, default: False Other parameters ---------------- -cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` - The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor - function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization - range contains negative and positive values then :rcraw:`cmap.diverging` is used. - Otherwise :rcraw:`cmap.sequential` is used. +cmap : colormap-spec, default: [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) or [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) + The colormap specifer, passed to the [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html) constructor + function. If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization + range contains negative and positive values then [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) is used. + Otherwise [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) is used. cmap_kw : dict-like, optional - Passed to :class:`~ultraplot.constructor.Colormap`. + Passed to [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html). c, color, colors : color-spec or sequence of color-spec, optional - The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + The color(s) used to create a [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html). If not passed, `cmap` is used. -norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` - The data value normalizer, passed to the `~ultraplot.constructor.Norm` +norm : norm-spec, default: [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) or [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) + The data value normalizer, passed to the [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html) constructor function. If `discrete` is ``True`` then 1) this affects the default level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and - 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they - are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). - If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains - negative and positive values then `~ultraplot.colors.DivergingNorm` is used. - Otherwise `~matplotlib.colors.Normalize` is used. + 2) this is passed to [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) to scale the colors before they + are discretized (if `norm` is not already a [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html)). + If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization range contains + negative and positive values then [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) is used. + Otherwise [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) is used. norm_kw : dict-like, optional - Passed to `~ultraplot.constructor.Norm`. + Passed to [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html). extend : {'neither', 'both', 'min', 'max'}, default: 'neither' Direction for drawing colorbar "extensions" indicating out-of-bounds data on the end of the colorbar. -discrete : bool, default: :rc:`cmap.discrete` - If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the +discrete : bool, default: [cmap.discrete](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.discrete) + If ``False``, then [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) is not applied to the colormap. Instead, for non-contour plots, the number of levels will be - roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + roughly controlled by [cmap.lut](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.lut). This has a similar effect to using `levels=large_number` but it may improve rendering speed. Default is - ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` - and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. + ``True`` only for contouring commands like [contourf](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.contourf) + and pseudocolor commands like [pcolor](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.pcolor). sequential, diverging, cyclic, qualitative : bool, default: None Boolean arguments used if `cmap` is not passed. Set these to ``True`` - to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, - :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. - The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + to use the default [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential), [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging), + [cmap.cyclic](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.cyclic), and [cmap.qualitative](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.qualitative) colormaps. + The `diverging` option also applies [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) as the default continuous normalizer. vmin, vmax : float, optional The minimum and maximum color scale values used with the `norm` normalizer. @@ -12947,7 +12895,7 @@ vmin, vmax : float, optional `vmin` and `vmax` are the minimum and maximum of the data values. N Shorthand for `levels`. -levels : int or sequence of float, default: :rc:`cmap.levels` +levels : int or sequence of float, default: [cmap.levels](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.levels) The number of level edges or a sequence of level edges. If the former, `locator` is used to generate this many level edges at "nice" intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing @@ -12955,31 +12903,31 @@ levels : int or sequence of float, default: :rc:`cmap.levels` values : int or sequence of float, default: None The number of level centers or a sequence of level centers. If the former, `locator` is used to generate this many level centers at "nice" intervals. - If the latter, levels are inferred using `~ultraplot.utils.edges`. + If the latter, levels are inferred using [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html). This will override any `levels` input. center_levels : bool, default False If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented. -robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` +robust : bool, float, or 2-tuple, default: [cmap.robust](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.robust) If ``True`` and `vmin` or `vmax` were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers. -inbounds : bool, default: :rc:`cmap.inbounds` +inbounds : bool, default: [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) If ``True`` and `vmin` or `vmax` were not provided, when axis limits - have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` - or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. - See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. -locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + have been explicitly restricted with [set_xlim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlim.html) + or [set_ylim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylim.html), out-of-bounds data is ignored. + See also [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) and [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds). +locator : locator-spec, default: [matplotlib.ticker.MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) The locator used to determine level locations if `levels` or `values` were not - already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. - Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. + already passed as lists. Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. + Default is [MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) with `levels` integer levels. locator_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Locator` class. + Keyword arguments passed to [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. symmetric : bool, default: False If ``True``, the normalization range or discrete colormap levels are symmetric about zero. @@ -12991,22 +12939,22 @@ negative : bool, default: False negative with a minimum at zero. nozero : bool, default: False If ``True``, ``0`` is removed from the level list. This is mainly useful for - single-color `~matplotlib.axes.Axes.contour` plots. -linewidths : unit-spec, default: 0.3 or :rc:`lines.linewidth` + single-color [contour](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.contour.html) plots. +linewidths : unit-spec, default: 0.3 or [lines.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.linewidth) The width of the line contours. Default is ``0.3`` when adding to filled contours - or :rc:`lines.linewidth` otherwise. Aliases: ``lw``, ``linewidth``. If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -linestyles : str, default: '-' or :rc:`contour.negative_linestyle` + or [lines.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.linewidth) otherwise. Aliases: ``lw``, ``linewidth``. If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +linestyles : str, default: '-' or [contour.negative_linestyle](https://ultraplot.readthedocs.io/en/stable/search.html?q=contour.negative_linestyle) The style of the line contours. Default is ``'-'`` for positive contours and - :rcraw:`contour.negative_linestyle` for negative contours. Aliases: ``ls``, ``linestyle``. + [contour.negative_linestyle](https://ultraplot.readthedocs.io/en/stable/search.html?q=contour.negative_linestyle) for negative contours. Aliases: ``ls``, ``linestyle``. edgecolors : color-spec, default: 'k' or inferred The color of the line contours. Default is ``'k'`` when adding to filled contours or inferred from `color` or `cmap` otherwise. Aliases: ``ec``, ``edgecolor``. alpha : float, optional The opacity of the contours. Inferred from `edgecolors` by default. Aliases: ``a``, ``alphas``. -edgefix : bool or float, default: :rc:`edgefix` +edgefix : bool or float, default: [edgefix](https://ultraplot.readthedocs.io/en/stable/search.html?q=edgefix) Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). - See this `github repo `__ for a + See this [github repo](https://github.com/jklymak/contourfIssues) for a demonstration of the problem. If ``True``, a small default linewidth of ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), this specific linewidth is used to cover up the white lines. This feature is @@ -13014,42 +12962,42 @@ edgefix : bool or float, default: :rc:`edgefix` label : str, optional The legend label to be used for this object. In the case of contours, this is paired with the the central artist in the artist - list returned by `matplotlib.contour.ContourSet.legend_elements`. + list returned by [matplotlib.contour.ContourSet.legend_elements](https://matplotlib.org/stable/api/_as_gen/matplotlib.contour.ContourSet.legend_elements.html). labels : bool, optional Whether to apply labels to contours and grid boxes. The text will be white when the luminance of the underlying filled contour or grid box is less than 50 and black otherwise. labels_kw : dict-like, optional Ignored if `labels` is ``False``. Extra keyword args for the labels. - For contour plots, this is passed to `~matplotlib.axes.Axes.clabel`. - Otherwise, this is passed to `~matplotlib.axes.Axes.text`. + For contour plots, this is passed to [clabel](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.clabel.html). + Otherwise, this is passed to [text](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.text.html). formatter, fmt : formatter-spec, optional - The `~matplotlib.ticker.Formatter` used to format number labels. - Passed to the `~ultraplot.constructor.Formatter` constructor. + The [Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) used to format number labels. + Passed to the [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html) constructor. formatter_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Formatter` class. + Keyword arguments passed to [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) class. precision : int, optional The maximum number of decimal places for number labels generated - with the default formatter `~ultraplot.ticker.Simpleformatter`. + with the default formatter [Simpleformatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.Simpleformatter.html). colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `matplotlib.axes.Axes.tricontourf`. + Passed to [matplotlib.axes.Axes.tricontourf](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.tricontourf.html). See also -------- @@ -13099,7 +13047,7 @@ z : array-like levels : int or array-like, optional Determines the number and positions of the contour lines / regions. - If an int *n*, use `~matplotlib.ticker.MaxNLocator`, which tries to + If an int *n*, use [MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html), which tries to automatically choose no more than *n+1* "nice" contour levels between between minimum and maximum numeric values of *Z*. @@ -13108,11 +13056,11 @@ levels : int or array-like, optional Returns ------- -`~matplotlib.tri.TriContourSet` +[TriContourSet](https://matplotlib.org/stable/api/_as_gen/matplotlib.tri.TriContourSet.html) Other Parameters ---------------- -colors : :mpltype:`color` or list of :mpltype:`color`, optional +colors : [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color), optional The colors of the levels, i.e., the contour regions. The sequence is cycled for the levels in ascending order. If the sequence @@ -13128,13 +13076,13 @@ colors : :mpltype:`color` or list of :mpltype:`color`, optional alpha : float, default: 1 The alpha blending value, between 0 (transparent) and 1 (opaque). -cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap` +cmap : str or [Colormap](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Colormap.html), default: [image.cmap](https://ultraplot.readthedocs.io/en/stable/search.html?q=image.cmap) The Colormap instance or registered colormap name used to map scalar data to colors. This parameter is ignored if *colors* is set. -norm : str or `~matplotlib.colors.Normalize`, optional +norm : str or [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html), optional The normalization method used to scale scalar data to the [0, 1] range before mapping to colors using *cmap*. By default, a linear scaling is used, mapping the lowest value to 0 and the highest to 1. @@ -13142,9 +13090,9 @@ norm : str or `~matplotlib.colors.Normalize`, optional If given, this can be one of the following: - An instance of `.Normalize` or one of its subclasses - (see :ref:`colormapnorms`). + (see [colormapnorms](https://ultraplot.readthedocs.io/en/stable/search.html?q=colormapnorms)). - A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For a - list of available scales, call `matplotlib.scale.get_scale_names()`. + list of available scales, call [matplotlib.scale.get_scale_names()](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.get_scale_names().html). In that case, a suitable `.Normalize` subclass is dynamically generated and instantiated. @@ -13169,7 +13117,7 @@ origin : {*None*, 'upper', 'lower', 'image'}, default: None - *None*: ``z[0, 0]`` is at X=0, Y=0 in the lower left corner. - 'lower': ``z[0, 0]`` is at X=0.5, Y=0.5 in the lower left corner. - 'upper': ``z[0, 0]`` is at X=N+0.5, Y=0.5 in the upper left corner. - - 'image': Use the value from :rc:`image.origin`. + - 'image': Use the value from [image.origin](https://ultraplot.readthedocs.io/en/stable/search.html?q=image.origin). extent : (x0, x1, y0, y1), optional If *origin* is not *None*, then *extent* is interpreted as in `.imshow`: it @@ -13210,12 +13158,12 @@ extend : {'neither', 'both', 'min', 'max'}, default: 'neither' xunits, yunits : registered units, optional Override axis units by specifying an instance of a - :class:`matplotlib.units.ConversionInterface`. + [matplotlib.units.ConversionInterface](https://matplotlib.org/stable/api/_as_gen/matplotlib.units.ConversionInterface.html). antialiased : bool, optional Enable antialiasing, overriding the defaults. For filled contours, the default is *True*. For line contours, - it is taken from :rc:`lines.antialiased`. + it is taken from [lines.antialiased](https://ultraplot.readthedocs.io/en/stable/search.html?q=lines.antialiased). hatches : list[str], optional A list of crosshatch patterns to use on the filled areas. @@ -13241,29 +13189,28 @@ Parameters The data passed as positional or keyword arguments. Interpreted as follows: * If only `z` coordinates are passed, try to infer the `x` and `y` coordinates - from the :class:`~pandas.DataFrame` indices and columns or the :class:`~xarray.DataArray` + from the [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) indices and columns or the [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])`` and the `x` coordinates are ``np.arange(0, y.shape[1])``. * For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using - `~ultraplot.utils.edges` or :func:`~ultraplot.utils.edges2d` if *centers* were provided. + [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html) or [edges2d](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges2d.html) if *centers* were provided. For all other methods, calculate coordinate *centers* if *edges* were provided. - * If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry - to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the - `z` coordinates are `pint.Quantity`, pass the magnitude to the plotting - command. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported. + * If the `x` or `y` coordinates are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), auto-add the pint unit registry + to matplotlib's unit registry using [setup_matplotlib](https://pint.readthedocs.io/en/stable/search.html?q=pint.UnitRegistry.setup_matplotlib). If the + `z` coordinates are [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity), pass the magnitude to the plotting + command. A [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) embedded in an [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) is also supported. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). transpose : bool, default: False Whether to transpose the input data. This should be used when passing datasets with column-major dimension order ``(x, y)``. @@ -13273,7 +13220,7 @@ order : {'C', 'F'}, default: 'C' row-major ordering (equivalent to ``transpose=False``). ``'F'`` corresponds to Fortran-style column-major ordering (equivalent to ``transpose=True``). globe : bool, default: False - For `ultraplot.axes.GeoAxes` only. Whether to enforce global + For [ultraplot.axes.GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.GeoAxes.html) only. Whether to enforce global coverage. When set to ``True`` this does the following: #. Interpolates input data to the North and South poles by setting the data @@ -13286,42 +13233,42 @@ globe : bool, default: False Other parameters ---------------- -cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` - The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor - function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization - range contains negative and positive values then :rcraw:`cmap.diverging` is used. - Otherwise :rcraw:`cmap.sequential` is used. +cmap : colormap-spec, default: [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) or [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) + The colormap specifer, passed to the [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html) constructor + function. If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization + range contains negative and positive values then [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) is used. + Otherwise [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) is used. cmap_kw : dict-like, optional - Passed to :class:`~ultraplot.constructor.Colormap`. + Passed to [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html). c, color, colors : color-spec or sequence of color-spec, optional - The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + The color(s) used to create a [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html). If not passed, `cmap` is used. -norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` - The data value normalizer, passed to the `~ultraplot.constructor.Norm` +norm : norm-spec, default: [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) or [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) + The data value normalizer, passed to the [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html) constructor function. If `discrete` is ``True`` then 1) this affects the default level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and - 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they - are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). - If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains - negative and positive values then `~ultraplot.colors.DivergingNorm` is used. - Otherwise `~matplotlib.colors.Normalize` is used. + 2) this is passed to [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) to scale the colors before they + are discretized (if `norm` is not already a [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html)). + If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization range contains + negative and positive values then [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) is used. + Otherwise [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) is used. norm_kw : dict-like, optional - Passed to `~ultraplot.constructor.Norm`. + Passed to [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html). extend : {'neither', 'both', 'min', 'max'}, default: 'neither' Direction for drawing colorbar "extensions" indicating out-of-bounds data on the end of the colorbar. -discrete : bool, default: :rc:`cmap.discrete` - If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the +discrete : bool, default: [cmap.discrete](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.discrete) + If ``False``, then [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) is not applied to the colormap. Instead, for non-contour plots, the number of levels will be - roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + roughly controlled by [cmap.lut](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.lut). This has a similar effect to using `levels=large_number` but it may improve rendering speed. Default is - ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` - and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. + ``True`` only for contouring commands like [contourf](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.contourf) + and pseudocolor commands like [pcolor](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.pcolor). sequential, diverging, cyclic, qualitative : bool, default: None Boolean arguments used if `cmap` is not passed. Set these to ``True`` - to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, - :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. - The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + to use the default [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential), [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging), + [cmap.cyclic](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.cyclic), and [cmap.qualitative](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.qualitative) colormaps. + The `diverging` option also applies [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) as the default continuous normalizer. vmin, vmax : float, optional The minimum and maximum color scale values used with the `norm` normalizer. @@ -13334,7 +13281,7 @@ vmin, vmax : float, optional `vmin` and `vmax` are the minimum and maximum of the data values. N Shorthand for `levels`. -levels : int or sequence of float, default: :rc:`cmap.levels` +levels : int or sequence of float, default: [cmap.levels](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.levels) The number of level edges or a sequence of level edges. If the former, `locator` is used to generate this many level edges at "nice" intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing @@ -13342,31 +13289,31 @@ levels : int or sequence of float, default: :rc:`cmap.levels` values : int or sequence of float, default: None The number of level centers or a sequence of level centers. If the former, `locator` is used to generate this many level centers at "nice" intervals. - If the latter, levels are inferred using `~ultraplot.utils.edges`. + If the latter, levels are inferred using [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html). This will override any `levels` input. center_levels : bool, default False If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented. -robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` +robust : bool, float, or 2-tuple, default: [cmap.robust](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.robust) If ``True`` and `vmin` or `vmax` were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers. -inbounds : bool, default: :rc:`cmap.inbounds` +inbounds : bool, default: [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) If ``True`` and `vmin` or `vmax` were not provided, when axis limits - have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` - or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. - See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. -locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + have been explicitly restricted with [set_xlim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlim.html) + or [set_ylim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylim.html), out-of-bounds data is ignored. + See also [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) and [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds). +locator : locator-spec, default: [matplotlib.ticker.MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) The locator used to determine level locations if `levels` or `values` were not - already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. - Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. + already passed as lists. Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. + Default is [MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) with `levels` integer levels. locator_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Locator` class. + Keyword arguments passed to [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. symmetric : bool, default: False If ``True``, the normalization range or discrete colormap levels are symmetric about zero. @@ -13378,20 +13325,20 @@ negative : bool, default: False negative with a minimum at zero. nozero : bool, default: False If ``True``, ``0`` is removed from the level list. This is mainly useful for - single-color `~matplotlib.axes.Axes.contour` plots. + single-color [contour](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.contour.html) plots. linewidths : unit-spec, default: 0.3 The width of lines between grid boxes. Aliases: ``lw``, ``linewidth``. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). linestyles : str, default: '-' The style of lines between grid boxes. Aliases: ``ls``, ``linestyle``. edgecolors : color-spec, default: 'k' The color of lines between grid boxes. Aliases: ``ec``, ``edgecolor``. alpha : float, optional The opacity of the grid boxes. Inferred from `cmap` by default. Aliases: ``a``, ``alphas``. -edgefix : bool or float, default: :rc:`edgefix` +edgefix : bool or float, default: [edgefix](https://ultraplot.readthedocs.io/en/stable/search.html?q=edgefix) Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). - See this `github repo `__ for a + See this [github repo](https://github.com/jklymak/contourfIssues) for a demonstration of the problem. If ``True``, a small default linewidth of ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), this specific linewidth is used to cover up the white lines. This feature is @@ -13399,42 +13346,42 @@ edgefix : bool or float, default: :rc:`edgefix` label : str, optional The legend label to be used for this object. In the case of contours, this is paired with the the central artist in the artist - list returned by `matplotlib.contour.ContourSet.legend_elements`. + list returned by [matplotlib.contour.ContourSet.legend_elements](https://matplotlib.org/stable/api/_as_gen/matplotlib.contour.ContourSet.legend_elements.html). labels : bool, optional Whether to apply labels to contours and grid boxes. The text will be white when the luminance of the underlying filled contour or grid box is less than 50 and black otherwise. labels_kw : dict-like, optional Ignored if `labels` is ``False``. Extra keyword args for the labels. - For contour plots, this is passed to `~matplotlib.axes.Axes.clabel`. - Otherwise, this is passed to `~matplotlib.axes.Axes.text`. + For contour plots, this is passed to [clabel](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.clabel.html). + Otherwise, this is passed to [text](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.text.html). formatter, fmt : formatter-spec, optional - The `~matplotlib.ticker.Formatter` used to format number labels. - Passed to the `~ultraplot.constructor.Formatter` constructor. + The [Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) used to format number labels. + Passed to the [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html) constructor. formatter_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Formatter` class. + Keyword arguments passed to [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) class. precision : int, optional The maximum number of decimal places for number labels generated - with the default formatter `~ultraplot.ticker.Simpleformatter`. + with the default formatter [Simpleformatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.Simpleformatter.html). colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `matplotlib.axes.Axes.tripcolor`. + Passed to [matplotlib.axes.Axes.tripcolor](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.tripcolor.html). See also -------- @@ -13494,11 +13441,11 @@ shading : {'flat', 'gouraud'}, default: 'flat' values used for each triangle are from the mean c of the triangle's three points. If *shading* is 'gouraud' then color values must be defined at points. -cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap` +cmap : str or [Colormap](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Colormap.html), default: [image.cmap](https://ultraplot.readthedocs.io/en/stable/search.html?q=image.cmap) The Colormap instance or registered colormap name used to map scalar data to colors. -norm : str or `~matplotlib.colors.Normalize`, optional +norm : str or [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html), optional The normalization method used to scale scalar data to the [0, 1] range before mapping to colors using *cmap*. By default, a linear scaling is used, mapping the lowest value to 0 and the highest to 1. @@ -13506,9 +13453,9 @@ norm : str or `~matplotlib.colors.Normalize`, optional If given, this can be one of the following: - An instance of `.Normalize` or one of its subclasses - (see :ref:`colormapnorms`). + (see [colormapnorms](https://ultraplot.readthedocs.io/en/stable/search.html?q=colormapnorms)). - A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For a - list of available scales, call `matplotlib.scale.get_scale_names()`. + list of available scales, call [matplotlib.scale.get_scale_names()](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.get_scale_names().html). In that case, a suitable `.Normalize` subclass is dynamically generated and instantiated. @@ -13519,19 +13466,19 @@ vmin, vmax : float, optional *vmin*/*vmax* when a *norm* instance is given (but using a `str` *norm* name together with *vmin*/*vmax* is acceptable). -colorizer : `~matplotlib.colorizer.Colorizer` or None, default: None +colorizer : [Colorizer](https://matplotlib.org/stable/api/_as_gen/matplotlib.colorizer.Colorizer.html) or None, default: None The Colorizer object used to map color to data. If None, a Colorizer object is created from a *norm* and *cmap*. Returns ------- -`~matplotlib.collections.PolyCollection` or `~matplotlib.collections.TriMesh` +[PolyCollection](https://matplotlib.org/stable/api/_as_gen/matplotlib.collections.PolyCollection.html) or [TriMesh](https://matplotlib.org/stable/api/_as_gen/matplotlib.collections.TriMesh.html) The result depends on *shading*: For ``shading='flat'`` the result is a `.PolyCollection`, for ``shading='gouraud'`` the result is a `.TriMesh`. Other Parameters ---------------- -**kwargs : `~matplotlib.collections.Collection` properties +**kwargs : [Collection](https://matplotlib.org/stable/api/_as_gen/matplotlib.collections.Collection.html) properties Properties: agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image @@ -13541,14 +13488,14 @@ Other Parameters array: array-like or None capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} clim: (vmin: float, vmax: float) - clip_box: `~matplotlib.transforms.BboxBase` or None + clip_box: [BboxBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.BboxBase.html) or None clip_on: bool clip_path: Patch or (Path, Transform) or None cmap: `.Colormap` or str or None - color: :mpltype:`color` or list of RGBA tuples - edgecolor or ec or edgecolors: :mpltype:`color` or list of :mpltype:`color` or 'face' - facecolor or facecolors or fc: :mpltype:`color` or list of :mpltype:`color` - figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + color: [color](https://matplotlib.org/stable/search.html?q=color) or list of RGBA tuples + edgecolor or ec or edgecolors: [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color) or 'face' + facecolor or facecolors or fc: [color](https://matplotlib.org/stable/search.html?q=color) or list of [color](https://matplotlib.org/stable/search.html?q=color) + figure: [Figure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html) or [SubFigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.SubFigure.html) gid: str hatch: {'/', '\\\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'} hatch_linewidth: unknown @@ -13568,7 +13515,7 @@ Other Parameters rasterized: bool sketch_params: (scale: float, length: float, randomness: float) snap: bool or None - transform: `~matplotlib.transforms.Transform` + transform: [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html) url: str urls: list of str or None visible: bool @@ -13583,56 +13530,55 @@ Parameters z : array-like The data passed as a positional argument or keyword argument. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- -cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` - The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor - function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization - range contains negative and positive values then :rcraw:`cmap.diverging` is used. - Otherwise :rcraw:`cmap.sequential` is used. +cmap : colormap-spec, default: [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) or [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) + The colormap specifer, passed to the [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html) constructor + function. If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization + range contains negative and positive values then [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) is used. + Otherwise [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) is used. cmap_kw : dict-like, optional - Passed to :class:`~ultraplot.constructor.Colormap`. + Passed to [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html). c, color, colors : color-spec or sequence of color-spec, optional - The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + The color(s) used to create a [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html). If not passed, `cmap` is used. -norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` - The data value normalizer, passed to the `~ultraplot.constructor.Norm` +norm : norm-spec, default: [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) or [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) + The data value normalizer, passed to the [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html) constructor function. If `discrete` is ``True`` then 1) this affects the default level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and - 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they - are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). - If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains - negative and positive values then `~ultraplot.colors.DivergingNorm` is used. - Otherwise `~matplotlib.colors.Normalize` is used. + 2) this is passed to [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) to scale the colors before they + are discretized (if `norm` is not already a [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html)). + If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization range contains + negative and positive values then [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) is used. + Otherwise [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) is used. norm_kw : dict-like, optional - Passed to `~ultraplot.constructor.Norm`. + Passed to [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html). extend : {'neither', 'both', 'min', 'max'}, default: 'neither' Direction for drawing colorbar "extensions" indicating out-of-bounds data on the end of the colorbar. -discrete : bool, default: :rc:`cmap.discrete` - If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the +discrete : bool, default: [cmap.discrete](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.discrete) + If ``False``, then [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) is not applied to the colormap. Instead, for non-contour plots, the number of levels will be - roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + roughly controlled by [cmap.lut](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.lut). This has a similar effect to using `levels=large_number` but it may improve rendering speed. Default is - ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` - and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. + ``True`` only for contouring commands like [contourf](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.contourf) + and pseudocolor commands like [pcolor](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.pcolor). sequential, diverging, cyclic, qualitative : bool, default: None Boolean arguments used if `cmap` is not passed. Set these to ``True`` - to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, - :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. - The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + to use the default [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential), [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging), + [cmap.cyclic](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.cyclic), and [cmap.qualitative](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.qualitative) colormaps. + The `diverging` option also applies [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) as the default continuous normalizer. vmin, vmax : float, optional The minimum and maximum color scale values used with the `norm` normalizer. @@ -13645,7 +13591,7 @@ vmin, vmax : float, optional `vmin` and `vmax` are the minimum and maximum of the data values. N Shorthand for `levels`. -levels : int or sequence of float, default: :rc:`cmap.levels` +levels : int or sequence of float, default: [cmap.levels](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.levels) The number of level edges or a sequence of level edges. If the former, `locator` is used to generate this many level edges at "nice" intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing @@ -13653,31 +13599,31 @@ levels : int or sequence of float, default: :rc:`cmap.levels` values : int or sequence of float, default: None The number of level centers or a sequence of level centers. If the former, `locator` is used to generate this many level centers at "nice" intervals. - If the latter, levels are inferred using `~ultraplot.utils.edges`. + If the latter, levels are inferred using [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html). This will override any `levels` input. center_levels : bool, default False If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented. -robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` +robust : bool, float, or 2-tuple, default: [cmap.robust](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.robust) If ``True`` and `vmin` or `vmax` were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers. -inbounds : bool, default: :rc:`cmap.inbounds` +inbounds : bool, default: [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) If ``True`` and `vmin` or `vmax` were not provided, when axis limits - have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` - or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. - See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. -locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + have been explicitly restricted with [set_xlim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlim.html) + or [set_ylim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylim.html), out-of-bounds data is ignored. + See also [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) and [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds). +locator : locator-spec, default: [matplotlib.ticker.MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) The locator used to determine level locations if `levels` or `values` were not - already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. - Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. + already passed as lists. Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. + Default is [MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) with `levels` integer levels. locator_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Locator` class. + Keyword arguments passed to [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. symmetric : bool, default: False If ``True``, the normalization range or discrete colormap levels are symmetric about zero. @@ -13689,26 +13635,26 @@ negative : bool, default: False negative with a minimum at zero. nozero : bool, default: False If ``True``, ``0`` is removed from the level list. This is mainly useful for - single-color `~matplotlib.axes.Axes.contour` plots. + single-color [contour](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.contour.html) plots. colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `matplotlib.axes.Axes.imshow`. + Passed to [matplotlib.axes.Axes.imshow](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.imshow.html). See also -------- @@ -13729,9 +13675,9 @@ The number of pixels used to render an image is set by the Axes size and the figure *dpi*. This can lead to aliasing artifacts when the image is resampled, because the displayed image size will usually not match the size of *X* (see -:doc:`/gallery/images_contours_and_fields/image_antialiasing`). +[/gallery/images_contours_and_fields/image_antialiasing](https://ultraplot.readthedocs.io/en/stable/search.html?q=%2Fgallery%2Fimages_contours_and_fields%2Fimage_antialiasing)). The resampling can be controlled via the *interpolation* parameter -and/or :rc:`image.interpolation`. +and/or [image.interpolation](https://ultraplot.readthedocs.io/en/stable/search.html?q=image.interpolation). Parameters ---------- @@ -13750,13 +13696,13 @@ X : array-like or PIL image Out-of-range RGB(A) values are clipped. -cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap` +cmap : str or [Colormap](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Colormap.html), default: [image.cmap](https://ultraplot.readthedocs.io/en/stable/search.html?q=image.cmap) The Colormap instance or registered colormap name used to map scalar data to colors. This parameter is ignored if *X* is RGB(A). -norm : str or `~matplotlib.colors.Normalize`, optional +norm : str or [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html), optional The normalization method used to scale scalar data to the [0, 1] range before mapping to colors using *cmap*. By default, a linear scaling is used, mapping the lowest value to 0 and the highest to 1. @@ -13764,9 +13710,9 @@ norm : str or `~matplotlib.colors.Normalize`, optional If given, this can be one of the following: - An instance of `.Normalize` or one of its subclasses - (see :ref:`colormapnorms`). + (see [colormapnorms](https://ultraplot.readthedocs.io/en/stable/search.html?q=colormapnorms)). - A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For a - list of available scales, call `matplotlib.scale.get_scale_names()`. + list of available scales, call [matplotlib.scale.get_scale_names()](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.get_scale_names().html). In that case, a suitable `.Normalize` subclass is dynamically generated and instantiated. @@ -13781,7 +13727,7 @@ vmin, vmax : float, optional This parameter is ignored if *X* is RGB(A). -colorizer : `~matplotlib.colorizer.Colorizer` or None, default: None +colorizer : [Colorizer](https://matplotlib.org/stable/api/_as_gen/matplotlib.colorizer.Colorizer.html) or None, default: None The Colorizer object used to map color to data. If None, a Colorizer object is created from a *norm* and *cmap*. @@ -13802,12 +13748,12 @@ aspect : {'equal', 'auto'} or float or None, default: None that the data fit in the Axes. In general, this will result in non-square pixels. - Normally, None (the default) means to use :rc:`image.aspect`. However, if + Normally, None (the default) means to use [image.aspect](https://ultraplot.readthedocs.io/en/stable/search.html?q=image.aspect). However, if the image uses a transform that does not contain the axes data transform, then None means to not modify the axes aspect at all (in that case, directly call `.Axes.set_aspect` if desired). -interpolation : str, default: :rc:`image.interpolation` +interpolation : str, default: [image.interpolation](https://ultraplot.readthedocs.io/en/stable/search.html?q=image.interpolation) The interpolation method used. Supported values are 'none', 'auto', 'nearest', 'bilinear', @@ -13834,9 +13780,9 @@ interpolation : str, default: :rc:`image.interpolation` image happens to be upsampled by exactly a factor of two or one. See - :doc:`/gallery/images_contours_and_fields/interpolation_methods` + [/gallery/images_contours_and_fields/interpolation_methods](https://ultraplot.readthedocs.io/en/stable/search.html?q=%2Fgallery%2Fimages_contours_and_fields%2Finterpolation_methods) for an overview of the supported interpolation methods, and - :doc:`/gallery/images_contours_and_fields/image_antialiasing` for + [/gallery/images_contours_and_fields/image_antialiasing](https://ultraplot.readthedocs.io/en/stable/search.html?q=%2Fgallery%2Fimages_contours_and_fields%2Fimage_antialiasing) for a discussion of image antialiasing. Some interpolation methods require an additional radius parameter, @@ -13855,7 +13801,7 @@ interpolation_stage : {'auto', 'data', 'rgba'}, default: 'auto' 'rgba' when downsampling, or upsampling at a rate less than 3, and 'data' when upsampling at a higher rate. - See :doc:`/gallery/images_contours_and_fields/image_antialiasing` for + See [/gallery/images_contours_and_fields/image_antialiasing](https://ultraplot.readthedocs.io/en/stable/search.html?q=%2Fgallery%2Fimages_contours_and_fields%2Fimage_antialiasing) for a discussion of image antialiasing. alpha : float or array-like, optional @@ -13863,7 +13809,7 @@ alpha : float or array-like, optional If *alpha* is an array, the alpha blending values are applied pixel by pixel, and *alpha* must have the same shape as *X*. -origin : {'upper', 'lower'}, default: :rc:`image.origin` +origin : {'upper', 'lower'}, default: [image.origin](https://ultraplot.readthedocs.io/en/stable/search.html?q=image.origin) Place the [0, 0] index of the array in the upper left or lower left corner of the Axes. The convention (the default) 'upper' is typically used for matrices and images. @@ -13871,7 +13817,7 @@ origin : {'upper', 'lower'}, default: :rc:`image.origin` Note that the vertical axis points upward for 'lower' but downward for 'upper'. - See the :ref:`imshow_extent` tutorial for + See the [imshow_extent](https://ultraplot.readthedocs.io/en/stable/search.html?q=imshow_extent) tutorial for examples and a more detailed description. extent : floats (left, right, bottom, top), optional @@ -13892,7 +13838,7 @@ extent : floats (left, right, bottom, top), optional - For ``origin == 'lower'`` the default is ``(-0.5, numcols-0.5, -0.5, numrows-0.5)``. - See the :ref:`imshow_extent` tutorial for + See the [imshow_extent](https://ultraplot.readthedocs.io/en/stable/search.html?q=imshow_extent) tutorial for examples and a more detailed description. filternorm : bool, default: True @@ -13908,7 +13854,7 @@ filterrad : float > 0, default: 4.0 The filter radius for filters that have a radius parameter, i.e. when interpolation is one of: 'sinc', 'lanczos' or 'blackman'. -resample : bool, default: :rc:`image.resample` +resample : bool, default: [image.resample](https://ultraplot.readthedocs.io/en/stable/search.html?q=image.resample) When *True*, use a full resampling method. When *False*, only resample when the output image is larger than the input image. @@ -13917,7 +13863,7 @@ url : str, optional Returns ------- -`~matplotlib.image.AxesImage` +[AxesImage](https://matplotlib.org/stable/api/_as_gen/matplotlib.image.AxesImage.html) Other Parameters ---------------- @@ -13925,7 +13871,7 @@ data : indexable object, optional If given, all parameters also accept a string ``s``, which is interpreted as ``data[s]`` if ``s`` is a key in ``data``. -**kwargs : `~matplotlib.artist.Artist` properties +**kwargs : [Artist](https://matplotlib.org/stable/api/_as_gen/matplotlib.artist.Artist.html) properties These parameters are passed on to the constructor of the `.AxesImage` artist. @@ -13947,7 +13893,7 @@ channel: - Premultiplied (associated) alpha: R, G, and B channels represent the color of the pixel, adjusted for its opacity by multiplication. -`~matplotlib.pyplot.imshow` expects RGB images adopting the straight +[imshow](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.imshow.html) expects RGB images adopting the straight (unassociated) alpha representation.""" ... @@ -13959,56 +13905,55 @@ Parameters z : array-like The data passed as a positional argument or keyword argument. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- -cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` - The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor - function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization - range contains negative and positive values then :rcraw:`cmap.diverging` is used. - Otherwise :rcraw:`cmap.sequential` is used. +cmap : colormap-spec, default: [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) or [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) + The colormap specifer, passed to the [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html) constructor + function. If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization + range contains negative and positive values then [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) is used. + Otherwise [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) is used. cmap_kw : dict-like, optional - Passed to :class:`~ultraplot.constructor.Colormap`. + Passed to [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html). c, color, colors : color-spec or sequence of color-spec, optional - The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + The color(s) used to create a [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html). If not passed, `cmap` is used. -norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` - The data value normalizer, passed to the `~ultraplot.constructor.Norm` +norm : norm-spec, default: [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) or [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) + The data value normalizer, passed to the [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html) constructor function. If `discrete` is ``True`` then 1) this affects the default level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and - 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they - are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). - If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains - negative and positive values then `~ultraplot.colors.DivergingNorm` is used. - Otherwise `~matplotlib.colors.Normalize` is used. + 2) this is passed to [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) to scale the colors before they + are discretized (if `norm` is not already a [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html)). + If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization range contains + negative and positive values then [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) is used. + Otherwise [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) is used. norm_kw : dict-like, optional - Passed to `~ultraplot.constructor.Norm`. + Passed to [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html). extend : {'neither', 'both', 'min', 'max'}, default: 'neither' Direction for drawing colorbar "extensions" indicating out-of-bounds data on the end of the colorbar. -discrete : bool, default: :rc:`cmap.discrete` - If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the +discrete : bool, default: [cmap.discrete](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.discrete) + If ``False``, then [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) is not applied to the colormap. Instead, for non-contour plots, the number of levels will be - roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + roughly controlled by [cmap.lut](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.lut). This has a similar effect to using `levels=large_number` but it may improve rendering speed. Default is - ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` - and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. + ``True`` only for contouring commands like [contourf](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.contourf) + and pseudocolor commands like [pcolor](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.pcolor). sequential, diverging, cyclic, qualitative : bool, default: None Boolean arguments used if `cmap` is not passed. Set these to ``True`` - to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, - :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. - The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + to use the default [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential), [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging), + [cmap.cyclic](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.cyclic), and [cmap.qualitative](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.qualitative) colormaps. + The `diverging` option also applies [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) as the default continuous normalizer. vmin, vmax : float, optional The minimum and maximum color scale values used with the `norm` normalizer. @@ -14021,7 +13966,7 @@ vmin, vmax : float, optional `vmin` and `vmax` are the minimum and maximum of the data values. N Shorthand for `levels`. -levels : int or sequence of float, default: :rc:`cmap.levels` +levels : int or sequence of float, default: [cmap.levels](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.levels) The number of level edges or a sequence of level edges. If the former, `locator` is used to generate this many level edges at "nice" intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing @@ -14029,31 +13974,31 @@ levels : int or sequence of float, default: :rc:`cmap.levels` values : int or sequence of float, default: None The number of level centers or a sequence of level centers. If the former, `locator` is used to generate this many level centers at "nice" intervals. - If the latter, levels are inferred using `~ultraplot.utils.edges`. + If the latter, levels are inferred using [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html). This will override any `levels` input. center_levels : bool, default False If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented. -robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` +robust : bool, float, or 2-tuple, default: [cmap.robust](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.robust) If ``True`` and `vmin` or `vmax` were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers. -inbounds : bool, default: :rc:`cmap.inbounds` +inbounds : bool, default: [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) If ``True`` and `vmin` or `vmax` were not provided, when axis limits - have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` - or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. - See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. -locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + have been explicitly restricted with [set_xlim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlim.html) + or [set_ylim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylim.html), out-of-bounds data is ignored. + See also [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) and [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds). +locator : locator-spec, default: [matplotlib.ticker.MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) The locator used to determine level locations if `levels` or `values` were not - already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. - Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. + already passed as lists. Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. + Default is [MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) with `levels` integer levels. locator_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Locator` class. + Keyword arguments passed to [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. symmetric : bool, default: False If ``True``, the normalization range or discrete colormap levels are symmetric about zero. @@ -14065,26 +14010,26 @@ negative : bool, default: False negative with a minimum at zero. nozero : bool, default: False If ``True``, ``0`` is removed from the level list. This is mainly useful for - single-color `~matplotlib.axes.Axes.contour` plots. + single-color [contour](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.contour.html) plots. colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `matplotlib.axes.Axes.matshow`. + Passed to [matplotlib.axes.Axes.matshow](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.matshow.html). See also -------- @@ -14106,11 +14051,11 @@ Z : (M, N) array-like Returns ------- -`~matplotlib.image.AxesImage` +[AxesImage](https://matplotlib.org/stable/api/_as_gen/matplotlib.image.AxesImage.html) Other Parameters ---------------- -**kwargs : `~matplotlib.axes.Axes.imshow` arguments +**kwargs : [imshow](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.imshow.html) arguments See Also -------- @@ -14136,56 +14081,55 @@ Parameters z : array-like The data passed as a positional argument or keyword argument. data : dict-like, optional - A dict-like dataset container (e.g., :class:`~pandas.DataFrame` or - `~xarray.Dataset`). If passed, each data argument can optionally + A dict-like dataset container (e.g., [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) or + [Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)). If passed, each data argument can optionally be a string `key` and the arrays used for plotting are retrieved - with ``data[key]``. This is a `native matplotlib feature - `__. -autoformat : bool, default: :rc:`autoformat` + with ``data[key]``. This is a [native matplotlib feature](https://matplotlib.org/stable/gallery/misc/keyword_plotting.html). +autoformat : bool, default: [autoformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=autoformat) Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a - `~pandas.Series`, :class:`~pandas.DataFrame`, :class:`~xarray.DataArray`, or `~pint.Quantity` - is passed to the plotting command. Formatting of `pint.Quantity` - unit strings is controlled by :rc:`unitformat`. + [Series](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html), [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html), [DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html), or [Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + is passed to the plotting command. Formatting of [pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity) + unit strings is controlled by [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat). Other parameters ---------------- -cmap : colormap-spec, default: :rc:`cmap.sequential` or :rc:`cmap.diverging` - The colormap specifer, passed to the :class:`~ultraplot.constructor.Colormap` constructor - function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization - range contains negative and positive values then :rcraw:`cmap.diverging` is used. - Otherwise :rcraw:`cmap.sequential` is used. +cmap : colormap-spec, default: [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) or [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) + The colormap specifer, passed to the [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html) constructor + function. If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization + range contains negative and positive values then [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging) is used. + Otherwise [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential) is used. cmap_kw : dict-like, optional - Passed to :class:`~ultraplot.constructor.Colormap`. + Passed to [Colormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Colormap.html). c, color, colors : color-spec or sequence of color-spec, optional - The color(s) used to create a :class:`~ultraplot.colors.DiscreteColormap`. + The color(s) used to create a [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html). If not passed, `cmap` is used. -norm : norm-spec, default: `~matplotlib.colors.Normalize` or `~ultraplot.colors.DivergingNorm` - The data value normalizer, passed to the `~ultraplot.constructor.Norm` +norm : norm-spec, default: [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) or [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) + The data value normalizer, passed to the [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html) constructor function. If `discrete` is ``True`` then 1) this affects the default level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and - 2) this is passed to `~ultraplot.colors.DiscreteNorm` to scale the colors before they - are discretized (if `norm` is not already a `~ultraplot.colors.DiscreteNorm`). - If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains - negative and positive values then `~ultraplot.colors.DivergingNorm` is used. - Otherwise `~matplotlib.colors.Normalize` is used. + 2) this is passed to [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) to scale the colors before they + are discretized (if `norm` is not already a [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html)). + If [cmap.autodiverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.autodiverging) is ``True`` and the normalization range contains + negative and positive values then [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) is used. + Otherwise [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) is used. norm_kw : dict-like, optional - Passed to `~ultraplot.constructor.Norm`. + Passed to [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html). extend : {'neither', 'both', 'min', 'max'}, default: 'neither' Direction for drawing colorbar "extensions" indicating out-of-bounds data on the end of the colorbar. -discrete : bool, default: :rc:`cmap.discrete` - If ``False``, then `~ultraplot.colors.DiscreteNorm` is not applied to the +discrete : bool, default: [cmap.discrete](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.discrete) + If ``False``, then [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) is not applied to the colormap. Instead, for non-contour plots, the number of levels will be - roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to + roughly controlled by [cmap.lut](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.lut). This has a similar effect to using `levels=large_number` but it may improve rendering speed. Default is - ``True`` only for contouring commands like `~ultraplot.axes.Axes.contourf` - and pseudocolor commands like `~ultraplot.axes.Axes.pcolor`. + ``True`` only for contouring commands like [contourf](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.contourf) + and pseudocolor commands like [pcolor](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.pcolor). sequential, diverging, cyclic, qualitative : bool, default: None Boolean arguments used if `cmap` is not passed. Set these to ``True`` - to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`, - :rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps. - The `diverging` option also applies `~ultraplot.colors.DivergingNorm` + to use the default [cmap.sequential](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.sequential), [cmap.diverging](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.diverging), + [cmap.cyclic](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.cyclic), and [cmap.qualitative](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.qualitative) colormaps. + The `diverging` option also applies [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) as the default continuous normalizer. vmin, vmax : float, optional The minimum and maximum color scale values used with the `norm` normalizer. @@ -14198,7 +14142,7 @@ vmin, vmax : float, optional `vmin` and `vmax` are the minimum and maximum of the data values. N Shorthand for `levels`. -levels : int or sequence of float, default: :rc:`cmap.levels` +levels : int or sequence of float, default: [cmap.levels](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.levels) The number of level edges or a sequence of level edges. If the former, `locator` is used to generate this many level edges at "nice" intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing @@ -14206,31 +14150,31 @@ levels : int or sequence of float, default: :rc:`cmap.levels` values : int or sequence of float, default: None The number of level centers or a sequence of level centers. If the former, `locator` is used to generate this many level centers at "nice" intervals. - If the latter, levels are inferred using `~ultraplot.utils.edges`. + If the latter, levels are inferred using [edges](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.edges.html). This will override any `levels` input. center_levels : bool, default False If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented. -robust : bool, float, or 2-tuple, default: :rc:`cmap.robust` +robust : bool, float, or 2-tuple, default: [cmap.robust](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.robust) If ``True`` and `vmin` or `vmax` were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, ``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers. -inbounds : bool, default: :rc:`cmap.inbounds` +inbounds : bool, default: [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) If ``True`` and `vmin` or `vmax` were not provided, when axis limits - have been explicitly restricted with :func:`~matplotlib.axes.Axes.set_xlim` - or :func:`~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored. - See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`. -locator : locator-spec, default: `matplotlib.ticker.MaxNLocator` + have been explicitly restricted with [set_xlim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlim.html) + or [set_ylim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylim.html), out-of-bounds data is ignored. + See also [cmap.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=cmap.inbounds) and [axes.inbounds](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.inbounds). +locator : locator-spec, default: [matplotlib.ticker.MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) The locator used to determine level locations if `levels` or `values` were not - already passed as lists. Passed to the `~ultraplot.constructor.Locator` constructor. - Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels. + already passed as lists. Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. + Default is [MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) with `levels` integer levels. locator_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Locator` class. + Keyword arguments passed to [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. symmetric : bool, default: False If ``True``, the normalization range or discrete colormap levels are symmetric about zero. @@ -14242,26 +14186,26 @@ negative : bool, default: False negative with a minimum at zero. nozero : bool, default: False If ``True``, ``0`` is removed from the level list. This is mainly useful for - single-color `~matplotlib.axes.Axes.contour` plots. + single-color [contour](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.contour.html) plots. colorbar : bool, int, or str, optional If not ``None``, this is a location specifying where to draw an *inset* or *outer* colorbar from the resulting object(s). If ``True``, - the default :rc:`colorbar.loc` is used. If the same location is + the default [colorbar.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists - of artists). Valid locations are shown in in `~ultraplot.axes.Axes.colorbar`. + of artists). Valid locations are shown in in [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). colorbar_kw : dict-like, optional - Extra keyword args for the call to `~ultraplot.axes.Axes.colorbar`. + Extra keyword args for the call to [colorbar](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.colorbar). legend : bool, int, or str, optional Location specifying where to draw an *inset* or *outer* legend from the - resulting object(s). If ``True``, the default :rc:`legend.loc` is used. + resulting object(s). If ``True``, the default [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations - are shown in :meth:`~ultraplot.axes.Axes.legend`. + are shown in [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). legend_kw : dict-like, optional - Extra keyword args for the call to :class:`~ultraplot.axes.Axes.legend`. + Extra keyword args for the call to [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.legend). **kwargs - Passed to `matplotlib.axes.Axes.spy`. + Passed to [matplotlib.axes.Axes.spy](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.spy.html). See also -------- @@ -14277,7 +14221,7 @@ This visualizes the non-zero values of the array. Two plotting styles are available: image and marker. Both are available for full arrays, but only the marker style -works for `scipy.sparse.spmatrix` instances. +works for [scipy.sparse.spmatrix](https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.spmatrix.html) instances. **Image style** @@ -14286,7 +14230,7 @@ extra remaining keyword arguments are passed to this method. **Marker style** -If *Z* is a `scipy.sparse.spmatrix` or *marker* or *markersize* are +If *Z* is a [scipy.sparse.spmatrix](https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.spmatrix.html) or *marker* or *markersize* are *None*, a `.Line2D` object will be returned with the value of marker determining the marker type, and any remaining keyword arguments passed to `~.Axes.plot`. @@ -14300,7 +14244,7 @@ precision : float or 'present', default: 0 If *precision* is 0, any non-zero value will be plotted. Otherwise, values of :math:`|Z| > precision` will be plotted. - For `scipy.sparse.spmatrix` instances, you can also + For [scipy.sparse.spmatrix](https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.spmatrix.html) instances, you can also pass 'present'. In this case any value present in the array will be plotted, even if it is identically zero. @@ -14316,16 +14260,16 @@ aspect : {'equal', 'auto', None} or float, default: 'equal' - 'auto': The Axes is kept fixed and the aspect is adjusted so that the data fit in the Axes. In general, this will result in non-square pixels. - - *None*: Use :rc:`image.aspect`. + - *None*: Use [image.aspect](https://ultraplot.readthedocs.io/en/stable/search.html?q=image.aspect). -origin : {'upper', 'lower'}, default: :rc:`image.origin` +origin : {'upper', 'lower'}, default: [image.origin](https://ultraplot.readthedocs.io/en/stable/search.html?q=image.origin) Place the [0, 0] index of the array in the upper left or lower left corner of the Axes. The convention 'upper' is typically used for matrices and images. Returns ------- -`~matplotlib.image.AxesImage` or `.Line2D` +[AxesImage](https://matplotlib.org/stable/api/_as_gen/matplotlib.image.AxesImage.html) or `.Line2D` The return type depends on the plotting style (see above). Other Parameters @@ -14349,28 +14293,28 @@ Other Parameters alpha: float or None animated: bool antialiased or aa: bool - clip_box: `~matplotlib.transforms.BboxBase` or None + clip_box: [BboxBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.BboxBase.html) or None clip_on: bool clip_path: Patch or (Path, Transform) or None - color or c: :mpltype:`color` + color or c: [color](https://matplotlib.org/stable/search.html?q=color) dash_capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} dash_joinstyle: `.JoinStyle` or {'miter', 'round', 'bevel'} dashes: sequence of floats (on/off ink in points) or (None, None) data: (2, N) array or two 1D arrays drawstyle or ds: {'default', 'steps', 'steps-pre', 'steps-mid', 'steps-post'}, default: 'default' - figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + figure: [Figure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html) or [SubFigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.SubFigure.html) fillstyle: {'full', 'left', 'right', 'bottom', 'top', 'none'} - gapcolor: :mpltype:`color` or None + gapcolor: [color](https://matplotlib.org/stable/search.html?q=color) or None gid: str in_layout: bool label: object linestyle or ls: {'-', '--', '-.', ':', '', (offset, on-off-seq), ...} linewidth or lw: float marker: marker style string, `~.path.Path` or `~.markers.MarkerStyle` - markeredgecolor or mec: :mpltype:`color` + markeredgecolor or mec: [color](https://matplotlib.org/stable/search.html?q=color) markeredgewidth or mew: float - markerfacecolor or mfc: :mpltype:`color` - markerfacecoloralt or mfcalt: :mpltype:`color` + markerfacecolor or mfc: [color](https://matplotlib.org/stable/search.html?q=color) + markerfacecoloralt or mfcalt: [color](https://matplotlib.org/stable/search.html?q=color) markersize or ms: float markevery: None or int or (int, int) or slice or list[int] or float or (float, float) or list[bool] mouseover: bool diff --git a/ultraplot/axes/polar.pyi b/ultraplot/axes/polar.pyi index 7a3d027c2..66df2516d 100644 --- a/ultraplot/axes/polar.pyi +++ b/ultraplot/axes/polar.pyi @@ -31,15 +31,15 @@ method and overrides several existing methods. Important --------- This axes subclass can be used by passing ``proj='polar'`` -to axes-creation commands like `~ultraplot.figure.Figure.add_axes`, -`~ultraplot.figure.Figure.add_subplot`, and `~ultraplot.figure.Figure.subplots`.""" +to axes-creation commands like [add_axes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.add_axes), +[add_subplot](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.add_subplot), and [subplots](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.subplots).""" _name = 'polar' def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: """Parameters ---------- *args - Passed to `matplotlib.axes.Axes`. + Passed to [matplotlib.axes.Axes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html). r0 : float, default: 0 The radial origin. theta0 : {'N', 'NW', 'W', 'SW', 'S', 'SE', 'E', 'NE'}, optional @@ -72,13 +72,13 @@ thetagridcolor, rgridcolor, gridcolor : color-spec, optional Use the keyword `gridcolor` to set both at once. thetalocator, rlocator : locator-spec, optional Used to determine the azimuthal and radial gridline positions. - Passed to the `~ultraplot.constructor.Locator` constructor. Can be - float, list of float, string, or `matplotlib.ticker.Locator` instance. + Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. Can be + float, list of float, string, or [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) instance. thetalines, rlines Aliases for `thetalocator`, `rlocator`. thetalocator_kw, rlocator_kw : dict-like, optional The azimuthal and radial locator settings. Passed to - `~ultraplot.constructor.Locator`. + [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html). thetaminorlocator, rminorlocator : optional As for `thetalocator`, `rlocator`, but for the minor gridlines. thetaminorticks, rminorticks : optional @@ -91,16 +91,16 @@ rlabelpos : float, optional position. thetaformatter, rformatter : formatter-spec, optional Used to determine the azimuthal and radial label format. - Passed to the `~ultraplot.constructor.Formatter` constructor. - Can be string, list of string, or `matplotlib.ticker.Formatter` + Passed to the [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html) constructor. + Can be string, list of string, or [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) instance. Use ``[]``, ``'null'``, or ``'none'`` for no labels. thetalabels, rlabels : optional Aliases for `thetaformatter`, `rformatter`. thetaformatter_kw, rformatter_kw : dict-like, optional The azimuthal and radial label formatter settings. Passed to - `~ultraplot.constructor.Formatter`. + [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html). thetalabel, rlabel : str, optional - Polar-aware axis labels rendered via `~ultraplot.text.CurvedText`. + Polar-aware axis labels rendered via [CurvedText](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.text.CurvedText.html). ``thetalabel`` follows the outer arc just beyond ``r=rmax``. ``rlabel`` follows a radial spoke, centered between ``rmin`` and ``rmax``. On a full circle it uses ``get_rlabel_position()`` unless @@ -121,24 +121,24 @@ rlabelloc : {'right', 'left'}, default: 'right' (default) anchors to ``thetamin`` and ``'left'`` anchors to ``thetamax``; the label is then offset outward from the sector. thetalabel_kw, rlabel_kw : dict-like, optional - Additional `~ultraplot.text.CurvedText` settings for the polar-aware + Additional [CurvedText](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.text.CurvedText.html) settings for the polar-aware labels (e.g. ``border``, ``bbox``, or rendering hints like ``min_advance``). See also `labelpad`, `labelcolor`, `labelsize`, and `labelweight`. -color : color-spec, default: :rc:`meta.color` +color : color-spec, default: [meta.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=meta.color) Color for the axes edge. Propagates to `labelcolor` unless specified - otherwise (similar to :func:`~ultraplot.axes.CartesianAxes.format`). -labelcolor, gridlabelcolor : color-spec, default: `color` or :rc:`grid.labelcolor` + otherwise (similar to [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html#ultraplot.axes.CartesianAxes.format)). +labelcolor, gridlabelcolor : color-spec, default: `color` or [grid.labelcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelcolor) Color for the gridline labels. -labelpad, gridlabelpad : unit-spec, default: :rc:`grid.labelpad` +labelpad, gridlabelpad : unit-spec, default: [grid.labelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelpad) The padding between the axes edge and the radial and azimuthal labels. For ``thetalabel`` and ``rlabel``, this is added on top of the built-in tick-clearance offset. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -labelsize, gridlabelsize : unit-spec or str, default: :rc:`grid.labelsize` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +labelsize, gridlabelsize : unit-spec or str, default: [grid.labelsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelsize) Font size for the gridline labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -labelweight, gridlabelweight : str, default: :rc:`grid.labelweight` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +labelweight, gridlabelweight : str, default: [grid.labelweight](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelweight) Font weight for the gridline labels. Other parameters @@ -146,14 +146,14 @@ Other parameters title : str or sequence, optional The axes title. Can optionally be a sequence strings, in which case the title will be selected from the sequence according to `~Axes.number`. -abc : bool or str or sequence, default: :rc:`abc` +abc : bool or str or sequence, default: [abc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc) The "a-b-c" subplot label style. Must contain the character `a` or `A`, for example ``'a.'``, or ``'A'``. If ``True`` then the default style of ``'a'`` is used. The `a` or ``A`` is replaced with the alphabetic character matching the `~Axes.number`. If `~Axes.number` is greater than 26, the characters loop around to a, ..., z, aa, ..., zz, aaa, ..., zzz, etc. Can also be a sequence of strings, in which case the "a-b-c" label will be selected sequentially from the list. For example `axs.format(abc = ["X", "Y"])` for a two-panel figure, and `axes[3:5].format(abc = ["X", "Y"])` for a two-panel subset of a larger figure. -abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` +abcloc, titleloc : str, default: [abc.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.loc), [title.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.loc) Strings indicating the location for the a-b-c label and main title. The following locations are valid: @@ -175,31 +175,31 @@ abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` right of y axis ``'outer right'``, ``'or'`` ======================== ============================ -abcborder, titleborder : bool, default: :rc:`abc.border` and :rc:`title.border` +abcborder, titleborder : bool, default: [abc.border](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.border) and [title.border](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.border) Whether to draw a white border around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes. -abcbbox, titlebbox : bool, default: :rc:`abc.bbox` and :rc:`title.bbox` +abcbbox, titlebbox : bool, default: [abc.bbox](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.bbox) and [title.bbox](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.bbox) Whether to draw a white bbox around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes. -abcpad : float or unit-spec, default: :rc:`abc.pad` +abcpad : float or unit-spec, default: [abc.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.pad) Horizontal offset to shift the a-b-c label position. Positive values move the label right, negative values move it left. This is separate from `abctitlepad`, which controls spacing between abc and title when co-located. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). abc_kw, title_kw : dict-like, optional Additional settings used to update the a-b-c label and title with ``text.update()``. -titlepad : float, default: :rc:`title.pad` +titlepad : float, default: [title.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.pad) The padding for the inner and outer titles and a-b-c labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -titleabove : bool, default: :rc:`title.above` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +titleabove : bool, default: [title.above](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.above) Whether to try to put outer titles and a-b-c labels above panels, colorbars, or legends that are above the axes. -abctitlepad : float, default: :rc:`abc.titlepad` +abctitlepad : float, default: [abc.titlepad](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.titlepad) The horizontal padding between a-b-c labels and titles in the same location. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle : str or sequence, optional Shorthands for the below keywords. lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle : str or sequence, optional @@ -208,22 +208,22 @@ lowerlefttitle, lowercentertitle, lowerrighttitle : str or sequence, optional an alternative to the ``ax.format(title='Title', titleloc=loc)`` workflow and permits adding more than one title-like label for a single axes. a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle : default: - :rc:`axes.alpha` (default: 1.0), :rc:`axes.facecolor` (default: white), :rc:`axes.edgecolor` (default: black), :rc:`axes.linewidth` (default: 0.6), - + [axes.alpha](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.alpha) (default: 1.0), [axes.facecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.facecolor) (default: white), [axes.edgecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.edgecolor) (default: black), [axes.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.linewidth) (default: 0.6), - Additional settings applied to the background patch, and their shorthands. Their defaults values are the ``'axes'`` properties. rc_mode : int, optional - The context mode passed to `~ultraplot.config.Configurator.context`. + The context mode passed to [context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context). rc_kw : dict-like, optional An alternative to passing extra keyword arguments. See below. **kwargs - Remaining keyword arguments are passed to `matplotlib.axes.Axes`.\\n Keyword arguments that match the name of an `~ultraplot.config.rc` setting are - passed to `ultraplot.config.Configurator.context` and used to update the axes. + Remaining keyword arguments are passed to [matplotlib.axes.Axes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html).\\n Keyword arguments that match the name of an [rc](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.rc.html) setting are + passed to [ultraplot.config.Configurator.context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context) and used to update the axes. If the setting name has "dots" you can simply omit the dots. For example, - ``abc='A.'`` modifies the :rcraw:`abc` setting, ``titleloc='left'`` modifies the - :rcraw:`title.loc` setting, ``gridminor=True`` modifies the :rcraw:`gridminor` - setting, and ``gridbelow=True`` modifies the :rcraw:`grid.below` setting. Many + ``abc='A.'`` modifies the [abc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc) setting, ``titleloc='left'`` modifies the + [title.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.loc) setting, ``gridminor=True`` modifies the [gridminor](https://ultraplot.readthedocs.io/en/stable/search.html?q=gridminor) + setting, and ``gridbelow=True`` modifies the [grid.below](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.below) setting. Many of the keyword arguments documented above are internally applied by retrieving - settings passed to `~ultraplot.config.Configurator.context`. + settings passed to [context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context). See also -------- @@ -310,7 +310,7 @@ returns False). Parameters ---------- -renderer : `~matplotlib.backend_bases.RendererBase` subclass. +renderer : [RendererBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.backend_bases.RendererBase.html) subclass. Notes ----- @@ -397,13 +397,13 @@ thetagridcolor, rgridcolor, gridcolor : color-spec, optional Use the keyword `gridcolor` to set both at once. thetalocator, rlocator : locator-spec, optional Used to determine the azimuthal and radial gridline positions. - Passed to the `~ultraplot.constructor.Locator` constructor. Can be - float, list of float, string, or `matplotlib.ticker.Locator` instance. + Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. Can be + float, list of float, string, or [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) instance. thetalines, rlines Aliases for `thetalocator`, `rlocator`. thetalocator_kw, rlocator_kw : dict-like, optional The azimuthal and radial locator settings. Passed to - `~ultraplot.constructor.Locator`. + [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html). thetaminorlocator, rminorlocator : optional As for `thetalocator`, `rlocator`, but for the minor gridlines. thetaminorticks, rminorticks : optional @@ -416,16 +416,16 @@ rlabelpos : float, optional position. thetaformatter, rformatter : formatter-spec, optional Used to determine the azimuthal and radial label format. - Passed to the `~ultraplot.constructor.Formatter` constructor. - Can be string, list of string, or `matplotlib.ticker.Formatter` + Passed to the [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html) constructor. + Can be string, list of string, or [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) instance. Use ``[]``, ``'null'``, or ``'none'`` for no labels. thetalabels, rlabels : optional Aliases for `thetaformatter`, `rformatter`. thetaformatter_kw, rformatter_kw : dict-like, optional The azimuthal and radial label formatter settings. Passed to - `~ultraplot.constructor.Formatter`. + [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html). thetalabel, rlabel : str, optional - Polar-aware axis labels rendered via `~ultraplot.text.CurvedText`. + Polar-aware axis labels rendered via [CurvedText](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.text.CurvedText.html). ``thetalabel`` follows the outer arc just beyond ``r=rmax``. ``rlabel`` follows a radial spoke, centered between ``rmin`` and ``rmax``. On a full circle it uses ``get_rlabel_position()`` unless @@ -446,24 +446,24 @@ rlabelloc : {'right', 'left'}, default: 'right' (default) anchors to ``thetamin`` and ``'left'`` anchors to ``thetamax``; the label is then offset outward from the sector. thetalabel_kw, rlabel_kw : dict-like, optional - Additional `~ultraplot.text.CurvedText` settings for the polar-aware + Additional [CurvedText](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.text.CurvedText.html) settings for the polar-aware labels (e.g. ``border``, ``bbox``, or rendering hints like ``min_advance``). See also `labelpad`, `labelcolor`, `labelsize`, and `labelweight`. -color : color-spec, default: :rc:`meta.color` +color : color-spec, default: [meta.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=meta.color) Color for the axes edge. Propagates to `labelcolor` unless specified - otherwise (similar to :func:`~ultraplot.axes.CartesianAxes.format`). -labelcolor, gridlabelcolor : color-spec, default: `color` or :rc:`grid.labelcolor` + otherwise (similar to [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html#ultraplot.axes.CartesianAxes.format)). +labelcolor, gridlabelcolor : color-spec, default: `color` or [grid.labelcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelcolor) Color for the gridline labels. -labelpad, gridlabelpad : unit-spec, default: :rc:`grid.labelpad` +labelpad, gridlabelpad : unit-spec, default: [grid.labelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelpad) The padding between the axes edge and the radial and azimuthal labels. For ``thetalabel`` and ``rlabel``, this is added on top of the built-in tick-clearance offset. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -labelsize, gridlabelsize : unit-spec or str, default: :rc:`grid.labelsize` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +labelsize, gridlabelsize : unit-spec or str, default: [grid.labelsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelsize) Font size for the gridline labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -labelweight, gridlabelweight : str, default: :rc:`grid.labelweight` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +labelweight, gridlabelweight : str, default: [grid.labelweight](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelweight) Font weight for the gridline labels. Other parameters @@ -471,14 +471,14 @@ Other parameters title : str or sequence, optional The axes title. Can optionally be a sequence strings, in which case the title will be selected from the sequence according to `~Axes.number`. -abc : bool or str or sequence, default: :rc:`abc` +abc : bool or str or sequence, default: [abc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc) The "a-b-c" subplot label style. Must contain the character `a` or `A`, for example ``'a.'``, or ``'A'``. If ``True`` then the default style of ``'a'`` is used. The `a` or ``A`` is replaced with the alphabetic character matching the `~Axes.number`. If `~Axes.number` is greater than 26, the characters loop around to a, ..., z, aa, ..., zz, aaa, ..., zzz, etc. Can also be a sequence of strings, in which case the "a-b-c" label will be selected sequentially from the list. For example `axs.format(abc = ["X", "Y"])` for a two-panel figure, and `axes[3:5].format(abc = ["X", "Y"])` for a two-panel subset of a larger figure. -abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` +abcloc, titleloc : str, default: [abc.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.loc), [title.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.loc) Strings indicating the location for the a-b-c label and main title. The following locations are valid: @@ -500,31 +500,31 @@ abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` right of y axis ``'outer right'``, ``'or'`` ======================== ============================ -abcborder, titleborder : bool, default: :rc:`abc.border` and :rc:`title.border` +abcborder, titleborder : bool, default: [abc.border](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.border) and [title.border](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.border) Whether to draw a white border around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes. -abcbbox, titlebbox : bool, default: :rc:`abc.bbox` and :rc:`title.bbox` +abcbbox, titlebbox : bool, default: [abc.bbox](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.bbox) and [title.bbox](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.bbox) Whether to draw a white bbox around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes. -abcpad : float or unit-spec, default: :rc:`abc.pad` +abcpad : float or unit-spec, default: [abc.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.pad) Horizontal offset to shift the a-b-c label position. Positive values move the label right, negative values move it left. This is separate from `abctitlepad`, which controls spacing between abc and title when co-located. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). abc_kw, title_kw : dict-like, optional Additional settings used to update the a-b-c label and title with ``text.update()``. -titlepad : float, default: :rc:`title.pad` +titlepad : float, default: [title.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.pad) The padding for the inner and outer titles and a-b-c labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -titleabove : bool, default: :rc:`title.above` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +titleabove : bool, default: [title.above](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.above) Whether to try to put outer titles and a-b-c labels above panels, colorbars, or legends that are above the axes. -abctitlepad : float, default: :rc:`abc.titlepad` +abctitlepad : float, default: [abc.titlepad](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.titlepad) The horizontal padding between a-b-c labels and titles in the same location. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle : str or sequence, optional Shorthands for the below keywords. lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle : str or sequence, optional @@ -533,7 +533,7 @@ lowerlefttitle, lowercentertitle, lowerrighttitle : str or sequence, optional an alternative to the ``ax.format(title='Title', titleloc=loc)`` workflow and permits adding more than one title-like label for a single axes. a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle : default: - :rc:`axes.alpha` (default: 1.0), :rc:`axes.facecolor` (default: white), :rc:`axes.edgecolor` (default: black), :rc:`axes.linewidth` (default: 0.6), - + [axes.alpha](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.alpha) (default: 1.0), [axes.facecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.facecolor) (default: white), [axes.edgecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.edgecolor) (default: black), [axes.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.linewidth) (default: 0.6), - Additional settings applied to the background patch, and their shorthands. Their defaults values are the ``'axes'`` properties. rowlabels, collabels, llabels, tlabels, rlabels, blabels @@ -544,14 +544,14 @@ leftlabels, toplabels, rightlabels, bottomlabels : sequence of str, optional bottom edges of the figure. The length of each list must match the number of subplots along the corresponding edge. leftlabelpad, toplabelpad, rightlabelpad, bottomlabelpad : float or unit-spec, default -: :rc:`leftlabel.pad`, :rc:`toplabel.pad`, :rc:`rightlabel.pad`, :rc:`bottomlabel.pad` +: [leftlabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=leftlabel.pad), [toplabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=toplabel.pad), [rightlabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=rightlabel.pad), [bottomlabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=bottomlabel.pad) The padding between the labels and the axes content. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). leftlabelsharedpad, toplabelsharedpad, rightlabelsharedpad, bottomlabelsharedpad : float or unit-spec, default -: :rc:`leftlabel.sharedpad`, :rc:`toplabel.sharedpad`, :rc:`rightlabel.sharedpad`, :rc:`bottomlabel.sharedpad` +: [leftlabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=leftlabel.sharedpad), [toplabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=toplabel.sharedpad), [rightlabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=rightlabel.sharedpad), [bottomlabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=bottomlabel.sharedpad) The padding between side labels and a shared spanning axis label on the same side. The spanning label is placed outside the side labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). leftlabels_kw, toplabels_kw, rightlabels_kw, bottomlabels_kw : dict-like, optional Additional settings used to update the labels with ``text.update()``. figtitle @@ -559,9 +559,9 @@ figtitle suptitle : str, optional The figure "super" title, centered between the left edge of the leftmost subplot and the right edge of the rightmost subplot. -suptitlepad : float, default: :rc:`suptitle.pad` +suptitlepad : float, default: [suptitle.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=suptitle.pad) The padding between the super title and the axes content. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). suptitle_kw : optional Additional settings used to update the super title with ``text.update()``. includepanels : bool, default: False @@ -569,18 +569,18 @@ includepanels : bool, default: False of the subplot grid and when aligning the `spanx` *x* axis labels and `spany` *y* axis labels along the sides of the subplot grid. rc_mode : int, optional - The context mode passed to `~ultraplot.config.Configurator.context`. + The context mode passed to [context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context). rc_kw : dict-like, optional An alternative to passing extra keyword arguments. See below. **kwargs - Keyword arguments that match the name of an `~ultraplot.config.rc` setting are - passed to `ultraplot.config.Configurator.context` and used to update the axes. + Keyword arguments that match the name of an [rc](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.rc.html) setting are + passed to [ultraplot.config.Configurator.context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context) and used to update the axes. If the setting name has "dots" you can simply omit the dots. For example, - ``abc='A.'`` modifies the :rcraw:`abc` setting, ``titleloc='left'`` modifies the - :rcraw:`title.loc` setting, ``gridminor=True`` modifies the :rcraw:`gridminor` - setting, and ``gridbelow=True`` modifies the :rcraw:`grid.below` setting. Many + ``abc='A.'`` modifies the [abc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc) setting, ``titleloc='left'`` modifies the + [title.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.loc) setting, ``gridminor=True`` modifies the [gridminor](https://ultraplot.readthedocs.io/en/stable/search.html?q=gridminor) + setting, and ``gridbelow=True`` modifies the [grid.below](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.below) setting. Many of the keyword arguments documented above are internally applied by retrieving - settings passed to `~ultraplot.config.Configurator.context`. + settings passed to [context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context). See also -------- diff --git a/ultraplot/axes/shared.pyi b/ultraplot/axes/shared.pyi index 5f6532adc..f0a5292db 100644 --- a/ultraplot/axes/shared.pyi +++ b/ultraplot/axes/shared.pyi @@ -16,8 +16,8 @@ except ImportError: from typing_extensions import override class _SharedAxes(object): - """Mix-in class with methods shared between `~ultraplot.axes.CartesianAxes` -and :class:`~ultraplot.axes.PolarAxes`.""" + """Mix-in class with methods shared between [CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html) +and [PolarAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PolarAxes.html).""" @staticmethod def _min_max_lim(key: Incomplete, min_: Incomplete=None, max_: Incomplete=None, lim: Incomplete=None) -> Incomplete: diff --git a/ultraplot/axes/taylor.pyi b/ultraplot/axes/taylor.pyi index 8ab9db582..78fe11927 100644 --- a/ultraplot/axes/taylor.pyi +++ b/ultraplot/axes/taylor.pyi @@ -21,9 +21,9 @@ class TaylorAxes(PolarAxes): Important --------- This axes subclass can be used by passing ``proj='taylor'`` to -axes-creation commands like `~ultraplot.figure.Figure.add_axes`, -`~ultraplot.figure.Figure.add_subplot`, and -`~ultraplot.figure.Figure.subplots`.""" +axes-creation commands like [add_axes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.add_axes), +[add_subplot](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.add_subplot), and +[subplots](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.subplots).""" _name = 'taylor' _name_aliases = () _default_corrs = np.array((1.0, 0.95, 0.9, 0.8, 0.6, 0.4, 0.2, 0.0)) @@ -33,7 +33,7 @@ axes-creation commands like `~ultraplot.figure.Figure.add_axes`, """Parameters ---------- *args - Passed to `matplotlib.axes.Axes`. + Passed to [matplotlib.axes.Axes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html). xlabel, ylabel : str, optional Labels for the standard-deviation axes. These are drawn as Taylor-specific text artists while the native polar axis labels are kept hidden. @@ -81,13 +81,13 @@ thetagridcolor, rgridcolor, gridcolor : color-spec, optional Use the keyword `gridcolor` to set both at once. thetalocator, rlocator : locator-spec, optional Used to determine the azimuthal and radial gridline positions. - Passed to the `~ultraplot.constructor.Locator` constructor. Can be - float, list of float, string, or `matplotlib.ticker.Locator` instance. + Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. Can be + float, list of float, string, or [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) instance. thetalines, rlines Aliases for `thetalocator`, `rlocator`. thetalocator_kw, rlocator_kw : dict-like, optional The azimuthal and radial locator settings. Passed to - `~ultraplot.constructor.Locator`. + [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html). thetaminorlocator, rminorlocator : optional As for `thetalocator`, `rlocator`, but for the minor gridlines. thetaminorticks, rminorticks : optional @@ -100,16 +100,16 @@ rlabelpos : float, optional position. thetaformatter, rformatter : formatter-spec, optional Used to determine the azimuthal and radial label format. - Passed to the `~ultraplot.constructor.Formatter` constructor. - Can be string, list of string, or `matplotlib.ticker.Formatter` + Passed to the [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html) constructor. + Can be string, list of string, or [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) instance. Use ``[]``, ``'null'``, or ``'none'`` for no labels. thetalabels, rlabels : optional Aliases for `thetaformatter`, `rformatter`. thetaformatter_kw, rformatter_kw : dict-like, optional The azimuthal and radial label formatter settings. Passed to - `~ultraplot.constructor.Formatter`. + [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html). thetalabel, rlabel : str, optional - Polar-aware axis labels rendered via `~ultraplot.text.CurvedText`. + Polar-aware axis labels rendered via [CurvedText](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.text.CurvedText.html). ``thetalabel`` follows the outer arc just beyond ``r=rmax``. ``rlabel`` follows a radial spoke, centered between ``rmin`` and ``rmax``. On a full circle it uses ``get_rlabel_position()`` unless @@ -130,24 +130,24 @@ rlabelloc : {'right', 'left'}, default: 'right' (default) anchors to ``thetamin`` and ``'left'`` anchors to ``thetamax``; the label is then offset outward from the sector. thetalabel_kw, rlabel_kw : dict-like, optional - Additional `~ultraplot.text.CurvedText` settings for the polar-aware + Additional [CurvedText](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.text.CurvedText.html) settings for the polar-aware labels (e.g. ``border``, ``bbox``, or rendering hints like ``min_advance``). See also `labelpad`, `labelcolor`, `labelsize`, and `labelweight`. -color : color-spec, default: :rc:`meta.color` +color : color-spec, default: [meta.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=meta.color) Color for the axes edge. Propagates to `labelcolor` unless specified - otherwise (similar to :func:`~ultraplot.axes.CartesianAxes.format`). -labelcolor, gridlabelcolor : color-spec, default: `color` or :rc:`grid.labelcolor` + otherwise (similar to [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html#ultraplot.axes.CartesianAxes.format)). +labelcolor, gridlabelcolor : color-spec, default: `color` or [grid.labelcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelcolor) Color for the gridline labels. -labelpad, gridlabelpad : unit-spec, default: :rc:`grid.labelpad` +labelpad, gridlabelpad : unit-spec, default: [grid.labelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelpad) The padding between the axes edge and the radial and azimuthal labels. For ``thetalabel`` and ``rlabel``, this is added on top of the built-in tick-clearance offset. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -labelsize, gridlabelsize : unit-spec or str, default: :rc:`grid.labelsize` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +labelsize, gridlabelsize : unit-spec or str, default: [grid.labelsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelsize) Font size for the gridline labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -labelweight, gridlabelweight : str, default: :rc:`grid.labelweight` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +labelweight, gridlabelweight : str, default: [grid.labelweight](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelweight) Font weight for the gridline labels. Other parameters @@ -155,14 +155,14 @@ Other parameters title : str or sequence, optional The axes title. Can optionally be a sequence strings, in which case the title will be selected from the sequence according to `~Axes.number`. -abc : bool or str or sequence, default: :rc:`abc` +abc : bool or str or sequence, default: [abc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc) The "a-b-c" subplot label style. Must contain the character `a` or `A`, for example ``'a.'``, or ``'A'``. If ``True`` then the default style of ``'a'`` is used. The `a` or ``A`` is replaced with the alphabetic character matching the `~Axes.number`. If `~Axes.number` is greater than 26, the characters loop around to a, ..., z, aa, ..., zz, aaa, ..., zzz, etc. Can also be a sequence of strings, in which case the "a-b-c" label will be selected sequentially from the list. For example `axs.format(abc = ["X", "Y"])` for a two-panel figure, and `axes[3:5].format(abc = ["X", "Y"])` for a two-panel subset of a larger figure. -abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` +abcloc, titleloc : str, default: [abc.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.loc), [title.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.loc) Strings indicating the location for the a-b-c label and main title. The following locations are valid: @@ -184,31 +184,31 @@ abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` right of y axis ``'outer right'``, ``'or'`` ======================== ============================ -abcborder, titleborder : bool, default: :rc:`abc.border` and :rc:`title.border` +abcborder, titleborder : bool, default: [abc.border](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.border) and [title.border](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.border) Whether to draw a white border around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes. -abcbbox, titlebbox : bool, default: :rc:`abc.bbox` and :rc:`title.bbox` +abcbbox, titlebbox : bool, default: [abc.bbox](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.bbox) and [title.bbox](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.bbox) Whether to draw a white bbox around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes. -abcpad : float or unit-spec, default: :rc:`abc.pad` +abcpad : float or unit-spec, default: [abc.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.pad) Horizontal offset to shift the a-b-c label position. Positive values move the label right, negative values move it left. This is separate from `abctitlepad`, which controls spacing between abc and title when co-located. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). abc_kw, title_kw : dict-like, optional Additional settings used to update the a-b-c label and title with ``text.update()``. -titlepad : float, default: :rc:`title.pad` +titlepad : float, default: [title.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.pad) The padding for the inner and outer titles and a-b-c labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -titleabove : bool, default: :rc:`title.above` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +titleabove : bool, default: [title.above](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.above) Whether to try to put outer titles and a-b-c labels above panels, colorbars, or legends that are above the axes. -abctitlepad : float, default: :rc:`abc.titlepad` +abctitlepad : float, default: [abc.titlepad](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.titlepad) The horizontal padding between a-b-c labels and titles in the same location. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle : str or sequence, optional Shorthands for the below keywords. lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle : str or sequence, optional @@ -217,22 +217,22 @@ lowerlefttitle, lowercentertitle, lowerrighttitle : str or sequence, optional an alternative to the ``ax.format(title='Title', titleloc=loc)`` workflow and permits adding more than one title-like label for a single axes. a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle : default: - :rc:`axes.alpha` (default: 1.0), :rc:`axes.facecolor` (default: white), :rc:`axes.edgecolor` (default: black), :rc:`axes.linewidth` (default: 0.6), - + [axes.alpha](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.alpha) (default: 1.0), [axes.facecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.facecolor) (default: white), [axes.edgecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.edgecolor) (default: black), [axes.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.linewidth) (default: 0.6), - Additional settings applied to the background patch, and their shorthands. Their defaults values are the ``'axes'`` properties. rc_mode : int, optional - The context mode passed to `~ultraplot.config.Configurator.context`. + The context mode passed to [context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context). rc_kw : dict-like, optional An alternative to passing extra keyword arguments. See below. **kwargs - Remaining keyword arguments are passed to `matplotlib.axes.Axes`.\\n Keyword arguments that match the name of an `~ultraplot.config.rc` setting are - passed to `ultraplot.config.Configurator.context` and used to update the axes. + Remaining keyword arguments are passed to [matplotlib.axes.Axes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html).\\n Keyword arguments that match the name of an [rc](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.rc.html) setting are + passed to [ultraplot.config.Configurator.context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context) and used to update the axes. If the setting name has "dots" you can simply omit the dots. For example, - ``abc='A.'`` modifies the :rcraw:`abc` setting, ``titleloc='left'`` modifies the - :rcraw:`title.loc` setting, ``gridminor=True`` modifies the :rcraw:`gridminor` - setting, and ``gridbelow=True`` modifies the :rcraw:`grid.below` setting. Many + ``abc='A.'`` modifies the [abc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc) setting, ``titleloc='left'`` modifies the + [title.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.loc) setting, ``gridminor=True`` modifies the [gridminor](https://ultraplot.readthedocs.io/en/stable/search.html?q=gridminor) + setting, and ``gridbelow=True`` modifies the [grid.below](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.below) setting. Many of the keyword arguments documented above are internally applied by retrieving - settings passed to `~ultraplot.config.Configurator.context`. + settings passed to [context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context). See also -------- @@ -370,13 +370,13 @@ thetagridcolor, rgridcolor, gridcolor : color-spec, optional Use the keyword `gridcolor` to set both at once. thetalocator, rlocator : locator-spec, optional Used to determine the azimuthal and radial gridline positions. - Passed to the `~ultraplot.constructor.Locator` constructor. Can be - float, list of float, string, or `matplotlib.ticker.Locator` instance. + Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. Can be + float, list of float, string, or [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) instance. thetalines, rlines Aliases for `thetalocator`, `rlocator`. thetalocator_kw, rlocator_kw : dict-like, optional The azimuthal and radial locator settings. Passed to - `~ultraplot.constructor.Locator`. + [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html). thetaminorlocator, rminorlocator : optional As for `thetalocator`, `rlocator`, but for the minor gridlines. thetaminorticks, rminorticks : optional @@ -389,16 +389,16 @@ rlabelpos : float, optional position. thetaformatter, rformatter : formatter-spec, optional Used to determine the azimuthal and radial label format. - Passed to the `~ultraplot.constructor.Formatter` constructor. - Can be string, list of string, or `matplotlib.ticker.Formatter` + Passed to the [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html) constructor. + Can be string, list of string, or [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) instance. Use ``[]``, ``'null'``, or ``'none'`` for no labels. thetalabels, rlabels : optional Aliases for `thetaformatter`, `rformatter`. thetaformatter_kw, rformatter_kw : dict-like, optional The azimuthal and radial label formatter settings. Passed to - `~ultraplot.constructor.Formatter`. + [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html). thetalabel, rlabel : str, optional - Polar-aware axis labels rendered via `~ultraplot.text.CurvedText`. + Polar-aware axis labels rendered via [CurvedText](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.text.CurvedText.html). ``thetalabel`` follows the outer arc just beyond ``r=rmax``. ``rlabel`` follows a radial spoke, centered between ``rmin`` and ``rmax``. On a full circle it uses ``get_rlabel_position()`` unless @@ -419,36 +419,36 @@ rlabelloc : {'right', 'left'}, default: 'right' (default) anchors to ``thetamin`` and ``'left'`` anchors to ``thetamax``; the label is then offset outward from the sector. thetalabel_kw, rlabel_kw : dict-like, optional - Additional `~ultraplot.text.CurvedText` settings for the polar-aware + Additional [CurvedText](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.text.CurvedText.html) settings for the polar-aware labels (e.g. ``border``, ``bbox``, or rendering hints like ``min_advance``). See also `labelpad`, `labelcolor`, `labelsize`, and `labelweight`. -color : color-spec, default: :rc:`meta.color` +color : color-spec, default: [meta.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=meta.color) Color for the axes edge. Propagates to `labelcolor` unless specified - otherwise (similar to :func:`~ultraplot.axes.CartesianAxes.format`). -labelcolor, gridlabelcolor : color-spec, default: `color` or :rc:`grid.labelcolor` + otherwise (similar to [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html#ultraplot.axes.CartesianAxes.format)). +labelcolor, gridlabelcolor : color-spec, default: `color` or [grid.labelcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelcolor) Color for the gridline labels. -labelpad, gridlabelpad : unit-spec, default: :rc:`grid.labelpad` +labelpad, gridlabelpad : unit-spec, default: [grid.labelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelpad) The padding between the axes edge and the radial and azimuthal labels. For ``thetalabel`` and ``rlabel``, this is added on top of the built-in tick-clearance offset. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -labelsize, gridlabelsize : unit-spec or str, default: :rc:`grid.labelsize` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +labelsize, gridlabelsize : unit-spec or str, default: [grid.labelsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelsize) Font size for the gridline labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -labelweight, gridlabelweight : str, default: :rc:`grid.labelweight` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +labelweight, gridlabelweight : str, default: [grid.labelweight](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelweight) Font weight for the gridline labels. title : str or sequence, optional The axes title. Can optionally be a sequence strings, in which case the title will be selected from the sequence according to `~Axes.number`. -abc : bool or str or sequence, default: :rc:`abc` +abc : bool or str or sequence, default: [abc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc) The "a-b-c" subplot label style. Must contain the character `a` or `A`, for example ``'a.'``, or ``'A'``. If ``True`` then the default style of ``'a'`` is used. The `a` or ``A`` is replaced with the alphabetic character matching the `~Axes.number`. If `~Axes.number` is greater than 26, the characters loop around to a, ..., z, aa, ..., zz, aaa, ..., zzz, etc. Can also be a sequence of strings, in which case the "a-b-c" label will be selected sequentially from the list. For example `axs.format(abc = ["X", "Y"])` for a two-panel figure, and `axes[3:5].format(abc = ["X", "Y"])` for a two-panel subset of a larger figure. -abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` +abcloc, titleloc : str, default: [abc.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.loc), [title.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.loc) Strings indicating the location for the a-b-c label and main title. The following locations are valid: @@ -470,31 +470,31 @@ abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` right of y axis ``'outer right'``, ``'or'`` ======================== ============================ -abcborder, titleborder : bool, default: :rc:`abc.border` and :rc:`title.border` +abcborder, titleborder : bool, default: [abc.border](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.border) and [title.border](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.border) Whether to draw a white border around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes. -abcbbox, titlebbox : bool, default: :rc:`abc.bbox` and :rc:`title.bbox` +abcbbox, titlebbox : bool, default: [abc.bbox](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.bbox) and [title.bbox](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.bbox) Whether to draw a white bbox around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes. -abcpad : float or unit-spec, default: :rc:`abc.pad` +abcpad : float or unit-spec, default: [abc.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.pad) Horizontal offset to shift the a-b-c label position. Positive values move the label right, negative values move it left. This is separate from `abctitlepad`, which controls spacing between abc and title when co-located. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). abc_kw, title_kw : dict-like, optional Additional settings used to update the a-b-c label and title with ``text.update()``. -titlepad : float, default: :rc:`title.pad` +titlepad : float, default: [title.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.pad) The padding for the inner and outer titles and a-b-c labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -titleabove : bool, default: :rc:`title.above` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +titleabove : bool, default: [title.above](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.above) Whether to try to put outer titles and a-b-c labels above panels, colorbars, or legends that are above the axes. -abctitlepad : float, default: :rc:`abc.titlepad` +abctitlepad : float, default: [abc.titlepad](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.titlepad) The horizontal padding between a-b-c labels and titles in the same location. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle : str or sequence, optional Shorthands for the below keywords. lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle : str or sequence, optional @@ -503,7 +503,7 @@ lowerlefttitle, lowercentertitle, lowerrighttitle : str or sequence, optional an alternative to the ``ax.format(title='Title', titleloc=loc)`` workflow and permits adding more than one title-like label for a single axes. a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle : default: - :rc:`axes.alpha` (default: 1.0), :rc:`axes.facecolor` (default: white), :rc:`axes.edgecolor` (default: black), :rc:`axes.linewidth` (default: 0.6), - + [axes.alpha](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.alpha) (default: 1.0), [axes.facecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.facecolor) (default: white), [axes.edgecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.edgecolor) (default: black), [axes.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.linewidth) (default: 0.6), - Additional settings applied to the background patch, and their shorthands. Their defaults values are the ``'axes'`` properties. rowlabels, collabels, llabels, tlabels, rlabels, blabels @@ -514,14 +514,14 @@ leftlabels, toplabels, rightlabels, bottomlabels : sequence of str, optional bottom edges of the figure. The length of each list must match the number of subplots along the corresponding edge. leftlabelpad, toplabelpad, rightlabelpad, bottomlabelpad : float or unit-spec, default -: :rc:`leftlabel.pad`, :rc:`toplabel.pad`, :rc:`rightlabel.pad`, :rc:`bottomlabel.pad` +: [leftlabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=leftlabel.pad), [toplabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=toplabel.pad), [rightlabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=rightlabel.pad), [bottomlabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=bottomlabel.pad) The padding between the labels and the axes content. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). leftlabelsharedpad, toplabelsharedpad, rightlabelsharedpad, bottomlabelsharedpad : float or unit-spec, default -: :rc:`leftlabel.sharedpad`, :rc:`toplabel.sharedpad`, :rc:`rightlabel.sharedpad`, :rc:`bottomlabel.sharedpad` +: [leftlabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=leftlabel.sharedpad), [toplabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=toplabel.sharedpad), [rightlabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=rightlabel.sharedpad), [bottomlabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=bottomlabel.sharedpad) The padding between side labels and a shared spanning axis label on the same side. The spanning label is placed outside the side labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). leftlabels_kw, toplabels_kw, rightlabels_kw, bottomlabels_kw : dict-like, optional Additional settings used to update the labels with ``text.update()``. figtitle @@ -529,9 +529,9 @@ figtitle suptitle : str, optional The figure "super" title, centered between the left edge of the leftmost subplot and the right edge of the rightmost subplot. -suptitlepad : float, default: :rc:`suptitle.pad` +suptitlepad : float, default: [suptitle.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=suptitle.pad) The padding between the super title and the axes content. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). suptitle_kw : optional Additional settings used to update the super title with ``text.update()``. includepanels : bool, default: False @@ -539,18 +539,18 @@ includepanels : bool, default: False of the subplot grid and when aligning the `spanx` *x* axis labels and `spany` *y* axis labels along the sides of the subplot grid. rc_mode : int, optional - The context mode passed to `~ultraplot.config.Configurator.context`. + The context mode passed to [context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context). rc_kw : dict-like, optional An alternative to passing extra keyword arguments. See below. **kwargs - Keyword arguments that match the name of an `~ultraplot.config.rc` setting are - passed to `ultraplot.config.Configurator.context` and used to update the axes. + Keyword arguments that match the name of an [rc](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.rc.html) setting are + passed to [ultraplot.config.Configurator.context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context) and used to update the axes. If the setting name has "dots" you can simply omit the dots. For example, - ``abc='A.'`` modifies the :rcraw:`abc` setting, ``titleloc='left'`` modifies the - :rcraw:`title.loc` setting, ``gridminor=True`` modifies the :rcraw:`gridminor` - setting, and ``gridbelow=True`` modifies the :rcraw:`grid.below` setting. Many + ``abc='A.'`` modifies the [abc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc) setting, ``titleloc='left'`` modifies the + [title.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.loc) setting, ``gridminor=True`` modifies the [gridminor](https://ultraplot.readthedocs.io/en/stable/search.html?q=gridminor) + setting, and ``gridbelow=True`` modifies the [grid.below](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.below) setting. Many of the keyword arguments documented above are internally applied by retrieving - settings passed to `~ultraplot.config.Configurator.context`. + settings passed to [context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context). See also -------- diff --git a/ultraplot/axes/three.pyi b/ultraplot/axes/three.pyi index 8200a2f69..9ca8f027c 100644 --- a/ultraplot/axes/three.pyi +++ b/ultraplot/axes/three.pyi @@ -11,14 +11,14 @@ except ImportError: Axes3D = object class ThreeAxes(shared._SharedAxes, base.Axes, Axes3D): - """Simple mix-in of `ultraplot.axes.Axes` with `~mpl_toolkits.mplot3d.axes3d.Axes3D`. + """Simple mix-in of [ultraplot.axes.Axes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html) with `~mpl_toolkits.mplot3d.axes3d.Axes3D`. Important --------- -Note that this subclass does *not* implement the :class:`~ultraplot.axes.PlotAxes` +Note that this subclass does *not* implement the [PlotAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PlotAxes.html) plotting overrides. This axes subclass can be used by passing ``proj='3d'`` or -``proj='three'`` to axes-creation commands like `~ultraplot.figure.Figure.add_axes`, -`~ultraplot.figure.Figure.add_subplot`, and `~ultraplot.figure.Figure.subplots`.""" +``proj='three'`` to axes-creation commands like [add_axes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.add_axes), +[add_subplot](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.add_subplot), and [subplots](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.subplots).""" _name = 'three' _name_aliases = ('3d',) @@ -27,7 +27,7 @@ plotting overrides. This axes subclass can be used by passing ``proj='3d'`` or Parameters ---------- -fig : `~matplotlib.figure.Figure` +fig : [Figure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html) The Axes is built in the `.Figure` *fig*. *args @@ -43,7 +43,7 @@ fig : `~matplotlib.figure.Figure` being created. Finally, ``*args`` can also directly be a `.SubplotSpec` instance. -sharex, sharey : `~matplotlib.axes.Axes`, optional +sharex, sharey : [Axes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html), optional The x- or y-`~.matplotlib.axis` is shared with the x- or y-axis in the input `~.axes.Axes`. Note that it is not possible to unshare axes. @@ -76,11 +76,11 @@ forward_navigation_events : bool or "auto", default: "auto" axes_locator: Callable[[Axes, Renderer], Bbox] axisbelow: bool or 'line' box_aspect: float or None - clip_box: `~matplotlib.transforms.BboxBase` or None + clip_box: [BboxBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.BboxBase.html) or None clip_on: bool clip_path: Patch or (Path, Transform) or None - facecolor or fc: :mpltype:`color` - figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + facecolor or fc: [color](https://matplotlib.org/stable/search.html?q=color) + figure: [Figure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html) or [SubFigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.SubFigure.html) forward_navigation_events: bool or "auto" frame_on: bool gid: str @@ -91,7 +91,7 @@ forward_navigation_events : bool or "auto", default: "auto" navigate_mode: unknown path_effects: list of `.AbstractPathEffect` picker: None or bool or float or callable - position: [left, bottom, width, height] or `~matplotlib.transforms.Bbox` + position: [left, bottom, width, height] or [Bbox](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Bbox.html) prop_cycle: `~cycler.Cycler` rasterization_zorder: float or None rasterized: bool @@ -99,7 +99,7 @@ forward_navigation_events : bool or "auto", default: "auto" snap: bool or None subplotspec: unknown title: str - transform: `~matplotlib.transforms.Transform` + transform: [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html) url: str visible: bool xbound: (lower: float, upper: float) diff --git a/ultraplot/colors.pyi b/ultraplot/colors.pyi index 250169ee6..df13b9d2f 100644 --- a/ultraplot/colors.pyi +++ b/ultraplot/colors.pyi @@ -107,7 +107,7 @@ ratios : sequence of float, optional def _make_lookup_table(N: Incomplete, data: Incomplete, gamma: Incomplete=1.0, inverse: Incomplete=False) -> Incomplete: """Generate lookup tables of HSL values given specified gradations. Similar to -`~matplotlib.colors.makeMappingArray` but permits *circular* hue gradations, +[makeMappingArray](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.makeMappingArray.html) but permits *circular* hue gradations, disables clipping of out-of-bounds values, and uses fancier "gamma" scaling. Parameters @@ -117,7 +117,7 @@ N : int data : array-like Sequence of `(x, y_0, y_1)` tuples specifying channel jumps (from `y_0` to `y_1`) and `x` coordinate of those jumps - (ranges between 0 and 1). See `~matplotlib.colors.LinearSegmentedColormap`. + (ranges between 0 and 1). See [LinearSegmentedColormap](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.LinearSegmentedColormap.html). gamma : float or sequence of float, optional To obtain channel values between coordinates `x_i` and `x_{i+1}` in rows `i` and `i+1` of `data` we use the formula: @@ -130,7 +130,7 @@ gamma : float or sequence of float, optional 0 to 1 between rows `i` and ``i+1``. If `gamma` is float, it applies to every transition. Otherwise, its length must equal ``data.shape[0]-1``. - This is similar to the `matplotlib.colors.makeMappingArray` `gamma` except + This is similar to the [matplotlib.colors.makeMappingArray](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.makeMappingArray.html) `gamma` except it controls the weighting for transitions *between* each segment data coordinate rather than the coordinates themselves. This makes more sense for `PerceptualColormap`\\ s because they usually contain just a @@ -214,7 +214,7 @@ algongside more intuitive ``Colormap(data, name, N)`` input.""" ... class ContinuousColormap(mcolors.LinearSegmentedColormap, _Colormap): - """Replacement for `~matplotlib.colors.LinearSegmentedColormap`.""" + """Replacement for [LinearSegmentedColormap](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.LinearSegmentedColormap.html).""" def __str__(self) -> str: ... @@ -231,11 +231,11 @@ segmentdata : dict-like and ``'a'`` are also acceptable. The key values can be callable functions that return channel values given a colormap index, or 3-column arrays indicating the coordinates and channel transitions. See - `matplotlib.colors.LinearSegmentedColormap` for a detailed explanation. + [matplotlib.colors.LinearSegmentedColormap](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.LinearSegmentedColormap.html) for a detailed explanation. name : str, default: '_no_name' The colormap name. This can also be passed as the first positional string argument. -N : int, default: :rc:`image.lut` +N : int, default: [image.lut](https://ultraplot.readthedocs.io/en/stable/search.html?q=image.lut) Number of points in the colormap lookup table. gamma : float, optional Gamma scaling used for the *x* coordinates. @@ -250,7 +250,7 @@ cyclic : bool, optional Other parameters ---------------- **kwargs - Passed to `matplotlib.colors.LinearSegmentedColormap`. + Passed to [matplotlib.colors.LinearSegmentedColormap](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.LinearSegmentedColormap.html). See also -------- @@ -357,7 +357,7 @@ Parameters ---------- path : path-like, optional The output filename. If not provided, the colormap is saved in the - ``cmaps`` subfolder in :func:`~ultraplot.config.Configurator.user_folder` + ``cmaps`` subfolder in [user_folder](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.user_folder) under the filename ``name.json`` (where ``name`` is the colormap name). Valid extensions are shown in the below table. @@ -560,7 +560,7 @@ PerceptualColormap.from_list""" ... class DiscreteColormap(mcolors.ListedColormap, _Colormap): - """Replacement for `~matplotlib.colors.ListedColormap`.""" + """Replacement for [ListedColormap](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.ListedColormap.html).""" def __str__(self) -> str: ... @@ -595,7 +595,7 @@ alpha : float, optional Other parameters ---------------- **kwargs - Passed to `~matplotlib.colors.ListedColormap`. + Passed to [ListedColormap](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.ListedColormap.html). See also -------- @@ -635,7 +635,7 @@ Parameters ---------- path : path-like, optional The output filename. If not provided, the colormap is saved in the - ``cycles`` subfolder in :func:`~ultraplot.config.Configurator.user_folder` + ``cycles`` subfolder in [user_folder](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.user_folder) under the filename ``name.hex`` (where ``name`` is the color cycle name). Valid extensions are described in the below table. @@ -777,16 +777,16 @@ segmentdata : dict-like ``'s'``, ``'l'``, ``'a'``, and ``'c'`` are also acceptable. The key values can be callable functions that return channel values given a colormap index, or 3-column arrays indicating the coordinates and - channel transitions. See `~matplotlib.colors.LinearSegmentedColormap` + channel transitions. See [LinearSegmentedColormap](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.LinearSegmentedColormap.html) for a more detailed explanation. name : str, default: '_no_name' The colormap name. This can also be passed as the first positional string argument. -N : int, default: :rc:`image.lut` +N : int, default: [image.lut](https://ultraplot.readthedocs.io/en/stable/search.html?q=image.lut) Number of points in the colormap lookup table. space : {'hsl', 'hpl', 'hcl', 'hsv'}, optional The hue, saturation, luminance-style colorspace to use for interpreting - the channels. See `this page `__ for + the channels. See [this page](http://www.hsluv.org/comparison/) for a full description. clip : bool, optional Whether to "clip" impossible colors (i.e. truncate HCL colors with @@ -796,11 +796,11 @@ gamma : float, optional gamma1 : float, optional If greater than 1, make low saturation colors more prominent. If less than 1, make high saturation colors more prominent. Similar to - the `HCLWizard `_ option. + the [HCLWizard](http://hclwizard.org:64230/hclwizard/) option. gamma2 : float, optional If greater than 1, make high luminance colors more prominent. If less than 1, make low luminance colors more prominent. Similar to - the `HCLWizard `_ option. + the [HCLWizard](http://hclwizard.org:64230/hclwizard/) option. alpha : float, optional The opacity for the entire colormap. This overrides the input opacities. @@ -835,7 +835,7 @@ ultraplot.constructor.Colormap""" ... def _init(self) -> None: - """As with `~matplotlib.colors.LinearSegmentedColormap`, but convert + """As with [LinearSegmentedColormap](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.LinearSegmentedColormap.html), but convert each value in the lookup table from ``self._space`` to RGB.""" ... @@ -849,11 +849,11 @@ gamma : float, optional gamma1 : float, optional If greater than 1, make low saturation colors more prominent. If less than 1, make high saturation colors more prominent. Similar to - the `HCLWizard `_ option. + the [HCLWizard](http://hclwizard.org:64230/hclwizard/) option. gamma2 : float, optional If greater than 1, make high luminance colors more prominent. If less than 1, make low luminance colors more prominent. Similar to - the `HCLWizard `_ option.""" + the [HCLWizard](http://hclwizard.org:64230/hclwizard/) option.""" ... def copy(self, name: Incomplete=None, segmentdata: Incomplete=None, N: Incomplete=None, *, alpha: Incomplete=None, gamma: Incomplete=None, cyclic: Incomplete=None, clip: Incomplete=None, gamma1: Incomplete=None, gamma2: Incomplete=None, space: Incomplete=None) -> PerceptualColormap: @@ -907,7 +907,7 @@ name : str, default: '_no_name' positional string argument. space : {'hsl', 'hpl', 'hcl', 'hsv'}, optional The hue, saturation, luminance-style colorspace to use for interpreting - the channels. See `this page `__ for + the channels. See [this page](http://www.hsluv.org/comparison/) for a full description. l, s, a, c Shorthands for `luminance`, `saturation`, `alpha`, and `chroma`. @@ -946,7 +946,7 @@ Parameters ---------- space : {'hsl', 'hpl', 'hcl', 'hsv'}, optional The hue, saturation, luminance-style colorspace to use for interpreting - the channels. See `this page `__ for + the channels. See [this page](http://www.hsluv.org/comparison/) for a full description. name : str, default: '_no_name' The colormap name. This can also be passed as the first @@ -1047,7 +1047,7 @@ def _interpolate_scalar(x: Incomplete, x0: Incomplete, x1: Incomplete, y0: Incom ... def _interpolate_extrapolate_vector(xq: Incomplete, x: Incomplete, y: Incomplete) -> Incomplete: - """Interpolate between two vectors. Similar to `numpy.interp` except this + """Interpolate between two vectors. Similar to [numpy.interp](https://numpy.org/doc/stable/reference/generated/numpy.interp.html) except this does not truncate out-of-bounds values (i.e. this is reversible).""" ... @@ -1066,7 +1066,7 @@ levels : sequence of float The level boundaries. Must be monotonically increasing or decreasing. If the latter then `~DiscreteNorm.descending` is set to ``True`` and the colorbar axis drawn with this normalizer will be reversed. -norm : `~matplotlib.colors.Normalize`, optional +norm : [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html), optional The normalizer used to transform `levels` and data values passed to `~DiscreteNorm.__call__` before discretization. The ``vmin`` and ``vmax`` of the normalizer are set to the minimum and maximum values in `levels`. @@ -1074,8 +1074,8 @@ unique : {'neither', 'both', 'min', 'max'}, optional Which out-of-bounds regions should be assigned unique colormap colors. Possible values are equivalent to the `extend` values. Internally, ultraplot sets this depending on the user-input `extend`, whether the colormap is - cyclic, and whether `~matplotlib.colors.Colormap.set_under` - or `~matplotlib.colors.Colormap.set_over` were called for the colormap. + cyclic, and whether [set_under](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Colormap.set_under.html) + or [set_over](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Colormap.set_over.html) were called for the colormap. step : float, optional The intensity of the transition to out-of-bounds colors as a fraction of the adjacent step between in-bounds colors. Internally, ultraplot sets @@ -1165,13 +1165,13 @@ Note ---- The algorithm this normalizer uses to select normalized values in-between level list indices is adapted from the algorithm -`~matplotlib.colors.LinearSegmentedColormap` uses to select channel +[LinearSegmentedColormap](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.LinearSegmentedColormap.html) uses to select channel values in-between segment data points (hence the name `SegmentedNorm`). Example ------- In the below example, unevenly spaced levels are passed to -`~matplotlib.axes.Axes.contourf`, resulting in the automatic +[contourf](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.contourf.html), resulting in the automatic application of `SegmentedNorm`. >>> import ultraplot as uplt @@ -1302,7 +1302,7 @@ colors "on-the-fly" from registered colormaps and color cycles. This works everywhere that colors are used in matplotlib, for example as `color`, `edgecolor`, or `facecolor` keyword arguments -passed to :class:`~ultraplot.axes.PlotAxes` commands.""" +passed to [PlotAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PlotAxes.html) commands.""" ... def __setitem__(self, key: Incomplete, value: Incomplete) -> None: @@ -1352,11 +1352,11 @@ kwargs : dict-like Parameters ---------- -cmap : str or `~matplotlib.colors.Colormap` or None +cmap : str or [Colormap](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Colormap.html) or None - if a `.Colormap`, return it - if a string, look it up in ``mpl.colormaps`` - - if None, return the Colormap defined in :rc:`image.cmap` + - if None, return the Colormap defined in [image.cmap](https://ultraplot.readthedocs.io/en/stable/search.html?q=image.cmap) Returns ------- diff --git a/ultraplot/config.pyi b/ultraplot/config.pyi index aa4397d9d..de28676c5 100644 --- a/ultraplot/config.pyi +++ b/ultraplot/config.pyi @@ -2,7 +2,7 @@ # fmt: off """ Tools for setting up ultraplot and configuring global settings. -See the :ref:`configuration guide ` for details. +See the [configuration guide](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_config) for details. """ from _typeshed import Incomplete import logging @@ -69,7 +69,7 @@ def _infer_ultraplot_dict(kw_params: Incomplete) -> Incomplete: ... def config_inline_backend(fmt: Incomplete=None) -> None: - """Set up the ipython `inline backend display format `__ + """Set up the ipython [inline backend display format](https://ipython.readthedocs.io/en/stable/interactive/magics.html#magic-matplotlib) and ensure that inline figures always look the same as saved figures. This runs the following ipython magic commands: @@ -81,11 +81,11 @@ This runs the following ipython magic commands: %%config InlineBackend.print_figure_kwargs = {'bbox_inches': None} When the inline backend is inactive or unavailable, this has no effect. -This function is called when you modify the :rcraw:`inlineformat` property. +This function is called when you modify the [inlineformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=inlineformat) property. Parameters ---------- -fmt : str or sequence, default: :rc:`inlineformat` +fmt : str or sequence, default: [inlineformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=inlineformat) The inline backend file format or a list thereof. Valid formats include ``'jpg'``, ``'png'``, ``'svg'``, ``'pdf'``, and ``'retina'``. @@ -95,9 +95,9 @@ Configurator""" ... def use_style(style: Incomplete) -> None: - """Apply the `matplotlib style(s) `__ -with `matplotlib.style.use`. This function is -called when you modify the :rcraw:`style` property. + """Apply the [matplotlib style(s)](https://matplotlib.org/stable/tutorials/introductory/customizing.html) +with [matplotlib.style.use](https://matplotlib.org/stable/api/_as_gen/matplotlib.style.use.html). This function is +called when you modify the [style](https://ultraplot.readthedocs.io/en/stable/search.html?q=style) property. Parameters ---------- @@ -117,9 +117,9 @@ def register_cmaps(*args: Incomplete, user: Incomplete=None, local: Incomplete=N Parameters ---------- -*args : path-spec or `~ultraplot.colors.ContinuousColormap`, optional +*args : path-spec or [ContinuousColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html), optional The colormaps to register. These can be file paths containing - RGB data or `~ultraplot.colors.ContinuousColormap` instances. By default, + RGB data or [ContinuousColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html) instances. By default, if positional arguments are passed, then `user` is set to ``False``. Valid file extensions are listed in the below table. Note that colormaps @@ -157,9 +157,9 @@ def register_cycles(*args: Incomplete, user: Incomplete=None, local: Incomplete= Parameters ---------- -*args : path-spec or `~ultraplot.colors.DiscreteColormap`, optional +*args : path-spec or [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html), optional The color cycles to register. These can be file paths containing - RGB data or `~ultraplot.colors.DiscreteColormap` instances. By default, + RGB data or [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html) instances. By default, if positional arguments are passed, then `user` is set to ``False``. Valid file extensions are listed in the below table. Note that color cycles @@ -213,11 +213,11 @@ default : bool, default: False Default is always ``False``. space : {'hcl', 'hsl', 'hpl'}, optional The colorspace used to pick "perceptually distinct" colors from - the `XKCD color survey `__. + the [XKCD color survey](https://xkcd.com/color/rgb/). If passed then `default` is set to ``True``. margin : float, default: 0.1 The margin used to pick "perceptually distinct" colors from the - `XKCD color survey `__. The normalized hue, + [XKCD color survey](https://xkcd.com/color/rgb/). The normalized hue, saturation, and luminance of each color must differ from the channel values of the prededing colors by `margin` in order to be registered. Must fall between ``0`` and ``1`` (``0`` will register all colors). @@ -242,7 +242,7 @@ Parameters *args : path-like, optional The font files to add. By default, if positional arguments are passed, then `user` is set to ``False``. Files must have the extensions ``.ttf`` or ``.otf``. - See `this link `__ + See [this link](https://gree2.github.io/python/2015/04/27/python-change-matplotlib-font-on-mac) for a guide on converting other font files to ``.ttf`` and ``.otf``. user : bool, optional Whether to reload fonts from `~Configurator.user_folder`. Default is @@ -263,11 +263,10 @@ ultraplot.demos.show_fonts""" ... class Configurator(MutableMapping, dict): - """A dictionary-like class for managing `matplotlib settings -`__ -stored in `rc_matplotlib` and :ref:`ultraplot settings ` + """A dictionary-like class for managing [matplotlib settings](https://matplotlib.org/stable/tutorials/introductory/customizing.html) +stored in `rc_matplotlib` and [ultraplot settings](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_rcultraplot) stored in `rc_ultraplot`. This class is instantiated as the `rc` object -on import. See the :ref:`user guide ` for details.""" +on import. See the [user guide](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_config) for details.""" def __repr__(self) -> str: ... @@ -452,7 +451,7 @@ Configurator.local_files""" def user_file() -> str: """Return location of the default ultraplotrc file. On Linux, this is either ``$XDG_CONFIG_HOME/ultraplot/ultraplotrc`` or ``~/.config/ultraplot/ultraplotrc`` -if the `XDG directory `__ +if the [XDG directory](https://wiki.archlinux.org/title/XDG_Base_Directory) is unset. On other operating systems, this is ``~/.ultraplot/ultraplotrc``. The location ``~/.ultraplotrc`` or ``~/.ultraplot/ultraplotrc`` is always returned if the file exists, regardless of the operating system. If multiple valid locations @@ -468,7 +467,7 @@ Configurator.local_files""" def user_folder(subfolder: Incomplete=None) -> str: """Return location of the default ultraplot folder. On Linux, this is either ``$XDG_CONFIG_HOME/ultraplot`` or ``~/.config/ultraplot`` -if the `XDG directory `__ +if the [XDG directory](https://wiki.archlinux.org/title/XDG_Base_Directory) is unset. On other operating systems, this is ``~/.ultraplot``. The location ``~/.ultraplot`` is always returned if the folder exists, regardless of the operating system. If multiple valid locations are found, a warning is raised. @@ -506,7 +505,7 @@ mode : {0, 1, 2}, optional whether or not they are local to the "with as" block. * ``mode=1``: Matplotlib's `rc_matplotlib` settings are only returned if they are local to the "with as" block. For example, - if :rcraw:`axes.titlesize` was passed to `~Configurator.context`, + if [axes.titlesize](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.titlesize) was passed to `~Configurator.context`, then ``uplt.rc.find('axes.titlesize', context=True)`` will return this value, but ``uplt.rc.find('axes.titleweight', context=True)`` will return ``None``. This is used internally when instantiating axes. @@ -517,10 +516,10 @@ mode : {0, 1, 2}, optional Note ---- Context "modes" are primarily used internally but may also be useful for power -users. Mode ``1`` is used when `~ultraplot.axes.Axes.format` is called during -axes instantiation, and mode ``2`` is used when `~ultraplot.axes.Axes.format` +users. Mode ``1`` is used when [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.format) is called during +axes instantiation, and mode ``2`` is used when [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.format) is manually called by users. The latter prevents successive calls to -`~ultraplot.axes.Axes.format` from constantly looking up and re-applying +[format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.format) from constantly looking up and re-applying unchanged settings and significantly increasing the runtime. Example @@ -534,7 +533,7 @@ The below applies settings to axes in a specific figure using >>> ax.plot(data) The below applies settings to a specific axes using -`~ultraplot.axes.Axes.format`, which uses `~Configurator.context` +[format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.format), which uses `~Configurator.context` internally. >>> import ultraplot as uplt @@ -608,7 +607,7 @@ Parameters a "category" name as the first argument, in which case all settings are prepended with ``'category.'``. For example, ``rc.update('axes', labelsize=20, titlesize=20)`` changes the - :rcraw:`axes.labelsize` and :rcraw:`axes.titlesize` settings. + [axes.labelsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.labelsize) and [axes.titlesize](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.titlesize) settings. **kwargs `rc` keys and values passed as keyword arguments. If the name has dots, simply omit them. @@ -681,7 +680,7 @@ comment : bool, optional this takes the same value as `user`. description : bool, default: False Whether to include descriptions of each setting (as seen in the - :ref:`user guide table `) as comments. + [user guide table](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_rctable)) as comments. See also -------- diff --git a/ultraplot/constructor.pyi b/ultraplot/constructor.pyi index fddcf8d42..f1581f5ef 100644 --- a/ultraplot/constructor.pyi +++ b/ultraplot/constructor.pyi @@ -115,38 +115,38 @@ def _modify_colormap(cmap: Incomplete, *, cut: Incomplete, left: Incomplete, rig def Colormap(*args: Incomplete, name: Incomplete=None, listmode: Incomplete='perceptual', filemode: Incomplete='continuous', discrete: Incomplete=False, cycle: Incomplete=None, save: Incomplete=False, save_kw: Incomplete=None, **kwargs: Incomplete) -> Incomplete: """Generate, retrieve, modify, and/or merge instances of -:class:`~ultraplot.colors.PerceptualColormap`, -:class:`~ultraplot.colors.ContinuousColormap`, and -:class:`~ultraplot.colors.DiscreteColormap`. +[PerceptualColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.PerceptualColormap.html), +[ContinuousColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html), and +[DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html). 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`. + [append](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html#ultraplot.colors.ContinuousColormap.append) + or [append](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html#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 + is loaded with [ultraplot.colors.ContinuousColormap.from_file](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html#ultraplot.colors.ContinuousColormap.from_file) or + [ultraplot.colors.DiscreteColormap.from_file](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html#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`. + [ContinuousColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html). + * If RGB tuple or color string, a [PerceptualColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.PerceptualColormap.html) + is generated with [from_color](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.PerceptualColormap.html#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 + [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html), [PerceptualColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.PerceptualColormap.html), + or [ContinuousColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html) 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`. + [PerceptualColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.PerceptualColormap.html). + * If dictionary, a [PerceptualColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.PerceptualColormap.html) is + generated with [from_hsl](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.PerceptualColormap.html#ultraplot.colors.PerceptualColormap.from_hsl). The dictionary should contain the keys ``'hue'``, ``'saturation'``, ``'luminance'``, and optionally ``'alpha'``, or their aliases (see below). @@ -159,11 +159,11 @@ filemode : {'perceptual', 'continuous', 'discrete'}, optional 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`. + [from_file](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html#ultraplot.colors.ContinuousColormap.from_file). The resulting + colormap may be a [ContinuousColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html) or + [PerceptualColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.PerceptualColormap.html) depending on the data file. + * If ``'discrete'``, a [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html) is generated + using [from_file](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html#ultraplot.colors.ContinuousColormap.from_file). Default is ``'continuous'`` when calling `Colormap` directly and ``'discrete'`` when `Colormap` is called by `Cycle`. @@ -171,28 +171,28 @@ 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 + * If ``'perceptual'``, a [PerceptualColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.PerceptualColormap.html) + is generated with [from_list](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.PerceptualColormap.html#ultraplot.colors.PerceptualColormap.from_list). + * If ``'continuous'``, a [ContinuousColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html) is + generated with [from_list](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html#ultraplot.colors.ContinuousColormap.from_list). + * If ``'discrete'``, a [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html) 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 + For [ContinuousColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html)\\ s, this is used to + generate [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html)\\ s with + [to_discrete](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html#ultraplot.colors.ContinuousColormap.to_discrete). For + [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html)\\ 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 + [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html), we leave it alone, but when it is a + [ContinuousColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html), we always call + [to_discrete](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html#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 @@ -202,12 +202,12 @@ left, right : float or sequence of float, optional 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, + [cut](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html#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 + [reversed](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html#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 @@ -219,25 +219,25 @@ 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 + [ultraplot.colors.ContinuousColormap.set_alpha](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html#ultraplot.colors.ContinuousColormap.set_alpha) + or [ultraplot.colors.DiscreteColormap.set_alpha](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html#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`. + [from_hsl](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.PerceptualColormap.html#ultraplot.colors.PerceptualColormap.from_hsl) and + [from_color](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.PerceptualColormap.html#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 + [from_hsl](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.PerceptualColormap.html#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`. + generated with [from_color](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.PerceptualColormap.html#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. @@ -246,29 +246,29 @@ 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 + and ``'C2'``. Default is from the active property [cycle](https://ultraplot.readthedocs.io/en/stable/search.html?q=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`. + [ultraplot.colors.ContinuousColormap.save](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html#ultraplot.colors.ContinuousColormap.save) or + [ultraplot.colors.DiscreteColormap.save](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html#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`. + save method, i.e. [ultraplot.colors.ContinuousColormap.save](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html#ultraplot.colors.ContinuousColormap.save) or + [ultraplot.colors.DiscreteColormap.save](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html#ultraplot.colors.DiscreteColormap.save). Other parameters ---------------- **kwargs - Passed to `ultraplot.colors.ContinuousColormap.copy`, - `ultraplot.colors.PerceptualColormap.copy`, or - `ultraplot.colors.DiscreteColormap.copy`. + Passed to [ultraplot.colors.ContinuousColormap.copy](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html#ultraplot.colors.ContinuousColormap.copy), + [ultraplot.colors.PerceptualColormap.copy](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.PerceptualColormap.html#ultraplot.colors.PerceptualColormap.copy), or + [ultraplot.colors.DiscreteColormap.copy](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html#ultraplot.colors.DiscreteColormap.copy). Returns ------- matplotlib.colors.Colormap - A :class:`~ultraplot.colors.ContinuousColormap` or - :class:`~ultraplot.colors.DiscreteColormap` instance. + A [ContinuousColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html) or + [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html) instance. See also -------- @@ -293,12 +293,12 @@ Parameters * 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`` + * If a [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html), colors from the ``colors`` attribute are used. - * If a string cycle name, that :class:`~ultraplot.colors.DiscreteColormap` + * If a string cycle name, that [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html) 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` + colors from the resulting [ContinuousColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html) are used. See the `samples` argument. If the last positional argument is numeric, it is used for the @@ -306,10 +306,10 @@ Parameters N Shorthand for `samples`. samples : float or sequence of float, optional - For :class:`~ultraplot.colors.DiscreteColormap`\\ s, this is the number of + For [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html)\\ 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 + For [ContinuousColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html)\\ 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)`` @@ -320,26 +320,26 @@ 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`. + included for consistency with [set_prop_cycle](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_prop_cycle.html). 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 + Lists of [Line2D](https://matplotlib.org/stable/api/_as_gen/matplotlib.lines.Line2D.html) 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 `__, - the `marker reference `__, - and the `custom dashes reference `__. + on cyclers see [set_prop_cycle](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_prop_cycle.html). 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` + to `Colormap` and used to build the [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html) from which the cycler will draw its colors. See also @@ -389,14 +389,14 @@ ultraplot.utils.get_colors""" ... def Norm(norm: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: - """Return an arbitrary `~matplotlib.colors.Normalize` instance. See this -`tutorial `__ + """Return an arbitrary [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) 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` +norm : str or [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) + The normalizer specification. If a [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) 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). @@ -410,24 +410,24 @@ norm : str or `~matplotlib.colors.Normalize` =============================== ===================================== Key(s) Class =============================== ===================================== - ``'null'``, ``'none'`` `~matplotlib.colors.NoNorm` - ``'diverging'``, ``'div'`` `~ultraplot.colors.DivergingNorm` - ``'segmented'``, ``'segments'`` `~ultraplot.colors.SegmentedNorm` - ``'linear'`` `~matplotlib.colors.Normalize` - ``'log'`` `~matplotlib.colors.LogNorm` - ``'power'`` `~matplotlib.colors.PowerNorm` - ``'symlog'`` `~matplotlib.colors.SymLogNorm` + ``'null'``, ``'none'`` [NoNorm](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.NoNorm.html) + ``'diverging'``, ``'div'`` [DivergingNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DivergingNorm.html) + ``'segmented'``, ``'segments'`` [SegmentedNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.SegmentedNorm.html) + ``'linear'`` [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) + ``'log'`` [LogNorm](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.LogNorm.html) + ``'power'`` [PowerNorm](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.PowerNorm.html) + ``'symlog'`` [SymLogNorm](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.SymLogNorm.html) =============================== ===================================== Other parameters ---------------- *args, **kwargs - Passed to the `~matplotlib.colors.Normalize` initializer. + Passed to the [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) initializer. Returns ------- matplotlib.colors.Normalize - A `~matplotlib.colors.Normalize` instance. + A [Normalize](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Normalize.html) instance. See also -------- @@ -437,22 +437,22 @@ ultraplot.constructor.Colormap""" ... def Locator(locator: Incomplete, *args: Incomplete, discrete: Incomplete=False, **kwargs: Incomplete) -> Incomplete: - """Return a `~matplotlib.ticker.Locator` instance. + """Return a [Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) instance. Parameters ---------- -locator : `~matplotlib.ticker.Locator`, str, bool, float, or sequence +locator : [Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html), str, bool, float, or sequence The locator specification, interpreted as follows: - * If a `~matplotlib.ticker.Locator` instance already, + * If a [Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) 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 ``False``, a [NullLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.NullLocator.html) is used, and if + ``True``, the default [AutoLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.AutoLocator.html) is used. * If a number, this specifies the *step size* between tick locations. - Returns a `~matplotlib.ticker.MultipleLocator`. + Returns a [MultipleLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MultipleLocator.html). * If a sequence of numbers, these points are ticked. Returns - a `~matplotlib.ticker.FixedLocator` by default or a - `~ultraplot.ticker.DiscreteLocator` if `discrete` is ``True``. + a [FixedLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.FixedLocator.html) by default or a + [DiscreteLocator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.DiscreteLocator.html) if `discrete` is ``True``. Otherwise, `locator` should be a string corresponding to one of the "registered" locators (see below table). If `locator` is a @@ -466,48 +466,48 @@ locator : `~matplotlib.ticker.Locator`, str, bool, float, or sequence ======================= ============================================ ===================================================================================== 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'`` `~ultraplot.ticker.DiscreteLocator` Major ticks restricted to these locations but subsampled depending on the axis length - ``'discreteminor'`` `~ultraplot.ticker.DiscreteLocator` Minor ticks restricted to these locations but subsampled depending on the axis length - ``'index'`` :class:`~ultraplot.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'`` `~ultraplot.ticker.LongitudeLocator` Longitude gridlines at sensible decimal locations - ``'lat'``, ``'deglat'`` `~ultraplot.ticker.LatitudeLocator` Latitude gridlines at sensible decimal locations - ``'dms'`` `~ultraplot.ticker.DegreeLocator` Gridlines on nice minute and second intervals - ``'dmslon'`` `~ultraplot.ticker.LongitudeLocator` Longitude gridlines on nice minute and second intervals - ``'dmslat'`` `~ultraplot.ticker.LatitudeLocator` Latitude gridlines on nice minute and second intervals + ``'null'``, ``'none'`` [NullLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.NullLocator.html) No ticks + ``'auto'`` [AutoLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.AutoLocator.html) Major ticks at sensible locations + ``'minor'`` [AutoMinorLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.AutoMinorLocator.html) Minor ticks at sensible locations + ``'date'`` [AutoDateLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.dates.AutoDateLocator.html) Default tick locations for datetime axes + ``'fixed'`` [FixedLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.FixedLocator.html) Ticks at these exact locations + ``'discrete'`` [DiscreteLocator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.DiscreteLocator.html) Major ticks restricted to these locations but subsampled depending on the axis length + ``'discreteminor'`` [DiscreteLocator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.DiscreteLocator.html) Minor ticks restricted to these locations but subsampled depending on the axis length + ``'index'`` [IndexLocator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.IndexLocator.html) Ticks on the non-negative integers + ``'linear'`` [LinearLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.LinearLocator.html) Exactly ``N`` ticks encompassing axis limits, spaced as ``numpy.linspace(lo, hi, N)`` + ``'log'`` [LogLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.LogLocator.html) For log-scale axes + ``'logminor'`` [LogLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.LogLocator.html) For log-scale axes on the 1st through 9th multiples of each power of the base + ``'logit'`` [LogitLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.LogitLocator.html) For logit-scale axes + ``'logitminor'`` [LogitLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.LogitLocator.html) For logit-scale axes with ``minor=True`` passed to [LogitLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.LogitLocator.html) + ``'maxn'`` [MaxNLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MaxNLocator.html) No more than ``N`` ticks at sensible locations + ``'multiple'`` [MultipleLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.MultipleLocator.html) Ticks every ``N`` step away from zero + ``'symlog'`` [SymmetricalLogLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.SymmetricalLogLocator.html) For symlog-scale axes + ``'symlogminor'`` [SymmetricalLogLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.SymmetricalLogLocator.html) For symlog-scale axes on the 1st through 9th multiples of each power of the base + ``'theta'`` [ThetaLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.projections.polar.ThetaLocator.html) Like the base locator but default locations are every [numpy.pi](https://numpy.org/doc/stable/reference/generated/numpy.pi.html) / 8 radians + ``'year'`` [YearLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.dates.YearLocator.html) Ticks every ``N`` years + ``'month'`` [MonthLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.dates.MonthLocator.html) Ticks every ``N`` months + ``'weekday'`` [WeekdayLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.dates.WeekdayLocator.html) Ticks every ``N`` weekdays + ``'day'`` [DayLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.dates.DayLocator.html) Ticks every ``N`` days + ``'hour'`` [HourLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.dates.HourLocator.html) Ticks every ``N`` hours + ``'minute'`` [MinuteLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.dates.MinuteLocator.html) Ticks every ``N`` minutes + ``'second'`` [SecondLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.dates.SecondLocator.html) Ticks every ``N`` seconds + ``'microsecond'`` [MicrosecondLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.dates.MicrosecondLocator.html) Ticks every ``N`` microseconds + ``'lon'``, ``'deglon'`` [LongitudeLocator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.LongitudeLocator.html) Longitude gridlines at sensible decimal locations + ``'lat'``, ``'deglat'`` [LatitudeLocator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.LatitudeLocator.html) Latitude gridlines at sensible decimal locations + ``'dms'`` [DegreeLocator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.DegreeLocator.html) Gridlines on nice minute and second intervals + ``'dmslon'`` [LongitudeLocator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.LongitudeLocator.html) Longitude gridlines on nice minute and second intervals + ``'dmslat'`` [LatitudeLocator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.LatitudeLocator.html) Latitude gridlines on nice minute and second intervals ======================= ============================================ ===================================================================================== Other parameters ---------------- *args, **kwargs - Passed to the `~matplotlib.ticker.Locator` class. + Passed to the [Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. Returns ------- matplotlib.ticker.Locator - A `~matplotlib.ticker.Locator` instance. + A [Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) instance. See also -------- @@ -520,33 +520,33 @@ ultraplot.constructor.Formatter""" ... def Formatter(formatter: Incomplete, *args: Incomplete, date: Incomplete=False, index: Incomplete=False, **kwargs: Incomplete) -> Incomplete: - """Return a `~matplotlib.ticker.Formatter` instance. + """Return a [Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) instance. Parameters ---------- -formatter : `~matplotlib.ticker.Formatter`, str, bool, callable, or sequence +formatter : [Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html), str, bool, callable, or sequence The formatter specification, interpreted as follows: - * If a `~matplotlib.ticker.Formatter` instance already, + * If a [Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) instance already, a `copy.copy` of the instance is returned. - * If ``False``, a `~matplotlib.ticker.NullFormatter` is used, and if - ``True``, the default `~ultraplot.ticker.AutoFormatter` is used. + * If ``False``, a [NullFormatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.NullFormatter.html) is used, and if + ``True``, the default [AutoFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.AutoFormatter.html) is used. * If a function, the labels will be generated using this function. - Returns a `~matplotlib.ticker.FuncFormatter`. + Returns a [FuncFormatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.FuncFormatter.html). * If sequence of strings, the ticks are labeled with these strings. - Returns a `~matplotlib.ticker.FixedFormatter` by default or - an :class:`~ultraplot.ticker.IndexFormatter` if `index` is ``True``. + Returns a [FixedFormatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.FixedFormatter.html) by default or + an [IndexFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.IndexFormatter.html) if `index` is ``True``. * If a string containing ``{x}`` or ``{x:...}``, ticks will be formatted by calling ``string.format(x=number)``. Returns - a `~matplotlib.ticker.StrMethodFormatter`. + a [StrMethodFormatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.StrMethodFormatter.html). * If a string containing ``'%%'`` and `date` is ``False``, ticks will be formatted using the C-style ``string %% number`` method. See - `this page `__ - for a review. Returns a `~matplotlib.ticker.FormatStrFormatter`. + [this page](https://docs.python.org/3/library/stdtypes.html#printf-style-string-formatting) + for a review. Returns a [FormatStrFormatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.FormatStrFormatter.html). * If a string containing ``'%%'`` and `date` is ``True``, ticks will be formatted using `~datetime.datetime.strfrtime`. See - `this page `__ - for a review. Returns a `~matplotlib.dates.DateFormatter`. + [this page](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes) + for a review. Returns a [DateFormatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.dates.DateFormatter.html). Otherwise, `formatter` should be a string corresponding to one of the "registered" formatters or formatter presets (see below table). If @@ -563,37 +563,37 @@ formatter : `~matplotlib.ticker.Formatter`, str, bool, callable, or sequence ====================== ============================================== ================================================================= Key Class Description ====================== ============================================== ================================================================= - ``'null'``, ``'none'`` `~matplotlib.ticker.NullFormatter` No tick labels - ``'auto'`` `~ultraplot.ticker.AutoFormatter` New default tick labels for axes - ``'sci'`` `~ultraplot.ticker.SciFormatter` Format ticks with scientific notation - ``'simple'`` `~ultraplot.ticker.SimpleFormatter` New default tick labels for e.g. contour labels - ``'sigfig'`` `~ultraplot.ticker.SigFigFormatter` Format labels using the first ``N`` significant digits - ``'frac'`` `~ultraplot.ticker.FracFormatter` Rational fractions - ``'date'`` `~matplotlib.dates.AutoDateFormatter` Default tick labels for datetime axes - ``'concise'`` `~matplotlib.dates.ConciseDateFormatter` More concise date labels introduced in matplotlib 3.1 - ``'datestr'`` `~matplotlib.dates.DateFormatter` Date formatting with C-style ``string %% format`` notation - ``'eng'`` `~matplotlib.ticker.EngFormatter` Engineering notation - ``'fixed'`` `~matplotlib.ticker.FixedFormatter` List of strings - ``'formatstr'`` `~matplotlib.ticker.FormatStrFormatter` From C-style ``string %% format`` notation - ``'func'`` `~matplotlib.ticker.FuncFormatter` Use an arbitrary function - ``'index'`` :class:`~ultraplot.ticker.IndexFormatter` List of strings corresponding to non-negative integer positions - ``'log'`` `~matplotlib.ticker.LogFormatterSciNotation` For log-scale axes with scientific notation - ``'logit'`` `~matplotlib.ticker.LogitFormatter` For logistic-scale axes - ``'percent'`` `~matplotlib.ticker.PercentFormatter` Trailing percent sign - ``'scalar'`` `~matplotlib.ticker.ScalarFormatter` The default matplotlib formatter - ``'strmethod'`` `~matplotlib.ticker.StrMethodFormatter` From the ``string.format`` method - ``'theta'`` `~matplotlib.projections.polar.ThetaFormatter` Formats radians as degrees, with a degree symbol - ``'e'`` `~ultraplot.ticker.FracFormatter` preset Fractions of *e* - ``'pi'`` `~ultraplot.ticker.FracFormatter` preset Fractions of :math:`\\pi` - ``'tau'`` `~ultraplot.ticker.FracFormatter` preset Fractions of the `one true circle constant `_ :math:`\\tau` - ``'lat'`` `~ultraplot.ticker.AutoFormatter` preset Cardinal "SN" indicator - ``'lon'`` `~ultraplot.ticker.AutoFormatter` preset Cardinal "WE" indicator - ``'deg'`` `~ultraplot.ticker.AutoFormatter` preset Trailing degree symbol - ``'deglat'`` `~ultraplot.ticker.AutoFormatter` preset Trailing degree symbol and cardinal "SN" indicator - ``'deglon'`` `~ultraplot.ticker.AutoFormatter` preset Trailing degree symbol and cardinal "WE" indicator - ``'dms'`` `~ultraplot.ticker.DegreeFormatter` Labels with degree/minute/second support - ``'dmslon'`` `~ultraplot.ticker.LongitudeFormatter` Longitude labels with degree/minute/second support - ``'dmslat'`` `~ultraplot.ticker.LatitudeFormatter` Latitude labels with degree/minute/second support + ``'null'``, ``'none'`` [NullFormatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.NullFormatter.html) No tick labels + ``'auto'`` [AutoFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.AutoFormatter.html) New default tick labels for axes + ``'sci'`` [SciFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.SciFormatter.html) Format ticks with scientific notation + ``'simple'`` [SimpleFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.SimpleFormatter.html) New default tick labels for e.g. contour labels + ``'sigfig'`` [SigFigFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.SigFigFormatter.html) Format labels using the first ``N`` significant digits + ``'frac'`` [FracFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.FracFormatter.html) Rational fractions + ``'date'`` [AutoDateFormatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.dates.AutoDateFormatter.html) Default tick labels for datetime axes + ``'concise'`` [ConciseDateFormatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.dates.ConciseDateFormatter.html) More concise date labels introduced in matplotlib 3.1 + ``'datestr'`` [DateFormatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.dates.DateFormatter.html) Date formatting with C-style ``string %% format`` notation + ``'eng'`` [EngFormatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.EngFormatter.html) Engineering notation + ``'fixed'`` [FixedFormatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.FixedFormatter.html) List of strings + ``'formatstr'`` [FormatStrFormatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.FormatStrFormatter.html) From C-style ``string %% format`` notation + ``'func'`` [FuncFormatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.FuncFormatter.html) Use an arbitrary function + ``'index'`` [IndexFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.IndexFormatter.html) List of strings corresponding to non-negative integer positions + ``'log'`` [LogFormatterSciNotation](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.LogFormatterSciNotation.html) For log-scale axes with scientific notation + ``'logit'`` [LogitFormatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.LogitFormatter.html) For logistic-scale axes + ``'percent'`` [PercentFormatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.PercentFormatter.html) Trailing percent sign + ``'scalar'`` [ScalarFormatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.ScalarFormatter.html) The default matplotlib formatter + ``'strmethod'`` [StrMethodFormatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.StrMethodFormatter.html) From the ``string.format`` method + ``'theta'`` [ThetaFormatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.projections.polar.ThetaFormatter.html) Formats radians as degrees, with a degree symbol + ``'e'`` [FracFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.FracFormatter.html) preset Fractions of *e* + ``'pi'`` [FracFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.FracFormatter.html) preset Fractions of :math:`\\pi` + ``'tau'`` [FracFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.FracFormatter.html) preset Fractions of the `one true circle constant `_ :math:`\\tau` + ``'lat'`` [AutoFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.AutoFormatter.html) preset Cardinal "SN" indicator + ``'lon'`` [AutoFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.AutoFormatter.html) preset Cardinal "WE" indicator + ``'deg'`` [AutoFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.AutoFormatter.html) preset Trailing degree symbol + ``'deglat'`` [AutoFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.AutoFormatter.html) preset Trailing degree symbol and cardinal "SN" indicator + ``'deglon'`` [AutoFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.AutoFormatter.html) preset Trailing degree symbol and cardinal "WE" indicator + ``'dms'`` [DegreeFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.DegreeFormatter.html) Labels with degree/minute/second support + ``'dmslon'`` [LongitudeFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.LongitudeFormatter.html) Longitude labels with degree/minute/second support + ``'dmslat'`` [LatitudeFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.LatitudeFormatter.html) Latitude labels with degree/minute/second support ====================== ============================================== ================================================================= date : bool, optional @@ -606,12 +606,12 @@ index : bool, optional Other parameters ---------------- *args, **kwargs - Passed to the `~matplotlib.ticker.Formatter` class. + Passed to the [Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) class. Returns ------- matplotlib.ticker.Formatter - A `~matplotlib.ticker.Formatter` instance. + A [Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) instance. See also -------- @@ -624,12 +624,12 @@ ultraplot.constructor.Locator""" ... def Scale(scale: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: - """Return a `~matplotlib.scale.ScaleBase` instance. + """Return a [ScaleBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.ScaleBase.html) instance. Parameters ---------- -scale : `~matplotlib.scale.ScaleBase`, str, or tuple - The axis scale specification. If a `~matplotlib.scale.ScaleBase` instance +scale : [ScaleBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.ScaleBase.html), str, or tuple + The axis scale specification. If a [ScaleBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.ScaleBase.html) instance already, a `copy.copy` of the instance is returned. Otherwise, `scale` should be a string corresponding to one of the "registered" axis scales or axis scale presets (see below table). @@ -643,26 +643,26 @@ scale : `~matplotlib.scale.ScaleBase`, str, or tuple ================= ====================================== =============================================== Key Class Description ================= ====================================== =============================================== - ``'linear'`` `~ultraplot.scale.LinearScale` Linear - ``'log'`` `~ultraplot.scale.LogScale` Logarithmic - ``'symlog'`` `~ultraplot.scale.SymmetricalLogScale` Logarithmic beyond finite space around zero - ``'logit'`` `~ultraplot.scale.LogitScale` Logistic - ``'inverse'`` `~ultraplot.scale.InverseScale` Inverse - ``'function'`` `~ultraplot.scale.FuncScale` Arbitrary forward and backwards transformations - ``'sine'`` `~ultraplot.scale.SineLatitudeScale` Sine function (in degrees) - ``'mercator'`` `~ultraplot.scale.MercatorLatitudeScale` Mercator latitude function (in degrees) - ``'exp'`` `~ultraplot.scale.ExpScale` Arbitrary exponential function - ``'power'`` `~ultraplot.scale.PowerScale` Arbitrary power function - ``'cutoff'`` `~ultraplot.scale.CutoffScale` Arbitrary piecewise linear transformations - ``'quadratic'`` `~ultraplot.scale.PowerScale` (preset) Quadratic function - ``'cubic'`` `~ultraplot.scale.PowerScale` (preset) Cubic function - ``'quartic'`` `~ultraplot.scale.PowerScale` (preset) Quartic function - ``'db'`` `~ultraplot.scale.ExpScale` (preset) Ratio expressed as `decibels `_ - ``'np'`` `~ultraplot.scale.ExpScale` (preset) Ratio expressed as `nepers `_ - ``'idb'`` `~ultraplot.scale.ExpScale` (preset) `Decibels `_ expressed as ratio - ``'inp'`` `~ultraplot.scale.ExpScale` (preset) `Nepers `_ expressed as ratio - ``'pressure'`` `~ultraplot.scale.ExpScale` (preset) Height (in km) expressed linear in pressure - ``'height'`` `~ultraplot.scale.ExpScale` (preset) Pressure (in hPa) expressed linear in height + ``'linear'`` [LinearScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.LinearScale.html) Linear + ``'log'`` [LogScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.LogScale.html) Logarithmic + ``'symlog'`` [SymmetricalLogScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.SymmetricalLogScale.html) Logarithmic beyond finite space around zero + ``'logit'`` [LogitScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.LogitScale.html) Logistic + ``'inverse'`` [InverseScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.InverseScale.html) Inverse + ``'function'`` [FuncScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.FuncScale.html) Arbitrary forward and backwards transformations + ``'sine'`` [SineLatitudeScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.SineLatitudeScale.html) Sine function (in degrees) + ``'mercator'`` [MercatorLatitudeScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.MercatorLatitudeScale.html) Mercator latitude function (in degrees) + ``'exp'`` [ExpScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.ExpScale.html) Arbitrary exponential function + ``'power'`` [PowerScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.PowerScale.html) Arbitrary power function + ``'cutoff'`` [CutoffScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.CutoffScale.html) Arbitrary piecewise linear transformations + ``'quadratic'`` [PowerScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.PowerScale.html) (preset) Quadratic function + ``'cubic'`` [PowerScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.PowerScale.html) (preset) Cubic function + ``'quartic'`` [PowerScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.PowerScale.html) (preset) Quartic function + ``'db'`` [ExpScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.ExpScale.html) (preset) Ratio expressed as `decibels `_ + ``'np'`` [ExpScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.ExpScale.html) (preset) Ratio expressed as `nepers `_ + ``'idb'`` [ExpScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.ExpScale.html) (preset) `Decibels `_ expressed as ratio + ``'inp'`` [ExpScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.ExpScale.html) (preset) `Nepers `_ expressed as ratio + ``'pressure'`` [ExpScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.ExpScale.html) (preset) Height (in km) expressed linear in pressure + ``'height'`` [ExpScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.ExpScale.html) (preset) Pressure (in hPa) expressed linear in height ================= ====================================== =============================================== .. _db: https://en.wikipedia.org/wiki/Decibel @@ -671,12 +671,12 @@ scale : `~matplotlib.scale.ScaleBase`, str, or tuple Other parameters ---------------- *args, **kwargs - Passed to the `~matplotlib.scale.ScaleBase` class. + Passed to the [ScaleBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.ScaleBase.html) class. Returns ------- matplotlib.scale.ScaleBase - A `~matplotlib.scale.ScaleBase` instance. + A [ScaleBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.ScaleBase.html) instance. See also -------- @@ -699,12 +699,11 @@ Parameters name : str, `cartopy.crs.Projection`, or `~mpl_toolkits.basemap.Basemap` The projection name or projection class instance. If the latter, it is simply returned. If the former, it must correspond to one of the - `PROJ `__ projection name shorthands, like in + [PROJ](https://proj.org) projection name shorthands, like in basemap. The following table lists the valid projection name shorthands, - their full names (with links to the relevant `PROJ documentation - `__), + their full names (with links to the relevant [PROJ documentation](https://proj.org/operations/projections)), and whether they are available in the cartopy and basemap packages. (added) indicates a projection class that ultraplot has "added" to cartopy using the cartopy API. @@ -767,7 +766,7 @@ name : str, `cartopy.crs.Projection`, or `~mpl_toolkits.basemap.Basemap` ``'wintri'`` `Winkel tripel `_ ✓ (added) ✗ ============= =============================================== ========= ======= -backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` +backend : {'cartopy', 'basemap'}, default: [geo.backend](https://ultraplot.readthedocs.io/en/stable/search.html?q=geo.backend) Whether to return a cartopy `~cartopy.crs.Projection` instance or a basemap `~mpl_toolkits.basemap.Basemap` instance. @@ -807,8 +806,8 @@ ultraplot.axes.GeoAxes References ---------- For more information on map projections, see the -`wikipedia page `__ and the -`PROJ `__ documentation. +[wikipedia page](https://en.wikipedia.org/wiki/Map_projection) and the +[PROJ](https://proj.org) documentation. .. _aea: https://proj.org/operations/projections/aea.html .. _aeqd: https://proj.org/operations/projections/aeqd.html diff --git a/ultraplot/demos.pyi b/ultraplot/demos.pyi index 8cf3d2b73..8237cfd7f 100644 --- a/ultraplot/demos.pyi +++ b/ultraplot/demos.pyi @@ -26,11 +26,11 @@ _colorbar_docstring = ... def show_channels(*args: Incomplete, N: Incomplete=100, rgb: Incomplete=False, saturation: Incomplete=True, minhue: Incomplete=0, maxsat: Incomplete=500, width: Incomplete=100, refwidth: Incomplete=1.7) -> Incomplete: """Show how arbitrary colormap(s) vary with respect to the hue, chroma, luminance, HSL saturation, and HPL saturation channels, and optionally -the red, blue and green channels. Adapted from `this example `__. +the red, blue and green channels. Adapted from [this example](https://matplotlib.org/stable/tutorials/colors/colormaps.html#lightness-of-matplotlib-colormaps). Parameters ---------- -*args : colormap-spec, default: :rc:`image.cmap` +*args : colormap-spec, default: [image.cmap](https://ultraplot.readthedocs.io/en/stable/search.html?q=image.cmap) Positional arguments are colormap names or objects. N : int, optional The number of markers to draw for each colormap. @@ -45,7 +45,7 @@ maxsat : float, optional width : int, optional The width of each colormap line in points. refwidth : int or str, optional - The width of each subplot. Passed to `~ultraplot.ui.subplots`. + The width of each subplot. Passed to [subplots](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ui.subplots.html). Returns ------- @@ -77,7 +77,7 @@ hue : float, optional are drawn for this hue. Must be between ``0`` and ``360``. refwidth : str or float, optional Average width of each subplot. Units are interpreted by - `~ultraplot.utils.units`. + [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Returns ------- @@ -99,13 +99,13 @@ def _draw_bars(cmaps: Incomplete, *, source: Incomplete, unknown: Incomplete='Us def show_cmaps(*args: Incomplete, **kwargs: Incomplete) -> Incomplete: """Generate a table of the registered colormaps or the input colormaps -categorized by source. Adapted from `this example `__. +categorized by source. Adapted from [this example](http://matplotlib.org/stable/gallery/color/colormap_reference.html). Parameters ---------- *args : colormap-spec, optional Colormap names or objects. -N : int, default: :rc:`image.lut` +N : int, default: [image.lut](https://ultraplot.readthedocs.io/en/stable/search.html?q=image.lut) The number of levels in each colorbar. unknown : str, default: 'User' Category name for colormaps that are unknown to ultraplot. @@ -117,14 +117,14 @@ include : str or sequence of str, default: None ignore : str or sequence of str, default: 'MATLAB', 'GNUplot', 'GIST', 'Other' Used only if `include` was not passed. Category names to be removed from the table. Use of the default ignored colormaps is discouraged because they contain - non-uniform color transitions (see the :ref:`user guide `). + non-uniform color transitions (see the [user guide](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_perceptual)). length : unit-spec, optional The length of each colorbar. - If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + If float, units are inches. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). width : float or str, optional The width of each colorbar. - If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. -rasterized : bool, default: :rc:`colorbar.rasterized` + If float, units are inches. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +rasterized : bool, default: [colorbar.rasterized](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.rasterized) Whether to rasterize the colorbar solids. This increases rendering time and decreases file sizes for vector graphics. @@ -146,7 +146,7 @@ show_fonts""" def show_cycles(*args: Incomplete, **kwargs: Incomplete) -> Incomplete: """Generate a table of registered color cycles or the input color cycles -categorized by source. Adapted from `this example `__. +categorized by source. Adapted from [this example](http://matplotlib.org/stable/gallery/color/colormap_reference.html). Parameters ---------- @@ -164,11 +164,11 @@ ignore : str or sequence of str, default: None from the table. length : unit-spec, optional The length of each colorbar. - If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + If float, units are inches. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). width : float or str, optional The width of each colorbar. - If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. -rasterized : bool, default: :rc:`colorbar.rasterized` + If float, units are inches. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +rasterized : bool, default: [colorbar.rasterized](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.rasterized) Whether to rasterize the colorbar solids. This increases rendering time and decreases file sizes for vector graphics. @@ -203,7 +203,7 @@ minsat : float def show_colors(*, nhues: Incomplete=17, minsat: Incomplete=10, unknown: Incomplete='User', include: Incomplete=None, ignore: Incomplete=None) -> Incomplete: """Generate tables of the registered color names. Adapted from -`this example `__. +[this example](https://matplotlib.org/examples/color/named_colors.html). Parameters ---------- @@ -238,22 +238,22 @@ it is replaced with the "¤" dummy character. Parameters ---------- -*args : str or `~matplotlib.font_manager.FontProperties` - The font specs, font names, or `~matplotlib.font_manager.FontProperties`\\ s +*args : str or [FontProperties](https://matplotlib.org/stable/api/_as_gen/matplotlib.font_manager.FontProperties.html) + The font specs, font names, or [FontProperties](https://matplotlib.org/stable/api/_as_gen/matplotlib.font_manager.FontProperties.html)\\ s to show. If no positional arguments are passed and the `family` argument is - not passed, then the fonts found in :func:`~ultraplot.config.Configurator.user_folder` - and `~ultraplot.config.Configurator.local_folders` and the *available* - :rcraw:`font.sans-serif` fonts are shown. + not passed, then the fonts found in [user_folder](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.user_folder) + and [local_folders](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.local_folders) and the *available* + [font.sans-serif](https://ultraplot.readthedocs.io/en/stable/search.html?q=font.sans-serif) fonts are shown. family : {'tex-gyre', 'sans-serif', 'serif', 'monospace', 'cursive', 'fantasy'}, optional The family from which *available* fonts are shown. Default is ``'sans-serif'`` if no arguments were provided. Otherwise the default is to not show family - fonts. The fonts belonging to each family are listed under :rcraw:`font.serif`, - :rcraw:`font.sans-serif`, :rcraw:`font.monospace`, :rcraw:`font.cursive`, and - :rcraw:`font.fantasy`. The special family ``'tex-gyre'`` includes the - `TeX Gyre `__ fonts. + fonts. The fonts belonging to each family are listed under [font.serif](https://ultraplot.readthedocs.io/en/stable/search.html?q=font.serif), + [font.sans-serif](https://ultraplot.readthedocs.io/en/stable/search.html?q=font.sans-serif), [font.monospace](https://ultraplot.readthedocs.io/en/stable/search.html?q=font.monospace), [font.cursive](https://ultraplot.readthedocs.io/en/stable/search.html?q=font.cursive), and + [font.fantasy](https://ultraplot.readthedocs.io/en/stable/search.html?q=font.fantasy). The special family ``'tex-gyre'`` includes the + [TeX Gyre](http://www.gust.org.pl/projects/e-foundry/tex-gyre) fonts. user : bool, optional - Whether to include fonts in :func:`~ultraplot.config.Configurator.user_folder` and - `~ultraplot.config.Configurator.local_folders` at the top of the table. Default + Whether to include fonts in [user_folder](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.user_folder) and + [local_folders](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.local_folders) at the top of the table. Default is ``True`` if called without any arguments and ``False`` otherwise. text : str, optional The sample text shown for each font. If not passed then default math or @@ -262,10 +262,10 @@ math : bool, default: False Whether the default sample text should show non-math Latin characters or or math equations and Greek letters. fallback : bool, default: False - Whether to use the fallback font :rcraw:`mathtext.fallback` for unavailable + Whether to use the fallback font [mathtext.fallback](https://ultraplot.readthedocs.io/en/stable/search.html?q=mathtext.fallback) for unavailable characters. If ``False`` the dummy glyph "¤" is shown for missing characters. **kwargs - Additional font properties passed to `~matplotlib.font_manager.FontProperties`. + Additional font properties passed to [FontProperties](https://matplotlib.org/stable/api/_as_gen/matplotlib.font_manager.FontProperties.html). Default size is ``12`` and default weight, style, and strength are ``'normal'``. Other parameters diff --git a/ultraplot/externals/hsluv.pyi b/ultraplot/externals/hsluv.pyi index 8f4823517..32f195e4c 100644 --- a/ultraplot/externals/hsluv.pyi +++ b/ultraplot/externals/hsluv.pyi @@ -3,8 +3,8 @@ """ Utilities for converting between colorspaces. Includes the following: -* `rgb_to_hsl` (same as `matplotlib.colors.rgb_to_hsv`) -* `hsl_to_rgb` (same as `matplotlib.colors.hsv_to_rgb`) +* `rgb_to_hsl` (same as [matplotlib.colors.rgb_to_hsv](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.rgb_to_hsv.html)) +* `hsl_to_rgb` (same as [matplotlib.colors.hsv_to_rgb](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.hsv_to_rgb.html)) * `hcl_to_rgb` * `rgb_to_hcl` * `hsluv_to_rgb` @@ -14,15 +14,13 @@ Utilities for converting between colorspaces. Includes the following: Note ---- -This file is adapted from `seaborn -`__ -and `hsluv-python -`__. +This file is adapted from [seaborn](https://github.com/mwaskom/seaborn/blob/master/seaborn/external/husl.py) +and [hsluv-python](https://github.com/hsluv/hsluv-python/blob/master/hsluv.py). For more information on colorspaces see the -`CIULUV specification `__, the -`CIE 1931 colorspace `__, -the `HCL colorspace `__, -and the `HSLuv system `__. +[CIULUV specification](https://en.wikipedia.org/wiki/CIELUV), the +[CIE 1931 colorspace](https://en.wikipedia.org/wiki/CIE_1931_color_space), +the [HCL colorspace](https://en.wikipedia.org/wiki/HCL_color_space), +and the [HSLuv system](http://www.hsluv.org/implementations/). """ from _typeshed import Incomplete import math diff --git a/ultraplot/figure.pyi b/ultraplot/figure.pyi index 03c1534b0..554873a92 100644 --- a/ultraplot/figure.pyi +++ b/ultraplot/figure.pyi @@ -70,7 +70,7 @@ def _clear_border_cache(func: _F) -> _F: ... class Figure(mfigure.Figure): - """The `~matplotlib.figure.Figure` subclass used by ultraplot.""" + """The [Figure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html) subclass used by ultraplot.""" _share_message = "Axis sharing level can be 0 or False (share nothing), 1 or 'labels' or 'labs' (share axis labels), 2 or 'limits' or 'lims' (share axis limits and axis labels), 3 or True (share axis limits, axis labels, and tick labels), 4 or 'all' (share axis labels and tick labels in the same gridspec rows and columns and share axis limits across all subplots), or 'auto' (start unshared and share only compatible axes)." _space_message = 'To set the left, right, bottom, top, wspace, or hspace gridspec values, pass them as keyword arguments to uplt.figure() or uplt.subplots(). Please note they are now specified in physical units, with strings interpreted by uplt.units() and floats interpreted as font size-widths.' _tight_message = "ultraplot uses its own tight layout algorithm that is activated by default. To disable it, set uplt.rc['subplots.tight'] to False or pass tight=False to uplt.subplots(). For details, see fig.auto_layout()." @@ -93,11 +93,11 @@ refaspect : float or 2-tuple of float, optional divided by height. If 2-tuple, this indicates the (width, height). Ignored if both `figwidth` *and* `figheight` or both `refwidth` *and* `refheight` were passed. The default value is ``1`` or the "data aspect ratio" if the latter - is explicitly fixed (as with `~ultraplot.axes.PlotAxes.imshow` plots and - `~ultraplot.axes.Axes.GeoAxes` projections; see :func:`~matplotlib.axes.Axes.set_aspect`). -refwidth, refheight : unit-spec, default: :rc:`subplots.refwidth` + is explicitly fixed (as with [imshow](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PlotAxes.html#ultraplot.axes.PlotAxes.imshow) plots and + [GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.GeoAxes) projections; see [set_aspect](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_aspect.html)). +refwidth, refheight : unit-spec, default: [subplots.refwidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.refwidth) The width, height of the reference subplot. - If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + If float, units are inches. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Ignored if `figwidth`, `figheight`, or `figsize` was passed. If you specify just one, `refaspect` will be respected. ref, aspect, axwidth, axheight @@ -105,13 +105,13 @@ ref, aspect, axwidth, axheight *These may be deprecated in a future release.* figwidth, figheight : unit-spec, optional The figure width and height. Default behavior is to use `refwidth`. - If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + If float, units are inches. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). If you specify just one, `refaspect` will be respected. width, height Aliases for `figwidth`, `figheight`. figsize : 2-tuple, optional Tuple specifying the figure ``(width, height)``. -sharex, sharey, share : {0, False, 1, 'labels', 'labs', 2, 'limits', 'lims', 3, True, 4, 'all', 'auto'}, default: :rc:`subplots.share` +sharex, sharey, share : {0, False, 1, 'labels', 'labs', 2, 'limits', 'lims', 3, True, 4, 'all', 'auto'}, default: [subplots.share](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.share) The axis sharing "level" for the *x* axis, *y* axis, or both axes. Options are as follows: @@ -131,7 +131,7 @@ sharex, sharey, share : {0, False, 1, 'labels', 'labs', 2, 'limits', 'lims', 3, Explicit sharing levels (``0`` to ``4`` and aliases) still force sharing attempts and can emit warnings for incompatible axes. -spanx, spany, span : bool or {0, 1}, default: :rc:`subplots.span` +spanx, spany, span : bool or {0, 1}, default: [subplots.span](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.span) Whether to use "spanning" axis labels for the *x* axis, *y* axis, or both axes. Default is ``False`` if `sharex`, `sharey`, or `share` are ``0`` or ``False``. When ``True``, a single, centered axis label is used for all axes @@ -139,44 +139,44 @@ spanx, spany, span : bool or {0, 1}, default: :rc:`subplots.span` redundancy in your figure. "Spanning" labels integrate with "shared" axes. For example, for a 3-row, 3-column figure, with ``sharey > 1`` and ``spany == True``, your figure will have 1 y axis label instead of 9 y axis labels. -alignx, aligny, align : bool or {0, 1}, default: :rc:`subplots.align` - Whether to `"align" axis labels `__ +alignx, aligny, align : bool or {0, 1}, default: [subplots.align](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.align) + Whether to ["align" axis labels](https://matplotlib.org/stable/gallery/subplots_axes_and_figures/align_labels_demo.html) for the *x* axis, *y* axis, or both axes. Aligned labels always appear in the same row or column. This is ignored if `spanx`, `spany`, or `span` are ``True``. left, right, top, bottom : unit-spec, default: None The fixed space between the subplots and the figure edge. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). If ``None``, the space is determined automatically based on the tick and - label settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + label settings. If [subplots.tight](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.tight) is ``True`` or ``tight=True`` was passed to the figure, the space is determined by the tight layout algorithm. wspace, hspace, space : unit-spec, default: None The fixed space between grid columns, rows, or both. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). If ``None``, the space is determined automatically based on the font size and axis - sharing settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + sharing settings. If [subplots.tight](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.tight) is ``True`` or ``tight=True`` was passed to the figure, the space is determined by the tight layout algorithm. tight : bool, default: :rc`subplots.tight` Whether automatic calls to `~Figure.auto_layout` should include - :ref:`tight layout adjustments `. If you manually specified a spacing - in the call to `~ultraplot.ui.subplots`, it will be used to override the tight + [tight layout adjustments](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_tight). If you manually specified a spacing + in the call to [subplots](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ui.subplots.html), it will be used to override the tight layout spacing. For example, with ``left=1``, the left margin is set to 1 em-width, while the remaining margin widths are calculated automatically. -wequal, hequal, equal : bool, default: :rc:`subplots.equalspace` +wequal, hequal, equal : bool, default: [subplots.equalspace](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.equalspace) Whether to make the tight layout algorithm apply equal spacing between columns, rows, or both. -wgroup, hgroup, group : bool, default: :rc:`subplots.groupspace` +wgroup, hgroup, group : bool, default: [subplots.groupspace](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.groupspace) Whether to make the tight layout algorithm just consider spaces between adjacent subplots instead of entire columns and rows of subplots. -outerpad : unit-spec, default: :rc:`subplots.outerpad` +outerpad : unit-spec, default: [subplots.outerpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.outerpad) The scalar tight layout padding around the left, right, top, bottom figure edges. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -innerpad : unit-spec, default: :rc:`subplots.innerpad` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +innerpad : unit-spec, default: [subplots.innerpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.innerpad) The scalar tight layout padding between columns and rows. Synonymous with `pad`. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -panelpad : unit-spec, default: :rc:`subplots.panelpad` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +panelpad : unit-spec, default: [subplots.panelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.panelpad) The scalar tight layout padding between subplots and their panels, colorbars, and legends and between "stacks" of these objects. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). journal : str, optional String corresponding to an academic journal standard used to control the figure width `figwidth` and, if specified, the figure height `figheight`. See the below @@ -223,14 +223,14 @@ leftlabels, toplabels, rightlabels, bottomlabels : sequence of str, optional bottom edges of the figure. The length of each list must match the number of subplots along the corresponding edge. leftlabelpad, toplabelpad, rightlabelpad, bottomlabelpad : float or unit-spec, default -: :rc:`leftlabel.pad`, :rc:`toplabel.pad`, :rc:`rightlabel.pad`, :rc:`bottomlabel.pad` +: [leftlabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=leftlabel.pad), [toplabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=toplabel.pad), [rightlabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=rightlabel.pad), [bottomlabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=bottomlabel.pad) The padding between the labels and the axes content. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). leftlabelsharedpad, toplabelsharedpad, rightlabelsharedpad, bottomlabelsharedpad : float or unit-spec, default -: :rc:`leftlabel.sharedpad`, :rc:`toplabel.sharedpad`, :rc:`rightlabel.sharedpad`, :rc:`bottomlabel.sharedpad` +: [leftlabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=leftlabel.sharedpad), [toplabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=toplabel.sharedpad), [rightlabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=rightlabel.sharedpad), [bottomlabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=bottomlabel.sharedpad) The padding between side labels and a shared spanning axis label on the same side. The spanning label is placed outside the side labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). leftlabels_kw, toplabels_kw, rightlabels_kw, bottomlabels_kw : dict-like, optional Additional settings used to update the labels with ``text.update()``. figtitle @@ -238,9 +238,9 @@ figtitle suptitle : str, optional The figure "super" title, centered between the left edge of the leftmost subplot and the right edge of the rightmost subplot. -suptitlepad : float, default: :rc:`suptitle.pad` +suptitlepad : float, default: [suptitle.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=suptitle.pad) The padding between the super title and the axes content. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). suptitle_kw : optional Additional settings used to update the super title with ``text.update()``. includepanels : bool, default: False @@ -248,7 +248,7 @@ includepanels : bool, default: False of the subplot grid and when aligning the `spanx` *x* axis labels and `spany` *y* axis labels along the sides of the subplot grid. **kwargs - Passed to `matplotlib.figure.Figure`. + Passed to [matplotlib.figure.Figure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html). See also -------- @@ -321,7 +321,7 @@ returns False). Parameters ---------- -renderer : `~matplotlib.backend_bases.RendererBase` subclass. +renderer : [RendererBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.backend_bases.RendererBase.html) subclass. Notes ----- @@ -338,15 +338,15 @@ This method is overridden in the Artist subclasses.""" Parameters ---------- -*artists : `~matplotlib.artist.Artist` +*artists : [Artist](https://matplotlib.org/stable/api/_as_gen/matplotlib.artist.Artist.html) Artists that will change between updates. -bbox : `~matplotlib.transforms.Bbox` or object with a ``bbox`` attribute, optional +bbox : [Bbox](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Bbox.html) or object with a ``bbox`` attribute, optional Region to cache and blit. By default, the union of the artists' axes bounding boxes is used. Returns ------- -`~ultraplot._animation._BlitManager` +[_BlitManager](https://ultraplot.readthedocs.io/en/stable/api/ultraplot._animation._BlitManager.html) Manager that restores the cached static background and redraws only the supplied artists.""" ... @@ -666,15 +666,15 @@ Other parameters ---------------- **legend_kwargs Placement and legend styling keywords forwarded to - `~ultraplot.figure.Figure.legend` when ``add=True``. This includes figure legend + [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.legend) when ``add=True``. This includes figure legend placement keywords like ``loc=``, ``ref=``, ``ax=``, ``rows=``, ``cols=``, and ``span=``. Pass ``add=False`` to return ``(handles, labels)`` without drawing. Notes ----- Handle generation currently reuses the semantic legend builder used by -`~ultraplot.axes.Axes.entrylegend`, then routes the final draw step through -`~ultraplot.figure.Figure.legend`.""" +[entrylegend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.entrylegend), then routes the final draw step through +[legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.legend).""" ... def catlegend(self, categories: Incomplete, *, colors: Incomplete=None, markers: Incomplete=None, line: Incomplete=None, linestyle: Incomplete=None, linewidth: Incomplete=None, markersize: Incomplete=None, alpha: Incomplete=None, markeredgecolor: Incomplete=None, markeredgewidth: Incomplete=None, markerfacecolor: Incomplete=None, handle_kw: Incomplete=None, add: Incomplete=True, **legend_kwargs: Incomplete) -> Incomplete: @@ -689,15 +689,15 @@ Other parameters ---------------- **legend_kwargs Placement and legend styling keywords forwarded to - `~ultraplot.figure.Figure.legend` when ``add=True``. This includes figure legend + [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.legend) when ``add=True``. This includes figure legend placement keywords like ``loc=``, ``ref=``, ``ax=``, ``rows=``, ``cols=``, and ``span=``. Pass ``add=False`` to return ``(handles, labels)`` without drawing. Notes ----- Handle generation currently reuses the semantic legend builder used by -`~ultraplot.axes.Axes.catlegend`, then routes the final draw step through -`~ultraplot.figure.Figure.legend`.""" +[catlegend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.catlegend), then routes the final draw step through +[legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.legend).""" ... def sizelegend(self, levels: Incomplete, *, labels: Incomplete=None, color: Incomplete=None, marker: Incomplete=None, area: Incomplete=None, values: Incomplete=None, vmin: Incomplete=None, vmax: Incomplete=None, smin: Incomplete=None, smax: Incomplete=None, area_size: Incomplete=None, absolute_size: Incomplete=None, scale: Incomplete=None, minsize: Incomplete=None, fmt: Incomplete=None, alpha: Incomplete=None, markeredgecolor: Incomplete=None, markeredgewidth: Incomplete=None, markerfacecolor: Incomplete=None, handle_kw: Incomplete=None, add: Incomplete=True, **legend_kwargs: Incomplete) -> Incomplete: @@ -709,22 +709,22 @@ levels Numeric levels used to generate marker-size entries. values, vmin, vmax, smin, smax, area_size, absolute_size Optional scatter-style size scaling controls forwarded to - `~ultraplot.axes.Axes.sizelegend`. When omitted, a compatible UltraPlot + [sizelegend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.sizelegend). When omitted, a compatible UltraPlot scatter artist can be used to infer the size scale automatically. Other parameters ---------------- **legend_kwargs Placement and legend styling keywords forwarded to - `~ultraplot.figure.Figure.legend` when ``add=True``. This includes figure legend + [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.legend) when ``add=True``. This includes figure legend placement keywords like ``loc=``, ``ref=``, ``ax=``, ``rows=``, ``cols=``, and ``span=``. Pass ``add=False`` to return ``(handles, labels)`` without drawing. Notes ----- Handle generation currently reuses the semantic legend builder used by -`~ultraplot.axes.Axes.sizelegend`, then routes the final draw step through -`~ultraplot.figure.Figure.legend`. +[sizelegend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.sizelegend), then routes the final draw step through +[legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.legend). Pass ``labels=[...]`` or ``labels={level: label}`` to override the generated labels.""" ... @@ -741,15 +741,15 @@ Other parameters ---------------- **legend_kwargs Placement and legend styling keywords forwarded to - `~ultraplot.figure.Figure.legend` when ``add=True``. This includes figure legend + [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.legend) when ``add=True``. This includes figure legend placement keywords like ``loc=``, ``ref=``, ``ax=``, ``rows=``, ``cols=``, and ``span=``. Pass ``add=False`` to return ``(handles, labels)`` without drawing. Notes ----- Handle generation currently reuses the semantic legend builder used by -`~ultraplot.axes.Axes.numlegend`, then routes the final draw step through -`~ultraplot.figure.Figure.legend`.""" +[numlegend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.numlegend), then routes the final draw step through +[legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.legend).""" ... def geolegend(self, entries: Incomplete, labels: Incomplete=None, *, country_reso: Incomplete=None, country_territories: Incomplete=None, country_proj: Incomplete=None, handlesize: Incomplete=None, facecolor: Incomplete=None, edgecolor: Incomplete=None, linewidth: Incomplete=None, alpha: Incomplete=None, fill: Incomplete=None, add: Incomplete=True, **legend_kwargs: Incomplete) -> Incomplete: @@ -766,15 +766,15 @@ Other parameters ---------------- **legend_kwargs Placement and legend styling keywords forwarded to - `~ultraplot.figure.Figure.legend` when ``add=True``. This includes figure legend + [legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.legend) when ``add=True``. This includes figure legend placement keywords like ``loc=``, ``ref=``, ``ax=``, ``rows=``, ``cols=``, and ``span=``. Pass ``add=False`` to return ``(handles, labels)`` without drawing. Notes ----- Handle generation currently reuses the semantic legend builder used by -`~ultraplot.axes.Axes.geolegend`, then routes the final draw step through -`~ultraplot.figure.Figure.legend`.""" +[geolegend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.geolegend), then routes the final draw step through +[legend](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.legend).""" ... def add_axes(self, rect: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -786,20 +786,20 @@ rect : 4-tuple of float The (left, bottom, width, height) dimensions of the axes in figure-relative coordinates. proj, projection : -str, :class:`cartopy.crs.Projection`, or :class:`~mpl_toolkits.basemap.Basemap`, optional +str, `cartopy.crs.Projection`, or `Basemap`, optional The map projection specification(s). If ``'cart'`` or ``'cartesian'`` - (the default), a :class:`~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, - a :class:`~ultraplot.axes.PolarAxes` is created. Otherwise, the argument is - interpreted by :class:`~ultraplot.constructor.Proj`, and the result is used - to make a :class:`~ultraplot.axes.GeoAxes` (in this case the argument can be - a :class:`cartopy.crs.Projection` instance, a :class:`~mpl_toolkits.basemap.Basemap` - instance, or a projection name listed in :ref:`this table `). + (the default), a [CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html) is created. If ``'polar'``, + a [PolarAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PolarAxes.html) is created. Otherwise, the argument is + interpreted by [Proj](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Proj.html), and the result is used + to make a [GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.GeoAxes.html) (in this case the argument can be + a `cartopy.crs.Projection` instance, a `Basemap` + instance, or a projection name listed in [this table](https://ultraplot.readthedocs.io/en/stable/search.html?q=proj_table)). proj_kw, projection_kw : dict-like, optional - Keyword arguments passed to :class:`~mpl_toolkits.basemap.Basemap` or - :class:`~cartopy.crs.Projection` classes on instantiation. -backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` - Whether to use :class:`~mpl_toolkits.basemap.Basemap` or - :class:`~cartopy.crs.Projection` for map projections. + Keyword arguments passed to `Basemap` or + `Projection` classes on instantiation. +backend : {'cartopy', 'basemap'}, default: [geo.backend](https://ultraplot.readthedocs.io/en/stable/search.html?q=geo.backend) + Whether to use `Basemap` or + `Projection` for map projections. .. deprecated:: 3.0.0 The ``'basemap'`` backend is deprecated and may be removed in a @@ -808,8 +808,8 @@ backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` Other parameters ---------------- **kwargs - Passed to the ultraplot class `ultraplot.axes.CartesianAxes`, `ultraplot.axes.PolarAxes`, - `ultraplot.axes.GeoAxes`, or `ultraplot.axes.ThreeAxes`. This can include keyword + Passed to the ultraplot class [ultraplot.axes.CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html), [ultraplot.axes.PolarAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PolarAxes.html), + [ultraplot.axes.GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.GeoAxes.html), or [ultraplot.axes.ThreeAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.ThreeAxes.html). This can include keyword arguments for projection-specific ``format`` commands. See also @@ -838,7 +838,7 @@ rect : tuple (left, bottom, width, height) projection : {None, 'aitoff', 'hammer', 'lambert', 'mollweide', 'polar', 'rectilinear', str}, optional The projection type of the `~.axes.Axes`. *str* is the name of - a custom projection, see `~matplotlib.projections`. The default + a custom projection, see [projections](https://matplotlib.org/stable/api/_as_gen/matplotlib.projections.html). The default None results in a 'rectilinear' projection. polar : bool, default: False @@ -847,10 +847,10 @@ polar : bool, default: False axes_class : subclass type of `~.axes.Axes`, optional The `.axes.Axes` subclass that is instantiated. This parameter is incompatible with *projection* and *polar*. See - :ref:`axisartist_users-guide-index` for examples. + [axisartist_users-guide-index](https://ultraplot.readthedocs.io/en/stable/search.html?q=axisartist_users-guide-index) for examples. -sharex, sharey : `~matplotlib.axes.Axes`, optional - Share the x or y `~matplotlib.axis` with sharex and/or sharey. +sharex, sharey : [Axes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html), optional + Share the x or y [axis](https://matplotlib.org/stable/api/_as_gen/matplotlib.axis.html) with sharex and/or sharey. The axis will have the same limits, ticks, and scale as the axis of the shared Axes. @@ -887,11 +887,11 @@ Other Parameters axes_locator: Callable[[Axes, Renderer], Bbox] axisbelow: bool or 'line' box_aspect: float or None - clip_box: `~matplotlib.transforms.BboxBase` or None + clip_box: [BboxBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.BboxBase.html) or None clip_on: bool clip_path: Patch or (Path, Transform) or None - facecolor or fc: :mpltype:`color` - figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + facecolor or fc: [color](https://matplotlib.org/stable/search.html?q=color) + figure: [Figure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html) or [SubFigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.SubFigure.html) forward_navigation_events: bool or "auto" frame_on: bool gid: str @@ -902,7 +902,7 @@ Other Parameters navigate_mode: unknown path_effects: list of `.AbstractPathEffect` picker: None or bool or float or callable - position: [left, bottom, width, height] or `~matplotlib.transforms.Bbox` + position: [left, bottom, width, height] or [Bbox](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Bbox.html) prop_cycle: `~cycler.Cycler` rasterization_zorder: float or None rasterized: bool @@ -910,7 +910,7 @@ Other Parameters snap: bool or None subplotspec: unknown title: str - transform: `~matplotlib.transforms.Transform` + transform: [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html) url: str visible: bool xbound: (lower: float, upper: float) @@ -962,51 +962,51 @@ Some simple examples:: Parameters ---------- -*args : int, tuple, or `~matplotlib.gridspec.SubplotSpec`, optional +*args : int, tuple, or [SubplotSpec](https://matplotlib.org/stable/api/_as_gen/matplotlib.gridspec.SubplotSpec.html), optional The subplot location specifier. Your options are: * A single 3-digit integer argument specifying the number of rows, number of columns, and gridspec number (using row-major indexing). * Three positional arguments specifying the number of rows, number of columns, and gridspec number (int) or number range (2-tuple of int). - * A `~matplotlib.gridspec.SubplotSpec` instance generated by indexing - a ultraplot :class:`~ultraplot.gridspec.GridSpec`. + * A [SubplotSpec](https://matplotlib.org/stable/api/_as_gen/matplotlib.gridspec.SubplotSpec.html) instance generated by indexing + a ultraplot [GridSpec](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.gridspec.GridSpec.html). For integer input, the implied geometry must be compatible with the implied geometry from previous calls -- for example, ``fig.add_subplot(331)`` followed by ``fig.add_subplot(132)`` is valid because the 1 row of the second input can be tiled into the 3 rows of the the first input, but ``fig.add_subplot(232)`` will raise an error because 2 rows cannot be tiled into 3 rows. For - `~matplotlib.gridspec.SubplotSpec` input, the `~matplotlig.gridspec.SubplotSpec` - must be derived from the :class:`~ultraplot.gridspec.GridSpec` used in previous calls. + [SubplotSpec](https://matplotlib.org/stable/api/_as_gen/matplotlib.gridspec.SubplotSpec.html) input, the `~matplotlig.gridspec.SubplotSpec` + must be derived from the [GridSpec](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.gridspec.GridSpec.html) used in previous calls. These restrictions arise because we allocate a single, unique `~Figure.gridspec` for each figure. number : int, optional - The axes number used for a-b-c labeling. See `~ultraplot.axes.Axes.format` for + The axes number used for a-b-c labeling. See [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.format) for details. By default this is incremented automatically based on the other subplots in the figure. Use e.g. ``number=None`` or ``number=False`` to ensure the subplot has no a-b-c label. Note the number corresponding to `a` is ``1``, not ``0``. autoshare : bool, default: True Whether to automatically share the *x* and *y* axes with subplots spanning the same rows and columns based on the figure-wide `sharex` and `sharey` settings. - This has no effect if :rcraw:`subplots.share` is ``False`` or if ``sharex=False`` + This has no effect if [subplots.share](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.share) is ``False`` or if ``sharex=False`` or ``sharey=False`` were passed to the figure. proj, projection : -str, :class:`cartopy.crs.Projection`, or :class:`~mpl_toolkits.basemap.Basemap`, optional +str, `cartopy.crs.Projection`, or `Basemap`, optional The map projection specification(s). If ``'cart'`` or ``'cartesian'`` - (the default), a :class:`~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, - a :class:`~ultraplot.axes.PolarAxes` is created. Otherwise, the argument is - interpreted by :class:`~ultraplot.constructor.Proj`, and the result is used - to make a :class:`~ultraplot.axes.GeoAxes` (in this case the argument can be - a :class:`cartopy.crs.Projection` instance, a :class:`~mpl_toolkits.basemap.Basemap` - instance, or a projection name listed in :ref:`this table `). + (the default), a [CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html) is created. If ``'polar'``, + a [PolarAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PolarAxes.html) is created. Otherwise, the argument is + interpreted by [Proj](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Proj.html), and the result is used + to make a [GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.GeoAxes.html) (in this case the argument can be + a `cartopy.crs.Projection` instance, a `Basemap` + instance, or a projection name listed in [this table](https://ultraplot.readthedocs.io/en/stable/search.html?q=proj_table)). proj_kw, projection_kw : dict-like, optional - Keyword arguments passed to :class:`~mpl_toolkits.basemap.Basemap` or - :class:`~cartopy.crs.Projection` classes on instantiation. -backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` - Whether to use :class:`~mpl_toolkits.basemap.Basemap` or - :class:`~cartopy.crs.Projection` for map projections. + Keyword arguments passed to `Basemap` or + `Projection` classes on instantiation. +backend : {'cartopy', 'basemap'}, default: [geo.backend](https://ultraplot.readthedocs.io/en/stable/search.html?q=geo.backend) + Whether to use `Basemap` or + `Projection` for map projections. .. deprecated:: 3.0.0 The ``'basemap'`` backend is deprecated and may be removed in a @@ -1015,8 +1015,8 @@ backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` Other parameters ---------------- **kwargs - Passed to the ultraplot class `ultraplot.axes.CartesianAxes`, `ultraplot.axes.PolarAxes`, - `ultraplot.axes.GeoAxes`, or `ultraplot.axes.ThreeAxes`. This can include keyword + Passed to the ultraplot class [ultraplot.axes.CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html), [ultraplot.axes.PolarAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PolarAxes.html), + [ultraplot.axes.GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.GeoAxes.html), or [ultraplot.axes.ThreeAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.ThreeAxes.html). This can include keyword arguments for projection-specific ``format`` commands. See also @@ -1062,7 +1062,7 @@ Parameters projection : {None, 'aitoff', 'hammer', 'lambert', 'mollweide', 'polar', 'rectilinear', str}, optional The projection type of the subplot (`~.axes.Axes`). *str* is the - name of a custom projection, see `~matplotlib.projections`. The + name of a custom projection, see [projections](https://matplotlib.org/stable/api/_as_gen/matplotlib.projections.html). The default None results in a 'rectilinear' projection. polar : bool, default: False @@ -1071,10 +1071,10 @@ polar : bool, default: False axes_class : subclass type of `~.axes.Axes`, optional The `.axes.Axes` subclass that is instantiated. This parameter is incompatible with *projection* and *polar*. See - :ref:`axisartist_users-guide-index` for examples. + [axisartist_users-guide-index](https://ultraplot.readthedocs.io/en/stable/search.html?q=axisartist_users-guide-index) for examples. -sharex, sharey : `~matplotlib.axes.Axes`, optional - Share the x or y `~matplotlib.axis` with sharex and/or sharey. +sharex, sharey : [Axes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html), optional + Share the x or y [axis](https://matplotlib.org/stable/api/_as_gen/matplotlib.axis.html) with sharex and/or sharey. The axis will have the same limits, ticks, and scale as the axis of the shared Axes. @@ -1111,11 +1111,11 @@ Other Parameters axes_locator: Callable[[Axes, Renderer], Bbox] axisbelow: bool or 'line' box_aspect: float or None - clip_box: `~matplotlib.transforms.BboxBase` or None + clip_box: [BboxBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.BboxBase.html) or None clip_on: bool clip_path: Patch or (Path, Transform) or None - facecolor or fc: :mpltype:`color` - figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + facecolor or fc: [color](https://matplotlib.org/stable/search.html?q=color) + figure: [Figure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html) or [SubFigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.SubFigure.html) forward_navigation_events: bool or "auto" frame_on: bool gid: str @@ -1126,7 +1126,7 @@ Other Parameters navigate_mode: unknown path_effects: list of `.AbstractPathEffect` picker: None or bool or float or callable - position: [left, bottom, width, height] or `~matplotlib.transforms.Bbox` + position: [left, bottom, width, height] or [Bbox](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Bbox.html) prop_cycle: `~cycler.Cycler` rasterization_zorder: float or None rasterized: bool @@ -1134,7 +1134,7 @@ Other Parameters snap: bool or None subplotspec: unknown title: str - transform: `~matplotlib.transforms.Transform` + transform: [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html) url: str visible: bool xbound: (lower: float, upper: float) @@ -1184,51 +1184,51 @@ Examples Parameters ---------- -*args : int, tuple, or `~matplotlib.gridspec.SubplotSpec`, optional +*args : int, tuple, or [SubplotSpec](https://matplotlib.org/stable/api/_as_gen/matplotlib.gridspec.SubplotSpec.html), optional The subplot location specifier. Your options are: * A single 3-digit integer argument specifying the number of rows, number of columns, and gridspec number (using row-major indexing). * Three positional arguments specifying the number of rows, number of columns, and gridspec number (int) or number range (2-tuple of int). - * A `~matplotlib.gridspec.SubplotSpec` instance generated by indexing - a ultraplot :class:`~ultraplot.gridspec.GridSpec`. + * A [SubplotSpec](https://matplotlib.org/stable/api/_as_gen/matplotlib.gridspec.SubplotSpec.html) instance generated by indexing + a ultraplot [GridSpec](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.gridspec.GridSpec.html). For integer input, the implied geometry must be compatible with the implied geometry from previous calls -- for example, ``fig.add_subplot(331)`` followed by ``fig.add_subplot(132)`` is valid because the 1 row of the second input can be tiled into the 3 rows of the the first input, but ``fig.add_subplot(232)`` will raise an error because 2 rows cannot be tiled into 3 rows. For - `~matplotlib.gridspec.SubplotSpec` input, the `~matplotlig.gridspec.SubplotSpec` - must be derived from the :class:`~ultraplot.gridspec.GridSpec` used in previous calls. + [SubplotSpec](https://matplotlib.org/stable/api/_as_gen/matplotlib.gridspec.SubplotSpec.html) input, the `~matplotlig.gridspec.SubplotSpec` + must be derived from the [GridSpec](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.gridspec.GridSpec.html) used in previous calls. These restrictions arise because we allocate a single, unique `~Figure.gridspec` for each figure. number : int, optional - The axes number used for a-b-c labeling. See `~ultraplot.axes.Axes.format` for + The axes number used for a-b-c labeling. See [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.format) for details. By default this is incremented automatically based on the other subplots in the figure. Use e.g. ``number=None`` or ``number=False`` to ensure the subplot has no a-b-c label. Note the number corresponding to `a` is ``1``, not ``0``. autoshare : bool, default: True Whether to automatically share the *x* and *y* axes with subplots spanning the same rows and columns based on the figure-wide `sharex` and `sharey` settings. - This has no effect if :rcraw:`subplots.share` is ``False`` or if ``sharex=False`` + This has no effect if [subplots.share](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.share) is ``False`` or if ``sharex=False`` or ``sharey=False`` were passed to the figure. proj, projection : -str, :class:`cartopy.crs.Projection`, or :class:`~mpl_toolkits.basemap.Basemap`, optional +str, `cartopy.crs.Projection`, or `Basemap`, optional The map projection specification(s). If ``'cart'`` or ``'cartesian'`` - (the default), a :class:`~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, - a :class:`~ultraplot.axes.PolarAxes` is created. Otherwise, the argument is - interpreted by :class:`~ultraplot.constructor.Proj`, and the result is used - to make a :class:`~ultraplot.axes.GeoAxes` (in this case the argument can be - a :class:`cartopy.crs.Projection` instance, a :class:`~mpl_toolkits.basemap.Basemap` - instance, or a projection name listed in :ref:`this table `). + (the default), a [CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html) is created. If ``'polar'``, + a [PolarAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PolarAxes.html) is created. Otherwise, the argument is + interpreted by [Proj](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Proj.html), and the result is used + to make a [GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.GeoAxes.html) (in this case the argument can be + a `cartopy.crs.Projection` instance, a `Basemap` + instance, or a projection name listed in [this table](https://ultraplot.readthedocs.io/en/stable/search.html?q=proj_table)). proj_kw, projection_kw : dict-like, optional - Keyword arguments passed to :class:`~mpl_toolkits.basemap.Basemap` or - :class:`~cartopy.crs.Projection` classes on instantiation. -backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` - Whether to use :class:`~mpl_toolkits.basemap.Basemap` or - :class:`~cartopy.crs.Projection` for map projections. + Keyword arguments passed to `Basemap` or + `Projection` classes on instantiation. +backend : {'cartopy', 'basemap'}, default: [geo.backend](https://ultraplot.readthedocs.io/en/stable/search.html?q=geo.backend) + Whether to use `Basemap` or + `Projection` for map projections. .. deprecated:: 3.0.0 The ``'basemap'`` backend is deprecated and may be removed in a @@ -1237,8 +1237,8 @@ backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` Other parameters ---------------- **kwargs - Passed to the ultraplot class `ultraplot.axes.CartesianAxes`, `ultraplot.axes.PolarAxes`, - `ultraplot.axes.GeoAxes`, or `ultraplot.axes.ThreeAxes`. This can include keyword + Passed to the ultraplot class [ultraplot.axes.CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html), [ultraplot.axes.PolarAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PolarAxes.html), + [ultraplot.axes.GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.GeoAxes.html), or [ultraplot.axes.ThreeAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.ThreeAxes.html). This can include keyword arguments for projection-specific ``format`` commands. See also @@ -1253,9 +1253,9 @@ ultraplot.figure.Figure.add_subplots""" Parameters ---------- -array : `ultraplot.gridspec.GridSpec` or array-like of int, optional - The subplot grid specifier. If a :class:`~ultraplot.gridspec.GridSpec`, one subplot is - drawn for each unique :class:`~ultraplot.gridspec.GridSpec` slot. If a 2D array of integers, +array : [ultraplot.gridspec.GridSpec](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.gridspec.GridSpec.html) or array-like of int, optional + The subplot grid specifier. If a [GridSpec](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.gridspec.GridSpec.html), one subplot is + drawn for each unique [GridSpec](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.gridspec.GridSpec.html) slot. If a 2D array of integers, one subplot is drawn for each unique integer in the array. Think of this array as a "picture" of the subplot grid -- for example, the array ``[[1, 1], [2, 3]]`` creates one long subplot in the top row, two smaller subplots in the bottom row. @@ -1267,18 +1267,18 @@ nrows, ncols : int, default: 1 if `array` was passed. Use these arguments for simple subplot grids. order : {'C', 'F'}, default: 'C' Whether subplots are numbered in column-major (``'C'``) or row-major (``'F'``) - order. Analogous to `numpy.array` ordering. This controls the order that + order. Analogous to [numpy.array](https://numpy.org/doc/stable/reference/generated/numpy.array.html) ordering. This controls the order that subplots appear in the `SubplotGrid` returned by this function, and the order - of subplot a-b-c labels (see `~ultraplot.axes.Axes.format`). + of subplot a-b-c labels (see [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.format)). proj, projection : -str, :class:`cartopy.crs.Projection`, or :class:`~mpl_toolkits.basemap.Basemap`, optional +str, `cartopy.crs.Projection`, or `Basemap`, optional The map projection specification(s). If ``'cart'`` or ``'cartesian'`` - (the default), a :class:`~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, - a :class:`~ultraplot.axes.PolarAxes` is created. Otherwise, the argument is - interpreted by :class:`~ultraplot.constructor.Proj`, and the result is used - to make a :class:`~ultraplot.axes.GeoAxes` (in this case the argument can be - a :class:`cartopy.crs.Projection` instance, a :class:`~mpl_toolkits.basemap.Basemap` - instance, or a projection name listed in :ref:`this table `). + (the default), a [CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html) is created. If ``'polar'``, + a [PolarAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PolarAxes.html) is created. Otherwise, the argument is + interpreted by [Proj](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Proj.html), and the result is used + to make a [GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.GeoAxes.html) (in this case the argument can be + a `cartopy.crs.Projection` instance, a `Basemap` + instance, or a projection name listed in [this table](https://ultraplot.readthedocs.io/en/stable/search.html?q=proj_table)). To use different projections for different subplots, you have two options: @@ -1295,16 +1295,16 @@ str, :class:`cartopy.crs.Projection`, or :class:`~mpl_toolkits.basemap.Basemap`, for the third and fourth subplots. proj_kw, projection_kw : dict-like, optional - Keyword arguments passed to :class:`~mpl_toolkits.basemap.Basemap` or - :class:`~cartopy.crs.Projection` classes on instantiation. + Keyword arguments passed to `Basemap` or + `Projection` classes on instantiation. If dictionary of properties, applies globally. If list or dictionary of dictionaries, applies to specific subplots, as with `proj`. For example, ``uplt.subplots(ncols=2, proj='cyl', proj_kw=({'lon_0': 0}, {'lon_0': 180})`` centers the projection in the left subplot on the prime meridian and in the right subplot on the international dateline. -backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` - Whether to use :class:`~mpl_toolkits.basemap.Basemap` or - :class:`~cartopy.crs.Projection` for map projections. +backend : {'cartopy', 'basemap'}, default: [geo.backend](https://ultraplot.readthedocs.io/en/stable/search.html?q=geo.backend) + Whether to use `Basemap` or + `Projection` for map projections. .. deprecated:: 3.0.0 The ``'basemap'`` backend is deprecated and may be removed in a @@ -1313,53 +1313,53 @@ backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` subplots, as with `proj`. left, right, top, bottom : unit-spec, default: None The fixed space between the subplots and the figure edge. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). If ``None``, the space is determined automatically based on the tick and - label settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + label settings. If [subplots.tight](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.tight) is ``True`` or ``tight=True`` was passed to the figure, the space is determined by the tight layout algorithm. wspace, hspace, space : unit-spec or sequence, default: None The fixed space between grid columns, rows, and both, respectively. If float, string, or ``None``, this value is expanded into lists of length ``ncols - 1`` (for `wspace`) or length ``nrows - 1`` (for `hspace`). If a sequence, its length must match these lengths. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). For elements equal to ``None``, the space is determined automatically based - on the tick and label settings. If :rcraw:`subplots.tight` is ``True`` or + on the tick and label settings. If [subplots.tight](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.tight) is ``True`` or ``tight=True`` was passed to the figure, the space is determined by the tight layout algorithm. For example, ``subplots(ncols=3, tight=True, wspace=(2, None))`` fixes the space between columns 1 and 2 but lets the tight layout algorithm determine the space between columns 2 and 3. wratios, hratios : float or sequence, optional - Passed to :class:`~ultraplot.gridspec.GridSpec`, denotes the width and height + Passed to [GridSpec](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.gridspec.GridSpec.html), denotes the width and height ratios for the subplot grid. Length of `wratios` must match the number of columns, and length of `hratios` must match the number of rows. width_ratios, height_ratios Aliases for `wratios`, `hratios`. Included for - consistency with `matplotlib.gridspec.GridSpec`. + consistency with [matplotlib.gridspec.GridSpec](https://matplotlib.org/stable/api/_as_gen/matplotlib.gridspec.GridSpec.html). wpad, hpad, pad : unit-spec or sequence, optional The tight layout padding between columns, rows, and both, respectively. Unlike ``space``, these control the padding between subplot content (including text, ticks, etc.) rather than subplot edges. As with ``space``, these can be scalars or arrays optionally containing ``None``. For elements equal to ``None``, the default is `innerpad`. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -wequal, hequal, equal : bool, default: :rc:`subplots.equalspace` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +wequal, hequal, equal : bool, default: [subplots.equalspace](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.equalspace) Whether to make the tight layout algorithm apply equal spacing between columns, rows, or both. -wgroup, hgroup, group : bool, default: :rc:`subplots.groupspace` +wgroup, hgroup, group : bool, default: [subplots.groupspace](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.groupspace) Whether to make the tight layout algorithm just consider spaces between adjacent subplots instead of entire columns and rows of subplots. -outerpad : unit-spec, default: :rc:`subplots.outerpad` +outerpad : unit-spec, default: [subplots.outerpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.outerpad) The scalar tight layout padding around the left, right, top, bottom figure edges. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -innerpad : unit-spec, default: :rc:`subplots.innerpad` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +innerpad : unit-spec, default: [subplots.innerpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.innerpad) The scalar tight layout padding between columns and rows. Synonymous with `pad`. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -panelpad : unit-spec, default: :rc:`subplots.panelpad` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +panelpad : unit-spec, default: [subplots.panelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.panelpad) The scalar tight layout padding between subplots and their panels, colorbars, and legends and between "stacks" of these objects. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Other parameters ---------------- @@ -1373,11 +1373,11 @@ refaspect : float or 2-tuple of float, optional divided by height. If 2-tuple, this indicates the (width, height). Ignored if both `figwidth` *and* `figheight` or both `refwidth` *and* `refheight` were passed. The default value is ``1`` or the "data aspect ratio" if the latter - is explicitly fixed (as with `~ultraplot.axes.PlotAxes.imshow` plots and - `~ultraplot.axes.Axes.GeoAxes` projections; see :func:`~matplotlib.axes.Axes.set_aspect`). -refwidth, refheight : unit-spec, default: :rc:`subplots.refwidth` + is explicitly fixed (as with [imshow](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PlotAxes.html#ultraplot.axes.PlotAxes.imshow) plots and + [GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.GeoAxes) projections; see [set_aspect](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_aspect.html)). +refwidth, refheight : unit-spec, default: [subplots.refwidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.refwidth) The width, height of the reference subplot. - If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + If float, units are inches. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Ignored if `figwidth`, `figheight`, or `figsize` was passed. If you specify just one, `refaspect` will be respected. ref, aspect, axwidth, axheight @@ -1385,13 +1385,13 @@ ref, aspect, axwidth, axheight *These may be deprecated in a future release.* figwidth, figheight : unit-spec, optional The figure width and height. Default behavior is to use `refwidth`. - If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + If float, units are inches. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). If you specify just one, `refaspect` will be respected. width, height Aliases for `figwidth`, `figheight`. figsize : 2-tuple, optional Tuple specifying the figure ``(width, height)``. -sharex, sharey, share : {0, False, 1, 'labels', 'labs', 2, 'limits', 'lims', 3, True, 4, 'all', 'auto'}, default: :rc:`subplots.share` +sharex, sharey, share : {0, False, 1, 'labels', 'labs', 2, 'limits', 'lims', 3, True, 4, 'all', 'auto'}, default: [subplots.share](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.share) The axis sharing "level" for the *x* axis, *y* axis, or both axes. Options are as follows: @@ -1411,7 +1411,7 @@ sharex, sharey, share : {0, False, 1, 'labels', 'labs', 2, 'limits', 'lims', 3, Explicit sharing levels (``0`` to ``4`` and aliases) still force sharing attempts and can emit warnings for incompatible axes. -spanx, spany, span : bool or {0, 1}, default: :rc:`subplots.span` +spanx, spany, span : bool or {0, 1}, default: [subplots.span](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.span) Whether to use "spanning" axis labels for the *x* axis, *y* axis, or both axes. Default is ``False`` if `sharex`, `sharey`, or `share` are ``0`` or ``False``. When ``True``, a single, centered axis label is used for all axes @@ -1419,44 +1419,44 @@ spanx, spany, span : bool or {0, 1}, default: :rc:`subplots.span` redundancy in your figure. "Spanning" labels integrate with "shared" axes. For example, for a 3-row, 3-column figure, with ``sharey > 1`` and ``spany == True``, your figure will have 1 y axis label instead of 9 y axis labels. -alignx, aligny, align : bool or {0, 1}, default: :rc:`subplots.align` - Whether to `"align" axis labels `__ +alignx, aligny, align : bool or {0, 1}, default: [subplots.align](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.align) + Whether to ["align" axis labels](https://matplotlib.org/stable/gallery/subplots_axes_and_figures/align_labels_demo.html) for the *x* axis, *y* axis, or both axes. Aligned labels always appear in the same row or column. This is ignored if `spanx`, `spany`, or `span` are ``True``. left, right, top, bottom : unit-spec, default: None The fixed space between the subplots and the figure edge. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). If ``None``, the space is determined automatically based on the tick and - label settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + label settings. If [subplots.tight](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.tight) is ``True`` or ``tight=True`` was passed to the figure, the space is determined by the tight layout algorithm. wspace, hspace, space : unit-spec, default: None The fixed space between grid columns, rows, or both. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). If ``None``, the space is determined automatically based on the font size and axis - sharing settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + sharing settings. If [subplots.tight](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.tight) is ``True`` or ``tight=True`` was passed to the figure, the space is determined by the tight layout algorithm. tight : bool, default: :rc`subplots.tight` Whether automatic calls to `~Figure.auto_layout` should include - :ref:`tight layout adjustments `. If you manually specified a spacing - in the call to `~ultraplot.ui.subplots`, it will be used to override the tight + [tight layout adjustments](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_tight). If you manually specified a spacing + in the call to [subplots](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ui.subplots.html), it will be used to override the tight layout spacing. For example, with ``left=1``, the left margin is set to 1 em-width, while the remaining margin widths are calculated automatically. -wequal, hequal, equal : bool, default: :rc:`subplots.equalspace` +wequal, hequal, equal : bool, default: [subplots.equalspace](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.equalspace) Whether to make the tight layout algorithm apply equal spacing between columns, rows, or both. -wgroup, hgroup, group : bool, default: :rc:`subplots.groupspace` +wgroup, hgroup, group : bool, default: [subplots.groupspace](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.groupspace) Whether to make the tight layout algorithm just consider spaces between adjacent subplots instead of entire columns and rows of subplots. -outerpad : unit-spec, default: :rc:`subplots.outerpad` +outerpad : unit-spec, default: [subplots.outerpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.outerpad) The scalar tight layout padding around the left, right, top, bottom figure edges. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -innerpad : unit-spec, default: :rc:`subplots.innerpad` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +innerpad : unit-spec, default: [subplots.innerpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.innerpad) The scalar tight layout padding between columns and rows. Synonymous with `pad`. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -panelpad : unit-spec, default: :rc:`subplots.panelpad` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +panelpad : unit-spec, default: [subplots.panelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.panelpad) The scalar tight layout padding between subplots and their panels, colorbars, and legends and between "stacks" of these objects. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). journal : str, optional String corresponding to an academic journal standard used to control the figure width `figwidth` and, if specified, the figure height `figheight`. See the below @@ -1493,8 +1493,8 @@ journal : str, optional .. _nat: https://www.nature.com/nature/for-authors/formatting-guide .. _pnas: https://www.pnas.org/page/authors/format **kwargs - Passed to the ultraplot class `ultraplot.axes.CartesianAxes`, `ultraplot.axes.PolarAxes`, - `ultraplot.axes.GeoAxes`, or `ultraplot.axes.ThreeAxes`. This can include keyword + Passed to the ultraplot class [ultraplot.axes.CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html), [ultraplot.axes.PolarAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PolarAxes.html), + [ultraplot.axes.GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.GeoAxes.html), or [ultraplot.axes.ThreeAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.ThreeAxes.html). This can include keyword arguments for projection-specific ``format`` commands. Returns @@ -1517,9 +1517,9 @@ ultraplot.axes.Axes""" Parameters ---------- -array : `ultraplot.gridspec.GridSpec` or array-like of int, optional - The subplot grid specifier. If a :class:`~ultraplot.gridspec.GridSpec`, one subplot is - drawn for each unique :class:`~ultraplot.gridspec.GridSpec` slot. If a 2D array of integers, +array : [ultraplot.gridspec.GridSpec](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.gridspec.GridSpec.html) or array-like of int, optional + The subplot grid specifier. If a [GridSpec](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.gridspec.GridSpec.html), one subplot is + drawn for each unique [GridSpec](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.gridspec.GridSpec.html) slot. If a 2D array of integers, one subplot is drawn for each unique integer in the array. Think of this array as a "picture" of the subplot grid -- for example, the array ``[[1, 1], [2, 3]]`` creates one long subplot in the top row, two smaller subplots in the bottom row. @@ -1531,18 +1531,18 @@ nrows, ncols : int, default: 1 if `array` was passed. Use these arguments for simple subplot grids. order : {'C', 'F'}, default: 'C' Whether subplots are numbered in column-major (``'C'``) or row-major (``'F'``) - order. Analogous to `numpy.array` ordering. This controls the order that + order. Analogous to [numpy.array](https://numpy.org/doc/stable/reference/generated/numpy.array.html) ordering. This controls the order that subplots appear in the `SubplotGrid` returned by this function, and the order - of subplot a-b-c labels (see `~ultraplot.axes.Axes.format`). + of subplot a-b-c labels (see [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.format)). proj, projection : -str, :class:`cartopy.crs.Projection`, or :class:`~mpl_toolkits.basemap.Basemap`, optional +str, `cartopy.crs.Projection`, or `Basemap`, optional The map projection specification(s). If ``'cart'`` or ``'cartesian'`` - (the default), a :class:`~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, - a :class:`~ultraplot.axes.PolarAxes` is created. Otherwise, the argument is - interpreted by :class:`~ultraplot.constructor.Proj`, and the result is used - to make a :class:`~ultraplot.axes.GeoAxes` (in this case the argument can be - a :class:`cartopy.crs.Projection` instance, a :class:`~mpl_toolkits.basemap.Basemap` - instance, or a projection name listed in :ref:`this table `). + (the default), a [CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html) is created. If ``'polar'``, + a [PolarAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PolarAxes.html) is created. Otherwise, the argument is + interpreted by [Proj](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Proj.html), and the result is used + to make a [GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.GeoAxes.html) (in this case the argument can be + a `cartopy.crs.Projection` instance, a `Basemap` + instance, or a projection name listed in [this table](https://ultraplot.readthedocs.io/en/stable/search.html?q=proj_table)). To use different projections for different subplots, you have two options: @@ -1559,16 +1559,16 @@ str, :class:`cartopy.crs.Projection`, or :class:`~mpl_toolkits.basemap.Basemap`, for the third and fourth subplots. proj_kw, projection_kw : dict-like, optional - Keyword arguments passed to :class:`~mpl_toolkits.basemap.Basemap` or - :class:`~cartopy.crs.Projection` classes on instantiation. + Keyword arguments passed to `Basemap` or + `Projection` classes on instantiation. If dictionary of properties, applies globally. If list or dictionary of dictionaries, applies to specific subplots, as with `proj`. For example, ``uplt.subplots(ncols=2, proj='cyl', proj_kw=({'lon_0': 0}, {'lon_0': 180})`` centers the projection in the left subplot on the prime meridian and in the right subplot on the international dateline. -backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` - Whether to use :class:`~mpl_toolkits.basemap.Basemap` or - :class:`~cartopy.crs.Projection` for map projections. +backend : {'cartopy', 'basemap'}, default: [geo.backend](https://ultraplot.readthedocs.io/en/stable/search.html?q=geo.backend) + Whether to use `Basemap` or + `Projection` for map projections. .. deprecated:: 3.0.0 The ``'basemap'`` backend is deprecated and may be removed in a @@ -1577,53 +1577,53 @@ backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` subplots, as with `proj`. left, right, top, bottom : unit-spec, default: None The fixed space between the subplots and the figure edge. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). If ``None``, the space is determined automatically based on the tick and - label settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + label settings. If [subplots.tight](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.tight) is ``True`` or ``tight=True`` was passed to the figure, the space is determined by the tight layout algorithm. wspace, hspace, space : unit-spec or sequence, default: None The fixed space between grid columns, rows, and both, respectively. If float, string, or ``None``, this value is expanded into lists of length ``ncols - 1`` (for `wspace`) or length ``nrows - 1`` (for `hspace`). If a sequence, its length must match these lengths. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). For elements equal to ``None``, the space is determined automatically based - on the tick and label settings. If :rcraw:`subplots.tight` is ``True`` or + on the tick and label settings. If [subplots.tight](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.tight) is ``True`` or ``tight=True`` was passed to the figure, the space is determined by the tight layout algorithm. For example, ``subplots(ncols=3, tight=True, wspace=(2, None))`` fixes the space between columns 1 and 2 but lets the tight layout algorithm determine the space between columns 2 and 3. wratios, hratios : float or sequence, optional - Passed to :class:`~ultraplot.gridspec.GridSpec`, denotes the width and height + Passed to [GridSpec](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.gridspec.GridSpec.html), denotes the width and height ratios for the subplot grid. Length of `wratios` must match the number of columns, and length of `hratios` must match the number of rows. width_ratios, height_ratios Aliases for `wratios`, `hratios`. Included for - consistency with `matplotlib.gridspec.GridSpec`. + consistency with [matplotlib.gridspec.GridSpec](https://matplotlib.org/stable/api/_as_gen/matplotlib.gridspec.GridSpec.html). wpad, hpad, pad : unit-spec or sequence, optional The tight layout padding between columns, rows, and both, respectively. Unlike ``space``, these control the padding between subplot content (including text, ticks, etc.) rather than subplot edges. As with ``space``, these can be scalars or arrays optionally containing ``None``. For elements equal to ``None``, the default is `innerpad`. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -wequal, hequal, equal : bool, default: :rc:`subplots.equalspace` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +wequal, hequal, equal : bool, default: [subplots.equalspace](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.equalspace) Whether to make the tight layout algorithm apply equal spacing between columns, rows, or both. -wgroup, hgroup, group : bool, default: :rc:`subplots.groupspace` +wgroup, hgroup, group : bool, default: [subplots.groupspace](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.groupspace) Whether to make the tight layout algorithm just consider spaces between adjacent subplots instead of entire columns and rows of subplots. -outerpad : unit-spec, default: :rc:`subplots.outerpad` +outerpad : unit-spec, default: [subplots.outerpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.outerpad) The scalar tight layout padding around the left, right, top, bottom figure edges. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -innerpad : unit-spec, default: :rc:`subplots.innerpad` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +innerpad : unit-spec, default: [subplots.innerpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.innerpad) The scalar tight layout padding between columns and rows. Synonymous with `pad`. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -panelpad : unit-spec, default: :rc:`subplots.panelpad` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +panelpad : unit-spec, default: [subplots.panelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.panelpad) The scalar tight layout padding between subplots and their panels, colorbars, and legends and between "stacks" of these objects. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Other parameters ---------------- @@ -1637,11 +1637,11 @@ refaspect : float or 2-tuple of float, optional divided by height. If 2-tuple, this indicates the (width, height). Ignored if both `figwidth` *and* `figheight` or both `refwidth` *and* `refheight` were passed. The default value is ``1`` or the "data aspect ratio" if the latter - is explicitly fixed (as with `~ultraplot.axes.PlotAxes.imshow` plots and - `~ultraplot.axes.Axes.GeoAxes` projections; see :func:`~matplotlib.axes.Axes.set_aspect`). -refwidth, refheight : unit-spec, default: :rc:`subplots.refwidth` + is explicitly fixed (as with [imshow](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PlotAxes.html#ultraplot.axes.PlotAxes.imshow) plots and + [GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.GeoAxes) projections; see [set_aspect](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_aspect.html)). +refwidth, refheight : unit-spec, default: [subplots.refwidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.refwidth) The width, height of the reference subplot. - If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + If float, units are inches. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Ignored if `figwidth`, `figheight`, or `figsize` was passed. If you specify just one, `refaspect` will be respected. ref, aspect, axwidth, axheight @@ -1649,13 +1649,13 @@ ref, aspect, axwidth, axheight *These may be deprecated in a future release.* figwidth, figheight : unit-spec, optional The figure width and height. Default behavior is to use `refwidth`. - If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + If float, units are inches. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). If you specify just one, `refaspect` will be respected. width, height Aliases for `figwidth`, `figheight`. figsize : 2-tuple, optional Tuple specifying the figure ``(width, height)``. -sharex, sharey, share : {0, False, 1, 'labels', 'labs', 2, 'limits', 'lims', 3, True, 4, 'all', 'auto'}, default: :rc:`subplots.share` +sharex, sharey, share : {0, False, 1, 'labels', 'labs', 2, 'limits', 'lims', 3, True, 4, 'all', 'auto'}, default: [subplots.share](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.share) The axis sharing "level" for the *x* axis, *y* axis, or both axes. Options are as follows: @@ -1675,7 +1675,7 @@ sharex, sharey, share : {0, False, 1, 'labels', 'labs', 2, 'limits', 'lims', 3, Explicit sharing levels (``0`` to ``4`` and aliases) still force sharing attempts and can emit warnings for incompatible axes. -spanx, spany, span : bool or {0, 1}, default: :rc:`subplots.span` +spanx, spany, span : bool or {0, 1}, default: [subplots.span](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.span) Whether to use "spanning" axis labels for the *x* axis, *y* axis, or both axes. Default is ``False`` if `sharex`, `sharey`, or `share` are ``0`` or ``False``. When ``True``, a single, centered axis label is used for all axes @@ -1683,44 +1683,44 @@ spanx, spany, span : bool or {0, 1}, default: :rc:`subplots.span` redundancy in your figure. "Spanning" labels integrate with "shared" axes. For example, for a 3-row, 3-column figure, with ``sharey > 1`` and ``spany == True``, your figure will have 1 y axis label instead of 9 y axis labels. -alignx, aligny, align : bool or {0, 1}, default: :rc:`subplots.align` - Whether to `"align" axis labels `__ +alignx, aligny, align : bool or {0, 1}, default: [subplots.align](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.align) + Whether to ["align" axis labels](https://matplotlib.org/stable/gallery/subplots_axes_and_figures/align_labels_demo.html) for the *x* axis, *y* axis, or both axes. Aligned labels always appear in the same row or column. This is ignored if `spanx`, `spany`, or `span` are ``True``. left, right, top, bottom : unit-spec, default: None The fixed space between the subplots and the figure edge. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). If ``None``, the space is determined automatically based on the tick and - label settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + label settings. If [subplots.tight](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.tight) is ``True`` or ``tight=True`` was passed to the figure, the space is determined by the tight layout algorithm. wspace, hspace, space : unit-spec, default: None The fixed space between grid columns, rows, or both. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). If ``None``, the space is determined automatically based on the font size and axis - sharing settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + sharing settings. If [subplots.tight](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.tight) is ``True`` or ``tight=True`` was passed to the figure, the space is determined by the tight layout algorithm. tight : bool, default: :rc`subplots.tight` Whether automatic calls to `~Figure.auto_layout` should include - :ref:`tight layout adjustments `. If you manually specified a spacing - in the call to `~ultraplot.ui.subplots`, it will be used to override the tight + [tight layout adjustments](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_tight). If you manually specified a spacing + in the call to [subplots](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ui.subplots.html), it will be used to override the tight layout spacing. For example, with ``left=1``, the left margin is set to 1 em-width, while the remaining margin widths are calculated automatically. -wequal, hequal, equal : bool, default: :rc:`subplots.equalspace` +wequal, hequal, equal : bool, default: [subplots.equalspace](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.equalspace) Whether to make the tight layout algorithm apply equal spacing between columns, rows, or both. -wgroup, hgroup, group : bool, default: :rc:`subplots.groupspace` +wgroup, hgroup, group : bool, default: [subplots.groupspace](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.groupspace) Whether to make the tight layout algorithm just consider spaces between adjacent subplots instead of entire columns and rows of subplots. -outerpad : unit-spec, default: :rc:`subplots.outerpad` +outerpad : unit-spec, default: [subplots.outerpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.outerpad) The scalar tight layout padding around the left, right, top, bottom figure edges. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -innerpad : unit-spec, default: :rc:`subplots.innerpad` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +innerpad : unit-spec, default: [subplots.innerpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.innerpad) The scalar tight layout padding between columns and rows. Synonymous with `pad`. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -panelpad : unit-spec, default: :rc:`subplots.panelpad` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +panelpad : unit-spec, default: [subplots.panelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.panelpad) The scalar tight layout padding between subplots and their panels, colorbars, and legends and between "stacks" of these objects. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). journal : str, optional String corresponding to an academic journal standard used to control the figure width `figwidth` and, if specified, the figure height `figheight`. See the below @@ -1757,8 +1757,8 @@ journal : str, optional .. _nat: https://www.nature.com/nature/for-authors/formatting-guide .. _pnas: https://www.pnas.org/page/authors/format **kwargs - Passed to the ultraplot class `ultraplot.axes.CartesianAxes`, `ultraplot.axes.PolarAxes`, - `ultraplot.axes.GeoAxes`, or `ultraplot.axes.ThreeAxes`. This can include keyword + Passed to the ultraplot class [ultraplot.axes.CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html), [ultraplot.axes.PolarAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PolarAxes.html), + [ultraplot.axes.GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.GeoAxes.html), or [ultraplot.axes.ThreeAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.ThreeAxes.html). This can include keyword arguments for projection-specific ``format`` commands. Returns @@ -1782,7 +1782,7 @@ triggered automatically whenever the figure is drawn. Parameters ---------- -renderer : `~matplotlib.backend_bases.RendererBase`, optional +renderer : [RendererBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.backend_bases.RendererBase.html), optional The renderer. If ``None`` a default renderer will be produced. aspect : bool, optional Whether to update the figure size based on the reference subplot aspect @@ -1791,7 +1791,7 @@ aspect : bool, optional tight : bool, optional Whether to update the figuer size and subplot positions according to a "tight layout". By default, this takes on the value of `tight` passed - to `Figure`. If nothing was passed, it is :rc:`subplots.tight`. + to `Figure`. If nothing was passed, it is [subplots.tight](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.tight). resize : bool, optional If ``False``, the current figure dimensions are fixed and automatic figure resizing is disabled. By default, the figure size may change @@ -1806,7 +1806,7 @@ input axes. By default the numbered subplots are used. Parameters ---------- -axs : sequence of `~ultraplot.axes.Axes`, optional +axs : sequence of [Axes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html), optional The axes to format. Default is the numbered subplots. rowlabels, collabels, llabels, tlabels, rlabels, blabels Aliases for `leftlabels` and `toplabels`, and for `leftlabels`, @@ -1816,14 +1816,14 @@ leftlabels, toplabels, rightlabels, bottomlabels : sequence of str, optional bottom edges of the figure. The length of each list must match the number of subplots along the corresponding edge. leftlabelpad, toplabelpad, rightlabelpad, bottomlabelpad : float or unit-spec, default -: :rc:`leftlabel.pad`, :rc:`toplabel.pad`, :rc:`rightlabel.pad`, :rc:`bottomlabel.pad` +: [leftlabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=leftlabel.pad), [toplabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=toplabel.pad), [rightlabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=rightlabel.pad), [bottomlabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=bottomlabel.pad) The padding between the labels and the axes content. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). leftlabelsharedpad, toplabelsharedpad, rightlabelsharedpad, bottomlabelsharedpad : float or unit-spec, default -: :rc:`leftlabel.sharedpad`, :rc:`toplabel.sharedpad`, :rc:`rightlabel.sharedpad`, :rc:`bottomlabel.sharedpad` +: [leftlabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=leftlabel.sharedpad), [toplabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=toplabel.sharedpad), [rightlabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=rightlabel.sharedpad), [bottomlabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=bottomlabel.sharedpad) The padding between side labels and a shared spanning axis label on the same side. The spanning label is placed outside the side labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). leftlabels_kw, toplabels_kw, rightlabels_kw, bottomlabels_kw : dict-like, optional Additional settings used to update the labels with ``text.update()``. figtitle @@ -1831,9 +1831,9 @@ figtitle suptitle : str, optional The figure "super" title, centered between the left edge of the leftmost subplot and the right edge of the rightmost subplot. -suptitlepad : float, default: :rc:`suptitle.pad` +suptitlepad : float, default: [suptitle.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=suptitle.pad) The padding between the super title and the axes content. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). suptitle_kw : optional Additional settings used to update the super title with ``text.update()``. includepanels : bool, default: False @@ -1846,24 +1846,24 @@ Important `leftlabelpad`, `leftlabelsharedpad`, `toplabelpad`, `toplabelsharedpad`, `rightlabelpad`, `rightlabelsharedpad`, `bottomlabelpad`, and `bottomlabelsharedpad` keywords are actually -:ref:`configuration settings `. +[configuration settings](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_config). We explicitly document these arguments here because it is common to -change them for specific figures. But many :ref:`other configuration -settings ` can be passed to ``format`` too. +change them for specific figures. But many [other configuration +settings ](https://ultraplot.readthedocs.io/en/stable/search.html?q=other+configuration%0Asettings+%3Cug_format%3E) can be passed to ``format`` too. Other parameters ---------------- title : str or sequence, optional The axes title. Can optionally be a sequence strings, in which case the title will be selected from the sequence according to `~Axes.number`. -abc : bool or str or sequence, default: :rc:`abc` +abc : bool or str or sequence, default: [abc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc) The "a-b-c" subplot label style. Must contain the character `a` or `A`, for example ``'a.'``, or ``'A'``. If ``True`` then the default style of ``'a'`` is used. The `a` or ``A`` is replaced with the alphabetic character matching the `~Axes.number`. If `~Axes.number` is greater than 26, the characters loop around to a, ..., z, aa, ..., zz, aaa, ..., zzz, etc. Can also be a sequence of strings, in which case the "a-b-c" label will be selected sequentially from the list. For example `axs.format(abc = ["X", "Y"])` for a two-panel figure, and `axes[3:5].format(abc = ["X", "Y"])` for a two-panel subset of a larger figure. -abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` +abcloc, titleloc : str, default: [abc.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.loc), [title.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.loc) Strings indicating the location for the a-b-c label and main title. The following locations are valid: @@ -1885,31 +1885,31 @@ abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` right of y axis ``'outer right'``, ``'or'`` ======================== ============================ -abcborder, titleborder : bool, default: :rc:`abc.border` and :rc:`title.border` +abcborder, titleborder : bool, default: [abc.border](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.border) and [title.border](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.border) Whether to draw a white border around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes. -abcbbox, titlebbox : bool, default: :rc:`abc.bbox` and :rc:`title.bbox` +abcbbox, titlebbox : bool, default: [abc.bbox](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.bbox) and [title.bbox](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.bbox) Whether to draw a white bbox around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes. -abcpad : float or unit-spec, default: :rc:`abc.pad` +abcpad : float or unit-spec, default: [abc.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.pad) Horizontal offset to shift the a-b-c label position. Positive values move the label right, negative values move it left. This is separate from `abctitlepad`, which controls spacing between abc and title when co-located. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). abc_kw, title_kw : dict-like, optional Additional settings used to update the a-b-c label and title with ``text.update()``. -titlepad : float, default: :rc:`title.pad` +titlepad : float, default: [title.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.pad) The padding for the inner and outer titles and a-b-c labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -titleabove : bool, default: :rc:`title.above` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +titleabove : bool, default: [title.above](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.above) Whether to try to put outer titles and a-b-c labels above panels, colorbars, or legends that are above the axes. -abctitlepad : float, default: :rc:`abc.titlepad` +abctitlepad : float, default: [abc.titlepad](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.titlepad) The horizontal padding between a-b-c labels and titles in the same location. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle : str or sequence, optional Shorthands for the below keywords. lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle : str or sequence, optional @@ -1918,22 +1918,22 @@ lowerlefttitle, lowercentertitle, lowerrighttitle : str or sequence, optional an alternative to the ``ax.format(title='Title', titleloc=loc)`` workflow and permits adding more than one title-like label for a single axes. a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle : default: - :rc:`axes.alpha` (default: 1.0), :rc:`axes.facecolor` (default: white), :rc:`axes.edgecolor` (default: black), :rc:`axes.linewidth` (default: 0.6), - + [axes.alpha](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.alpha) (default: 1.0), [axes.facecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.facecolor) (default: white), [axes.edgecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.edgecolor) (default: black), [axes.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.linewidth) (default: 0.6), - Additional settings applied to the background patch, and their shorthands. Their defaults values are the ``'axes'`` properties. aspect : {'auto', 'equal'} or float, optional - The data aspect ratio. See :func:`~matplotlib.axes.Axes.set_aspect` + The data aspect ratio. See [set_aspect](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_aspect.html) for details. xlabel, ylabel : str, optional - The x and y axis labels. Applied with `~matplotlib.axes.Axes.set_xlabel` - and `~matplotlib.axes.Axes.set_ylabel`. + The x and y axis labels. Applied with [set_xlabel](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlabel.html) + and [set_ylabel](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylabel.html). xlabel_kw, ylabel_kw : dict-like, optional - Additional axis label settings applied with `~matplotlib.axes.Axes.set_xlabel` - and `~matplotlib.axes.Axes.set_ylabel`. See also `labelpad`, `labelcolor`, + Additional axis label settings applied with [set_xlabel](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlabel.html) + and [set_ylabel](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylabel.html). See also `labelpad`, `labelcolor`, `labelsize`, and `labelweight` below. xlim, ylim : 2-tuple of floats or None, optional - The x and y axis data limits. Applied with :func:`~matplotlib.axes.Axes.set_xlim` - and :func:`~matplotlib.axes.Axes.set_ylim`. + The x and y axis data limits. Applied with [set_xlim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlim.html) + and [set_ylim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylim.html). xmin, ymin : float, optional The x and y minimum data limits. Useful if you do not want to set the maximum limits. @@ -1944,12 +1944,12 @@ xreverse, yreverse : bool, optional Whether to "reverse" the x and y axis direction. Makes the x and y axes ascend left-to-right and top-to-bottom, respectively. xscale, yscale : scale-spec, optional - The x and y axis scales. Passed to the `~ultraplot.scale.Scale` constructor. + The x and y axis scales. Passed to the [Scale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.Scale.html) constructor. For example, ``xscale='log'`` applies logarithmic scaling, and - ``xscale=('cutoff', 100, 2)`` applies a `~ultraplot.scale.CutoffScale`. + ``xscale=('cutoff', 100, 2)`` applies a [CutoffScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.CutoffScale.html). xscale_kw, yscale_kw : dict-like, optional - The x and y axis scale settings. Passed to `~ultraplot.scale.Scale`. -xmargin, ymargin, margin : float, default: :rc:`margin` + The x and y axis scale settings. Passed to [Scale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.Scale.html). +xmargin, ymargin, margin : float, default: [margin](https://ultraplot.readthedocs.io/en/stable/search.html?q=margin) The default margin between plotted content and the x and y axis spines in axes-relative coordinates. This is useful if you don't witch to explicitly set axis limits. Use the keyword `margin` to set both at once. @@ -1962,16 +1962,16 @@ xtickrange, ytickrange : 2-tuple of float, optional The x and y axis data ranges within which major tick marks are labelled. For example, ``xlim=(-5, 5)`` combined with ``xtickrange=(-1, 1)`` and a tick interval of 1 will only label the ticks marks at -1, 0, and 1. See - `~ultraplot.ticker.AutoFormatter` for details. + [AutoFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.AutoFormatter.html) for details. xwraprange, ywraprange : 2-tuple of float, optional The x and y axis data ranges with which major tick mark values are wrapped. For example, ``xwraprange=(0, 3)`` causes the values 0 through 9 to be formatted as - 0, 1, 2, 0, 1, 2, 0, 1, 2, 0. See `~ultraplot.ticker.AutoFormatter` for details. This + 0, 1, 2, 0, 1, 2, 0, 1, 2, 0. See [AutoFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.AutoFormatter.html) for details. This can be combined with `xtickrange` and `ytickrange` to make "stacked" line plots. xloc, yloc : optional Shorthands for `xspineloc`, `yspineloc`. xspineloc, yspineloc : {'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right', 'both', 'neither', 'none', 'zero', 'center'} or 2-tuple, optional - The x and y spine locations. Applied with `~matplotlib.spines.Spine.set_position`. + The x and y spine locations. Applied with [set_position](https://matplotlib.org/stable/api/_as_gen/matplotlib.spines.Spine.set_position.html). Propagates to `tickloc` unless specified otherwise. xtickloc, ytickloc : {'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right', 'both', 'neither', 'none'}, optional Which x and y axis spines should have major and minor tick marks. Inherits from @@ -1993,25 +1993,25 @@ xticklabeldir, yticklabeldir : {'in', 'out'}, optional Propagates to `xtickdir` and `ytickdir` unless specified otherwise. xrotation, yrotation : float, default: 0 The rotation for x and y axis tick labels. - for normal axes, :rc:`formatter.timerotation` for time x axes. -xgrid, ygrid, grid : bool, default: :rc:`grid` + for normal axes, [formatter.timerotation](https://ultraplot.readthedocs.io/en/stable/search.html?q=formatter.timerotation) for time x axes. +xgrid, ygrid, grid : bool, default: [grid](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid) Whether to draw major gridlines on the x and y axis. Use the keyword `grid` to toggle both. -xgridminor, ygridminor, gridminor : bool, default: :rc:`gridminor` +xgridminor, ygridminor, gridminor : bool, default: [gridminor](https://ultraplot.readthedocs.io/en/stable/search.html?q=gridminor) Whether to draw minor gridlines for the x and y axis. Use the keyword `gridminor` to toggle both. -xtickminor, ytickminor, tickminor : bool, default: :rc:`tick.minor` +xtickminor, ytickminor, tickminor : bool, default: [tick.minor](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.minor) Whether to draw minor ticks on the x and y axes. Use the keyword `tickminor` to toggle both. xticks, yticks : optional Aliases for `xlocator`, `ylocator`. xlocator, ylocator : locator-spec, optional Used to determine the x and y axis tick mark positions. Passed - to the `~ultraplot.constructor.Locator` constructor. Can be float, - list of float, string, or `matplotlib.ticker.Locator` instance. + to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. Can be float, + list of float, string, or [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) instance. Use ``[]``, ``'null'``, or ``'none'`` for no ticks. xlocator_kw, ylocator_kw : dict-like, optional - Keyword arguments passed to the `matplotlib.ticker.Locator` class. + Keyword arguments passed to the [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. xminorticks, yminorticks : optional Aliases for `xminorlocator`, `yminorlocator`. xminorlocator, yminorlocator : optional @@ -2022,66 +2022,66 @@ xticklabels, yticklabels : optional Aliases for `xformatter`, `yformatter`. xformatter, yformatter : formatter-spec, optional Used to determine the x and y axis tick label string format. - Passed to the `~ultraplot.constructor.Formatter` constructor. - Can be string, list of strings, or `matplotlib.ticker.Formatter` instance. + Passed to the [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html) constructor. + Can be string, list of strings, or [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) instance. Use ``[]``, ``'null'``, or ``'none'`` for no labels. xformatter_kw, yformatter_kw : dict-like, optional - Keyword arguments passed to the `matplotlib.ticker.Formatter` class. -xcolor, ycolor, color : color-spec, default: :rc:`meta.color` + Keyword arguments passed to the [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) class. +xcolor, ycolor, color : color-spec, default: [meta.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=meta.color) Color for the x and y axis spines, ticks, tick labels, and axis labels. Use the keyword `color` to set both at once. -xgridcolor, ygridcolor, gridcolor : color-spec, default: :rc:`grid.color` +xgridcolor, ygridcolor, gridcolor : color-spec, default: [grid.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.color) Color for the x and y axis major and minor gridlines. Use the keyword `gridcolor` to set both at once. -xlinewidth, ylinewidth, linewidth : color-spec, default: :rc:`meta.width` +xlinewidth, ylinewidth, linewidth : color-spec, default: [meta.width](https://ultraplot.readthedocs.io/en/stable/search.html?q=meta.width) Line width for the x and y axis spines and major ticks. Propagates to `tickwidth` unless specified otherwise. Use the keyword `linewidth` to set both at once. -xtickcolor, ytickcolor, tickcolor : color-spec, default: :rc:`tick.color` +xtickcolor, ytickcolor, tickcolor : color-spec, default: [tick.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.color) Color for the x and y axis ticks. Defaults are `xcolor`, `ycolor`, and `color` if they were passed. Use the keyword `tickcolor` to set both at once. -xticklen, yticklen, ticklen : unit-spec, default: :rc:`tick.len` +xticklen, yticklen, ticklen : unit-spec, default: [tick.len](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.len) Major tick lengths for the x and y axis. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Use the keyword `ticklen` to set both at once. -xticklenratio, yticklenratio, ticklenratio : float, default: :rc:`tick.lenratio` +xticklenratio, yticklenratio, ticklenratio : float, default: [tick.lenratio](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.lenratio) Relative scaling of `xticklen` and `yticklen` used to determine minor tick lengths. Use the keyword `ticklenratio` to set both at once. -xtickwidth, ytickwidth, tickwidth, : unit-spec, default: :rc:`tick.width` +xtickwidth, ytickwidth, tickwidth, : unit-spec, default: [tick.width](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.width) Major tick widths for the x ans y axis. Default is `linewidth` if it was passed. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Use the keyword `tickwidth` to set both at once. -xtickwidthratio, ytickwidthratio, tickwidthratio : float, default: :rc:`tick.widthratio` +xtickwidthratio, ytickwidthratio, tickwidthratio : float, default: [tick.widthratio](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.widthratio) Relative scaling of `xtickwidth` and `ytickwidth` used to determine minor tick widths. Use the keyword `tickwidthratio` to set both at once. -xticklabelpad, yticklabelpad, ticklabelpad : unit-spec, default: :rc:`tick.labelpad` +xticklabelpad, yticklabelpad, ticklabelpad : unit-spec, default: [tick.labelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.labelpad) The padding between the x and y axis ticks and tick labels. Use the keyword `ticklabelpad` to set both at once. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -xticklabelcolor, yticklabelcolor, ticklabelcolor : color-spec, default: :rc:`tick.labelcolor` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +xticklabelcolor, yticklabelcolor, ticklabelcolor : color-spec, default: [tick.labelcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.labelcolor) Color for the x and y tick labels. Defaults are `xcolor`, `ycolor`, and `color` if they were passed. Use the keyword `ticklabelcolor` to set both at once. -xticklabelsize, yticklabelsize, ticklabelsize : unit-spec or str, default: :rc:`tick.labelsize` +xticklabelsize, yticklabelsize, ticklabelsize : unit-spec or str, default: [tick.labelsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.labelsize) Font size for the x and y tick labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Use the keyword `ticklabelsize` to set both at once. -xticklabelweight, yticklabelweight, ticklabelweight : str, default: :rc:`tick.labelweight` +xticklabelweight, yticklabelweight, ticklabelweight : str, default: [tick.labelweight](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.labelweight) Font weight for the x and y tick labels. Use the keyword `ticklabelweight` to set both at once. -xlabelpad, ylabelpad : unit-spec, default: :rc:`label.pad` +xlabelpad, ylabelpad : unit-spec, default: [label.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=label.pad) The padding between the x and y axis bounding box and the x and y axis labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -xlabelcolor, ylabelcolor, labelcolor : color-spec, default: :rc:`label.color` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +xlabelcolor, ylabelcolor, labelcolor : color-spec, default: [label.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=label.color) Color for the x and y axis labels. Defaults are `xcolor`, `ycolor`, and `color` if they were passed. Use the keyword `labelcolor` to set both at once. -xlabelsize, ylabelsize, labelsize : unit-spec or str, default: :rc:`label.size` +xlabelsize, ylabelsize, labelsize : unit-spec or str, default: [label.size](https://ultraplot.readthedocs.io/en/stable/search.html?q=label.size) Font size for the x and y axis labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Use the keyword `labelsize` to set both at once. -xlabelweight, ylabelweight, labelweight : str, default: :rc:`label.weight` +xlabelweight, ylabelweight, labelweight : str, default: [label.weight](https://ultraplot.readthedocs.io/en/stable/search.html?q=label.weight) Font weight for the x and y axis labels. Use the keyword `labelweight` to set both at once. fixticks : bool, default: False - Whether to transform the tick locators to a `~matplotlib.ticker.FixedLocator`. + Whether to transform the tick locators to a [FixedLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.FixedLocator.html). If your axis ticks are doing weird things (for example, ticks are drawn outside of the axis spine) you can try setting this to ``True``. r0 : float, default: 0 @@ -2116,13 +2116,13 @@ thetagridcolor, rgridcolor, gridcolor : color-spec, optional Use the keyword `gridcolor` to set both at once. thetalocator, rlocator : locator-spec, optional Used to determine the azimuthal and radial gridline positions. - Passed to the `~ultraplot.constructor.Locator` constructor. Can be - float, list of float, string, or `matplotlib.ticker.Locator` instance. + Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. Can be + float, list of float, string, or [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) instance. thetalines, rlines Aliases for `thetalocator`, `rlocator`. thetalocator_kw, rlocator_kw : dict-like, optional The azimuthal and radial locator settings. Passed to - `~ultraplot.constructor.Locator`. + [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html). thetaminorlocator, rminorlocator : optional As for `thetalocator`, `rlocator`, but for the minor gridlines. thetaminorticks, rminorticks : optional @@ -2135,16 +2135,16 @@ rlabelpos : float, optional position. thetaformatter, rformatter : formatter-spec, optional Used to determine the azimuthal and radial label format. - Passed to the `~ultraplot.constructor.Formatter` constructor. - Can be string, list of string, or `matplotlib.ticker.Formatter` + Passed to the [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html) constructor. + Can be string, list of string, or [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) instance. Use ``[]``, ``'null'``, or ``'none'`` for no labels. thetalabels, rlabels : optional Aliases for `thetaformatter`, `rformatter`. thetaformatter_kw, rformatter_kw : dict-like, optional The azimuthal and radial label formatter settings. Passed to - `~ultraplot.constructor.Formatter`. + [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html). thetalabel, rlabel : str, optional - Polar-aware axis labels rendered via `~ultraplot.text.CurvedText`. + Polar-aware axis labels rendered via [CurvedText](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.text.CurvedText.html). ``thetalabel`` follows the outer arc just beyond ``r=rmax``. ``rlabel`` follows a radial spoke, centered between ``rmin`` and ``rmax``. On a full circle it uses ``get_rlabel_position()`` unless @@ -2165,40 +2165,40 @@ rlabelloc : {'right', 'left'}, default: 'right' (default) anchors to ``thetamin`` and ``'left'`` anchors to ``thetamax``; the label is then offset outward from the sector. thetalabel_kw, rlabel_kw : dict-like, optional - Additional `~ultraplot.text.CurvedText` settings for the polar-aware + Additional [CurvedText](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.text.CurvedText.html) settings for the polar-aware labels (e.g. ``border``, ``bbox``, or rendering hints like ``min_advance``). See also `labelpad`, `labelcolor`, `labelsize`, and `labelweight`. -color : color-spec, default: :rc:`meta.color` +color : color-spec, default: [meta.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=meta.color) Color for the axes edge. Propagates to `labelcolor` unless specified - otherwise (similar to :func:`~ultraplot.axes.CartesianAxes.format`). -labelcolor, gridlabelcolor : color-spec, default: `color` or :rc:`grid.labelcolor` + otherwise (similar to [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html#ultraplot.axes.CartesianAxes.format)). +labelcolor, gridlabelcolor : color-spec, default: `color` or [grid.labelcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelcolor) Color for the gridline labels. -labelpad, gridlabelpad : unit-spec, default: :rc:`grid.labelpad` +labelpad, gridlabelpad : unit-spec, default: [grid.labelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelpad) The padding between the axes edge and the radial and azimuthal labels. For ``thetalabel`` and ``rlabel``, this is added on top of the built-in tick-clearance offset. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -labelsize, gridlabelsize : unit-spec or str, default: :rc:`grid.labelsize` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +labelsize, gridlabelsize : unit-spec or str, default: [grid.labelsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelsize) Font size for the gridline labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -labelweight, gridlabelweight : str, default: :rc:`grid.labelweight` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +labelweight, gridlabelweight : str, default: [grid.labelweight](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelweight) Font weight for the gridline labels. aspect : {'auto', 'equal'} or float, optional The map aspect ratio. ``'auto'`` makes the map fill its subplot slot, which can be useful for aligning it with neighboring Cartesian axes but distorts - the projection. See :func:`~matplotlib.axes.Axes.set_aspect` for details. + the projection. See [set_aspect](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_aspect.html) for details. abcanchor : {'axes', 'slot'}, default: 'axes' The coordinate box used for the a-b-c label. ``'axes'`` attaches it to the visible map boundary. ``'slot'`` attaches it to the unadjusted GridSpec slot, keeping labels aligned with neighboring subplots when fixed map aspect leaves empty space inside a slot. -round : bool, default: :rc:`geo.round` +round : bool, default: [geo.round](https://ultraplot.readthedocs.io/en/stable/search.html?q=geo.round) *For polar cartopy axes only*. Whether to bound polar projections with circles rather than squares. Note that outer gridline labels cannot be added to circle-bounded polar projections. When basemap - is the backend this argument must be passed to `~ultraplot.constructor.Proj` instead. -extent : {'globe', 'auto'}, default: :rc:`geo.extent` + is the backend this argument must be passed to [Proj](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Proj.html) instead. +extent : {'globe', 'auto'}, default: [geo.extent](https://ultraplot.readthedocs.io/en/stable/search.html?q=geo.extent) *For cartopy axes only*. Whether to auto adjust the map bounds based on plotted content. If ``'globe'`` then non-polar projections are fixed with `~cartopy.mpl.geoaxes.GeoAxes.set_global`, @@ -2208,42 +2208,42 @@ lonlim, latlim : 2-tuple of float, optional *For cartopy axes only.* The approximate longitude and latitude boundaries of the map, applied with `~cartopy.mpl.geoaxes.GeoAxes.set_extent`. When basemap is the backend - this argument must be passed to `~ultraplot.constructor.Proj` instead. + this argument must be passed to [Proj](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Proj.html) instead. boundinglat : float, optional *For cartopy axes only.* The edge latitude for the circle bounding North Pole and South Pole-centered projections. When basemap is the backend this argument must be passed to - `~ultraplot.constructor.Proj` instead. -longrid, latgrid, grid : bool, default: :rc:`grid` + [Proj](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Proj.html) instead. +longrid, latgrid, grid : bool, default: [grid](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid) Whether to draw longitude and latitude gridlines. Use the keyword `grid` to toggle both at once. -longridminor, latgridminor, gridminor : bool, default: :rc:`gridminor` +longridminor, latgridminor, gridminor : bool, default: [gridminor](https://ultraplot.readthedocs.io/en/stable/search.html?q=gridminor) Whether to draw "minor" longitude and latitude lines. Use the keyword `gridminor` to toggle both at once. -lonticklen, latticklen, ticklen : unit-spec, default: :rc:`tick.len` +lonticklen, latticklen, ticklen : unit-spec, default: [tick.len](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.len) Major tick lengths for the longitudinal (x) and latitude (y) axis. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Use the keyword `ticklen` to set both at once. latmax : float, default: 80 The maximum absolute latitude for gridlines. Longitude gridlines are cut off poleward of this value (note this feature does not work in cartopy 0.18). -nsteps : int, default: :rc:`grid.nsteps` +nsteps : int, default: [grid.nsteps](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.nsteps) *For cartopy axes only.* The number of interpolation steps used to draw gridlines. lonlocator, latlocator : locator-spec, optional Used to determine the longitude and latitude gridline locations. Aliases: ``lonlines`` and ``latlines``, respectively. - Passed to the `~ultraplot.constructor.Locator` constructor. Can be - string, float, list of float, or `matplotlib.ticker.Locator` instance. + Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. Can be + string, float, list of float, or [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) instance. For basemap or cartopy < 0.18, the defaults are ``'deglon'`` and - ``'deglat'``, which correspond to the `~ultraplot.ticker.LongitudeLocator` - and `~ultraplot.ticker.LatitudeLocator` locators (adapted from cartopy). + ``'deglat'``, which correspond to the [LongitudeLocator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.LongitudeLocator.html) + and [LatitudeLocator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.LatitudeLocator.html) locators (adapted from cartopy). For cartopy >= 0.18, the defaults are ``'dmslon'`` and ``'dmslat'``, which uses the same locators with ``dms=True``. This selects gridlines at nice degree-minute-second intervals when the map extent is very small. lonlocator_kw, latlocator_kw : dict-like, optional - Keyword arguments passed to the `matplotlib.ticker.Locator` class. + Keyword arguments passed to the [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. Aliases: ``lonlines_kw`` and ``latlines_kw``, respectively. lonminorlocator, latminorlocator : optional As with `lonlocator` and `latlocator` but for the "minor" gridlines. @@ -2251,7 +2251,7 @@ lonminorlocator, latminorlocator : optional lonminorlocator_kw, latminorlocator_kw : optional As with `lonlocator_kw`, and `latlocator_kw` but for the "minor" gridlines. Aliases: ``lonminorlines_kw`` and ``latminorlines_kw``, respectively. -lonlabels, latlabels, labels : str, bool, or sequence, :rc:`grid.labels` +lonlabels, latlabels, labels : str, bool, or sequence, [grid.labels](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labels) Whether to add non-inline longitude and latitude gridline labels, and on which sides of the map. Use the keyword `labels` to set both at once. The argument must conform to one of the following options: @@ -2270,14 +2270,14 @@ lonlabels, latlabels, labels : str, bool, or sequence, :rc:`grid.labels` and the ``(left, right)`` sides for latitudes. * A boolean 4-tuple indicating whether to draw labels on the ``(left, right, bottom, top)`` sides, as with the basemap - :func:`~mpl_toolkits.basemap.Basemap.drawmeridians` and - :func:`~mpl_toolkits.basemap.Basemap.drawparallels` `labels` keyword. + `drawmeridians` and + `drawparallels` `labels` keyword. -loninline, latinline, inlinelabels : bool, default: :rc:`grid.inlinelabels` +loninline, latinline, inlinelabels : bool, default: [grid.inlinelabels](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.inlinelabels) *For cartopy axes only.* Whether to add inline longitude and latitude gridline labels. Use the keyword `inlinelabels` to set both at once. -rotatelabels : bool, default: :rc:`grid.rotatelabels` +rotatelabels : bool, default: [grid.rotatelabels](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.rotatelabels) *For cartopy axes only.* Whether to rotate non-inline gridline labels so that they automatically follow the map boundary curvature. @@ -2290,11 +2290,11 @@ lonlabelrotation : float, optional latlabelrotation : float, optional The rotation angle in degrees for latitude tick labels. Works for both cartopy and basemap backends. -labelpad : unit-spec, default: :rc:`grid.labelpad` +labelpad : unit-spec, default: [grid.labelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelpad) *For cartopy axes only.* The padding between non-inline gridline labels and the map boundary. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -dms : bool, default: :rc:`grid.dmslabels` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +dms : bool, default: [grid.dmslabels](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.dmslabels) *For cartopy axes only.* Whether the default locators and formatters should use "minutes" and "seconds" for gridline labels on small scales rather than decimal degrees. Setting this to @@ -2302,11 +2302,11 @@ dms : bool, default: :rc:`grid.dmslabels` and ``ax.format(lonformatter='deglon', latformatter='deglat')``. lonformatter, latformatter : formatter-spec, optional Formatter used to style longitude and latitude gridline labels. - Passed to the `~ultraplot.constructor.Formatter` constructor. Can be - string, list of string, or `matplotlib.ticker.Formatter` instance. + Passed to the [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html) constructor. Can be + string, list of string, or [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) instance. For basemap or cartopy < 0.18, the defaults are ``'deglon'`` and - ``'deglat'``, which correspond to `~ultraplot.ticker.SimpleFormatter` + ``'deglat'``, which correspond to [SimpleFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.SimpleFormatter.html) presets with degree symbols and cardinal direction suffixes. For cartopy >= 0.18, the defaults are ``'dmslon'`` and ``'dmslat'``, which uses cartopy's `~cartopy.mpl.ticker.LongitudeFormatter` and @@ -2314,46 +2314,46 @@ lonformatter, latformatter : formatter-spec, optional This formats gridlines that do not fall on whole degrees as "minutes" and "seconds" rather than decimal degrees. Use ``dms=False`` to disable this. lonformatter_kw, latformatter_kw : dict-like, optional - Keyword arguments passed to the `matplotlib.ticker.Formatter` class. + Keyword arguments passed to the [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) class. land, ocean, coast, rivers, lakes, borders, innerborders : bool, optional Toggles various geographic features. These are actually the - :rcraw:`land`, :rcraw:`ocean`, :rcraw:`coast`, :rcraw:`rivers`, - :rcraw:`lakes`, :rcraw:`borders`, and :rcraw:`innerborders` - settings passed to `~ultraplot.config.Configurator.context`. + [land](https://ultraplot.readthedocs.io/en/stable/search.html?q=land), [ocean](https://ultraplot.readthedocs.io/en/stable/search.html?q=ocean), [coast](https://ultraplot.readthedocs.io/en/stable/search.html?q=coast), [rivers](https://ultraplot.readthedocs.io/en/stable/search.html?q=rivers), + [lakes](https://ultraplot.readthedocs.io/en/stable/search.html?q=lakes), [borders](https://ultraplot.readthedocs.io/en/stable/search.html?q=borders), and [innerborders](https://ultraplot.readthedocs.io/en/stable/search.html?q=innerborders) + settings passed to [context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context). The style can be modified using additional `rc` settings. - For example, to change :rcraw:`land.color`, use + For example, to change [land.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=land.color), use ``ax.format(landcolor='green')``, and to change - :rcraw:`land.zorder`, use ``ax.format(landzorder=4)``. + [land.zorder](https://ultraplot.readthedocs.io/en/stable/search.html?q=land.zorder), use ``ax.format(landzorder=4)``. reso : {'lo', 'med', 'hi', 'x-hi', 'xx-hi'}, optional *For cartopy axes only.* The resolution of geographic features. When basemap is the backend this - must be passed to `~ultraplot.constructor.Proj` instead. -color : color-spec, default: :rc:`meta.color` + must be passed to [Proj](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Proj.html) instead. +color : color-spec, default: [meta.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=meta.color) The color for the axes edge. Propagates to `labelcolor` unless specified - otherwise (similar to :func:`~ultraplot.axes.CartesianAxes.format`). -gridcolor : color-spec, default: :rc:`grid.color` + otherwise (similar to [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html#ultraplot.axes.CartesianAxes.format)). +gridcolor : color-spec, default: [grid.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.color) The color for the gridline labels. -labelcolor : color-spec, default: `color` or :rc:`grid.labelcolor` +labelcolor : color-spec, default: `color` or [grid.labelcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelcolor) The color for the gridline labels (`gridlabelcolor` is also allowed). -labelsize : unit-spec or str, default: :rc:`grid.labelsize` +labelsize : unit-spec or str, default: [grid.labelsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelsize) The font size for the gridline labels (`gridlabelsize` is also allowed). - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -labelweight : str, default: :rc:`grid.labelweight` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +labelweight : str, default: [grid.labelweight](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelweight) The font weight for the gridline labels (`gridlabelweight` is also allowed). rc_mode : int, optional - The context mode passed to `~ultraplot.config.Configurator.context`. + The context mode passed to [context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context). rc_kw : dict-like, optional An alternative to passing extra keyword arguments. See below. **kwargs - Keyword arguments that match the name of an `~ultraplot.config.rc` setting are - passed to `ultraplot.config.Configurator.context` and used to update the axes. + Keyword arguments that match the name of an [rc](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.rc.html) setting are + passed to [ultraplot.config.Configurator.context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context) and used to update the axes. If the setting name has "dots" you can simply omit the dots. For example, - ``abc='A.'`` modifies the :rcraw:`abc` setting, ``titleloc='left'`` modifies the - :rcraw:`title.loc` setting, ``gridminor=True`` modifies the :rcraw:`gridminor` - setting, and ``gridbelow=True`` modifies the :rcraw:`grid.below` setting. Many + ``abc='A.'`` modifies the [abc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc) setting, ``titleloc='left'`` modifies the + [title.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.loc) setting, ``gridminor=True`` modifies the [gridminor](https://ultraplot.readthedocs.io/en/stable/search.html?q=gridminor) + setting, and ``gridbelow=True`` modifies the [grid.below](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.below) setting. Many of the keyword arguments documented above are internally applied by retrieving - settings passed to `~ultraplot.config.Configurator.context`. + settings passed to [context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context). See also -------- @@ -2371,45 +2371,45 @@ ultraplot.config.Configurator.context""" Parameters ---------- mappable : mappable, colormap-spec, sequence of color-spec, - or sequence of :class:`~matplotlib.artist.Artist` + or sequence of [Artist](https://matplotlib.org/stable/api/_as_gen/matplotlib.artist.Artist.html) There are four options here: - 1. A `~matplotlib.cm.ScalarMappable` (e.g., an object returned by - `~ultraplot.axes.PlotAxes.contourf` or `~ultraplot.axes.PlotAxes.pcolormesh`). - 2. A `~matplotlib.colors.Colormap` or registered colormap name used to build a - `~matplotlib.cm.ScalarMappable` on-the-fly. The colorbar range and ticks depend + 1. A [ScalarMappable](https://matplotlib.org/stable/api/_as_gen/matplotlib.cm.ScalarMappable.html) (e.g., an object returned by + [contourf](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PlotAxes.html#ultraplot.axes.PlotAxes.contourf) or [pcolormesh](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PlotAxes.html#ultraplot.axes.PlotAxes.pcolormesh)). + 2. A [Colormap](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Colormap.html) or registered colormap name used to build a + [ScalarMappable](https://matplotlib.org/stable/api/_as_gen/matplotlib.cm.ScalarMappable.html) on-the-fly. The colorbar range and ticks depend on the arguments `values`, `vmin`, `vmax`, and `norm`. The default for a - :class:`~ultraplot.colors.ContinuousColormap` is ``vmin=0`` and ``vmax=1`` (note that + [ContinuousColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html) is ``vmin=0`` and ``vmax=1`` (note that passing `values` will "discretize" the colormap). The default for a - :class:`~ultraplot.colors.DiscreteColormap` is ``values=np.arange(0, cmap.N)``. + [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html) is ``values=np.arange(0, cmap.N)``. 3. A sequence of hex strings, color names, or RGB[A] tuples. A - :class:`~ultraplot.colors.DiscreteColormap` will be generated from these colors and - used to build a `~matplotlib.cm.ScalarMappable` on-the-fly. The colorbar + [DiscreteColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteColormap.html) will be generated from these colors and + used to build a [ScalarMappable](https://matplotlib.org/stable/api/_as_gen/matplotlib.cm.ScalarMappable.html) on-the-fly. The colorbar range and ticks depend on the arguments `values`, `norm`, and `norm_kw`. The default is ``values=np.arange(0, len(mappable))``. - 4. A sequence of `matplotlib.artist.Artist` instances (e.g., a list of - `~matplotlib.lines.Line2D` instances returned by `~ultraplot.axes.PlotAxes.plot`). + 4. A sequence of [matplotlib.artist.Artist](https://matplotlib.org/stable/api/_as_gen/matplotlib.artist.Artist.html) instances (e.g., a list of + [Line2D](https://matplotlib.org/stable/api/_as_gen/matplotlib.lines.Line2D.html) instances returned by [plot](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PlotAxes.html#ultraplot.axes.PlotAxes.plot)). A colormap will be generated from the colors of these objects (where the color is determined by ``get_color``, if available, or ``get_facecolor``). The colorbar range and ticks depend on the arguments `values`, `norm`, and `norm_kw`. The default is to infer colorbar ticks and tick labels - by calling `~matplotlib.artist.Artist.get_label` on each artist. + by calling [get_label](https://matplotlib.org/stable/api/_as_gen/matplotlib.artist.Artist.get_label.html) on each artist. values : sequence of float or str, optional - Ignored if `mappable` is a `~matplotlib.cm.ScalarMappable`. This maps the colormap - colors to numeric values using `~ultraplot.colors.DiscreteNorm`. If the colormap is - a :class:`~ultraplot.colors.ContinuousColormap` then its colors will be "discretized". + Ignored if `mappable` is a [ScalarMappable](https://matplotlib.org/stable/api/_as_gen/matplotlib.cm.ScalarMappable.html). This maps the colormap + colors to numeric values using [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html). If the colormap is + a [ContinuousColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html) then its colors will be "discretized". These These can also be strings, in which case the list indices are used for tick locations and the strings are applied as tick labels. -length : float, default: :rc:`colorbar.length` +length : float, default: [colorbar.length](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.length) The colorbar length. Units are relative to the span of the rows and columns of subplots. shrink : float, optional Alias for `length`. This is included for consistency with - `matplotlib.figure.Figure.colorbar`. -width : unit-spec, default: :rc:`colorbar.width` + [matplotlib.figure.Figure.colorbar](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.colorbar.html). +width : unit-spec, default: [colorbar.width](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.width) The colorbar width. - If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + If float, units are inches. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). loc : str, optional The colorbar location. Valid location keys are as follows. @@ -2424,15 +2424,15 @@ loc : str, optional space : float or str, default: None The fixed space between the colorbar and the subplot grid edge. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. - When the :ref:`tight layout algorithm ` is active for the figure, + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). + When the [tight layout algorithm](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_tight) is active for the figure, `space` is computed automatically (see `pad`). Otherwise, `space` is set to a suitable default. -pad : float or str, default: :rc:`subplots.innerpad` or :rc:`subplots.panelpad` - The :ref:`tight layout padding ` between the colorbar and the - subplot grid. Default is :rcraw:`subplots.innerpad` for the first colorbar - and :rcraw:`subplots.panelpad` for subsequently "stacked" colorbars. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +pad : float or str, default: [subplots.innerpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.innerpad) or [subplots.panelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.panelpad) + The [tight layout padding](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_tight) between the colorbar and the + subplot grid. Default is [subplots.innerpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.innerpad) for the first colorbar + and [subplots.panelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.panelpad) for subsequently "stacked" colorbars. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). row, rows Aliases for `span` for colorbars on the left or right side. col, cols @@ -2456,25 +2456,25 @@ orientation : {None, 'horizontal', 'vertical'}, optional The colorbar orientation. By default this depends on the "side" of the subplot or figure where the colorbar is drawn. Inset colorbars are always horizontal. norm : norm-spec, optional - Ignored if `mappable` is a `~matplotlib.cm.ScalarMappable`. This is the continuous - normalizer used to scale the :class:`~ultraplot.colors.ContinuousColormap` (or passed - to `~ultraplot.colors.DiscreteNorm` if `values` was passed). Passed to the - `~ultraplot.constructor.Norm` constructor function. + Ignored if `mappable` is a [ScalarMappable](https://matplotlib.org/stable/api/_as_gen/matplotlib.cm.ScalarMappable.html). This is the continuous + normalizer used to scale the [ContinuousColormap](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ContinuousColormap.html) (or passed + to [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html) if `values` was passed). Passed to the + [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html) constructor function. norm_kw : dict-like, optional - Ignored if `mappable` is a `~matplotlib.cm.ScalarMappable`. These are the - normalizer keyword arguments. Passed to `~ultraplot.constructor.Norm`. + Ignored if `mappable` is a [ScalarMappable](https://matplotlib.org/stable/api/_as_gen/matplotlib.cm.ScalarMappable.html). These are the + normalizer keyword arguments. Passed to [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html). vmin, vmax : float, optional - Ignored if `mappable` is a `~matplotlib.cm.ScalarMappable`. These are the minimum - and maximum colorbar values. Passed to `~ultraplot.constructor.Norm`. + Ignored if `mappable` is a [ScalarMappable](https://matplotlib.org/stable/api/_as_gen/matplotlib.cm.ScalarMappable.html). These are the minimum + and maximum colorbar values. Passed to [Norm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Norm.html). label, title : str, optional The colorbar label. The `title` keyword is also accepted for - consistency with `~matplotlib.axes.Axes.legend`. + consistency with [legend](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.legend.html). reverse : bool, optional Whether to reverse the direction of the colorbar. This is done automatically - when descending levels are used with `~ultraplot.colors.DiscreteNorm`. + when descending levels are used with [DiscreteNorm](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.DiscreteNorm.html). rotation : float, default: 0 The tick label rotation. -grid, edges, drawedges : bool, default: :rc:`colorbar.grid` +grid, edges, drawedges : bool, default: [colorbar.grid](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.grid) Whether to draw "grid" dividers between each distinct color. extend : {'neither', 'both', 'min', 'max'}, optional Direction for drawing colorbar "extensions" (i.e. color keys for out-of-bounds @@ -2482,76 +2482,76 @@ extend : {'neither', 'both', 'min', 'max'}, optional passed to the plotting command or use ``'neither'`` if the value is unknown. extendfrac : float, optional The length of the colorbar "extensions" relative to the length of the colorbar. - This is a native matplotlib `~matplotlib.figure.Figure.colorbar` keyword. -extendsize : unit-spec, default: :rc:`colorbar.extend` or :rc:`colorbar.insetextend` + This is a native matplotlib [colorbar](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.colorbar.html) keyword. +extendsize : unit-spec, default: [colorbar.extend](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.extend) or [colorbar.insetextend](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.insetextend) The length of the colorbar "extensions" in physical units. Default is - :rcraw:`colorbar.extend` for outer colorbars and :rcraw:`colorbar.insetextend` - for inset colorbars. If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + [colorbar.extend](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.extend) for outer colorbars and [colorbar.insetextend](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.insetextend) + for inset colorbars. If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). extendrect : bool, default: False Whether to draw colorbar "extensions" as rectangles. If ``False`` then the extensions are drawn as triangles. locator, ticks : locator-spec, optional Used to determine the colorbar tick positions. Passed to the - `~ultraplot.constructor.Locator` constructor function. By default - `~matplotlib.ticker.AutoLocator` is used for continuous color levels - and `~ultraplot.ticker.DiscreteLocator` is used for discrete color levels. + [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor function. By default + [AutoLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.AutoLocator.html) is used for continuous color levels + and [DiscreteLocator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.DiscreteLocator.html) is used for discrete color levels. locator_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Locator` class. + Keyword arguments passed to [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. minorlocator, minorticks As with `locator`, `ticks` but for the minor ticks. By default - `~matplotlib.ticker.AutoMinorLocator` is used for continuous color levels - and `~ultraplot.ticker.DiscreteLocator` is used for discrete color levels. + [AutoMinorLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.AutoMinorLocator.html) is used for continuous color levels + and [DiscreteLocator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.DiscreteLocator.html) is used for discrete color levels. minorlocator_kw As with `locator_kw`, but for the minor ticks. format, formatter, ticklabels : formatter-spec, optional - The tick label format. Passed to the `~ultraplot.constructor.Formatter` + The tick label format. Passed to the [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html) constructor function. formatter_kw : dict-like, optional - Keyword arguments passed to `matplotlib.ticker.Formatter` class. + Keyword arguments passed to [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) class. frame, frameon : bool, optional For inset colorbars, indicates whether to draw a background "frame", - just like `~matplotlib.axes.Axes.legend`. Defaults to - :rc:`colorbar.frameon` for inset colorbars. For outer colorbars, this is a + just like [legend](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.legend.html). Defaults to + [colorbar.frameon](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.frameon) for inset colorbars. For outer colorbars, this is a backwards-compatible alias for `outline`; when omitted, outer colorbars - still default to :rc:`colorbar.outline`. + still default to [colorbar.outline](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.outline). tickminor : bool, optional - Whether to add minor ticks using `~matplotlib.colorbar.ColorbarBase.minorticks_on`. + Whether to add minor ticks using [minorticks_on](https://matplotlib.org/stable/api/_as_gen/matplotlib.colorbar.ColorbarBase.minorticks_on.html). tickloc, ticklocation : {'bottom', 'top', 'left', 'right'}, optional Where to draw tick marks on the colorbar. Default is toward the outside of the subplot for outer colorbars and ``'bottom'`` for inset colorbars. -tickdir, tickdirection : {'out', 'in', 'inout'}, default: :rc:`tick.dir` +tickdir, tickdirection : {'out', 'in', 'inout'}, default: [tick.dir](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.dir) Direction of major and minor colorbar ticks. -ticklen : unit-spec, default: :rc:`tick.len` +ticklen : unit-spec, default: [tick.len](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.len) Major tick lengths for the colorbar ticks. -ticklenratio : float, default: :rc:`tick.lenratio` +ticklenratio : float, default: [tick.lenratio](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.lenratio) Relative scaling of `ticklen` used to determine minor tick lengths. tickwidth : unit-spec, default: `linewidth` Major tick widths for the colorbar ticks. - or :rc:`tick.width` if `linewidth` was not passed. -tickwidthratio : float, default: :rc:`tick.widthratio` + or [tick.width](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.width) if `linewidth` was not passed. +tickwidthratio : float, default: [tick.widthratio](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.widthratio) Relative scaling of `tickwidth` used to determine minor tick widths. -ticklabelcolor, ticklabelsize, ticklabelweight: default: :rc:`tick.labelcolor`, :rc:`tick.labelsize`, :rc:`tick.labelweight`. +ticklabelcolor, ticklabelsize, ticklabelweight: default: [tick.labelcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.labelcolor), [tick.labelsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.labelsize), [tick.labelweight](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.labelweight). The font color, size, and weight for colorbar tick labels labelloc, labellocation : {'bottom', 'top', 'left', 'right'} The colorbar label location. Inherits from `tickloc` by default. Default is toward the outside of the subplot for outer colorbars and ``'bottom'`` for inset colorbars. -labelcolor, labelsize, labelweight: default: :rc:`label.color`, :rc:`label.size`, and :rc:`label.weight`. +labelcolor, labelsize, labelweight: default: [label.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=label.color), [label.size](https://ultraplot.readthedocs.io/en/stable/search.html?q=label.size), and [label.weight](https://ultraplot.readthedocs.io/en/stable/search.html?q=label.weight). The font color, size, and weight for the colorbar label. -a, alpha, framealpha, fc, facecolor, framecolor, ec, edgecolor, ew, edgewidth : default: :rc:`colorbar.framealpha`, :rc:`colorbar.framecolor` +a, alpha, framealpha, fc, facecolor, framecolor, ec, edgecolor, ew, edgewidth : default: [colorbar.framealpha](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.framealpha), [colorbar.framecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.framecolor) For inset colorbars only. Controls the transparency and color of the background frame. lw, linewidth, c, color : optional Controls the line width and edge color for both the colorbar outline and the level dividers. -edgefix : bool or float, default: :rc:`edgefix` +edgefix : bool or float, default: [edgefix](https://ultraplot.readthedocs.io/en/stable/search.html?q=edgefix) Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). - See this `github repo `__ for a + See this [github repo](https://github.com/jklymak/contourfIssues) for a demonstration of the problem. If ``True``, a small default linewidth of ``0.3`` is used to cover up the white lines. If float (e.g. ``edgefix=0.5``), this specific linewidth is used to cover up the white lines. This feature is automatically disabled when the patches have transparency. -rasterize : bool, default: :rc:`colorbar.rasterized` +rasterize : bool, default: [colorbar.rasterized](https://ultraplot.readthedocs.io/en/stable/search.html?q=colorbar.rasterized) Whether to rasterize the colorbar solids. The matplotlib default was ``True`` but ultraplot changes this to ``False`` since rasterization can cause misalignment between the color patches and the colorbar outline. @@ -2565,7 +2565,7 @@ labelrotation : str, float, default: None **kwargs - Passed to `~matplotlib.figure.Figure.colorbar`. + Passed to [colorbar](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.colorbar.html). See also -------- @@ -2580,7 +2580,7 @@ Add a colorbar to a plot. Parameters ---------- mappable - The `matplotlib.cm.ScalarMappable` (i.e., `.AxesImage`, + The [matplotlib.cm.ScalarMappable](https://matplotlib.org/stable/api/_as_gen/matplotlib.cm.ScalarMappable.html) (i.e., `.AxesImage`, `.ContourSet`, etc.) described by this colorbar. This argument is mandatory for the `.Figure.colorbar` method but optional for the `.pyplot.colorbar` function, which sets the default to the current @@ -2592,12 +2592,12 @@ mappable fig.colorbar(cm.ScalarMappable(norm=norm, cmap=cmap), ax=ax) -cax : `~matplotlib.axes.Axes`, optional +cax : [Axes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html), optional Axes into which the colorbar will be drawn. If `None`, then a new Axes is created and the space for it will be stolen from the Axes(s) specified in *ax*. -ax : `~matplotlib.axes.Axes` or iterable or `numpy.ndarray` of Axes, optional +ax : [Axes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html) or iterable or [numpy.ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html) of Axes, optional The one or more parent Axes from which space for a new colorbar Axes will be stolen. This parameter is only used if *cax* is not set. @@ -2611,7 +2611,7 @@ use_gridspec : bool, optional Returns ------- -colorbar : `~matplotlib.colorbar.Colorbar` +colorbar : [Colorbar](https://matplotlib.org/stable/api/_as_gen/matplotlib.colorbar.Colorbar.html) Other Parameters ---------------- @@ -2737,23 +2737,22 @@ Parameters handles : list of artist, optional List of matplotlib artists, or a list of lists of artist instances (see the `center` keyword). If not passed, artists with valid labels (applied by passing `label` or - `labels` to a plotting command or calling `~matplotlib.artist.Artist.set_label`) - are retrieved automatically. If the object is a `~matplotlib.contour.ContourSet`, - `~matplotlib.contour.ContourSet.legend_elements` is used to select the central + `labels` to a plotting command or calling [set_label](https://matplotlib.org/stable/api/_as_gen/matplotlib.artist.Artist.set_label.html)) + are retrieved automatically. If the object is a [ContourSet](https://matplotlib.org/stable/api/_as_gen/matplotlib.contour.ContourSet.html), + [legend_elements](https://matplotlib.org/stable/api/_as_gen/matplotlib.contour.ContourSet.legend_elements.html) is used to select the central artist in the list (generally useful for single-color contour plots). Note that - ultraplot's `~ultraplot.axes.PlotAxes.contour` and `~ultraplot.axes.PlotAxes.contourf` + ultraplot's [contour](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PlotAxes.html#ultraplot.axes.PlotAxes.contour) and [contourf](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PlotAxes.html#ultraplot.axes.PlotAxes.contourf) accept a legend `label` keyword argument. labels : list of str, optional A matching list of string labels or ``None`` placeholders, or a matching list of lists (see the `center` keyword). Wherever ``None`` appears in the list (or if no labels were passed at all), labels are retrieved by calling - `~matplotlib.artist.Artist.get_label` on each `~matplotlib.artist.Artist` in the + [get_label](https://matplotlib.org/stable/api/_as_gen/matplotlib.artist.Artist.get_label.html) on each [Artist](https://matplotlib.org/stable/api/_as_gen/matplotlib.artist.Artist.html) in the handle list. If a handle consists of a tuple group of artists, labels are inferred from the artists in the tuple (if there are multiple unique labels in the tuple group of artists, the tuple group is expanded into unique legend entries -- otherwise, the tuple group elements are drawn on top of eachother). For details - on matplotlib legend handlers and tuple groups, see the matplotlib `legend guide -`__. + on matplotlib legend handlers and tuple groups, see the matplotlib [legend guide](https://matplotlib.org/stable/tutorials/intermediate/legend_guide.html). loc : str, optional The legend location. Valid location keys are as follows. @@ -2768,15 +2767,15 @@ loc : str, optional space : float or str, default: None The fixed space between the legend and the subplot grid edge. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. - When the :ref:`tight layout algorithm ` is active for the figure, + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). + When the [tight layout algorithm](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_tight) is active for the figure, `space` is computed automatically (see `pad`). Otherwise, `space` is set to a suitable default. -pad : float or str, default: :rc:`subplots.innerpad` or :rc:`subplots.panelpad` - The :ref:`tight layout padding ` between the legend and the - subplot grid. Default is :rcraw:`subplots.innerpad` for the first legend - and :rcraw:`subplots.panelpad` for subsequently "stacked" legends. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +pad : float or str, default: [subplots.innerpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.innerpad) or [subplots.panelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.panelpad) + The [tight layout padding](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_tight) between the legend and the + subplot grid. Default is [subplots.innerpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.innerpad) for the first legend + and [subplots.panelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.panelpad) for subsequently "stacked" legends. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). row, rows Aliases for `span` for legends on the left or right side. col, cols @@ -2794,8 +2793,8 @@ align : {'center', 'top', 't', 'bottom', 'b', 'left', 'l', 'right', 'r'}, option legends. The default is always ``'center'``. width : unit-spec, optional The space allocated for the legend box. This does nothing if - the :ref:`tight layout algorithm ` is active for the figure. - If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + the [tight layout algorithm](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_tight) is active for the figure. + If float, units are inches. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Other parameters ---------------- @@ -2804,10 +2803,10 @@ frame, frameon : bool, optional independent from matplotlib's built-in legend frame is created. ncol, ncols : int, optional The number of columns. `ncols` is an alias, added - for consistency with `~matplotlib.pyplot.subplots`. + for consistency with [subplots](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.subplots.html). order : {'C', 'F'}, optional Whether legend handles are drawn in row-major (``'C'``) or column-major - (``'F'``) order. Analagous to `numpy.array` ordering. The matplotlib + (``'F'``) order. Analagous to [numpy.array](https://numpy.org/doc/stable/reference/generated/numpy.array.html) ordering. The matplotlib default was ``'F'`` but ultraplot changes this to ``'C'``. center : bool, optional Whether to center each legend row individually. If ``True``, we draw @@ -2819,17 +2818,17 @@ alphabetize : bool, default: False the legend labels. title, label : str, optional The legend title. The `label` keyword is also accepted, for consistency - with `~matplotlib.figure.Figure.colorbar`. + with [colorbar](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.colorbar.html). fontsize, fontweight, fontcolor : optional The font size, weight, and color for the legend text. Font size is interpreted - by `~ultraplot.utils.units`. The default font size is :rcraw:`legend.fontsize`. + by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). The default font size is [legend.fontsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.fontsize). titlefontsize, titlefontweight, titlefontcolor : optional The font size, weight, and color for the legend title. Font size is interpreted - by `~ultraplot.utils.units`. The default size is `fontsize`. + by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). The default size is `fontsize`. borderpad, borderaxespad, handlelength, handleheight, handletextpad, labelspacing, columnspacing : unit-spec, optional - Various matplotlib `~matplotlib.axes.Axes.legend` spacing arguments. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -a, alpha, framealpha, fc, facecolor, framecolor, ec, edgecolor, ew, edgewidth: default: :rc:`legend.framealpha`, :rc:`legend.facecolor`, :rc:`legend.edgecolor`, :rc:`axes.linewidth` The opacity, face color, edge color, and edge width for the legend frame. + Various matplotlib [legend](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.legend.html) spacing arguments. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +a, alpha, framealpha, fc, facecolor, framecolor, ec, edgecolor, ew, edgewidth: default: [legend.framealpha](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.framealpha), [legend.facecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.facecolor), [legend.edgecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.edgecolor), [axes.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.linewidth) The opacity, face color, edge color, and edge width for the legend frame. c, color, lw, linewidth, m, marker, ls, linestyle, dashes, ms, markersize : optional Properties used to override the legend handles. For example, for a legend describing variations in line style ignoring variations @@ -2841,9 +2840,9 @@ handle_kw : dict-like, optional handler_map : dict-like, optional A dictionary mapping instances or types to a legend handler. This `handler_map` updates the default handler map found at - `matplotlib.legend.Legend.get_legend_handler_map`. + [matplotlib.legend.Legend.get_legend_handler_map](https://matplotlib.org/stable/api/_as_gen/matplotlib.legend.Legend.get_legend_handler_map.html). **kwargs - Passed to `~matplotlib.axes.Axes.legend`. + Passed to [legend](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.legend.html). See also -------- @@ -2872,7 +2871,7 @@ when you do not pass in any extra arguments. In this case, the labels are taken from the artist. You can specify them either at artist creation or by calling the -:meth:`~.Artist.set_label` method on the artist:: +`set_label` method on the artist:: ax.plot([1, 2, 3], label='Inline label') fig.legend() @@ -2945,7 +2944,7 @@ labels : list of str, optional Returns ------- -`~matplotlib.legend.Legend` +[Legend](https://matplotlib.org/stable/api/_as_gen/matplotlib.legend.Legend.html) Other Parameters ---------------- @@ -2995,7 +2994,7 @@ loc : str or pair of floats, default: 'upper right' right side of the layout. In addition to the values of *loc* listed above, we have 'outside right upper', 'outside right lower', 'outside left upper', and 'outside left lower'. See - :ref:`legend_guide` for more details. + [legend_guide](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend_guide) for more details. bbox_to_anchor : `.BboxBase`, 2-tuple, or 4-tuple of floats Box that is used to position the legend in conjunction with *loc*. @@ -3026,29 +3025,29 @@ ncols : int, default: 1 For backward compatibility, the spelling *ncol* is also supported but it is discouraged. If both are given, *ncols* takes precedence. -prop : None or `~matplotlib.font_manager.FontProperties` or dict +prop : None or [FontProperties](https://matplotlib.org/stable/api/_as_gen/matplotlib.font_manager.FontProperties.html) or dict The font properties of the legend. If None (default), the current - :data:`matplotlib.rcParams` will be used. + [matplotlib.rcParams](https://matplotlib.org/stable/api/_as_gen/matplotlib.rcParams.html) will be used. fontsize : int or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'} The font size of the legend. If the value is numeric the size will be the absolute font size in points. String values are relative to the current default font size. This argument is only used if *prop* is not specified. -labelcolor : str or list, default: :rc:`legend.labelcolor` +labelcolor : str or list, default: [legend.labelcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.labelcolor) The color of the text in the legend. Either a valid color string (for example, 'red'), or a list of color strings. The labelcolor can also be made to match the color of the line or marker using 'linecolor', 'markerfacecolor' (or 'mfc'), or 'markeredgecolor' (or 'mec'). - Labelcolor can be set globally using :rc:`legend.labelcolor`. If None, - use :rc:`text.color`. + Labelcolor can be set globally using [legend.labelcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.labelcolor). If None, + use [text.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=text.color). -numpoints : int, default: :rc:`legend.numpoints` +numpoints : int, default: [legend.numpoints](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.numpoints) The number of marker points in the legend when creating a legend entry for a `.Line2D` (line). -scatterpoints : int, default: :rc:`legend.scatterpoints` +scatterpoints : int, default: [legend.scatterpoints](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.scatterpoints) The number of marker points in the legend when creating a legend entry for a `.PathCollection` (scatter plot). @@ -3058,7 +3057,7 @@ scatteryoffsets : iterable of floats, default: ``[0.375, 0.5, 0.3125]`` legend text, and 1.0 is at the top. To draw all markers at the same height, set to ``[0.5]``. -markerscale : float, default: :rc:`legend.markerscale` +markerscale : float, default: [legend.markerscale](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.markerscale) The relative size of legend markers compared to the originally drawn ones. markerfirst : bool, default: True @@ -3071,50 +3070,50 @@ reverse : bool, default: False .. versionadded:: 3.7 -frameon : bool, default: :rc:`legend.frameon` +frameon : bool, default: [legend.frameon](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.frameon) Whether the legend should be drawn on a patch (frame). -fancybox : bool, default: :rc:`legend.fancybox` +fancybox : bool, default: [legend.fancybox](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.fancybox) Whether round edges should be enabled around the `.FancyBboxPatch` which makes up the legend's background. -shadow : None, bool or dict, default: :rc:`legend.shadow` +shadow : None, bool or dict, default: [legend.shadow](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.shadow) Whether to draw a shadow behind the legend. The shadow can be configured using `.Patch` keywords. - Customization via :rc:`legend.shadow` is currently not supported. + Customization via [legend.shadow](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.shadow) is currently not supported. -framealpha : float, default: :rc:`legend.framealpha` +framealpha : float, default: [legend.framealpha](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.framealpha) The alpha transparency of the legend's background. If *shadow* is activated and *framealpha* is ``None``, the default value is ignored. -facecolor : "inherit" or color, default: :rc:`legend.facecolor` +facecolor : "inherit" or color, default: [legend.facecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.facecolor) The legend's background color. - If ``"inherit"``, use :rc:`axes.facecolor`. + If ``"inherit"``, use [axes.facecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.facecolor). -edgecolor : "inherit" or color, default: :rc:`legend.edgecolor` +edgecolor : "inherit" or color, default: [legend.edgecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.edgecolor) The legend's background patch edge color. - If ``"inherit"``, use :rc:`axes.edgecolor`. + If ``"inherit"``, use [axes.edgecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.edgecolor). mode : {"expand", None} If *mode* is set to ``"expand"`` the legend will be horizontally expanded to fill the Axes area (or *bbox_to_anchor* if defines the legend's size). -bbox_transform : None or `~matplotlib.transforms.Transform` +bbox_transform : None or [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html) The transform for the bounding box (*bbox_to_anchor*). For a value of ``None`` (default) the Axes' - :data:`~matplotlib.axes.Axes.transAxes` transform will be used. + [transAxes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.transAxes.html) transform will be used. title : str or None The legend's title. Default is no title (``None``). -title_fontproperties : None or `~matplotlib.font_manager.FontProperties` or dict +title_fontproperties : None or [FontProperties](https://matplotlib.org/stable/api/_as_gen/matplotlib.font_manager.FontProperties.html) or dict The font properties of the legend's title. If None (default), the *title_fontsize* argument will be used if present; if *title_fontsize* is - also None, the current :rc:`legend.title_fontsize` will be used. + also None, the current [legend.title_fontsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.title_fontsize) will be used. -title_fontsize : int or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}, default: :rc:`legend.title_fontsize` +title_fontsize : int or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}, default: [legend.title_fontsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.title_fontsize) The font size of the legend's title. Note: This cannot be combined with *title_fontproperties*. If you want to set the fontsize alongside other font properties, use the *size* @@ -3124,31 +3123,31 @@ alignment : {'center', 'left', 'right'}, default: 'center' The alignment of the legend title and the box of entries. The entries are aligned as a single block, so that markers always lined up. -borderpad : float, default: :rc:`legend.borderpad` +borderpad : float, default: [legend.borderpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.borderpad) The fractional whitespace inside the legend border, in font-size units. -labelspacing : float, default: :rc:`legend.labelspacing` +labelspacing : float, default: [legend.labelspacing](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.labelspacing) The vertical space between the legend entries, in font-size units. -handlelength : float, default: :rc:`legend.handlelength` +handlelength : float, default: [legend.handlelength](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.handlelength) The length of the legend handles, in font-size units. -handleheight : float, default: :rc:`legend.handleheight` +handleheight : float, default: [legend.handleheight](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.handleheight) The height of the legend handles, in font-size units. -handletextpad : float, default: :rc:`legend.handletextpad` +handletextpad : float, default: [legend.handletextpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.handletextpad) The pad between the legend handle and text, in font-size units. -borderaxespad : float, default: :rc:`legend.borderaxespad` +borderaxespad : float, default: [legend.borderaxespad](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.borderaxespad) The pad between the Axes and legend border, in font-size units. -columnspacing : float, default: :rc:`legend.columnspacing` +columnspacing : float, default: [legend.columnspacing](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.columnspacing) The spacing between columns, in font-size units. handler_map : dict or None The custom dictionary mapping instances or types to a legend handler. This *handler_map* updates the default handler map - found at `matplotlib.legend.Legend.get_legend_handler_map`. + found at [matplotlib.legend.Legend.get_legend_handler_map](https://matplotlib.org/stable/api/_as_gen/matplotlib.legend.Legend.get_legend_handler_map.html). draggable : bool, default: False Whether the legend can be dragged with the mouse. @@ -3161,7 +3160,7 @@ See Also Notes ----- Some artists are not supported by this function. See -:ref:`legend_guide` for details.""" +[legend_guide](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend_guide) for details.""" ... def save(self, filename: Incomplete, **kwargs: Incomplete) -> None: @@ -3172,7 +3171,7 @@ Parameters path : path-like, optional The file path. User paths are expanded with `os.path.expanduser`. **kwargs - Passed to `~matplotlib.figure.Figure.savefig` + Passed to [savefig](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.savefig.html) See also -------- @@ -3189,7 +3188,7 @@ Parameters path : path-like, optional The file path. User paths are expanded with `os.path.expanduser`. **kwargs - Passed to `~matplotlib.figure.Figure.savefig` + Passed to [savefig](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.savefig.html) See also -------- @@ -3217,7 +3216,7 @@ Parameters fname : str or path-like or binary file-like A path, or a Python file-like object, or possibly some backend-dependent object such as - `matplotlib.backends.backend_pdf.PdfPages`. + [matplotlib.backends.backend_pdf.PdfPages](https://matplotlib.org/stable/api/_as_gen/matplotlib.backends.backend_pdf.PdfPages.html). If *format* is set, it determines the output format, and the file is saved as *fname*. Note that *fname* is used verbatim, and there @@ -3227,12 +3226,12 @@ fname : str or path-like or binary file-like If *format* is not set, then the format is inferred from the extension of *fname*, if there is one. If *format* is not set and *fname* has no extension, then the file is saved with - :rc:`savefig.format` and the appropriate extension is appended to + [savefig.format](https://ultraplot.readthedocs.io/en/stable/search.html?q=savefig.format) and the appropriate extension is appended to *fname*. Other Parameters ---------------- -transparent : bool, default: :rc:`savefig.transparent` +transparent : bool, default: [savefig.transparent](https://ultraplot.readthedocs.io/en/stable/search.html?q=savefig.transparent) If *True*, the Axes patches will all be transparent; the Figure patch will also be transparent unless *facecolor* and/or *edgecolor* are specified via kwargs. @@ -3248,7 +3247,7 @@ transparent : bool, default: :rc:`savefig.transparent` This is useful, for example, for displaying a plot on top of a colored background on a web page. -dpi : float or 'figure', default: :rc:`savefig.dpi` +dpi : float or 'figure', default: [savefig.dpi](https://ultraplot.readthedocs.io/en/stable/search.html?q=savefig.dpi) The resolution in dots per inch. If 'figure', use the figure's dpi value. @@ -3273,21 +3272,21 @@ metadata : dict, optional Does not currently support 'jpg', 'tiff', or 'webp', but may include embedding EXIF metadata in the future. -bbox_inches : str or `.Bbox`, default: :rc:`savefig.bbox` +bbox_inches : str or `.Bbox`, default: [savefig.bbox](https://ultraplot.readthedocs.io/en/stable/search.html?q=savefig.bbox) Bounding box in inches: only the given portion of the figure is saved. If 'tight', try to figure out the tight bbox of the figure. -pad_inches : float or 'layout', default: :rc:`savefig.pad_inches` +pad_inches : float or 'layout', default: [savefig.pad_inches](https://ultraplot.readthedocs.io/en/stable/search.html?q=savefig.pad_inches) Amount of padding in inches around the figure when bbox_inches is 'tight'. If 'layout' use the padding from the constrained or compressed layout engine; ignored if one of those engines is not in use. -facecolor : :mpltype:`color` or 'auto', default: :rc:`savefig.facecolor` +facecolor : [color](https://matplotlib.org/stable/search.html?q=color) or 'auto', default: [savefig.facecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=savefig.facecolor) The facecolor of the figure. If 'auto', use the current figure facecolor. -edgecolor : :mpltype:`color` or 'auto', default: :rc:`savefig.edgecolor` +edgecolor : [color](https://matplotlib.org/stable/search.html?q=color) or 'auto', default: [savefig.edgecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=savefig.edgecolor) The edgecolor of the figure. If 'auto', use the current figure edgecolor. @@ -3296,7 +3295,7 @@ backend : str, optional png file with the "cairo" backend rather than the default "agg", or a pdf file with the "pgf" backend rather than the default "pdf". Note that the default backend is normally sufficient. See - :ref:`the-builtin-backends` for a list of valid backends for each + [the-builtin-backends](https://ultraplot.readthedocs.io/en/stable/search.html?q=the-builtin-backends) for a list of valid backends for each file format. Custom backends can be referenced as "module://...". orientation : {'landscape', 'portrait'} @@ -3307,7 +3306,7 @@ papertype : str 'a10', 'b0' through 'b10'. Only supported for postscript output. -bbox_extra_artists : list of `~matplotlib.artist.Artist`, optional +bbox_extra_artists : list of [Artist](https://matplotlib.org/stable/api/_as_gen/matplotlib.artist.Artist.html), optional A list of extra artists that will be considered when the tight bbox is calculated. @@ -3318,12 +3317,12 @@ pil_kwargs : dict, optional def set_canvas(self, canvas: Incomplete) -> None: """Set the figure canvas. Add monkey patches for the instance-level -`~matplotlib.backend_bases.FigureCanvasBase.draw` and -`~matplotlib.backend_bases.FigureCanvasBase.print_figure` methods. +[draw](https://matplotlib.org/stable/api/_as_gen/matplotlib.backend_bases.FigureCanvasBase.draw.html) and +[print_figure](https://matplotlib.org/stable/api/_as_gen/matplotlib.backend_bases.FigureCanvasBase.print_figure.html) methods. Parameters ---------- -canvas : `~matplotlib.backend_bases.FigureCanvasBase` +canvas : [FigureCanvasBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.backend_bases.FigureCanvasBase.html) The figure canvas. See also @@ -3399,7 +3398,7 @@ To transform from pixels to inches divide by `Figure.dpi`.""" def _iter_axes(self, hidden: Incomplete=False, children: Incomplete=False, panels: Incomplete=True) -> Incomplete: """Iterate over all axes and panels in the figure belonging to the -`~ultraplot.axes.Axes` class. Exclude inset and twin axes. +[Axes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html) class. Exclude inset and twin axes. Parameters ---------- @@ -3413,7 +3412,7 @@ panels : bool or str or sequence of str, optional @property def gridspec(self) -> Incomplete: - """The single :class:`~ultraplot.gridspec.GridSpec` instance used for all + """The single [GridSpec](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.gridspec.GridSpec.html) instance used for all subplots in the figure. See also @@ -3425,7 +3424,7 @@ ultraplot.gridspec.SubplotGrid.gridspec""" @gridspec.setter def gridspec(self, gs: Incomplete) -> None: - """The single :class:`~ultraplot.gridspec.GridSpec` instance used for all + """The single [GridSpec](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.gridspec.GridSpec.html) instance used for all subplots in the figure. See also @@ -3445,8 +3444,8 @@ ultraplot.gridspec.SubplotGrid.gridspec""" @property def subplotgrid(self) -> Incomplete: - """A :class:`~ultraplot.gridspec.SubplotGrid` containing the numbered subplots in the -figure. The subplots are ordered by increasing `~ultraplot.axes.Axes.number`. + """A [SubplotGrid](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.gridspec.SubplotGrid.html) containing the numbered subplots in the +figure. The subplots are ordered by increasing [number](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.number). See also -------- @@ -3456,8 +3455,8 @@ ultraplot.gridspec.SubplotGrid.figure""" @property def tight(self) -> Incomplete: - """Whether the :ref:`tight layout algorithm ` is active for the -figure. This value is passed to `~ultraplot.figure.Figure.auto_layout` + """Whether the [tight layout algorithm](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_tight) is active for the +figure. This value is passed to [auto_layout](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.auto_layout) every time the figure is drawn. Can be changed e.g. ``fig.tight = False``. See also diff --git a/ultraplot/gridspec.pyi b/ultraplot/gridspec.pyi index 7a084571a..4b772c16e 100644 --- a/ultraplot/gridspec.pyi +++ b/ultraplot/gridspec.pyi @@ -46,7 +46,7 @@ def _apply_to_all(func: None=None, *, doc_key: Optional[str]=None) -> Callable[[ ... class _SubplotSpec(mgridspec.SubplotSpec): - """A thin `~matplotlib.gridspec.SubplotSpec` subclass with a nice string + """A thin [SubplotSpec](https://matplotlib.org/stable/api/_as_gen/matplotlib.gridspec.SubplotSpec.html) subclass with a nice string representation and a few helper methods.""" def __repr__(self) -> Incomplete: @@ -74,7 +74,7 @@ the main plots, not the panels or colorbars.""" ... class GridSpec(mgridspec.GridSpec): - """A `~matplotlib.gridspec.GridSpec` subclass that permits variable spacing + """A [GridSpec](https://matplotlib.org/stable/api/_as_gen/matplotlib.gridspec.GridSpec.html) subclass that permits variable spacing between successive rows and columns and hides "panel slots" from indexing.""" def __repr__(self) -> str: @@ -104,53 +104,53 @@ Other parameters ---------------- left, right, top, bottom : unit-spec, default: None The fixed space between the subplots and the figure edge. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). If ``None``, the space is determined automatically based on the tick and - label settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + label settings. If [subplots.tight](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.tight) is ``True`` or ``tight=True`` was passed to the figure, the space is determined by the tight layout algorithm. wspace, hspace, space : unit-spec or sequence, default: None The fixed space between grid columns, rows, and both, respectively. If float, string, or ``None``, this value is expanded into lists of length ``ncols - 1`` (for `wspace`) or length ``nrows - 1`` (for `hspace`). If a sequence, its length must match these lengths. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). For elements equal to ``None``, the space is determined automatically based - on the tick and label settings. If :rcraw:`subplots.tight` is ``True`` or + on the tick and label settings. If [subplots.tight](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.tight) is ``True`` or ``tight=True`` was passed to the figure, the space is determined by the tight layout algorithm. For example, ``subplots(ncols=3, tight=True, wspace=(2, None))`` fixes the space between columns 1 and 2 but lets the tight layout algorithm determine the space between columns 2 and 3. wratios, hratios : float or sequence, optional - Passed to :class:`~ultraplot.gridspec.GridSpec`, denotes the width and height + Passed to [GridSpec](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.gridspec.GridSpec.html), denotes the width and height ratios for the subplot grid. Length of `wratios` must match the number of columns, and length of `hratios` must match the number of rows. width_ratios, height_ratios Aliases for `wratios`, `hratios`. Included for - consistency with `matplotlib.gridspec.GridSpec`. + consistency with [matplotlib.gridspec.GridSpec](https://matplotlib.org/stable/api/_as_gen/matplotlib.gridspec.GridSpec.html). wpad, hpad, pad : unit-spec or sequence, optional The tight layout padding between columns, rows, and both, respectively. Unlike ``space``, these control the padding between subplot content (including text, ticks, etc.) rather than subplot edges. As with ``space``, these can be scalars or arrays optionally containing ``None``. For elements equal to ``None``, the default is `innerpad`. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -wequal, hequal, equal : bool, default: :rc:`subplots.equalspace` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +wequal, hequal, equal : bool, default: [subplots.equalspace](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.equalspace) Whether to make the tight layout algorithm apply equal spacing between columns, rows, or both. -wgroup, hgroup, group : bool, default: :rc:`subplots.groupspace` +wgroup, hgroup, group : bool, default: [subplots.groupspace](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.groupspace) Whether to make the tight layout algorithm just consider spaces between adjacent subplots instead of entire columns and rows of subplots. -outerpad : unit-spec, default: :rc:`subplots.outerpad` +outerpad : unit-spec, default: [subplots.outerpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.outerpad) The scalar tight layout padding around the left, right, top, bottom figure edges. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -innerpad : unit-spec, default: :rc:`subplots.innerpad` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +innerpad : unit-spec, default: [subplots.innerpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.innerpad) The scalar tight layout padding between columns and rows. Synonymous with `pad`. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -panelpad : unit-spec, default: :rc:`subplots.panelpad` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +panelpad : unit-spec, default: [subplots.panelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.panelpad) The scalar tight layout padding between subplots and their panels, colorbars, and legends and between "stacks" of these objects. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). See also -------- @@ -167,9 +167,9 @@ Adding axes panels, axes or figure colorbars, and axes or figure legends quietly augments the gridspec geometry by inserting "panel slots". However, subsequently indexing the gridspec with ``gs[num]`` or ``gs[row, col]`` will ignore the "panel slots". This permits adding new subplots by passing -``gs[num]`` or ``gs[row, col]`` to `~ultraplot.figure.Figure.add_subplot` +``gs[num]`` or ``gs[row, col]`` to [add_subplot](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.add_subplot) even in the presence of panels (see `~GridSpec.__getitem__` for details). -This also means that each `GridSpec` is `~ultraplot.figure.Figure`-specific, +This also means that each `GridSpec` is [Figure](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html)-specific, i.e. it can only be used once (if you are working with `GridSpec` instances manually and want the same geometry for multiple figures, you must create a copy with `GridSpec.copy` before working on the subsequent figure).""" @@ -200,10 +200,10 @@ bbox : Bbox or None ... def __getitem__(self, key: Incomplete) -> _SubplotSpec: - """Get a `~matplotlib.gridspec.SubplotSpec`. "Hidden" slots allocated for axes + """Get a [SubplotSpec](https://matplotlib.org/stable/api/_as_gen/matplotlib.gridspec.SubplotSpec.html). "Hidden" slots allocated for axes panels, colorbars, and legends are ignored. For example, given a gridspec with 2 subplot rows, 3 subplot columns, and a "panel" row between the subplot rows, -calling ``gs[1, 1]`` returns a `~matplotlib.gridspec.SubplotSpec` corresponding +calling ``gs[1, 1]`` returns a [SubplotSpec](https://matplotlib.org/stable/api/_as_gen/matplotlib.gridspec.SubplotSpec.html) corresponding to the central subplot on the second row rather than a "panel" slot.""" ... @@ -303,7 +303,7 @@ gridspec and figure parameters. May or may not need to be applied.""" ... def copy(self, **kwargs: Incomplete) -> GridSpec: - """Return a copy of the `GridSpec` with the `~ultraplot.figure.Figure`-specific + """Return a copy of the `GridSpec` with the [Figure](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html)-specific "panel slots" removed. This can be useful if you want to draw multiple figures with the same geometry. Properties are inherited from this `GridSpec` by default but can be changed by passing keyword arguments. @@ -312,53 +312,53 @@ Parameters ---------- left, right, top, bottom : unit-spec, default: None The fixed space between the subplots and the figure edge. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). If ``None``, the space is determined automatically based on the tick and - label settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + label settings. If [subplots.tight](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.tight) is ``True`` or ``tight=True`` was passed to the figure, the space is determined by the tight layout algorithm. wspace, hspace, space : unit-spec or sequence, default: None The fixed space between grid columns, rows, and both, respectively. If float, string, or ``None``, this value is expanded into lists of length ``ncols - 1`` (for `wspace`) or length ``nrows - 1`` (for `hspace`). If a sequence, its length must match these lengths. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). For elements equal to ``None``, the space is determined automatically based - on the tick and label settings. If :rcraw:`subplots.tight` is ``True`` or + on the tick and label settings. If [subplots.tight](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.tight) is ``True`` or ``tight=True`` was passed to the figure, the space is determined by the tight layout algorithm. For example, ``subplots(ncols=3, tight=True, wspace=(2, None))`` fixes the space between columns 1 and 2 but lets the tight layout algorithm determine the space between columns 2 and 3. wratios, hratios : float or sequence, optional - Passed to :class:`~ultraplot.gridspec.GridSpec`, denotes the width and height + Passed to [GridSpec](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.gridspec.GridSpec.html), denotes the width and height ratios for the subplot grid. Length of `wratios` must match the number of columns, and length of `hratios` must match the number of rows. width_ratios, height_ratios Aliases for `wratios`, `hratios`. Included for - consistency with `matplotlib.gridspec.GridSpec`. + consistency with [matplotlib.gridspec.GridSpec](https://matplotlib.org/stable/api/_as_gen/matplotlib.gridspec.GridSpec.html). wpad, hpad, pad : unit-spec or sequence, optional The tight layout padding between columns, rows, and both, respectively. Unlike ``space``, these control the padding between subplot content (including text, ticks, etc.) rather than subplot edges. As with ``space``, these can be scalars or arrays optionally containing ``None``. For elements equal to ``None``, the default is `innerpad`. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -wequal, hequal, equal : bool, default: :rc:`subplots.equalspace` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +wequal, hequal, equal : bool, default: [subplots.equalspace](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.equalspace) Whether to make the tight layout algorithm apply equal spacing between columns, rows, or both. -wgroup, hgroup, group : bool, default: :rc:`subplots.groupspace` +wgroup, hgroup, group : bool, default: [subplots.groupspace](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.groupspace) Whether to make the tight layout algorithm just consider spaces between adjacent subplots instead of entire columns and rows of subplots. -outerpad : unit-spec, default: :rc:`subplots.outerpad` +outerpad : unit-spec, default: [subplots.outerpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.outerpad) The scalar tight layout padding around the left, right, top, bottom figure edges. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -innerpad : unit-spec, default: :rc:`subplots.innerpad` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +innerpad : unit-spec, default: [subplots.innerpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.innerpad) The scalar tight layout padding between columns and rows. Synonymous with `pad`. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -panelpad : unit-spec, default: :rc:`subplots.panelpad` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +panelpad : unit-spec, default: [subplots.panelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.panelpad) The scalar tight layout padding between subplots and their panels, colorbars, and legends and between "stacks" of these objects. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). See also -------- @@ -405,8 +405,8 @@ Note ---- The physical units for positioning grid cells are converted from em-widths to inches when the `GridSpec` is instantiated. This means that subsequent changes -to :rcraw:`font.size` will have no effect on the spaces. This is consistent -with :rcraw:`font.size` having no effect on already-instantiated figures. +to [font.size](https://ultraplot.readthedocs.io/en/stable/search.html?q=font.size) will have no effect on the spaces. This is consistent +with [font.size](https://ultraplot.readthedocs.io/en/stable/search.html?q=font.size) having no effect on already-instantiated figures. See also -------- @@ -421,53 +421,53 @@ Parameters ---------- left, right, top, bottom : unit-spec, default: None The fixed space between the subplots and the figure edge. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). If ``None``, the space is determined automatically based on the tick and - label settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + label settings. If [subplots.tight](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.tight) is ``True`` or ``tight=True`` was passed to the figure, the space is determined by the tight layout algorithm. wspace, hspace, space : unit-spec or sequence, default: None The fixed space between grid columns, rows, and both, respectively. If float, string, or ``None``, this value is expanded into lists of length ``ncols - 1`` (for `wspace`) or length ``nrows - 1`` (for `hspace`). If a sequence, its length must match these lengths. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). For elements equal to ``None``, the space is determined automatically based - on the tick and label settings. If :rcraw:`subplots.tight` is ``True`` or + on the tick and label settings. If [subplots.tight](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.tight) is ``True`` or ``tight=True`` was passed to the figure, the space is determined by the tight layout algorithm. For example, ``subplots(ncols=3, tight=True, wspace=(2, None))`` fixes the space between columns 1 and 2 but lets the tight layout algorithm determine the space between columns 2 and 3. wratios, hratios : float or sequence, optional - Passed to :class:`~ultraplot.gridspec.GridSpec`, denotes the width and height + Passed to [GridSpec](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.gridspec.GridSpec.html), denotes the width and height ratios for the subplot grid. Length of `wratios` must match the number of columns, and length of `hratios` must match the number of rows. width_ratios, height_ratios Aliases for `wratios`, `hratios`. Included for - consistency with `matplotlib.gridspec.GridSpec`. + consistency with [matplotlib.gridspec.GridSpec](https://matplotlib.org/stable/api/_as_gen/matplotlib.gridspec.GridSpec.html). wpad, hpad, pad : unit-spec or sequence, optional The tight layout padding between columns, rows, and both, respectively. Unlike ``space``, these control the padding between subplot content (including text, ticks, etc.) rather than subplot edges. As with ``space``, these can be scalars or arrays optionally containing ``None``. For elements equal to ``None``, the default is `innerpad`. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -wequal, hequal, equal : bool, default: :rc:`subplots.equalspace` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +wequal, hequal, equal : bool, default: [subplots.equalspace](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.equalspace) Whether to make the tight layout algorithm apply equal spacing between columns, rows, or both. -wgroup, hgroup, group : bool, default: :rc:`subplots.groupspace` +wgroup, hgroup, group : bool, default: [subplots.groupspace](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.groupspace) Whether to make the tight layout algorithm just consider spaces between adjacent subplots instead of entire columns and rows of subplots. -outerpad : unit-spec, default: :rc:`subplots.outerpad` +outerpad : unit-spec, default: [subplots.outerpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.outerpad) The scalar tight layout padding around the left, right, top, bottom figure edges. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -innerpad : unit-spec, default: :rc:`subplots.innerpad` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +innerpad : unit-spec, default: [subplots.innerpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.innerpad) The scalar tight layout padding between columns and rows. Synonymous with `pad`. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -panelpad : unit-spec, default: :rc:`subplots.panelpad` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +panelpad : unit-spec, default: [subplots.panelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.panelpad) The scalar tight layout padding between subplots and their panels, colorbars, and legends and between "stacks" of these objects. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). See also -------- @@ -476,7 +476,7 @@ GridSpec.copy""" @property def figure(self) -> Incomplete: - """The `ultraplot.figure.Figure` uniquely associated with this `GridSpec`. + """The [ultraplot.figure.Figure](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html) uniquely associated with this `GridSpec`. On assignment the gridspec parameters and figure size are updated. See also @@ -487,7 +487,7 @@ ultraplot.figure.Figure.gridspec""" @figure.setter def figure(self, fig: Incomplete) -> None: - """The `ultraplot.figure.Figure` uniquely associated with this `GridSpec`. + """The [ultraplot.figure.Figure](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html) uniquely associated with this `GridSpec`. On assignment the gridspec parameters and figure size are updated. See also @@ -509,7 +509,7 @@ In order of precedence the values are taken from - non-*None* attributes of the GridSpec - the provided *figure* -- :rc:`figure.subplot.*` +- [figure.subplot.*](https://ultraplot.readthedocs.io/en/stable/search.html?q=figure.subplot.%2A) Note that the ``figure`` attribute of the GridSpec is always ignored.""" ... @@ -557,8 +557,8 @@ This is a subset of the attributes of `.SubplotParams`.""" class SubplotGrid(MutableSequence[paxes.Axes], list[paxes.Axes], paxes.PlotAxes): """List-like, array-like object used to store subplots returned by -`~ultraplot.figure.Figure.subplots`. 1D indexing uses the underlying list of -`~ultraplot.axes.Axes` while 2D indexing uses the `~SubplotGrid.gridspec`. +[subplots](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.subplots). 1D indexing uses the underlying list of +[Axes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html) while 2D indexing uses the `~SubplotGrid.gridspec`. See `~SubplotGrid.__getitem__` for details.""" def __repr__(self) -> str: @@ -577,7 +577,7 @@ See `~SubplotGrid.__getitem__` for details.""" """Parameters ---------- sequence : sequence - A sequence of `ultraplot.axes.Axes` subplots or their children. + A sequence of [ultraplot.axes.Axes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html) subplots or their children. See also -------- @@ -589,7 +589,7 @@ ultraplot.figure.Figure.add_subplots""" def __getattr__(self, attr: str) -> Any: """Get a missing attribute. Simply redirects to the axes if the `SubplotGrid` is singleton and raises an error otherwise. This can be convenient for -single-axes figures generated with `~ultraplot.figure.Figure.subplots`.""" +single-axes figures generated with [subplots](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.subplots).""" ... @overload @@ -651,7 +651,7 @@ Parameters ---------- key : int or slice The 1D index. -value : `ultraplot.axes.Axes` +value : [ultraplot.axes.Axes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html) The ultraplot subplot or its child or panel axes, or a sequence thereof if the index was a slice.""" ... @@ -669,14 +669,14 @@ Parameters title : str or sequence, optional The axes title. Can optionally be a sequence strings, in which case the title will be selected from the sequence according to `~Axes.number`. -abc : bool or str or sequence, default: :rc:`abc` +abc : bool or str or sequence, default: [abc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc) The "a-b-c" subplot label style. Must contain the character `a` or `A`, for example ``'a.'``, or ``'A'``. If ``True`` then the default style of ``'a'`` is used. The `a` or ``A`` is replaced with the alphabetic character matching the `~Axes.number`. If `~Axes.number` is greater than 26, the characters loop around to a, ..., z, aa, ..., zz, aaa, ..., zzz, etc. Can also be a sequence of strings, in which case the "a-b-c" label will be selected sequentially from the list. For example `axs.format(abc = ["X", "Y"])` for a two-panel figure, and `axes[3:5].format(abc = ["X", "Y"])` for a two-panel subset of a larger figure. -abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` +abcloc, titleloc : str, default: [abc.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.loc), [title.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.loc) Strings indicating the location for the a-b-c label and main title. The following locations are valid: @@ -698,31 +698,31 @@ abcloc, titleloc : str, default: :rc:`abc.loc`, :rc:`title.loc` right of y axis ``'outer right'``, ``'or'`` ======================== ============================ -abcborder, titleborder : bool, default: :rc:`abc.border` and :rc:`title.border` +abcborder, titleborder : bool, default: [abc.border](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.border) and [title.border](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.border) Whether to draw a white border around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes. -abcbbox, titlebbox : bool, default: :rc:`abc.bbox` and :rc:`title.bbox` +abcbbox, titlebbox : bool, default: [abc.bbox](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.bbox) and [title.bbox](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.bbox) Whether to draw a white bbox around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes. -abcpad : float or unit-spec, default: :rc:`abc.pad` +abcpad : float or unit-spec, default: [abc.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.pad) Horizontal offset to shift the a-b-c label position. Positive values move the label right, negative values move it left. This is separate from `abctitlepad`, which controls spacing between abc and title when co-located. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). abc_kw, title_kw : dict-like, optional Additional settings used to update the a-b-c label and title with ``text.update()``. -titlepad : float, default: :rc:`title.pad` +titlepad : float, default: [title.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.pad) The padding for the inner and outer titles and a-b-c labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -titleabove : bool, default: :rc:`title.above` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +titleabove : bool, default: [title.above](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.above) Whether to try to put outer titles and a-b-c labels above panels, colorbars, or legends that are above the axes. -abctitlepad : float, default: :rc:`abc.titlepad` +abctitlepad : float, default: [abc.titlepad](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc.titlepad) The horizontal padding between a-b-c labels and titles in the same location. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle : str or sequence, optional Shorthands for the below keywords. lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle : str or sequence, optional @@ -731,7 +731,7 @@ lowerlefttitle, lowercentertitle, lowerrighttitle : str or sequence, optional an alternative to the ``ax.format(title='Title', titleloc=loc)`` workflow and permits adding more than one title-like label for a single axes. a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle : default: - :rc:`axes.alpha` (default: 1.0), :rc:`axes.facecolor` (default: white), :rc:`axes.edgecolor` (default: black), :rc:`axes.linewidth` (default: 0.6), - + [axes.alpha](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.alpha) (default: 1.0), [axes.facecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.facecolor) (default: white), [axes.edgecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.edgecolor) (default: black), [axes.linewidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.linewidth) (default: 0.6), - Additional settings applied to the background patch, and their shorthands. Their defaults values are the ``'axes'`` properties. **kwargs @@ -748,14 +748,14 @@ leftlabels, toplabels, rightlabels, bottomlabels : sequence of str, optional bottom edges of the figure. The length of each list must match the number of subplots along the corresponding edge. leftlabelpad, toplabelpad, rightlabelpad, bottomlabelpad : float or unit-spec, default -: :rc:`leftlabel.pad`, :rc:`toplabel.pad`, :rc:`rightlabel.pad`, :rc:`bottomlabel.pad` +: [leftlabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=leftlabel.pad), [toplabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=toplabel.pad), [rightlabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=rightlabel.pad), [bottomlabel.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=bottomlabel.pad) The padding between the labels and the axes content. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). leftlabelsharedpad, toplabelsharedpad, rightlabelsharedpad, bottomlabelsharedpad : float or unit-spec, default -: :rc:`leftlabel.sharedpad`, :rc:`toplabel.sharedpad`, :rc:`rightlabel.sharedpad`, :rc:`bottomlabel.sharedpad` +: [leftlabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=leftlabel.sharedpad), [toplabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=toplabel.sharedpad), [rightlabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=rightlabel.sharedpad), [bottomlabel.sharedpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=bottomlabel.sharedpad) The padding between side labels and a shared spanning axis label on the same side. The spanning label is placed outside the side labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). leftlabels_kw, toplabels_kw, rightlabels_kw, bottomlabels_kw : dict-like, optional Additional settings used to update the labels with ``text.update()``. figtitle @@ -763,9 +763,9 @@ figtitle suptitle : str, optional The figure "super" title, centered between the left edge of the leftmost subplot and the right edge of the rightmost subplot. -suptitlepad : float, default: :rc:`suptitle.pad` +suptitlepad : float, default: [suptitle.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=suptitle.pad) The padding between the super title and the axes content. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). suptitle_kw : optional Additional settings used to update the super title with ``text.update()``. includepanels : bool, default: False @@ -773,18 +773,18 @@ includepanels : bool, default: False of the subplot grid and when aligning the `spanx` *x* axis labels and `spany` *y* axis labels along the sides of the subplot grid. aspect : {'auto', 'equal'} or float, optional - The data aspect ratio. See :func:`~matplotlib.axes.Axes.set_aspect` + The data aspect ratio. See [set_aspect](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_aspect.html) for details. xlabel, ylabel : str, optional - The x and y axis labels. Applied with `~matplotlib.axes.Axes.set_xlabel` - and `~matplotlib.axes.Axes.set_ylabel`. + The x and y axis labels. Applied with [set_xlabel](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlabel.html) + and [set_ylabel](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylabel.html). xlabel_kw, ylabel_kw : dict-like, optional - Additional axis label settings applied with `~matplotlib.axes.Axes.set_xlabel` - and `~matplotlib.axes.Axes.set_ylabel`. See also `labelpad`, `labelcolor`, + Additional axis label settings applied with [set_xlabel](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlabel.html) + and [set_ylabel](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylabel.html). See also `labelpad`, `labelcolor`, `labelsize`, and `labelweight` below. xlim, ylim : 2-tuple of floats or None, optional - The x and y axis data limits. Applied with :func:`~matplotlib.axes.Axes.set_xlim` - and :func:`~matplotlib.axes.Axes.set_ylim`. + The x and y axis data limits. Applied with [set_xlim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xlim.html) + and [set_ylim](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_ylim.html). xmin, ymin : float, optional The x and y minimum data limits. Useful if you do not want to set the maximum limits. @@ -795,12 +795,12 @@ xreverse, yreverse : bool, optional Whether to "reverse" the x and y axis direction. Makes the x and y axes ascend left-to-right and top-to-bottom, respectively. xscale, yscale : scale-spec, optional - The x and y axis scales. Passed to the `~ultraplot.scale.Scale` constructor. + The x and y axis scales. Passed to the [Scale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.Scale.html) constructor. For example, ``xscale='log'`` applies logarithmic scaling, and - ``xscale=('cutoff', 100, 2)`` applies a `~ultraplot.scale.CutoffScale`. + ``xscale=('cutoff', 100, 2)`` applies a [CutoffScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.CutoffScale.html). xscale_kw, yscale_kw : dict-like, optional - The x and y axis scale settings. Passed to `~ultraplot.scale.Scale`. -xmargin, ymargin, margin : float, default: :rc:`margin` + The x and y axis scale settings. Passed to [Scale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.Scale.html). +xmargin, ymargin, margin : float, default: [margin](https://ultraplot.readthedocs.io/en/stable/search.html?q=margin) The default margin between plotted content and the x and y axis spines in axes-relative coordinates. This is useful if you don't witch to explicitly set axis limits. Use the keyword `margin` to set both at once. @@ -813,16 +813,16 @@ xtickrange, ytickrange : 2-tuple of float, optional The x and y axis data ranges within which major tick marks are labelled. For example, ``xlim=(-5, 5)`` combined with ``xtickrange=(-1, 1)`` and a tick interval of 1 will only label the ticks marks at -1, 0, and 1. See - `~ultraplot.ticker.AutoFormatter` for details. + [AutoFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.AutoFormatter.html) for details. xwraprange, ywraprange : 2-tuple of float, optional The x and y axis data ranges with which major tick mark values are wrapped. For example, ``xwraprange=(0, 3)`` causes the values 0 through 9 to be formatted as - 0, 1, 2, 0, 1, 2, 0, 1, 2, 0. See `~ultraplot.ticker.AutoFormatter` for details. This + 0, 1, 2, 0, 1, 2, 0, 1, 2, 0. See [AutoFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.AutoFormatter.html) for details. This can be combined with `xtickrange` and `ytickrange` to make "stacked" line plots. xloc, yloc : optional Shorthands for `xspineloc`, `yspineloc`. xspineloc, yspineloc : {'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right', 'both', 'neither', 'none', 'zero', 'center'} or 2-tuple, optional - The x and y spine locations. Applied with `~matplotlib.spines.Spine.set_position`. + The x and y spine locations. Applied with [set_position](https://matplotlib.org/stable/api/_as_gen/matplotlib.spines.Spine.set_position.html). Propagates to `tickloc` unless specified otherwise. xtickloc, ytickloc : {'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right', 'both', 'neither', 'none'}, optional Which x and y axis spines should have major and minor tick marks. Inherits from @@ -844,25 +844,25 @@ xticklabeldir, yticklabeldir : {'in', 'out'}, optional Propagates to `xtickdir` and `ytickdir` unless specified otherwise. xrotation, yrotation : float, default: 0 The rotation for x and y axis tick labels. - for normal axes, :rc:`formatter.timerotation` for time x axes. -xgrid, ygrid, grid : bool, default: :rc:`grid` + for normal axes, [formatter.timerotation](https://ultraplot.readthedocs.io/en/stable/search.html?q=formatter.timerotation) for time x axes. +xgrid, ygrid, grid : bool, default: [grid](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid) Whether to draw major gridlines on the x and y axis. Use the keyword `grid` to toggle both. -xgridminor, ygridminor, gridminor : bool, default: :rc:`gridminor` +xgridminor, ygridminor, gridminor : bool, default: [gridminor](https://ultraplot.readthedocs.io/en/stable/search.html?q=gridminor) Whether to draw minor gridlines for the x and y axis. Use the keyword `gridminor` to toggle both. -xtickminor, ytickminor, tickminor : bool, default: :rc:`tick.minor` +xtickminor, ytickminor, tickminor : bool, default: [tick.minor](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.minor) Whether to draw minor ticks on the x and y axes. Use the keyword `tickminor` to toggle both. xticks, yticks : optional Aliases for `xlocator`, `ylocator`. xlocator, ylocator : locator-spec, optional Used to determine the x and y axis tick mark positions. Passed - to the `~ultraplot.constructor.Locator` constructor. Can be float, - list of float, string, or `matplotlib.ticker.Locator` instance. + to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. Can be float, + list of float, string, or [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) instance. Use ``[]``, ``'null'``, or ``'none'`` for no ticks. xlocator_kw, ylocator_kw : dict-like, optional - Keyword arguments passed to the `matplotlib.ticker.Locator` class. + Keyword arguments passed to the [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. xminorticks, yminorticks : optional Aliases for `xminorlocator`, `yminorlocator`. xminorlocator, yminorlocator : optional @@ -873,66 +873,66 @@ xticklabels, yticklabels : optional Aliases for `xformatter`, `yformatter`. xformatter, yformatter : formatter-spec, optional Used to determine the x and y axis tick label string format. - Passed to the `~ultraplot.constructor.Formatter` constructor. - Can be string, list of strings, or `matplotlib.ticker.Formatter` instance. + Passed to the [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html) constructor. + Can be string, list of strings, or [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) instance. Use ``[]``, ``'null'``, or ``'none'`` for no labels. xformatter_kw, yformatter_kw : dict-like, optional - Keyword arguments passed to the `matplotlib.ticker.Formatter` class. -xcolor, ycolor, color : color-spec, default: :rc:`meta.color` + Keyword arguments passed to the [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) class. +xcolor, ycolor, color : color-spec, default: [meta.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=meta.color) Color for the x and y axis spines, ticks, tick labels, and axis labels. Use the keyword `color` to set both at once. -xgridcolor, ygridcolor, gridcolor : color-spec, default: :rc:`grid.color` +xgridcolor, ygridcolor, gridcolor : color-spec, default: [grid.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.color) Color for the x and y axis major and minor gridlines. Use the keyword `gridcolor` to set both at once. -xlinewidth, ylinewidth, linewidth : color-spec, default: :rc:`meta.width` +xlinewidth, ylinewidth, linewidth : color-spec, default: [meta.width](https://ultraplot.readthedocs.io/en/stable/search.html?q=meta.width) Line width for the x and y axis spines and major ticks. Propagates to `tickwidth` unless specified otherwise. Use the keyword `linewidth` to set both at once. -xtickcolor, ytickcolor, tickcolor : color-spec, default: :rc:`tick.color` +xtickcolor, ytickcolor, tickcolor : color-spec, default: [tick.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.color) Color for the x and y axis ticks. Defaults are `xcolor`, `ycolor`, and `color` if they were passed. Use the keyword `tickcolor` to set both at once. -xticklen, yticklen, ticklen : unit-spec, default: :rc:`tick.len` +xticklen, yticklen, ticklen : unit-spec, default: [tick.len](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.len) Major tick lengths for the x and y axis. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Use the keyword `ticklen` to set both at once. -xticklenratio, yticklenratio, ticklenratio : float, default: :rc:`tick.lenratio` +xticklenratio, yticklenratio, ticklenratio : float, default: [tick.lenratio](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.lenratio) Relative scaling of `xticklen` and `yticklen` used to determine minor tick lengths. Use the keyword `ticklenratio` to set both at once. -xtickwidth, ytickwidth, tickwidth, : unit-spec, default: :rc:`tick.width` +xtickwidth, ytickwidth, tickwidth, : unit-spec, default: [tick.width](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.width) Major tick widths for the x ans y axis. Default is `linewidth` if it was passed. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Use the keyword `tickwidth` to set both at once. -xtickwidthratio, ytickwidthratio, tickwidthratio : float, default: :rc:`tick.widthratio` +xtickwidthratio, ytickwidthratio, tickwidthratio : float, default: [tick.widthratio](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.widthratio) Relative scaling of `xtickwidth` and `ytickwidth` used to determine minor tick widths. Use the keyword `tickwidthratio` to set both at once. -xticklabelpad, yticklabelpad, ticklabelpad : unit-spec, default: :rc:`tick.labelpad` +xticklabelpad, yticklabelpad, ticklabelpad : unit-spec, default: [tick.labelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.labelpad) The padding between the x and y axis ticks and tick labels. Use the keyword `ticklabelpad` to set both at once. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -xticklabelcolor, yticklabelcolor, ticklabelcolor : color-spec, default: :rc:`tick.labelcolor` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +xticklabelcolor, yticklabelcolor, ticklabelcolor : color-spec, default: [tick.labelcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.labelcolor) Color for the x and y tick labels. Defaults are `xcolor`, `ycolor`, and `color` if they were passed. Use the keyword `ticklabelcolor` to set both at once. -xticklabelsize, yticklabelsize, ticklabelsize : unit-spec or str, default: :rc:`tick.labelsize` +xticklabelsize, yticklabelsize, ticklabelsize : unit-spec or str, default: [tick.labelsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.labelsize) Font size for the x and y tick labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Use the keyword `ticklabelsize` to set both at once. -xticklabelweight, yticklabelweight, ticklabelweight : str, default: :rc:`tick.labelweight` +xticklabelweight, yticklabelweight, ticklabelweight : str, default: [tick.labelweight](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.labelweight) Font weight for the x and y tick labels. Use the keyword `ticklabelweight` to set both at once. -xlabelpad, ylabelpad : unit-spec, default: :rc:`label.pad` +xlabelpad, ylabelpad : unit-spec, default: [label.pad](https://ultraplot.readthedocs.io/en/stable/search.html?q=label.pad) The padding between the x and y axis bounding box and the x and y axis labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -xlabelcolor, ylabelcolor, labelcolor : color-spec, default: :rc:`label.color` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +xlabelcolor, ylabelcolor, labelcolor : color-spec, default: [label.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=label.color) Color for the x and y axis labels. Defaults are `xcolor`, `ycolor`, and `color` if they were passed. Use the keyword `labelcolor` to set both at once. -xlabelsize, ylabelsize, labelsize : unit-spec or str, default: :rc:`label.size` +xlabelsize, ylabelsize, labelsize : unit-spec or str, default: [label.size](https://ultraplot.readthedocs.io/en/stable/search.html?q=label.size) Font size for the x and y axis labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Use the keyword `labelsize` to set both at once. -xlabelweight, ylabelweight, labelweight : str, default: :rc:`label.weight` +xlabelweight, ylabelweight, labelweight : str, default: [label.weight](https://ultraplot.readthedocs.io/en/stable/search.html?q=label.weight) Font weight for the x and y axis labels. Use the keyword `labelweight` to set both at once. fixticks : bool, default: False - Whether to transform the tick locators to a `~matplotlib.ticker.FixedLocator`. + Whether to transform the tick locators to a [FixedLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.FixedLocator.html). If your axis ticks are doing weird things (for example, ticks are drawn outside of the axis spine) you can try setting this to ``True``. r0 : float, default: 0 @@ -967,13 +967,13 @@ thetagridcolor, rgridcolor, gridcolor : color-spec, optional Use the keyword `gridcolor` to set both at once. thetalocator, rlocator : locator-spec, optional Used to determine the azimuthal and radial gridline positions. - Passed to the `~ultraplot.constructor.Locator` constructor. Can be - float, list of float, string, or `matplotlib.ticker.Locator` instance. + Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. Can be + float, list of float, string, or [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) instance. thetalines, rlines Aliases for `thetalocator`, `rlocator`. thetalocator_kw, rlocator_kw : dict-like, optional The azimuthal and radial locator settings. Passed to - `~ultraplot.constructor.Locator`. + [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html). thetaminorlocator, rminorlocator : optional As for `thetalocator`, `rlocator`, but for the minor gridlines. thetaminorticks, rminorticks : optional @@ -986,16 +986,16 @@ rlabelpos : float, optional position. thetaformatter, rformatter : formatter-spec, optional Used to determine the azimuthal and radial label format. - Passed to the `~ultraplot.constructor.Formatter` constructor. - Can be string, list of string, or `matplotlib.ticker.Formatter` + Passed to the [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html) constructor. + Can be string, list of string, or [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) instance. Use ``[]``, ``'null'``, or ``'none'`` for no labels. thetalabels, rlabels : optional Aliases for `thetaformatter`, `rformatter`. thetaformatter_kw, rformatter_kw : dict-like, optional The azimuthal and radial label formatter settings. Passed to - `~ultraplot.constructor.Formatter`. + [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html). thetalabel, rlabel : str, optional - Polar-aware axis labels rendered via `~ultraplot.text.CurvedText`. + Polar-aware axis labels rendered via [CurvedText](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.text.CurvedText.html). ``thetalabel`` follows the outer arc just beyond ``r=rmax``. ``rlabel`` follows a radial spoke, centered between ``rmin`` and ``rmax``. On a full circle it uses ``get_rlabel_position()`` unless @@ -1016,40 +1016,40 @@ rlabelloc : {'right', 'left'}, default: 'right' (default) anchors to ``thetamin`` and ``'left'`` anchors to ``thetamax``; the label is then offset outward from the sector. thetalabel_kw, rlabel_kw : dict-like, optional - Additional `~ultraplot.text.CurvedText` settings for the polar-aware + Additional [CurvedText](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.text.CurvedText.html) settings for the polar-aware labels (e.g. ``border``, ``bbox``, or rendering hints like ``min_advance``). See also `labelpad`, `labelcolor`, `labelsize`, and `labelweight`. -color : color-spec, default: :rc:`meta.color` +color : color-spec, default: [meta.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=meta.color) Color for the axes edge. Propagates to `labelcolor` unless specified - otherwise (similar to :func:`~ultraplot.axes.CartesianAxes.format`). -labelcolor, gridlabelcolor : color-spec, default: `color` or :rc:`grid.labelcolor` + otherwise (similar to [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html#ultraplot.axes.CartesianAxes.format)). +labelcolor, gridlabelcolor : color-spec, default: `color` or [grid.labelcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelcolor) Color for the gridline labels. -labelpad, gridlabelpad : unit-spec, default: :rc:`grid.labelpad` +labelpad, gridlabelpad : unit-spec, default: [grid.labelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelpad) The padding between the axes edge and the radial and azimuthal labels. For ``thetalabel`` and ``rlabel``, this is added on top of the built-in tick-clearance offset. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -labelsize, gridlabelsize : unit-spec or str, default: :rc:`grid.labelsize` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +labelsize, gridlabelsize : unit-spec or str, default: [grid.labelsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelsize) Font size for the gridline labels. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -labelweight, gridlabelweight : str, default: :rc:`grid.labelweight` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +labelweight, gridlabelweight : str, default: [grid.labelweight](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelweight) Font weight for the gridline labels. aspect : {'auto', 'equal'} or float, optional The map aspect ratio. ``'auto'`` makes the map fill its subplot slot, which can be useful for aligning it with neighboring Cartesian axes but distorts - the projection. See :func:`~matplotlib.axes.Axes.set_aspect` for details. + the projection. See [set_aspect](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_aspect.html) for details. abcanchor : {'axes', 'slot'}, default: 'axes' The coordinate box used for the a-b-c label. ``'axes'`` attaches it to the visible map boundary. ``'slot'`` attaches it to the unadjusted GridSpec slot, keeping labels aligned with neighboring subplots when fixed map aspect leaves empty space inside a slot. -round : bool, default: :rc:`geo.round` +round : bool, default: [geo.round](https://ultraplot.readthedocs.io/en/stable/search.html?q=geo.round) *For polar cartopy axes only*. Whether to bound polar projections with circles rather than squares. Note that outer gridline labels cannot be added to circle-bounded polar projections. When basemap - is the backend this argument must be passed to `~ultraplot.constructor.Proj` instead. -extent : {'globe', 'auto'}, default: :rc:`geo.extent` + is the backend this argument must be passed to [Proj](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Proj.html) instead. +extent : {'globe', 'auto'}, default: [geo.extent](https://ultraplot.readthedocs.io/en/stable/search.html?q=geo.extent) *For cartopy axes only*. Whether to auto adjust the map bounds based on plotted content. If ``'globe'`` then non-polar projections are fixed with `~cartopy.mpl.geoaxes.GeoAxes.set_global`, @@ -1059,42 +1059,42 @@ lonlim, latlim : 2-tuple of float, optional *For cartopy axes only.* The approximate longitude and latitude boundaries of the map, applied with `~cartopy.mpl.geoaxes.GeoAxes.set_extent`. When basemap is the backend - this argument must be passed to `~ultraplot.constructor.Proj` instead. + this argument must be passed to [Proj](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Proj.html) instead. boundinglat : float, optional *For cartopy axes only.* The edge latitude for the circle bounding North Pole and South Pole-centered projections. When basemap is the backend this argument must be passed to - `~ultraplot.constructor.Proj` instead. -longrid, latgrid, grid : bool, default: :rc:`grid` + [Proj](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Proj.html) instead. +longrid, latgrid, grid : bool, default: [grid](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid) Whether to draw longitude and latitude gridlines. Use the keyword `grid` to toggle both at once. -longridminor, latgridminor, gridminor : bool, default: :rc:`gridminor` +longridminor, latgridminor, gridminor : bool, default: [gridminor](https://ultraplot.readthedocs.io/en/stable/search.html?q=gridminor) Whether to draw "minor" longitude and latitude lines. Use the keyword `gridminor` to toggle both at once. -lonticklen, latticklen, ticklen : unit-spec, default: :rc:`tick.len` +lonticklen, latticklen, ticklen : unit-spec, default: [tick.len](https://ultraplot.readthedocs.io/en/stable/search.html?q=tick.len) Major tick lengths for the longitudinal (x) and latitude (y) axis. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Use the keyword `ticklen` to set both at once. latmax : float, default: 80 The maximum absolute latitude for gridlines. Longitude gridlines are cut off poleward of this value (note this feature does not work in cartopy 0.18). -nsteps : int, default: :rc:`grid.nsteps` +nsteps : int, default: [grid.nsteps](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.nsteps) *For cartopy axes only.* The number of interpolation steps used to draw gridlines. lonlocator, latlocator : locator-spec, optional Used to determine the longitude and latitude gridline locations. Aliases: ``lonlines`` and ``latlines``, respectively. - Passed to the `~ultraplot.constructor.Locator` constructor. Can be - string, float, list of float, or `matplotlib.ticker.Locator` instance. + Passed to the [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor. Can be + string, float, list of float, or [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) instance. For basemap or cartopy < 0.18, the defaults are ``'deglon'`` and - ``'deglat'``, which correspond to the `~ultraplot.ticker.LongitudeLocator` - and `~ultraplot.ticker.LatitudeLocator` locators (adapted from cartopy). + ``'deglat'``, which correspond to the [LongitudeLocator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.LongitudeLocator.html) + and [LatitudeLocator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.LatitudeLocator.html) locators (adapted from cartopy). For cartopy >= 0.18, the defaults are ``'dmslon'`` and ``'dmslat'``, which uses the same locators with ``dms=True``. This selects gridlines at nice degree-minute-second intervals when the map extent is very small. lonlocator_kw, latlocator_kw : dict-like, optional - Keyword arguments passed to the `matplotlib.ticker.Locator` class. + Keyword arguments passed to the [matplotlib.ticker.Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) class. Aliases: ``lonlines_kw`` and ``latlines_kw``, respectively. lonminorlocator, latminorlocator : optional As with `lonlocator` and `latlocator` but for the "minor" gridlines. @@ -1102,7 +1102,7 @@ lonminorlocator, latminorlocator : optional lonminorlocator_kw, latminorlocator_kw : optional As with `lonlocator_kw`, and `latlocator_kw` but for the "minor" gridlines. Aliases: ``lonminorlines_kw`` and ``latminorlines_kw``, respectively. -lonlabels, latlabels, labels : str, bool, or sequence, :rc:`grid.labels` +lonlabels, latlabels, labels : str, bool, or sequence, [grid.labels](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labels) Whether to add non-inline longitude and latitude gridline labels, and on which sides of the map. Use the keyword `labels` to set both at once. The argument must conform to one of the following options: @@ -1121,14 +1121,14 @@ lonlabels, latlabels, labels : str, bool, or sequence, :rc:`grid.labels` and the ``(left, right)`` sides for latitudes. * A boolean 4-tuple indicating whether to draw labels on the ``(left, right, bottom, top)`` sides, as with the basemap - :func:`~mpl_toolkits.basemap.Basemap.drawmeridians` and - :func:`~mpl_toolkits.basemap.Basemap.drawparallels` `labels` keyword. + `drawmeridians` and + `drawparallels` `labels` keyword. -loninline, latinline, inlinelabels : bool, default: :rc:`grid.inlinelabels` +loninline, latinline, inlinelabels : bool, default: [grid.inlinelabels](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.inlinelabels) *For cartopy axes only.* Whether to add inline longitude and latitude gridline labels. Use the keyword `inlinelabels` to set both at once. -rotatelabels : bool, default: :rc:`grid.rotatelabels` +rotatelabels : bool, default: [grid.rotatelabels](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.rotatelabels) *For cartopy axes only.* Whether to rotate non-inline gridline labels so that they automatically follow the map boundary curvature. @@ -1141,11 +1141,11 @@ lonlabelrotation : float, optional latlabelrotation : float, optional The rotation angle in degrees for latitude tick labels. Works for both cartopy and basemap backends. -labelpad : unit-spec, default: :rc:`grid.labelpad` +labelpad : unit-spec, default: [grid.labelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelpad) *For cartopy axes only.* The padding between non-inline gridline labels and the map boundary. - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -dms : bool, default: :rc:`grid.dmslabels` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +dms : bool, default: [grid.dmslabels](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.dmslabels) *For cartopy axes only.* Whether the default locators and formatters should use "minutes" and "seconds" for gridline labels on small scales rather than decimal degrees. Setting this to @@ -1153,11 +1153,11 @@ dms : bool, default: :rc:`grid.dmslabels` and ``ax.format(lonformatter='deglon', latformatter='deglat')``. lonformatter, latformatter : formatter-spec, optional Formatter used to style longitude and latitude gridline labels. - Passed to the `~ultraplot.constructor.Formatter` constructor. Can be - string, list of string, or `matplotlib.ticker.Formatter` instance. + Passed to the [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html) constructor. Can be + string, list of string, or [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) instance. For basemap or cartopy < 0.18, the defaults are ``'deglon'`` and - ``'deglat'``, which correspond to `~ultraplot.ticker.SimpleFormatter` + ``'deglat'``, which correspond to [SimpleFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.SimpleFormatter.html) presets with degree symbols and cardinal direction suffixes. For cartopy >= 0.18, the defaults are ``'dmslon'`` and ``'dmslat'``, which uses cartopy's `~cartopy.mpl.ticker.LongitudeFormatter` and @@ -1165,46 +1165,46 @@ lonformatter, latformatter : formatter-spec, optional This formats gridlines that do not fall on whole degrees as "minutes" and "seconds" rather than decimal degrees. Use ``dms=False`` to disable this. lonformatter_kw, latformatter_kw : dict-like, optional - Keyword arguments passed to the `matplotlib.ticker.Formatter` class. + Keyword arguments passed to the [matplotlib.ticker.Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) class. land, ocean, coast, rivers, lakes, borders, innerborders : bool, optional Toggles various geographic features. These are actually the - :rcraw:`land`, :rcraw:`ocean`, :rcraw:`coast`, :rcraw:`rivers`, - :rcraw:`lakes`, :rcraw:`borders`, and :rcraw:`innerborders` - settings passed to `~ultraplot.config.Configurator.context`. + [land](https://ultraplot.readthedocs.io/en/stable/search.html?q=land), [ocean](https://ultraplot.readthedocs.io/en/stable/search.html?q=ocean), [coast](https://ultraplot.readthedocs.io/en/stable/search.html?q=coast), [rivers](https://ultraplot.readthedocs.io/en/stable/search.html?q=rivers), + [lakes](https://ultraplot.readthedocs.io/en/stable/search.html?q=lakes), [borders](https://ultraplot.readthedocs.io/en/stable/search.html?q=borders), and [innerborders](https://ultraplot.readthedocs.io/en/stable/search.html?q=innerborders) + settings passed to [context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context). The style can be modified using additional `rc` settings. - For example, to change :rcraw:`land.color`, use + For example, to change [land.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=land.color), use ``ax.format(landcolor='green')``, and to change - :rcraw:`land.zorder`, use ``ax.format(landzorder=4)``. + [land.zorder](https://ultraplot.readthedocs.io/en/stable/search.html?q=land.zorder), use ``ax.format(landzorder=4)``. reso : {'lo', 'med', 'hi', 'x-hi', 'xx-hi'}, optional *For cartopy axes only.* The resolution of geographic features. When basemap is the backend this - must be passed to `~ultraplot.constructor.Proj` instead. -color : color-spec, default: :rc:`meta.color` + must be passed to [Proj](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Proj.html) instead. +color : color-spec, default: [meta.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=meta.color) The color for the axes edge. Propagates to `labelcolor` unless specified - otherwise (similar to :func:`~ultraplot.axes.CartesianAxes.format`). -gridcolor : color-spec, default: :rc:`grid.color` + otherwise (similar to [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html#ultraplot.axes.CartesianAxes.format)). +gridcolor : color-spec, default: [grid.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.color) The color for the gridline labels. -labelcolor : color-spec, default: `color` or :rc:`grid.labelcolor` +labelcolor : color-spec, default: `color` or [grid.labelcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelcolor) The color for the gridline labels (`gridlabelcolor` is also allowed). -labelsize : unit-spec or str, default: :rc:`grid.labelsize` +labelsize : unit-spec or str, default: [grid.labelsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelsize) The font size for the gridline labels (`gridlabelsize` is also allowed). - If float, units are points. If string, interpreted by `~ultraplot.utils.units`. -labelweight : str, default: :rc:`grid.labelweight` + If float, units are points. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +labelweight : str, default: [grid.labelweight](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.labelweight) The font weight for the gridline labels (`gridlabelweight` is also allowed). rc_mode : int, optional - The context mode passed to `~ultraplot.config.Configurator.context`. + The context mode passed to [context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context). rc_kw : dict-like, optional An alternative to passing extra keyword arguments. See below. **kwargs - Keyword arguments that match the name of an `~ultraplot.config.rc` setting are - passed to `ultraplot.config.Configurator.context` and used to update the axes. + Keyword arguments that match the name of an [rc](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.rc.html) setting are + passed to [ultraplot.config.Configurator.context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context) and used to update the axes. If the setting name has "dots" you can simply omit the dots. For example, - ``abc='A.'`` modifies the :rcraw:`abc` setting, ``titleloc='left'`` modifies the - :rcraw:`title.loc` setting, ``gridminor=True`` modifies the :rcraw:`gridminor` - setting, and ``gridbelow=True`` modifies the :rcraw:`grid.below` setting. Many + ``abc='A.'`` modifies the [abc](https://ultraplot.readthedocs.io/en/stable/search.html?q=abc) setting, ``titleloc='left'`` modifies the + [title.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=title.loc) setting, ``gridminor=True`` modifies the [gridminor](https://ultraplot.readthedocs.io/en/stable/search.html?q=gridminor) + setting, and ``gridbelow=True`` modifies the [grid.below](https://ultraplot.readthedocs.io/en/stable/search.html?q=grid.below) setting. Many of the keyword arguments documented above are internally applied by retrieving - settings passed to `~ultraplot.config.Configurator.context`. + settings passed to [context](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.config.Configurator.html#ultraplot.config.Configurator.context). See also -------- @@ -1222,7 +1222,7 @@ ultraplot.config.Configurator.context""" @property def figure(self) -> Incomplete: - """The `ultraplot.figure.Figure` uniquely associated with this `SubplotGrid`. + """The [ultraplot.figure.Figure](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html) uniquely associated with this `SubplotGrid`. This is used with the `SubplotGrid.format` command. See also @@ -1234,7 +1234,7 @@ ultraplot.figure.Figure.subplotgrid""" @property def gridspec(self) -> Incomplete: - """The :class:`~ultraplot.gridspec.GridSpec` uniquely associated with this `SubplotGrid`. + """The [GridSpec](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.gridspec.GridSpec.html) uniquely associated with this `SubplotGrid`. This is used to resolve 2D indexing. See `~SubplotGrid.__getitem__` for details. See also @@ -1246,7 +1246,7 @@ ultraplot.gridspec.SubplotGrid.shape""" @property def shape(self) -> Incomplete: - """The shape of the :class:`~ultraplot.gridspec.GridSpec` associated with the grid. + """The shape of the [GridSpec](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.gridspec.GridSpec.html) associated with the grid. See `~SubplotGrid.__getitem__` for details. See also @@ -1274,14 +1274,14 @@ list """Add an axis locked to the same location with a distinct x axis for every axes in the grid. This is an alias and arguably more intuitive name for -`~ultraplot.axes.CartesianAxes.twiny`, which generates +[twiny](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html#ultraplot.axes.CartesianAxes.twiny), which generates two x axes with a shared ("twin") y axes. Parameters ---------- **kwargs - Passed to `~ultraplot.axes.CartesianAxes`. Supports all valid - `~ultraplot.axes.CartesianAxes.format` keywords. You can optionally + Passed to [CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html). Supports all valid + [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html#ultraplot.axes.CartesianAxes.format) keywords. You can optionally omit the x from keywords beginning with ``x`` -- for example ``ax.altx(lim=(0, 10))`` is equivalent to ``ax.altx(xlim=(0, 10))``. You can also change the default side for the axis spine, axis tick marks, @@ -1309,21 +1309,21 @@ This enforces the following default settings: def dualx(self, *args: Incomplete, **kwargs: Incomplete) -> 'SubplotGrid': """Add an axes locked to the same location whose x axis denotes equivalent coordinates in alternate units for every axes in the grid. -This is an alternative to `matplotlib.axes.Axes.secondary_xaxis` with +This is an alternative to [matplotlib.axes.Axes.secondary_xaxis](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.secondary_xaxis.html) with additional convenience features. Parameters ---------- funcscale : callable, 2-tuple of callables, or scale-spec The scale used to transform units from the parent axis to the secondary - axis. This can be a `~ultraplot.scale.FuncScale` itself or a function, + axis. This can be a [FuncScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.FuncScale.html) itself or a function, (function, function) tuple, or an axis scale specification interpreted - by the `~ultraplot.constructor.Scale` constructor function, any of which - will be used to build a `~ultraplot.scale.FuncScale` and applied - to the dual axis (see `~ultraplot.scale.FuncScale` for details). + by the [Scale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Scale.html) constructor function, any of which + will be used to build a [FuncScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.FuncScale.html) and applied + to the dual axis (see [FuncScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.FuncScale.html) for details). **kwargs - Passed to `~ultraplot.axes.CartesianAxes`. Supports all valid - `~ultraplot.axes.CartesianAxes.format` keywords. You can optionally + Passed to [CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html). Supports all valid + [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html#ultraplot.axes.CartesianAxes.format) keywords. You can optionally omit the x from keywords beginning with ``x`` -- for example ``ax.altx(lim=(0, 10))`` is equivalent to ``ax.altx(xlim=(0, 10))``. You can also change the default side for the axis spine, axis tick marks, @@ -1351,13 +1351,13 @@ This enforces the following default settings: def twinx(self, *args: Incomplete, **kwargs: Incomplete) -> 'SubplotGrid': """Add an axis locked to the same location with a distinct y axis for every axes in the grid. -This builds upon `matplotlib.axes.Axes.twinx`. +This builds upon [matplotlib.axes.Axes.twinx](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.twinx.html). Parameters ---------- **kwargs - Passed to `~ultraplot.axes.CartesianAxes`. Supports all valid - `~ultraplot.axes.CartesianAxes.format` keywords. You can optionally + Passed to [CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html). Supports all valid + [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html#ultraplot.axes.CartesianAxes.format) keywords. You can optionally omit the y from keywords beginning with ``y`` -- for example ``ax.alty(lim=(0, 10))`` is equivalent to ``ax.alty(ylim=(0, 10))``. You can also change the default side for the axis spine, axis tick marks, @@ -1386,14 +1386,14 @@ This enforces the following default settings: """Add an axis locked to the same location with a distinct y axis for every axes in the grid. This is an alias and arguably more intuitive name for -`~ultraplot.axes.CartesianAxes.twinx`, which generates +[twinx](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html#ultraplot.axes.CartesianAxes.twinx), which generates two y axes with a shared ("twin") x axes. Parameters ---------- **kwargs - Passed to `~ultraplot.axes.CartesianAxes`. Supports all valid - `~ultraplot.axes.CartesianAxes.format` keywords. You can optionally + Passed to [CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html). Supports all valid + [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html#ultraplot.axes.CartesianAxes.format) keywords. You can optionally omit the y from keywords beginning with ``y`` -- for example ``ax.alty(lim=(0, 10))`` is equivalent to ``ax.alty(ylim=(0, 10))``. You can also change the default side for the axis spine, axis tick marks, @@ -1421,21 +1421,21 @@ This enforces the following default settings: def dualy(self, *args: Incomplete, **kwargs: Incomplete) -> 'SubplotGrid': """Add an axes locked to the same location whose y axis denotes equivalent coordinates in alternate units for every axes in the grid. -This is an alternative to `matplotlib.axes.Axes.secondary_yaxis` with +This is an alternative to [matplotlib.axes.Axes.secondary_yaxis](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.secondary_yaxis.html) with additional convenience features. Parameters ---------- funcscale : callable, 2-tuple of callables, or scale-spec The scale used to transform units from the parent axis to the secondary - axis. This can be a `~ultraplot.scale.FuncScale` itself or a function, + axis. This can be a [FuncScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.FuncScale.html) itself or a function, (function, function) tuple, or an axis scale specification interpreted - by the `~ultraplot.constructor.Scale` constructor function, any of which - will be used to build a `~ultraplot.scale.FuncScale` and applied - to the dual axis (see `~ultraplot.scale.FuncScale` for details). + by the [Scale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Scale.html) constructor function, any of which + will be used to build a [FuncScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.FuncScale.html) and applied + to the dual axis (see [FuncScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.FuncScale.html) for details). **kwargs - Passed to `~ultraplot.axes.CartesianAxes`. Supports all valid - `~ultraplot.axes.CartesianAxes.format` keywords. You can optionally + Passed to [CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html). Supports all valid + [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html#ultraplot.axes.CartesianAxes.format) keywords. You can optionally omit the y from keywords beginning with ``y`` -- for example ``ax.alty(lim=(0, 10))`` is equivalent to ``ax.alty(ylim=(0, 10))``. You can also change the default side for the axis spine, axis tick marks, @@ -1463,13 +1463,13 @@ This enforces the following default settings: def twiny(self, *args: Incomplete, **kwargs: Incomplete) -> 'SubplotGrid': """Add an axis locked to the same location with a distinct x axis for every axes in the grid. -This builds upon `matplotlib.axes.Axes.twiny`. +This builds upon [matplotlib.axes.Axes.twiny](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.twiny.html). Parameters ---------- **kwargs - Passed to `~ultraplot.axes.CartesianAxes`. Supports all valid - `~ultraplot.axes.CartesianAxes.format` keywords. You can optionally + Passed to [CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html). Supports all valid + [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html#ultraplot.axes.CartesianAxes.format) keywords. You can optionally omit the x from keywords beginning with ``x`` -- for example ``ax.altx(lim=(0, 10))`` is equivalent to ``ax.altx(xlim=(0, 10))``. You can also change the default side for the axis spine, axis tick marks, @@ -1511,18 +1511,18 @@ side : str, optional top ``'top'``, ``'t'`` ========== ===================== -width : unit-spec, default: :rc:`subplots.panelwidth` +width : unit-spec, default: [subplots.panelwidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.panelwidth) The panel width. - If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + If float, units are inches. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). space : unit-spec, default: None The fixed space between the panel and the subplot edge. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. - When the :ref:`tight layout algorithm ` is active for the figure, + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). + When the [tight layout algorithm](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_tight) is active for the figure, `space` is computed automatically (see `pad`). Otherwise, `space` is set to a suitable default. -pad : unit-spec, default: :rc:`subplots.panelpad` - The :ref:`tight layout padding ` between the panel and the subplot. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. +pad : unit-spec, default: [subplots.panelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.panelpad) + The [tight layout padding](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_tight) between the panel and the subplot. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). row, rows Aliases for `span` for panels on the left or right side (vertical panels). col, cols @@ -1545,8 +1545,8 @@ share : bool, default: True Other parameters ----------------- **kwargs - Passed to `ultraplot.axes.CartesianAxes`. Supports all valid - `~ultraplot.axes.CartesianAxes.format` keywords. + Passed to [ultraplot.axes.CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html). Supports all valid + [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html#ultraplot.axes.CartesianAxes.format) keywords. Returns -------- @@ -1559,53 +1559,53 @@ ultraplot.axes.CartesianAxes def inset(self, *args: Incomplete, **kwargs: Incomplete) -> 'SubplotGrid': """Add an inset axes for every axes in the grid. -This is similar to `matplotlib.axes.Axes.inset_axes`. +This is similar to [matplotlib.axes.Axes.inset_axes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.inset_axes.html). Parameters ----------- bounds : 4-tuple of float or (4-tuple, transform) The (left, bottom, width, height) coordinates for the axes. To specify the coordinate system alongside the coordinates, pass ``(bounds, transform)``. -transform : {'data', 'axes', 'figure', 'subfigure'} or `~matplotlib.transforms.Transform`, optional +transform : {'data', 'axes', 'figure', 'subfigure'} or [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html), optional The transform used to interpret the bounds. Can be a - :class:`~matplotlib.transforms.Transform` instance or a string representing - the :class:`~matplotlib.axes.Axes.transData`, :class:`~matplotlib.axes.Axes.transAxes`, - :class:`~matplotlib.figure.Figure.transFigure`, or - :class:`~matplotlib.figure.Figure.transSubfigure`, transforms. + [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html) instance or a string representing + the [transData](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.transData.html), [transAxes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.transAxes.html), + [transFigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.transFigure.html), or + [transSubfigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.transSubfigure.html), transforms. Default is to use the same projection as the current axes. proj, projection : -str, :class:`cartopy.crs.Projection`, or :class:`~mpl_toolkits.basemap.Basemap`, optional +str, `cartopy.crs.Projection`, or `Basemap`, optional The map projection specification(s). If ``'cart'`` or ``'cartesian'`` - (the default), a :class:`~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, - a :class:`~ultraplot.axes.PolarAxes` is created. Otherwise, the argument is - interpreted by :class:`~ultraplot.constructor.Proj`, and the result is used - to make a :class:`~ultraplot.axes.GeoAxes` (in this case the argument can be - a :class:`cartopy.crs.Projection` instance, a :class:`~mpl_toolkits.basemap.Basemap` - instance, or a projection name listed in :ref:`this table `). + (the default), a [CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html) is created. If ``'polar'``, + a [PolarAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PolarAxes.html) is created. Otherwise, the argument is + interpreted by [Proj](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Proj.html), and the result is used + to make a [GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.GeoAxes.html) (in this case the argument can be + a `cartopy.crs.Projection` instance, a `Basemap` + instance, or a projection name listed in [this table](https://ultraplot.readthedocs.io/en/stable/search.html?q=proj_table)). proj_kw, projection_kw : dict-like, optional - Keyword arguments passed to :class:`~mpl_toolkits.basemap.Basemap` or - :class:`~cartopy.crs.Projection` classes on instantiation. -backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` - Whether to use :class:`~mpl_toolkits.basemap.Basemap` or - :class:`~cartopy.crs.Projection` for map projections. + Keyword arguments passed to `Basemap` or + `Projection` classes on instantiation. +backend : {'cartopy', 'basemap'}, default: [geo.backend](https://ultraplot.readthedocs.io/en/stable/search.html?q=geo.backend) + Whether to use `Basemap` or + `Projection` for map projections. .. deprecated:: 3.0.0 The ``'basemap'`` backend is deprecated and may be removed in a future release. Please use the ``'cartopy'`` backend instead. zorder : float, default: 4 - The `zorder `__ + The [zorder](https://matplotlib.org/stable/gallery/misc/zorder_demo.html) of the axes. Should be greater than the zorder of elements in the parent axes. zoom : bool, default: True or False Whether to draw lines indicating the inset zoom using `~Axes.indicate_inset_zoom`. The line positions will automatically adjust when the parent or inset axes limits - change. Default is ``True`` only if both axes are `~ultraplot.axes.CartesianAxes`. + change. Default is ``True`` only if both axes are [CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html). zoom_kw : dict, optional Passed to `~Axes.indicate_inset_zoom`. Other parameters ----------------- **kwargs - Passed to `ultraplot.axes.Axes`. + Passed to [ultraplot.axes.Axes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html). Returns -------- diff --git a/ultraplot/internals/__init__.pyi b/ultraplot/internals/__init__.pyi index 78c0f97d9..52398bd27 100644 --- a/ultraplot/internals/__init__.pyi +++ b/ultraplot/internals/__init__.pyi @@ -24,13 +24,13 @@ def _pop_rc(src: Incomplete, *, ignore_conflicts: Incomplete=True) -> Incomplete def _translate_loc(loc: Incomplete, mode: Incomplete, *, default: Incomplete=None, **kwargs: Incomplete) -> Incomplete: """Translate the location string `loc` into a standardized form. The `mode` -must be a string for which there is a :rcraw:`mode.loc` setting. Additional +must be a string for which there is a [mode.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=mode.loc) setting. Additional options can be added with keyword arguments.""" ... def _translate_grid(b: Incomplete, key: Incomplete) -> Incomplete: """Translate an instruction to turn either major or minor gridlines on or off into a -boolean and string applied to :rcraw:`axes.grid` and :rcraw:`axes.grid.which`.""" +boolean and string applied to [axes.grid](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.grid) and [axes.grid.which](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.grid.which).""" ... def _resolve_lazy(name: Incomplete) -> Incomplete: diff --git a/ultraplot/internals/fonts.pyi b/ultraplot/internals/fonts.pyi index 675433009..11c3564e2 100644 --- a/ultraplot/internals/fonts.pyi +++ b/ultraplot/internals/fonts.pyi @@ -24,16 +24,16 @@ def _clear_math_parse_cache() -> None: ... class _UnicodeFonts(UnicodeFonts): - """A simple `~matplotlib._mathtext.UnicodeFonts` subclass that + """A simple [UnicodeFonts](https://matplotlib.org/stable/api/_as_gen/matplotlib._mathtext.UnicodeFonts.html) subclass that interprets ``rc['mathtext.default'] != 'regular'`` in the presence of ``rc['mathtext.fontset'] == 'custom'`` as possibly modifying the active font. Works by permitting the ``rc['mathtext.rm']``, ``rc['mathtext.it']``, etc. settings to have the dummy value ``'regular'`` instead of a valid family name, e.g. ``rc['mathtext.it'] == 'regular:italic'`` (permitted through an -override of the `~matplotlib.rcsetup.validate_font_properties` validator). +override of the [validate_font_properties](https://matplotlib.org/stable/api/_as_gen/matplotlib.rcsetup.validate_font_properties.html) validator). When this dummy value is detected then the font properties passed to -`~matplotlib._mathtext.TrueTypeFont` are taken by replacing ``'regular'`` +[TrueTypeFont](https://matplotlib.org/stable/api/_as_gen/matplotlib._mathtext.TrueTypeFont.html) are taken by replacing ``'regular'`` in the "math" fontset with the active font name.""" def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: diff --git a/ultraplot/internals/inputs.pyi b/ultraplot/internals/inputs.pyi index 40cf8ff5c..c8b3e26e6 100644 --- a/ultraplot/internals/inputs.pyi +++ b/ultraplot/internals/inputs.pyi @@ -86,8 +86,8 @@ subset of the weights. Used to sanitize input for `_dist_kde`.""" def _dist_kde(distribution: Incomplete, *, coords: Incomplete=None, points: Incomplete=None, margin: Incomplete=0.0, bw_method: Incomplete=None, weights: Incomplete=None) -> Incomplete: """Return the coordinates and gaussian kernel density estimate of the input distribution. This is the single entry point for the kernel density -estimates drawn by `~ultraplot.axes.PlotAxes.hist` and -`~ultraplot.axes.PlotAxes.ridgeline`. +estimates drawn by [hist](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PlotAxes.html#ultraplot.axes.PlotAxes.hist) and +[ridgeline](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PlotAxes.html#ultraplot.axes.PlotAxes.ridgeline). Parameters ---------- @@ -96,17 +96,17 @@ distribution : array-like coords : array-like, optional The coordinates to evaluate the estimate on. If ``None`` an evenly spaced grid is built from the data range (see `points` and `margin`). -points : int, default: :rc:`kde.points` +points : int, default: [kde.points](https://ultraplot.readthedocs.io/en/stable/search.html?q=kde.points) The number of evenly spaced evaluation coordinates. Larger values give smoother curves at the cost of speed. Ignored if `coords` was passed. margin : float, default: 0 The fraction of the data range used to pad either side of the evaluation grid. Ignored if `coords` was passed. bw_method : str, float, or callable, optional - The bandwidth selector passed to `scipy.stats.gaussian_kde`. Can be + The bandwidth selector passed to [scipy.stats.gaussian_kde](https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.gaussian_kde.html). Can be ``'scott'``, ``'silverman'``, a scalar, or a callable. weights : array-like, optional - The per-sample weights passed to `scipy.stats.gaussian_kde`. + The per-sample weights passed to [scipy.stats.gaussian_kde](https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.gaussian_kde.html). Returns ------- @@ -158,8 +158,8 @@ Include units in the title if `include_units` is ``True``.""" ... def _meta_units(data: Incomplete) -> Incomplete: - """Get the unit string from the `xarray.DataArray` attributes or the -`pint.Quantity`. Format the latter with :rcraw:`unitformat`.""" + """Get the unit string from the [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) attributes or the +[pint.Quantity](https://pint.readthedocs.io/en/stable/search.html?q=pint.Quantity). Format the latter with [unitformat](https://ultraplot.readthedocs.io/en/stable/search.html?q=unitformat).""" ... def _geo_basemap_1d(x: Incomplete, *ys: Incomplete, xmin: Incomplete=-180, xmax: Incomplete=180) -> Incomplete: diff --git a/ultraplot/legend.pyi b/ultraplot/legend.pyi index 62fd8164d..7229b7cf9 100644 --- a/ultraplot/legend.pyi +++ b/ultraplot/legend.pyi @@ -48,7 +48,7 @@ def _wedge_legend_patch(legend: Incomplete, orig_handle: Incomplete, xdescent: I class LegendEntry(mlines.Line2D): """Convenience artist for custom legend entries. -This is a lightweight wrapper around `matplotlib.lines.Line2D` that +This is a lightweight wrapper around [matplotlib.lines.Line2D](https://matplotlib.org/stable/api/_as_gen/matplotlib.lines.Line2D.html) that initializes with empty data so it can be passed directly to `Axes.legend()` or `Figure.legend()` handles.""" @@ -63,28 +63,28 @@ Properties: alpha: float or None animated: bool antialiased or aa: bool - clip_box: `~matplotlib.transforms.BboxBase` or None + clip_box: [BboxBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.BboxBase.html) or None clip_on: bool clip_path: Patch or (Path, Transform) or None - color or c: :mpltype:`color` + color or c: [color](https://matplotlib.org/stable/search.html?q=color) dash_capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} dash_joinstyle: `.JoinStyle` or {'miter', 'round', 'bevel'} dashes: sequence of floats (on/off ink in points) or (None, None) data: (2, N) array or two 1D arrays drawstyle or ds: {'default', 'steps', 'steps-pre', 'steps-mid', 'steps-post'}, default: 'default' - figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + figure: [Figure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html) or [SubFigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.SubFigure.html) fillstyle: {'full', 'left', 'right', 'bottom', 'top', 'none'} - gapcolor: :mpltype:`color` or None + gapcolor: [color](https://matplotlib.org/stable/search.html?q=color) or None gid: str in_layout: bool label: object linestyle or ls: {'-', '--', '-.', ':', '', (offset, on-off-seq), ...} linewidth or lw: float marker: marker style string, `~.path.Path` or `~.markers.MarkerStyle` - markeredgecolor or mec: :mpltype:`color` + markeredgecolor or mec: [color](https://matplotlib.org/stable/search.html?q=color) markeredgewidth or mew: float - markerfacecolor or mfc: :mpltype:`color` - markerfacecoloralt or mfcalt: :mpltype:`color` + markerfacecolor or mfc: [color](https://matplotlib.org/stable/search.html?q=color) + markerfacecoloralt or mfcalt: [color](https://matplotlib.org/stable/search.html?q=color) markersize or ms: float markevery: None or int or (int, int) or slice or list[int] or float or (float, float) or list[bool] mouseover: bool @@ -103,9 +103,9 @@ Properties: ydata: 1D array zorder: float -See :meth:`set_linestyle` for a description of the line styles, -:meth:`set_marker` for a description of the markers, and -:meth:`set_drawstyle` for a description of the draw styles.""" +See `set_linestyle` for a description of the line styles, +`set_marker` for a description of the markers, and +`set_drawstyle` for a description of the draw styles.""" ... @classmethod @@ -126,9 +126,9 @@ class _Line2DLegendHandler(mhandler.HandlerLine2D): Parameters ---------- -legend : `~matplotlib.legend.Legend` +legend : [Legend](https://matplotlib.org/stable/api/_as_gen/matplotlib.legend.Legend.html) The legend for which these legend artists are being created. -orig_handle : `~matplotlib.artist.Artist` or similar +orig_handle : [Artist](https://matplotlib.org/stable/api/_as_gen/matplotlib.artist.Artist.html) or similar The object for which these legend artists are being created. xdescent, ydescent, width, height : int The rectangle (*xdescent*, *ydescent*, *width*, *height*) that the @@ -136,7 +136,7 @@ xdescent, ydescent, width, height : int fontsize : int The fontsize in pixels. The legend artists being created should be scaled according to the given fontsize. -trans : `~matplotlib.transforms.Transform` +trans : [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html) The transform that is applied to the legend artists being created. Typically from unit coordinates in the handler box to screen coordinates.""" @@ -303,7 +303,7 @@ Parameters ---------- geometry Geometry shorthand (e.g. ``'triangle'`` or ``'country:AU'``), - shapely geometry, or `matplotlib.path.Path`.""" + shapely geometry, or [matplotlib.path.Path](https://matplotlib.org/stable/api/_as_gen/matplotlib.path.Path.html).""" def __init__(self, geometry: Any='square', *, country_reso: str='110m', country_territories: bool=False, country_proj: Any=None, label: Optional[str]=None, facecolor: Any='none', edgecolor: Any='0.25', linewidth: float=1.0, joinstyle: str=_DEFAULT_GEO_JOINSTYLE, alpha: Optional[float]=None, fill: Optional[bool]=None, **kwargs: Any) -> None: """*path* is a `.Path` object. @@ -316,13 +316,13 @@ Properties: animated: bool antialiased or aa: bool or None capstyle: `.CapStyle` or {'butt', 'projecting', 'round'} - clip_box: `~matplotlib.transforms.BboxBase` or None + clip_box: [BboxBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.BboxBase.html) or None clip_on: bool clip_path: Patch or (Path, Transform) or None - color: :mpltype:`color` - edgecolor or ec: :mpltype:`color` or None - facecolor or fc: :mpltype:`color` or None - figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + color: [color](https://matplotlib.org/stable/search.html?q=color) + edgecolor or ec: [color](https://matplotlib.org/stable/search.html?q=color) or None + facecolor or fc: [color](https://matplotlib.org/stable/search.html?q=color) or None + figure: [Figure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html) or [SubFigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.SubFigure.html) fill: bool gid: str hatch: {'/', '\\\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'} @@ -338,7 +338,7 @@ Properties: rasterized: bool sketch_params: (scale: float, length: float, randomness: float) snap: bool or None - transform: `~matplotlib.transforms.Transform` + transform: [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html) url: str visible: bool zorder: float""" @@ -521,7 +521,7 @@ class Legend(mlegend.Legend): def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: """Parameters ---------- -parent : `~matplotlib.axes.Axes` or `.Figure` +parent : [Axes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html) or `.Figure` The artist that contains the legend. handles : list of (`.Artist` or tuple of `.Artist`) @@ -535,7 +535,7 @@ labels : list of str Other Parameters ---------------- -loc : str or pair of floats, default: :rc:`legend.loc` for Axes, 'upper right' for Figure +loc : str or pair of floats, default: [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) for Axes, 'upper right' for Figure The location of the legend. The strings ``'upper left'``, ``'upper right'``, ``'lower left'``, @@ -585,7 +585,7 @@ loc : str or pair of floats, default: :rc:`legend.loc` for Axes, 'upper right' f right side of the layout. In addition to the values of *loc* listed above, we have 'outside right upper', 'outside right lower', 'outside left upper', and 'outside left lower'. See - :ref:`legend_guide` for more details. + [legend_guide](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend_guide) for more details. bbox_to_anchor : `.BboxBase`, 2-tuple, or 4-tuple of floats Box that is used to position the legend in conjunction with *loc*. @@ -616,29 +616,29 @@ ncols : int, default: 1 For backward compatibility, the spelling *ncol* is also supported but it is discouraged. If both are given, *ncols* takes precedence. -prop : None or `~matplotlib.font_manager.FontProperties` or dict +prop : None or [FontProperties](https://matplotlib.org/stable/api/_as_gen/matplotlib.font_manager.FontProperties.html) or dict The font properties of the legend. If None (default), the current - :data:`matplotlib.rcParams` will be used. + [matplotlib.rcParams](https://matplotlib.org/stable/api/_as_gen/matplotlib.rcParams.html) will be used. fontsize : int or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'} The font size of the legend. If the value is numeric the size will be the absolute font size in points. String values are relative to the current default font size. This argument is only used if *prop* is not specified. -labelcolor : str or list, default: :rc:`legend.labelcolor` +labelcolor : str or list, default: [legend.labelcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.labelcolor) The color of the text in the legend. Either a valid color string (for example, 'red'), or a list of color strings. The labelcolor can also be made to match the color of the line or marker using 'linecolor', 'markerfacecolor' (or 'mfc'), or 'markeredgecolor' (or 'mec'). - Labelcolor can be set globally using :rc:`legend.labelcolor`. If None, - use :rc:`text.color`. + Labelcolor can be set globally using [legend.labelcolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.labelcolor). If None, + use [text.color](https://ultraplot.readthedocs.io/en/stable/search.html?q=text.color). -numpoints : int, default: :rc:`legend.numpoints` +numpoints : int, default: [legend.numpoints](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.numpoints) The number of marker points in the legend when creating a legend entry for a `.Line2D` (line). -scatterpoints : int, default: :rc:`legend.scatterpoints` +scatterpoints : int, default: [legend.scatterpoints](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.scatterpoints) The number of marker points in the legend when creating a legend entry for a `.PathCollection` (scatter plot). @@ -648,7 +648,7 @@ scatteryoffsets : iterable of floats, default: ``[0.375, 0.5, 0.3125]`` legend text, and 1.0 is at the top. To draw all markers at the same height, set to ``[0.5]``. -markerscale : float, default: :rc:`legend.markerscale` +markerscale : float, default: [legend.markerscale](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.markerscale) The relative size of legend markers compared to the originally drawn ones. markerfirst : bool, default: True @@ -661,50 +661,50 @@ reverse : bool, default: False .. versionadded:: 3.7 -frameon : bool, default: :rc:`legend.frameon` +frameon : bool, default: [legend.frameon](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.frameon) Whether the legend should be drawn on a patch (frame). -fancybox : bool, default: :rc:`legend.fancybox` +fancybox : bool, default: [legend.fancybox](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.fancybox) Whether round edges should be enabled around the `.FancyBboxPatch` which makes up the legend's background. -shadow : None, bool or dict, default: :rc:`legend.shadow` +shadow : None, bool or dict, default: [legend.shadow](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.shadow) Whether to draw a shadow behind the legend. The shadow can be configured using `.Patch` keywords. - Customization via :rc:`legend.shadow` is currently not supported. + Customization via [legend.shadow](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.shadow) is currently not supported. -framealpha : float, default: :rc:`legend.framealpha` +framealpha : float, default: [legend.framealpha](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.framealpha) The alpha transparency of the legend's background. If *shadow* is activated and *framealpha* is ``None``, the default value is ignored. -facecolor : "inherit" or color, default: :rc:`legend.facecolor` +facecolor : "inherit" or color, default: [legend.facecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.facecolor) The legend's background color. - If ``"inherit"``, use :rc:`axes.facecolor`. + If ``"inherit"``, use [axes.facecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.facecolor). -edgecolor : "inherit" or color, default: :rc:`legend.edgecolor` +edgecolor : "inherit" or color, default: [legend.edgecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.edgecolor) The legend's background patch edge color. - If ``"inherit"``, use :rc:`axes.edgecolor`. + If ``"inherit"``, use [axes.edgecolor](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.edgecolor). mode : {"expand", None} If *mode* is set to ``"expand"`` the legend will be horizontally expanded to fill the Axes area (or *bbox_to_anchor* if defines the legend's size). -bbox_transform : None or `~matplotlib.transforms.Transform` +bbox_transform : None or [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html) The transform for the bounding box (*bbox_to_anchor*). For a value of ``None`` (default) the Axes' - :data:`~matplotlib.axes.Axes.transAxes` transform will be used. + [transAxes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.transAxes.html) transform will be used. title : str or None The legend's title. Default is no title (``None``). -title_fontproperties : None or `~matplotlib.font_manager.FontProperties` or dict +title_fontproperties : None or [FontProperties](https://matplotlib.org/stable/api/_as_gen/matplotlib.font_manager.FontProperties.html) or dict The font properties of the legend's title. If None (default), the *title_fontsize* argument will be used if present; if *title_fontsize* is - also None, the current :rc:`legend.title_fontsize` will be used. + also None, the current [legend.title_fontsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.title_fontsize) will be used. -title_fontsize : int or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}, default: :rc:`legend.title_fontsize` +title_fontsize : int or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}, default: [legend.title_fontsize](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.title_fontsize) The font size of the legend's title. Note: This cannot be combined with *title_fontproperties*. If you want to set the fontsize alongside other font properties, use the *size* @@ -714,31 +714,31 @@ alignment : {'center', 'left', 'right'}, default: 'center' The alignment of the legend title and the box of entries. The entries are aligned as a single block, so that markers always lined up. -borderpad : float, default: :rc:`legend.borderpad` +borderpad : float, default: [legend.borderpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.borderpad) The fractional whitespace inside the legend border, in font-size units. -labelspacing : float, default: :rc:`legend.labelspacing` +labelspacing : float, default: [legend.labelspacing](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.labelspacing) The vertical space between the legend entries, in font-size units. -handlelength : float, default: :rc:`legend.handlelength` +handlelength : float, default: [legend.handlelength](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.handlelength) The length of the legend handles, in font-size units. -handleheight : float, default: :rc:`legend.handleheight` +handleheight : float, default: [legend.handleheight](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.handleheight) The height of the legend handles, in font-size units. -handletextpad : float, default: :rc:`legend.handletextpad` +handletextpad : float, default: [legend.handletextpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.handletextpad) The pad between the legend handle and text, in font-size units. -borderaxespad : float, default: :rc:`legend.borderaxespad` +borderaxespad : float, default: [legend.borderaxespad](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.borderaxespad) The pad between the Axes and legend border, in font-size units. -columnspacing : float, default: :rc:`legend.columnspacing` +columnspacing : float, default: [legend.columnspacing](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.columnspacing) The spacing between columns, in font-size units. handler_map : dict or None The custom dictionary mapping instances or types to a legend handler. This *handler_map* updates the default handler map - found at `matplotlib.legend.Legend.get_legend_handler_map`. + found at [matplotlib.legend.Legend.get_legend_handler_map](https://matplotlib.org/stable/api/_as_gen/matplotlib.legend.Legend.get_legend_handler_map.html). draggable : bool, default: False Whether the legend can be dragged with the mouse. @@ -766,7 +766,7 @@ legend_handles Parameters ---------- -loc : str or pair of floats, default: :rc:`legend.loc` for Axes, 'upper right' for Figure +loc : str or pair of floats, default: [legend.loc](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend.loc) for Axes, 'upper right' for Figure The location of the legend. The strings ``'upper left'``, ``'upper right'``, ``'lower left'``, @@ -816,7 +816,7 @@ loc : str or pair of floats, default: :rc:`legend.loc` for Axes, 'upper right' f right side of the layout. In addition to the values of *loc* listed above, we have 'outside right upper', 'outside right lower', 'outside left upper', and 'outside left lower'. See - :ref:`legend_guide` for more details.""" + [legend_guide](https://ultraplot.readthedocs.io/en/stable/search.html?q=legend_guide) for more details.""" ... def remove(self) -> None: @@ -850,27 +850,27 @@ class UltraLegend: def entrylegend(self, entries: Iterable[Any] | Mapping[Any, Any], *, line: Optional[bool]=None, marker: Incomplete=None, color: Incomplete=None, handle_kw: Optional[dict[str, Any]]=None, add: bool=True, **kwargs: Any) -> Incomplete: """Build generic semantic legend entries and optionally draw a legend. -Public docs live on :meth:`Axes.entrylegend`.""" +Public docs live on `Axes.entrylegend`.""" ... def catlegend(self, categories: Iterable[Any], *, color: Incomplete=None, marker: Incomplete=None, line: Optional[bool]=None, handle_kw: Optional[dict[str, Any]]=None, add: bool=True, **kwargs: Any) -> Incomplete: """Build categorical legend entries and optionally draw a legend. -Public docs live on :meth:`Axes.catlegend`.""" +Public docs live on `Axes.catlegend`.""" ... def sizelegend(self, levels: Iterable[float], *, labels: Incomplete=None, color: Incomplete=None, marker: Incomplete=None, area: Optional[bool]=None, values: Incomplete=None, vmin: Optional[float]=None, vmax: Optional[float]=None, smin: Optional[float]=None, smax: Optional[float]=None, area_size: Optional[bool]=None, absolute_size: Optional[bool]=None, scale: Optional[float]=None, minsize: Optional[float]=None, fmt: Incomplete=None, handle_kw: Optional[dict[str, Any]]=None, add: bool=True, **kwargs: Any) -> Incomplete: """Build size legend entries and optionally draw a legend. -Public docs live on :meth:`Axes.sizelegend`.""" +Public docs live on `Axes.sizelegend`.""" ... def numlegend(self, levels: Incomplete=None, *, vmin: Incomplete=None, vmax: Incomplete=None, n: Optional[int]=None, cmap: Incomplete=None, norm: Incomplete=None, fmt: Incomplete=None, facecolor: Incomplete=None, edgecolor: Incomplete=None, linewidth: Optional[float]=None, linestyle: Incomplete=None, alpha: Incomplete=None, handle_kw: Optional[dict[str, Any]]=None, add: bool=True, **kwargs: Any) -> Incomplete: """Build numeric-color legend entries and optionally draw a legend. -Public docs live on :meth:`Axes.numlegend`.""" +Public docs live on `Axes.numlegend`.""" ... def geolegend(self, entries: Iterable[Any] | dict[Any, Any], labels: Optional[Iterable[Any]]=None, *, country_reso: Optional[str]=None, country_territories: Optional[bool]=None, country_proj: Any=None, handlesize: Optional[float]=None, facecolor: Any=None, edgecolor: Any=None, linewidth: Optional[float]=None, alpha: Optional[float]=None, fill: Optional[bool]=None, handle_kw: Optional[dict[str, Any]]=None, add: bool=True, **kwargs: Any) -> Incomplete: """Build geometry legend entries and optionally draw a legend. -Public docs live on :meth:`Axes.geolegend`.""" +Public docs live on `Axes.geolegend`.""" ... @staticmethod diff --git a/ultraplot/proj.pyi b/ultraplot/proj.pyi index a3024adce..6f83b4d9c 100644 --- a/ultraplot/proj.pyi +++ b/ultraplot/proj.pyi @@ -17,7 +17,7 @@ _reso_docstring = ... _init_docstring = ... class Aitoff(_WarpedRectangularProjection): - """The `Aitoff `__ projection.""" + """The [Aitoff](https://en.wikipedia.org/wiki/Aitoff_projection) projection.""" name = 'aitoff' def __init__(self, central_longitude: Incomplete=0, globe: Incomplete=None, false_easting: Incomplete=None, false_northing: Incomplete=None) -> None: @@ -39,7 +39,7 @@ globe : `~cartopy.crs.Globe`, optional ... class Hammer(_WarpedRectangularProjection): - """The `Hammer `__ projection.""" + """The [Hammer](https://en.wikipedia.org/wiki/Hammer_projection) projection.""" name = 'hammer' def __init__(self, central_longitude: Incomplete=0, globe: Incomplete=None, false_easting: Incomplete=None, false_northing: Incomplete=None) -> None: @@ -61,7 +61,7 @@ globe : `~cartopy.crs.Globe`, optional ... class KavrayskiyVII(_WarpedRectangularProjection): - """The `Kavrayskiy VII `__ projection.""" + """The [Kavrayskiy VII](https://en.wikipedia.org/wiki/Kavrayskiy_VII_projection) projection.""" name = 'kavrayskiyVII' def __init__(self, central_longitude: Incomplete=0, globe: Incomplete=None, false_easting: Incomplete=None, false_northing: Incomplete=None) -> None: @@ -83,7 +83,7 @@ globe : `~cartopy.crs.Globe`, optional ... class WinkelTripel(_WarpedRectangularProjection): - """The `Winkel tripel (Winkel III) `__ projection.""" + """The [Winkel tripel (Winkel III)](https://en.wikipedia.org/wiki/Winkel_tripel_projection) projection.""" name = 'winkeltripel' def __init__(self, central_longitude: Incomplete=0, globe: Incomplete=None, false_easting: Incomplete=None, false_northing: Incomplete=None) -> None: diff --git a/ultraplot/scale.pyi b/ultraplot/scale.pyi index c079b8a27..9268a0723 100644 --- a/ultraplot/scale.pyi +++ b/ultraplot/scale.pyi @@ -1,7 +1,7 @@ # @generated by tools/generate_stubs.py; do not edit # fmt: off """ -Various axis `~matplotlib.scale.ScaleBase` classes. +Various axis [ScaleBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.ScaleBase.html) classes. """ from _typeshed import Incomplete import copy @@ -22,10 +22,10 @@ change the default `linthresh` to ``1``.""" class _Scale(object): """Mix-in class that standardizes the behavior of -`~matplotlib.scale.ScaleBase.set_default_locators_and_formatters` -and `~matplotlib.scale.ScaleBase.get_transform`. Also overrides +[set_default_locators_and_formatters](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.ScaleBase.set_default_locators_and_formatters.html) +and [get_transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.ScaleBase.get_transform.html). Also overrides `__init__` so you no longer have to instantiate scales with an -`~matplotlib.axis.Axis` instance.""" +[Axis](https://matplotlib.org/stable/api/_as_gen/matplotlib.axis.Axis.html) instance.""" def __init__(self, *args: Incomplete, **kwargs: Incomplete) -> None: ... @@ -36,7 +36,7 @@ initialization and define defaults for all scales. Parameters ---------- -axis : `~matplotlib.axis.Axis` +axis : [Axis](https://matplotlib.org/stable/api/_as_gen/matplotlib.axis.Axis.html) The axis. only_if_default : bool, optional Whether to refrain from updating the locators and formatters if the @@ -49,8 +49,8 @@ only_if_default : bool, optional ... class LinearScale(_Scale, mscale.LinearScale): - """As with `~matplotlib.scale.LinearScale` but with -`~ultraplot.ticker.AutoFormatter` as the default major formatter.""" + """As with [LinearScale](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.LinearScale.html) but with +[AutoFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.AutoFormatter.html) as the default major formatter.""" name = 'linear' def __init__(self, **kwargs: Incomplete) -> None: @@ -60,7 +60,7 @@ ultraplot.constructor.Scale""" ... class LogitScale(_Scale, mscale.LogitScale): - """As with `~matplotlib.scale.LogitScale` but with `~ultraplot.ticker.AutoFormatter` + """As with [LogitScale](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.LogitScale.html) but with [AutoFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.AutoFormatter.html) as the default major formatter.""" name = 'logit' @@ -77,7 +77,7 @@ ultraplot.constructor.Scale""" ... class LogScale(_Scale, mscale.LogScale): - """As with `~matplotlib.scale.LogScale` but with `~ultraplot.ticker.AutoFormatter` + """As with [LogScale](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.LogScale.html) but with [AutoFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.AutoFormatter.html) as the default major formatter. `x` and `y` versions of each keyword argument are no longer required.""" name = 'log' @@ -104,8 +104,8 @@ ultraplot.constructor.Scale""" ... class SymmetricalLogScale(_Scale, mscale.SymmetricalLogScale): - """As with `~matplotlib.scale.SymmetricalLogScale` but with -`~ultraplot.ticker.AutoFormatter` as the default major formatter. + """As with [SymmetricalLogScale](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.SymmetricalLogScale.html) but with +[AutoFormatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ticker.AutoFormatter.html) as the default major formatter. `x` and `y` versions of each keyword argument are no longer required.""" name = 'symlog' @@ -149,8 +149,8 @@ transform : callable, 2-tuple of callable, or scale-spec The transform used to translate units from the parent axis to the secondary axis. Input can be as follows: - * A single `linear `__ or - `involutory `__ + * A single [linear](https://en.wikipedia.org/wiki/Linear_function) or + [involutory](https://en.wikipedia.org/wiki/Involution_(mathematics)) function that accepts a number and returns some transformation of that number. For example, to convert Kelvin to Celsius, use ``ax.dualx(lambda x: x - 273.15)``. To convert kilometers to @@ -159,26 +159,26 @@ transform : callable, 2-tuple of callable, or scale-spec functions are non-linear and non-involutory. The second function must be the inverse of the first. For example, to apply the square, use ``ax.dualx((lambda x: x ** 2, lambda x: x ** 0.5))``. - * A scale specification passed to the `~ultraplot.constructor.Scale` + * A scale specification passed to the [Scale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Scale.html) constructor function. The transform and default locators and formatters - are borrowed from the resulting `~matplotlib.scale.ScaleBase` instance. + are borrowed from the resulting [ScaleBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.ScaleBase.html) instance. For example, to apply the inverse, use ``ax.dualx('inverse')``. To apply the base-10 exponential, use ``ax.dualx(('exp', 10))``. invert : bool, optional If ``True``, the forward and inverse functions are *swapped*. Used when drawing dual axes. -parent_scale : `~matplotlib.scale.ScaleBase`, default: `LinearScale` +parent_scale : [ScaleBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.ScaleBase.html), default: `LinearScale` The axis scale of the "parent" axis. Its forward transform is applied to the `FuncTransform`. major_locator, minor_locator : locator-spec, optional The default major and minor locator. Passed to the - `~ultraplot.constructor.Locator` constructor function. By default, these are + [Locator](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Locator.html) constructor function. By default, these are the same as the default locators on the input transform. If the input transform was not an axis scale, these are borrowed from `parent_scale`. major_formatter, minor_formatter : formatter-spec, optional The default major and minor formatter. Passed to the - `~ultraplot.constructor.Formatter` constructor function. By default, these are + [Formatter](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Formatter.html) constructor function. By default, these are the same as the default formatters on the input transform. If the input transform was not an axis scale, these are borrowed from `parent_scale`. @@ -227,14 +227,14 @@ always a no-op. Parameters ---------- values : array - The input values as an array of length :attr:`input_dims` or - shape (N, :attr:`input_dims`). + The input values as an array of length `input_dims` or + shape (N, `input_dims`). Returns ------- array - The output values as an array of length :attr:`output_dims` or - shape (N, :attr:`output_dims`), depending on the input.""" + The output values as an array of length `output_dims` or + shape (N, `output_dims`), depending on the input.""" ... class PowerScale(_Scale, mscale.ScaleBase): @@ -296,14 +296,14 @@ always a no-op. Parameters ---------- values : array - The input values as an array of length :attr:`input_dims` or - shape (N, :attr:`input_dims`). + The input values as an array of length `input_dims` or + shape (N, `input_dims`). Returns ------- array - The output values as an array of length :attr:`output_dims` or - shape (N, :attr:`output_dims`), depending on the input.""" + The output values as an array of length `output_dims` or + shape (N, `output_dims`), depending on the input.""" ... class InvertedPowerTransform(mtransforms.Transform): @@ -344,14 +344,14 @@ always a no-op. Parameters ---------- values : array - The input values as an array of length :attr:`input_dims` or - shape (N, :attr:`input_dims`). + The input values as an array of length `input_dims` or + shape (N, `input_dims`). Returns ------- array - The output values as an array of length :attr:`output_dims` or - shape (N, :attr:`output_dims`), depending on the input.""" + The output values as an array of length `output_dims` or + shape (N, `output_dims`), depending on the input.""" ... class ExpScale(_Scale, mscale.ScaleBase): @@ -433,14 +433,14 @@ always a no-op. Parameters ---------- values : array - The input values as an array of length :attr:`input_dims` or - shape (N, :attr:`input_dims`). + The input values as an array of length `input_dims` or + shape (N, `input_dims`). Returns ------- array - The output values as an array of length :attr:`output_dims` or - shape (N, :attr:`output_dims`), depending on the input.""" + The output values as an array of length `output_dims` or + shape (N, `output_dims`), depending on the input.""" ... class InvertedExpTransform(mtransforms.Transform): @@ -481,18 +481,18 @@ always a no-op. Parameters ---------- values : array - The input values as an array of length :attr:`input_dims` or - shape (N, :attr:`input_dims`). + The input values as an array of length `input_dims` or + shape (N, `input_dims`). Returns ------- array - The output values as an array of length :attr:`output_dims` or - shape (N, :attr:`output_dims`), depending on the input.""" + The output values as an array of length `output_dims` or + shape (N, `output_dims`), depending on the input.""" ... class MercatorLatitudeScale(_Scale, mscale.ScaleBase): - """Axis scale that is linear in the `Mercator projection latitude `__. Adapted from `this example `__. + """Axis scale that is linear in the [Mercator projection latitude](http://en.wikipedia.org/wiki/Mercator_projection). Adapted from [this example](https://matplotlib.org/2.0.2/examples/api/custom_scale_example.html). The scale function is as follows: .. math:: @@ -561,14 +561,14 @@ always a no-op. Parameters ---------- values : array - The input values as an array of length :attr:`input_dims` or - shape (N, :attr:`input_dims`). + The input values as an array of length `input_dims` or + shape (N, `input_dims`). Returns ------- array - The output values as an array of length :attr:`output_dims` or - shape (N, :attr:`output_dims`), depending on the input.""" + The output values as an array of length `output_dims` or + shape (N, `output_dims`), depending on the input.""" ... class InvertedMercatorLatitudeTransform(mtransforms.Transform): @@ -609,14 +609,14 @@ always a no-op. Parameters ---------- values : array - The input values as an array of length :attr:`input_dims` or - shape (N, :attr:`input_dims`). + The input values as an array of length `input_dims` or + shape (N, `input_dims`). Returns ------- array - The output values as an array of length :attr:`output_dims` or - shape (N, :attr:`output_dims`), depending on the input.""" + The output values as an array of length `output_dims` or + shape (N, `output_dims`), depending on the input.""" ... class SineLatitudeScale(_Scale, mscale.ScaleBase): @@ -684,14 +684,14 @@ always a no-op. Parameters ---------- values : array - The input values as an array of length :attr:`input_dims` or - shape (N, :attr:`input_dims`). + The input values as an array of length `input_dims` or + shape (N, `input_dims`). Returns ------- array - The output values as an array of length :attr:`output_dims` or - shape (N, :attr:`output_dims`), depending on the input.""" + The output values as an array of length `output_dims` or + shape (N, `output_dims`), depending on the input.""" ... class InvertedSineLatitudeTransform(mtransforms.Transform): @@ -732,14 +732,14 @@ always a no-op. Parameters ---------- values : array - The input values as an array of length :attr:`input_dims` or - shape (N, :attr:`input_dims`). + The input values as an array of length `input_dims` or + shape (N, `input_dims`). Returns ------- array - The output values as an array of length :attr:`output_dims` or - shape (N, :attr:`output_dims`), depending on the input.""" + The output values as an array of length `output_dims` or + shape (N, `output_dims`), depending on the input.""" ... class CutoffScale(_Scale, mscale.ScaleBase): @@ -818,14 +818,14 @@ always a no-op. Parameters ---------- values : array - The input values as an array of length :attr:`input_dims` or - shape (N, :attr:`input_dims`). + The input values as an array of length `input_dims` or + shape (N, `input_dims`). Returns ------- array - The output values as an array of length :attr:`output_dims` or - shape (N, :attr:`output_dims`), depending on the input.""" + The output values as an array of length `output_dims` or + shape (N, `output_dims`), depending on the input.""" ... class InverseScale(_Scale, mscale.ScaleBase): @@ -885,14 +885,14 @@ always a no-op. Parameters ---------- values : array - The input values as an array of length :attr:`input_dims` or - shape (N, :attr:`input_dims`). + The input values as an array of length `input_dims` or + shape (N, `input_dims`). Returns ------- array - The output values as an array of length :attr:`output_dims` or - shape (N, :attr:`output_dims`), depending on the input.""" + The output values as an array of length `output_dims` or + shape (N, `output_dims`), depending on the input.""" ... def _scale_factory(scale: Incomplete, axis: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: @@ -900,10 +900,10 @@ def _scale_factory(scale: Incomplete, axis: Incomplete, *args: Incomplete, **kwa Parameters ---------- -scale : str or `~matplotlib.scale.ScaleBase` +scale : str or [ScaleBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.ScaleBase.html) The axis scale name or scale instance. -axis : `~matplotlib.axis.Axis` +axis : [Axis](https://matplotlib.org/stable/api/_as_gen/matplotlib.axis.Axis.html) The axis instance. *args, **kwargs - Passed to `~matplotlib.scale.ScaleBase` if `scale` is a string.""" + Passed to [ScaleBase](https://matplotlib.org/stable/api/_as_gen/matplotlib.scale.ScaleBase.html) if `scale` is a string.""" ... diff --git a/ultraplot/tests/test_stubs.py b/ultraplot/tests/test_stubs.py index fe02f57a0..0a53fa450 100644 --- a/ultraplot/tests/test_stubs.py +++ b/ultraplot/tests/test_stubs.py @@ -149,6 +149,15 @@ def test_generated_stubs_include_runtime_docstrings(): assert "Matplotlib documentation" in plot_doc assert "Plot standard lines" in plot_doc assert "=====================\nultraplot documentation" not in plot_doc + assert ( + "[DataFrame](https://pandas.pydata.org/pandas-docs/stable/" + "reference/api/pandas.DataFrame.html)" in plot_doc + ) + assert ( + "[Cycle](https://ultraplot.readthedocs.io/en/stable/api/" + "ultraplot.constructor.Cycle.html)" in plot_doc + ) + assert ":class:`~pandas.DataFrame`" not in plot_doc grid_stub = PACKAGE / "gridspec.pyi" grid_tree = ast.parse(grid_stub.read_text(encoding="utf-8")) diff --git a/ultraplot/text.pyi b/ultraplot/text.pyi index 94db2be44..834909a76 100644 --- a/ultraplot/text.pyi +++ b/ultraplot/text.pyi @@ -34,7 +34,7 @@ curvature_pad : float, default: 2.0 min_advance : float, default: 1.0 Minimum additional spacing (pixels) enforced between glyph centers. **kwargs - Passed to `matplotlib.text.Text` for character styling.""" + Passed to [matplotlib.text.Text](https://matplotlib.org/stable/api/_as_gen/matplotlib.text.Text.html) for character styling.""" def __init__(self, x: Incomplete, y: Incomplete, text: Incomplete, axes: Incomplete, *, upright: Incomplete=True, ellipsis: Incomplete=False, avoid_overlap: Incomplete=True, overlap_tol: Incomplete=0.1, curvature_pad: Incomplete=2.0, min_advance: Incomplete=1.0, **kwargs: Incomplete) -> None: """Create a `.Text` instance at *x*, *y* with string *text*. @@ -42,7 +42,7 @@ min_advance : float, default: 1.0 The text is aligned relative to the anchor point (*x*, *y*) according to ``horizontalalignment`` (default: 'left') and ``verticalalignment`` (default: 'baseline'). See also -:doc:`/gallery/text_labels_and_annotations/text_alignment`. +[/gallery/text_labels_and_annotations/text_alignment](https://ultraplot.readthedocs.io/en/stable/search.html?q=%2Fgallery%2Ftext_labels_and_annotations%2Ftext_alignment). While Text accepts the 'label' keyword argument, by default it is not added to the handles of a legend. @@ -54,13 +54,13 @@ Properties: alpha: float or None animated: bool antialiased: bool - backgroundcolor: :mpltype:`color` + backgroundcolor: [color](https://matplotlib.org/stable/search.html?q=color) bbox: dict with properties for `.patches.FancyBboxPatch` clip_box: unknown clip_on: unknown clip_path: unknown - color or c: :mpltype:`color` - figure: `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure` + color or c: [color](https://matplotlib.org/stable/search.html?q=color) + figure: [Figure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html) or [SubFigure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.SubFigure.html) fontfamily or family or fontname: {FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'} fontproperties or font or font_properties: `.font_manager.FontProperties` or `str` or `pathlib.Path` fontsize or size: float or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'} @@ -86,10 +86,10 @@ Properties: sketch_params: (scale: float, length: float, randomness: float) snap: bool or None text: object - transform: `~matplotlib.transforms.Transform` + transform: [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html) transform_rotates_text: bool url: str - usetex: bool, default: :rc:`text.usetex` + usetex: bool, default: [text.usetex](https://ultraplot.readthedocs.io/en/stable/search.html?q=text.usetex) verticalalignment or va: {'baseline', 'bottom', 'center', 'center_baseline', 'top'} visible: bool wrap: bool @@ -144,7 +144,7 @@ level : float""" Parameters ---------- -t : `~matplotlib.transforms.Transform`""" +t : [Transform](https://matplotlib.org/stable/api/_as_gen/matplotlib.transforms.Transform.html)""" ... def draw(self, renderer: Incomplete, *args: Incomplete, **kwargs: Incomplete) -> None: diff --git a/ultraplot/textalign.pyi b/ultraplot/textalign.pyi index ac2243196..7931fea9f 100644 --- a/ultraplot/textalign.pyi +++ b/ultraplot/textalign.pyi @@ -124,14 +124,14 @@ Parameters ---------- ax : ultraplot.axes.Axes The axes whose labels are aligned. -labels : sequence of `~matplotlib.text.Text`, optional +labels : sequence of [Text](https://matplotlib.org/stable/api/_as_gen/matplotlib.text.Text.html), optional The labels to move. Default is every text registered for alignment on - the axes (see `~ultraplot.axes.Axes.text` with ``avoid_overlap=True``). + the axes (see [text](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.text) with ``avoid_overlap=True``). pad : float, default: 2.0 Padding in points added around every label bounding box. avoid_points : bool, default: True Whether labels also repel the data points of lines and scatter plots. -avoid : sequence of `~matplotlib.artist.Artist`, optional +avoid : sequence of [Artist](https://matplotlib.org/stable/api/_as_gen/matplotlib.artist.Artist.html), optional Additional artists (a legend, an inset, ...) whose bounding boxes the labels must stay clear of. only_move : {'xy', 'x', 'y'}, default: 'xy' @@ -148,7 +148,7 @@ clip : bool, default: True Whether to keep labels inside the axes. arrows : bool or dict, default: False Whether to draw a connector from displaced labels back to their anchor. - A dict is passed to `~matplotlib.patches.FancyArrowPatch`. + A dict is passed to [FancyArrowPatch](https://matplotlib.org/stable/api/_as_gen/matplotlib.patches.FancyArrowPatch.html). min_arrow_dist : float, default: 8.0 Only draw connectors for labels displaced further than this (in points). diff --git a/ultraplot/ticker.pyi b/ultraplot/ticker.pyi index 61555a5a0..3b804cdb1 100644 --- a/ultraplot/ticker.pyi +++ b/ultraplot/ticker.pyi @@ -1,7 +1,7 @@ # @generated by tools/generate_stubs.py; do not edit # fmt: off """ -Various `~matplotlib.ticker.Locator` and `~matplotlib.ticker.Formatter` classes. +Various [Locator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Locator.html) and [Formatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.Formatter.html) classes. """ from _typeshed import Incomplete import locale @@ -74,7 +74,7 @@ set_params() function will call this.""" class DiscreteLocator(mticker.Locator): """A tick locator suitable for discretized colorbars. Adds ticks to some subset of the location list depending on the available space determined from -`~matplotlib.axis.Axis.get_tick_space`. Zero will be used if it appears in the +[get_tick_space](https://matplotlib.org/stable/api/_as_gen/matplotlib.axis.Axis.get_tick_space.html). Zero will be used if it appears in the location list, and step sizes along the location list are restricted to "nice" intervals by default.""" default_params = {'nbins': None, 'minor': False, 'steps': np.array([1, 2, 3, 4, 5, 6, 8, 10]), 'min_n_ticks': 2} @@ -211,12 +211,12 @@ elsewhere.""" class AutoFormatter(mticker.ScalarFormatter): """The default formatter used for ultraplot tick labels. -Replaces `~matplotlib.ticker.ScalarFormatter`.""" +Replaces [ScalarFormatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.ScalarFormatter.html).""" def __init__(self, zerotrim: Incomplete=None, tickrange: Incomplete=None, wraprange: Incomplete=None, prefix: Incomplete=None, suffix: Incomplete=None, negpos: Incomplete=None, **kwargs: Incomplete) -> None: """Parameters ---------- -zerotrim : bool, default: :rc:`formatter.zerotrim` +zerotrim : bool, default: [formatter.zerotrim](https://ultraplot.readthedocs.io/en/stable/search.html?q=formatter.zerotrim) Whether to trim trailing decimal zeros. tickrange : 2-tuple of float, optional Range within which major tick marks are labeled. @@ -234,7 +234,7 @@ negpos : str, optional Other parameters ---------------- **kwargs - Passed to `matplotlib.ticker.ScalarFormatter`. + Passed to [matplotlib.ticker.ScalarFormatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.ScalarFormatter.html). See also -------- @@ -243,10 +243,10 @@ ultraplot.ticker.SimpleFormatter Note ---- -`matplotlib.ticker.ScalarFormatter` determines the number of +[matplotlib.ticker.ScalarFormatter](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.ScalarFormatter.html) determines the number of significant digits based on the axis limits, and therefore may truncate digits while formatting ticks on highly non-linear axis -scales like `~ultraplot.scale.LogScale`. `AutoFormatter` corrects +scales like [LogScale](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.scale.LogScale.html). `AutoFormatter` corrects this behavior, making it suitable for arbitrary axis scales. We therefore use `AutoFormatter` with every axis scale by default.""" ... @@ -318,7 +318,7 @@ from true floating point precision at which we want to limit string precision."" class SimpleFormatter(mticker.Formatter): """A general purpose number formatter. This is similar to `AutoFormatter` but suitable for arbitrary formatting not necessarily associated with -an `~matplotlib.axis.Axis` instance.""" +an [Axis](https://matplotlib.org/stable/api/_as_gen/matplotlib.axis.Axis.html) instance.""" def __init__(self, precision: Incomplete=None, zerotrim: Incomplete=None, tickrange: Incomplete=None, wraprange: Incomplete=None, prefix: Incomplete=None, suffix: Incomplete=None, negpos: Incomplete=None) -> None: """Parameters @@ -326,7 +326,7 @@ an `~matplotlib.axis.Axis` instance.""" precision : int, default: {6, 2} The maximum number of digits after the decimal point. Default is ``6`` when `zerotrim` is ``True`` and ``2`` otherwise. -zerotrim : bool, default: :rc:`formatter.zerotrim` +zerotrim : bool, default: [formatter.zerotrim](https://ultraplot.readthedocs.io/en/stable/search.html?q=formatter.zerotrim) Whether to trim trailing decimal zeros. tickrange : 2-tuple of float, optional Range within which major tick marks are labeled. @@ -360,7 +360,7 @@ pos : float, optional class IndexFormatter(mticker.Formatter): """Format numbers by assigning fixed strings to non-negative indices. Generally -paired with `IndexLocator` or `~matplotlib.ticker.FixedLocator`.""" +paired with `IndexLocator` or [FixedLocator](https://matplotlib.org/stable/api/_as_gen/matplotlib.ticker.FixedLocator.html).""" def __init__(self, labels: Incomplete) -> None: ... @@ -379,7 +379,7 @@ class SciFormatter(mticker.Formatter): precision : int, default: {6, 2} The maximum number of digits after the decimal point. Default is ``6`` when `zerotrim` is ``True`` and ``2`` otherwise. -zerotrim : bool, default: :rc:`formatter.zerotrim` +zerotrim : bool, default: [formatter.zerotrim](https://ultraplot.readthedocs.io/en/stable/search.html?q=formatter.zerotrim) Whether to trim trailing decimal zeros. See also @@ -407,7 +407,7 @@ class SigFigFormatter(mticker.Formatter): ---------- sigfig : float, default: 3 The number of significant digits. -zerotrim : bool, default: :rc:`formatter.zerotrim` +zerotrim : bool, default: [formatter.zerotrim](https://ultraplot.readthedocs.io/en/stable/search.html?q=formatter.zerotrim) Whether to trim trailing decimal zeros. base : float, default: 1 The base unit for rounding. For example ``SigFigFormatter(2, base=5)`` @@ -432,7 +432,7 @@ pos : float, optional class FracFormatter(mticker.Formatter): """Format numbers as integers or integer fractions. Optionally express the -values relative to some constant like `numpy.pi`.""" +values relative to some constant like [numpy.pi](https://numpy.org/doc/stable/reference/generated/numpy.pi.html).""" def __init__(self, symbol: Incomplete='', number: Incomplete=1) -> None: """Parameters @@ -440,7 +440,7 @@ values relative to some constant like `numpy.pi`.""" symbol : str, default: '' The constant symbol, e.g. ``r'$\\pi$'``. number : float, default: 1 - The constant value, e.g. `numpy.pi`. + The constant value, e.g. [numpy.pi](https://numpy.org/doc/stable/reference/generated/numpy.pi.html). Note ---- @@ -624,7 +624,7 @@ class CFTimeConverter(mdates.DateConverter): @staticmethod def axisinfo(unit: Incomplete, axis: Incomplete) -> Incomplete: - """Returns the :class:`~matplotlib.units.AxisInfo` for *unit*.""" + """Returns the [AxisInfo](https://matplotlib.org/stable/api/_as_gen/matplotlib.units.AxisInfo.html) for *unit*.""" ... @classmethod @@ -634,5 +634,5 @@ class CFTimeConverter(mdates.DateConverter): @classmethod def convert(cls, value: Incomplete, unit: Incomplete, axis: Incomplete) -> Incomplete: - """Converts value with :py:func:`cftime.date2num`.""" + """Converts value with `cftime.date2num`.""" ... diff --git a/ultraplot/ui.pyi b/ultraplot/ui.pyi index 790900686..39279d976 100644 --- a/ultraplot/ui.pyi +++ b/ultraplot/ui.pyi @@ -19,54 +19,54 @@ def _parse_figsize(kwargs: Incomplete) -> Incomplete: ... def show(*args: Incomplete, **kwargs: Incomplete) -> None: - """Call `matplotlib.pyplot.show`. -This is included so you don't have to import `~matplotlib.pyplot`. + """Call [matplotlib.pyplot.show](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.show.html). +This is included so you don't have to import [pyplot](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.html). Parameters ---------- *args, **kwargs - Passed to `matplotlib.pyplot.show`.""" + Passed to [matplotlib.pyplot.show](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.show.html).""" ... def close(*args: Incomplete, **kwargs: Incomplete) -> None: - """Call `matplotlib.pyplot.close`. -This is included so you don't have to import `~matplotlib.pyplot`. + """Call [matplotlib.pyplot.close](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.close.html). +This is included so you don't have to import [pyplot](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.html). Parameters ---------- *args, **kwargs - Passed to `matplotlib.pyplot.close`.""" + Passed to [matplotlib.pyplot.close](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.close.html).""" ... def switch_backend(*args: Incomplete, **kwargs: Incomplete) -> None: - """Call `matplotlib.pyplot.switch_backend`. -This is included so you don't have to import `~matplotlib.pyplot`. + """Call [matplotlib.pyplot.switch_backend](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.switch_backend.html). +This is included so you don't have to import [pyplot](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.html). Parameters ---------- *args, **kwargs - Passed to `matplotlib.pyplot.switch_backend`.""" + Passed to [matplotlib.pyplot.switch_backend](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.switch_backend.html).""" ... def ion() -> Incomplete: - """Call `matplotlib.pyplot.ion`. -This is included so you don't have to import `~matplotlib.pyplot`.""" + """Call [matplotlib.pyplot.ion](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.ion.html). +This is included so you don't have to import [pyplot](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.html).""" ... def ioff() -> Incomplete: - """Call `matplotlib.pyplot.ioff`. -This is included so you don't have to import `~matplotlib.pyplot`.""" + """Call [matplotlib.pyplot.ioff](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.ioff.html). +This is included so you don't have to import [pyplot](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.html).""" ... def isinteractive() -> bool: - """Call `matplotlib.pyplot.isinteractive`. -This is included so you don't have to import `~matplotlib.pyplot`.""" + """Call [matplotlib.pyplot.isinteractive](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.isinteractive.html). +This is included so you don't have to import [pyplot](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.html).""" ... def figure(**kwargs: Incomplete) -> Figure: """Create an empty figure. Subplots can be subsequently added using -`~ultraplot.figure.Figure.add_subplot` or `~ultraplot.figure.Figure.subplots`. -This command is analogous to `matplotlib.pyplot.figure`. +[add_subplot](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.add_subplot) or [subplots](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.subplots). +This command is analogous to [matplotlib.pyplot.figure](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.figure.html). Parameters ---------- @@ -80,11 +80,11 @@ refaspect : float or 2-tuple of float, optional divided by height. If 2-tuple, this indicates the (width, height). Ignored if both `figwidth` *and* `figheight` or both `refwidth` *and* `refheight` were passed. The default value is ``1`` or the "data aspect ratio" if the latter - is explicitly fixed (as with `~ultraplot.axes.PlotAxes.imshow` plots and - `~ultraplot.axes.Axes.GeoAxes` projections; see :func:`~matplotlib.axes.Axes.set_aspect`). -refwidth, refheight : unit-spec, default: :rc:`subplots.refwidth` + is explicitly fixed (as with [imshow](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PlotAxes.html#ultraplot.axes.PlotAxes.imshow) plots and + [GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.GeoAxes) projections; see [set_aspect](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_aspect.html)). +refwidth, refheight : unit-spec, default: [subplots.refwidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.refwidth) The width, height of the reference subplot. - If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + If float, units are inches. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Ignored if `figwidth`, `figheight`, or `figsize` was passed. If you specify just one, `refaspect` will be respected. ref, aspect, axwidth, axheight @@ -92,13 +92,13 @@ ref, aspect, axwidth, axheight *These may be deprecated in a future release.* figwidth, figheight : unit-spec, optional The figure width and height. Default behavior is to use `refwidth`. - If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + If float, units are inches. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). If you specify just one, `refaspect` will be respected. width, height Aliases for `figwidth`, `figheight`. figsize : 2-tuple, optional Tuple specifying the figure ``(width, height)``. -sharex, sharey, share : {0, False, 1, 'labels', 'labs', 2, 'limits', 'lims', 3, True, 4, 'all', 'auto'}, default: :rc:`subplots.share` +sharex, sharey, share : {0, False, 1, 'labels', 'labs', 2, 'limits', 'lims', 3, True, 4, 'all', 'auto'}, default: [subplots.share](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.share) The axis sharing "level" for the *x* axis, *y* axis, or both axes. Options are as follows: @@ -118,7 +118,7 @@ sharex, sharey, share : {0, False, 1, 'labels', 'labs', 2, 'limits', 'lims', 3, Explicit sharing levels (``0`` to ``4`` and aliases) still force sharing attempts and can emit warnings for incompatible axes. -spanx, spany, span : bool or {0, 1}, default: :rc:`subplots.span` +spanx, spany, span : bool or {0, 1}, default: [subplots.span](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.span) Whether to use "spanning" axis labels for the *x* axis, *y* axis, or both axes. Default is ``False`` if `sharex`, `sharey`, or `share` are ``0`` or ``False``. When ``True``, a single, centered axis label is used for all axes @@ -126,44 +126,44 @@ spanx, spany, span : bool or {0, 1}, default: :rc:`subplots.span` redundancy in your figure. "Spanning" labels integrate with "shared" axes. For example, for a 3-row, 3-column figure, with ``sharey > 1`` and ``spany == True``, your figure will have 1 y axis label instead of 9 y axis labels. -alignx, aligny, align : bool or {0, 1}, default: :rc:`subplots.align` - Whether to `"align" axis labels `__ +alignx, aligny, align : bool or {0, 1}, default: [subplots.align](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.align) + Whether to ["align" axis labels](https://matplotlib.org/stable/gallery/subplots_axes_and_figures/align_labels_demo.html) for the *x* axis, *y* axis, or both axes. Aligned labels always appear in the same row or column. This is ignored if `spanx`, `spany`, or `span` are ``True``. left, right, top, bottom : unit-spec, default: None The fixed space between the subplots and the figure edge. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). If ``None``, the space is determined automatically based on the tick and - label settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + label settings. If [subplots.tight](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.tight) is ``True`` or ``tight=True`` was passed to the figure, the space is determined by the tight layout algorithm. wspace, hspace, space : unit-spec, default: None The fixed space between grid columns, rows, or both. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). If ``None``, the space is determined automatically based on the font size and axis - sharing settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + sharing settings. If [subplots.tight](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.tight) is ``True`` or ``tight=True`` was passed to the figure, the space is determined by the tight layout algorithm. tight : bool, default: :rc`subplots.tight` Whether automatic calls to `~Figure.auto_layout` should include - :ref:`tight layout adjustments `. If you manually specified a spacing - in the call to `~ultraplot.ui.subplots`, it will be used to override the tight + [tight layout adjustments](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_tight). If you manually specified a spacing + in the call to [subplots](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ui.subplots.html), it will be used to override the tight layout spacing. For example, with ``left=1``, the left margin is set to 1 em-width, while the remaining margin widths are calculated automatically. -wequal, hequal, equal : bool, default: :rc:`subplots.equalspace` +wequal, hequal, equal : bool, default: [subplots.equalspace](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.equalspace) Whether to make the tight layout algorithm apply equal spacing between columns, rows, or both. -wgroup, hgroup, group : bool, default: :rc:`subplots.groupspace` +wgroup, hgroup, group : bool, default: [subplots.groupspace](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.groupspace) Whether to make the tight layout algorithm just consider spaces between adjacent subplots instead of entire columns and rows of subplots. -outerpad : unit-spec, default: :rc:`subplots.outerpad` +outerpad : unit-spec, default: [subplots.outerpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.outerpad) The scalar tight layout padding around the left, right, top, bottom figure edges. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -innerpad : unit-spec, default: :rc:`subplots.innerpad` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +innerpad : unit-spec, default: [subplots.innerpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.innerpad) The scalar tight layout padding between columns and rows. Synonymous with `pad`. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -panelpad : unit-spec, default: :rc:`subplots.panelpad` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +panelpad : unit-spec, default: [subplots.panelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.panelpad) The scalar tight layout padding between subplots and their panels, colorbars, and legends and between "stacks" of these objects. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). journal : str, optional String corresponding to an academic journal standard used to control the figure width `figwidth` and, if specified, the figure height `figheight`. See the below @@ -203,7 +203,7 @@ journal : str, optional Other parameters ---------------- **kwargs - Passed to `ultraplot.figure.Figure.format`. + Passed to [ultraplot.figure.Figure.format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.format). See also -------- @@ -216,7 +216,7 @@ matplotlib.figure.Figure""" def subplot(**kwargs: Incomplete) -> tuple[Figure, paxes.Axes]: """Return a figure and a single subplot. -This command is analogous to `matplotlib.pyplot.subplot`, +This command is analogous to [matplotlib.pyplot.subplot](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.subplot.html), except the figure instance is also returned. Other parameters @@ -231,11 +231,11 @@ refaspect : float or 2-tuple of float, optional divided by height. If 2-tuple, this indicates the (width, height). Ignored if both `figwidth` *and* `figheight` or both `refwidth` *and* `refheight` were passed. The default value is ``1`` or the "data aspect ratio" if the latter - is explicitly fixed (as with `~ultraplot.axes.PlotAxes.imshow` plots and - `~ultraplot.axes.Axes.GeoAxes` projections; see :func:`~matplotlib.axes.Axes.set_aspect`). -refwidth, refheight : unit-spec, default: :rc:`subplots.refwidth` + is explicitly fixed (as with [imshow](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PlotAxes.html#ultraplot.axes.PlotAxes.imshow) plots and + [GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.GeoAxes) projections; see [set_aspect](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_aspect.html)). +refwidth, refheight : unit-spec, default: [subplots.refwidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.refwidth) The width, height of the reference subplot. - If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + If float, units are inches. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Ignored if `figwidth`, `figheight`, or `figsize` was passed. If you specify just one, `refaspect` will be respected. ref, aspect, axwidth, axheight @@ -243,13 +243,13 @@ ref, aspect, axwidth, axheight *These may be deprecated in a future release.* figwidth, figheight : unit-spec, optional The figure width and height. Default behavior is to use `refwidth`. - If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + If float, units are inches. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). If you specify just one, `refaspect` will be respected. width, height Aliases for `figwidth`, `figheight`. figsize : 2-tuple, optional Tuple specifying the figure ``(width, height)``. -sharex, sharey, share : {0, False, 1, 'labels', 'labs', 2, 'limits', 'lims', 3, True, 4, 'all', 'auto'}, default: :rc:`subplots.share` +sharex, sharey, share : {0, False, 1, 'labels', 'labs', 2, 'limits', 'lims', 3, True, 4, 'all', 'auto'}, default: [subplots.share](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.share) The axis sharing "level" for the *x* axis, *y* axis, or both axes. Options are as follows: @@ -269,7 +269,7 @@ sharex, sharey, share : {0, False, 1, 'labels', 'labs', 2, 'limits', 'lims', 3, Explicit sharing levels (``0`` to ``4`` and aliases) still force sharing attempts and can emit warnings for incompatible axes. -spanx, spany, span : bool or {0, 1}, default: :rc:`subplots.span` +spanx, spany, span : bool or {0, 1}, default: [subplots.span](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.span) Whether to use "spanning" axis labels for the *x* axis, *y* axis, or both axes. Default is ``False`` if `sharex`, `sharey`, or `share` are ``0`` or ``False``. When ``True``, a single, centered axis label is used for all axes @@ -277,44 +277,44 @@ spanx, spany, span : bool or {0, 1}, default: :rc:`subplots.span` redundancy in your figure. "Spanning" labels integrate with "shared" axes. For example, for a 3-row, 3-column figure, with ``sharey > 1`` and ``spany == True``, your figure will have 1 y axis label instead of 9 y axis labels. -alignx, aligny, align : bool or {0, 1}, default: :rc:`subplots.align` - Whether to `"align" axis labels `__ +alignx, aligny, align : bool or {0, 1}, default: [subplots.align](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.align) + Whether to ["align" axis labels](https://matplotlib.org/stable/gallery/subplots_axes_and_figures/align_labels_demo.html) for the *x* axis, *y* axis, or both axes. Aligned labels always appear in the same row or column. This is ignored if `spanx`, `spany`, or `span` are ``True``. left, right, top, bottom : unit-spec, default: None The fixed space between the subplots and the figure edge. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). If ``None``, the space is determined automatically based on the tick and - label settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + label settings. If [subplots.tight](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.tight) is ``True`` or ``tight=True`` was passed to the figure, the space is determined by the tight layout algorithm. wspace, hspace, space : unit-spec, default: None The fixed space between grid columns, rows, or both. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). If ``None``, the space is determined automatically based on the font size and axis - sharing settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + sharing settings. If [subplots.tight](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.tight) is ``True`` or ``tight=True`` was passed to the figure, the space is determined by the tight layout algorithm. tight : bool, default: :rc`subplots.tight` Whether automatic calls to `~Figure.auto_layout` should include - :ref:`tight layout adjustments `. If you manually specified a spacing - in the call to `~ultraplot.ui.subplots`, it will be used to override the tight + [tight layout adjustments](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_tight). If you manually specified a spacing + in the call to [subplots](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ui.subplots.html), it will be used to override the tight layout spacing. For example, with ``left=1``, the left margin is set to 1 em-width, while the remaining margin widths are calculated automatically. -wequal, hequal, equal : bool, default: :rc:`subplots.equalspace` +wequal, hequal, equal : bool, default: [subplots.equalspace](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.equalspace) Whether to make the tight layout algorithm apply equal spacing between columns, rows, or both. -wgroup, hgroup, group : bool, default: :rc:`subplots.groupspace` +wgroup, hgroup, group : bool, default: [subplots.groupspace](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.groupspace) Whether to make the tight layout algorithm just consider spaces between adjacent subplots instead of entire columns and rows of subplots. -outerpad : unit-spec, default: :rc:`subplots.outerpad` +outerpad : unit-spec, default: [subplots.outerpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.outerpad) The scalar tight layout padding around the left, right, top, bottom figure edges. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -innerpad : unit-spec, default: :rc:`subplots.innerpad` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +innerpad : unit-spec, default: [subplots.innerpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.innerpad) The scalar tight layout padding between columns and rows. Synonymous with `pad`. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -panelpad : unit-spec, default: :rc:`subplots.panelpad` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +panelpad : unit-spec, default: [subplots.panelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.panelpad) The scalar tight layout padding between subplots and their panels, colorbars, and legends and between "stacks" of these objects. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). journal : str, optional String corresponding to an academic journal standard used to control the figure width `figwidth` and, if specified, the figure height `figheight`. See the below @@ -351,14 +351,14 @@ journal : str, optional .. _nat: https://www.nature.com/nature/for-authors/formatting-guide .. _pnas: https://www.pnas.org/page/authors/format **kwargs - Passed to `ultraplot.figure.Figure.format` or the + Passed to [ultraplot.figure.Figure.format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.format) or the projection-specific ``format`` command for the axes. Returns ------- -fig : `ultraplot.figure.Figure` +fig : [ultraplot.figure.Figure](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html) The figure instance. -ax : `ultraplot.axes.Axes` +ax : [ultraplot.axes.Axes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html) The axes instance. See also @@ -371,14 +371,14 @@ matplotlib.figure.Figure""" def subplots(*args: Incomplete, **kwargs: Incomplete) -> tuple[Figure, pgridspec.SubplotGrid]: """Return a figure and an arbitrary grid of subplots. -This command is analogous to `matplotlib.pyplot.subplots`, -except the subplots are stored in a :class:`~ultraplot.gridspec.SubplotGrid`. +This command is analogous to [matplotlib.pyplot.subplots](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.subplots.html), +except the subplots are stored in a [SubplotGrid](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.gridspec.SubplotGrid.html). Parameters ---------- -array : `ultraplot.gridspec.GridSpec` or array-like of int, optional - The subplot grid specifier. If a :class:`~ultraplot.gridspec.GridSpec`, one subplot is - drawn for each unique :class:`~ultraplot.gridspec.GridSpec` slot. If a 2D array of integers, +array : [ultraplot.gridspec.GridSpec](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.gridspec.GridSpec.html) or array-like of int, optional + The subplot grid specifier. If a [GridSpec](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.gridspec.GridSpec.html), one subplot is + drawn for each unique [GridSpec](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.gridspec.GridSpec.html) slot. If a 2D array of integers, one subplot is drawn for each unique integer in the array. Think of this array as a "picture" of the subplot grid -- for example, the array ``[[1, 1], [2, 3]]`` creates one long subplot in the top row, two smaller subplots in the bottom row. @@ -390,18 +390,18 @@ nrows, ncols : int, default: 1 if `array` was passed. Use these arguments for simple subplot grids. order : {'C', 'F'}, default: 'C' Whether subplots are numbered in column-major (``'C'``) or row-major (``'F'``) - order. Analogous to `numpy.array` ordering. This controls the order that + order. Analogous to [numpy.array](https://numpy.org/doc/stable/reference/generated/numpy.array.html) ordering. This controls the order that subplots appear in the `SubplotGrid` returned by this function, and the order - of subplot a-b-c labels (see `~ultraplot.axes.Axes.format`). + of subplot a-b-c labels (see [format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.format)). proj, projection : -str, :class:`cartopy.crs.Projection`, or :class:`~mpl_toolkits.basemap.Basemap`, optional +str, `cartopy.crs.Projection`, or `Basemap`, optional The map projection specification(s). If ``'cart'`` or ``'cartesian'`` - (the default), a :class:`~ultraplot.axes.CartesianAxes` is created. If ``'polar'``, - a :class:`~ultraplot.axes.PolarAxes` is created. Otherwise, the argument is - interpreted by :class:`~ultraplot.constructor.Proj`, and the result is used - to make a :class:`~ultraplot.axes.GeoAxes` (in this case the argument can be - a :class:`cartopy.crs.Projection` instance, a :class:`~mpl_toolkits.basemap.Basemap` - instance, or a projection name listed in :ref:`this table `). + (the default), a [CartesianAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.CartesianAxes.html) is created. If ``'polar'``, + a [PolarAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PolarAxes.html) is created. Otherwise, the argument is + interpreted by [Proj](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Proj.html), and the result is used + to make a [GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.GeoAxes.html) (in this case the argument can be + a `cartopy.crs.Projection` instance, a `Basemap` + instance, or a projection name listed in [this table](https://ultraplot.readthedocs.io/en/stable/search.html?q=proj_table)). To use different projections for different subplots, you have two options: @@ -418,16 +418,16 @@ str, :class:`cartopy.crs.Projection`, or :class:`~mpl_toolkits.basemap.Basemap`, for the third and fourth subplots. proj_kw, projection_kw : dict-like, optional - Keyword arguments passed to :class:`~mpl_toolkits.basemap.Basemap` or - :class:`~cartopy.crs.Projection` classes on instantiation. + Keyword arguments passed to `Basemap` or + `Projection` classes on instantiation. If dictionary of properties, applies globally. If list or dictionary of dictionaries, applies to specific subplots, as with `proj`. For example, ``uplt.subplots(ncols=2, proj='cyl', proj_kw=({'lon_0': 0}, {'lon_0': 180})`` centers the projection in the left subplot on the prime meridian and in the right subplot on the international dateline. -backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` - Whether to use :class:`~mpl_toolkits.basemap.Basemap` or - :class:`~cartopy.crs.Projection` for map projections. +backend : {'cartopy', 'basemap'}, default: [geo.backend](https://ultraplot.readthedocs.io/en/stable/search.html?q=geo.backend) + Whether to use `Basemap` or + `Projection` for map projections. .. deprecated:: 3.0.0 The ``'basemap'`` backend is deprecated and may be removed in a @@ -436,53 +436,53 @@ backend : {'cartopy', 'basemap'}, default: :rc:`geo.backend` subplots, as with `proj`. left, right, top, bottom : unit-spec, default: None The fixed space between the subplots and the figure edge. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). If ``None``, the space is determined automatically based on the tick and - label settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + label settings. If [subplots.tight](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.tight) is ``True`` or ``tight=True`` was passed to the figure, the space is determined by the tight layout algorithm. wspace, hspace, space : unit-spec or sequence, default: None The fixed space between grid columns, rows, and both, respectively. If float, string, or ``None``, this value is expanded into lists of length ``ncols - 1`` (for `wspace`) or length ``nrows - 1`` (for `hspace`). If a sequence, its length must match these lengths. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). For elements equal to ``None``, the space is determined automatically based - on the tick and label settings. If :rcraw:`subplots.tight` is ``True`` or + on the tick and label settings. If [subplots.tight](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.tight) is ``True`` or ``tight=True`` was passed to the figure, the space is determined by the tight layout algorithm. For example, ``subplots(ncols=3, tight=True, wspace=(2, None))`` fixes the space between columns 1 and 2 but lets the tight layout algorithm determine the space between columns 2 and 3. wratios, hratios : float or sequence, optional - Passed to :class:`~ultraplot.gridspec.GridSpec`, denotes the width and height + Passed to [GridSpec](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.gridspec.GridSpec.html), denotes the width and height ratios for the subplot grid. Length of `wratios` must match the number of columns, and length of `hratios` must match the number of rows. width_ratios, height_ratios Aliases for `wratios`, `hratios`. Included for - consistency with `matplotlib.gridspec.GridSpec`. + consistency with [matplotlib.gridspec.GridSpec](https://matplotlib.org/stable/api/_as_gen/matplotlib.gridspec.GridSpec.html). wpad, hpad, pad : unit-spec or sequence, optional The tight layout padding between columns, rows, and both, respectively. Unlike ``space``, these control the padding between subplot content (including text, ticks, etc.) rather than subplot edges. As with ``space``, these can be scalars or arrays optionally containing ``None``. For elements equal to ``None``, the default is `innerpad`. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -wequal, hequal, equal : bool, default: :rc:`subplots.equalspace` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +wequal, hequal, equal : bool, default: [subplots.equalspace](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.equalspace) Whether to make the tight layout algorithm apply equal spacing between columns, rows, or both. -wgroup, hgroup, group : bool, default: :rc:`subplots.groupspace` +wgroup, hgroup, group : bool, default: [subplots.groupspace](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.groupspace) Whether to make the tight layout algorithm just consider spaces between adjacent subplots instead of entire columns and rows of subplots. -outerpad : unit-spec, default: :rc:`subplots.outerpad` +outerpad : unit-spec, default: [subplots.outerpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.outerpad) The scalar tight layout padding around the left, right, top, bottom figure edges. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -innerpad : unit-spec, default: :rc:`subplots.innerpad` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +innerpad : unit-spec, default: [subplots.innerpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.innerpad) The scalar tight layout padding between columns and rows. Synonymous with `pad`. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -panelpad : unit-spec, default: :rc:`subplots.panelpad` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +panelpad : unit-spec, default: [subplots.panelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.panelpad) The scalar tight layout padding between subplots and their panels, colorbars, and legends and between "stacks" of these objects. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Other parameters ---------------- @@ -496,11 +496,11 @@ refaspect : float or 2-tuple of float, optional divided by height. If 2-tuple, this indicates the (width, height). Ignored if both `figwidth` *and* `figheight` or both `refwidth` *and* `refheight` were passed. The default value is ``1`` or the "data aspect ratio" if the latter - is explicitly fixed (as with `~ultraplot.axes.PlotAxes.imshow` plots and - `~ultraplot.axes.Axes.GeoAxes` projections; see :func:`~matplotlib.axes.Axes.set_aspect`). -refwidth, refheight : unit-spec, default: :rc:`subplots.refwidth` + is explicitly fixed (as with [imshow](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.PlotAxes.html#ultraplot.axes.PlotAxes.imshow) plots and + [GeoAxes](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.axes.Axes.html#ultraplot.axes.Axes.GeoAxes) projections; see [set_aspect](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_aspect.html)). +refwidth, refheight : unit-spec, default: [subplots.refwidth](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.refwidth) The width, height of the reference subplot. - If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + If float, units are inches. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). Ignored if `figwidth`, `figheight`, or `figsize` was passed. If you specify just one, `refaspect` will be respected. ref, aspect, axwidth, axheight @@ -508,13 +508,13 @@ ref, aspect, axwidth, axheight *These may be deprecated in a future release.* figwidth, figheight : unit-spec, optional The figure width and height. Default behavior is to use `refwidth`. - If float, units are inches. If string, interpreted by `~ultraplot.utils.units`. + If float, units are inches. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). If you specify just one, `refaspect` will be respected. width, height Aliases for `figwidth`, `figheight`. figsize : 2-tuple, optional Tuple specifying the figure ``(width, height)``. -sharex, sharey, share : {0, False, 1, 'labels', 'labs', 2, 'limits', 'lims', 3, True, 4, 'all', 'auto'}, default: :rc:`subplots.share` +sharex, sharey, share : {0, False, 1, 'labels', 'labs', 2, 'limits', 'lims', 3, True, 4, 'all', 'auto'}, default: [subplots.share](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.share) The axis sharing "level" for the *x* axis, *y* axis, or both axes. Options are as follows: @@ -534,7 +534,7 @@ sharex, sharey, share : {0, False, 1, 'labels', 'labs', 2, 'limits', 'lims', 3, Explicit sharing levels (``0`` to ``4`` and aliases) still force sharing attempts and can emit warnings for incompatible axes. -spanx, spany, span : bool or {0, 1}, default: :rc:`subplots.span` +spanx, spany, span : bool or {0, 1}, default: [subplots.span](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.span) Whether to use "spanning" axis labels for the *x* axis, *y* axis, or both axes. Default is ``False`` if `sharex`, `sharey`, or `share` are ``0`` or ``False``. When ``True``, a single, centered axis label is used for all axes @@ -542,44 +542,44 @@ spanx, spany, span : bool or {0, 1}, default: :rc:`subplots.span` redundancy in your figure. "Spanning" labels integrate with "shared" axes. For example, for a 3-row, 3-column figure, with ``sharey > 1`` and ``spany == True``, your figure will have 1 y axis label instead of 9 y axis labels. -alignx, aligny, align : bool or {0, 1}, default: :rc:`subplots.align` - Whether to `"align" axis labels `__ +alignx, aligny, align : bool or {0, 1}, default: [subplots.align](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.align) + Whether to ["align" axis labels](https://matplotlib.org/stable/gallery/subplots_axes_and_figures/align_labels_demo.html) for the *x* axis, *y* axis, or both axes. Aligned labels always appear in the same row or column. This is ignored if `spanx`, `spany`, or `span` are ``True``. left, right, top, bottom : unit-spec, default: None The fixed space between the subplots and the figure edge. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). If ``None``, the space is determined automatically based on the tick and - label settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + label settings. If [subplots.tight](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.tight) is ``True`` or ``tight=True`` was passed to the figure, the space is determined by the tight layout algorithm. wspace, hspace, space : unit-spec, default: None The fixed space between grid columns, rows, or both. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). If ``None``, the space is determined automatically based on the font size and axis - sharing settings. If :rcraw:`subplots.tight` is ``True`` or ``tight=True`` was + sharing settings. If [subplots.tight](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.tight) is ``True`` or ``tight=True`` was passed to the figure, the space is determined by the tight layout algorithm. tight : bool, default: :rc`subplots.tight` Whether automatic calls to `~Figure.auto_layout` should include - :ref:`tight layout adjustments `. If you manually specified a spacing - in the call to `~ultraplot.ui.subplots`, it will be used to override the tight + [tight layout adjustments](https://ultraplot.readthedocs.io/en/stable/search.html?q=ug_tight). If you manually specified a spacing + in the call to [subplots](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.ui.subplots.html), it will be used to override the tight layout spacing. For example, with ``left=1``, the left margin is set to 1 em-width, while the remaining margin widths are calculated automatically. -wequal, hequal, equal : bool, default: :rc:`subplots.equalspace` +wequal, hequal, equal : bool, default: [subplots.equalspace](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.equalspace) Whether to make the tight layout algorithm apply equal spacing between columns, rows, or both. -wgroup, hgroup, group : bool, default: :rc:`subplots.groupspace` +wgroup, hgroup, group : bool, default: [subplots.groupspace](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.groupspace) Whether to make the tight layout algorithm just consider spaces between adjacent subplots instead of entire columns and rows of subplots. -outerpad : unit-spec, default: :rc:`subplots.outerpad` +outerpad : unit-spec, default: [subplots.outerpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.outerpad) The scalar tight layout padding around the left, right, top, bottom figure edges. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -innerpad : unit-spec, default: :rc:`subplots.innerpad` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +innerpad : unit-spec, default: [subplots.innerpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.innerpad) The scalar tight layout padding between columns and rows. Synonymous with `pad`. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. -panelpad : unit-spec, default: :rc:`subplots.panelpad` + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). +panelpad : unit-spec, default: [subplots.panelpad](https://ultraplot.readthedocs.io/en/stable/search.html?q=subplots.panelpad) The scalar tight layout padding between subplots and their panels, colorbars, and legends and between "stacks" of these objects. - If float, units are em-widths. If string, interpreted by `~ultraplot.utils.units`. + If float, units are em-widths. If string, interpreted by [units](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.utils.units.html). journal : str, optional String corresponding to an academic journal standard used to control the figure width `figwidth` and, if specified, the figure height `figheight`. See the below @@ -616,15 +616,15 @@ journal : str, optional .. _nat: https://www.nature.com/nature/for-authors/formatting-guide .. _pnas: https://www.pnas.org/page/authors/format **kwargs - Passed to `ultraplot.figure.Figure.format` or the + Passed to [ultraplot.figure.Figure.format](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html#ultraplot.figure.Figure.format) or the projection-specific ``format`` command for each axes. Returns ------- -fig : `ultraplot.figure.Figure` +fig : [ultraplot.figure.Figure](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.figure.Figure.html) The figure instance. -axs : `ultraplot.gridspec.SubplotGrid` - The axes instances stored in a :class:`~ultraplot.gridspec.SubplotGrid`. +axs : [ultraplot.gridspec.SubplotGrid](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.gridspec.SubplotGrid.html) + The axes instances stored in a [SubplotGrid](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.gridspec.SubplotGrid.html). See also -------- diff --git a/ultraplot/utils.pyi b/ultraplot/utils.pyi index d80f8f2fc..93b2bf112 100644 --- a/ultraplot/utils.pyi +++ b/ultraplot/utils.pyi @@ -30,7 +30,7 @@ def _keep_units(func: Incomplete) -> Incomplete: ... def arange(min_: Incomplete, *args: Incomplete) -> Incomplete: - """Identical to `numpy.arange` but with inclusive endpoints. For example, + """Identical to [numpy.arange](https://numpy.org/doc/stable/reference/generated/numpy.arange.html) but with inclusive endpoints. For example, ``uplt.arange(2, 4)`` returns the numpy array ``[2, 3, 4]`` instead of ``[2, 3]``. This is useful for generating lists of tick locations or colormap levels, e.g. ``ax.format(xlocator=uplt.arange(0, 10))`` @@ -115,7 +115,7 @@ on-the-fly color cycle or colormap. Parameters ---------- *args, **kwargs - Passed to `~ultraplot.constructor.Cycle`. + Passed to [Cycle](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.constructor.Cycle.html). Returns ------- @@ -341,7 +341,7 @@ def _translate_cycle_color(color: Incomplete, cycle: Incomplete=None) -> Incompl def to_hex(color: Incomplete, space: Incomplete='rgb', cycle: Incomplete=None, keep_alpha: Incomplete=True) -> str: """Translate the color from an arbitrary colorspace to a HEX string. -This is a generalization of `matplotlib.colors.to_hex`. +This is a generalization of [matplotlib.colors.to_hex](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.to_hex.html). Parameters ---------- @@ -349,7 +349,7 @@ color : color-spec The color. Can be a 3-tuple or 4-tuple of channel values, a hex string, a registered color name, a cycle color like ``'C0'``, or a 2-tuple colormap coordinate specification like ``('magma', 0.5)`` - (see `~ultraplot.colors.ColorDatabase` for details). + (see [ColorDatabase](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ColorDatabase.html) for details). If `space` is ``'rgb'``, this is a tuple of RGB values, and any channels are larger than ``2``, the channels are assumed to be @@ -357,7 +357,7 @@ color : color-spec space : {'rgb', 'hsv', 'hcl', 'hpl', 'hsl'}, optional The colorspace for the input channel values. Ignored unless `color` is a tuple of numbers. -cycle : str, default: :rcraw:`cycle` +cycle : str, default: [cycle](https://ultraplot.readthedocs.io/en/stable/search.html?q=cycle) The registered color cycle name used to interpret colors that look like ``'C0'``, ``'C1'``, etc. clip : bool, default: True @@ -383,7 +383,7 @@ to_xyza""" def to_rgb(color: Incomplete, space: Incomplete='rgb', cycle: Incomplete=None) -> Incomplete: """Translate the color from an arbitrary colorspace to an RGB tuple. This is -a generalization of `matplotlib.colors.to_rgb` and the inverse of `to_xyz`. +a generalization of [matplotlib.colors.to_rgb](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.to_rgb.html) and the inverse of `to_xyz`. Parameters ---------- @@ -391,7 +391,7 @@ color : color-spec The color. Can be a 3-tuple or 4-tuple of channel values, a hex string, a registered color name, a cycle color like ``'C0'``, or a 2-tuple colormap coordinate specification like ``('magma', 0.5)`` - (see `~ultraplot.colors.ColorDatabase` for details). + (see [ColorDatabase](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ColorDatabase.html) for details). If `space` is ``'rgb'``, this is a tuple of RGB values, and any channels are larger than ``2``, the channels are assumed to be @@ -399,7 +399,7 @@ color : color-spec space : {'rgb', 'hsv', 'hcl', 'hpl', 'hsl'}, optional The colorspace for the input channel values. Ignored unless `color` is a tuple of numbers. -cycle : str, default: :rcraw:`cycle` +cycle : str, default: [cycle](https://ultraplot.readthedocs.io/en/stable/search.html?q=cycle) The registered color cycle name used to interpret colors that look like ``'C0'``, ``'C1'``, etc. clip : bool, default: True @@ -421,7 +421,7 @@ to_xyza""" def to_rgba(color: Incomplete, space: Incomplete='rgb', cycle: Incomplete=None, clip: Incomplete=True) -> Incomplete: """Translate the color from an arbitrary colorspace to an RGBA tuple. This is -a generalization of `matplotlib.colors.to_rgba` and the inverse of `to_xyz`. +a generalization of [matplotlib.colors.to_rgba](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.to_rgba.html) and the inverse of `to_xyz`. Parameters ---------- @@ -429,7 +429,7 @@ color : color-spec The color. Can be a 3-tuple or 4-tuple of channel values, a hex string, a registered color name, a cycle color like ``'C0'``, or a 2-tuple colormap coordinate specification like ``('magma', 0.5)`` - (see `~ultraplot.colors.ColorDatabase` for details). + (see [ColorDatabase](https://ultraplot.readthedocs.io/en/stable/api/ultraplot.colors.ColorDatabase.html) for details). If `space` is ``'rgb'``, this is a tuple of RGB values, and any channels are larger than ``2``, the channels are assumed to be @@ -437,7 +437,7 @@ color : color-spec space : {'rgb', 'hsv', 'hcl', 'hpl', 'hsl'}, optional The colorspace for the input channel values. Ignored unless `color` is a tuple of numbers. -cycle : str, default: :rcraw:`cycle` +cycle : str, default: [cycle](https://ultraplot.readthedocs.io/en/stable/search.html?q=cycle) The registered color cycle name used to interpret colors that look like ``'C0'``, ``'C1'``, etc. clip : bool, default: True @@ -536,12 +536,12 @@ value : float or str or sequence ``'in'`` Inches ``'pc'`` `Pica `_ (1/6 inches) ``'pt'`` `Points `_ (1/72 inches) - ``'px'`` Pixels on screen, using dpi of :rcraw:`figure.dpi` - ``'pp'`` Pixels once printed, using dpi of :rcraw:`savefig.dpi` - ``'em'`` `Em square `_ for :rcraw:`font.size` - ``'en'`` `En square `_ for :rcraw:`font.size` - ``'Em'`` `Em square `_ for :rcraw:`axes.titlesize` - ``'En'`` `En square `_ for :rcraw:`axes.titlesize` + ``'px'`` Pixels on screen, using dpi of [figure.dpi](https://ultraplot.readthedocs.io/en/stable/search.html?q=figure.dpi) + ``'pp'`` Pixels once printed, using dpi of [savefig.dpi](https://ultraplot.readthedocs.io/en/stable/search.html?q=savefig.dpi) + ``'em'`` `Em square `_ for [font.size](https://ultraplot.readthedocs.io/en/stable/search.html?q=font.size) + ``'en'`` `En square `_ for [font.size](https://ultraplot.readthedocs.io/en/stable/search.html?q=font.size) + ``'Em'`` `Em square `_ for [axes.titlesize](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.titlesize) + ``'En'`` `En square `_ for [axes.titlesize](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.titlesize) ``'ax'`` Axes-relative units (not always available) ``'fig'`` Figure-relative units (not always available) ``'ly'`` Light years ;) @@ -556,13 +556,13 @@ numeric : str, default: 'in' The units associated with numeric input. dest : str, default: `numeric` The destination units. -fontsize : str or float, default: :rc:`font.size` or :rc:`axes.titlesize` +fontsize : str or float, default: [font.size](https://ultraplot.readthedocs.io/en/stable/search.html?q=font.size) or [axes.titlesize](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.titlesize) The font size in points used for scaling. Default is - :rcraw:`font.size` for ``em`` and ``en`` units and - :rcraw:`axes.titlesize` for ``Em`` and ``En`` units. -axes : `~matplotlib.axes.Axes`, optional + [font.size](https://ultraplot.readthedocs.io/en/stable/search.html?q=font.size) for ``em`` and ``en`` units and + [axes.titlesize](https://ultraplot.readthedocs.io/en/stable/search.html?q=axes.titlesize) for ``Em`` and ``En`` units. +axes : [Axes](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html), optional The axes to use for scaling units that look like ``'0.1ax'``. -figure : `~matplotlib.figure.Figure`, optional +figure : [Figure](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html), optional The figure to use for scaling units that look like ``'0.1fig'``. If not provided we try to get the figure from ``axes.figure``. width : bool, optional From 2d9b81b1671266a66de0566c6d3b941918b74b8a Mon Sep 17 00:00:00 2001 From: cvanelteren Date: Fri, 4 Sep 2026 15:11:27 +1000 Subject: [PATCH 9/9] fix plot not resolving --- tools/generate_stubs.py | 23 +++++++++++++++++++++++ ultraplot/axes/plot.pyi | 2 +- ultraplot/tests/test_stubs.py | 24 ++++++++++++++++++++++++ 3 files changed, 48 insertions(+), 1 deletion(-) diff --git a/tools/generate_stubs.py b/tools/generate_stubs.py index 32d051e2f..1ac86e976 100644 --- a/tools/generate_stubs.py +++ b/tools/generate_stubs.py @@ -834,6 +834,28 @@ def _add_static_forwarding_bases(source_path: Path, tree: ast.Module) -> None: return +def _add_static_signatures(source_path: Path, tree: ast.Module) -> None: + """Add useful signatures for public wrappers that are dynamic at runtime.""" + if source_path != PACKAGE / "axes" / "plot.py": + return + + signature = ast.parse( + "def plot(" + "self, *args: Any, " + "scalex: bool = ..., scaley: bool = ..., data: Any = ..., " + "**kwargs: Any" + ") -> list[Any]: ..." + ).body[0] + for node in tree.body: + if not isinstance(node, ast.ClassDef) or node.name != "PlotAxes": + continue + for member in node.body: + if isinstance(member, ast.FunctionDef) and member.name == "plot": + member.args = signature.args + member.returns = signature.returns + return + + def _render( source_path: Path, expand_docstring, @@ -849,6 +871,7 @@ def _render( tree = ast.parse(source, filename=str(source_path)) annotation_counts = _merge_annotations(tree, inferred) _add_static_forwarding_bases(source_path, tree) + _add_static_signatures(source_path, tree) tree = _StubTransformer(expand_docstring, module=runtime_module).visit( copy.deepcopy(tree) ) diff --git a/ultraplot/axes/plot.pyi b/ultraplot/axes/plot.pyi index 1b0a5f3ac..9bfcee5ef 100644 --- a/ultraplot/axes/plot.pyi +++ b/ultraplot/axes/plot.pyi @@ -2303,7 +2303,7 @@ Notes This is the [pyplot wrapper](https://ultraplot.readthedocs.io/en/stable/search.html?q=pyplot_interface) for `.axes.Axes.semilogx`.""" ... - def plot(self, *args: Incomplete, **kwargs: Incomplete) -> Incomplete: + def plot(self, *args: Any, scalex: bool=..., scaley: bool=..., data: Any=..., **kwargs: Any) -> list[Any]: """Plot standard lines. Parameters diff --git a/ultraplot/tests/test_stubs.py b/ultraplot/tests/test_stubs.py index 0a53fa450..e12023158 100644 --- a/ultraplot/tests/test_stubs.py +++ b/ultraplot/tests/test_stubs.py @@ -169,6 +169,30 @@ def test_generated_stubs_include_runtime_docstrings(): assert "for every axes in the grid" in twiny_doc +def test_plot_stub_exposes_static_signature(): + """The dynamic plot wrapper should retain its useful public call shape.""" + tree = ast.parse((PACKAGE / "axes" / "plot.pyi").read_text(encoding="utf-8")) + plot_axes = next( + node + for node in tree.body + if isinstance(node, ast.ClassDef) and node.name == "PlotAxes" + ) + plot = next( + node + for node in plot_axes.body + if isinstance(node, ast.FunctionDef) and node.name == "plot" + ) + + assert ast.unparse(plot.args.vararg.annotation) == "Any" + assert [argument.arg for argument in plot.args.kwonlyargs] == [ + "scalex", + "scaley", + "data", + ] + assert ast.unparse(plot.args.kwarg.annotation) == "Any" + assert ast.unparse(plot.returns) == "list[Any]" + + def test_subplot_grid_stub_preserves_axes_indexing_chain(): """Integer indexing must lead static analyzers from a grid to an axes.""" grid_stub = PACKAGE / "gridspec.pyi"