What’s new in each version¶

Looking forward¶

Now that seaborn is a Python 3 library, it can take advantage of keyword-only arguments. It is likely that future versions will introduce this syntax, potentially in a breaking way. For guidance, most seaborn functions have a signature that looks like

func(x, y, ..., data=None, **kwargs)

where the **kwargs are specified in the function. Going forward it will likely be necessary to specify data and all subsequent arguments with an explicit key=value mapping. This style has long been used throughout the documentation, and the formal requirement will not be introduced until at least the next major release. Adding this feature will make it possible to enhance some older functions with more modern capabilities (e.g., adding a native hue semantic within functions like jointplot() and regplot()) and will allow parameters that control new features to be situated nearby related, making them more discoverable.

New features¶

• Added more control over the arrangement of the elements drawn by clustermap() with the {dendrogram,colors}_ratio and cbar_pos parameters. Additionally, the default organization and scaling with different figure sizes has been improved.

• Added the corner option to PairGrid and pairplot() to make a grid without the upper triangle of bivariate axes.

• Added the ability to seed the random number generator for the bootstrap used to define error bars in several plots. Relevant functions now have a seed parameter, which can take either fixed seed (typically an int) or a numpy random number generator object (either the newer numpy.random.Generator or the older numpy.random.mtrand.RandomState).

• Generalized the idea of “diagonal” axes in PairGrid to any axes that share an x and y variable.

• In PairGrid, the hue variable is now excluded from the default list of variables that make up the rows and columns of the grid.

• Exposed the layout_pad parameter in PairGrid and set a smaller default than what matptlotlib sets for more efficient use of space in dense grids.

• It is now possible to force a categorical interpretation of the hue variable in a relational plot by passing the name of a categorical palette (e.g. "deep", or "Set2"). This complements the (previously supported) option of passing a list/dict of colors.

• Added the tree_kws parameter to clustermap() to control the properties of the lines in the dendrogram.

• Added the ability to pass hierarchical label names to the FacetGrid legend, which also fixes a bug in relplot() when the same label appeared in different semantics.

• Improved support for grouping observations based on pandas index information in categorical plots.

Bug fixes and adaptations¶

• Avoided an error when singular data is passed to kdeplot(), issuing a warning instead. This makes pairplot() more robust.

• Fixed the behavior of dropna in PairGrid to properly exclude null datapoints from each plot when set to True.

• Fixed an issue where regplot() could interfere with other axes in a multi-plot matplotlib figure.

• Semantic variables with a category data type will always be treated as categorical in relational plots.

• Avoided a warning about color specifications that arose from boxenplot() on newer matplotlibs.

• Adapted to a change in how matplotlib scales axis margins, which caused multiple calls to regplot() with truncate=False to progressively expand the x axis limits. Because there are currently limitations on how autoscaling works in matplotlib, the default value for truncate in seaborn has also been changed to True.

• Relational plots no longer error when hue/size data are inferred to be numeric but stored with a string datatype.

• Relational plots now consider semantics with only a single value that can be interpreted as boolean (0 or 1) to be categorical, not numeric.

• Relational plots now handle list or dict specifications for sizes correctly.

• Fixed an issue in pointplot() where missing levels of a hue variable would cause an exception after a recent update in matplotlib.

• Fixed a bug when setting the rotation of x tick labels on a FacetGrid.

• Fixed a bug where values would be excluded from categorical plots when only one variable was a pandas Series with a non-default index.

• Fixed a bug when using Series objects as arguments for x_partial or y_partial in regplot().

• Fixed a bug when passing a norm object and using color annotations in clustermap().

• Fixed a bug where annotations were not rearranged to match the clustering in clustermap().

• Fixed a bug when trying to call set() while specifying a list of colors for the palette.

• Fixed a bug when resetting the color code short-hands to the matplotlib default.

• Avoided errors from stricter type checking in upcoming numpy changes.

