# ---
# jupyter:
#   jupytext:
#     text_representation:
#       extension: .py
#       format_name: percent
#       format_version: '1.3'
#       jupytext_version: 1.11.4
#   kernelspec:
#     display_name: Python 3
#     language: python
#     name: python3
# ---

# %% [raw] raw_mimetype="text/restructuredtext"
# .. _ug_cycles:
#
# Color cycles
# ============
#
# UltraPlot defines **color cycles** or **discrete colormaps** as color palettes
# comprising sets of *distinct colors*. Unlike :ref:`continuous colormaps <ug_cmaps>`,
# interpolation between these colors may not make sense. Generally, color cycles are
# used with distinct plot elements like lines and bars. Occasionally,
# they are used with categorical data as "qualitative" colormaps. UltraPlot's
# color cycles are registered as :class:`~ultraplot.colors.DiscreteColormap`\ s,
# and can be easily converted into `property cyclers
# <https://matplotlib.org/stable/tutorials/intermediate/color_cycle.html>`__
# for use with distinct plot elements using the :class:`~ultraplot.constructor.Cycle`
# constructor function. :class:`~ultraplot.constructor.Cycle` can also
# :ref:`extract colors <ug_cycles_new>` from :class:`~ultraplot.colors.ContinuousColormap`\ s.
#
# UltraPlot :ref:`adds several features <why_colormaps_cycles>` to help you use color
# cycles effectively in your figures. This section documents the new registered
# color cycles, explains how to make and modify color cycles, and shows how to
# apply them to your plots.


# %% [raw] raw_mimetype="text/restructuredtext" tags=[]
# .. _ug_cycles_included:
#
# Included color cycles
# ---------------------
#
# Use :func:`~ultraplot.demos.show_cycles` to generate a table of registered color
# cycles. The table includes the default color cycles registered by UltraPlot and
# "user" color cycles created with the :class:`~ultraplot.constructor.Cycle` constructor
# function or loaded from :func:`~ultraplot.config.Configurator.user_folder`. If you need
# the list of colors associated with a registered or on-the-fly color cycle,
# simply use :func:`~ultraplot.utils.get_colors`.

# %%
import ultraplot as uplt

fig, axs = uplt.show_cycles(rasterized=True)


# %% [raw] raw_mimetype="text/restructuredtext"
# .. _ug_cycles_changing:
#
# Changing the color cycle
# ------------------------
#
# Most 1D :class:`~ultraplot.axes.PlotAxes` commands like :func:`~ultraplot.axes.PlotAxes.line`
# and :func:`~ultraplot.axes.PlotAxes.scatter` accept a `cycle` keyword (see the
# :ref:`1D plotting section <ug_apply_cycle>`). This can be used to change the
# color cycle on-the-fly, whether plotting with successive calls to
# :class:`~ultraplot.axes.PlotAxes` commands or a single call using 2D array(s) (see
# the :ref:`1D plotting section <ug_1dstd>`). To change the global property
# cycler, pass a :class:`~ultraplot.colors.DiscreteColormap` or cycle name
# to :rcraw:`cycle` or pass the result of :class:`~ultraplot.constructor.Cycle`
# to :rcraw:`axes.prop_cycle` (see the :ref:`configuration guide <ug_config>`).

# %%
import ultraplot as uplt
import numpy as np

# Sample data
state = np.random.RandomState(51423)
data = (state.rand(12, 6) - 0.45).cumsum(axis=0)
kwargs = {"legend": "b", "labels": list("abcdef")}

# Figure
lw = 5
uplt.rc.cycle = "538"
fig = uplt.figure(refwidth=1.9, suptitle="Changing the color cycle")

# Modify the default color cycle
ax = fig.subplot(131, title="Global color cycle")
ax.plot(data, lw=lw, **kwargs)

# Pass the cycle to a plotting command
ax = fig.subplot(132, title="Local color cycle")
ax.plot(data, cycle="qual1", lw=lw, **kwargs)

# As above but draw each line individually
# Note that passing cycle=name to successive plot calls does
# not reset the cycle position if the cycle is unchanged
ax = fig.subplot(133, title="Multiple plot calls")
labels = kwargs["labels"]
for i in range(data.shape[1]):
    ax.plot(data[:, i], cycle="qual1", legend="b", label=labels[i], lw=lw)


# %% [raw] raw_mimetype="text/restructuredtext"
# .. _ug_cycles_new:
#
# Making color cycles
# -------------------
#
# UltraPlot includes tools for merging color cycles, modifying existing color
# cycles, making new color cycles, and saving color cycles for future use.
# Most of these features can be accessed via the :class:`~ultraplot.constructor.Cycle`
# :ref:`constructor function <why_constructor>`. This command returns
# :class:`~cycler.Cycler` instances whose `color` properties are determined by the
# positional arguments (see :ref:`below <ug_cycles_other>` for changing other
# properties). Note that every :class:`~ultraplot.axes.PlotAxes` command that accepts a
# `cycle` keyword passes it through this function (see the :ref:`1D plotting
# section <ug_apply_cycle>`).

