Add default theme configuration to Plot (#3223)

* Improve Plot.theme docstring * First pass at Plot.config and Plot.config.theme * Validate rc params in Plot.theme * Add documentation for Plot.config.theme * Restrict Plot.theme.config.update to 'style' groups * Add docstrings for Plot.config objects * Clean up notebook * Fix notebook * Add type hints
mwaskom · Jan 16, 2023 · a47b97e · a47b97e
1 parent dce8afd
commit a47b97e
Show file tree

Hide file tree

Showing 6 changed files with 385 additions and 66 deletions.
diff --git a/doc/_docstrings/objects.Plot.config.ipynb b/doc/_docstrings/objects.Plot.config.ipynb
@@ -0,0 +1,124 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "a38a6fed-51de-4dbc-8d5b-4971d06acf2e",
+   "metadata": {
+    "tags": [
+     "hide"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "import seaborn.objects as so"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "38081259-9382-4623-8d67-09aa114e0949",
+   "metadata": {},
+   "source": [
+    "Theme configuration\n",
+    "^^^^^^^^^^^^^^^^^^^\n",
+    "\n",
+    "The theme is a dictionary of matplotlib `rc parameters <https://matplotlib.org/stable/tutorials/introductory/customizing.html>`_. You can set individual parameters directly:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "34ca0ce9-5284-47b6-8281-180709dbec89",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "so.Plot.config.theme[\"axes.facecolor\"] = \"white\""
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "b3f93646-8370-4c16-ace4-7bb811688758",
+   "metadata": {},
+   "source": [
+    "To change the overall style of the plot, update the theme with a dictionary of parameters, perhaps from one of seaborn's theming functions:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8e5eb7d3-cc7a-4231-b887-db37045f3db4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from seaborn import axes_style\n",
+    "so.Plot.config.theme.update(axes_style(\"whitegrid\"))"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "f7c7bd9c-722d-45db-902a-c2dcdef571ee",
+   "metadata": {},
+   "source": [
+    "To sync :class:`Plot` with matplotlib's global state, pass the `rcParams` dictionary:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "fd1cd96e-1a2c-474a-809f-20b8c4794578",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import matplotlib as mpl\n",
+    "so.Plot.config.theme.update(mpl.rcParams)"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "7e305ec1-4a83-411f-91df-aee2ec4d1806",
+   "metadata": {},
+   "source": [
+    "The theme can also be reset back to seaborn defaults:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e3146b1d-1b5e-464f-a631-e6d6caf161b3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "so.Plot.config.theme.reset()"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "eae5da42-cf7f-41c9-b13d-8fa25e5cf0be",
+   "metadata": {},
+   "source": [
+    "Changes made through this interface will apply to all subsequent :class:`Plot` instances. Use the :meth:`Plot.theme` method to modify the theme on a plot-by-plot basis."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "py310",
+   "language": "python",
+   "name": "py310"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/doc/_docstrings/objects.Plot.theme.ipynb b/doc/_docstrings/objects.Plot.theme.ipynb
@@ -32,7 +32,7 @@
    "outputs": [],
    "source": [
     "p = (\n",
-    "    so.Plot(anscombe, \"x\", \"y\")\n",
+    "    so.Plot(anscombe, \"x\", \"y\", color=\"dataset\")\n",
     "    .facet(\"dataset\", wrap=2)\n",
     "    .add(so.Line(), so.PolyFit(order=1))\n",
     "    .add(so.Dot())\n",
@@ -55,7 +55,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "p.theme({\"axes.facecolor\": \"w\", \"axes.edgecolor\": \"C0\"})"
+    "p.theme({\"axes.facecolor\": \"w\", \"axes.edgecolor\": \"slategray\"})"
    ]
   },
   {
@@ -77,8 +77,8 @@
    ]
   },
   {
-   "cell_type": "markdown",
-   "id": "2c8fa27e-d1ea-4376-a717-c3059ba1d272",
+   "cell_type": "raw",
+   "id": "0186e852-9c47-4da1-999a-f61f41687dfb",
    "metadata": {},
    "source": [
     "Apply seaborn styles by passing in the output of the style functions:"
@@ -92,7 +92,7 @@
    "outputs": [],
    "source": [
     "from seaborn import axes_style\n",
-    "p.theme({**axes_style(\"ticks\")})"
+    "p.theme(axes_style(\"ticks\"))"
    ]
   },
   {
@@ -111,7 +111,15 @@
    "outputs": [],
    "source": [
     "from matplotlib import style\n",
-    "p.theme({**style.library[\"fivethirtyeight\"]})"
+    "p.theme(style.library[\"fivethirtyeight\"])"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "e1870ad0-48a0-4fd1-a557-d337979bc845",
+   "metadata": {},
+   "source": [
+    "Multiple parameter dictionaries should be passed to the same function call. On Python 3.9+, you can use dictionary union syntax for this:"
    ]
   },
   {
@@ -120,7 +128,37 @@
    "id": "dec4db5b-1b2b-4b9d-97e1-9cf0f20d6b83",
    "metadata": {},
    "outputs": [],
-   "source": []
+   "source": [
+    "from seaborn import plotting_context\n",
+    "p.theme(axes_style(\"whitegrid\") | plotting_context(\"talk\"))"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "7cc09720-887d-463e-a162-1e3ef8a46ad9",
+   "metadata": {},
+   "source": [
+    "The default theme for all :class:`Plot` instances can be changed using the :attr:`Plot.config` attribute:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4e535ddf-d394-4ce1-8d09-4dc95ca314b4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "so.Plot.config.theme.update(axes_style(\"white\"))\n",
+    "p"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "2f19f645-3f8d-4044-82e9-4a87165a0078",
+   "metadata": {},
+   "source": [
+    "See :ref:`Plot Configuration <plot_config>` for more details."
+   ]
   }
  ],
  "metadata": {

diff --git a/doc/_templates/autosummary/plot.rst b/doc/_templates/autosummary/plot.rst
@@ -4,54 +4,66 @@
 
 .. autoclass:: {{ objname }}
 
-   {% block methods %}
+{% block methods %}
 
-   .. rubric:: Specification methods
+Methods
+~~~~~~~
 
-   .. autosummary::
-      :toctree: ./
-      :nosignatures:
+.. rubric:: Specification methods
 
-      ~Plot.add
-      ~Plot.scale
+.. autosummary::
+   :toctree: ./
+   :nosignatures:
 
-   .. rubric:: Subplot methods
+   ~Plot.add
+   ~Plot.scale
 
-   .. autosummary::
-      :toctree: ./
-      :nosignatures:
+.. rubric:: Subplot methods
 
-      ~Plot.facet
-      ~Plot.pair
+.. autosummary::
+   :toctree: ./
+   :nosignatures:
 
-   .. rubric:: Customization methods
+   ~Plot.facet
+   ~Plot.pair
 
-   .. autosummary::
-      :toctree: ./
-      :nosignatures:
+.. rubric:: Customization methods
 
-      ~Plot.layout
-      ~Plot.label
-      ~Plot.limit
-      ~Plot.share
-      ~Plot.theme
+.. autosummary::
+   :toctree: ./
+   :nosignatures:
 
-   .. rubric:: Integration methods
+   ~Plot.layout
+   ~Plot.label
+   ~Plot.limit
+   ~Plot.share
+   ~Plot.theme
 
-   .. autosummary::
-      :toctree: ./
-      :nosignatures:
+.. rubric:: Integration methods
 
-      ~Plot.on
+.. autosummary::
+   :toctree: ./
+   :nosignatures:
 
-   .. rubric:: Output methods
+   ~Plot.on
 
-   .. autosummary::
-      :toctree: ./
-      :nosignatures:
+.. rubric:: Output methods
 
-      ~Plot.plot
-      ~Plot.save
-      ~Plot.show
+.. autosummary::
+   :toctree: ./
+   :nosignatures:
 
-   {% endblock %}
+   ~Plot.plot
+   ~Plot.save
+   ~Plot.show
+
+{% endblock %}
+
+.. _plot_config:
+
+Configuration
+~~~~~~~~~~~~~
+
+The :class:`Plot` object's default behavior can be configured through its :attr:`Plot.config` attribute. Notice that this is a property of the class, not a method on an instance.
+
+.. include:: ../docstrings/objects.Plot.config.rst
diff --git a/doc/_tutorial/objects_interface.ipynb b/doc/_tutorial/objects_interface.ipynb
@@ -1043,16 +1043,27 @@
    "outputs": [],
    "source": [
     "from seaborn import axes_style\n",
-    "so.Plot().theme({**axes_style(\"whitegrid\"), \"grid.linestyle\": \":\"})"
+    "theme_dict = {**axes_style(\"whitegrid\"), \"grid.linestyle\": \":\"}\n",
+    "so.Plot().theme(theme_dict)"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "475d5157-5e88-473e-991f-528219ed3744",
+   "metadata": {},
+   "source": [
+    "To change the theme for all :class:`Plot` instances, update the settings in :attr:`Plot.config:"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "8ac5e809-e4a0-4c08-b9c0-fa78bd93eb82",
+   "id": "41ac347c-766f-495c-8a7f-43fee8cad29a",
    "metadata": {},
    "outputs": [],
-   "source": []
+   "source": [
+    "so.Plot.config.theme.update(theme_dict)"
+   ]
   }
  ],
  "metadata": {