ridgeplot: beautiful ridgeline plots in Python

ridgeplot is a Python package that provides a simple interface for plotting beautiful and interactive ridgeline plots within the extensive Plotly ecosystem.

Installation

ridgeplot can be installed and updated from PyPi using pip:

pip install -U ridgeplot

For more information, see the installation guide.

Getting started

Take a look at the getting started guide, which provides a quick introduction to the ridgeplot library.

Basic example

For those in a hurry, here’s a very basic example on how to quickly get started with ridgeplot().

import numpy as np
from ridgeplot import ridgeplot

my_samples = [np.random.normal(n / 1.2, size=600) for n in range(9, 0, -1)]
fig = ridgeplot(samples=my_samples)
fig.update_layout(height=500, width=800)
fig.show()

Interactive output

Static image output

ridgeline plot example using the ridgeplot Python library

Installation#

Installing from PyPi#

ridgeplot can be installed and updated from PyPi using pip:

pip install -U ridgeplot

Installing from source#

The source code for this project is hosted on GitHub at: https://github.com/tpvasconcelos/ridgeplot

Take a look at the contributing guide for instructions on how to build from the git source. Further, refer to the instructions on creating a development environment if you wish to create a local development environment, or wish to contribute to the project.

Dependencies#

We try to keep the number of dependencies to a minimum and only use common and well-established libraries in the scientific python ecosystem. Currently, we only depend on the following 3 Python packages:

plotly - The interactive graphing backend that powers ridgeplot
statsmodels - Used for Kernel Density Estimation (KDE)
numpy - Supporting library for multidimensional array manipulations

Getting started#

This page provides a quick introduction to the ridgeplot library, showcasing some of its features and providing a few practical examples. All examples use the ridgeplot.ridgeplot() function, which is the main entry point to the library. For more information on the available options, take a look at the reference page.

Basic example#

This basic example shows how you can quickly get started with a simple call to the ridgeplot() function.

import numpy as np
from ridgeplot import ridgeplot

my_samples = [np.random.normal(n / 1.2, size=600) for n in range(9, 0, -1)]
fig = ridgeplot(samples=my_samples)
fig.update_layout(height=500, width=800)
fig.show()

Interactive output

Static image output

ridgeline plot example using the ridgeplot Python library

Flexible configuration#

In this example, we will try to replicate the first ridgeline plot in this from Data to Viz post. The example in the post was created using the “Perception of Probability Words” dataset (see load_probly()) and the popular ggridges R package. In the end, we will see how the ridgeplot Python library can be used to create a (nearly) identical plot, thanks to its extensive configuration options.

import numpy as np
from ridgeplot import ridgeplot
from ridgeplot.datasets import load_probly

# Load the probly dataset
df = load_probly()

# Let's grab the subset of columns used in the example
column_names = [
    "Almost Certainly",
    "Very Good Chance",
    "We Believe",
    "Likely",
    "About Even",
    "Little Chance",
    "Chances Are Slight",
    "Almost No Chance",
]
df = df[column_names]

# Not only does 'ridgeplot(...)' come configured with sensible defaults
# but is also fully configurable to your own style and preference!
fig = ridgeplot(
    samples=df.values.T,
    bandwidth=4,
    kde_points=np.linspace(-12.5, 112.5, 500),
    colorscale="viridis",
    colormode="row-index",
    coloralpha=0.65,
    labels=column_names,
    linewidth=2,
    spacing=5 / 9,
)

# And you can still update and extend the final
# Plotly Figure using standard Plotly methods
fig.update_layout(
    height=760,
    width=900,
    font_size=16,
    plot_bgcolor="white",
    xaxis_tickvals=[-12.5, 0, 12.5, 25, 37.5, 50, 62.5, 75, 87.5, 100, 112.5],
    xaxis_ticktext=["", "0", "", "25", "", "50", "", "75", "", "100", ""],
    xaxis_gridcolor="rgba(0, 0, 0, 0.1)",
    yaxis_gridcolor="rgba(0, 0, 0, 0.1)",
    yaxis_title="Assigned Probability (%)",
    showlegend=False,
)

# Show us the work!
fig.show()

Interactive output

Static image output

The resulting ridgeline plot generated by the code above: ridgeline plot of the probly dataset using the ridgeplot Python library

Target/reference image

The target reference from the from Data to Viz post: reference ridgeline plot of the probly dataset from data to viz

More traces#

In this example, we will dive a bit deeper into the samples parameter and see how we can be used to plot multiple traces per row in a ridgeline plot.

Final result#

For the ones in a hurry, we are including the entire final code-block and resulting plot already in this section. It is here also to serve as a reference for the rest of the section and to demonstrate what the goal of this example is. That said, throughout the rest of this section, we will dive a bit deeper into the samples parameter and understand how flexible it is.

Interactive output

Static image output

ridgeline plot of the Lincoln Weather dataset using the ridgeplot Python library

Code

import numpy as np
from ridgeplot import ridgeplot
from ridgeplot.datasets import load_lincoln_weather

# Load test data
df = load_lincoln_weather()

# Transform the data into a 3D (ragged) array format of
# daily min and max temperature samples per month
months = df.index.month_name().unique()
samples = [
    [
        df[df.index.month_name() == month]["Min Temperature [F]"],
        df[df.index.month_name() == month]["Max Temperature [F]"],
    ]
    for month in months
]

# And finish by styling it up to your liking!
fig = ridgeplot(
    samples=samples,
    labels=months,
    coloralpha=0.98,
    bandwidth=4,
    kde_points=np.linspace(-25, 110, 400),
    spacing=0.33,
    linewidth=2,
)
fig.update_layout(
    title="Minimum and maximum daily temperatures in Lincoln, NE (2016)",
    height=650,
    width=950,
    font_size=14,
    plot_bgcolor="rgb(245, 245, 245)",
    xaxis_gridcolor="white",
    yaxis_gridcolor="white",
    xaxis_gridwidth=2,
    yaxis_title="Month",
    xaxis_title="Temperature [F]",
    showlegend=False,
)
fig.show()

Step-by-step#

Let’s start by loading the “Lincoln Weather” test dataset (see load_lincoln_weather()).

>>> from ridgeplot.datasets import load_lincoln_weather
>>> df = load_lincoln_weather()
>>> df[["Min Temperature [F]", "Max Temperature [F]"]].head()
            Min Temperature [F]  Max Temperature [F]
CST
2016-01-01                   11                   37
2016-01-02                    5                   41
2016-01-03                    8                   37
2016-01-04                    4                   30
2016-01-05                   19                   38

The goal will be to plot the KDEs for the minimum and maximum daily temperatures for each month of 2016 (i.e. the year covered by the dataset).

>>> months = df.index.month_name().unique()
>>> months.to_list()
['January', 'February', 'March', 'April', 'May', 'June', 'July',
 'August', 'September', 'October', 'November', 'December']

The samples argument in the ridgeplot() function expects a 3D array of shape $(R, T_r, S_t)$, where $R$ is the number of rows, $T_r$ is the number of traces per row, and $S_t$ is the number of samples per trace, with:

Dimension values	Description
$R=12$	One row per month.
$T_r=2$ (for all rows $r \in R$)	Two traces per row (one for the minimum temperatures and one for the maximum temperatures).
$S_t \in \{29, 30, 31\}$	One sample per day of the month, where different months have different number of days.

We can create this array using a simple list comprehension, where each element of the list is a list of two arrays, one for the minimum temperatures and one for the maximum temperatures samples, for each month:

samples = [
    [
        df[df.index.month_name() == month]["Min Temperature [F]"],
        df[df.index.month_name() == month]["Max Temperature [F]"],
    ]
    for month in months
]

Note

For other use cases (like in the two previous examples), you could use a numpy ndarray to represent the samples. However, since different months have different number of days, we need to use a data container that can hold arrays of different lengths along the same dimension. Irregular arrays like this one are called ragged arrays. There are many different ways you can represent irregular arrays in Python. In this specific example, we used a list of lists of pandas Series. However,ridgeplot is designed to handle any object that implements the Collection[Collection[Collection[Numeric]]] protocol (i.e. any numeric 3D ragged array).

Finally, we can pass the samples list to the ridgeplot() function and specify any other arguments we want to customize the plot, like adjusting the KDE’s bandwidth, the vertical spacing between rows, etc.

fig = ridgeplot(
    samples=samples,
    labels=months,
    coloralpha=0.98,
    bandwidth=4,
    kde_points=np.linspace(-25, 110, 400),
    spacing=0.33,
    linewidth=2,
)

