seaborn Documentation

File: README.md Copy Chapter

seaborn: statistical data visualization

Seaborn is a Python visualization library based on matplotlib. It provides a high-level interface for drawing attractive statistical graphics.

Documentation Copy Chapter

Online documentation is available at seaborn.pydata.org.

The docs include a tutorial, example gallery, API reference, FAQ, and other useful information.

To build the documentation locally, please refer to doc/README.md.

Dependencies Copy Chapter

Seaborn supports Python 3.10+.

Installation requires numpy, pandas, and matplotlib. Some advanced statistical functionality requires scipy and/or statsmodels.

Installation Copy Chapter

The latest stable release (and required dependencies) can be installed from PyPI:

uv pip install seaborn

It is also possible to include optional statistical dependencies:

uv pip install seaborn[stats]

Seaborn can also be installed with conda:

conda install seaborn

Note that the main anaconda repository lags PyPI in adding new releases, but conda-forge (-c conda-forge) typically updates quickly.

Citing Copy Chapter

A paper describing seaborn has been published in the Journal of Open Source Software. The paper provides an introduction to the key features of the library, and it can be used as a citation if seaborn proves integral to a scientific publication.

Testing Copy Chapter

Testing seaborn requires installing additional dependencies; they will be installed when running uv sync with a source checkout.

To test the code, run make test in the source directory. This will exercise the unit tests (using pytest) and generate a coverage report.

Code style is enforced with ruff using the settings in the pyproject.toml file. Run make lint to check. Alternately, you can use pre-commit to automatically run lint checks on any files you are committing: just run pre-commit install to set it up, and then commit as usual going forward.

Development Copy Chapter

Seaborn development takes place on Github: https://github.com/mwaskom/seaborn

Please submit bugs that you encounter to the issue tracker with a reproducible example demonstrating the problem. Questions about usage are more at home on StackOverflow, where there is a seaborn tag.

File: doc/_templates/autosummary/base.rst Copy Chapter

{{ fullname | escape | underline}}

.. currentmodule:: {{ module }}

.. auto{{ objtype }}:: {{ objname }}

File: doc/_templates/autosummary/class.rst Copy Chapter

{{ fullname | escape | underline}}

.. currentmodule:: {{ module }}

.. autoclass:: {{ objname }}

{% block methods %}
.. automethod:: init

{% if methods %}
.. rubric:: Methods

.. autosummary::
:toctree: ./
{% for item in methods %}
~{{ name }}.{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}

{% block attributes %}
{% if attributes %}
.. rubric:: Attributes

.. autosummary::
{% for item in attributes %}
~{{ name }}.{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}

File: doc/_templates/autosummary/object.rst Copy Chapter

{{ fullname | escape | underline}}

.. currentmodule:: {{ module }}

.. autoclass:: {{ objname }}

File: doc/_templates/autosummary/plot.rst Copy Chapter

{{ fullname | escape | underline}}

.. currentmodule:: {{ module }}

.. autoclass:: {{ objname }}

{% block methods %}

Methods

.. rubric:: Specification methods

.. autosummary::
   :toctree: ./
   :nosignatures:

   ~Plot.add
   ~Plot.scale

.. rubric:: Subplot methods

.. autosummary::
   :toctree: ./
   :nosignatures:

   ~Plot.facet
   ~Plot.pair

.. rubric:: Customization methods

.. autosummary::
   :toctree: ./
   :nosignatures:

   ~Plot.layout
   ~Plot.label
   ~Plot.limit
   ~Plot.share
   ~Plot.theme

.. rubric:: Integration methods

.. autosummary::
   :toctree: ./
   :nosignatures:

   ~Plot.on

.. rubric:: Output methods

.. autosummary::
   :toctree: ./
   :nosignatures:

   ~Plot.plot
   ~Plot.save
   ~Plot.show

{% endblock %}

.. _plot_config:

Configuration

The :class:Plot object's default behavior can be configured through its :attr:Plot.config attribute. Notice that this is a property of the class, not a method on an instance.

.. include:: ../docstrings/objects.Plot.config.rst

File: doc/_templates/autosummary/scale.rst Copy Chapter

