python-plotto 0.5.2__tar.gz → 0.7.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (26) hide show
  1. {python_plotto-0.5.2/python_plotto.egg-info → python_plotto-0.7.0}/PKG-INFO +6 -1
  2. {python_plotto-0.5.2 → python_plotto-0.7.0}/README.md +2 -0
  3. {python_plotto-0.5.2 → python_plotto-0.7.0}/plotto/__init__.py +1 -1
  4. python_plotto-0.7.0/plotto/_assets/README.md +233 -0
  5. python_plotto-0.7.0/plotto/_assets/SPEC.md +331 -0
  6. {python_plotto-0.5.2 → python_plotto-0.7.0}/plotto/_assets/grammar.json +20 -11
  7. python_plotto-0.7.0/plotto/_assets/plotto.js +36 -0
  8. python_plotto-0.7.0/plotto/_assets/widget.js +36 -0
  9. python_plotto-0.7.0/plotto/data.py +88 -0
  10. {python_plotto-0.5.2 → python_plotto-0.7.0}/plotto/plot.py +109 -1
  11. python_plotto-0.7.0/plotto/widget.py +19 -0
  12. {python_plotto-0.5.2 → python_plotto-0.7.0}/pyproject.toml +2 -1
  13. {python_plotto-0.5.2 → python_plotto-0.7.0/python_plotto.egg-info}/PKG-INFO +6 -1
  14. {python_plotto-0.5.2 → python_plotto-0.7.0}/python_plotto.egg-info/SOURCES.txt +4 -0
  15. {python_plotto-0.5.2 → python_plotto-0.7.0}/python_plotto.egg-info/requires.txt +4 -0
  16. {python_plotto-0.5.2 → python_plotto-0.7.0}/tests/test_builder.py +56 -0
  17. {python_plotto-0.5.2 → python_plotto-0.7.0}/tests/test_output.py +27 -0
  18. python_plotto-0.5.2/plotto/_assets/plotto.js +0 -35
  19. python_plotto-0.5.2/plotto/data.py +0 -49
  20. {python_plotto-0.5.2 → python_plotto-0.7.0}/LICENSE +0 -0
  21. {python_plotto-0.5.2 → python_plotto-0.7.0}/plotto/_assets/theme.json +0 -0
  22. {python_plotto-0.5.2 → python_plotto-0.7.0}/plotto/assets.py +0 -0
  23. {python_plotto-0.5.2 → python_plotto-0.7.0}/plotto/output.py +0 -0
  24. {python_plotto-0.5.2 → python_plotto-0.7.0}/python_plotto.egg-info/dependency_links.txt +0 -0
  25. {python_plotto-0.5.2 → python_plotto-0.7.0}/python_plotto.egg-info/top_level.txt +0 -0
  26. {python_plotto-0.5.2 → python_plotto-0.7.0}/setup.cfg +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: python-plotto
3
- Version: 0.5.2
3
+ Version: 0.7.0
4
4
  Summary: Grammar-of-graphics plots for notebooks, web pages and slides with one renderer.
5
5
  License-Expression: MIT
6
6
  Project-URL: Homepage, https://theoradusz.github.io/plotto/
@@ -16,12 +16,15 @@ Description-Content-Type: text/markdown
16
16
  License-File: LICENSE
17
17
  Requires-Dist: pandas>=2
18
18
  Requires-Dist: numpy
19
+ Provides-Extra: marimo
20
+ Requires-Dist: anywidget; extra == "marimo"
19
21
  Provides-Extra: test
20
22
  Requires-Dist: pytest; extra == "test"
21
23
  Requires-Dist: ruff; extra == "test"
22
24
  Requires-Dist: black; extra == "test"
23
25
  Requires-Dist: nbconvert; extra == "test"
24
26
  Requires-Dist: ipykernel; extra == "test"
27
+ Requires-Dist: anywidget; extra == "test"
25
28
  Dynamic: license-file
26
29
 
27
30
  # python-plotto
@@ -44,3 +47,5 @@ p.save("fig.png") # needs Node.js 20 or later
44
47
  - Gallery, grammar tutorial and reference: https://theoradusz.github.io/plotto/
45
48
  - Source and full documentation: https://github.com/theoradusz/plotto
46
49
  - The JavaScript package for web pages and React: `npm install plotto`
50
+ - marimo: `pip install "python-plotto[marimo]"` draws `p` as a live widget.
51
+ - The installed package holds the full `README.md` and `SPEC.md` of its version in `plotto/_assets/`.
@@ -18,3 +18,5 @@ p.save("fig.png") # needs Node.js 20 or later
18
18
  - Gallery, grammar tutorial and reference: https://theoradusz.github.io/plotto/
19
19
  - Source and full documentation: https://github.com/theoradusz/plotto
20
20
  - The JavaScript package for web pages and React: `npm install plotto`
21
+ - marimo: `pip install "python-plotto[marimo]"` draws `p` as a live widget.
22
+ - The installed package holds the full `README.md` and `SPEC.md` of its version in `plotto/_assets/`.
@@ -3,7 +3,7 @@
3
3
  https://github.com/theoradusz/plotto