• Avoided error/warning in lineplot() when plotting categoricals with empty levels.

• Allowed colors to be passed through to a bivariate kdeplot().

• Standardized the output format of custom color palette functions.

• Fixed a bug where legends for numerical variables in a relational plot could show a surprisingly large number of decimal places.

• Improved robustness to missing values in distribution plots.

• Made it possible to specify the location of the FacetGrid legend using matplotlib keyword arguments.

New relational plots¶

Three completely new plotting functions have been added: relplot(), scatterplot(), and lineplot(). The first is a figure-level interface to the latter two that combines them with a FacetGrid. The functions bring the high-level, dataset-oriented API of the seaborn categorical plotting functions to more general plots (scatter plots and line plots).

These functions can visualize a relationship between two numeric variables while mapping up to three additional variables by modifying hue, size, and/or style semantics. The common high-level API is implemented differently in the two functions. For example, the size semantic in scatterplot() scales the area of scatter plot points, but in lineplot() it scales width of the line plot lines. The API is dataset-oriented, meaning that in both cases you pass the variable in your dataset rather than directly specifying the matplotlib parameters to use for point area or line width.

Another way the relational functions differ from existing seaborn functionality is that they have better support for using numeric variables for hue and size semantics. This functionality may be propagated to other functions that can add a hue semantic in future versions; it has not been in this release.

The lineplot() function also has support for statistical estimation and is replacing the older tsplot function, which still exists but is marked for removal in a future release. lineplot() is better aligned with the API of the rest of the library and more flexible in showing relationships across additional variables by modifying the size and style semantics independently. It also has substantially improved support for date and time data, a major pain factor in tsplot. The cost is that some of the more esoteric options in tsplot for representing uncertainty (e.g. a colormapped KDE of the bootstrap distribution) have not been implemented in the new function.

There is quite a bit of new documentation that explains these new functions in more detail, including detailed examples of the various options in the API reference and a more verbose tutorial.

These functions should be considered in a “stable beta” state. They have been thoroughly tested, but some unknown corner cases may remain to be found. The main features are in place, but not all planned functionality has been implemented. There are planned improvements to some elements, particularly the default legend, that are a little rough around the edges in this release. Finally, some of the default behavior (e.g. the default range of point/line sizes) may change somewhat in future releases.

Updates to themes and palettes¶

Several changes have been made to the seaborn style themes, context scaling, and color palettes. In general the aim of these changes was to make the seaborn styles more consistent with the style updates in matplotlib 2.0 and to leverage some of the new style parameters for better implementation of some aspects of the seaborn styles. Here is a list of the changes:

• Reorganized and updated some axes_style()/plotting_context() parameters to take advantage of improvements in the matplotlib 2.0 update. The biggest change involves using several new parameters in the “style” spec while moving parameters that used to implement the corresponding aesthetics to the “context” spec. For example, axes spines and ticks are now off instead of having their width/length zeroed out for the darkgrid style. That means the width/length of these elements can now be scaled in different contexts. The effect is a more cohesive appearance of the plots, especially in larger contexts. These changes include only minimal support for the 1.x matplotlib series. Users who are stuck on matplotlib 1.5 but wish to use seaborn styling may want to use the seaborn parameters that can be accessed through the matplotlib stylesheet interface.

• Updated the seaborn palettes (“deep”, “muted”, “colorblind”, etc.) to correspond with the new 10-color matplotlib default. The legacy palettes are now available at “deep6”, “muted6”, “colorblind6”, etc. Additionally, a few individual colors were tweaked for better consistency, aesthetics, and accessibility.

• Calling color_palette() (or set_palette()) with a named qualitative palettes (i.e. one of the seaborn palettes, the colorbrewer qualitative palettes, or the matplotlib matplotlib tableau-derived palettes) and no specified number of colors will return all of the colors in the palette. This means that for some palettes, the returned list will have a different length than it did in previous versions.