# Positional arguments passed to :class:`~ultraplot.constructor.Cycle` are interpreted
# by the :class:`~ultraplot.constructor.Colormap` constructor function. If the result
# is a :class:`~ultraplot.colors.DiscreteColormap`, those colors are used for the resulting
# :class:`~cycler.Cycler`. If the result is a :class:`~ultraplot.colors.ContinuousColormap`, the
# colormap is sampled at `N` discrete values -- for example, ``uplt.Cycle('Blues', 5)``
# selects 5 evenly-spaced values. When building color cycles on-the-fly, for example
# with ``ax.plot(data, cycle='Blues')``, UltraPlot automatically selects as many colors
# as there are columns in the 2D array (i.e., if we are drawing 10 lines using an array
# with 10 columns, UltraPlot will select 10 evenly-spaced values from the colormap).
# To exclude near-white colors on the end of a colormap, pass e.g. ``left=x``
# to :class:`~ultraplot.constructor.Cycle`, or supply a plotting command with e.g.
# ``cycle_kw={'left': x}``. See the :ref:`colormaps section <ug_cmaps>` for details.
#
# In the below example, several color cycles are constructed from scratch, and
# the lines are referenced with colorbars and legends. Note that UltraPlot permits
# generating colorbars from :ref:`lists of artists <ug_colorbars>`.

# %%
import ultraplot as uplt
import numpy as np

fig = uplt.figure(refwidth=2, share=False)
state = np.random.RandomState(51423)
data = (20 * state.rand(10, 21) - 10).cumsum(axis=0)

# Cycle from on-the-fly monochromatic colormap
ax = fig.subplot(121)
lines = ax.plot(data[:, :5], cycle="plum", lw=5)
fig.colorbar(lines, loc="b", col=1, values=np.arange(0, len(lines)))
fig.legend(lines, loc="b", col=1, labels=np.arange(0, len(lines)))
ax.format(title="Cycle from a single color")

# Cycle from registered colormaps
ax = fig.subplot(122)
cycle = uplt.Cycle("blues", "reds", "oranges", 15, left=0.1)
lines = ax.plot(data[:, :15], cycle=cycle, lw=5)
fig.colorbar(lines, loc="b", col=2, values=np.arange(0, len(lines)), locator=2)
fig.legend(lines, loc="b", col=2, labels=np.arange(0, len(lines)), ncols=4)
ax.format(title="Cycle from merged colormaps", suptitle="Color cycles from colormaps")


# %% [raw] raw_mimetype="text/restructuredtext"
# .. _ug_cycles_other:
#
# Cycles of other properties
# --------------------------
#
# :class:`~ultraplot.constructor.Cycle` can generate :class:`~cycler.Cycler` instances that
# change :func:`~ultraplot.axes.PlotAxes.line` and :func:`~ultraplot.axes.PlotAxes.scatter`
# properties other than `color`. In the below example, a single-color line
# property cycler is constructed and applied to the axes locally using the
# line properties `lw` and `dashes` (the aliases `linewidth` or `linewidths`
# would also work). The resulting property cycle can be applied globally
# using ``uplt.rc['axes.prop_cycle'] = cycle``.

# %%
import ultraplot as uplt
import numpy as np
import pandas as pd

# Cycle that loops through 'dashes' Line2D property
cycle = uplt.Cycle(lw=3, dashes=[(1, 0.5), (1, 1.5), (3, 0.5), (3, 1.5)])

# Sample data
state = np.random.RandomState(51423)
data = (state.rand(20, 4) - 0.5).cumsum(axis=0)
data = pd.DataFrame(data, columns=pd.Index(["a", "b", "c", "d"], name="label"))

# Plot data
fig, ax = uplt.subplots(refwidth=2.5, suptitle="Plot without color cycle")
obj = ax.plot(
    data, cycle=cycle, legend="ll", legend_kw={"ncols": 2, "handlelength": 2.5}
)


# %% [raw] raw_mimetype="text/restructuredtext"
# .. _ug_cycles_dl:
#
# Downloading color cycles
# ------------------------
#
# There are several interactive online tools for generating perceptually
# distinct color cycles, including
# `i want hue <http://tools.medialab.sciences-po.fr/iwanthue/index.php>`__,
# `Color Cycle Picker <https://colorcyclepicker.mpetroff.net/>`__,
# `Colorgorical <http://vrl.cs.brown.edu/color>`__,
# `Adobe Color <https://color.adobe.com/explore>`__,
# `Color Hunt <https://colorhunt.co/>`__,
# `Coolers <https://coolors.co>`__,
# and `Color Drop <https://colordrop.io/>`__.

# To add color cycles downloaded from any of these sources, save the color data file
# to the ``cycles`` subfolder inside :func:`~ultraplot.config.Configurator.user_folder`,
# or to a folder named ``ultraplot_cycles`` in the same directory as your python session
# or an arbitrary parent directory (see :func:`~ultraplot.config.Configurator.local_folders`).
# After adding the file, call :func:`~ultraplot.config.register_cycles` or restart your python
# session. You can also use :func:`~ultraplot.colors.DiscreteColormap.from_file` or manually
# pass :class:`~ultraplot.colors.DiscreteColormap` instances or file paths to
# :func:`~ultraplot.config.register_cycles`. See :func:`~ultraplot.config.register_cycles`
# for a table of recognized data file extensions.