Configuration

The `rcParams`

Hint

If you are using the psyplot-gui module, you can also use the preferences widget to modify the configuration. See Configuration of the GUI.

Psyplot, and especially it’s plugins have a lot of configuration values. Our rcParams handling is motivated by matplotlib although we extended the possibilities of it’s matplotlib.RcParams class. Our rcParams are stored in the psyplot.rcParams object. Without any plugins, this looks like

In [1]: from psyplot import rcParams

In [2]: print(rcParams.dump(exclude_keys=[]))
# Configuration parameters of the psyplot module
# 
# You can copy this file (or parts of it) to another path and save it as
# psyplotrc.yml. The directory should then be stored in the PSYPLOTCONFIGDIR
# environment variable.
# 
# Created with python
# 
# 3.9.19 (main, Jul 10 2024, 19:03:52) 
# [GCC 12.2.0]
# 
# 
# Automatically draw the figures if the draw keyword in the update and start_update methods is None
auto_draw: true
# Automatically show the figures after the update andstart_update methods
auto_show: false
# path for supplementary data
datapath: null
# interpolation method to calculate 2D-bounds (see the `kind` parameterin the :meth:`psyplot.data.CFDecoder.get_plotbounds` method)
decoder.interp_kind: linear
# names that shall be interpreted as the time dimension
decoder.t: !!set
  time: null
# names that shall be interpreted as the longitudinal x dim
decoder.x: !!set {}
# names that shall be interpreted as the latitudinal y dim
decoder.y: !!set {}
# names that shall be interpreted as the vertical z dim
decoder.z: !!set {}
# Boolean flag to control whether CDOs (Climate Data Operators) should be used to calculate grid weights. If None, they are tried to be used.
gridweights.use_cdo: null
# default value (boolean) for the auto_update parameter in the initialization of Plotter, Project, etc. instances
lists.auto_update: true
# formatoption keys and values that are defined by the user to be used by
# the specified plotters. For example to modify the title of all
# :class:`psyplot.plotter.maps.FieldPlotter` instances, set
# ``{'plotter.fieldplotter.title': 'my title'}``
plotter.user: {}
# A list of filenames with trusted presets
presets.trusted: []
# boolean controlling whether all plotters specified in the project.plotters item will be automatically imported when importing the psyplot.project module
project.auto_import: false
# boolean controlling whether the seaborn module shall be imported when importing the project module. If None, it is only tried to import the module.
project.import_seaborn: null
# mapping from identifier to plotter definitions for the Project class. See the :func:`psyplot.project.register_plotter` function for possible keywords and values. See :attr:`psyplot.project.registered_plotters` for examples.
project.plotters: {}
# Plot methods that are defined by the user and overwrite those in the``'project.plotters'`` key. Use this if you want to define your own plotters without writing a plugin
project.plotters.user: {}

You can use this object like a dictionary and modify the default values. For example, if you do not want, that the seaborn package is imported when the psyplot.project module is imported, you can simply do this via:

In [3]: rcParams["project.import_seaborn"] = False

Additionally, you can make these changes permanent. At every first import of the psyplot module, the rcParams are updated from a yaml configuration file. On Linux and OS X, this is stored under $HOME/.config/psyplot/psyplotrc.yml, under Windows it is stored at $HOME/.psyplot/psyplotrc.yml. But use the psyplot.config.rcsetup.psyplot_fname() function, to get the correct location.

To make our changes from above permanent, we could just do:

In [4]: import yaml
   ...: from psyplot.config.rcsetup import psyplot_fname
   ...: 

In [5]: with open(psyplot_fname(if_exists=False), "w") as f:
   ...:     yaml.dump({"project.import_seaborn": False}, f)
   ...: 

# or we use the dump method
In [6]: rcParams.dump(
   ...:     psyplot_fname(if_exists=False),
   ...:     overwrite=True,  # update the existing file
   ...:     include_keys=["project.import_seaborn"],
   ...: )
   ...: 

Default formatoptions

The psyplot plugins, (psy_simple.plugin, psy_maps.plugin, etc.) define their own rcParams instance. When the plugins are loaded at the first import of psyplot, these instances update psyplot.rcParams.

The update mainly defines the default values for the plotters defined by that plugin. However, it is not always obvious, which key in the psyplot.rcParams belongs to which formatoption. For this purpose, however, you can use the default_key attribute. For example, the title formatoption has the default_key

In [7]: import psyplot.project as psy

In [8]: plotter = psy.plot.lineplot.plotter_cls()
   ...: plotter.title.default_key
   ...: 
Out[8]: 'plotter.baseplotter.title'

As our plotters are based on inheritance, the default values use it, too. Therefore, the FieldPlotter, the underlying plotter for the mapplot plot method, uses the same configuration value in the psyplot.rcParams:

In [9]: plotter = psy.plot.mapplot.plotter_cls()
   ...: plotter.title.default_key
   ...: 
Out[9]: 'plotter.baseplotter.title'

Configuration

The rcParams

Default formatoptions

The `rcParams`