• Enhanced color_palette() to accept a parameterized specification of a cubehelix palette in in a string, prefixed with "ch:" (e.g. "ch:-.1,.2,l=.7"). Note that keyword arguments can be spelled out or referenced using only their first letter. Reversing the palette is accomplished by appending "_r", as with other matplotlib colormaps. This specification will be accepted by any seaborn function with a palette= parameter.

• Slightly increased the base font sizes in plotting_context() and increased the scaling factors for "talk" and "poster" contexts.

• Calling set() will now call set_color_codes() to re-assign the single letter color codes by default

API changes¶

A few functions have been renamed or have had changes to their default parameters.

• The factorplot function has been renamed to catplot(). The new name ditches the original R-inflected terminology to use a name that is more consistent with terminology in pandas and in seaborn itself. This change should hopefully make catplot() easier to discover, and it should make more clear what its role is. factorplot still exists and will pass its arguments through to catplot() with a warning. It may be removed eventually, but the transition will be as gradual as possible.

• The other reason that the factorplot name was changed was to ease another alteration which is that the default kind in catplot() is now "strip" (corresponding to stripplot()). This plots a categorical scatter plot which is usually a much better place to start and is more consistent with the default in relplot(). The old default style in factorplot ("point", corresponding to pointplot()) remains available if you want to show a statistical estimation.

• The lvplot function has been renamed to boxenplot(). The “letter-value” terminology that was used to name the original kind of plot is obscure, and the abbreviation to lv did not help anything. The new name should make the plot more discoverable by describing its format (it plots multiple boxes, also known as “boxen”). As with factorplot, the lvplot function still exists to provide a relatively smooth transition.

• Renamed the size parameter to height in multi-plot grid objects (FacetGrid, PairGrid, and JointGrid) along with functions that use them (factorplot, lmplot(), pairplot(), and jointplot()) to avoid conflicts with the size parameter that is used in scatterplot and lineplot (necessary to make relplot() work) and also makes the meaning of the parameter a bit more clear.

