Add set_theme() to replace set() (#2253)

* Add set_theme function and change set to an alias * Add test * Change set -> set_theme everywhere * Update aesthetics tutorial * Update API page and release notes * Expose set_theme as public API (cherry picked from commit 0b7697d)
mwaskom · Sep 8, 2020 · afba270 · afba270
1 parent f83941c
commit afba270
Show file tree

Hide file tree

Showing 81 changed files with 161 additions and 123 deletions.
diff --git a/doc/api.rst b/doc/api.rst
@@ -116,20 +116,21 @@ Joint grids
 
 .. _style_api:
 
-Style control 
--------------
+Themes
+------
 
 .. autosummary::
     :toctree: generated/
 
-    set
+    set_theme
     axes_style
     set_style
     plotting_context
     set_context
     set_color_codes
     reset_defaults
     reset_orig
+    set
 
 .. _palette_api:
 

diff --git a/doc/docstrings/FacetGrid.ipynb b/doc/docstrings/FacetGrid.ipynb
@@ -11,7 +11,7 @@
    "outputs": [],
    "source": [
     "import seaborn as sns\n",
-    "sns.set(style=\"ticks\")"
+    "sns.set_theme(style=\"ticks\")"
    ]
   },
   {

diff --git a/doc/docstrings/JointGrid.ipynb b/doc/docstrings/JointGrid.ipynb
@@ -11,7 +11,7 @@
    "outputs": [],
    "source": [
     "import seaborn as sns\n",
-    "sns.set()"
+    "sns.set_theme()"
    ]
   },
   {

diff --git a/doc/docstrings/PairGrid.ipynb b/doc/docstrings/PairGrid.ipynb
@@ -10,7 +10,7 @@
    },
    "outputs": [],
    "source": [
-    "import seaborn as sns; sns.set()\n",
+    "import seaborn as sns; sns.set_theme()\n",
     "import matplotlib.pyplot as plt"
    ]
   },

