Software Open Access

mwaskom/seaborn: v0.12.0

Michael Waskom; Maoz Gelbart; Olga Botvinnik; Joel Ostblom; Paul Hobson; Saulius Lukauskas; David C Gemperline; Tom Augspurger; Yaroslav Halchenko; Jordi Warmenhoven; John B. Cole; Julian de Ruiter; Ewout ter Hoeven; Jake Vanderplas; Stephan Hoyer; Cameron Pye; Alistair Miles; Corban Swain; Kyle Meyer; Marcel Martin; Pete Bachant; Eric Quintero; Gero Kunter; Santi Villalba; Brian; Clark Fitzgerald; Constantine Evans; Mike Lee Williams; Stefanie Molin; Drew O'Kane

v0.12.0 (September 2022) Introduction of the objects interface

This release debuts the <span class="title-ref">seaborn.objects</span> interface, an entirely new approach to making plots with seaborn. It is the product of several years of design and 16 months of implementation work. The interface aims to provide a more declarative, composable, and extensible API for making statistical graphics. It is inspired by Wilkinson's grammar of graphics, offering a Pythonic API that is informed by the design of libraries such as <span class="title-ref">ggplot2</span> and <span class="title-ref">vega-lite</span> along with lessons from the past 10 years of seaborn's development.

For more information and numerous examples, see the tutorial chapter and API reference.

This initial release should be considered "experimental". While it is stable enough for serious use, there are definitely some rough edges, and some key features remain to be implemented. It is possible that breaking changes may occur over the next few minor releases. Please be patient with any limitations that you encounter and help the development by reporting issues when you find behavior surprising.

Keyword-only arguments

Seaborn's plotting functions now require explicit keywords for most arguments, following the deprecation of positional arguments in v0.11.0. With this enforcement, most functions have also had their parameter lists rearranged so that <span class="title-ref">data</span> is the first and only positional argument. This adds consistency across the various functions in the library. It also means that calling <span class="title-ref">func(data)</span> will do something for nearly all functions (those that support wide-form data) and that pandas.DataFrame can be piped directly into a plot. It is possible that the signatures will be loosened a bit in future releases so that <span class="title-ref">x</span> and <span class="title-ref">y</span> can be positional, but minimal support for positional arguments after this change will reduce the chance of inadvertent mis-specification (2804).

Modernization of categorical scatterplots

This release begins the process of modernizing the categorical plots, beginning with stripplot and swarmplot. These functions are sporting some enhancements that alleviate a few long-running frustrations (2413, 2447):

  • The new native_scale parameter allows numeric or datetime categories to be plotted with their original scale rather than converted to strings and plotted at fixed intervals.
  • The new formatter parameter allows more control over the string representation of values on the categorical axis. There should also be improved defaults for some types, such as dates.
  • It is now possible to assign hue when using only one coordinate variable (i.e. only x or y).
  • It is now possible to disable the legend.

The updates also harmonize behavior with functions that have been more recently introduced. This should be relatively non-disruptive, although a few defaults will change:

  • The functions now hook into matplotlib's unit system for plotting categorical data. (Seaborn's categorical functions actually predate support for categorical data in matplotlib.) This should mostly be transparent to the user, but it may resolve a few edge cases. For example, matplotlib interactivity should work better (e.g., for showing the data value under the cursor).
  • A color palette is no longer applied to levels of the categorical variable by default. It is now necessary to explicitly assign <span class="title-ref">hue</span> to see multiple colors (i.e., assign the same variable to <span class="title-ref">x</span>/<span class="title-ref">y</span> and <span class="title-ref">hue</span>). Passing <span class="title-ref">palette</span> without <span class="title-ref">hue</span> will continue to be honored for one release cycle.
  • Numeric <span class="title-ref">hue</span> variables now receive a continuous mapping by default, using the same rules as scatterplot. Pass <span class="title-ref">palette="deep"</span> to reproduce previous defaults.
  • The plots now follow the default property cycle; i.e. calling an axes-level function multiple times with the same active axes will produce different-colored artists.
  • Currently, assigning <span class="title-ref">hue</span> and then passing a <span class="title-ref">color</span> will produce a gradient palette. This is now deprecated, as it is easy to request a gradient with, e.g. <span class="title-ref">palette="light:blue"</span>.

Similar enhancements / updates should be expected to roll out to other categorical plotting functions in future releases. There are also several function-specific enhancements:

  • In stripplot, a "strip" with a single observation will be plotted without jitter (2413)
  • In swarmplot, the points are now swarmed at draw time, meaning that the plot will adapt to further changes in axis scaling or tweaks to the plot layout (2443).
  • In swarmplot, the proportion of points that must overlap before issuing a warning can now be controlled with the <span class="title-ref">warn_thresh</span> parameter (2447).
  • In swarmplot, the order of the points in each swarm now matches the order in the original dataset; previously they were sorted. This affects only the underlying data stored in the matplotlib artist, not the visual representation (2443).
More flexible errorbars

Increased the flexibility of what can be shown by the internally-calculated errorbars for lineplot, barplot, and pointplot.

