Software Open Access
Michael Waskom; Maoz Gelbart; Olga Botvinnik; Joel Ostblom; Paul Hobson; Saulius Lukauskas; David C Gemperline; Tom Augspurger; Yaroslav Halchenko; Jordi Warmenhoven; John B. Cole; Ewout ter Hoeven; Julian de Ruiter; Jake Vanderplas; Stephan Hoyer; Cameron Pye; Alistair Miles; Corban Swain; Kyle Meyer; Marcel Martin; Pete Bachant; Stefanie Molin; Eric Quintero; Gero Kunter; Santi Villalba; Brian; Clark Fitzgerald; Constantine Evans; Mike Lee Williams
See the online docs for an annotated version of these notes with working links.
This is a major release with a number of important new features and changes. The highlight is a major overhaul to seaborn's categorical plotting functions, providing them with many new capabilities and better aligning their API with the rest of the library. There is also provisional support for alternate dataframe libraries like polars, a new theme and display configuration system for
objects.Plot, and many smaller bugfixes and enhancements.
Updating is recommended, but users are encouraged to carefully check the outputs of existing code that uses the categorical functions, and they should be aware of some deprecations and intentional changes to the default appearance of the resulting plots (see notes below with and tags).Major enhancements to categorical plots
categorical functions <categorical_api> have been completely rewritten for this release. This provided the opportunity to address some longstanding quirks as well as to add a number of smaller but much-desired features and enhancements.
The categorical functions have historically treated all data as categorical, even when it has a numeric or datetime type. This can now be controlled with the new <span class="title-ref">native_scale</span> parameter. The default remains <span class="title-ref">False</span> to preserve existing behavior. But with <span class="title-ref">native_scale=True</span>, values will be treated as they would by other seaborn or matplotlib functions. Element widths will be derived from the minimum distance between two unique values on the categorical axis.
Additionally, while seaborn previously determined the mapping from categorical values to ordinal positions internally, this is now delegated to matplotlib. The change should mostly be transparent to the user, but categorical plots (even with <span class="title-ref">native_scale=False</span>) will better align with artists added by other seaborn or matplotlib functions in most cases, and matplotlib's interactive machinery will work better.Changes to color defaults and specification
The categorical functions now act more like the rest of seaborn in that they will produce a plot with a single main color unless the <span class="title-ref">hue</span> variable is assigned. Previously, there would be an implicit redundant color mapping (e.g., each box in a boxplot would get a separate color from the default palette). To retain the previous behavior, explicitly assign a redundant <span class="title-ref">hue</span> variable (e.g., <span class="title-ref">boxplot(data, x="x", y="y", hue="x")</span>).
Two related idiosyncratic color specifications are deprecated, but they will continue to work (with a warning) for one release cycle:
Finally, like other seaborn functions, the default palette now depends on the variable type, and a sequential palette will be used with numeric data. To retain the previous behavior, pass the name of a qualitative palette (e.g., <span class="title-ref">palette="deep"</span> for seaborn's default). Accordingly, the functions have gained a parameter to control numeric color mappings (<span class="title-ref">hue_norm</span>).Other features, enhancements, and changes
The following updates apply to multiple categorical functions.
violinplotfunctions now support a single <span class="title-ref">linecolor</span> parameter.
pointplotor the kernel density fit in
violinplot) are now applied in that scale space.
The following updates are function-specific.
pointplot, a single
matplotlib.lines.Line2Dartist is now used rather than adding separate
matplotlib.collections.PathCollectionartist for the points. As a result, it is now possible to pass additional keyword arguments for complete customization the appearance of both the lines and markers; additionally, the legend representation is improved. Accordingly, parameters that previously allowed only partial customization (<span class="title-ref">scale</span>, <span class="title-ref">join</span>, and <span class="title-ref">errwidth</span>) are now deprecated. The old parameters will now trigger detailed warning messages with instructions for adapting existing code.
violinplotbetter aligns with
kdeplot, as the <span class="title-ref">bw</span> parameter is now deprecated in favor of <span class="title-ref">bw_method</span> and <span class="title-ref">bw_adjust</span>.
boxenplot, the boxen are now drawn with separate patch artists in each tail. This may have consequences for code that works with the underlying artists, but it produces a better result for low-alpha / unfilled plots and enables proper area/density scaling.
barplot, the <span class="title-ref">errcolor</span> and <span class="title-ref">errwidth</span> parameters are now deprecated in favor of a more general <span class="title-ref">err_kws</span>` dictionary. The existing parameters will continue to work for two releases.
violinplot, the <span class="title-ref">scale</span> and <span class="title-ref">scale_hue</span> parameters have been renamed to <span class="title-ref">density_norm</span> and <span class="title-ref">common_norm</span> for clarity and to reflect the fact that common normalization is now applied over both hue and faceting variables in
boxenplot, the <span class="title-ref">scale</span> parameter has been renamed to <span class="title-ref">width_method</span> as part of a broader effort to de-confound the meaning of "scale" in seaborn parameters.
pointplot, a bar or point will be drawn for each entry in the vector rather than plotting a single aggregated value. To retain the previous behavior, assign the vector to the <span class="title-ref">y</span> variable.
boxplot, the default flier marker now follows the matplotlib rcparams so that it can be globally customized.
violinplot, a separate mini-box is now drawn for each split violin.
boxenplot, all plots now use a consistent luminance ramp for the different box levels. This leads to a change in the appearance of existing plots, but reduces the chances of a misleading result.
boxenplotnow approximates the density of the underlying observations, including for asymmetric distributions. This produces a substantial change in the appearance of plots with <span class="title-ref">width_method="area"</span>, although the existing behavior was poorly defined.
countplot, the new <span class="title-ref">stat</span> parameter can be used to apply a normalization (e.g to show a <span class="title-ref">"percent"</span> or <span class="title-ref">"proportion"</span>).
violinplotis now more general and can be set to <span class="title-ref">True</span> regardless of the number of <span class="title-ref">hue</span> variable levels (or even without <span class="title-ref">hue</span>). This is probably most useful for showing half violins.
violinplot, the new <span class="title-ref">inner_kws</span> parameter allows additional control over the interior artists.
catplot, as data vectors can now be passed directly.
boxplot, the artists that comprise each box plot are now packaged in a <span class="title-ref">BoxPlotContainer</span> for easier post-plotting access.
objects.Plotvia the new <span class="title-ref">label</span> parameter in
objects.Plot.labelthe <span class="title-ref">x</span> / <span class="title-ref">y</span> parameters can be used to set a common scale / limit / label for paired subplots (
ecdfplot, <span class="title-ref">stat="percent"</span> is now a valid option (
histplot, infinite values are now ignored when choosing the default bin range (
load_datasetto use an approach more compatible with <span class="title-ref">pyiodide</span> (
histplot, treatment of the <span class="title-ref">binwidth</span> parameter has changed such that the actual bin width will be only approximately equal to the requested width when that value does not evenly divide the bin range. This fixes an issue where the largest data value was sometimes dropped due to floating point error (
objects.Barswidths when using a nonlinear scale (
move_legendwhen <span class="title-ref">labels</span> were provided (
histplotadded a stray empty <span class="title-ref">BarContainer</span> (
objects.Plot.onwould override a figure's layout engine (
lineplotwith a list of tuples for the keyword argument dashes caused a TypeError (
PairGridthat caused an exception when the input dataframe had a column multiindex (