Modernize and enhance violinplot (#3353)

* Add very basic new violinplot code

* Break apart violin plotting into two loops

* Update saturation

* Take advantage of new common methods for dodging and scale inversion

* Get all density normalizations working (with common norm)

* Get split violins and singular KDEs working

* Other KDE parameters, including bw deprecation

* Add inner points and sticks

* Add inner quartiles and box

* Add group-specific normalization (scale_hue=False)

* Add fill, inner_kwargs, and rename scale/scale_hue

* Allow prefix checks in check_argument helper

* Use a dash for the inner box median by default, but allow more customization

* Use plot_violins in catplot

* Remove vestigal _ViolinPlotter and tests

* Basic positional tests

* Color tests

* Test for inner statistics

* Further testing

* Fix tests

* Update API docs and examples

* Update violinplot docstring

Author: mwaskom

doc/_docstrings/barplot.ipynb

@@ -160,7 +160,7 @@
    "outputs": [],
    "source": [
     "ax = sns.barplot(flights, x=\"year\", y=\"passengers\", estimator=\"sum\", errorbar=None)\n",
-    "ax.bar_label(ax.containers[0], fontsize=10)"
+    "ax.bar_label(ax.containers[0], fontsize=10);"
    ]
   },
   {
@@ -248,6 +248,14 @@
     "    height=4, aspect=.5,\n",
     ")"
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "0b6a62b9-eef7-4c85-a1c2-85a58231e6c6",
+   "metadata": {},
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {

doc/_docstrings/violinplot.ipynb

@@ -16,11 +16,11 @@
    ]
   },
   {
-   "cell_type": "markdown",
-   "id": "863c03b1-63e2-4d60-a3a4-4693afab4b5b",
+   "cell_type": "raw",
+   "id": "c72b5394-ff5f-42b1-b083-2e42b2ffdf0f",
    "metadata": {},
    "source": [
-    "Draw a single horizontal boxplot, assigning the data directly to the coordinate variable:"
+    "The default violinplot represents a distribution two ways: a patch showing a symmetric kernel density estimate (KDE), and the quartiles / whiskers of a box plot:"
    ]
   },
   {
@@ -35,11 +35,11 @@
    ]
   },
   {
-   "cell_type": "markdown",
-   "id": "aeea380b-405e-4762-8ede-db57f5549ca5",
+   "cell_type": "raw",
+   "id": "e7d25589-0dc9-48ce-92f9-ab61ffbf964a",
    "metadata": {},
    "source": [
-    "Group by a categorical variable, referencing columns in a dataframe:"
+    "In a bivariate plot, one of the variables will \"group\" so that multiple violins are drawn:"
    ]
   },
   {
@@ -53,11 +53,11 @@
    ]
   },
   {
-   "cell_type": "markdown",
-   "id": "c9a99aa4-2da0-42fa-879a-0c3b264803f4",
+   "cell_type": "raw",
+   "id": "6d588b32-b14b-4b33-bbd9-69b17f8212a6",
    "metadata": {},
    "source": [
-    "Draw vertical violins, grouped by two variables:"
+    "By default, the orientation of the plot is determined by the variable types, preferring to group by a categorical variable:"
    ]
   },
   {
@@ -71,11 +71,29 @@
    ]
   },
   {
-   "cell_type": "markdown",
-   "id": "973e6617-5720-428d-a0ac-447e76aa9fde",
+   "cell_type": "raw",
+   "id": "402812f2-c024-4179-9fee-fed92f03deb2",
    "metadata": {},
    "source": [
-    "Draw split violins to take up less space:"
+    "Pass `fill=False to draw line-art violins:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8e00ce8b-5871-486b-8c55-a4f2e764aa86",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sns.violinplot(data=df, x=\"class\", y=\"age\", hue=\"alive\", fill=False)"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "8350abce-6a40-4e18-9501-7d358192471b",
+   "metadata": {},
+   "source": [
+    "Draw \"split\" violins to take up less space, and only show the data quarties:"
    ]
   },
   {
@@ -85,51 +103,51 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "sns.violinplot(data=df, x=\"deck\", y=\"age\", hue=\"alive\", split=True)"
+    "sns.violinplot(data=df, x=\"class\", y=\"age\", hue=\"alive\", split=True, inner=\"quart\")"
    ]
   },
   {
-   "cell_type": "markdown",
-   "id": "f291d4a2-41bc-4eb0-813d-7a1ceacc0cb0",
+   "cell_type": "raw",
+   "id": "90f4263f-7294-4ad5-bff4-25d7d796cb45",
    "metadata": {},
    "source": [
-    "Prevent the density from smoothing beyond the limits of the data:"
+    "Add a small gap between the dodged violins:"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "82556de0-3756-426c-a591-9af6ed6c45d4",
+   "id": "26cb5b89-496d-4893-8914-ca8b6fbf97b7",
    "metadata": {},
    "outputs": [],
    "source": [
-    "sns.violinplot(data=df, x=\"age\", y=\"alive\", cut=0)"
+    "sns.violinplot(data=df, x=\"class\", y=\"age\", hue=\"alive\", split=True, gap=.1, inner=\"quart\")"
    ]
   },
   {
-   "cell_type": "markdown",
-   "id": "6f351f71-1db3-4c5a-948c-9e1dbc550234",
+   "cell_type": "raw",
+   "id": "bbea49e0-7b08-4b25-8686-1d5404b71601",
    "metadata": {},
    "source": [
-    "Use a narrower bandwidth to reduce the amount of smoothing:"
+    "Starting in version 0.13.0, it is possilbe to \"split\" single violins:"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "8d17e1e3-e0f4-4d2c-ac6e-aec42ed75390",
+   "id": "ba261531-a280-44e5-b8c0-bcc5a53f60bf",
    "metadata": {},
    "outputs": [],
    "source": [
-    "sns.violinplot(data=df, x=\"age\", y=\"alive\", bw=.15)"
+    "sns.violinplot(data=df, x=\"class\", y=\"age\", split=True, inner=\"quart\")"
    ]
   },
   {
-   "cell_type": "markdown",
-   "id": "c4aaeb60-6c1b-4337-91ce-d6b744a3dd90",
+   "cell_type": "raw",
+   "id": "7c4dafa1-2747-4b43-ba4a-4c9b32778086",
    "metadata": {},
    "source": [
-    "Represent every observation inside the distribution"
+    "Represent every observation inside the distribution by setting `inner=\"stick\"` or `inner=\"point\"`:"
    ]
   },
   {
@@ -139,15 +157,15 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "sns.violinplot(data=df, x=\"age\", y=\"embark_town\", inner=\"stick\")"
+    "sns.violinplot(data=df, x=\"age\", y=\"deck\", inner=\"point\")"
    ]
   },
   {
-   "cell_type": "markdown",
-   "id": "01622556-9df8-4af1-b36c-9bc5f6b6099e",
+   "cell_type": "raw",
+   "id": "23c13695-cd01-4da8-bc89-2519ae445f9f",
    "metadata": {},
    "source": [
-    "Use a different scaling rule for normalizing the density:"
+    "Normalize the width of each violin to represent the number of observations:"
    ]
   },
   {
@@ -157,13 +175,122 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "sns.violinplot(data=df, x=\"age\", y=\"embark_town\", scale=\"count\")"
+    "sns.violinplot(data=df, x=\"age\", y=\"deck\", inner=\"point\", density_norm=\"count\")"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "abe650fb-4d26-4bac-97f3-f451a3872cf5",
+   "metadata": {},
+   "source": [
+    "By default, the KDE will smooth past the extremes of the observed data; set `cut=0` to prevent this:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "82556de0-3756-426c-a591-9af6ed6c45d4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sns.violinplot(data=df, x=\"age\", y=\"alive\", cut=0, inner=\"stick\")"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "abfb9e78-d524-4536-90ef-c71834b055f9",
+   "metadata": {},
+   "source": [
+    "The `bw_adjust` parameter controls the amount of smoothing:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8d17e1e3-e0f4-4d2c-ac6e-aec42ed75390",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sns.violinplot(data=df, x=\"age\", y=\"alive\", bw_adjust=.5, inner=\"stick\")"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "407bc513-5b7f-418c-8ffe-ec488836586d",
+   "metadata": {},
+   "source": [
+    "By default, the violins are drawn at fixed positions on a categorical scale, even if the grouping variable is numeric. Starting in version 0.13.0, pass the `native_scale=True` parameter to preserve the original scale on both axes:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e7b6d901-9a97-4716-8d24-1b30145e9c57",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sns.violinplot(x=df[\"age\"].round(-1) + 5, y=df[\"fare\"], native_scale=True)"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "790e3989-0b47-4e77-9bdb-dc757d1e938c",
+   "metadata": {},
+   "source": [
+    "When using a categorical scale, the `formatter` parameter accepts a function that defines categories:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "28a769d4-3e23-4b53-a9ef-391d5fc24201",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "decades = lambda x: f\"{int(x)}–{int(x + 10)}\"\n",
+    "sns.violinplot(x=df[\"age\"].round(-1), y=df[\"fare\"], formatter=decades)"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "6f914d73-7a0c-4fbc-8432-40c4f0577857",
+   "metadata": {},
+   "source": [
+    "By default, the \"inner\" representation scales with the `linewidth` and `linecolor` parameters:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "18cb2afd-8487-40bd-b3f2-1f83243ffa3c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sns.violinplot(data=df, x=\"age\", linewidth=1, linecolor=\"k\")"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "ca2ef541-c07f-4853-ba98-ce75855ba262",
+   "metadata": {},
+   "source": [
+    "Use `inner_kws` to pass parameters directly to the inner plotting functions:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "934f91bc-2698-4c07-92cf-4e6039c801b2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sns.violinplot(data=df, x=\"age\", inner_kws=dict(box_width=15, whis_width=2, color=\".8\"))"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "fdda9a33-37f3-43fd-b02d-1ff414657a37",
+   "id": "4aa00d3c-f016-4db8-b6b0-da4e6a327831",
    "metadata": {},
    "outputs": [],
    "source": []

doc/_tutorial/categorical.ipynb

@@ -293,15 +293,15 @@
    "source": [
     "sns.catplot(\n",
     "    data=tips, x=\"total_bill\", y=\"day\", hue=\"sex\",\n",
-    "    kind=\"violin\", bw=.15, cut=0,\n",
+    "    kind=\"violin\", bw_adjust=.5, cut=0,\n",
     ")"
    ]
   },
   {
    "cell_type": "raw",
    "metadata": {},
    "source": [
-    "It's also possible to \"split\" the violins when the hue parameter has only two levels, which can allow for a more efficient use of space:"
+    "It's also possible to \"split\" the violins, which can allow for a more efficient use of space:"
    ]
   },
   {
@@ -406,7 +406,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "sns.catplot(data=titanic, x=\"deck\", kind=\"count\", palette=\"ch:.25\")"
+    "sns.catplot(data=titanic, x=\"deck\", kind=\"count\")"
    ]
   },
   {

doc/whatsnew/index.rst

@@ -3,6 +3,13 @@
 What's new in each version
 ==========================
 
+v0.13
+-----
+.. toctree::
+   :maxdepth: 2
+
+   v0.13.0
+
 v0.12
 -----
 .. toctree::

examples/wide_form_violinplot.py

@@ -27,7 +27,7 @@
 f, ax = plt.subplots(figsize=(11, 6))
 
 # Draw a violinplot with a narrower bandwidth than the default
-sns.violinplot(data=corr_df, palette="Set3", bw=.2, cut=1, linewidth=1)
+sns.violinplot(data=corr_df, palette="Set3", bw_adjust=.5, cut=1, linewidth=1)
 
 # Finalize the figure
 ax.set(ylim=(-.7, 1.05))