With the new <span class="title-ref">errorbar</span> parameter, it is now possible to select bootstrap confidence intervals, percentile / predictive intervals, or intervals formed by scaled standard deviations or standard errors. The parameter also accepts an arbitrary function that maps from a vector to an interval. There is a new user guide chapter demonstrating these options and explaining when you might want to use each one.

As a consequence of this change, the <span class="title-ref">ci</span> parameter has been deprecated. Note that regplot retains the previous API, but it will likely be updated in a future release (2407, 2866).

Other updates
  • It is now possible to aggregate / sort a lineplot along the y axis using <span class="title-ref">orient="y"</span> (2854).
  • Made it easier to customize FacetGrid / PairGrid / JointGrid with a fluent (method-chained) style by adding <span class="title-ref">apply</span>/ <span class="title-ref">pipe</span> methods. Additionally, fixed the <span class="title-ref">tight_layout</span> and <span class="title-ref">refline</span> methods so that they return <span class="title-ref">self</span> (2926).
  • Added FacetGrid.tick_params and PairGrid.tick_params to customize the appearance of the ticks, tick labels, and gridlines of all subplots at once (2944).
  • Added a <span class="title-ref">width</span> parameter to barplot (2860).
  • It is now possible to specify <span class="title-ref">estimator</span> as a string in barplot and pointplot, in addition to a callable (2866).
  • Error bars in regplot now inherit the alpha value of the points they correspond to (2540).
  • When using pairplot with <span class="title-ref">corner=True</span> and <span class="title-ref">diag_kind=None</span>, the top left y axis label is no longer hidden (2850).
  • It is now possible to plot a discrete histplot as a step function or polygon (2859).
  • It is now possible to customize the appearance of elements in a boxenplot with <span class="title-ref">box_kws</span>/<span class="title-ref">line_kws</span>/<span class="title-ref">flier_kws</span> (2909).
  • Improved integration with the matplotlib color cycle in most axes-level functions (2449).
  • Fixed a regression in 0.11.2 that caused some functions to stall indefinitely or raise when the input data had a duplicate index (2776).
  • Fixed a bug in histplot and kdeplot where weights were not factored into the normalization (2812).
  • Fixed two edgecases in histplot when only <span class="title-ref">binwidth</span> was provided (2813).
  • Fixed a bug in violinplot where inner boxes/points could be missing with unpaired split violins (2814).
  • Fixed a bug in PairGrid where an error would be raised when defining <span class="title-ref">hue</span> only in the mapping methods (2847).
  • Fixed a bug in scatterplot where an error would be raised when <span class="title-ref">hue_order</span> was a subset of the hue levels (2848).
  • Fixed a bug in histplot where dodged bars would have different widths on a log scale (2849).
  • In lineplot, allowed the <span class="title-ref">dashes</span> keyword to set the style of a line without mapping a <span class="title-ref">style</span> variable (2449).
  • Improved support in relplot for "wide" data and for faceting variables passed as non-pandas objects (2846).
  • Subplot titles will no longer be reset when calling or FacetGrid.map_dataframe (2705).
  • Added a workaround for a matplotlib issue that caused figure-level functions to freeze when <span class="title-ref"></span> was called (2925).
  • Improved robustness to numerical errors in kdeplot (2862).
  • Fixed a bug where rugplot was ignoring expand_margins=False (2953).
  • The <span class="title-ref">patch.facecolor</span> rc param is no longer set by set_palette (or set_theme). This should have no general effect, because the matplotlib default is now <span class="title-ref">"C0"</span> (2906).
  • Made <span class="title-ref">scipy</span> an optional dependency and added <span class="title-ref">pip install seaborn\[stats\]</span> as a method for ensuring the availability of compatible <span class="title-ref">scipy</span> and <span class="title-ref">statsmodels</span> libraries at install time. This has a few minor implications for existing code, which are explained in the Github pull request (2398).
  • Example datasets are now stored in an OS-specific cache location (as determined by <span class="title-ref">appdirs</span>) rather than in the user's home directory. Users should feel free to remove <span class="title-ref">\~/seaborn-data</span> if desired (2773).
  • The unit test suite is no longer part of the source or wheel distribution. Seaborn has never had a runtime API for exercising the tests, so this should not have workflow implications (2833).
  • Following NEP29, dropped support for Python 3.6 and bumped the minimally-supported versions of the library dependencies.
  • Removed the previously-deprecated <span class="title-ref">factorplot</span> along with several previously-deprecated utility functions (<span class="title-ref">iqr</span>, <span class="title-ref">percentiles</span>, <span class="title-ref">pmf_hist</span>, and <span class="title-ref">sort_df</span>).
  • Removed the (previously-unused) option to pass additional keyword arguments to pointplot.
If seaborn is integral to a scientific publication, please cite the following paper:
Files (2.0 MB)
Name Size
2.0 MB Download
All versions This version
Views 47,753827
Downloads 2,06914
Data volume 1.8 GB27.7 MB
Unique views 35,802760
Unique downloads 1,69113


Cite as