Statistical data visualization in Python
This is a minor release containing internal changes that adapt to upcoming deprecations in pandas. All users are encouraged to update.
This is a minor release with some bug fixes and a couple new features. All users are encouraged to update.
|Feature| Added support for weighted mean estimation (with boostrap CIs) in lineplot, barplot, pointplot, and objects.Est (#3580, #3586).
|Feature| Added the extent option in objects.Plot.layout (#3552).
|Fix| Fixed a regression in v0.13.0 that triggered an exception when working with non-numpy data types (#3516).
|Fix| Fixed a bug in objects.Plot so that tick labels are shown for wrapped axes that aren't in the bottom-most row (#3600).
|Fix| Fixed a bug in catplot where a blank legend would be added when hue was redundantly assigned (#3540).
|Fix| Fixed a bug in catplot where the edgecolor parameter was ignored with kind="bar" (#3547).
|Fix| Fixed a bug in boxplot where an exception was raised when using the matplotlib bootstrap option (#3562).
|Fix| Fixed a bug in lineplot where an exception was raised when hue was assigned with an empty dataframe (#3569).
|Fix| Fixed a bug in multiple categorical plots that raised with hue=None and dodge=True; this is now has no effect (#3605).
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).
Seaborn's 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 native_scale parameter. The default remains False to preserve existing behavior. But with native_scale=True, 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 native_scale=False) will better align with artists added by other seaborn or matplotlib functions in most cases, and matplotlib's interactive machinery will work better.
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 hue 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 hue variable (e.g., boxplot(data, x="x", y="y", hue="x")).
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., palette="deep" for seaborn's default). Accordingly, the functions have gained a parameter to control numeric color mappings (hue_norm).
The following updates apply to multiple categorical functions.
boxplot, boxenplot, and violinplot functions now support a single linecolor parameter.pointplot or the kernel density fit in violinplot) are now applied in that scale space.The following updates are function-specific.
pointplot, a single matplotlib.lines.Line2D artist is now used rather than adding separate matplotlib.collections.PathCollection artist 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 (scale, join, and errwidth) are now deprecated. The old parameters will now trigger detailed warning messages with instructions for adapting existing code.violinplot better aligns with kdeplot, as the bw parameter is now deprecated in favor of bw_method and bw_adjust.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 errcolor and errwidth parameters are now deprecated in favor of a more general err_kws` dictionary. The existing parameters will continue to work for two releases.violinplot, the scale and scale_hue parameters have been renamed to density_norm and common_norm for clarity and to reflect the fact that common normalization is now applied over both hue and faceting variables in catplot.boxenplot, the scale parameter has been renamed to width_method as part of a broader effort to de-confound the meaning of "scale" in seaborn parameters.barplot or 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 y 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.boxenplot now approximates the density of the underlying observations, including for asymmetric distributions. This produces a substantial change in the appearance of plots with width_method="area", although the existing behavior was poorly defined.countplot, the new stat parameter can be used to apply a normalization (e.g to show a "percent" or "proportion").violinplot is now more general and can be set to True regardless of the number of hue variable levels (or even without hue). This is probably most useful for showing half violins.violinplot, the new inner_kws 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 BoxPlotContainer for easier post-plotting access.3369).objects.Plot (3223)objects.Plot (3225).objects.Plot via the new label parameter in objects.Plot.add (3456).objects.Plot.scale, objects.Plot.limit, and objects.Plot.label the x / y parameters can be used to set a common scale / limit / label for paired subplots (3458).3467).ecdfplot, stat="percent" is now a valid option (3336).3488).histplot, infinite values are now ignored when choosing the default bin range (3488).3440).load_dataset to use an approach more compatible with pyiodide (3234).3452).histplot, treatment of the binwidth 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 (3489).objects.Bar and objects.Bars widths when using a nonlinear scale (3217).move_legend when labels were provided (3454).histplot added a stray empty BarContainer (3246).objects.Plot.on would override a figure's layout engine (3216).lineplot with a list of tuples for the keyword argument dashes caused a TypeError (3316).PairGrid that caused an exception when the input dataframe had a column multiindex (3407).3394).This is a release candidate for seaborn v0.13.0, a major release with a complete overhaul of seaborn's categorical plotting functions.
Please test the release candidate, especially the categorical plots. The internals of these functions have been completely rewritten to provide new functionality and to better align with the rest of the library. There are some intentional changes to default behavior / deprecations, but also the potential for unintentional breakage. Please help surface any examples of the latter prior to final release.
See the Release Notes for more information about the new features and changes.
Please open a GitHub issue with a reproducible example demonstrating any problems that you encounter. The final release is targeted for the end of September.
This is an incremental release that is a recommended upgrade for all users. It is very likely the final release of the 0.12 series and the last version to support Python 3.7.
|Feature| Added the objects.KDE stat (#3111).
|Feature| Added the objects.Boolean scale (#3205).
|Enhancement| Improved user feedback for failures during plot compilation by catching exceptions and re-raising with a PlotSpecError that provides additional context. (#3203).
|Fix| Improved calculation of automatic mark widths with unshared facet axes (#3119).
|Fix| Improved robustness to empty data in several components of the objects interface (#3202).
|Fix| Fixed a bug where legends for numeric variables with large values would be incorrectly shown (i.e. with a missing offset or exponent; #3187).
|Fix| Fixed a regression in v0.12.0 where manually-added labels could have duplicate legend entries (#3116).
|Fix| Fixed a bug in histplot with kde=True and log_scale=True where the curve was not scaled properly (#3173).
|Fix| Fixed a bug in relplot where inner axis labels would be shown when axis sharing was disabled (#3180).
|Fix| Fixed a bug in objects.Continuous to avoid an exception with boolean data (#3190).
This is an incremental release that is a recommended upgrade for all users. It addresses a handful of bugs / regressions in v0.12.0 and adds several features and enhancements to the new objects interface.
objects.Text mark (#3051).objects.Dash mark (#3074).objects.Perc stat (#3063).objects.Count stat (#3086).objects.Band and objects.Range marks will now cover the full
extent of the data if min / max variables are not explicitly assigned or
added in a transform (#3056).objects.Jitter move now applies a small amount of jitter by
default (#3066).objects.Nominal scale now appear like categorical axes
in classic seaborn, with fixed margins, no grid, and an inverted y
axis (#3069).objects.Continuous.label method now accepts base=None to override the default formatter
with a log transform (#3087).objects.Line) now use a
stable algorithm (#3064).label parameter to pointplot,
which addresses a regression in 0.12.0 when pointplot is passed to
FacetGrid (#3016).objects.Plot (#3055).objects.PolyFit robust to missing data (#3010).objects.Plot that occurred when data assigned to the
orient coordinate had zero variance (#3084).kdeplot where passing cmap for an unfilled bivariate plot would
raise an exception (#3065).lineplot with a large number
of unique x values (#3081).This release debuts the seaborn.objects 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 ggplot2 and vega-lite 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.
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 data is the first and only positional argument. This adds consistency across the various functions in the library. It also means that calling func(data) 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 x and y can be positional, but minimal support for positional arguments after this change will reduce the chance of inadvertent mis-specification (2804).
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):
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.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.hue when using only one coordinate variable (i.e. only x or y).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:
scatterplot. Pass palette="deep" to reproduce previous defaults.Similar enhancements / updates should be expected to roll out to other categorical plotting functions in future releases. There are also several function-specific enhancements:
stripplot, a "strip" with a single observation will be plotted without jitter (2413)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).swarmplot, the proportion of points that must overlap before issuing a warning can now be controlled with the warn_thresh parameter (2447).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).Increased the flexibility of what can be shown by the internally-calculated errorbars for lineplot, barplot, and pointplot.
With the new errorbar 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 ci parameter has been deprecated. Note that regplot retains the previous API, but it will likely be updated in a future release (2407, 2866).
lineplot along the y axis using orient="y" (2854).FacetGrid / PairGrid / JointGrid with a fluent (method-chained) style by adding apply/ pipe methods. Additionally, fixed the tight_layout and refline methods so that they return self (2926).FacetGrid.tick_params and PairGrid.tick_params to customize the appearance of the ticks, tick labels, and gridlines of all subplots at once (2944).barplot (2860).barplot and pointplot, in addition to a callable (2866).regplot now inherit the alpha value of the points they correspond to (2540).pairplot with corner=True and diag_kind=None, the top left y axis label is no longer hidden (2850).histplot as a step function or polygon (2859).boxenplot with box_kws/line_kws/flier_kws (2909).2449).2776).histplot and kdeplot where weights were not factored into the normalization (2812).histplot when only binwidth was provided (2813).violinplot where inner boxes/points could be missing with unpaired split violins (2814).PairGrid where an error would be raised when defining hue only in the mapping methods (2847).scatterplot where an error would be raised when hue_order was a subset of the hue levels (2848).histplot where dodged bars would have different widths on a log scale (2849).lineplot, allowed the dashes keyword to set the style of a line without mapping a style variable (2449).relplot for "wide" data and for faceting variables passed as non-pandas objects (2846).FacetGrid.map or FacetGrid.map_dataframe (2705).2925).kdeplot (2862).rugplot was ignoring expand_margins=False (2953).set_palette (or set_theme). This should have no general effect, because the matplotlib default is now "C0" (2906).2398).2773).2833).pointplot.This is the first release candidate for seaborn v0.12, a major update introducing an entirely new interface along with numerous features, enhancements, and fixes for existing functionality.
To install for testing, run
pip install seaborn==0.12.0rc0
There were several renamings and API changes from the final beta release. See the referenced PRs for more information on each change.
Scatter -> Dots (#2942)Ribbon -> Band (#2945)Interval -> Range (#2945)Plot API changesstat= and move= parameters were removed from Plot.add, which now has the following signature: Plot.add(mark, *transforms, ...). (#2948)Plot.configure method was renamed to Plot.layout, with the figsize parameter changed to size. The share{x,y} parameters were removed from Plot.layout, with that functionality now supported by the new Plot.share method. (#2954)Additionally, the install extra for including statistical packages was changed from seaborn[all] to seaborn[stats]. (#2939)
This is the third and final beta release for seaborn v0.12, a major update introducing an entirely new interface along with numerous features, enhancements, and fixes for existing functionality.
To install for testing, run
pip install seaborn==0.12.0b3
Changes from the second beta release:
Est stat for aggregating with a flexible error bar interval (#2912)Interval mark for drawing lines perpendicular to the orient axis (#2912)Plot.theme for basic control over figure appearance (#2929)Plot.label to control plot titles (#2934)Plot.scale so that it applies to variables added during the stat transform (#2915)Plot.configure spec would not persist after further method calls (#2917)artist_kws parameter (#2921).apply and .pipe methods to FacetGrid/PairGrid/JointGrid for fluent customization (#2928)This is the second beta release for seaborn v0.12, a major update introducing an entirely new interface along with numerous features, enhancements, and fixes for existing functionality.
To install for testing, run
pip install seaborn==0.12.0b2
Changes from the first beta release:
Plot.label method for controlling axis labels/legend titles (#2902)Plot.limit method for controlling axis limits (#2898)Bars, a more efficient mark for histograms, and improved performance of Bar mark as well (#2893)Area and Ribbon marks used a simpler matplotlib artist class for them (#2896)Bar mark (#2889)