Add the concept of a "layer legend" to so.Plot (#3456)

* Fix Mark._legend_artist type annotations * Work around possible matplotlib type annotation bug * Add the concept of a layer legend to so.Plot * Add tests and API docs * Rephrase docstrings
mwaskom · Aug 31, 2023 · 082486d · 082486d
1 parent 0a64c1a
commit 082486d
Show file tree

Hide file tree

Showing 5 changed files with 280 additions and 33 deletions.
diff --git a/doc/_docstrings/objects.Plot.add.ipynb b/doc/_docstrings/objects.Plot.add.ipynb
@@ -19,7 +19,14 @@
   {
    "cell_type": "raw",
    "id": "33cd5d3c-d3ad-4e3b-bdac-350f8e104594",
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "raw_mimetype": "",
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "source": [
     "Every layer must be defined with a :class:`Mark`:"
    ]
@@ -175,7 +182,13 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "45690aaa-1abf-40ae-be3b-1ab648f8be62",
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "outputs": [],
    "source": [
     "(\n",
@@ -185,11 +198,53 @@
     ")"
    ]
   },
+  {
+   "cell_type": "raw",
+   "id": "e62f9e80-bfba-4516-a43a-a265dc35eb79",
+   "metadata": {
+    "editable": true,
+    "raw_mimetype": "",
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
+   "source": [
+    "Providing a `label` will annotate the layer in the plot's legend:"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
    "id": "a403012a-e895-4e5b-b690-dc27efbeccad",
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "(\n",
+    "    so.Plot(tips, x=\"size\")\n",
+    "    .add(so.Line(color=\"C1\"), so.Agg(), y=\"total_bill\", label=\"Bill\")\n",
+    "    .add(so.Line(color=\"C2\"), so.Agg(), y=\"tip\", label=\"Tip\")\n",
+    "    .label(y=\"Value\")\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c14526a4-37bb-4f4c-84fa-e5c556eee5c2",
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "outputs": [],
    "source": []
   }

diff --git a/doc/_docstrings/objects.Plot.label.ipynb b/doc/_docstrings/objects.Plot.label.ipynb
@@ -5,6 +5,10 @@
    "execution_count": null,
    "id": "9252d5a5-8af1-4f99-b799-ee044329fb23",
    "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
     "tags": [
      "hide"
     ]
@@ -19,7 +23,14 @@
   {
    "cell_type": "raw",
    "id": "fb32137a-e882-4222-9463-b8cf0ee1c8bd",
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "raw_mimetype": "",
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "source": [
     "Use strings to override default labels:"
    ]
@@ -28,7 +39,13 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "65b4320e-6fb9-48ed-9132-53b0d21b85e6",
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "outputs": [],
    "source": [
     "p = (\n",
@@ -41,7 +58,14 @@
   {
    "cell_type": "raw",
    "id": "a39626d2-76f5-40a9-a3fd-6f44dd69bd30",
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "raw_mimetype": "",
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "source": [
     "Pass a function to *modify* the default label:"
    ]
@@ -50,7 +74,13 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "c3540c54-1c91-4d55-8f58-cd758abbe2fd",
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "outputs": [],
    "source": [
     "p.label(color=str.capitalize)"
@@ -59,7 +89,13 @@
   {
    "cell_type": "markdown",
    "id": "68f3b321-0755-4ef1-a9e6-bcff61a9178d",
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "source": [
     "Use this method to set the title for a single-axes plot:"
    ]
@@ -68,7 +104,13 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "12d23c6e-781f-4b5c-a6b0-3ea0317ab7fb",
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "outputs": [],
    "source": [
     "p.label(title=\"Penguin species exhibit distinct bill shapes\")"
@@ -77,7 +119,13 @@
   {
    "cell_type": "markdown",
    "id": "8e0bcb80-0929-4ab9-b5c0-13bb3d8e4484",
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "source": [
     "When faceting, the `title` parameter will modify default titles:"
    ]
@@ -86,7 +134,13 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "da1516b7-b823-41c0-b251-01bdecb6a4e6",
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "outputs": [],
    "source": [
     "p.facet(\"sex\").label(title=str.upper)"
@@ -95,7 +149,13 @@
   {
    "cell_type": "markdown",
    "id": "bb439eae-6cc3-4a6c-bef2-b4b7746edbd1",
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "source": [
     "And the `col`/`row` parameters will add labels to the title for each facet:"
    ]
@@ -104,7 +164,13 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "e0d49ba9-0507-4358-b477-2e0253f0df8f",
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "outputs": [],
    "source": [
     "p.facet(\"sex\").label(col=\"Sex:\")"
@@ -113,7 +179,13 @@
   {
    "cell_type": "markdown",
    "id": "99471c06-1b1a-4ef5-844c-5f4aa8f322f5",
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "source": [
     "If more customization is needed, a format string can work well:"
    ]
@@ -122,7 +194,13 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "848be3a3-5a2c-4b98-918f-825257be85ae",
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "outputs": [],
    "source": [
     "p.facet(\"sex\").label(title=\"{} penguins\".format)"
@@ -132,7 +210,65 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "94012def-dd7c-48f4-8830-f77a3bf7299b",
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "p"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "e9b669e9-fd3d-4292-9c8d-e5fb093932b2",
+   "metadata": {
+    "editable": true,
+    "raw_mimetype": "",
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
+   "source": [
+    "When adding labels for each layer, the `legend=` parameter sets the title for the legend:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "78d22763-3f92-4be1-bc3f-bc24ad39da70",
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "(\n",
+    "    so.Plot(penguins, x=\"species\")\n",
+    "    .add(so.Line(color=\"C1\"), so.Agg(), y=\"bill_length_mm\", label=\"length\")\n",
+    "    .add(so.Line(color=\"C2\"), so.Agg(), y=\"bill_depth_mm\", label=\"depth\")\n",
+    "    .label(legend=\"Measurement\")\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5c7a7b91-bb5c-4bf5-99f8-719a220e3b36",
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "outputs": [],
    "source": []
   }