Document the legend argument of categorical scatterplots (#2933)

* Simplify jitter stripplot example * Document the legend argument * Demonstrate 0.11 legend behavior in docstrings * Include more info on legend for numeric variables * Include more info on legend for numeric variables Co-authored-by: Michael Waskom <[email protected]>
mwaskom · Aug 3, 2022 · ff96e1f · ff96e1f
1 parent d504beb
commit ff96e1f
Show file tree

Hide file tree

Showing 4 changed files with 20 additions and 9 deletions.
diff --git a/doc/_docstrings/stripplot.ipynb b/doc/_docstrings/stripplot.ipynb
@@ -76,7 +76,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "sns.stripplot(data=tips, x=\"total_bill\", y=\"day\", hue=\"day\")"
+    "sns.stripplot(data=tips, x=\"total_bill\", y=\"day\", hue=\"day\", legend=False)"
    ]
   },
   {

diff --git a/doc/_docstrings/swarmplot.ipynb b/doc/_docstrings/swarmplot.ipynb
@@ -76,7 +76,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "sns.swarmplot(data=tips, x=\"total_bill\", y=\"day\", hue=\"day\")"
+    "sns.swarmplot(data=tips, x=\"total_bill\", y=\"day\", hue=\"day\", legend=False)"
    ]
   },
   {

diff --git a/examples/jitter_stripplot.py b/examples/jitter_stripplot.py
@@ -19,7 +19,8 @@
 
 # Show each observation with a scatterplot
 sns.stripplot(x="value", y="measurement", hue="species",
-              data=iris, dodge=True, alpha=.25, zorder=1)
+              data=iris, dodge=True, alpha=.25, zorder=1,
+              legend=False)
 
 # Show the conditional means, aligning each pointplot in the
 # center of the strips by adjusting the width allotted to each
@@ -30,7 +31,6 @@
               markers="d", scale=.75, ci=None)
 
 # Improve the legend
-handles, labels = ax.get_legend_handles_labels()
-ax.legend(handles[3:], labels[3:], title="species",
-          handletextpad=0, columnspacing=1,
-          loc="lower right", ncol=3, frameon=True)
+sns.move_legend(
+    ax, loc="lower right", ncol=3, frameon=True, columnspacing=1, handletextpad=0
+)
diff --git a/seaborn/categorical.py b/seaborn/categorical.py
@@ -2133,6 +2133,14 @@ def plot(self, ax, boxplot_kws):
         Function for converting categorical data into strings. Affects both grouping
         and tick labels.\
     """),
+    legend=dedent("""\
+legend : "auto", "brief", "full", or False
+    How to draw the legend. If "brief", numeric `hue` and `size`
+    variables will be represented with a sample of evenly spaced values.
+    If "full", every group will get an entry in the legend. If "auto",
+    choose between brief or full representation based on number of levels.
+    If `False`, no legend data is added and no legend is drawn.
+    """),
     ax_in=dedent("""\
     ax : matplotlib Axes, optional
         Axes object to draw the plot onto, otherwise uses the current Axes.\
@@ -2542,6 +2550,7 @@ def stripplot(
     {linewidth}
     {native_scale}
     {formatter}
+    {legend}
     {ax_in}
     kwargs : key, value mappings
         Other keyword arguments are passed through to
@@ -2663,6 +2672,7 @@ def swarmplot(
     {linewidth}
     {native_scale}
     {formatter}
+    {legend}
     {ax_in}
     kwargs : key, value mappings
         Other keyword arguments are passed through to
@@ -3272,8 +3282,9 @@ def catplot(
     {color}
     {palette}
     {hue_norm}
-    legend : bool, optional
-        If ``True`` and there is a ``hue`` variable, draw a legend on the plot.
+    legend : str or bool, optional
+        Set to `False` to disable the legend. With `strip` or `swarm` plots,
+        this also accepts a string, as described in the axes-level docstrings.
     {legend_out}
     {share_xy}
     {margin_titles}