{{ fullname | escape | underline}}

.. currentmodule:: {{ module }}

.. autoclass:: {{ objname }}

.. automethod:: tick

.. automethod:: label

File: doc/whatsnew/index.rst Copy Chapter

.. _whatsnew:

Seaborn changelog

v0.13 Copy Chapter

.. toctree::
:maxdepth: 2

v0.13.2
v0.13.1
v0.13.0

v0.12 Copy Chapter

.. toctree::
:maxdepth: 2

v0.12.2
v0.12.1
v0.12.0

v0.11 Copy Chapter

.. toctree::
:maxdepth: 2

v0.11.2
v0.11.1
v0.11.0

v0.10 Copy Chapter

.. toctree::
:maxdepth: 2

v0.10.1
v0.10.0

v0.9 Copy Chapter

.. toctree::
:maxdepth: 2

v0.9.1
v0.9.0

v0.8 Copy Chapter

.. toctree::
:maxdepth: 2

v0.8.1
v0.8.0

v0.7 Copy Chapter

.. toctree::
:maxdepth: 2

v0.7.1
v0.7.0

v0.6 Copy Chapter

.. toctree::
:maxdepth: 2

v0.6.0

v0.5 Copy Chapter

.. toctree::
:maxdepth: 2

v0.5.1
v0.5.0

v0.4 Copy Chapter

.. toctree::
:maxdepth: 2

v0.4.0

v0.3 Copy Chapter

.. toctree::
:maxdepth: 2

v0.3.1
v0.3.0

v0.2 Copy Chapter

.. toctree::
:maxdepth: 2

v0.2.1
v0.2.0

File: doc/whatsnew/v0.2.0.rst Copy Chapter

v0.2.0 (December 2013) Copy Chapter

This is a major release from 0.1 with a number of API changes, enhancements,
and bug fixes.

Highlights include an overhaul of timeseries plotting to work intelligently
with dataframes, the new function interactplot() for visualizing continuous
interactions, bivariate kernel density estimates in kdeplot(), and
significant improvements to color palette handling.

Version 0.2 also introduces experimental support for Python 3.

In addition to the library enhancements, the documentation has been
substantially rewritten to reflect the new features and improve the
presentation of the ideas behind the package.

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

Plotting functions
^^^^^^^^^^^^^^^^^^

- The ``corrplot()`` function can be drawn without the correlation coefficient
  annotation and with variable names on the side of the plot to work with large
  datasets.

- Additionally, ``corrplot()`` sets the color palette intelligently based on
  the direction of the specified test.

- The ``distplot()`` histogram uses a reference rule to choose the bin size if it
  is not provided.

- Added the ``x_bins`` option in ``lmplot()`` for binning a continuous
  predictor variable, allowing for clearer trends with many datapoints.

- Enhanced support for labeling plot elements and axes based on ``name``
  attributes in several distribution plot functions and ``tsplot()`` for
  smarter Pandas integration.

- Scatter points in ``lmplot()`` are slightly transparent so it is easy to see
  where observations overlap.

- Added the ``order`` parameter to ``boxplot()`` and ``violinplot()`` to
  control the order of the bins when using a Pandas object.

- When an ``ax`` argument is not provided to a plotting function, it grabs the
  currently active axis instead of drawing a new one.

Color palettes
^^^^^^^^^^^^^^

- Added the ``dark_palette()`` and ``blend_palette()`` for on-the-fly creation
  of blended color palettes.

- The color palette machinery is now intelligent about qualitative ColorBrewer
  palettes (``Set1``, ``Paired``, etc.), which are properly treated as discrete.

- Seaborn color palettes (``deep``, ``muted``, etc.) have been standardized in
  terms of basic hue sequence, and all palettes now have 6 colors.

- Introduced ``{mpl_palette}_d`` palettes, which make a palette with the basic
  color scheme of the source palette, but with a sequential blend from dark
  instead of light colors for use with line/scatter/contour plots.

- Added the ``palette_context()`` function for blockwise color palettes
  controlled by a ``with`` statement.

Plot styling
^^^^^^^^^^^^

- Added the ``despine()`` function for easily removing plot spines.

- A new plot style, ``"ticks"`` has been added.

- Tick labels are padded a bit farther from the axis in all styles, avoiding
  collisions at (0, 0).

General package issues
^^^^^^^^^^^^^^^^^^^^^^

- Reorganized the package by breaking up the monolithic ``plotobjs`` module
  into smaller modules grouped by general objective of the constituent plots.

- Removed the ``scikits-learn`` dependency in ``moss``.

- Installing with ``pip`` should automatically install most missing dependencies.

- The example notebooks are now used as an automated test suite.

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.

---

## File: doc/whatsnew/v0.2.1.rst

v0.2.1 (December 2013)
----------------------

This is a bugfix release, with no new features.

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.

---

## File: doc/whatsnew/v0.3.0.rst

v0.3.0 (March 2014)
-------------------

This is a major release from 0.2 with a number of enhancements to the plotting capabilities and styles. Highlights include :class:`FacetGrid`, ``factorplot``, :func:`jointplot`, and an overhaul to :ref:`style management <aesthetics_tutorial>`. There is also lots of new documentation, including an :ref:`example gallery <example_gallery>` and reorganized :ref:`tutorial <tutorial>`.

New plotting functions

• The :class: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 :ref:tutorial <facet_grid> for more information.

• Version 0.3 introduces the factorplot function, which is similar in spirit to :func: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 :func:pointplot and :func: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 :func:jointplot, which is built using the new :class:JointGrid object. :func:jointplot generalizes the behavior of :func:regplot in previous versions of seaborn (:func: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 :func: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 :class:JointGrid directly to build up more complex plots when the default methods offered by :func:jointplot are not suitable for your visualization problem. The tutorial for :class:JointGrid has more examples of how this object can be useful.

• The :func:residplot function complements :func: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 :func:jointplot.

API changes

- The most noticeable change will be that :func:`regplot` no longer produces a multi-component plot with distributions in marginal axes. Instead. :func:`regplot` is now an "Axes-level" function that can be plotted into any existing figure on a specific set of axes. :func:`regplot` and :func:`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 :func:`regplot`, use :func:`jointplot` with ``kind="reg"``.

- As noted above, :func:`lmplot` has been rewritten to exploit the :class:`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 :func:`lmplot` function now returns the :class:`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, :func:`axes_style` and :func:`set_style`, :func:`plotting_context` and :func:`set_context`, and :func:`color_palette` and :func:`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 :func:`set` now also takes a dictionary to update any of the matplotlib defaults. See the :ref:`tutorial <aesthetics_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

Using the package
^^^^^^^^^^^^^^^^^

• If you want to use plotting functions provided by the package without setting the matplotlib style to a seaborn theme, you can now do import seaborn.apionly as sns or from seaborn.apionly import lmplot, etc. This is using the (also new) :func:reset_orig function, which returns the rc parameters to what they are at matplotlib import time — i.e. they will respect any custom matplotlibrc settings on top of the matplotlib defaults.

• The dependency load of the package has been reduced. It can now be installed and used with only numpy, scipy, matplotlib, and pandas. Although statsmodels is still recommended for full functionality, it is not required.

Plotting functions
^^^^^^^^^^^^^^^^^^

• :func:lmplot (and :func:regplot) have two new options for fitting regression models: lowess and robust. The former fits a nonparametric smoother, while the latter fits a regression using methods that are less sensitive to outliers.

• The regression uncertainty in :func:lmplot and :func:regplot is now estimated with fewer bootstrap iterations, so plotting should be faster.

• The univariate :func:kdeplot can now be drawn as a cumulative density plot.

• Changed :func:interactplot to use a robust calculation of the data range when finding default limits for the contour colormap to work better when there are outliers in the data.

Style
^^^^^

• There is a new style, dark, which shares most features with darkgrid but does not draw a grid by default.

• There is a new function, :func:offset_spines, and a corresponding option in :func:despine called trim. Together, these can be used to make plots where the axis spines are offset from the main part of the figure and limited within the range of the ticks. This is recommended for use with the ticks style.

• Other aspects of the seaborn styles have been tweaked for more attractive plots.