fig.update_layout(
    title="Minimum and maximum daily temperatures in Lincoln, NE (2016)",
    height=650,
    width=950,
    font_size=14,
    plot_bgcolor="rgb(245, 245, 245)",
    xaxis_gridcolor="white",
    yaxis_gridcolor="white",
    xaxis_gridwidth=2,
    yaxis_title="Month",
    xaxis_title="Temperature [F]",
    showlegend=False,
)
fig.show()

Interactive output

Static image output

ridgeline plot of the Lincoln Weather dataset using the ridgeplot Python library

Contributing#

Thank you for your interest in contributing to ridgeplot! 🚀

The contribution process for ridgeplot should start with filing a GitHub issue. We define three main categories of issues, and each category has its own GitHub issue template

⭐ Feature requests
🐛 Bug reports
📚 Documentation fixes

After the implementation strategy has been agreed on by a ridgeplot contributor, the next step is to introduce your changes as a pull request (see Pull Request Workflow) against the ridgeplot repository. Once your pull request is merged, your changes will be automatically included in the next ridgeplot release. Every change should be listed in the ridgeplot Changelog.

The following is a set of (slightly opinionated) rules and general guidelines for contributing to ridgeplot. Emphasis on guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.

Development environment#

Here are some guidelines for setting up your development environment. Most of the steps have been abstracted away using the make build automation tool. Feel free to peak inside Makefile at any time to see exactly what is being run, and in which order.

First, you will need to clone this repository. For this, make sure you have a GitHub account, fork ridgeplot to your GitHub account by clicking the Fork button, and clone the main repository locally (e.g. using SSH)

git clone git@github.com:tpvasconcelos/ridgeplot.git
cd ridgeplot

You will also need to add your fork as a remote to push your work to. Replace {username} with your GitHub username.

git remote add fork git@github.com:{username}/ridgeplot.git

The following command will 1) create a new virtual environment (under .venv), 2) install ridgeplot in editable mode (along with all it’s dependencies), and 3) set up and install all pre-commit hooks. Make sure you always work within this virtual environment (i.e., $ source .venv/bin/activate). On top of this, you should also set up your IDE to always point to this python interpreter. In PyCharm, open Preferences -> Project: ridgeplot -> Project Interpreter and point the python interpreter to .venv/bin/python.

make init

The default and recommended base python is python3.7 . You can change this by exporting the BASE_PYTHON environment variable. For instance, if you are having issues installing scientific packages on macOS for python 3.7, you can try python 3.8 instead:

BASE_PYTHON=python3.8 make init

If you need to use jupyter-lab, you can install all extra requirements, as well as set up the environment and jupyter kernel with

make init-jupyter

Pull Request Workflow#

Always confirm that you have properly configured your Git username and email.

git config --global user.name 'Your name'
git config --global user.email 'Your email address'

Each release series has its own branch (i.e. MAJOR.MINOR.x). If submitting a documentation or bug fix contribution, branch off of the latest release series branch.
```
git fetch origin
git checkout -b <YOUR-BRANCH-NAME> origin/x.x.x
```
Otherwise, if submitting a new feature or API change, branch off of the main branch
```
git fetch origin
git checkout -b <YOUR-BRANCH-NAME> origin/main
```
Apply and commit your changes.
Include tests that cover any code changes you make, and make sure the test fails without your patch.
Add an entry to CHANGES.md summarising the changes in this pull request. The entry should follow the same style and format as other entries, i.e.