4
4
  """
5
5
 
6
- __version__ = "0.5.2"
6
+ __version__ = "0.7.0"
7
7
 
8
8
  from .plot import Plot, plot # noqa: E402
9
9
 
@@ -0,0 +1,233 @@
1
+ # plotto
2
+
3
+ plotto makes grammar-of-graphics plots for notebooks, web pages, slides and reports. You write a plot in Python or in JavaScript with the same methods. One renderer draws it, so the notebook view, the interactive view and the saved file look the same.
4
+
5
+ **Gallery:** [gallery link](https://theoradusz.github.io/plotto/), with pages for the basics, the plot types, the colors, the scales and legends, a step-by-step grammar tutorial and the API reference. `SPEC.md` is the contract: the spec format, the rules, the layers, the scales and the behavior.
6
+
7
+ <p>
8
+ <img src="docs/img/lines.png" width="49%"> <img src="docs/img/stacked_bars.png" width="49%">
9
+ <img src="docs/img/histogram.png" width="49%"> <img src="docs/img/diverging.png" width="49%">
10
+ <img src="docs/img/facets.png" width="49%"> <img src="docs/img/smooth_1.png" width="49%">
11
+ </p>
12
+
13
+ ```python
14
+ from plotto import plot
15
+
16
+ p = (
17
+ plot(df, x="time", y="value", color="sensor")
18
+ .line()
19
+ .hline(y=0.75, color="red", dash="dashed")
20
+ .facet("indicator", free="y")
21
+ .y(limits=[0, None])
22
+ .labels(title="Water quality", x=None)
23
+ )
24
+ p # drawn at the cell width, with copy and download buttons
25
+ p.interactive() # the same plot with zoom, pan, hover and legend toggle
26
+ p.theme("wota") # another style
27
+ p.color(palette="aizome") # another palette
28
+ p.save("fig.png") # PNG; .svg for vector files
29
+ p.theme("wota", format="slide").save("slide.png") # 691 × 403 px: 7.2 × 4.2 in on a slide
30
+ ```
31
+
32
+ ```js
33
+ import { plot, draw } from "plotto";
34
+ draw(plot(rows, { x: "time", y: "value", color: "sensor" }).line().facet("indicator", { free: "y" }), el, { interactive: true });
35
+ ```
36
+
37
+ ## How it works
38
+
39
+ 1. The builder writes a JSON spec: the data columns, the layers, the scales, the facets, the labels and the theme.
40
+ 2. `src/figure.js` computes the statistics, the scales and the layout. Then it draws the title, strips and legend, and Observable Plot draws each panel.
41
+ 3. In the browser, a zoom, a legend click or a resize draws the figure again with the same code. The look does not change.
42
+ 4. For files, Python sends the spec to one Node process (`src/render.mjs`). The process draws the SVG with jsdom and the PNG with resvg.
43
+
44
+ | Part | Files |
45
+ |---|---|
46
+ | Grammar and themes | `grammar.json` (layers, channels, options), `theme.json` (styles, formats) |
47
+ | JS builder and renderer | `src/`. Each file has one job, stated in its header comment. |
48
+ | Python builder and outputs | `python/plotto/` |
49
+ | Examples | `examples/` |
50
+ | Tests | `tests/`, `python/tests/` |
51
+
52
+ ## Install
53
+
54
+ | Where | Install | Import |
55
+ |---|---|---|
56
+ | Python, notebooks | `pip install python-plotto` | `from plotto import plot` |
57
+ | Web pages, React | `npm install plotto` | `import { plot, draw } from "plotto"`; `import { Plot } from "plotto/react"` |
58
+
59
+ - Python 3.12 or later. A notebook plot needs no Node.
60
+ - `save()` (PNG and SVG files) and the static copy in notebook outputs need Node.js 20 or later. On the first use, plotto downloads its renderer with `npx` (the npm package of the same version) and keeps it in the npm cache.
61
+ - The `wota` style uses the M PLUS 1p font. Install the font to use that style.
62
+
63
+ ### Development
64
+
65
+ 1. Clone the repo and run `npm install`.
66
+ 2. Run `pip install -e "python[test]"` in a virtual environment. In a checkout, the package uses `grammar.json`, `theme.json` and `src/` of the repo directly.
67
+
68
+ ## Use
69
+
70
+ ### Data
71
+
72
+ - Use long format: one row per observation, one column per variable.
73
+ - Python takes a pandas DataFrame (also a GeoDataFrame) or a list of dicts. JavaScript takes an array of row objects. Both take a GeoJSON FeatureCollection.
74
+ - A time-zone-aware datetime column shows its local clock time.
75
+ - To set the order of categories, use a pandas categorical column or `x(limits=[...])`.
76
+
77
+ ### Axes and colors
78
+
79
+ | Need | Call |
80
+ |---|---|
81
+ | Axis range | `x(limits=[0, 10])`; `y(limits=[0, None])` keeps the data bound on the `None` side |
82
+ | Category order | `x(limits=["low", "mid", "high"])` |
83
+ | Log axis, time labels | `y(type="log")`; `x(format="%a %H:%M")` |
84
+ | Set ticks and their text | `x(type="log", breaks=[1, 1.5, 2, 3, 5, 10])`; `y(breaks=[0, 50], labels=["none", "50"])` |
85
+ | Colors side by side in a category | `point(position="dodge")`, `segment(..., position="dodge")`: on a category x or y |
86
+ | Name lines at their ends | `line(direct=True)` with `theme(legend="none")` |
87
+ | Areas from GeoJSON or a GeoDataFrame | `plot(geojson).polygon(fill="households", tooltip="name")`; outlines only: `polygon()` |
88
+ | Classes with a stepped legend | `fill(breaks=[0, 50, 1000, 10000])`; class names: `labels=[...]`; the same for `color()` |
89
+ | Maps | `coord("geo")`: x = longitude, y = latitude, equal distance per px, degree labels; `coord("geo", scalebar=True, north=True)` |
90
+ | Distant areas in the same figure | `inset(x=[122.9, 131.4], y=[24.0, 28.6], at=[0.02, 0.6, 0.3, 0.98])` |
91
+ | Labels that do not overlap | `text(label="name", repel=True)` |
92
+ | A grid under the map (1 km intensity mesh) | `raster(data=grid, x="lon", y="lat", fill="intensity")` with `fill(breaks=...)` |
93
+ | Category colors | `color(palette="sakura")`, or `color(values={"a": "red", "b": "#123456"})` |
94
+ | Number colors | `color(scheme="ai")`; diverging: `color(scheme="aiaka", mid=0)` |
95
+
96
+ Palettes: `pastel` (the default style), `sakura`, `aizome`, `momiji` (inspired by traditional Japanese colors), `wota`, `tableau`. Schemes: `ai`, `sakura`, `matcha`, `yuhi`, `sumi`, `aiaka` (diverging), and every d3 scheme (`viridis`, `magma`, …).
97
+
98
+ ### Info table
99
+
100
+ Put facts about the data or the experiment in a table instead of a long subtitle:
101
+
102
+ ```python
103
+ p.info({"data point": 15, "location": "hayama", "experiment": "cleaning with chlorine"})
104
+ p.info(entries, position="bottom") # "right" (default) or "bottom"
105
+ ```
106
+
107
+ The table is a card on the right of the plot, or below it. A plot narrower than 560 px puts it below. `SPEC.md` §7 has the rules.
108
+
109
+ ### Notebook
110
+
111
+ - A plot shows at the width of the cell. The text keeps its size, and the height follows the aspect ratio of the format.
112
+ - `.interactive()` adds zoom, pan, hover and the legend toggle.
113
+ - The hover follows the plot type:
114
+ - lines and areas: every series at the nearest x, or only the series under the pointer when there are more than 6;
115
+ - bars: the stack and its total;
116
+ - box: the quartiles;
117
+ - tile: the cell value;
118
+ - points: the nearest point.
119
+ - A click pins the hover label; the next click (or Esc) releases it. A drag starts after 5 px of movement; a double-click resets the view.
120
+ - A legend click hides or shows a series. Two quick clicks on the same entry (within 300 ms) show only that series.
121
+ - The toolbar shows at the top right when the pointer is on the plot:
122
+ - copy as PNG;
123
+ - copy for a slide: the current view in the slide format, which pastes into Google Slides at 7.2 × 4.2 in, sharp;
124
+ - download as PNG or SVG;
125
+ - in interactive mode, also zoom box, pan, zoom in, zoom out and reset.
126
+ - The output loads d3 and Observable Plot from `cdn.jsdelivr.net`. GitHub, nbviewer, or a page without network access shows the static SVG in the output.
127
+ - Each output holds the data of the plot and the plotto script (about 60 kB). A plot with 20 000 points adds about 2 MB to the notebook.
128
+ - In marimo, install `pip install "python-plotto[marimo]"` (anywidget). Then `p` and `p.interactive()` show as a live widget, with the same toolbar and interaction. A widget needs no Node, so the cell runs faster. Without anywidget, marimo shows the static SVG.
129
+
130
+ ### Web pages and React
131
+
132
+ - `draw(spec, element, { interactive })` draws into an element at its width, and draws again when the width changes. It returns `{ destroy }`.
133
+ - In React, use `import { Plot } from "plotto/react"`, then `<Plot spec={plot(rows, {...}).line()} interactive />`.
134
+
135
+ ### Slides and reports
136
+
137
+ | Target | Use |
138
+ |---|---|
139
+ | Google Slides | The "Copy for a slide" button, then paste under the slide title: 7.2 × 4.2 in, with room for comments on the right. Or a PNG: `p.save("fig.png")`. Google Slides does not accept SVG. |
140
+ | PowerPoint, Keynote, documents | SVG: `p.save("fig.svg")`. The SVG uses the installed fonts. |
141
+ | A slide layout | `p.theme(style, format="slide")`: 691 × 403 px, the size on the slide |
142
+ | A report column | `p.theme(style, format="report")`: 640 × 400 px |
143
+ | Square panels | `p.theme(aspect=1)`, for observed-against-predicted plots. Give x and y the same `limits`. |
144
+ | A given size | `p.save("fig.png", width=1600)` lays the plot out again at 1600 px. |
145
+ | From the notebook | Use the copy button, which copies the current view as PNG. |
146
+
147
+ ## Examples
148
+
149
+ | File | Content |
150
+ |---|---|
151
+ | `examples/gallery.py` | 28 examples on 4 pages (basics, plot types, colors, scales and legends), which use every feature. The data is made-up, except for two files of real measurements. |
152
+ | `examples/grammar.py` | The grammar tutorial: 14 steps, each with its text, code and result. |
153
+ | `examples/reference.py` | The API reference. The layer methods come from `grammar.json`. |
154
+ | `examples/build_site.py` | Builds the site in `docs/`: one HTML page per gallery page, `grammar.html` and `reference.html` (each with the plotto script inline), and `img/` (the PNG and SVG of each gallery plot). GitHub Pages serves `docs/`. |
155
+ | `examples/showcase.ipynb` | The examples in a notebook. |
156
+ | `examples/web/` | Examples in JavaScript. Run `python3 -m http.server` in the repo, then open `http://localhost:8000/examples/web/`. |
157
+
158
+ To publish the gallery:
159
+
160
+ 1. Run `python examples/build_site.py`.
161
+ 2. Commit `docs/`.
162
+ 3. On GitHub, set Settings → Pages → Source to "Deploy from a branch", with branch `main` and folder `/docs`.
163
+ | `examples/data/` | The datasets. `examples/make_datasets.py` makes the made-up ones. |
164
+
165
+ ## Tests
166
+
167
+ | Command | What it verifies |
168
+ |---|---|
169
+ | `npm test` | Each layer and style (SVG snapshots in `tests/snapshots/`), stacks, bins, smooth fits, domains, facets, legends, reflow, errors |
170
+ | `npm run browser-test` | In headless Chrome: the browser SVG equals the Node SVG. Zoom, Home, the toolbar, hover, legend clicks and their timing, reflow and the static mode work. The marimo widget draws in a shadow root, with its styles and legend clicks. |
171
+ | `pytest python/tests` | The Python and JS builders make the same spec; data conversion; SVG and PNG files; notebook output; the marimo widget; the files in the wheel. Run `npm run build:python` first. |
172
+ | `ruff check . && black --check .` | Python lint |
173
+
174
+ If a change of the look is intentional, run `UPDATE_SNAPSHOTS=1 npm test` and review the SVG diff.
175
+
176
+ ## Maintenance
177
+
178
+ To add a layer type:
179
+
180
+ 1. Add the layer to `grammar.json`: channels, options and required channels.
181
+ 2. Add one entry to `LAYERS` in `src/layers.js`.
182
+ 3. For a statistic, add the computation to `src/stats.js` and a case to `makeView` and `hoverOf` in `src/views.js`.
183
+ 4. Add the method to `src/builder.js` and `python/plotto/plot.py`.
184
+ 5. Add a case to `tests/render.test.js` and to `tests/fixtures/parity.json`.
185
+ 6. Add a row to the layer table in `SPEC.md`.
186
+
187
+ To change a style, a format, a palette or a scheme, edit `theme.json`. A scheme is a list of colors from light to dark; plotto interpolates it in Lab space. To use a new font, add it to `scripts/font_metrics.py`, run the script, and set `font` and `metrics` of the style.
188
+
189
+ ## Release
190
+
191
+ A tag `vX.Y.Z` publishes `python-plotto` to PyPI and `plotto` to npm (`.github/workflows/release.yml`).
192
+
193
+ One-time setup:
194
+
195
+ 1. On pypi.org, create an account. Under "Publishing", add a pending trusted publisher: project `python-plotto`, owner `theoradusz`, repository `plotto`, workflow `release.yml`, environment `pypi`.
196
+ 2. On GitHub, create the environment `pypi` (Settings → Environments).
197
+ 3. On npmjs.com, create an account (with two-factor authentication). Publish the first version from your computer, in the repo:
198
+
199
+ ```
200
+ npm login
201
+ npm test
202
+ npm publish --access public
203
+ ```
204
+
205
+ 4. On npmjs.com, open the package `plotto` → Settings → Trusted publishing → GitHub Actions: repository `theoradusz/plotto`, workflow `release.yml`. Later versions then publish from GitHub with no token. The workflow skips a version that is already on npm.
206
+
207
+ Each release (`main` takes changes only through a reviewed pull request):
208
+
209
+ ```bash
210
+ # 1. Merge your changes into main through a pull request,
211
+ # with a line for each change under "## Unreleased" in CHANGELOG.md
212
+
213
+ # 2. Prepare the release
214
+ git switch main && git pull && source .venv/bin/activate
215
+ scripts/release.sh 0.3.1
216
+ # → the pull request page opens: create it, get it approved and merged
217
+
218
+ # 3. Publish
219
+ scripts/release.sh tag # answer y
220
+
221
+ # 4. Check
222
+ npm view plotto version && pip index versions python-plotto
223
+ ```
224
+
225
+ - `scripts/release.sh X.Y.Z` checks that `main` is current, that the version is new and that `CHANGELOG.md` has changes under "Unreleased". It runs every test and lint. Then, on the branch `release/vX.Y.Z`, it sets the version in `package.json`, `package-lock.json` and `python/plotto/__init__.py`, moves the "Unreleased" changes to a dated `X.Y.Z` section, builds `docs/`, commits and pushes.
226
+ - `scripts/release.sh tag` tags the merged `main` as `vX.Y.Z`, asks before it pushes the tag, and deletes the release branch.
227
+ - The pushed tag runs `.github/workflows/release.yml`, which publishes to PyPI and npm. Follow it in the Actions tab.
228
+
229
+ To upgrade Observable Plot or d3:
230
+
231
+ 1. Change the exact version in `package.json`.
232
+ 2. Run `npm install`.
233
+ 3. Run the tests. A snapshot difference shows a change of the look.
@@ -0,0 +1,331 @@
1
+ # plotto spec
2
+
3
+ This document is the contract of plotto: the spec format, the builder rules, the layers, the scales, the facets, the themes, the display, the interaction and the outputs. The README tells how to install and use the package.
4
+
5
+ ## 1. Model
6
+
7
+ A plot is a JSON spec.
8
+ - The Python builder (`python/plotto/plot.py`) and the JS builder (`src/builder.js`) write the same spec for the same calls.
9
+ - One JS renderer (`src/figure.js`) draws the spec as SVG, with Observable Plot for the panels.
10
+ - The renderer runs in the browser and in Node (jsdom), so every output has the same look.
11
+
12
+ ```
13
+ builder → spec → normalize (spec.js) → views (views.js, stats.js) → scales and layout → figure → panels (Observable Plot) → SVG
14
+ ```
15
+
16
+ `grammar.json` lists the layers, channels, options and scale keys. Both builders and `src/spec.js` read it. `theme.json` holds the styles and the formats.
17
+
18
+ ## 2. Spec format (version 1)
19
+
20
+ ```json
21
+ {
22
+ "version": 1,
23
+ "data": [{ "columns": { "time": { "type": "time", "values": [1792454400000] }, "W": { "type": "number", "values": [0.25] } } }],
24
+ "mapping": { "x": "time", "y": "W", "color": "sensor" },
25
+ "layers": [{ "type": "line", "mapping": {}, "set": { "size": 1 } }, { "type": "hline", "mapping": {}, "set": { "y": 0 }, "data": 1 }],
26
+ "facet": { "wrap": "sensor", "free": "y", "ncol": null },
27
+ "scales": { "x": { "type": "time" }, "color": { "values": { "sensor A": "blue" } } },
28
+ "labels": { "title": "Water quality", "x": null, "y": "W (a.u.)" },
29
+ "info": { "entries": [["data point", 15], ["location", "hayama"]], "position": "right" },
30
+ "theme": { "style": "pastel", "format": "screen", "legend": "right" }
31
+ }
32
+ ```
33
+
34
+ | Key | Content |
35
+ |---|---|
36
+ | `data` | A list of tables. Table 0 is the plot data. A layer with its own data has `"data": <index>`. |
37
+ | `columns` | `{name: {type, values, levels?}}`, with values in row order. `null` is a missing value. |
38
+ | `mapping` | Plot channels → column names. They apply to every layer that accepts the channel (rule 4). |
39
+ | `layers[].mapping` | Layer channels → column names |
40
+ | `layers[].set` | Constants: channel values and options |
41
+ | `facet` | `{wrap, free, ncol}`, `{rows, cols, free}` or `null` |
42
+ | `scales` | `x`, `y`: `type`, `limits`, `format`, `breaks`, `labels`. `color`, `fill`: `values`, `palette`, `scheme`, `limits`, `mid`, `clamp`, `breaks`, `labels`. |
43
+ | `labels` | `title`, `subtitle`, `caption`, `x`, `y`, `color`, `fill`. `null` removes a title. A missing key uses the first mapped column name. |
44
+ | `info` | Optional. `entries`: `[key, value]` pairs in order; a value is a string, a number, a boolean or `null`. `position`: `right` or `bottom`; without it, `right`, or the place with the most room in a fixed size. |
45
+ | `coord` | Optional. `{type: "geo", scalebar?, north?}`: map coordinates, with the corners of the scale bar and the north arrow (§5) |
46
+ | `insets` | Optional. `[{x: [low, high], y: [low, high], at: [left, bottom, right, top]}]`: inset panels (§6) |
47
+ | `theme` | `style`, `format`, and the overrides `width`, `height`, `size`, `legend` |
48
+
49
+ ### Column types
50
+
51
+ | Type | Values | From Python | From JS |
52
+ |---|---|---|---|
53
+ | `number` | numbers | numeric dtypes | `number` |
54
+ | `time` | wall-clock epoch ms | `datetime64`. A time-zone-aware column keeps its local clock time. | `Date` (local clock time) |
55
+ | `string` | strings | object, string, bool (`"true"`, `"false"`), categorical (with `levels`) | any other value |
56
+ | `geometry` | GeoJSON geometries (`{type, coordinates}`) | values with `__geo_interface__` (a GeoDataFrame geometry column, shapely) or GeoJSON dicts | GeoJSON geometry objects |
57
+
58
+ - Times are wall-clock times. The axis shows the clock time of the data, in every output and every time zone.
59
+ - A float that is not an integer keeps 6 significant digits.
60
+ - The builders send only the columns that a mapping or a facet uses.
61
+ - Geometry coordinates keep 5 decimals (about 1 m in degrees).
62
+ - `plot()` and the `data` of a layer also take a GeoJSON FeatureCollection: one row per feature, with its properties as columns and its geometry in the column `geometry`.
63
+
64
+ ## 3. Builder rules
65
+
66
+ 1. Each method returns a new plot. The old plot does not change.
67
+ 2. A string that is a column name of the layer data is a mapping. Any other value is a constant.
68
+ 3. A constant color is a theme color or a CSS color.
69
+ - The theme colors are `blue`, `orange`, `red`, `teal`, `green`, `yellow`, `purple`, `pink`, `brown` and `gray`.
70
+ - The theme roles are `ink`, `muted`, `grid`, `tick`, `strip`, `accent` and `background`.
71
+ - Any other value is an error.
72
+ 4. A layer inherits the plot mappings for its channels. `hline`, `vline`, `abline` and `band` do not inherit.
73
+ 5. `tooltip` and `group` accept columns only.
74
+ 6. An unknown column, method, option, style, format or value is an error at the call. The message lists the valid names.
75
+ 7. Python keyword arguments and JS option objects have the same names and values: `facet("g", free="y")` is `facet("g", { free: "y" })`.
76
+
77
+ ## 4. Layers
78
+
79
+ | Method | Channels | Options | Statistic | Observable Plot mark |
80
+ |---|---|---|---|---|
81
+ | `line` | x, y, color, group, tooltip | size, alpha, dash, summary, direct | `summary` | `line`, sorted by x; `text` for the direct labels |
82
+ | `path` | x, y, color, group, tooltip | size, alpha, dash | – | `line`, in row order |
83
+ | `step` | x, y, color, group, tooltip | size, alpha, dash | – | `line`, step after each point |
84
+ | `point` | x, y, color, tooltip | size, alpha, jitter, summary, position | `summary`, dodge | `dot` |
85
+ | `bar` | x, y, color, tooltip | alpha, position | stack or dodge | `barY` (category x), `rect` (number or time x, 90% of the data step) |
86
+ | `hist` | x, color | alpha, bins, density, position | bins | `rect` |
87
+ | `density` | x, color | size, alpha, dash | Gaussian kernel density | `areaY` + `line` |
88
+ | `area` | x, y, color, group | alpha, position | stack | `areaY` |
89
+ | `ribbon` | x, ymin, ymax, color, group | alpha | – | `areaY` |
90
+ | `smooth` | x, y, color | size, alpha, dash, method, span, band | linear fit or loess | `areaY` (band) + `line` |
91
+ | `hline`, `vline` | y or x, color | size, alpha, dash | – | `ruleY`, `ruleX` |
92
+ | `abline` | color | slope, intercept, size, alpha, dash | – | `line` across the x domain |
93
+ | `segment` | x, y, xend, yend, color | size, alpha, dash, position | dodge | `link` |
94
+ | `rect` | xmin, xmax, ymin, ymax, color, tooltip | alpha | – | `rect` |
95
+ | `band` | xmin, xmax, ymin, ymax, color | alpha | – | `rect`. A missing bound is the panel edge. |
96
+ | `tile` | x, y, color, tooltip | alpha | – | `cell` (two categories), `barX`/`barY` (one category), `rect` (two numbers) |
97
+ | `text` | x, y, label, color | size, alpha, repel | – | `text`; with `repel`, leader lines (`path`) |
98
+ | `errorbar` | x, ymin, ymax, color | size, alpha, position | dodge | `ruleX` and two caps |
99
+ | `polygon` | geometry, fill, color, tooltip | size, alpha | – | `geo`, through the x and y scales |
100
+ | `raster` | x, y, fill | alpha | the grid of the cells | one `image` (a PNG) in an `svg` clipped to the frame |
101
+ | `box` | x, y, color | alpha (of the box fill, default 0.3) | Tukey box per category (`boxStats` in `stats.js`): quartiles, whiskers to the last values within 1.5 IQR, outliers | `barY` (q1 to q3, outlined in the series color), `tickY` (bold median and whisker caps), `ruleX` (whiskers), `dot` (outliers, in the series color) |
102
+
103
+ | Option | Values | Meaning |
104
+ |---|---|---|
105
+ | `size` | number | Line width or point radius, in px; text size, in px |
106
+ | `alpha` | 0–1 | Opacity |
107
+ | `dash` | `solid`, `dashed`, `dotted`, `dashdot` | Line pattern |
108
+ | `jitter` | number | Random horizontal offset, as a share of the category width or of the x step. The seed is fixed, so each output is the same. |
109
+ | `summary` | `mean`, `median`, `min`, `max`, `sum` | One row per (x, color, group), with the summary of y |
110
+ | `position` | `stack`, `dodge`, `overlay` | Bars and areas (default `stack`): the colors add up at each x, in the legend order. Dodge (bars): one bar per color, side by side. Overlay: each color starts at 0; fills are see-through. Points, segments and error bars (default `overlay`; `stack` is an error): dodge puts each color in its own slot of the category band (below). |
111
+ | `bins` | number | About this number of bins on round values (default 30). All panels and colors use the same bins. |
112
+ | `density` | `true`, `false` | `hist` counts divided by (rows × bin width), so the area is 1 |
113
+ | `method` | `lm` (default), `loess` | `lm`: least squares with a 95% confidence band (Student t). `loess`: local linear fit with tricube weights, without a band. |
114
+ | `span` | 0–1 | The share of the points in each local fit of `loess` (default 0.75) |
115
+ | `band` | `true` (default), `false` | The confidence band of `lm` |
116
+ | `direct` | `true`, `false` (default) | The name of each line at its end (below) |
117
+ | `repel` | `true`, `false` (default) | Text labels move to a free place near their point (below) |
118
+
119
+ - `color` maps the stroke of lines and the fill of points, bars, areas, rects, tiles and text, and the outline of polygons. `fill` maps the fill of polygons and rasters.
120
+ - A line, path or step without `group` has one line per color value. A missing value (`null`) makes a gap.
121
+ - A layer without columns, for example `hline(y=0)`, draws once in each panel.
122
+ - A layer table without the facet column draws in each panel.
123
+ - A statistic runs on the rows of each panel, after the legend filter. Bin edges do not depend on the panel.
124
+ - Dodge of `point`, `segment` and `errorbar`: the band of each category has one slot per color of the plot, in the legend order, so a color has the same place in every category, panel and layer, and the segments of a color meet its points. A color that the legend hides leaves its slot empty. The slots are along the category axis: x, else y (`errorbar` draws vertical bars, so it needs a category x). Dodge needs a category axis and a color mapped to a string column; a constant color takes the center. The caps of an error bar are 30% of the band, or 60% of a slot.
125
+ - `polygon` draws the GeoJSON `Polygon` and `MultiPolygon` geometries of a geometry column, with x as the first coordinate (longitude) and y as the second (latitude). Holes stay empty (even-odd rule). Without `geometry`, it takes the column named `geometry`. `fill` fills the areas (a column, through the fill scale, or a color); `color` is the outline. Without `fill`, it draws outlines in `muted`, 0.6 px; with `fill`, thin outlines (0.5 px) in the `background` color separate the areas. `size` is the outline width; `alpha` the opacity of the fill (or of the outline without fill). The bounding boxes of the geometries train the axis domains. A geometry column goes to `geometry` only.
126
+ - `raster` draws a regular grid of cells (one row per cell center, for example a 1 km mesh of seismic intensity) as one image of one pixel per cell, colored by the fill scale, without smoothing, under the layers after it. The grid step in x and y is the mean of the gaps between neighbouring distinct values over the number of steps that each gap spans (refined three times), so values with 6 significant digits keep their columns; a missing cell, or a `null` fill, is transparent. A value more than a quarter of a step off the grid is an error. The cell edges train the axis domains. x and y must be number or time axes. The PNG is made once per figure and a zoom moves it; Node and the browser write the same bytes.
127
+ - `text(repel=true)` places each label, in row order (put the important ones first), at the first free place around its anchor: right, upper right, lower right, left, upper left, lower left, above, below (0.4 em beside, 0.2 em above or below, beyond a point drawn there), then on rings 0.5 em apart, up to 10 em. A place is free when the label is inside the panel and clear of the labels placed before, of the anchors, of the points of the `point` layers of the panel, of the insets and of the scale bar and north arrow. When no place is free, the label goes to the right of its anchor anyway. A label further than 1.5 em from its anchor gets a thin leader line in `muted`. The placement uses the font metrics (the same in Node and the browser) and runs again at each zoom.
128
+ - Direct labels (`line(direct=true)`): each series (the `group` value, else the `color` value) gets its name right of its last point in view, in its color, darkened (or lightened on a dark background) to a contrast of 3:1 at least. A long name wraps to 2 lines, at most 160 px or 20% of the figure width. Labels that would overlap move apart vertically, and stay in the panel when there is room. Each panel gets a right margin for the longest name; the legend stays unless `theme(legend="none")`.
129
+
130
+ ## 5. Scales
131
+
132
+ ### Position (`x`, `y`)
133
+
134
+ - The axis type is `type`, or else the type of the first mapped column: `time` → time, `string` → category, `number` → linear. `log` is a log10 axis.
135
+ - The axis domain trains on the layer views, which include the statistics. For example, it includes the 0 of a bar and the top of a stack.
136
+ - The first view is `limits` when it is set. A `null` bound keeps the data bound on that side, with its 5% space. Without limits, the first view is the data range plus 5% on each side.
137
+ - A category axis shows the categories in the `limits` order, then in the `levels` order, then in natural sort order. A label that is too wide for its band wraps at its spaces, to 3 lines at most. If a word is still too wide, all labels rotate by 40°; a rotated label gets 60% of the panel height (at least 10 em) and ends with an ellipsis beyond it, and the left margin grows so that the first one is not cut off.
138
+ - Continuous axes have major ticks and minor grid lines at the midpoints. A log axis has ticks at the powers of ten, with minor lines at 2–9 times each power; with fewer than three powers of ten in view, it has ticks at 1, 2 and 5 times each power.
139
+ - `breaks` (a list of numbers or times) sets the major ticks of a number, log or time axis, with no minor grid lines; a zoom keeps them, and a break outside the view does not show. `labels` (strings, one per break) are the tick labels; without them, the label is `format`, or `~g` (log), `,~r` (linear) or the time pattern. Breaks on a category axis are an error.
140
+ - Time labels are on one line. The pattern follows the tick step: `%Y-%m`, `%m-%d`, `%m-%d %H:%M` (more than one day in view), `%H:%M` or `%H:%M:%S`. `format`, a d3-format or d3-time-format string, replaces it.
141
+
142
+ ### Color
143
+
144
+ | Column type | Scale | Legend |
145
+ |---|---|---|
146
+ | `string` | One color per category: `values` (a list, or a map category → color), else `palette`, else the style palette, in order | Swatches: a square for fills, a line for lines, a point for points |
147
+ | `number`, `time` | `values` (a list of colors), else `scheme`, else the style scheme | A color ramp |
148
+ | `number`, `time`, with `breaks` | One color per class: `values` (a list of one color per break), else the scheme at the middle of each class | Steps: one box per class |
149
+
150
+ There are two color scales: `color` (`color()`, the `color` channel) and `fill` (`fill()`, the `fill` channel of `polygon` and `raster`). They have the same options, each its own legend, and they can map different columns: for example the outage of each area (`fill`) and the class of each town (`color`).
151
+
152
+ - `breaks` (numbers or times that increase) make a binned scale. The classes are `[b0, b1)`, …, `[b(n-1), bn)` and `[bn, ∞)`: one class per break, closed on the left. They depend on the breaks only, so two plots with the same breaks have the same colors. A value below `b0` is `muted` (with `clamp: true`, the first class) and has no legend entry; `null` is `muted`. `labels` (one per break) names the classes. `mid` and a map of `values` do not apply. Breaks on a string column are an error.
153
+ - The steps legend has one box per class, low to high: left to right at the bottom, bottom to top on the right. The break values (format `,~r`, or the time pattern) are at the lower edge of each box; class names (`labels`) are on the boxes.
154
+ - `limits` sets the categories (and their order) or the range of the color scale. A `null` bound keeps the data bound.
155
+ - `mid` makes a diverging scale: `mid` takes the center color of the scheme, and each side stretches to its limit.
156
+ - A list of colors and a plotto scheme interpolate in Lab space. A d3 scheme name (such as `viridis` or `blues`) uses the d3 interpolator.
157
+ - A continuous value outside the domain is `muted`. `clamp: true` gives it the end color.
158
+ - All the color mappings of one scale must use the same column.
159
+ - A plot with mappings on both scales stacks the two legends (color first), at the right or at the bottom. The fill legend does not toggle values.
160
+ - A long legend wraps into columns.
161
+ - A horizontal color ramp has fewer ticks when their labels would touch.
162
+ - A right legend keeps a narrow column (20% of the width, 110 to 200 px): a long label wraps to 3 lines at most, then ends with an ellipsis, and its full text is its SVG title. A bottom legend has one line per label.
163
+
164
+ ### Map coordinates
165
+
166
+ `coord("geo")` makes x the longitude and y the latitude, in degrees, at the same distance per px in x and y.
167
+
168
+ - One degree of longitude is `cos φ` degrees of latitude, at the center latitude φ of the view. This is exact for a region and about 10% off east-west at the edges of a map of all Japan (no projection).
169
+ - The panels take the shape of the map (the median shape when the panels have their own extent), unless `theme(aspect=)` sets it. Each panel then grows its extent in x or in y, around its center, to fill its box. `limits` is the area that must show; one side can grow.
170
+ - The stored view does not change: zoom, pan, reset, a resize and "Copy for a slide" draw it at equal scale again.
171
+ - Tick labels are in degrees: `135°E`, `35°N` (W and S for negative values), unless `format` is set. There are no axis titles unless `labels()` sets them.
172
+ - x and y must be number axes (not log, time or category), and `facet(free=)` must be `both` or unset.
173
+ - `coord("geo", scalebar=, north=)`: `true` or a corner (`bottom-left`, `bottom-right`, `top-left`, `top-right`). `scalebar=true` is at the bottom left, `north=true` at the top right, 0.8 em inside the frame of each main panel (not the insets). The scale bar is a round length (1, 2 or 5 × 10^k km) near a fifth of the panel width, at 111.32 km × cos φ per degree of longitude, with its length as text above it; it follows the zoom. The north arrow points up.
174
+
175
+ ### Insets
176
+
177
+ `inset(x=[low, high], y=[low, high], at=[left, bottom, right, top])` draws the extent x × y in a box of each panel; `at` is in shares of the panel, from its bottom left. For example the Okinawa islands, the Izu and Ogasawara islands, or eastern Hokkaido on a map of Japan, so that no point is left out of the main extent. Each call adds one inset.
178
+
179
+ - An inset draws the layers of its panel (with the rows of that panel), on the `background` color, with a frame in `tick` and without axes and grid lines. It covers the panel under it.
180
+ - In map coordinates, the extent grows on one side to fill the box at the same distance per px in x and y.
181
+ - An inset keeps its extent: zoom, pan and the zoom buttons apply to the main panels only. Hover and pinned labels work in insets.
182
+ - Insets need number or time axes.
183
+
184
+ ## 6. Facets
185
+
186
+ | Call | Panels | Strips |
187
+ |---|---|---|
188
+ | `facet(by, free=, ncol=)` | One panel per value of `by`. The default column count is the ggplot rule (`n2mfrow`). | Above each panel |
189
+ | `grid(rows=, cols=, free=)` | One panel per (row value, column value) | Column values above the top row; row values on the right of the last column |
190
+
191
+ - `free` is `x`, `y` or `both`. A free axis has one domain per panel (`facet`), or per column for x and per row for y (`grid`).
192
+ - A shared y axis shows on the first column only. A shared x axis shows below the last panel of each column. A free axis shows on each panel.
193
+ - All panels have the same inner size, so they align.
194
+ - A strip label that is too long ends with an ellipsis. The full label is its SVG title.
195
+
196
+ ### Palettes and schemes (`theme.json`)
197
+
198
+ | Palette | Colors |
199
+ |---|---|
200
+ | `pastel` | The pastel style: soft blue, coral, sage, lavender, rose, mustard, aqua, brick, mocha, slate |
201
+ | `sakura`, `aizome`, `momiji` | Spring, indigo-dye and autumn sets, inspired by traditional Japanese colors |
202
+ | `wota`, `tableau` | The wota brand; Tableau 10 |
203
+
204
+ A style can also list theme color names as its palette: the `paper` and `dark` styles use their own colors this way.
205
+
206
+ | Scheme | Gradient |
207
+ |---|---|
208
+ | `ai` | Light to deep indigo (the pastel style) |
209
+ | `sakura` | Light to deep cherry (the wota style) |
210
+ | `matcha` | Cream to deep green |
211
+ | `yuhi` | Sunset: yellow, orange, red, plum (the dark style) |
212
+ | `sumi` | Ink grays |
213
+ | `aiaka` | Diverging: indigo, white, vermilion. Use it with `mid`. |
214
+
215
+ ## 7. Themes
216
+
217
+ `theme(style, format=, width=, height=, size=, legend=, aspect=)`.
218
+
219
+ | Style | Look |
220
+ |---|---|
221
+ | `pastel` (default) | Warm white paper, warm gray ink and grid, the `pastel` palette, the `ai` scheme, Helvetica or Arial, lines 25% thicker |
222
+ | `wota` | WOTA brand: pink and blue first, tinted strips, M PLUS 1p |
223
+ | `paper` | Black ink, color-blind-safe palette (Okabe–Ito) |
224
+ | `dark` | Dark background, bright palette |
225
+
226
+ | Format | Size (px) | Base text (px) | Width |
227
+ |---|---|---|---|
228
+ | `screen` (default) | 900 × 500 | 12 | Follows the element or cell width (reflow) |
229
+ | `report` | 640 × 400 | 10 | Fixed |
230
+ | `slide` | 691 × 403 | 13 | Fixed, in slide pixels (96 per inch): 7.2 × 4.2 in for the body of a 16:9 slide, between its title and its footer, with room for comments on the right. The outer margin is 0.3 em. A plot with one panel is at most 0.55 times as tall as it is wide (`flat`); the height that is left goes half above and half below it. |
231
+
232
+ - A style in `theme.json` lists only what differs from `pastel`. `weight` scales the line width (and the point radius by its square root).
233
+ - `width` fixes the size. The height then follows the aspect ratio of the format, unless `height` is set too.
234
+ - `height` alone fixes the height and keeps the reflow of the width.
235
+ - In reflow, the text keeps its px size, and the height follows the aspect ratio (at least 240 px).
236
+ - Below 560 px of width, a right legend moves to the bottom.
237
+ - A fixed size (`report`, `slide`, or a set `height`) chooses the layout of the legend and the info table:
238
+ 1. It tries each on the right and at the bottom. A place that the spec sets (`theme(legend=)`, `info(position=)`) stays.
239
+ 2. A format with `shrink` in `theme.json` (`slide`: 0.7) also tries their text smaller, in steps of 5%, down to that share of its size.
240
+ 3. It keeps the layouts that cut the least: legend labels and info keys with an ellipsis, a second legend column, "+N more" info rows.
241
+ 4. Of these, it keeps the layouts whose useful panel area is at most 20% below the largest one. The useful area counts the width of a panel only up to its height / 0.3: a flatter panel gets nothing from more width. It takes the largest text, then the usual places, then the largest area. The usual places are the legend of the theme (default: `right`; the `slide` format: `bottom`) and the info table on the right.
242
+ - A `screen` plot keeps the places and the text size.
243
+ - A bottom legend has its title on its first row, before the items.
244
+ - A format with `shrink` makes the facet strip text smaller (the same size for all strips) before it cuts a label, down to that share of its size.
245
+ - `aspect` is the shape of each panel, height / width: `1` gives square panels (for observed-against-predicted plots, with the same `limits` on x and y). The panels shrink in one direction to get that shape. A `screen` plot without `height` changes its height instead (at most 1.2 times its usual height), so the panels fill it. The space that is left goes half on each side of the panels.
246
+ - The title and the subtitle align left with the panels and wrap to two lines at most. A format with `shrink` first makes a long title or subtitle smaller, down to that share of its size, so that it stays on one line; one that does not fit even then keeps its size and wraps. A `screen` plot keeps room on the right for the toolbar; a fixed size uses the full width. The caption is at the bottom left, aligned with the panels: it wraps at the width of the figure less the y axis, to 4 lines at most (a longer one ends with an ellipsis), and starts further left only when it would run off the figure.
247
+ - A bottom info table puts its entries in up to 3 columns, as many as fit on one line each; else one column whose values wrap.
248
+ - `src/metrics.js` holds the glyph widths of each style font for the layout. CJK characters are one em wide.
249
+
250
+ ### Info table
251
+
252
+ `info(entries, position=)` draws facts about the data or the experiment as a key/value table: keys in `muted`, values in `ink`.
253
+
254
+ | Position | Place | Look |
255
+ |---|---|---|
256
+ | `right` | The right column, above the legend | A card in the `strip` color |
257
+ | `bottom` | Below the panels, above a bottom legend and the caption. The entries flow into 1 to 3 columns. | The same card |
258
+
259
+ - `right` is the default. Below 560 px of width, it moves to the `bottom`, as the legend does.
260
+ - A value wraps to 3 lines at most. A key takes at most 45% of the table width; a longer key ends with an ellipsis, and its full text is its SVG title.
261
+ - The table takes at most 60% of the figure height (`right`) or 30% (`bottom`). The entries that do not fit become one last row, `+N more`.
262
+ - A number keeps 6 significant digits, as in the data. `null` shows as `–`.
263
+ - Zoom and legend clicks do not change the table.
264
+
265
+ ## 8. Display and interaction
266
+
267
+ `draw(spec, element, { interactive, width })` draws the plot into the element. The element can be in a shadow root (marimo widgets): the styles then go into that shadow root.
268
+
269
+ | Item | Behavior |
270
+ |---|---|
271
+ | Width | A `screen` plot lays out at the element width, and again 100 ms after a width change (minimum 320 px). A fixed size scales down to fit. |
272
+ | Toolbar | A flat, square bar of icon buttons at the top right. It shows when the pointer is on the plot, and always on touch screens. The button size is 1/34 of the figure width, from 22 to 30 px. The active mode has the accent color. |
273
+ | Static buttons | Copy as PNG; Copy for a slide; Download (PNG or SVG) |
274
+ | Copy for a slide | Draws the current view (zoom, hidden series) again in the `slide` format, with the plot's style. The clipboard gets a PNG with 4 times the pixels (2764 px wide) and an HTML `<img>` at the figure size (691 × 403 px). Google Slides pastes the HTML at 96 px per inch: 7.2 in wide. |
275
+ | Interactive buttons | Also zoom box and pan (the active mode is highlighted), zoom in, zoom out, reset |
276
+
277
+ With `interactive: true`:
278
+
279
+ | Action | Result |
280
+ |---|---|
281
+ | Click in a panel | Pins the hover label: it stays when the pointer moves. The next click, or Esc, releases it. A press that moves less than 5 px is a click. |
282
+ | Drag in a panel (zoom mode) | After 5 px of movement, draws the zoom box; the release zooms to it. A flat drag (less than 5 px high) zooms x only. A narrow drag zooms y only. |
283
+ | Drag in a panel (pan mode) | Moves the view |
284
+ | Zoom in, zoom out | Keeps 75% of the range (or 133%) around the center of each panel |
285
+ | Reset, double-click in a panel | Restores the first view |
286
+ | Hover | Shows the label of the row under the pointer (see below) |
287
+ | Legend click | Hides or shows that value in all panels at once. Stacks and statistics compute again; the domains do not change. |
288
+ | Two legend clicks within 300 ms | Show only that value; two more show all. A slower second click only shows the value again. |
289
+
290
+ Hover:
291
+
292
+ | Layers | What the label shows | Marks |
293
+ |---|---|---|
294
+ | line, step, area, density, smooth, ribbon | Up to 6 series at the nearest x: every series, in the legend order, with the series nearest the pointer in bold (crosshair and a dot on each series). More than 6 series: only the series nearest the pointer, and the count of the others (crosshair and one dot). The picked series stays until another one is at least 4 px nearer. | – |
295
+ | bar, hist | The column nearest the pointer: one row per color, the segment under the pointer in bold, and the total of a stack | Outline of the segment |
296
+ | box | The box under the pointer: whiskers, quartiles, median, count and outliers. It wins over the points drawn with it. | – |
297
+ | tile | The value of the cell, and its x and y | Outline of the cell |
298
+ | polygon | The area under the pointer (the top one): its tooltip value as the header, and its fill and color values. A point near the pointer wins. | – |
299
+ | raster | The cell under the pointer: its fill value as the header, and its x and y | – |
300
+ | point, path, errorbar | The nearest point within 40 px. It stays picked until another point is at least 4 px nearer. | Dot |
301
+
302
+ - The label box is flat and square. Its header has the color of the hovered series. A light color gets dark text; any other color gets white text, on the color darkened until the contrast is at least 4:1. On several series, the header is dark and each row has a color swatch.
303
+ - With several series, the rows keep the legend order (or the order of the color values), so they do not jump.
304
+ - The box follows the pointer, not the data, so noisy data does not make it jump.
305
+ - Numbers have 4 significant digits, with thousands separators. Times follow the data: `%Y-%m` (months), `%Y-%m-%d` (days), `%m-%d %H:%M` or `%m-%d %H:%M:%S`.
306
+
307
+ - A zoom on a shared axis applies to every panel that shares it. A category axis does not zoom.
308
+ - A zoom, a legend click or a resize draws again with the same code, so the look does not change. A resize keeps the zoom and the hidden values.
309
+
310
+ ## 9. Outputs
311
+
312
+ | Output | Function | Notes |
313
+ |---|---|---|
314
+ | Static SVG | `toSVG(spec)` (JS), `p.save("f.svg")` (Python) | At the size of the theme |
315
+ | PNG | `p.save("f.png", scale=2, width=, height=)` | resvg draws the Node SVG. `width` and `height` lay out again at that size. |
316
+ | Notebook | `p`, `p.interactive()` | `text/html`: the static SVG, the spec and the browser bundle, which calls `draw()`. The bundle loads d3 and Observable Plot from `cdn.jsdelivr.net`. Without the script, the static SVG stays. |
317
+ | marimo | `p`, `p.interactive()` | `_display_()` (Jupyter ignores it). With anywidget: a widget with the traits `spec` and `interactive`, whose module (`widget.js`) calls `draw()`. It loads d3 and Observable Plot from `cdn.jsdelivr.net`. No Node call and no static SVG. Without anywidget: the notebook HTML through `mo.Html`, of which marimo shows the static SVG. |
318
+ | Browser | `draw(spec, el, options)` | Returns `{ state, redraw(), resize(width), destroy() }` |
319
+ | React | `<Plot spec={...} interactive />` (`plotto/react`) | Calls `draw()`; it follows the container width |
320
+
321
+ The Node SVG and the browser SVG are the same, except for the numbers of the clip paths. On a screen with a device pixel ratio of 1, Observable Plot also adds a half-pixel offset to lines.
322
+
323
+ ## 10. Limits
324
+
325
+ - Themes are styles and formats with four overrides. There is no `element_*` theming.
326
+ - There are two color scales per plot: `color` and `fill`. Size and shape are constants, not mappings.
327
+ - A raster has one row per cell in the spec (about 30 bytes per cell) and an image of 4 bytes per cell, without compression: crop the grid to the map (90 000 cells make a spec of about 3 MB).
328
+ - A geometry column is JSON in the spec and in the notebook HTML: simplify the geometries first (for example `GeoSeries.simplify` or mapshaper). Each zoom and pan draws every area again.
329
+ - There is no plot composition.
330
+ - More than about 20 000 points make a large SVG: the SVG of 20 000 points is about 1.7 MB.
331
+ - A saved SVG uses the fonts of the viewer. Without the style font, the text has other widths.