bivario

Python library for plotting bivariate choropleth maps in Matplotlib, Folium and Lonboard.

Installation

With pip:

pip install bivario

With uv:

uv add bivario

Usage

Example of a Folium map in light and dark modes.

Simple Folium map:

from bivario import explore_bivariate_data
from bivario.example_data import nyc_bike_trips

explore_bivariate_data(
    nyc_bike_trips(), "morning_starts", "morning_ends"
)

Simple Lonboard map:

from bivario import viz_bivariate_data
from bivario.example_data import nyc_bike_trips

viz_bivariate_data(
    nyc_bike_trips(), "morning_starts", "morning_ends"
)

In dark mode:

from bivario import explore_bivariate_data
from bivario.example_data import nyc_bike_trips

explore_bivariate_data(
    nyc_bike_trips(),
    column_a="morning_starts",
    column_b="morning_ends",
    dark_mode=True, # default is False
)

Use other palette:

from bivario import explore_bivariate_data
from bivario.example_data import nyc_bike_trips

explore_bivariate_data(
    nyc_bike_trips(),
    column_a="morning_starts",
    column_b="morning_ends",
    cmap="bubblegum"
)

Set numerical mode (disable bucketing):

[!NOTE] By default, map is created using Mapclassify library with NaturalBreaks method to split data into 5 categories. Method and number of buckets can be changed or disabled completely.

from bivario import explore_bivariate_data
from bivario.example_data import nyc_bike_trips

explore_bivariate_data(
    nyc_bike_trips(),
    column_a="morning_starts",
    column_b="morning_ends",
    dark_mode=True,
    cmap="late_sunset",
    scheme=False, # or set to None
    legend_size_px=300,
)

Example of a Folium map in a numerical mode.

Bivariate colourmaps

Palettes in bivario are created by blending 2 or 4 colours in a 2D space using OKLab colour space. The operations on input and output are done in RGB, an internally are transformed into OKLab values using colour-science library.

bivario has 4 modes of Bivariate colourmaps:

AccentsBivariateColourmap - defined by two accent colours and a light and a dark colour.

CornersBivariateColourmap - defined by 4 corner colours (accent a/b, low value and high value)

MplCmapBivariateColourmap - defined by 2 Matplotlib colourmaps along axis X and Y

NamedBivariateColourmap - can load predefined palette from string name

Available palettes

You can load these palettes by passing a string name to the cmap attribute, or load a NamedBivariateColourmap object:

cmap = NamedBivariateColourmap("coral_ocean")

# You can call it similar to Matplotlib Colormap object
rgb_values = cmap(values_a=[0, 1], values_b=[0, 1])