python-plotto 0.5.1__tar.gz → 0.6.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 (25) hide show
  1. {python_plotto-0.5.1/python_plotto.egg-info → python_plotto-0.6.0}/PKG-INFO +6 -1
  2. {python_plotto-0.5.1 → python_plotto-0.6.0}/README.md +2 -0
  3. {python_plotto-0.5.1 → python_plotto-0.6.0}/plotto/__init__.py +1 -1
  4. python_plotto-0.6.0/plotto/_assets/README.md +224 -0
  5. python_plotto-0.6.0/plotto/_assets/SPEC.md +285 -0
  6. python_plotto-0.6.0/plotto/_assets/plotto.js +35 -0
  7. python_plotto-0.6.0/plotto/_assets/widget.js +35 -0
  8. {python_plotto-0.5.1 → python_plotto-0.6.0}/plotto/plot.py +11 -0
  9. python_plotto-0.6.0/plotto/widget.py +19 -0
  10. {python_plotto-0.5.1 → python_plotto-0.6.0}/pyproject.toml +2 -1
  11. {python_plotto-0.5.1 → python_plotto-0.6.0/python_plotto.egg-info}/PKG-INFO +6 -1
  12. {python_plotto-0.5.1 → python_plotto-0.6.0}/python_plotto.egg-info/SOURCES.txt +4 -0
  13. {python_plotto-0.5.1 → python_plotto-0.6.0}/python_plotto.egg-info/requires.txt +4 -0
  14. {python_plotto-0.5.1 → python_plotto-0.6.0}/tests/test_output.py +27 -0
  15. python_plotto-0.5.1/plotto/_assets/plotto.js +0 -35
  16. {python_plotto-0.5.1 → python_plotto-0.6.0}/LICENSE +0 -0
  17. {python_plotto-0.5.1 → python_plotto-0.6.0}/plotto/_assets/grammar.json +0 -0
  18. {python_plotto-0.5.1 → python_plotto-0.6.0}/plotto/_assets/theme.json +0 -0
  19. {python_plotto-0.5.1 → python_plotto-0.6.0}/plotto/assets.py +0 -0
  20. {python_plotto-0.5.1 → python_plotto-0.6.0}/plotto/data.py +0 -0
  21. {python_plotto-0.5.1 → python_plotto-0.6.0}/plotto/output.py +0 -0
  22. {python_plotto-0.5.1 → python_plotto-0.6.0}/python_plotto.egg-info/dependency_links.txt +0 -0
  23. {python_plotto-0.5.1 → python_plotto-0.6.0}/python_plotto.egg-info/top_level.txt +0 -0
  24. {python_plotto-0.5.1 → python_plotto-0.6.0}/setup.cfg +0 -0
  25. {python_plotto-0.5.1 → python_plotto-0.6.0}/tests/test_builder.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: python-plotto
3
- Version: 0.5.1
3
+ Version: 0.6.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.1"
6
+ __version__ = "0.6.0"
7
7
 
8
8
  from .plot import Plot, plot # noqa: E402
9
9
 
@@ -0,0 +1,224 @@
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 or a list of dicts. JavaScript takes an array of row objects.
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
+ | Category colors | `color(palette="sakura")`, or `color(values={"a": "red", "b": "#123456"})` |
85
+ | Number colors | `color(scheme="ai")`; diverging: `color(scheme="aiaka", mid=0)` |
86
+
87
+ 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`, …).
88
+
89
+ ### Info table
90
+
91
+ Put facts about the data or the experiment in a table instead of a long subtitle:
92
+
93
+ ```python
94
+ p.info({"data point": 15, "location": "hayama", "experiment": "cleaning with chlorine"})
95
+ p.info(entries, position="bottom") # "right" (default) or "bottom"
96
+ ```
97
+
98
+ 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.
99
+
100
+ ### Notebook
101
+
102
+ - A plot shows at the width of the cell. The text keeps its size, and the height follows the aspect ratio of the format.
103
+ - `.interactive()` adds zoom, pan, hover and the legend toggle.
104
+ - The hover follows the plot type:
105
+ - lines and areas: every series at the nearest x, or only the series under the pointer when there are more than 6;
106
+ - bars: the stack and its total;
107
+ - box: the quartiles;
108
+ - tile: the cell value;
109
+ - points: the nearest point.
110
+ - 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.
111
+ - A legend click hides or shows a series. Two quick clicks on the same entry (within 300 ms) show only that series.
112
+ - The toolbar shows at the top right when the pointer is on the plot:
113
+ - copy as PNG;
114
+ - copy for a slide: the current view in the slide format, which pastes into Google Slides at 7.2 × 4.2 in, sharp;
115
+ - download as PNG or SVG;
116
+ - in interactive mode, also zoom box, pan, zoom in, zoom out and reset.
117
+ - 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.
118
+ - 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.
119
+ - 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.
120
+
121
+ ### Web pages and React
122
+
123
+ - `draw(spec, element, { interactive })` draws into an element at its width, and draws again when the width changes. It returns `{ destroy }`.
124
+ - In React, use `import { Plot } from "plotto/react"`, then `<Plot spec={plot(rows, {...}).line()} interactive />`.
125
+
126
+ ### Slides and reports
127
+
128
+ | Target | Use |
129
+ |---|---|
130
+ | 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. |
131
+ | PowerPoint, Keynote, documents | SVG: `p.save("fig.svg")`. The SVG uses the installed fonts. |
132
+ | A slide layout | `p.theme(style, format="slide")`: 691 × 403 px, the size on the slide |
133
+ | A report column | `p.theme(style, format="report")`: 640 × 400 px |
134
+ | Square panels | `p.theme(aspect=1)`, for observed-against-predicted plots. Give x and y the same `limits`. |
135
+ | A given size | `p.save("fig.png", width=1600)` lays the plot out again at 1600 px. |
136
+ | From the notebook | Use the copy button, which copies the current view as PNG. |
137
+
138
+ ## Examples
139
+
140
+ | File | Content |
141
+ |---|---|
142
+ | `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. |
143
+ | `examples/grammar.py` | The grammar tutorial: 14 steps, each with its text, code and result. |
144
+ | `examples/reference.py` | The API reference. The layer methods come from `grammar.json`. |
145
+ | `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/`. |
146
+ | `examples/showcase.ipynb` | The examples in a notebook. |
147
+ | `examples/web/` | Examples in JavaScript. Run `python3 -m http.server` in the repo, then open `http://localhost:8000/examples/web/`. |
148
+
149
+ To publish the gallery:
150
+
151
+ 1. Run `python examples/build_site.py`.
152
+ 2. Commit `docs/`.
153
+ 3. On GitHub, set Settings → Pages → Source to "Deploy from a branch", with branch `main` and folder `/docs`.
154
+ | `examples/data/` | The datasets. `examples/make_datasets.py` makes the made-up ones. |
155
+
156
+ ## Tests
157
+
158
+ | Command | What it verifies |
159
+ |---|---|
160
+ | `npm test` | Each layer and style (SVG snapshots in `tests/snapshots/`), stacks, bins, smooth fits, domains, facets, legends, reflow, errors |
161
+ | `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. |
162
+ | `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. |
163
+ | `ruff check . && black --check .` | Python lint |
164
+
165
+ If a change of the look is intentional, run `UPDATE_SNAPSHOTS=1 npm test` and review the SVG diff.
166
+
167
+ ## Maintenance
168
+
169
+ To add a layer type:
170
+
171
+ 1. Add the layer to `grammar.json`: channels, options and required channels.
172
+ 2. Add one entry to `LAYERS` in `src/layers.js`.
173
+ 3. For a statistic, add the computation to `src/stats.js` and a case to `makeView` and `hoverOf` in `src/views.js`.
174
+ 4. Add the method to `src/builder.js` and `python/plotto/plot.py`.
175
+ 5. Add a case to `tests/render.test.js` and to `tests/fixtures/parity.json`.
176
+ 6. Add a row to the layer table in `SPEC.md`.
177
+
178
+ 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.
179
+
180
+ ## Release
181
+
182
+ A tag `vX.Y.Z` publishes `python-plotto` to PyPI and `plotto` to npm (`.github/workflows/release.yml`).
183
+
184
+ One-time setup:
185
+
186
+ 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`.
187
+ 2. On GitHub, create the environment `pypi` (Settings → Environments).
188
+ 3. On npmjs.com, create an account (with two-factor authentication). Publish the first version from your computer, in the repo:
189
+
190
+ ```
191
+ npm login
192
+ npm test
193
+ npm publish --access public
194
+ ```
195
+
196
+ 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.
197
+
198
+ Each release (`main` takes changes only through a reviewed pull request):
199
+
200
+ ```bash
201
+ # 1. Merge your changes into main through a pull request,
202
+ # with a line for each change under "## Unreleased" in CHANGELOG.md
203
+
204
+ # 2. Prepare the release
205
+ git switch main && git pull && source .venv/bin/activate
206
+ scripts/release.sh 0.3.1
207
+ # → the pull request page opens: create it, get it approved and merged
208
+
209
+ # 3. Publish
210
+ scripts/release.sh tag # answer y
211
+
212
+ # 4. Check
213
+ npm view plotto version && pip index versions python-plotto
214
+ ```
215
+
216
+ - `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.
217
+ - `scripts/release.sh tag` tags the merged `main` as `vX.Y.Z`, asks before it pushes the tag, and deletes the release branch.
218
+ - The pushed tag runs `.github/workflows/release.yml`, which publishes to PyPI and npm. Follow it in the Actions tab.
219
+
220
+ To upgrade Observable Plot or d3:
221
+
222
+ 1. Change the exact version in `package.json`.
223
+ 2. Run `npm install`.
224
+ 3. Run the tests. A snapshot difference shows a change of the look.
@@ -0,0 +1,285 @@
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`. `color`: `values`, `palette`, `scheme`, `limits`, `mid`, `clamp`. |
43
+ | `labels` | `title`, `subtitle`, `caption`, `x`, `y`, `color`. `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
+ | `theme` | `style`, `format`, and the overrides `width`, `height`, `size`, `legend` |
46
+
47
+ ### Column types
48
+
49
+ | Type | Values | From Python | From JS |
50
+ |---|---|---|---|
51
+ | `number` | numbers | numeric dtypes | `number` |
52
+ | `time` | wall-clock epoch ms | `datetime64`. A time-zone-aware column keeps its local clock time. | `Date` (local clock time) |
53
+ | `string` | strings | object, string, bool (`"true"`, `"false"`), categorical (with `levels`) | any other value |
54
+
55
+ - Times are wall-clock times. The axis shows the clock time of the data, in every output and every time zone.
56
+ - A float that is not an integer keeps 6 significant digits.
57
+ - The builders send only the columns that a mapping or a facet uses.
58
+
59
+ ## 3. Builder rules
60
+
61
+ 1. Each method returns a new plot. The old plot does not change.
62
+ 2. A string that is a column name of the layer data is a mapping. Any other value is a constant.
63
+ 3. A constant color is a theme color or a CSS color.
64
+ - The theme colors are `blue`, `orange`, `red`, `teal`, `green`, `yellow`, `purple`, `pink`, `brown` and `gray`.
65
+ - The theme roles are `ink`, `muted`, `grid`, `tick`, `strip`, `accent` and `background`.
66
+ - Any other value is an error.
67
+ 4. A layer inherits the plot mappings for its channels. `hline`, `vline`, `abline` and `band` do not inherit.
68
+ 5. `tooltip` and `group` accept columns only.
69
+ 6. An unknown column, method, option, style, format or value is an error at the call. The message lists the valid names.
70
+ 7. Python keyword arguments and JS option objects have the same names and values: `facet("g", free="y")` is `facet("g", { free: "y" })`.
71
+
72
+ ## 4. Layers
73
+
74
+ | Method | Channels | Options | Statistic | Observable Plot mark |
75
+ |---|---|---|---|---|
76
+ | `line` | x, y, color, group, tooltip | size, alpha, dash, summary | `summary` | `line`, sorted by x |
77
+ | `path` | x, y, color, group, tooltip | size, alpha, dash | – | `line`, in row order |
78
+ | `step` | x, y, color, group, tooltip | size, alpha, dash | – | `line`, step after each point |
79
+ | `point` | x, y, color, tooltip | size, alpha, jitter, summary | `summary` | `dot` |
80
+ | `bar` | x, y, color, tooltip | alpha, position | stack or dodge | `barY` (category x), `rect` (number or time x, 90% of the data step) |
81
+ | `hist` | x, color | alpha, bins, density, position | bins | `rect` |
82
+ | `density` | x, color | size, alpha, dash | Gaussian kernel density | `areaY` + `line` |
83
+ | `area` | x, y, color, group | alpha, position | stack | `areaY` |
84
+ | `ribbon` | x, ymin, ymax, color, group | alpha | – | `areaY` |
85
+ | `smooth` | x, y, color | size, alpha, dash, method, span, band | linear fit or loess | `areaY` (band) + `line` |
86
+ | `hline`, `vline` | y or x, color | size, alpha, dash | – | `ruleY`, `ruleX` |
87
+ | `abline` | color | slope, intercept, size, alpha, dash | – | `line` across the x domain |
88
+ | `segment` | x, y, xend, yend, color | size, alpha, dash | – | `link` |
89
+ | `rect` | xmin, xmax, ymin, ymax, color, tooltip | alpha | – | `rect` |
90
+ | `band` | xmin, xmax, ymin, ymax, color | alpha | – | `rect`. A missing bound is the panel edge. |
91
+ | `tile` | x, y, color, tooltip | alpha | – | `cell` (two categories), `barX`/`barY` (one category), `rect` (two numbers) |
92
+ | `text` | x, y, label, color | size, alpha | – | `text` |
93
+ | `errorbar` | x, ymin, ymax, color | size, alpha | – | `ruleX` and two caps |
94
+ | `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) |
95
+
96
+ | Option | Values | Meaning |
97
+ |---|---|---|
98
+ | `size` | number | Line width or point radius, in px; text size, in px |
99
+ | `alpha` | 0–1 | Opacity |
100
+ | `dash` | `solid`, `dashed`, `dotted`, `dashdot` | Line pattern |
101
+ | `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. |
102
+ | `summary` | `mean`, `median`, `min`, `max`, `sum` | One row per (x, color, group), with the summary of y |
103
+ | `position` | `stack` (default), `dodge` (bar only), `overlay` | Stack: the colors add up at each x, in the legend order. Dodge: one bar per color, side by side. Overlay: each color starts at 0; fills are see-through. |
104
+ | `bins` | number | About this number of bins on round values (default 30). All panels and colors use the same bins. |
105
+ | `density` | `true`, `false` | `hist` counts divided by (rows × bin width), so the area is 1 |
106
+ | `method` | `lm` (default), `loess` | `lm`: least squares with a 95% confidence band (Student t). `loess`: local linear fit with tricube weights, without a band. |
107
+ | `span` | 0–1 | The share of the points in each local fit of `loess` (default 0.75) |
108
+ | `band` | `true` (default), `false` | The confidence band of `lm` |
109
+
110
+ - `color` maps the stroke of lines and the fill of points, bars, areas, rects, tiles and text.
111
+ - A line, path or step without `group` has one line per color value. A missing value (`null`) makes a gap.
112
+ - A layer without columns, for example `hline(y=0)`, draws once in each panel.
113
+ - A layer table without the facet column draws in each panel.
114
+ - A statistic runs on the rows of each panel, after the legend filter. Bin edges do not depend on the panel.
115
+
116
+ ## 5. Scales
117
+
118
+ ### Position (`x`, `y`)
119
+
120
+ - 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.
121
+ - 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.
122
+ - 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.
123
+ - 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.
124
+ - 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.
125
+ - 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.
126
+
127
+ ### Color
128
+
129
+ | Column type | Scale | Legend |
130
+ |---|---|---|
131
+ | `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 |
132
+ | `number`, `time` | `values` (a list of colors), else `scheme`, else the style scheme | A color ramp |
133
+
134
+ - `limits` sets the categories (and their order) or the range of the color scale. A `null` bound keeps the data bound.
135
+ - `mid` makes a diverging scale: `mid` takes the center color of the scheme, and each side stretches to its limit.
136
+ - 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.
137
+ - A continuous value outside the domain is `muted`. `clamp: true` gives it the end color.
138
+ - All color mappings of one plot must use the same column.
139
+ - A long legend wraps into columns.
140
+ - 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.
141
+
142
+ ## 6. Facets
143
+
144
+ | Call | Panels | Strips |
145
+ |---|---|---|
146
+ | `facet(by, free=, ncol=)` | One panel per value of `by`. The default column count is the ggplot rule (`n2mfrow`). | Above each panel |
147
+ | `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 |
148
+
149
+ - `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`).
150
+ - 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.
151
+ - All panels have the same inner size, so they align.
152
+ - A strip label that is too long ends with an ellipsis. The full label is its SVG title.
153
+
154
+ ### Palettes and schemes (`theme.json`)
155
+
156
+ | Palette | Colors |
157
+ |---|---|
158
+ | `pastel` | The pastel style: soft blue, coral, sage, lavender, rose, mustard, aqua, brick, mocha, slate |
159
+ | `sakura`, `aizome`, `momiji` | Spring, indigo-dye and autumn sets, inspired by traditional Japanese colors |
160
+ | `wota`, `tableau` | The wota brand; Tableau 10 |
161
+
162
+ A style can also list theme color names as its palette: the `paper` and `dark` styles use their own colors this way.
163
+
164
+ | Scheme | Gradient |
165
+ |---|---|
166
+ | `ai` | Light to deep indigo (the pastel style) |
167
+ | `sakura` | Light to deep cherry (the wota style) |
168
+ | `matcha` | Cream to deep green |
169
+ | `yuhi` | Sunset: yellow, orange, red, plum (the dark style) |
170
+ | `sumi` | Ink grays |
171
+ | `aiaka` | Diverging: indigo, white, vermilion. Use it with `mid`. |
172
+
173
+ ## 7. Themes
174
+
175
+ `theme(style, format=, width=, height=, size=, legend=, aspect=)`.
176
+
177
+ | Style | Look |
178
+ |---|---|
179
+ | `pastel` (default) | Warm white paper, warm gray ink and grid, the `pastel` palette, the `ai` scheme, Helvetica or Arial, lines 25% thicker |
180
+ | `wota` | WOTA brand: pink and blue first, tinted strips, M PLUS 1p |
181
+ | `paper` | Black ink, color-blind-safe palette (Okabe–Ito) |
182
+ | `dark` | Dark background, bright palette |
183
+
184
+ | Format | Size (px) | Base text (px) | Width |
185
+ |---|---|---|---|
186
+ | `screen` (default) | 900 × 500 | 12 | Follows the element or cell width (reflow) |
187
+ | `report` | 640 × 400 | 10 | Fixed |
188
+ | `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. |
189
+
190
+ - A style in `theme.json` lists only what differs from `pastel`. `weight` scales the line width (and the point radius by its square root).
191
+ - `width` fixes the size. The height then follows the aspect ratio of the format, unless `height` is set too.
192
+ - `height` alone fixes the height and keeps the reflow of the width.
193
+ - In reflow, the text keeps its px size, and the height follows the aspect ratio (at least 240 px).
194
+ - Below 560 px of width, a right legend moves to the bottom.
195
+ - A fixed size (`report`, `slide`, or a set `height`) chooses the layout of the legend and the info table:
196
+ 1. It tries each on the right and at the bottom. A place that the spec sets (`theme(legend=)`, `info(position=)`) stays.
197
+ 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.
198
+ 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.
199
+ 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.
200
+ - A `screen` plot keeps the places and the text size.
201
+ - A bottom legend has its title on its first row, before the items.
202
+ - 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.
203
+ - `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.
204
+ - 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.
205
+ - 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.
206
+ - `src/metrics.js` holds the glyph widths of each style font for the layout. CJK characters are one em wide.
207
+
208
+ ### Info table
209
+
210
+ `info(entries, position=)` draws facts about the data or the experiment as a key/value table: keys in `muted`, values in `ink`.
211
+
212
+ | Position | Place | Look |
213
+ |---|---|---|
214
+ | `right` | The right column, above the legend | A card in the `strip` color |
215
+ | `bottom` | Below the panels, above a bottom legend and the caption. The entries flow into 1 to 3 columns. | The same card |
216
+
217
+ - `right` is the default. Below 560 px of width, it moves to the `bottom`, as the legend does.
218
+ - 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.
219
+ - 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`.
220
+ - A number keeps 6 significant digits, as in the data. `null` shows as `–`.
221
+ - Zoom and legend clicks do not change the table.
222
+
223
+ ## 8. Display and interaction
224
+
225
+ `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.
226
+
227
+ | Item | Behavior |
228
+ |---|---|
229
+ | 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. |
230
+ | 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. |
231
+ | Static buttons | Copy as PNG; Copy for a slide; Download (PNG or SVG) |
232
+ | 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. |
233
+ | Interactive buttons | Also zoom box and pan (the active mode is highlighted), zoom in, zoom out, reset |
234
+
235
+ With `interactive: true`:
236
+
237
+ | Action | Result |
238
+ |---|---|
239
+ | 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. |
240
+ | 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. |
241
+ | Drag in a panel (pan mode) | Moves the view |
242
+ | Zoom in, zoom out | Keeps 75% of the range (or 133%) around the center of each panel |
243
+ | Reset, double-click in a panel | Restores the first view |
244
+ | Hover | Shows the label of the row under the pointer (see below) |
245
+ | Legend click | Hides or shows that value in all panels at once. Stacks and statistics compute again; the domains do not change. |
246
+ | Two legend clicks within 300 ms | Show only that value; two more show all. A slower second click only shows the value again. |
247
+
248
+ Hover:
249
+
250
+ | Layers | What the label shows | Marks |
251
+ |---|---|---|
252
+ | 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. | – |
253
+ | 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 |
254
+ | box | The box under the pointer: whiskers, quartiles, median, count and outliers. It wins over the points drawn with it. | – |
255
+ | tile | The value of the cell, and its x and y | Outline of the cell |
256
+ | point, path, errorbar | The nearest point within 40 px. It stays picked until another point is at least 4 px nearer. | Dot |
257
+
258
+ - 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.
259
+ - With several series, the rows keep the legend order (or the order of the color values), so they do not jump.
260
+ - The box follows the pointer, not the data, so noisy data does not make it jump.
261
+ - 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`.
262
+
263
+ - A zoom on a shared axis applies to every panel that shares it. A category axis does not zoom.
264
+ - 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.
265
+
266
+ ## 9. Outputs
267
+
268
+ | Output | Function | Notes |
269
+ |---|---|---|
270
+ | Static SVG | `toSVG(spec)` (JS), `p.save("f.svg")` (Python) | At the size of the theme |
271
+ | PNG | `p.save("f.png", scale=2, width=, height=)` | resvg draws the Node SVG. `width` and `height` lay out again at that size. |
272
+ | 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. |
273
+ | 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. |
274
+ | Browser | `draw(spec, el, options)` | Returns `{ state, redraw(), resize(width), destroy() }` |
275
+ | React | `<Plot spec={...} interactive />` (`plotto/react`) | Calls `draw()`; it follows the container width |
276
+
277
+ 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.
278
+
279
+ ## 10. Limits
280
+
281
+ - Themes are styles and formats with four overrides. There is no `element_*` theming.
282
+ - There is one color scale per plot. Size and shape are constants, not mappings.
283
+ - There is no plot composition.
284
+ - More than about 20 000 points make a large SVG: the SVG of 20 000 points is about 1.7 MB.
285
+ - A saved SVG uses the fonts of the viewer. Without the style font, the text has other widths.