• Changed the default diagonal plots in pairplot() to use func:kdeplot` when a "hue" dimension is used.

• Deprecated the statistical annotation component of JointGrid. The method is still available but will be removed in a future version.

• Two older functions that were deprecated in earlier versions, coefplot and interactplot, have undergone final removal from the code base.

Documentation improvements¶

There has been some effort put into improving the documentation. The biggest change is that the introduction to the library has been completely rewritten to provide much more information and, critically, examples. In addition to the high-level motivation, the introduction also covers some important topics that are often sources of confusion, like the distinction between figure-level and axes-level functions, how datasets should be formatted for use in seaborn, and how to customize the appearance of the plots.

Other improvements have been made throughout, most notably a thorough re-write of the categorical tutorial.

Other small enhancements and bug fixes¶

• Changed rugplot() to plot a matplotlib LineCollection instead of many Line2D objects, providing a big speedup for large arrays.

• Changed the default off-diagonal plots to use scatterplot(). (Note that the "hue" currently draws three separate scatterplots instead of using the hue semantic of the scatterplot function).

• Changed color handling when using kdeplot() with two variables. The default colormap for the 2D density now follows the color cycle, and the function can use color and label kwargs, adding more flexibility and avoiding a warning when using with multi-plot grids.

• Added the subplot_kws parameter to PairGrid for more flexibility.

• Removed a special case in PairGrid that defaulted to drawing stacked histograms on the diagonal axes.

• Fixed jointplot()/JointGrid and regplot() so that they now accept list inputs.

• Fixed a bug in FacetGrid when using a single row/column level or using col_wrap=1.

• Fixed functions that set axis limits so that they preserve auto-scaling state on matplotlib 2.0.

• Avoided an error when using matplotlib backends that cannot render a canvas (e.g. PDF).

• Changed the install infrastructure to explicitly declare dependencies in a way that pip is aware of. This means that pip install seaborn will now work in an empty environment. Additionally, the dependencies are specified with strict minimal versions.

• Updated the testing infrastructure to execute tests with pytest (although many individual tests still use nose assertion).

Changes and updates to categorical plots¶

In version 0.6, the “categorical” plots have been unified with a common API. This new category of functions groups together plots that show the relationship between one numeric variable and one or two categorical variables. This includes plots that show distribution of the numeric variable in each bin (boxplot(), violinplot(), and stripplot()) and plots that apply a statistical estimation within each bin (pointplot(), barplot(), and countplot()). There is a new tutorial chapter that introduces these functions.

The categorical functions now each accept the same formats of input data and can be invoked in the same way. They can plot using long- or wide-form data, and can be drawn vertically or horizontally. When long-form data is used, the orientation of the plots is inferred from the types of the input data. Additionally, all functions natively take a hue variable to add a second layer of categorization.

With the (in some cases new) API, these functions can all be drawn correctly by FacetGrid. However, factorplot can also now create faceted verisons of any of these kinds of plots, so in most cases it will be unnecessary to use FacetGrid directly. By default, factorplot draws a point plot, but this is controlled by the kind parameter.

Here are details on what has changed in the process of unifying these APIs:

• Changes to boxplot() and violinplot() will probably be the most disruptive. Both functions maintain backwards-compatibility in terms of the kind of data they can accept, but the syntax has changed to be more similar to other seaborn functions. These functions are now invoked with x and/or y parameters that are either vectors of data or names of variables in a long-form DataFrame passed to the new data parameter. You can still pass wide-form DataFrames or arrays to data, but it is no longer the first positional argument. See the github pull request (#410) for more information on these changes and the logic behind them.

• As pointplot() and barplot() can now plot with the major categorical variable on the y axis, the x_order parameter has been renamed to order.

• Added a hue argument to boxplot() and violinplot(), which allows for nested grouping the plot elements by a third categorical variable. For violinplot(), this nesting can also be accomplished by splitting the violins when there are two levels of the hue variable (using split=True). To make this functionality feasible, the ability to specify where the plots will be draw in data coordinates has been removed. These plots now are drawn at set positions, like (and identical to) barplot() and pointplot().

• Added a palette parameter to boxplot()/violinplot(). The color parameter still exists, but no longer does double-duty in accepting the name of a seaborn palette. palette supersedes color so that it can be used with a FacetGrid.

Along with these API changes, the following changes/enhancements were made to the plotting functions:

• The default rules for ordering the categories has changed. Instead of automatically sorting the category levels, the plots now show the levels in the order they appear in the input data (i.e., the order given by Series.unique()). Order can be specified when plotting with the order and hue_order parameters. Additionally, when variables are pandas objects with a “categorical” dtype, the category order is inferred from the data object. This change also affects FacetGrid and PairGrid.

• Added the scale and scale_hue parameters to violinplot(). These control how the width of the violins are scaled. The default is area, which is different from how the violins used to be drawn. Use scale='width' to get the old behavior.

• Used a different style for the box kind of interior plot in violinplot(), which shows the whisker range in addition to the quartiles. Use inner='quartile' to get the old style.

New plotting functions¶

• Added the stripplot() function, which draws a scatterplot where one of the variables is categorical. This plot has the same API as boxplot() and violinplot(). It is useful both on its own and when composed with one of these other plot kinds to show both the observations and underlying distribution.

• Added the countplot() function, which uses a bar plot representation to show counts of variables in one or more categorical bins. This replaces the old approach of calling barplot() without a numeric variable.

Other additions and changes¶

• The corrplot() and underlying symmatplot() functions have been deprecated in favor of heatmap(), which is much more flexible and robust. These two functions are still available in version 0.6, but they will be removed in a future version.

• Added the set_color_codes() function and the color_codes argument to set() and set_palette(). This changes the interpretation of shorthand color codes (i.e. “b”, “g”, k”, etc.) within matplotlib to use the values from one of the named seaborn palettes (i.e. “deep”, “muted”, etc.). That makes it easier to have a more uniform look when using matplotlib functions directly with seaborn imported. This could be disruptive to existing plots, so it does not happen by default. It is possible this could change in the future.

• The color_palette() function no longer trims palettes that are longer than 6 colors when passed into it.

• Added the as_hex method to color palette objects, to return a list of hex codes rather than rgb tuples.

• jointplot() now passes additional keyword arguments to the function used to draw the plot on the joint axes.

• Changed the default linewidths in heatmap() and clustermap() to 0 so that larger matrices plot correctly. This parameter still exists and can be used to get the old effect of lines demarcating each cell in the heatmap (the old default linewidths was 0.5).

• heatmap() and clustermap() now automatically use a mask for missing values, which previously were shown with the “under” value of the colormap per default plt.pcolormesh behavior.

• Added the seaborn.crayons dictionary and the crayon_palette() function to define colors from the 120 box (!) of Crayola crayons.

• Added the line_kws parameter to residplot() to change the style of the lowess line, when used.

• Added open-ended **kwargs to the add_legend method on FacetGrid and PairGrid, which will pass additional keyword arguments through when calling the legend function on the Figure or Axes.

• Added the gridspec_kws parameter to FacetGrid, which allows for control over the size of individual facets in the grid to emphasize certain plots or account for differences in variable ranges.

• The interactive palette widgets now show a continuous colorbar, rather than a discrete palette, when as_cmap is True.

• The default Axes size for pairplot() and PairGrid is now slightly smaller.

• Added the shade_lowest parameter to kdeplot() which will set the alpha for the lowest contour level to 0, making it easier to plot multiple bivariate distributions on the same axes.

• The height parameter of rugplot() is now interpreted as a function of the axis size and is invariant to changes in the data scale on that axis. The rug lines are also slightly narrower by default.

• Added a catch in distplot() when calculating a default number of bins. For highly skewed data it will now use sqrt(n) bins, where previously the reference rule would return “infinite” bins and cause an exception in matplotlib.

• Added a ceiling (50) to the default number of bins used for distplot() histograms. This will help avoid confusing errors with certain kinds of datasets that heavily violate the assumptions of the reference rule used to get a default number of bins. The ceiling is not applied when passing a specific number of bins.

• The various property dictionaries that can be passed to plt.boxplot are now applied after the seaborn restyling to allow for full customizability.

• Added a savefig method to JointGrid that defaults to a tight bounding box to make it easier to save figures using this class, and set a tight bbox as the default for the savefig method on other Grid objects.

• You can now pass an integer to the xticklabels and yticklabels parameter of heatmap() (and, by extension, clustermap()). This will make the plot use the ticklabels inferred from the data, but only plot every n label, where n is the number you pass. This can help when visualizing larger matrices with some sensible ordering to the rows or columns of the dataframe.

• Added “figure.facecolor” to the style parameters and set the default to white.

• The load_dataset() function now caches datasets locally after downloading them, and uses the local copy on subsequent calls.

Bug fixes¶

• Fixed bugs in clustermap() where the mask and specified ticklabels were not being reorganized using the dendrograms.

• Fixed a bug in FacetGrid and PairGrid that lead to incorrect legend labels when levels of the hue variable appeared in hue_order but not in the data.

• Fixed a bug in FacetGrid.set_xticklabels() or FacetGrid.set_yticklabels() when col_wrap is being used.

• Fixed a bug in PairGrid where the hue_order parameter was ignored.

• Fixed two bugs in despine() that caused errors when trying to trim the spines on plots that had inverted axes or no ticks.

• Improved support for the margin_titles option in FacetGrid, which can now be used with a legend.

Plotting functions¶

• Added the heatmap() function for visualizing a matrix of data by color-encoding the values. See the docs for more information.

• Added the clustermap() function for clustering and visualizing a matrix of data, with options to label individual rows and columns by colors. See the docs for more information. This work was lead by Olga Botvinnik.

• lmplot() and pairplot() get a new keyword argument, markers. This can be a single kind of marker or a list of different markers for each level of the hue variable. Using different markers for different hues should let plots be more comprehensible when reproduced to black-and-white (i.e. when printed). See the github pull request (#323) for examples.

• More generally, there is a new keyword argument in FacetGrid and PairGrid, hue_kws. This similarly lets plot aesthetics vary across the levels of the hue variable, but more flexibily. hue_kws should be a dictionary that maps the name of keyword arguments to lists of values that are as long as the number of levels of the hue variable.

• The argument subplot_kws has been added to FacetGrid. This allows for faceted plots with custom projections, including maps with Cartopy.

Color palettes¶

• Added two new functions to create custom color palettes. For sequential palettes, you can use the light_palette() function, which takes a seed color and creates a ramp from a very light, desaturated variant of it. For diverging palettes, you can use the diverging_palette() function to create a balanced ramp between two endpoints to a light or dark midpoint. See the palette tutorial for more information.

• Added the ability to specify the seed color for light_palette() and dark_palette() as a tuple of husl or hls space values or as a named xkcd color. The interpretation of the seed color is now provided by the new input parameter to these functions.

• Added several new interactive palette widgets: choose_colorbrewer_palette(), choose_light_palette(), choose_dark_palette(), and choose_diverging_palette(). For consistency, renamed the cubehelix widget to choose_cubehelix_palette() (and fixed a bug where the cubehelix palette was reversed). These functions also now return either a color palette list or a matplotlib colormap when called, and that object will be live-updated as you play with the widget. This should make it easy to iterate over a plot until you find a good representation for the data. See the Github pull request or this notebook (download it to use the widgets) for more information.

• Overhauled the color palette tutorial to organize the discussion by class of color palette and provide more motivation behind the various choices one might make when choosing colors for their data.

Bug fixes¶

• Fixed a bug in PairGrid that gave incorrect results (or a crash) when the input DataFrame has a non-default index.

• Fixed a bug in PairGrid where passing columns with a date-like datatype raised an exception.

• Fixed a bug where lmplot() would show a legend when the hue variable was also used on either the rows or columns (making the legend redundant).

• Worked around a matplotlib bug that was forcing outliers in boxplot() to appear as blue.

• kdeplot() now accepts pandas Series for the data and data2 arguments.

• Using a non-default correlation method in corrplot() now implies sig_stars=False as the permutation test used to significance values for the correlations uses a pearson metric.

• Removed pdf.fonttype from the style definitions, as the value used in version 0.4 resulted in very large PDF files.

Plotting functions¶

• A new object, PairGrid, and a corresponding function pairplot(), for drawing grids of pairwise relationships in a dataset. This style of plot is sometimes called a “scatterplot matrix”, but the representation of the data in PairGrid is flexible and many styles other than scatterplots can be used. See the docs for more information. Note: due to a bug in older versions of matplotlib, you will have best results if you use these functions with matplotlib 1.4 or later.

• The rules for choosing default color palettes when variables are mapped to different colors have been unified (and thus changed in some cases). Now when no specific palette is requested, the current global color palette will be used, unless the number of variables to be mapped exceeds the number of unique colors in the palette, in which case the "husl" palette will be used to avoid cycling.

• Added a keyword argument hist_norm to distplot(). When a distplot() is now drawn without a KDE or parametric density, the histogram is drawn as counts instead of a density. This can be overridden by by setting hist_norm to True.

• When using FacetGrid with a hue variable, the legend is no longer drawn by default when you call FacetGrid.map(). Instead, you have to call FacetGrid.add_legend() manually. This should make it easier to layer multiple plots onto the grid without having duplicated legends.

• Made some changes to factorplot so that it behaves better when not all levels of the x variable are represented in each facet.

• Added the logx option to regplot() for fitting the regression in log space.

• When violinplot() encounters a bin with only a single observation, it will now plot a horizontal line at that value instead of erroring out.

Style and color palettes¶

• Added the cubehelix_palette() function for generating sequential palettes from the cubehelix system. See the palette docs for more information on how these palettes can be used. There is also the choose_cubehelix() which will launch an interactive app to select cubehelix parameters in the notebook.

• Added the xkcd_palette() and the xkcd_rgb dictionary so that colors can be specified with names from the xkcd color survey.

• Added the font_scale option to plotting_context(), set_context(), and set(). font_scale can independently increase or decrease the size of the font elements in the plot.

• Font-handling should work better on systems without Arial installed. This is accomplished by adding the font.sans-serif field to the axes_style definition with Arial and Liberation Sans prepended to matplotlib defaults. The font family can also be set through the font keyword argument in set(). Due to matplotlib bugs, this might not work as expected on matplotlib 1.3.

• The despine() function gets a new keyword argument offset, which replaces the deprecated offset_spines() function. You no longer need to offset the spines before plotting data.

• Added a default value for pdf.fonttype so that text in PDFs is editable in Adobe Illustrator.

Other API Changes¶

• Removed the deprecated set_color_palette and palette_context functions. These were replaced in version 0.3 by the set_palette() function and ability to use color_palette() directly in a with statement.

• Removed the ability to specify a nogrid style, which was renamed to white in 0.3.

Plotting functions¶

• The size of the points in pointplot() and factorplot are now scaled with the linewidth for better aesthetics across different plotting contexts.

• The pointplot() glyphs for different levels of the hue variable are drawn at different z-orders so that they appear uniform.

Bug Fixes¶

• Fixed a bug in FacetGrid (and thus affecting lmplot and factorplot) that appeared when col_wrap was used with a number of facets that did not evenly divide into the column width.

• Fixed an issue where the support for kernel density estimates was sometimes computed incorrectly.

• Fixed a problem where hue variable levels that were not strings were missing in FacetGrid legends.

• When passing a color palette list in a with statement, the entire palette is now used instead of the first six colors.

New plotting functions¶

• The FacetGrid class adds a new form of functionality to seaborn, providing a way to abstractly structure a grid of plots corresponding to subsets of a dataset. It can be used with a wide variety of plotting functions (including most of the matplotlib and seaborn APIs. See the tutorial for more information.

• Version 0.3 introduces the factorplot function, which is similar in spirit to lmplot() but intended for use when the main independent variable is categorical instead of quantitative. factorplot can draw a plot in either a point or bar representation using the corresponding Axes-level functions pointplot() and barplot() (which are also new). Additionally, the factorplot function can be used to draw box plots on a faceted grid. For examples of how to use these functions, you can refer to the tutorial.

• Another new function is jointplot(), which is built using the new JointGrid object. jointplot() generalizes the behavior of regplot() in previous versions of seaborn (regplot() has changed somewhat in 0.3; see below for details) by drawing a bivariate plot of the relationship between two variables with their marginal distributions drawn on the side of the plot. With jointplot(), you can draw a scatterplot or regression plot as before, but you can now also draw bivariate kernel densities or hexbin plots with appropriate univariate graphs for the marginal distributions. Additionally, it’s easy to use JointGrid directly to build up more complex plots when the default methods offered by jointplot() are not suitable for your visualization problem. The tutorial for JointGrid has more examples of how this object can be useful.

• The residplot() function complements regplot() and can be quickly used to diagnose problems with a linear model by calculating and plotting the residuals of a simple regression. There is also a "resid" kind for jointplot().

API changes¶

• The most noticeable change will be that regplot() no longer produces a multi-component plot with distributions in marginal axes. Instead. regplot() is now an “Axes-level” function that can be plotted into any existing figure on a specific set of axes. regplot() and lmplot() have also been unified (the latter uses the former behind the scenes), so all options for how to fit and represent the regression model can be used for both functions. To get the old behavior of regplot(), use jointplot() with kind="reg".

• As noted above, lmplot() has been rewritten to exploit the FacetGrid machinery. This involves a few changes. The color keyword argument has been replaced with hue, for better consistency across the package. The hue parameter will always take a variable name, while color will take a color name or (in some cases) a palette. The lmplot() function now returns the FacetGrid used to draw the plot instance.

• The functions that interact with matplotlib rc parameters have been updated and standardized. There are now three pairs of functions, axes_style() and set_style(), plotting_context() and set_context(), and color_palette() and set_palette(). In each case, the pairs take the exact same arguments. The first function defines and returns the parameters, and the second sets the matplotlib defaults. Additionally, the first function in each pair can be used in a with statement to temporarily change the defaults. Both the style and context functions also now accept a dictionary of matplotlib rc parameters to override the seaborn defaults, and set() now also takes a dictionary to update any of the matplotlib defaults. See the tutorial for more information.

• The nogrid style has been deprecated and changed to white for more uniformity (i.e. there are now darkgrid, dark, whitegrid, and white styles).

Other changes¶

Bug fixes¶

• Changed the mechanics of violinplot() and boxplot() when using a Series object as data and performing a groupby to assign data to bins to address a problem that arises in Pandas 0.13.

• Additionally fixed the groupby code to work with all styles of group specification (specifically, using a dictionary or a function now works).

• Fixed a bug where artifacts from the kde fitting could undershoot and create a plot where the density axis starts below 0.

• Ensured that data used for kde fitting is double-typed to avoid a low-level statsmodels error.

• Changed the implementation of the histogram bin-width reference rule to take a ceiling of the estimated number of bins.

API changes¶

• The tsplot() function was rewritten to accept data in a long-form DataFrame and to plot different traces by condition. This introduced a relatively minor but unavoidable API change, where instead of doing sns.tsplot(time, heights), you now must do sns.tsplot(heights, time=time) (the time parameter is now optional, for quicker specification of simple plots). Additionally, the "obs_traces" and "obs_points" error styles in tsplot() have been renamed to "unit_traces" and "unit_points", respectively.

• Functions that fit kernel density estimates (kdeplot() and violinplot()) now use statsmodels instead of scipy, and the parameters that influence the density estimate have changed accordingly. This allows for increased flexibility in specifying the bandwidth and kernel, and smarter choices for defining the range of the support. Default options should produce plots that are very close to the old defaults.

• The kdeplot() function now takes a second positional argument of data for drawing bivariate densities.

• The violin() function has been changed to violinplot(), for consistency. In 0.2, violin will still work, but it will fire a UserWarning.

New plotting functions¶

• The interactplot() function draws a contour plot for an interactive linear model (i.e., the contour shows y-hat from the model y ~ x1 * x2) over a scatterplot between the two predictor variables. This plot should aid the understanding of an interaction between two continuous variables.

• The kdeplot() function can now draw a bivariate density estimate as a contour plot if provided with two-dimensional input data.

• The palplot() function provides a simple grid-based visualization of a color palette.

Other changes¶

Bug fixes¶

• Fixed a bug where labels did not match data for boxplot() and violinplot() when using a groupby.

• Fixed a bug in the desaturate() function.

• Fixed a bug in the coefplot() figure size calculation.

• Fixed a bug where regplot() choked on list input.

• Fixed buggy behavior when drawing horizontal boxplots.

• Specifying bins for the distplot() histogram now works.

• Fixed a bug where kdeplot() would reset the axis height and cut off existing data.

• All axis styling has been moved out of the top-level seaborn.set() function, so context or color palette can be cleanly changed.