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: Python implementation of Mosaic Spec (coming soon!)

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.