plots.styles
============

.. py:module:: plots.styles


Submodules
----------

.. toctree::
   :maxdepth: 1

   /_api/plots/styles/auto/index
   /_api/plots/styles/colors/index
   /_api/plots/styles/legends/index
   /_api/plots/styles/levels/index
   /_api/plots/styles/magics/index
   /_api/plots/styles/symbols/index


Attributes
----------

.. autoapisummary::

   plots.styles.DEFAULT_STYLE


Classes
-------

.. autoapisummary::

   plots.styles.Style


Package Contents
----------------

.. py:data:: DEFAULT_STYLE

.. py:class:: Style(colors=schema.default_cmap, levels=None, gradients=None, normalize=True, units=None, scale_factor=None, units_label=None, legend_style='colorbar', legend_kwargs=None, categories=None, ticks=None, preferred_method='contourf', resample=None, **kwargs)

   A style for plotting data.

   :param colors: The colors to be used in this `Style`. This can be a
                  `named matplotlib colormap
                  <https://matplotlib.org/stable/gallery/color/colormap_reference.html>`__,
                  a list of colors (as named CSS4 colors, hexadecimal colors or three
                  (four)-element lists of RGB(A) values), or a pre-defined matplotlib
                  colormap object. If not provided, the default colormap of the active
                  `schema` will be used.
   :type colors: str or list or matplotlib.colors.Colormap, optional
   :param levels: The levels to use in this `Style`. This can be a list of specific
                  levels, or an earthkit `Levels` object. If not provided, some suitable
                  levels will be generated automatically (experimental!).
   :type levels: list or earthkit.maps.styles.levels.Levels, optional
   :param gradients: The number of colors to insert between each level in `levels`. If None,
                     one color level will be inserted between each level.
   :type gradients: list, optional
   :param normalize: If `True` (default), then the colors will be normalized over the level
                     range.
   :type normalize: bool, optional
   :param units: The units in which the levels are defined. If this `Style` is used with
                 data not using the given units, then a conversion will be attempted;
                 any data incompatible with these units will not be able to use this
                 `Style`. If `units` are not provided, then data plotted using this
                 `Style` will remain in their original units.
   :type units: str, optional
   :param units_label: The label to use in titles and legends to represent the units of the
                       data.
   :type units_label: str, optional
   :param legend_style: The style of legend to use by default with this style. Must be one of
                        `colorbar` (default), `disjoint`, `histogram`, or `None` (no legend).
   :type legend_style: str, optional
   :param bin_labels: A list of categorical labels for each bin in the legend.
   :type bin_labels: list, optional


   .. py:method:: apply_scale_factor(values)

      Apply the scale factor to some values.



   .. py:method:: bar(ax, x, y, values, *args, mode='linear', **kwargs)

      Plot a scatter plot using this `Style`.

      :param ax: The axes on which to plot the data.
      :type ax: matplotlib.axes.Axes
      :param x: The x coordinates of the data to be plotted.
      :type x: numpy.ndarray
      :param y: The y coordinates of the data to be plotted.
      :type y: numpy.ndarray
      :param values: The values of the data to be plotted.
      :type values: numpy.ndarray
      :param \*\*kwargs: Any additional arguments accepted by `matplotlib.axes.Axes.scatter`.



   .. py:method:: barbs(ax, x, y, u, v, *args, **kwargs)


   .. py:method:: colorbar(*args, **kwargs)

      Create a colorbar legend for this `Style`.



   .. py:method:: contour(ax, x, y, values, *args, **kwargs)

      Plot line contours using this `Style`.

      :param ax: The axes on which to plot the data.
      :type ax: matplotlib.axes.Axes
      :param x: The x coordinates of the data to be plotted.
      :type x: numpy.ndarray
      :param y: The y coordinates of the data to be plotted.
      :type y: numpy.ndarray
      :param values: The values of the data to be plotted.
      :type values: numpy.ndarray
      :param \*\*kwargs: Any additional arguments accepted by `matplotlib.axes.Axes.contour`.



   .. py:method:: contourf(ax, x, y, values, *args, **kwargs)

      Plot shaded contours using this `Style`.

      :param ax: The axes on which to plot the data.
      :type ax: matplotlib.axes.Axes
      :param x: The x coordinates of the data to be plotted.
      :type x: numpy.ndarray
      :param y: The y coordinates of the data to be plotted.
      :type y: numpy.ndarray
      :param values: The values of the data to be plotted.
      :type values: numpy.ndarray
      :param \*\*kwargs: Any additional arguments accepted by `matplotlib.axes.Axes.contourf`.



   .. py:method:: convert_units(values, source_units, short_name='')

      Convert some values from their source units to this `Style`'s units.

      :param values: The values to convert from their source units to this `Style`'s
                     units.
      :type values: numpy.ndarray
      :param source_units: The source units of the given values.
      :type source_units: str
      :param short_name: The short name of the variable, which is used to make extra
                         assumptions about the data's unit covnersion (for example,
                         temperature anomalies need special consideration when converting
                         between Celsius and Kelvin).
      :type short_name: str, optional



   .. py:method:: disjoint(*args, **kwargs)

      Create a disjoint legend for this `Style`.



   .. py:property:: extend

      Convenience access to 'extend' kwarg.


   .. py:method:: from_dict(kwargs)
      :classmethod:


      Create a `Style` from a dictionary.



   .. py:attribute:: gradients
      :value: None



   .. py:method:: imshow(ax, x, y, values, *args, **kwargs)

      Plot a pcolormesh using this `Style`.

      :param ax: The axes on which to plot the data.
      :type ax: matplotlib.axes.Axes
      :param x: The x coordinates of the data to be plotted.
      :type x: numpy.ndarray
      :param y: The y coordinates of the data to be plotted.
      :type y: numpy.ndarray
      :param values: The values of the data to be plotted.
      :type values: numpy.ndarray
      :param \*\*kwargs: Any additional arguments accepted by `matplotlib.axes.Axes.pcolormesh`.



   .. py:method:: legend(*args, **kwargs)

      Create the default legend for this `Style`.

      :param \*args: Arguments to be passed to the legend method.
      :type \*args: list
      :param \*\*kwargs: Keyword arguments to be passed to the legend method.
      :type \*\*kwargs: dict



   .. py:method:: levels(data=None)

      Generate levels specific to some data.

      :param data: The data for which to generate a list of levels.
      :type data: numpy.ndarray or xarray.DataArray or earthkit.data.core.Base

      :rtype: list



   .. py:method:: line(ax, x, y, values, *args, mode='linear', **kwargs)

      Plot a scatter plot using this `Style`.

      :param ax: The axes on which to plot the data.
      :type ax: matplotlib.axes.Axes
      :param x: The x coordinates of the data to be plotted.
      :type x: numpy.ndarray
      :param y: The y coordinates of the data to be plotted.
      :type y: numpy.ndarray
      :param values: The values of the data to be plotted.
      :type values: numpy.ndarray
      :param \*\*kwargs: Any additional arguments accepted by `matplotlib.axes.Axes.scatter`.



   .. py:attribute:: normalize
      :value: True



   .. py:method:: pcolormesh(ax, x, y, values, *args, **kwargs)

      Plot a pcolormesh using this `Style`.

      :param ax: The axes on which to plot the data.
      :type ax: matplotlib.axes.Axes
      :param x: The x coordinates of the data to be plotted.
      :type x: numpy.ndarray
      :param y: The y coordinates of the data to be plotted.
      :type y: numpy.ndarray
      :param values: The values of the data to be plotted.
      :type values: numpy.ndarray
      :param \*\*kwargs: Any additional arguments accepted by `matplotlib.axes.Axes.pcolormesh`.



   .. py:method:: plot(*args, **kwargs)

      Plot the data using the `Style`'s defaults.



   .. py:method:: quiver(ax, x, y, u, v, *args, **kwargs)

      Plot quiver arrows using this `Style`.

      :param ax: The axes on which to plot the data.
      :type ax: matplotlib.axes.Axes
      :param x: The x coordinates of the data to be plotted.
      :type x: numpy.ndarray
      :param y: The y coordinates of the data to be plotted.
      :type y: numpy.ndarray
      :param u: The u-component of the data to be plotted.
      :type u: numpy.ndarray
      :param v: The v-component of the data to be plotted.
      :type v: numpy.ndarray
      :param \*\*kwargs: Any additional arguments accepted by `matplotlib.axes.Axes.quiver`.



   .. py:attribute:: resample
      :value: None



   .. py:method:: save_legend_graphic(filename='legend.png', data=None, transparent=True, **kwargs)

      Save a standalone image of the legend associated with this `Style`.

      :param filename: The name of the image to save.
      :type filename: str
      :param data: It can sometimes be useful to pass some data in order to
                   automatically generate legend labels or color ranges, depending on
                   the `Style`.
      :type data: earthkit.data.core.Base, optional



   .. py:attribute:: scale_factor
      :value: None



   .. py:method:: scatter(ax, x, y, values, s=3, *args, **kwargs)

      Plot a scatter plot using this `Style`.

      :param ax: The axes on which to plot the data.
      :type ax: matplotlib.axes.Axes
      :param x: The x coordinates of the data to be plotted.
      :type x: numpy.ndarray
      :param y: The y coordinates of the data to be plotted.
      :type y: numpy.ndarray
      :param values: The values of the data to be plotted.
      :type values: numpy.ndarray
      :param \*\*kwargs: Any additional arguments accepted by `matplotlib.axes.Axes.scatter`.



   .. py:method:: to_contour_kwargs(data)

      Generate `contour` arguments required for plotting data in this `Style`.

      :param data: The data to be plotted using this `Style`.
      :type data: numpy.ndarray



   .. py:method:: to_contourf_kwargs(data)

      Generate `contourf` arguments required for plotting data in this `Style`.

      :param data: The data to be plotted using this `Style`.
      :type data: numpy.ndarray



   .. py:method:: to_matplotlib_kwargs(data, extend_levels=True)

      Generate matplotlib arguments required for plotting data in this `Style`.

      :param data: The data to be plotted using this `Style`.
      :type data: numpy.ndarray



   .. py:method:: to_pcolormesh_kwargs(data)

      Generate `pcolormesh` arguments required for plotting data in this `Style`.

      :param data: The data to be plotted using this `Style`.
      :type data: numpy.ndarray



   .. py:method:: to_quiver_kwargs(data)

      Generate `quiver` arguments required for plotting data in this `Style`.

      :param data: The data to be plotted using this `Style`.
      :type data: numpy.ndarray



   .. py:method:: to_scatter_kwargs(data)

      Generate `scatter` arguments required for plotting data in this `Style`.

      :param data: The data to be plotted using this `Style`.
      :type data: numpy.ndarray



   .. py:method:: tricontourf(ax, x, y, values, *args, **kwargs)

      Plot triangulated shaded contours using this `Style`.

      :param ax: The axes on which to plot the data.
      :type ax: matplotlib.axes.Axes
      :param x: The x coordinates of the data to be plotted.
      :type x: numpy.ndarray
      :param y: The y coordinates of the data to be plotted.
      :type y: numpy.ndarray
      :param values: The values of the data to be plotted.
      :type values: numpy.ndarray
      :param \*\*kwargs: Any additional arguments accepted by `matplotlib.axes.Axes.tricontourf`.



   .. py:method:: tripcolor(ax, x, y, values, *args, **kwargs)

      Plot triangulated shaded contours using this `Style`.

      :param ax: The axes on which to plot the data.
      :type ax: matplotlib.axes.Axes
      :param x: The x coordinates of the data to be plotted.
      :type x: numpy.ndarray
      :param y: The y coordinates of the data to be plotted.
      :type y: numpy.ndarray
      :param values: The values of the data to be plotted.
      :type values: numpy.ndarray
      :param \*\*kwargs: Any additional arguments accepted by `matplotlib.axes.Axes.tricontourf`.



   .. py:property:: units

      Formatted units for use in figure text.


   .. py:method:: values_to_colors(values, data=None)

      Convert a value or list of values to colors based on this `Style`.

      :param values: The values to convert to colors on this `Style`'s color scale.
      :type values: float or list of floats



   .. py:method:: vector(*args, **kwargs)

      Create a vector legend for this `Style`.