- Your summary here. (#XXX)

where #XXX should link to the relevant pull request. If you think that the changes in this pull request do not warrant a changelog entry, please state it in your pull request’s description. In such cases, a maintainer should add a skip news label to make CI pass.
Make sure all integration approval steps are passing locally (i.e., tox).

Push your changes to your fork

git push --set-upstream fork <YOUR-BRANCH-NAME>

Create a pull request . Remember to update the pull request’s description with relevant notes on the changes implemented, and to link to relevant issues (e.g., fixes #XXX or closes #XXX).
Wait for all remote CI checks to pass and for a ridgeplot contributor to approve your pull request.

Continuous Integration#

From GitHub’s Continuous Integration and Continuous Delivery (CI/CD) Fundamentals:

Continuous Integration (CI) automatically builds, tests, and integrates code changes within a shared repository.

The first step to Continuous Integration (CI) is having a version control system (VCS) in place. Luckily, you don’t have to worry about that! As you have already noticed, we use Git and host on GitHub.

On top of this, we also run a series of integration approval steps that allow us to ship code changes faster and more reliably. In order to achieve this, we run automated tests and coverage reports, as well as syntax (and type) checkers, code style formatters, and dependency vulnerability scans.

Running it locally#

Our tool of choice to configure and reliably run all integration approval steps is Tox, which allows us to run each step in reproducible isolated virtual environments. To trigger all checks in parallel, simply run

./bin/tox --parallel auto -m static tests

It’s that simple 🙌 !! Note only that this will take a while the first time you run the command, since it will have to create all the required virtual environments (along with their dependencies) for each CI step.

The configuration for Tox can be found in tox.ini.

Tests and coverage reports#

We use pytest as our testing framework, and pytest-cov to track and measure code coverage. You can find all configuration details in tox.ini. To trigger all tests, simply run

./bin/tox --parallel auto -m tests

If you need more control over which tests are running, or which flags are being passed to pytest, you can also invoke pytest directly which will run on your current virtual environment. Configuration details can be found in tox.ini.

Linting#

This project uses pre-commit hooks to check and automatically fix any formatting rules. These checks are triggered before creating any git commit. To manually trigger all linting steps (i.e., all pre-commit hooks), run

pre-commit run --all-files

For more information on which hooks will run, have a look inside the .pre-commit-config.yaml configuration file. If you want to manually trigger individual hooks, you can invoke the pre-commitscript directly. If you need even more control over the tools used you could also invoke them directly (e.g., isort .). Remember however that this is not the recommended approach.

GitHub Actions#

We use GitHub Actions to automatically run all integration approval steps defined with Tox on every push or pull request event. These checks run on all major operating systems and all supported Python versions. Finally, the generated coverage reports are uploaded to Codecov and Codacy. Check .github/workflows/ci.yaml for more details.

Tools and software#

Here is a quick overview of all CI tools and software in use, some of which have already been discussed in the sections above.

Tool	Category	config files	Details
Tox	🔧 Orchestration	tox.ini	We use Tox to reliably run all integration approval steps in reproducible isolated virtual environments.
GitHub Actions	🔧 Orchestration	.github/workflows/ci.yaml	Workflow automation for GitHub. We use it to automatically run all integration approval steps defined with Tox on every push or pull request event.
Git	🕰 VCS	.gitignore	Projects version control system software of choice.
pytest	🧪 Testing	tox.ini	Testing framework for python code.
pytest-cov	📊 Coverage	tox.ini	Coverage plugin for pytest.
Codecov and Codacy	📊 Coverage		Two great services for tracking, monitoring, and alerting on code coverage and code quality.
pre-commit hooks	💅 Linting	.pre-commit-config.yaml	Used to to automatically check and fix any formatting rules on every commit.
mypy	💅 Linting	mypy.ini	A static type checker for Python. We use quite a strict configuration here, which can be tricky at times. Feel free to ask for help from the community by commenting on your issue or pull request.
black	💅 Linting	pyproject.toml	“The uncompromising Python code formatter”. We use `black` to automatically format Python code in a deterministic manner. We use a maximum line length of 100 characters.
flake8	💅 Linting	setup.cfg	Used to check the style and quality of python code.
isort	💅 Linting	setup.cfg	Used to sort python imports.
EditorConfig	💅 Linting	.editorconfig	This repository uses the `.editorconfig` standard configuration file, which aims to ensure consistent style across multiple programming environments.

Project structure#

Community health files#

GitHub’s community health files allow repository maintainers to set contributing guidelines to help collaborators make meaningful, useful contributions to a project. Read more on this official reference .

CODE_OF_CONDUCT.md - A CODE_OF_CONDUCT file defines standards for how to engage in a community. For more information, see “Adding a code of conduct to your project.”
CONTRIBUTING.md - A CONTRIBUTING file communicates how people should contribute to your project. For more information, see “Setting guidelines for repository contributors.”

Configuration files#

For more context on some of the tools referenced below, refer to the sections on Continuous Integration.

.github/workflows/ci.yaml - Workflow definition for our CI GitHub Actions pipeline.
.pre-commit-config.yaml - List of pre-commit hooks.
.editorconfig - EditorConfig standard configuration file.
mypy.ini - Configuration for the mypy static type checker.
pyproject.toml -
build system requirements (probably won’t need to touch these!) and black configurations.
setup.cfg - Here, we specify the package metadata, requirements, as well as configuration details for flake8 and isort.
tox.ini - Configuration for tox, pytest, and coverage.

Release process#

You need push access to the project’s repository to make releases. The following release steps are here for reference only.

Review the ## Unreleased changes section in CHANGES.md by checking for consistency in format and, if necessary, refactoring related entries into relevant subsections (e.g. Features , Docs, Bugfixes, Security, etc). Take a look at previous release notes for guidance and try to keep it consistent.
Submit a pull request with these changes only and use the "Cleanup release notes for X.X.X release" template for the pull request title. ridgeplot uses the SemVer (MAJOR.MINOR.PATCH) versioning standard. You can determine the latest release version by running git describe --tags --abbrev=0 on the main branch. Based on this, you can determine the next release version by incrementing the MAJOR, MINOR, or PATCH. More on this on the next section. For now, just make sure you merge this pull request into the main branch before continuing.

Use the bumpversion utility to bump the current version. This utility will automatically bump the current version, and issue a relevant commit and git tag. E.g.,

# Bump MAJOR version (e.g., 0.4.2 -> 1.0.0)
bumpversion major

# Bump MINOR version (e.g., 0.4.2 -> 0.5.0)
bumpversion minor

# Bump PATCH version (e.g., 0.4.2 -> 0.4.3)
bumpversion patch

You can always perform a dry-run to see what will happen under the hood.

bumpversion --dry-run --verbose [--allow-dirty] [major,minor,patch]

Push your changes along with all tag references:
```
git push && git push --tags
```
At this point a couple of GitHub Actions workflows will be triggered:
1. .github/workflows/ci.yaml: Runs all CI checks with Tox against the new changes pushed to main.
2. .github/workflows/release.yaml: Issues a new GitHub release triggered by the new git tag pushed in the previous step.
3. .github/workflows/publish-pypi.yaml: Builds, packages, and uploads the source and wheel package to PyPI (and test PyPI). This is triggered by the new GitHub release created in the previous step.
Trust but verify!
1. Verify that all three workflows passed successfully: https://github.com/tpvasconcelos/ridgeplot/actions
2. Verify that the new git tag is present in the remote repository: https://github.com/tpvasconcelos/ridgeplot/tags
3. Verify that the new release is present in the remote repository and that the release notes were correctly parsed: https://github.com/tpvasconcelos/ridgeplot/releases
4. Verify that the new package is available in PyPI: https://pypi.org/project/ridgeplot/
5. Verify that the docs were updated and published to https://ridgeplot.readthedocs.io/en/stable/

Code of Conduct#

Please remember to read and follow our Code of Conduct. 🤝

`ridgeplot.datasets.load_probly`	Load a version of the "Perception of Probability Words" (a.k.a., "probly") dataset.
`ridgeplot.datasets.load_lincoln_weather`	Load the "Weather in Lincoln, Nebraska in 2016" dataset.

Dimension values	Description
\(R=12\)	One row per month.
\(T_r=2\) (for all rows \(r \in R\))	Two traces per row (one for the minimum temperatures and one for the maximum temperatures).
\(S_t \in \{29, 30, 31\}\)	One sample per day of the month, where different months have different number of days.

ridgeplot: beautiful ridgeline plots in Python

Installation

Getting started

Basic example

Installation#

Installing from PyPi#

Installing from source#

Dependencies#

Getting started#

Basic example#

Flexible configuration#

More traces#

Final result#

Step-by-step#

API Reference#

Color utilities#

Data loading utilities#

Internals#

Color utilities#

Figure factory#

Kernel density estimation (KDE)#

Testing#

Types#

Other utilities#

Alternatives#

Changelog#

Unreleased changes#

0.1.23#

0.1.22#

Deprecations#

Features#

Documentation#

Internal#

0.1.21#

Features#

Documentation#

Internal#

0.1.17#

0.1.16#

0.1.14#

0.1.13#

0.1.12#

Internal#

Documentation#

0.1.11#

0.1.0#

Contributing#

Development environment#

Pull Request Workflow#

Continuous Integration#

Running it locally#

Tests and coverage reports#

Linting#

GitHub Actions#

Tools and software#

Project structure#

Community health files#

Configuration files#

Release process#

Code of Conduct#