|
24 | 24 | # used with distinct plot elements like lines and bars. Occasionally, |
25 | 25 | # they are used with categorical data as "qualitative" colormaps. Proplot's |
26 | 26 | # color cycles are registered as `~proplot.colors.DiscreteColormap`\ s, |
27 | | -# and can be converted into `property cyclers |
| 27 | +# and can be easily converted into `property cyclers |
28 | 28 | # <https://matplotlib.org/stable/tutorials/intermediate/color_cycle.html>`__ |
29 | 29 | # for use with distinct plot elements using the `~proplot.constructor.Cycle` |
30 | 30 | # constructor function. `~proplot.constructor.Cycle` can also |
|
60 | 60 | # Changing the color cycle |
61 | 61 | # ------------------------ |
62 | 62 | # |
63 | | -# Various plotting commands like `~proplot.axes.PlotAxes.line` and |
64 | | -# `~proplot.axes.PlotAxes.scatter` now accept a `cycle` keyword |
65 | | -# passed to the `~proplot.constructor.Cycle` constructor function |
66 | | -# (see the :ref:`1D plotting section <ug_apply_cycle>`). To save |
67 | | -# your color cycle data and use it every time proplot is imported, simply pass |
68 | | -# ``save=True`` to `~proplot.constructor.Cycle`. If you want to change the global |
69 | | -# property cycler, pass a `~proplot.colors.DiscreteColormap` or colormap name |
| 63 | +# Most 1D `~proplot.axes.PlotAxes` commands like `~proplot.axes.PlotAxes.line` |
| 64 | +# and `~proplot.axes.PlotAxes.scatter` accept a `cycle` keyword (see the |
| 65 | +# :ref:`1D plotting section <ug_apply_cycle>`). This can be used to change the |
| 66 | +# color cycle on-the-fly, whether plotting with successive calls to |
| 67 | +# `~proplot.axes.PlotAxes` commands or a single call using 2D array(s) (see |
| 68 | +# the :ref:`1D plotting section <ug_1dstd>`). To change the global property |
| 69 | +# cycler, pass a `~proplot.colors.DiscreteColormap` or cycle name |
70 | 70 | # to :rcraw:`cycle` or pass the result of `~proplot.constructor.Cycle` |
71 | 71 | # to :rcraw:`axes.prop_cycle` (see the :ref:`configuration guide <ug_config>`). |
72 | 72 |
|
|
107 | 107 | # Making color cycles |
108 | 108 | # ------------------- |
109 | 109 | # |
110 | | -# You can make new color cycles with the `~proplot.constructor.Cycle` |
111 | | -# :ref:`constructor function <why_constructor>`. One great way to make cycles is by |
112 | | -# sampling colormaps! Just pass the colormap name to `~proplot.constructor.Cycle`, |
113 | | -# and optionally specify the number of samples you want to draw as the last |
114 | | -# positional argument -- e.g. ``pplt.Cycle('Blues', 5)``. Calling e.g. |
115 | | -# ``ax.plot(data, cycle='Blues')`` where ``data`` is a 2D array will automatically |
116 | | -# use the same number of samples as the number of columns in the array. |
117 | | -# |
| 110 | +# Proplot includes tools for merging color cycles, modifying existing color |
| 111 | +# cycles, making new color cycles, and saving color cycles for future use. |
| 112 | +# Most of these features can be accessed via the `~proplot.constructor.Cycle` |
| 113 | +# :ref:`constructor function <why_constructor>`. This command returns |
| 114 | +# `~cycler.Cycler` instances whose `color` properties are determined by the |
| 115 | +# positional arguments (see :ref:`below <ug_cycles_other>` for changing other |
| 116 | +# properties). Note that every `~proplot.axes.PlotAxes` command that accepts a |
| 117 | +# `cycle` keyword passes it through this function (see the :ref:`1D plotting |
| 118 | +# section <ug_apply_cycle>`). |
| 119 | + |
118 | 120 | # Positional arguments passed to `~proplot.constructor.Cycle` are interpreted |
119 | | -# by the `~proplot.constructor.Colormap` constructor function, and the resulting |
120 | | -# colormap is sampled at discrete values. To exclude near-white colors on the |
121 | | -# end of a colormap, pass e.g. ``left=x`` to `~proplot.constructor.Cycle`, or |
122 | | -# supply a plotting command with e.g. ``cycle_kw={'left': x}``. See |
123 | | -# the :ref:`colormaps section <ug_cmaps>` for details. |
| 121 | +# by the `~proplot.constructor.Colormap` constructor function. If the result |
| 122 | +# is a `~proplot.colors.DiscreteColormap`, those colors are used for the resulting |
| 123 | +# `~cycler.Cycler`. If the result is a `~proplot.colors.ContinuousColormap`, the |
| 124 | +# colormap is sampled at `N` discrete values -- for example, ``pplt.Cycle('Blues', 5)`` |
| 125 | +# selects 5 evenly-spaced values. When building color cycles on-the-fly, for example |
| 126 | +# with ``ax.plot(data, cycle='Blues')``, proplot automatically selects as many colors |
| 127 | +# as there are columns in the 2D array (i.e., if we are drawing 10 lines using an array |
| 128 | +# with 10 columns, proplot will select 10 evenly-spaced values from the colormap). |
| 129 | +# To exclude near-white colors on the end of a colormap, pass e.g. ``left=x`` |
| 130 | +# to `~proplot.constructor.Cycle`, or supply a plotting command with e.g. |
| 131 | +# ``cycle_kw={'left': x}``. See the :ref:`colormaps section <ug_cmaps>` for details. |
124 | 132 | # |
125 | | -# In the below example, several cycles are constructed from scratch, and the |
126 | | -# lines are referenced with colorbars and legends. Note that proplot permits |
| 133 | +# In the below example, several color cycles are constructed from scratch, and |
| 134 | +# the lines are referenced with colorbars and legends. Note that proplot permits |
127 | 135 | # generating colorbars from :ref:`lists of artists <ug_colorbars>`. |
128 | 136 |
|
129 | 137 | # %% |
|
155 | 163 | # Cycles of other properties |
156 | 164 | # -------------------------- |
157 | 165 | # |
158 | | -# `~proplot.constructor.Cycle` can also generate cyclers that change |
159 | | -# properties other than color. Below, a single-color dash style cycler is |
160 | | -# constructed and applied to the axes locally. To apply it globally, simply |
161 | | -# use ``pplt.rc['axes.prop_cycle'] = cycle``. |
| 166 | +# `~proplot.constructor.Cycle` can generate `~cycler.Cycler` instances that |
| 167 | +# change `~proplot.axes.PlotAxes.line` and `~proplot.axes.PlotAxes.scatter` |
| 168 | +# properties other than `color`. In the below example, a single-color line |
| 169 | +# property cycler is constructed and applied to the axes locally using the |
| 170 | +# line properties `lw` and `dashes` (the aliases `linewidth` or `linewidths` |
| 171 | +# would also work). The resulting property cycle can be applied globally |
| 172 | +# using ``pplt.rc['axes.prop_cycle'] = cycle``. |
162 | 173 |
|
163 | 174 | # %% |
164 | 175 | import proplot as pplt |
|
0 commit comments