.. _ug_rcmpl: https://matplotlib.org/stable/tutorials/introductory/customizing.html .. _ug_mplrc: https://matplotlib.org/stable/tutorials/introductory/customizing.html#customizing-with-matplotlibrc-files .. _ug_config: Configuring UltraPlot =================== Overview -------- A dictionary-like object named :obj:`~ultraplot.config.rc`, belonging to the :class:`~ultraplot.config.Configurator` class, is created when you import UltraPlot. This is your one-stop shop for working with `matplotlib settings `_ stored in :obj:`~ultraplot.config.rc_matplotlib` (our name for the :obj:`~matplotlib.rcParams` dictionary) and :ref:`ultraplot settings ` stored in :obj:`~ultraplot.config.rc_ultraplot`. To change global settings on-the-fly, simply update :obj:`~ultraplot.config.rc` using either dot notation or as you would any other dictionary: .. code-block:: python import ultraplot as uplt uplt.rc.name = value uplt.rc['name'] = value uplt.rc.update(name1=value1, name2=value2) uplt.rc.update({'name1': value1, 'name2': value2}) To apply settings to a particular axes or figure, pass the setting to :func:`~ultraplot.axes.Axes.format` or :func:`~ultraplot.figure.Figure.format`: .. code-block:: python import ultraplot as uplt fig, ax = uplt.subplots() ax.format(name1=value1, name2=value2) ax.format(rc_kw={'name1': value1, 'name2': value2}) To temporarily modify settings for particular figure(s), pass the setting to the :func:`~ultraplot.config.Configurator.context` command: .. code-block:: python import ultraplot as uplt with uplt.rc.context(name1=value1, name2=value2): fig, ax = uplt.subplots() with uplt.rc.context({'name1': value1, 'name2': value2}): fig, ax = uplt.subplots() In all of these examples, if the setting name contains dots, you can simply omit the dots. For example, to change the :rcraw:`title.loc` property, the following approaches are valid: .. code-block:: python import ultraplot as uplt # Apply globally uplt.rc.titleloc = value uplt.rc.update(titleloc=value) # Apply locally fig, ax = uplt.subplots() ax.format(titleloc=value) .. _ug_rcmatplotlib: Matplotlib settings ------------------- Matplotlib settings are natively stored in the :obj:`~matplotlib.rcParams` dictionary. UltraPlot makes this dictionary available in the top-level namespace as :obj:`~ultraplot.config.rc_matplotlib`. All matplotlib settings can also be changed with :obj:`~ultraplot.config.rc`. Details on the matplotlib settings can be found on `this page `_. .. _ug_rcUltraPlot: UltraPlot settings ---------------- UltraPlot settings are natively stored in the :obj:`~ultraplot.config.rc_ultraplot` dictionary. They should almost always be changed with :obj:`~ultraplot.config.rc` rather than :obj:`~ultraplot.config.rc_ultraplot` to ensure that :ref:`meta-settings ` are synced. These settings are not found in :obj:`~matplotlib.rcParams` -- they either control UltraPlot-managed features (e.g., a-b-c labels and geographic gridlines) or they represent existing matplotlib settings with more clear or succinct names. Here's a broad overview of the new settings: * The ``subplots`` category includes settings that control the default subplot layout and padding. * The ``geo`` category contains settings related to geographic plotting, including the geographic backend, gridline label settings, and map bound settings. * The ``abc``, ``title``, and ``label`` categories control a-b-c labels, axes titles, and axis labels. The latter two replace ``axes.title`` and ``axes.label``. * The ``suptitle``, ``leftlabel``, ``toplabel``, ``rightlabel``, and ``bottomlabel`` categories control the figure titles and subplot row and column labels. * The ``formatter`` category supersedes matplotlib's ``axes.formatter`` and includes settings that control the :class:`~ultraplot.ticker.AutoFormatter` behavior. * The ``cmap`` category supersedes matplotlib's ``image`` and includes settings relevant to colormaps and the :class:`~ultraplot.colors.DiscreteNorm` normalizer. * The ``tick`` category supersedes matplotlib's ``xtick`` and ``ytick`` to simultaneously control *x* and *y* axis tick and tick label settings. * The matplotlib ``grid`` category includes new settings that control the meridian and parallel gridlines and gridline labels managed by :class:`~ultraplot.axes.GeoAxes`. * The ``gridminor`` category optionally controls minor gridlines separately from major gridlines. * The ``land``, ``ocean``, ``rivers``, ``lakes``, ``borders``, and ``innerborders`` categories control geographic content managed by :class:`~ultraplot.axes.GeoAxes`. .. _ug_rcmeta: Meta-settings ------------- Some UltraPlot settings may be more accurately described as "meta-settings", as they change several matplotlib and UltraPlot settings at once (note that settings are only synced when they are changed on the :obj:`~ultraplot.config.rc` object rather than the :obj:`~ultraplot.config.rc_UltraPlot` and :obj:`~ultraplot.config.rc_matplotlib` dictionaries). Here's a broad overview of the "meta-settings": * Setting :rcraw:`font.small` (or, equivalently, :rcraw:`fontsmall`) changes the :rcraw:`tick.labelsize`, :rcraw:`grid.labelsize`, :rcraw:`legend.fontsize`, and :rcraw:`axes.labelsize`. * Setting :rcraw:`font.large` (or, equivalently, :rcraw:`fontlarge`) changes the :rcraw:`abc.size`, :rcraw:`title.size`, :rcraw:`suptitle.size`, :rcraw:`leftlabel.size`, :rcraw:`toplabel.size`, :rcraw:`rightlabel.size` :rcraw:`bottomlabel.size`. * Setting :rcraw:`meta.color` changes the :rcraw:`axes.edgecolor`, :rcraw:`axes.labelcolor` :rcraw:`tick.labelcolor`, :rcraw:`hatch.color`, :rcraw:`xtick.color`, and :rcraw:`ytick.color` . * Setting :rcraw:`meta.width` changes the :rcraw:`axes.linewidth` and the major and minor tickline widths :rcraw:`xtick.major.width`, :rcraw:`ytick.major.width`, :rcraw:`xtick.minor.width`, and :rcraw:`ytick.minor.width`. The minor tickline widths are scaled by :rcraw:`tick.widthratio` (or, equivalently, :rcraw:`tickwidthratio`). * Setting :rcraw:`tick.len` (or, equivalently, :rcraw:`ticklen`) changes the major and minor tickline lengths :rcraw:`xtick.major.size`, :rcraw:`ytick.major.size`, :rcraw:`xtick.minor.size`, and :rcraw:`ytick.minor.size`. The minor tickline lengths are scaled by :rcraw:`tick.lenratio` (or, equivalently, :rcraw:`ticklenratio`). * Setting :rcraw:`grid.color`, :rcraw:`grid.linewidth`, :rcraw:`grid.linestyle`, or :rcraw:`grid.alpha` also changes the corresponding ``gridminor`` settings. Any distinct ``gridminor`` settings must be applied after ``grid`` settings. * Setting :rcraw:`grid.linewidth` changes the major and minor gridline widths. The minor gridline widths are scaled by :rcraw:`grid.widthratio` (or, equivalently, :rcraw:`gridwidthratio`). * Setting :rcraw:`title.border` or :rcraw:`abc.border` to ``True`` automatically sets :rcraw:`title.bbox` or :rcraw:`abc.bbox` to ``False``, and vice versa. .. _ug_rctable: Table of settings ----------------- A comprehensive table of the new UltraPlot settings is shown below. .. include:: _static/rctable.rst .. _ug_ultraplotrc: The ultraplotrc file ------------------ When you import UltraPlot for the first time, a ``ultraplotrc`` file is generated with all lines commented out. This file is just like `matplotlibrc `_, except it controls both matplotlib *and* UltraPlot settings. The syntax is essentially the same as matplotlibrc, and the file path is very similar to matplotlibrc. On most platforms it is found in ``~/.UltraPlot/ultraplotrc``, but a loose hidden file in the home directory named ``~/.ultraplotrc`` is also allowed (use :func:`~ultraplot.config.Configurator.user_file` to print the path). To update this file after a version change, simply remove it and restart your python session. To change the global :obj:`~ultraplot.config.rc` settings, edit and uncomment the lines in the ``ultraplotrc`` file. To change the settings for a specific project, place a file named either ``.ultraplotrc`` or ``ultraplotrc`` in the same directory as your python session, or in an arbitrary parent directory. To generate a ``ultraplotrc`` file containing the settings you have changed during a python session, use :func:`~ultraplot.config.Configurator.save` (use :func:`~ultraplot.config.Configurator.changed` to preview a dictionary of the changed settings). To explicitly load a ``ultraplotrc`` file, use :func:`~ultraplot.config.Configator.load`. As an example, a ``ultraplotrc`` file containing the default settings is shown below. .. include:: _static/ultraplotrc :literal: