Feature implementation from commits 72faf27..7231fc2

doc/_docstrings/barplot.ipynb

@@ -12,15 +12,17 @@
    "outputs": [],
    "source": [
     "import seaborn as sns\n",
-    "sns.set_theme(style=\"whitegrid\")"
+    "sns.set_theme(style=\"whitegrid\")\n",
+    "penguins = sns.load_dataset(\"penguins\")\n",
+    "flights = sns.load_dataset(\"flights\")"
    ]
   },
   {
-   "cell_type": "markdown",
-   "id": "a7ef20b6-3bd8-4992-a270-4c3ecc86a0fa",
+   "cell_type": "raw",
+   "id": "b53b65b8-5670-4905-aa39-36db04f4b813",
    "metadata": {},
    "source": [
-    "Group by a categorical varaible and plot aggregated values, with confidence intervals:"
+    "With long data, assign `x` and `y` to group by a categorical varaible and plot aggregated values, with confidence intervals:"
    ]
   },
   {
@@ -30,16 +32,70 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "df = sns.load_dataset(\"penguins\")\n",
-    "sns.barplot(data=df, x=\"island\", y=\"body_mass_g\")"
+    "sns.barplot(penguins, x=\"island\", y=\"body_mass_g\")"
    ]
   },
   {
-   "cell_type": "markdown",
-   "id": "38f7c39e-485d-4b50-ac21-f1b402f26aa4",
+   "cell_type": "raw",
+   "id": "ed061d6f-bd3b-4189-bbc7-aed998be05cb",
    "metadata": {},
    "source": [
-    "Add a second layer of grouping:"
+    "Prior to v0.13.0, each bar would have a different color. To replicate this behavior, assign the grouping variable to `hue` as well:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3ded2e23-c610-450b-bcd2-1d2ba54db566",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sns.barplot(penguins, x=\"body_mass_g\", y=\"island\", hue=\"island\", legend=False)"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "e00fa127-4dd4-4565-9897-51317adfea3c",
+   "metadata": {},
+   "source": [
+    "When plotting a \"wide-form\" dataframe, each column will be aggregated and represented as a bar:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ae7e0f4e-471e-4dee-8913-5e7b67e0a381",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "flights_wide = flights.pivot(index=\"year\", columns=\"month\", values=\"passengers\")\n",
+    "sns.barplot(flights_wide)"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "6020404c-15c6-4c00-9ffd-6c12ba624e52",
+   "metadata": {},
+   "source": [
+    "Passing only a series (or dict) will plot each of its values, using the index (or keys) to label the bars:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "77b2c3eb-c3e4-4d44-929a-27a456da4b88",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sns.barplot(flights_wide[\"Jun\"])"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "b0c3b101-7649-4014-9ab2-10ff206d39d7",
+   "metadata": {},
+   "source": [
+    "With long-form data, you can add a second layer of grouping with `hue`:"
    ]
   },
   {
@@ -49,12 +105,12 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "sns.barplot(data=df, x=\"island\", y=\"body_mass_g\", hue=\"sex\")"
+    "sns.barplot(penguins, x=\"island\", y=\"body_mass_g\", hue=\"sex\")"
    ]
   },
   {
-   "cell_type": "markdown",
-   "id": "7f8fa070-a8f4-41fb-be74-c489acbdbcbe",
+   "cell_type": "raw",
+   "id": "069ce509-ee0d-42c8-b053-1b4b6d764449",
    "metadata": {},
    "source": [
     "Use the error bars to show the standard deviation rather than a confidence interval:"
@@ -67,15 +123,93 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "sns.barplot(data=df, x=\"island\", y=\"body_mass_g\", errorbar=\"sd\")"
+    "sns.barplot(penguins, x=\"island\", y=\"body_mass_g\", errorbar=\"sd\")"
    ]
   },
   {
-   "cell_type": "markdown",
-   "id": "7f579f70-39a2-4d0c-baa2-9adae11ce2ce",
+   "cell_type": "raw",
+   "id": "6dc3d564-4d26-4753-a2a0-6194b10452bc",
    "metadata": {},
    "source": [
-    "Customize the appearance of the plot:"
+    "Use a different aggregation function and disable the error bars:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "448ba05e-c533-459d-84b6-0fca80e6e3ce",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sns.barplot(flights, x=\"year\", y=\"passengers\", estimator=\"sum\", errorbar=None)"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "7746220d-b6b4-4ee5-886c-5867db35d4e3",
+   "metadata": {},
+   "source": [
+    "Add text labels with each bar's value:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e343485c-636e-4b96-b20d-59a7f7155be8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ax = sns.barplot(flights, x=\"year\", y=\"passengers\", estimator=\"sum\", errorbar=None)\n",
+    "ax.bar_label(ax.containers[0], fontsize=10)"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "457702c2-9fa6-4021-a19b-f44b39aa0a19",
+   "metadata": {},
+   "source": [
+    "Preserve the original scaling of the grouping variable and add annotations in numeric coordinates:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "08b60118-5830-4fd7-8a66-431c065d57cb",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ax = sns.barplot(\n",
+    "    flights, x=\"year\", y=\"passengers\",\n",
+    "    native_scale=True,\n",
+    "    estimator=\"sum\", errorbar=None,\n",
+    ")\n",
+    "ax.plot(1955, 3600, \"*\", markersize=10, color=\"r\")"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "206be839-f33b-4ffe-8101-bd98bc5942b8",
+   "metadata": {},
+   "source": [
+    "Use `orient` to resolve ambiguity about which variable should group when both are numeric:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3aff3c69-3c24-40ad-af12-a507e33f5d3f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sns.barplot(flights, x=\"passengers\", y=\"year\", orient=\"y\")"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "90277a3b-1f86-4884-97ad-e5d65df408ef",
+   "metadata": {},
+   "source": [
+    "Customize the appearance of the plot using :class:`matplotlib.patches.Rectangle` and :class:`matplotlib.lines.Line2D` keyword arguments:"
    ]
   },
   {
@@ -86,19 +220,34 @@
    "outputs": [],
    "source": [
     "sns.barplot(\n",
-    "    data=df, x=\"body_mass_g\", y=\"island\",\n",
-    "    errorbar=(\"pi\", 50), capsize=.4, errcolor=\".5\",\n",
-    "    linewidth=3, edgecolor=\".5\", facecolor=(0, 0, 0, 0),\n",
+    "    penguins, x=\"body_mass_g\", y=\"island\",\n",
+    "    errorbar=(\"pi\", 50), capsize=.4,\n",
+    "    err_kws={\"color\": \".5\", \"linewidth\": 2.5},\n",
+    "    linewidth=2.5, edgecolor=\".5\", facecolor=(0, 0, 0, 0),\n",
     ")"
    ]
   },
+  {
+   "cell_type": "raw",
+   "id": "08ef562f-13a3-4da5-a9cf-46deaa543890",
+   "metadata": {},
+   "source": [
+    "Use :func:`catplot` to draw faceted bars, which is recommended over working directly with :class:`FacetGrid`:"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "faedd6f9-a123-4927-9eff-a2046edf5c72",
+   "id": "4d23777f-8a69-4c68-ab35-3e6740c61bcf",
    "metadata": {},
    "outputs": [],
-   "source": []
+   "source": [
+    "sns.catplot(\n",
+    "    penguins, kind=\"bar\",\n",
+    "    x=\"sex\", y=\"body_mass_g\", col=\"species\",\n",
+    "    height=4, aspect=.5,\n",
+    ")"
+   ]
   }
  ],
  "metadata": {