README.md

Mosaic Python

Python bindings for Mosaic



Made by Ploomber with ❤️

Deploy Streamlit and Dash apps on Ploomber.io for free.

1. Dash Mosaic (component for Dash)
2. Streamlit Mosaic (component for Streamlit)
3. Mosaic Spec Generator free tool to generate Mosaic plots

Dash Mosaic

dash-mosaic.mp4

Installation

pip install dash-mosaic-ploomber

Why?

dash-mosaic is already taken on PyPI.

Usage

from dash import Dash, html
import dash_mosaic

app = Dash(__name__)

# your mosaic spec as a python dictionary
spec = {...}

app.layout = html.Div(
    [
        dash_mosaic.DashMosaic(
            id="my-plot",
            spec=spec,
            # if None, it'll use DuckDB WASM. If a string, it'll use the
            # restConnector (if the url begins with "http") or the
            # socketConnector (if it begins with "ws")
            # **IMPORTANT** if you want to load a local file, you cannot pass
            # uri=None. See the latest section in the README.md
            uri=None,
        )
    ]
)

if __name__ == "__main__":
    app.run_server(debug=True)

Click to expand full code example

from dash import Dash, html
import dash_mosaic

app = Dash(__name__)

spec = {
    "meta": {
        "title": "Interactive Penguin Bill Measurements",
        "description": "Scatterplot of bill length vs depth with interactive selection",
    },
    "data": {
        "penguins": {
            "type": "parquet",
            "file": "https://raw.githubusercontent.com/uwdata/mosaic/refs/heads/main/data/penguins.parquet",
        }
    },
    "params": {
        "brush": {"select": "crossfilter"},
        "domain": ["Adelie", "Chinstrap", "Gentoo"],
        "colors": ["#1f77b4", "#ff7f0e", "#2ca02c"],
    },
    "vconcat": [
        {
            "name": "scatterplot",
            "width": 600,
            "height": 400,
            "xLabel": "Bill Length (mm) →",
            "yLabel": "↑ Bill Depth (mm)",
            "colorDomain": "$domain",
            "colorRange": "$colors",
            "plot": [
                {
                    "fill": "species",
                    "x": "bill_length",
                    "y": "bill_depth",
                    "data": {"from": "penguins", "filterBy": "$brush"},
                    "mark": "dot",
                },
                {"as": "$brush", "select": "intervalXY"},
            ],
        },
        {
            "name": "species_count",
            "width": 600,
            "height": 200,
            "xLabel": "Penguin Species →",
            "yLabel": "↑ Count",
            "colorDomain": "$domain",
            "colorRange": "$colors",
            "plot": [
                {
                    "fill": "species",
                    "y": {"count": None},
                    "x": "species",
                    "data": {"from": "penguins", "filterBy": "$brush"},
                    "mark": "barY",
                }
            ],
        },
    ],
}


app.layout = html.Div(
    [
        dash_mosaic.DashMosaic(
            id="penguin-plot",
            spec=spec,
            # **IMPORTANT** if you want to load a local file, you cannot pass
            # uri=None. See the latest section in the README.md
            uri=None,
        )
    ]
)

if __name__ == "__main__":
    app.run_server(debug=True)

Demo

cd dash-mosaic/demo
pip install -r requirements.txt
python app.py

Open: http://localhost:8050

Streamlit Mosaic

streamlit-mosaic.mp4

Installation

pip install streamlit-mosaic

Usage

import streamlit as st
from streamlit_mosaic import mosaic

# your mosaic spec as a dictionary
spec = {...}

mosaic(spec=spec,
       height=600,
        # if None, it'll use DuckDB WASM. If a string, it'll use the
        # restConnector (if the url begins with "http") or the
        # socketConnector (if it begins with "ws")
        # **IMPORTANT** if you want to load a local file, you cannot pass
        # uri=None. See the latest section in the README.md
       uri=None)

Click to expand full code example

import streamlit as st
from streamlit_mosaic import mosaic

spec = {
    "meta": {
        "title": "Interactive Penguin Bill Measurements",
        "description": "Scatterplot of bill length vs depth with interactive selection",
    },
    "data": {
        "penguins": {
            "type": "parquet",
            "file": "https://raw.githubusercontent.com/uwdata/mosaic/refs/heads/main/data/penguins.parquet",
        }
    },
    "params": {
        "brush": {"select": "crossfilter"},
        "domain": ["Adelie", "Chinstrap", "Gentoo"],
        "colors": ["#1f77b4", "#ff7f0e", "#2ca02c"],
    },
    "vconcat": [
        {
            "name": "scatterplot",
            "width": 600,
            "height": 400,
            "xLabel": "Bill Length (mm) →",
            "yLabel": "↑ Bill Depth (mm)",
            "colorDomain": "$domain",
            "colorRange": "$colors",
            "plot": [
                {
                    "fill": "species",
                    "x": "bill_length",
                    "y": "bill_depth",
                    "data": {"from": "penguins", "filterBy": "$brush"},
                    "mark": "dot",
                },
                {"as": "$brush", "select": "intervalXY"},
            ],
        },
        {
            "name": "species_count",
            "width": 600,
            "height": 200,
            "xLabel": "Penguin Species →",
            "yLabel": "↑ Count",
            "colorDomain": "$domain",
            "colorRange": "$colors",
            "plot": [
                {
                    "fill": "species",
                    "y": {"count": None},
                    "x": "species",
                    "data": {"from": "penguins", "filterBy": "$brush"},
                    "mark": "barY",
                }
            ],
        },
    ],
}

# **IMPORTANT** if you want to load a local file, you cannot pass
# uri=None. See the latest section in the README.md
mosaic(spec=spec, height=600, uri=None)

Demo

cd streamlit-mosaic/demo
pip install -r requirements.txt
streamlit run app.py

Open: http://localhost:8501

Loading local files

If you want to visualize local files with dash-mosaic or streamlit-mosaic, passing uri=None won't work. Instead, you can pass: http://localhost:3000 and run the duckdb-server:

pip install duckdb-server
duckdb-server

Read more in Mosaic's documentation.