vgplot

A Python API for authoring Mosaic visualizations. Build declarative, interactive plots backed by DuckDB — in notebooks, as JSON specs, or as part of a data pipeline.

vgplot produces Mosaic View objects that can be rendered with mosaic-widget or exported to JSON for use in a browser. Data sources and parameters defined as local variables are automatically discovered at render time.

Installation

pip install vgplot

To render visualizations in the widget, install the widget:

pip install mosaic-widget

Usage

File-based data

Load data from a file using vg.parquet(), vg.csv(), or vg.table(), pass it directly to a mark, then call view.show() or view:

import vgplot as vg

athletes = vg.parquet("data/athletes.parquet")

view = vg.plot(
    vg.dot(athletes, x="weight", y="height", fill="sex", opacity=0.5),
    vg.width(600),
    vg.height(400),
)

view

Interactive selections

Params and selections are first-class objects. Declare them before the view so they can be referenced by multiple marks or interactors:

import vgplot as vg

flights = vg.parquet("data/flights-200k.parquet")
brush = vg.selection.crossfilter()

view = vg.vconcat(
    vg.plot(
        vg.rect_y(flights, x=vg.bin("delay"), y=vg.count(),
                  filter_by=brush, fill="steelblue",
                  inset_left=0.5, inset_right=0.5),
        vg.interval_x(bind=brush),
        vg.x_domain("Fixed"),
        vg.x_label("Arrival Delay (min)"),
        vg.height(200),
    ),
    vg.plot(
        vg.rect_y(flights, x=vg.bin("time"), y=vg.count(),
                  filter_by=brush, fill="steelblue",
                  inset_left=0.5, inset_right=0.5),
        vg.interval_x(bind=brush),
        vg.x_domain("Fixed"),
        vg.x_label("Departure Time (hour)"),
        vg.height(200),
    ),
)

view

Scalar params and input widgets

Use vg.param() for scalar parameters bound to input controls:

import vgplot as vg

walk = vg.parquet("data/random-walk.parquet")
bias = vg.param(0)

view = vg.vconcat(
    vg.slider(label="Bias", bind=bias, min=0, max=1000, step=1),
    vg.plot(
        vg.area_y(walk, x="t", y=vg.sql("v + $bias")),
        vg.width(680),
        vg.height(200),
    ),
)

view

Key concepts

Concept	Python API
File-based data	`vg.parquet(path)`, `vg.csv(path)`, `vg.spatial(path)`, `vg.table(query)`
Mark	`vg.dot(...)`, `vg.bar_y(...)`, `vg.area_y(...)`, `vg.line_y(...)`, …
Aggregation / transform	`vg.count()`, `vg.bin("col")`, `vg.avg("col")`, `vg.sum("col")`, …
SQL expression	`vg.sql("expr")` — use `$param` to interpolate a param, e.g. `vg.sql("v + $bias")`
Plot attributes	`vg.width(n)`, `vg.height(n)`, `vg.x_label("…")`, `vg.color_scheme("…")`, …
Interactor	`vg.interval_x(...)`, `vg.interval_xy(...)`, `vg.region(...)`, `vg.highlight(...)`, …
Layout	`vg.vconcat(...)`, `vg.hconcat(...)`, `vg.vspace(n)`, `vg.hspace(n)`
Crossfilter selection	`vg.selection.crossfilter()`
Intersect / union selection	`vg.selection.intersect()`, `vg.selection.union()`
Scalar param	`vg.param(value)`
Input widgets	`vg.slider(...)`, `vg.menu(...)`, `vg.select(...)`, `vg.checkbox(...)`
Named data reference	`vg.source("table_name")`
Render	`view.show()` or `view` as last cell expression in notebooks

Option names match the vgplot API reference, but in snake_case. For example, xDomain → x_domain, colorScheme → color_scheme, filterBy → filter_by.

Any mark or directive not listed above is also accessible by its snake_case name — vg.regression_y(...) and vg.x_tick_rotate(45) work without explicit exports.

Exporting specs

view.to_dict() returns a plain Python dictionary. view.to_json() returns a JSON string:

from pprint import pprint

pprint(view.to_dict())
print(view.to_json(indent=2))

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

vgplot-0.29.0.tar.gz (23.8 kB view details)

Uploaded Jul 14, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

vgplot-0.29.0-py3-none-any.whl (23.1 kB view details)

Uploaded Jul 14, 2026 Python 3

File details

Details for the file vgplot-0.29.0.tar.gz.

File metadata

Download URL: vgplot-0.29.0.tar.gz
Upload date: Jul 14, 2026
Size: 23.8 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for vgplot-0.29.0.tar.gz
Algorithm	Hash digest
SHA256	`2f457798caa18d2afa3f076b2defb6f9313b37040060e27a7d71c635567503c4`
MD5	`75160f1cfc9fa85860bfc4f2133f85db`
BLAKE2b-256	`c0d0e9748f07f9c3173e6f3ac9700f1f8f28c34f63c2c2591d39c3d57c0a1f6b`

See more details on using hashes here.

Provenance

The following attestation bundles were made for vgplot-0.29.0.tar.gz:

Publisher: release.yml on uwdata/mosaic

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: vgplot-0.29.0.tar.gz
- Subject digest: 2f457798caa18d2afa3f076b2defb6f9313b37040060e27a7d71c635567503c4
- Sigstore transparency entry: 2168753588
- Sigstore integration time: Jul 14, 2026
Source repository:
- Permalink: uwdata/mosaic@aca7cb3f2df1bd99828bb7e2d7f1103292c22ddf
- Branch / Tag: refs/heads/main
- Owner: https://github.com/uwdata
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@aca7cb3f2df1bd99828bb7e2d7f1103292c22ddf
- Trigger Event: workflow_dispatch

File details

Details for the file vgplot-0.29.0-py3-none-any.whl.

File metadata

Download URL: vgplot-0.29.0-py3-none-any.whl
Upload date: Jul 14, 2026
Size: 23.1 kB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for vgplot-0.29.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`5571880aa017201a9ad8389505249a3496748bb87a84646ea0c8586b6d7233fa`
MD5	`180c5e3fbb77cdd56cf250b98b5f86a3`
BLAKE2b-256	`cbe53757e098ecb4afe7796c0aa97da31fc94bc65492828a3fdbafadfdb237d4`

See more details on using hashes here.

Provenance

The following attestation bundles were made for vgplot-0.29.0-py3-none-any.whl:

Publisher: release.yml on uwdata/mosaic

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: vgplot-0.29.0-py3-none-any.whl
- Subject digest: 5571880aa017201a9ad8389505249a3496748bb87a84646ea0c8586b6d7233fa
- Sigstore transparency entry: 2168753710
- Sigstore integration time: Jul 14, 2026
Source repository:
- Permalink: uwdata/mosaic@aca7cb3f2df1bd99828bb7e2d7f1103292c22ddf
- Branch / Tag: refs/heads/main
- Owner: https://github.com/uwdata
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@aca7cb3f2df1bd99828bb7e2d7f1103292c22ddf
- Trigger Event: workflow_dispatch

Release history Release notifications | RSS feed

0.30.0

Aug 9, 2026

0.29.1

Jul 16, 2026

This release

0.29.0

Jul 14, 2026

0.1.0

Apr 7, 2026

vgplot 0.29.0

vgplot

Installation

Usage

File-based data

Interactive selections

Scalar params and input widgets

Key concepts

Exporting specs

Project links

Key dates

2 maintainers

GitHub Statistics

Requires

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Release history Release notifications | RSS feed