diff --git a/doc/docstrings/color_palette.ipynb b/doc/docstrings/color_palette.ipynb
@@ -10,7 +10,7 @@
    },
    "outputs": [],
    "source": [
-    "import seaborn as sns; sns.set()"
+    "import seaborn as sns; sns.set_theme()"
    ]
   },
   {

diff --git a/doc/docstrings/displot.ipynb b/doc/docstrings/displot.ipynb
@@ -10,7 +10,7 @@
    },
    "outputs": [],
    "source": [
-    "import seaborn as sns; sns.set(style=\"ticks\")"
+    "import seaborn as sns; sns.set_theme(style=\"ticks\")"
    ]
   },
   {

diff --git a/doc/docstrings/ecdfplot.ipynb b/doc/docstrings/ecdfplot.ipynb
@@ -17,7 +17,7 @@
    },
    "outputs": [],
    "source": [
-    "import seaborn as sns; sns.set()"
+    "import seaborn as sns; sns.set_theme()"
    ]
   },
   {

diff --git a/doc/docstrings/histplot.ipynb b/doc/docstrings/histplot.ipynb
@@ -11,7 +11,7 @@
    "outputs": [],
    "source": [
     "import seaborn as sns\n",
-    "sns.set(style=\"white\")"
+    "sns.set_theme(style=\"white\")"
    ]
   },
   {

diff --git a/doc/docstrings/jointplot.ipynb b/doc/docstrings/jointplot.ipynb
@@ -11,7 +11,7 @@
    "outputs": [],
    "source": [
     "import seaborn as sns\n",
-    "sns.set(style=\"white\")"
+    "sns.set_theme(style=\"white\")"
    ]
   },
   {

diff --git a/doc/docstrings/kdeplot.ipynb b/doc/docstrings/kdeplot.ipynb
@@ -10,7 +10,7 @@
    },
    "outputs": [],
    "source": [
-    "import seaborn as sns; sns.set()"
+    "import seaborn as sns; sns.set_theme()"
    ]
   },
   {

diff --git a/doc/docstrings/lineplot.ipynb b/doc/docstrings/lineplot.ipynb
@@ -15,7 +15,7 @@
     "import seaborn as sns\n",
     "import matplotlib as mpl\n",
     "import matplotlib.pyplot as plt\n",
-    "sns.set()"
+    "sns.set_theme()"
    ]
   },
   {

diff --git a/doc/docstrings/pairplot.ipynb b/doc/docstrings/pairplot.ipynb
@@ -11,7 +11,7 @@
    "outputs": [],
    "source": [
     "import seaborn as sns\n",
-    "sns.set(style=\"ticks\")"
+    "sns.set_theme(style=\"ticks\")"
    ]
   },
   {

diff --git a/doc/docstrings/relplot.ipynb b/doc/docstrings/relplot.ipynb
@@ -19,7 +19,7 @@
    "source": [
     "import seaborn as sns\n",
     "import matplotlib.pyplot as plt\n",
-    "sns.set(style=\"ticks\")"
+    "sns.set_theme(style=\"ticks\")"
    ]
   },
   {

diff --git a/doc/docstrings/rugplot.ipynb b/doc/docstrings/rugplot.ipynb
@@ -13,7 +13,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "import seaborn as sns; sns.set()\n",
+    "import seaborn as sns; sns.set_theme()\n",
     "tips = sns.load_dataset(\"tips\")\n",
     "sns.kdeplot(data=tips, x=\"total_bill\")\n",
     "sns.rugplot(data=tips, x=\"total_bill\")"

diff --git a/doc/docstrings/scatterplot.ipynb b/doc/docstrings/scatterplot.ipynb
@@ -14,7 +14,7 @@
     "import pandas as pd\n",
     "import seaborn as sns\n",
     "import matplotlib.pyplot as plt\n",
-    "sns.set()"
+    "sns.set_theme()"
    ]
   },
   {

diff --git a/doc/introduction.ipynb b/doc/introduction.ipynb
@@ -35,7 +35,7 @@
     "import seaborn as sns\n",
     "\n",
     "# Apply the default theme\n",
-    "sns.set()\n",
+    "sns.set_theme()\n",
     "\n",
     "# Load an example dataset\n",
     "tips = sns.load_dataset(\"tips\")\n",
@@ -89,7 +89,7 @@
    "outputs": [],
    "source": [
     "# Apply the default theme\n",
-    "sns.set()"
+    "sns.set_theme()"
    ]
   },
   {
@@ -409,7 +409,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "sns.set(style=\"ticks\", font_scale=1.25)\n",
+    "sns.set_theme(style=\"ticks\", font_scale=1.25)\n",
     "g = sns.relplot(\n",
     "    data=penguins,\n",
     "    x=\"bill_length_mm\", y=\"bill_depth_mm\", hue=\"body_mass_g\",\n",

diff --git a/doc/releases/v0.11.0.txt b/doc/releases/v0.11.0.txt
@@ -110,6 +110,11 @@ Documentation improvements
 
 - |Docs| Improved cross-linking within the seaborn docs and between the seaborn and matplotlib docs.
 
+Theming
+~~~~~~~
+
+- |API| The :func:`set` function has been renamed to :func:`set_theme` for more clarity about what it does. For the foreseeable future, :func:`set` will remain as an alias, but it is recommended to update your code.
+
 Relational plots
 ^^^^^^^^^^^^^^^^
 

diff --git a/doc/tutorial/aesthetics.ipynb b/doc/tutorial/aesthetics.ipynb
@@ -94,7 +94,7 @@
    "cell_type": "raw",
    "metadata": {},
    "source": [
-    "To switch to seaborn defaults, simply call the :func:`set` function."
+    "To switch to seaborn defaults, simply call the :func:`set_theme` function."
    ]
   },
   {
@@ -103,15 +103,15 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "sns.set()\n",
+    "sns.set_theme()\n",
     "sinplot()"
    ]
   },
   {
    "cell_type": "raw",
    "metadata": {},
    "source": [
-    "(Note that in versions of seaborn prior to 0.8, :func:`set` was called on import. On later versions, it must be explicitly invoked).\n",
+    "(Note that in versions of seaborn prior to 0.8, :func:`set_theme` was called on import. On later versions, it must be explicitly invoked).\n",
     "\n",
     "Seaborn splits matplotlib parameters into two independent groups. The first group sets the aesthetic style of the plot, and the second scales various elements of the figure so that it can be easily incorporated into different contexts.\n",
     "\n",
@@ -283,7 +283,7 @@
     "Overriding elements of the seaborn styles\n",
     "-----------------------------------------\n",
     "\n",
-    "If you want to customize the seaborn styles, you can pass a dictionary of parameters to the ``rc`` argument of :func:`axes_style` and :func:`set_style`. Note that you can only override the parameters that are part of the style definition through this method. (However, the higher-level :func:`set` function takes a dictionary of any matplotlib parameters).\n",
+    "If you want to customize the seaborn styles, you can pass a dictionary of parameters to the ``rc`` argument of :func:`axes_style` and :func:`set_style`. Note that you can only override the parameters that are part of the style definition through this method. (However, the higher-level :func:`set_theme` function takes a dictionary of any matplotlib parameters).\n",
     "\n",
     "If you want to see what parameters are included, you can just call the function with no arguments, which will return the current settings:"
    ]
@@ -325,7 +325,7 @@
     "\n",
     "A separate set of parameters control the scale of plot elements, which should let you use the same code to make plots that are suited for use in settings where larger or smaller plots are appropriate.\n",
     "\n",
-    "First let's reset the default parameters by calling :func:`set`:"
+    "First let's reset the default parameters by calling :func:`set_theme`:"
    ]
   },
   {
@@ -334,7 +334,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "sns.set()"
+    "sns.set_theme()"
    ]
   },
   {

diff --git a/doc/tutorial/axis_grids.ipynb b/doc/tutorial/axis_grids.ipynb
@@ -54,7 +54,7 @@
    },
    "outputs": [],
    "source": [
-    "sns.set(style=\"ticks\")"
+    "sns.set_theme(style=\"ticks\")"
    ]
   },
   {

diff --git a/doc/tutorial/categorical.ipynb b/doc/tutorial/categorical.ipynb
@@ -56,7 +56,7 @@
    "source": [
     "import seaborn as sns\n",
     "import matplotlib.pyplot as plt\n",
-    "sns.set(style=\"ticks\", color_codes=True)"
+    "sns.set_theme(style=\"ticks\", color_codes=True)"
    ]
   },
   {

diff --git a/doc/tutorial/color_palettes.ipynb b/doc/tutorial/color_palettes.ipynb
@@ -38,7 +38,7 @@
     "import numpy as np\n",
     "import seaborn as sns\n",
     "import matplotlib.pyplot as plt\n",
-    "sns.set(style=\"white\", rc={\"xtick.major.pad\": 1, \"ytick.major.pad\": 1})"
+    "sns.set_theme(style=\"white\", rc={\"xtick.major.pad\": 1, \"ytick.major.pad\": 1})"
    ]
   },
   {

diff --git a/doc/tutorial/data_structure.ipynb b/doc/tutorial/data_structure.ipynb
@@ -39,7 +39,7 @@
     "import numpy as np\n",
     "import pandas as pd\n",
     "import seaborn as sns\n",
-    "sns.set()"
+    "sns.set_theme()"
    ]
   },
   {

diff --git a/doc/tutorial/distributions.ipynb b/doc/tutorial/distributions.ipynb
@@ -38,7 +38,7 @@
    "outputs": [],
    "source": [
     "%matplotlib inline\n",
-    "import seaborn as sns; sns.set()"
+    "import seaborn as sns; sns.set_theme()"
    ]
   },
   {

diff --git a/doc/tutorial/function_overview.ipynb b/doc/tutorial/function_overview.ipynb
@@ -38,7 +38,7 @@
     "import seaborn as sns\n",
     "import matplotlib.pyplot as plt\n",
     "from IPython.display import HTML\n",
-    "sns.set()"
+    "sns.set_theme()"
    ]
   },
   {

diff --git a/doc/tutorial/regression.ipynb b/doc/tutorial/regression.ipynb
@@ -47,7 +47,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "sns.set(color_codes=True)"
+    "sns.set_theme(color_codes=True)"
    ]
   },
   {

diff --git a/doc/tutorial/relational.ipynb b/doc/tutorial/relational.ipynb
@@ -40,7 +40,7 @@
     "import pandas as pd\n",
     "import matplotlib.pyplot as plt\n",
     "import seaborn as sns\n",
-    "sns.set(style=\"darkgrid\")"
+    "sns.set_theme(style=\"darkgrid\")"
    ]
   },
   {

diff --git a/examples/anscombes_quartet.py b/examples/anscombes_quartet.py
@@ -5,7 +5,7 @@
 _thumb: .4, .4
 """
 import seaborn as sns
-sns.set(style="ticks")
+sns.set_theme(style="ticks")
 
 # Load the example dataset for Anscombe's quartet
 df = sns.load_dataset("anscombe")

diff --git a/examples/different_scatter_variables.py b/examples/different_scatter_variables.py
@@ -7,7 +7,7 @@
 """
 import seaborn as sns
 import matplotlib.pyplot as plt
-sns.set(style="whitegrid")
+sns.set_theme(style="whitegrid")
 
 # Load the example diamonds dataset
 diamonds = sns.load_dataset("diamonds")

diff --git a/examples/errorband_lineplots.py b/examples/errorband_lineplots.py
@@ -6,7 +6,7 @@
 
 """
 import seaborn as sns
-sns.set(style="darkgrid")
+sns.set_theme(style="darkgrid")
 
 # Load an example dataset with long-form data
 fmri = sns.load_dataset("fmri")

diff --git a/examples/faceted_histogram.py b/examples/faceted_histogram.py
@@ -6,7 +6,7 @@
 """
 import seaborn as sns
 
-sns.set(style="darkgrid")
+sns.set_theme(style="darkgrid")
 df = sns.load_dataset("penguins")
 sns.displot(
     df, x="flipper_length_mm", col="species", row="sex",

diff --git a/examples/faceted_lineplot.py b/examples/faceted_lineplot.py
@@ -6,7 +6,7 @@
 
 """
 import seaborn as sns
-sns.set(style="ticks")
+sns.set_theme(style="ticks")
 
 dots = sns.load_dataset("dots")
 

diff --git a/examples/grouped_barplot.py b/examples/grouped_barplot.py
@@ -5,7 +5,7 @@
 _thumb: .36, .5
 """
 import seaborn as sns
-sns.set(style="whitegrid")
+sns.set_theme(style="whitegrid")
 
 penguins = sns.load_dataset("penguins")
 

diff --git a/examples/grouped_boxplot.py b/examples/grouped_boxplot.py
@@ -6,7 +6,7 @@
 
 """
 import seaborn as sns
-sns.set(style="ticks", palette="pastel")
+sns.set_theme(style="ticks", palette="pastel")
 
 # Load the example tips dataset
 tips = sns.load_dataset("tips")

diff --git a/examples/grouped_violinplots.py b/examples/grouped_violinplots.py
@@ -5,7 +5,7 @@
 _thumb: .44, .47
 """
 import seaborn as sns
-sns.set(style="whitegrid")
+sns.set_theme(style="whitegrid")
 
 # Load the example tips dataset
 tips = sns.load_dataset("tips")

diff --git a/examples/heat_scatter.py b/examples/heat_scatter.py
@@ -6,7 +6,7 @@
 
 """
 import seaborn as sns
-sns.set(style="whitegrid")
+sns.set_theme(style="whitegrid")
 
 # Load the brain networks dataset, select subset, and collapse the multi-index
 df = sns.load_dataset("brain_networks", header=[0, 1, 2], index_col=0)