plot3 0.4.2__tar.gz → 0.5.1__tar.gz

plot3-0.5.1/PKG-INFO

@@ -0,0 +1,308 @@
+Metadata-Version: 2.4
+Name: plot3
+Version: 0.5.1
+Summary: ggplot2 grammar of graphics for Python: interactive WebGL figures and journal-ready PNG, SVG, and PDF
+Author: Rigoberto Leyva Salmeron
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rleyvasal/plot3
+Project-URL: Changelog, https://github.com/rleyvasal/plot3/blob/main/CHANGELOG.md
+Keywords: ggplot,ggplot2,grammar of graphics,visualization,plotting,three.js,dataframe
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Jupyter
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Provides-Extra: fast
+Requires-Dist: contourpy>=1.0; extra == "fast"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: polars>=1.0; extra == "dev"
+Requires-Dist: contourpy>=1.0; extra == "dev"
+Provides-Extra: jupyter
+Requires-Dist: ipython>=8.0; extra == "jupyter"
+Provides-Extra: polars
+Requires-Dist: polars>=1.0; extra == "polars"
+Provides-Extra: export
+Requires-Dist: cairosvg>=2.7; extra == "export"
+Dynamic: license-file
+
+# plot3
+
+**ggplot2 for Python, plus what ggplot2 can't do: interactive 3D, animated
+data, and plots typed straight from an equation.** Figures render with WebGL
+in the notebook and save as journal-ready PNG, SVG, or PDF.
+
+<table>
+<tr>
+<td width="50%"><img src="https://raw.githubusercontent.com/rleyvasal/plot3/main/docs/img/gapminder.gif" alt="Gapminder: life expectancy against GDP per capita, animated from 1952 to 2007"></td>
+<td width="50%"><img src="https://raw.githubusercontent.com/rleyvasal/plot3/main/docs/img/lidar.gif" alt="A lidar driving scene with detection boxes, orbiting"></td>
+</tr>
+<tr>
+<td><sub><code>+ transition_time("year")</code>: gapminder in one line</sub></td>
+<td><sub><code>geom_point3d()</code> + <code>geom_box3d()</code>: a 220k-point lidar sweep with detection boxes</sub></td>
+</tr>
+<tr>
+<td><img src="https://raw.githubusercontent.com/rleyvasal/plot3/main/docs/img/ripple.gif" alt="An animated ripple surface z = sin(r - t)"></td>
+<td><img src="https://raw.githubusercontent.com/rleyvasal/plot3/main/docs/img/beta_slider.gif" alt="A beta density reshaping as two sliders move"></td>
+</tr>
+<tr>
+<td><sub><code>geom_function("z = sin(sqrt(x^2 + y^2) - t)") + transition_time(t=(0, 6.28))</code></sub></td>
+<td><sub><code>geom_function("y = dbeta(x, a, b)") + slider(a=…, b=…)</code></sub></td>
+</tr>
+</table>
+
+```bash
+pip install "plot3[jupyter,export]"
+```
+
+Contents: [Plot an equation](#plot-an-equation) ·
+[Animate your data](#animate-your-data) · [3D and point clouds](#3d-and-point-clouds) ·
+[One figure, two outputs](#one-figure-two-outputs) · [It's ggplot2](#its-ggplot2) ·
+[Notebooks, SolveIt, CRAFT](#notebooks-solveit-and-craft) · [Install](#install) ·
+[Full reference](docs/reference.md)
+
+## Plot an equation
+
+Write the maths as you would on paper. `geom_function` works out whether
+it's a curve, an implicit shape, a region, or a 3D surface, and picks a
+sensible window.
+
+```python
+from plot3 import *
+
+(ggplot() + geom_function("y = sin(x)", xlim=(-4, 4))                        # a function and
+ + geom_function("y = x - x^3/6", xlim=(-4, 4)))                            # its Taylor polynomial
+ggplot() + geom_function("(x^2 + y^2 - 1)^3 = x^2 y^3")                     # implicit: a heart
+ggplot() + geom_function("y > x^2", xlim=(-2, 2))                           # shaded region
+ggplot() + geom_function("r = 1 + cos(theta)") + coord_polar()              # polar cardioid
+ggplot() + geom_function(r"z = \frac{\sin\sqrt{x^2+y^2}}{\sqrt{x^2+y^2}}",  # LaTeX in, 3D sombrero out
+                         xlim=(-10, 10), ylim=(-10, 10))
+ggplot() + geom_vector_field("dx = y, dy = -sin(x) - 0.3y",                # a damped pendulum's
+                          xlim=(-6, 6), ylim=(-3, 3), stream=True)          # phase portrait
+```
+
+<p>
+<img src="https://raw.githubusercontent.com/rleyvasal/plot3/main/docs/img/fn_taylor.png" width="15%" alt="sin(x) and its Taylor polynomial">
+<img src="https://raw.githubusercontent.com/rleyvasal/plot3/main/docs/img/fn_heart.png" width="15%" alt="Implicit heart curve">
+<img src="https://raw.githubusercontent.com/rleyvasal/plot3/main/docs/img/fn_region.png" width="15%" alt="Shaded region y > x^2">
+<img src="https://raw.githubusercontent.com/rleyvasal/plot3/main/docs/img/fn_cardioid.png" width="15%" alt="Polar cardioid">
+<img src="https://raw.githubusercontent.com/rleyvasal/plot3/main/docs/img/fn_sombrero.png" width="15%" alt="3D sombrero surface">
+<img src="https://raw.githubusercontent.com/rleyvasal/plot3/main/docs/img/fn_streamlines.png" width="15%" alt="Streamlines of a damped pendulum">
+</p>
+
+**Probability and calculus, with the answer printed.** No SciPy needed:
+
+```python
+inf = float("inf")
+ggplot() + geom_function("y = dbeta(x, 2, 5)") + area(0.2, 0.5)          # labels P(0.2 ≤ X ≤ 0.5) = 0.546
+ggplot() + geom_function("y = dnorm(x)") + area(-inf, -1.96) + area(1.96, inf)
+ggplot() + geom_function("y = x^3 - 3x") + tangent(at=1) + derivative()
+```
+
+**Turn any coefficient into a slider or an animation:**
+
+```python
+ggplot() + geom_function("y = dbeta(x, a, b)") + slider(a=(0.5, 5), b=(0.5, 5))
+ggplot() + geom_function("y = sin(x - t)") + transition_time(t=(0, 6.28))   # travelling wave
+```
+
+Equations mix freely with data:
+`ggplot(df, aes(x="dose", y="response")) + geom_point() + geom_function("y = 2 + 0.6x")`.
+`^` is power and `2x` means `2*x`. All functions, densities, and rules are in
+the [reference](docs/reference.md#functions-and-maths).
+
+## Animate your data
+
+[gganimate](https://gganimate.com)'s grammar: add a transition and the plot
+plays. The viewer interpolates between frames in the browser, with play,
+pause, scrubbing, speed control, and one-click video export.
+
+```python notest
+import pandas as pd
+gapminder = pd.read_csv("https://raw.githubusercontent.com/kirenz/datasets/master/gapminder.csv")
+
+(ggplot(gapminder, aes(x="gdpPercap", y="lifeExp", size="pop", colour="continent", group="country"))
+ + geom_point(alpha=0.7)
+ + scale_x_log10()
+ + transition_time("year")
+ + labs(title="{frame_time}", x="GDP per capita", y="Life expectancy"))
+```
+
+`{frame_time}` in the title shows the current year as it plays.
+`transition_states("phase")` steps through categories instead of time.
+
+<details>
+<summary>Run this without downloading anything (made-up gapminder-shaped data)</summary>
+
+```python
+import pandas as pd
+
+countries = {"Brazil": "Americas", "China": "Asia", "Egypt": "Africa",
+             "France": "Europe", "India": "Asia", "Mexico": "Americas"}
+gapminder = pd.DataFrame([
+    {"country": country, "continent": continent, "year": year,
+     "gdpPercap": 800 * (1.03 + 0.01 * i) ** (year - 1952),
+     "lifeExp": 45 + 0.35 * (year - 1952) + 2 * i,
+     "pop": 2e7 * (1.02 + 0.002 * i) ** (year - 1952)}
+    for i, (country, continent) in enumerate(countries.items())
+    for year in range(1952, 2008, 5)
+])
+
+(ggplot(gapminder, aes(x="gdpPercap", y="lifeExp", size="pop", colour="continent", group="country"))
+ + geom_point() + scale_x_log10() + transition_time("year") + labs(title="{frame_time}"))
+```
+
+</details>
+
+## 3D and point clouds
+
+Map `z` and the plot becomes a 3D scene you can orbit, zoom, and hover.
+Hundreds of thousands of points stay smooth because they're drawn on the
+GPU.
+
+```python
+import numpy as np
+
+rng = np.random.default_rng(0)
+arm = rng.integers(0, 2, 20_000)
+r = rng.gamma(2, 1.2, 20_000)
+theta = r * 0.9 + arm * np.pi + rng.normal(0, 0.25, 20_000)
+galaxy = pd.DataFrame({"x": r * np.cos(theta), "y": r * np.sin(theta),
+                       "z": rng.normal(0, 0.15, 20_000), "r": r})
+
+(ggplot(galaxy, aes(x="x", y="y", z="z", colour="r"))
+ + geom_point3d(size=0.01) + scale_colour_viridis_c(option="magma")
+ + coord_3d(elev=40) + theme_lidar() + guides(colour="none"))
+```
+
+<p>
+<img src="https://raw.githubusercontent.com/rleyvasal/plot3/main/docs/img/galaxy.gif" width="32%" alt="A 20,000-point spiral galaxy, orbiting">
+<img src="https://raw.githubusercontent.com/rleyvasal/plot3/main/docs/img/peaks.png" width="32%" alt="The peaks surface coloured by height">
+<img src="https://raw.githubusercontent.com/rleyvasal/plot3/main/docs/img/isosurface.png" width="32%" alt="Nested density isosurfaces of three clusters">
+</p>
+
+Surfaces, isosurfaces, and self-driving scenes use the same grammar:
+
+```python notest
+ggplot(grid, aes(x="x", y="y", z="height", fill="height")) + geom_surface()
+ggplot(points, aes(x="x", y="y", z="z")) + geom_isosurface(levels=[0.2, 0.5, 0.8])
+
+(ggplot(sweep, aes(x="x", y="y", z="z"))                 # a nuScenes / KITTI lidar sweep
+ + geom_point3d()                                         # coloured by height, as lidar viewers do
+ + geom_box3d(aes(length="l", width="w", height="h", angle="yaw", colour="class"), data=boxes)
+ + coord_3d(azim=180, elev=28, zoom=1.6)                 # chase camera behind the car
+ + theme_lidar())
+```
+
+`read_bin("scan.pcd.bin")` loads nuScenes-style point clouds, and NumPy
+arrays work by column position: `aes(x=0, y=1, z=2, colour=3)`. Camera,
+aspect, and point-budget options are in the
+[reference](docs/reference.md#api-reference) under `coord_3d`.
+
+## One figure, two outputs
+
+The same object is an interactive figure in the notebook and a publication
+figure on disk, with real fonts, correct DPI metadata, and `theme_bw` by
+default.
+
+```python notest
+ggsave("fig1.pdf", p, width=3.5, height=2.6, units="in")         # vector, one journal column
+ggsave("fig1.png", p, width=7, height=4.5, units="in", dpi=300)   # two columns
+ggsave("fig1.html", p)                                            # interactive page to share
+```
+
+## It's ggplot2
+
+If you know ggplot2, you already know plot3: `+` layers, `aes()`, geoms,
+stats, scales, facets, themes, `labs()`, and patchwork's `|` and `/`, with
+ggplot2's names and defaults.
+
+```python
+rng = np.random.default_rng(1)
+trial = pd.DataFrame({"arm": rng.choice(["placebo", "low", "high"], 150),
+                      "dose": rng.uniform(0, 10, 150)})
+trial["response"] = 2 + 0.6 * trial.dose + 1.5 * (trial.arm == "high") + rng.normal(0, 1.2, 150)
+
+a = (ggplot(trial, aes(x="dose", y="response", colour="arm"))
+     + geom_point(alpha=0.7) + geom_smooth(method="lm"))
+b = (ggplot(trial, aes(x="arm", y="response", fill="arm"))
+     + geom_violin() + geom_jitter(width=0.1, height=0) + theme(legend_position="none"))
+fig = (a | b) + plot_annotation(title="Response by dose and arm", tag_levels="A")
+```
+
+<img src="https://raw.githubusercontent.com/rleyvasal/plot3/main/docs/img/ggplot2_compose.png" alt="Two-panel figure: scatter with linear fits, and violins by arm">
+
+Everything else you'd expect is there, including histograms, densities,
+boxplots, bar positions, `stat_summary`, error bars, heatmaps, hexbins, 2D
+densities, `facet_wrap` / `facet_grid`, Brewer, viridis, and Okabe–Ito
+scales, date axes, `theme()` with `element_*()`, and `coord_flip` /
+`coord_polar`. See the **[full reference](docs/reference.md)** for what
+plot3 supports and how it differs from ggplot2, or use the
+[ggplot2 docs](https://ggplot2.tidyverse.org/reference/) directly; the
+names match.
+
+In notebooks, bare column names work as in R: `aes(x=dose, y=response)`.
+
+## Notebooks, SolveIt, and CRAFT
+
+- **Jupyter / SolveIt**: bare column names and backticks work in `aes()`,
+  `facet_wrap()`, and `facet_grid()` (`aes(x=`First Name`)`). Toggle with
+  `enable_r_style()` / `disable_r_style()`. `.py` files keep quoted strings.
+- **SolveIt** draws figures inline and hides their HTML from the model's
+  context (`autohide(False)` to opt out).
+- **VS Code notebooks** block WebGL in output cells, so plot3 opens figures
+  in your browser (`PLOT3_DISPLAY=browser|iframe` to force a mode). The page
+  is written to `.plot3_preview/latest.html` in the notebook's folder, or to
+  the system temp folder when that folder is read-only.
+- **CRAFT / `%gpu`**: the same `ggplot(...)` code runs on the remote kernel;
+  stats run where the data lives and only a compact payload comes back.
+
+```text
+%run /path/to/plot3/plot3.py        # loads plot3 locally and seeds the GPU kernel
+%plot3 df x=wt y=mpg color=cyl       # optional shortcut magic
+```
+
+## Install
+
+```bash
+pip install "plot3[jupyter,export]"
+```
+
+Python 3.10 or newer; NumPy and pandas are the only required packages.
+
+| Extra | Adds |
+|---|---|
+| `export` | `cairosvg`: PNG with real fonts and PDF. Needs the Cairo C library (`brew install cairo`, `apt install libcairo2`). SVG needs nothing. |
+| `fast` | `contourpy`: faster implicit-curve contours (matplotlib users have it) |
+| `jupyter` | IPython integration (bare column names, `%plot3`) |
+| `polars` | Polars tables |
+
+The latest unreleased code installs from GitHub with
+`pip install "plot3[jupyter,export] @ git+https://github.com/rleyvasal/plot3"`.
+
+## Development
+
+```bash
+git clone https://github.com/rleyvasal/plot3 && cd plot3
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev,jupyter,export]"
+pytest -q                       # includes every example in this README and docs/reference.md
+python examples/showcase_2d.py  # 2D gallery in the browser
+python examples/showcase_3d.py  # 3D gallery
+```
+
+The code is in `plot3/`: `geoms.py` (grammar objects), `scaling.py`
+(scale functions), `build.py` (stats to a figure spec), `stat2d.py` and
+`flip.py` (statistical layers), `static.py` (PNG/SVG/PDF), `viewer.py` (the
+WebGL viewer), `expr.py` / `function.py` / `calculus.py` (formulas),
+`compose.py` (multi-panel figures). See [CHANGELOG.md](CHANGELOG.md) for
+changes between versions.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

plot3-0.5.1/README.md

@@ -0,0 +1,275 @@
+# plot3
+
+**ggplot2 for Python, plus what ggplot2 can't do: interactive 3D, animated
+data, and plots typed straight from an equation.** Figures render with WebGL
+in the notebook and save as journal-ready PNG, SVG, or PDF.
+
+<table>
+<tr>
+<td width="50%"><img src="https://raw.githubusercontent.com/rleyvasal/plot3/main/docs/img/gapminder.gif" alt="Gapminder: life expectancy against GDP per capita, animated from 1952 to 2007"></td>
+<td width="50%"><img src="https://raw.githubusercontent.com/rleyvasal/plot3/main/docs/img/lidar.gif" alt="A lidar driving scene with detection boxes, orbiting"></td>
+</tr>
+<tr>
+<td><sub><code>+ transition_time("year")</code>: gapminder in one line</sub></td>
+<td><sub><code>geom_point3d()</code> + <code>geom_box3d()</code>: a 220k-point lidar sweep with detection boxes</sub></td>
+</tr>
+<tr>
+<td><img src="https://raw.githubusercontent.com/rleyvasal/plot3/main/docs/img/ripple.gif" alt="An animated ripple surface z = sin(r - t)"></td>
+<td><img src="https://raw.githubusercontent.com/rleyvasal/plot3/main/docs/img/beta_slider.gif" alt="A beta density reshaping as two sliders move"></td>
+</tr>
+<tr>
+<td><sub><code>geom_function("z = sin(sqrt(x^2 + y^2) - t)") + transition_time(t=(0, 6.28))</code></sub></td>
+<td><sub><code>geom_function("y = dbeta(x, a, b)") + slider(a=…, b=…)</code></sub></td>
+</tr>
+</table>
+
+```bash
+pip install "plot3[jupyter,export]"
+```
+
+Contents: [Plot an equation](#plot-an-equation) ·
+[Animate your data](#animate-your-data) · [3D and point clouds](#3d-and-point-clouds) ·
+[One figure, two outputs](#one-figure-two-outputs) · [It's ggplot2](#its-ggplot2) ·
+[Notebooks, SolveIt, CRAFT](#notebooks-solveit-and-craft) · [Install](#install) ·
+[Full reference](docs/reference.md)
+
+## Plot an equation
+
+Write the maths as you would on paper. `geom_function` works out whether
+it's a curve, an implicit shape, a region, or a 3D surface, and picks a
+sensible window.
+
+```python
+from plot3 import *
+
+(ggplot() + geom_function("y = sin(x)", xlim=(-4, 4))                        # a function and
+ + geom_function("y = x - x^3/6", xlim=(-4, 4)))                            # its Taylor polynomial
+ggplot() + geom_function("(x^2 + y^2 - 1)^3 = x^2 y^3")                     # implicit: a heart
+ggplot() + geom_function("y > x^2", xlim=(-2, 2))                           # shaded region
+ggplot() + geom_function("r = 1 + cos(theta)") + coord_polar()              # polar cardioid
+ggplot() + geom_function(r"z = \frac{\sin\sqrt{x^2+y^2}}{\sqrt{x^2+y^2}}",  # LaTeX in, 3D sombrero out
+                         xlim=(-10, 10), ylim=(-10, 10))
+ggplot() + geom_vector_field("dx = y, dy = -sin(x) - 0.3y",                # a damped pendulum's
+                          xlim=(-6, 6), ylim=(-3, 3), stream=True)          # phase portrait
+```
+
+<p>
+<img src="https://raw.githubusercontent.com/rleyvasal/plot3/main/docs/img/fn_taylor.png" width="15%" alt="sin(x) and its Taylor polynomial">
+<img src="https://raw.githubusercontent.com/rleyvasal/plot3/main/docs/img/fn_heart.png" width="15%" alt="Implicit heart curve">
+<img src="https://raw.githubusercontent.com/rleyvasal/plot3/main/docs/img/fn_region.png" width="15%" alt="Shaded region y > x^2">
+<img src="https://raw.githubusercontent.com/rleyvasal/plot3/main/docs/img/fn_cardioid.png" width="15%" alt="Polar cardioid">
+<img src="https://raw.githubusercontent.com/rleyvasal/plot3/main/docs/img/fn_sombrero.png" width="15%" alt="3D sombrero surface">
+<img src="https://raw.githubusercontent.com/rleyvasal/plot3/main/docs/img/fn_streamlines.png" width="15%" alt="Streamlines of a damped pendulum">
+</p>
+
+**Probability and calculus, with the answer printed.** No SciPy needed:
+
+```python
+inf = float("inf")
+ggplot() + geom_function("y = dbeta(x, 2, 5)") + area(0.2, 0.5)          # labels P(0.2 ≤ X ≤ 0.5) = 0.546
+ggplot() + geom_function("y = dnorm(x)") + area(-inf, -1.96) + area(1.96, inf)
+ggplot() + geom_function("y = x^3 - 3x") + tangent(at=1) + derivative()
+```
+
+**Turn any coefficient into a slider or an animation:**
+
+```python
+ggplot() + geom_function("y = dbeta(x, a, b)") + slider(a=(0.5, 5), b=(0.5, 5))
+ggplot() + geom_function("y = sin(x - t)") + transition_time(t=(0, 6.28))   # travelling wave
+```
+
+Equations mix freely with data:
+`ggplot(df, aes(x="dose", y="response")) + geom_point() + geom_function("y = 2 + 0.6x")`.
+`^` is power and `2x` means `2*x`. All functions, densities, and rules are in
+the [reference](docs/reference.md#functions-and-maths).
+
+## Animate your data
+
+[gganimate](https://gganimate.com)'s grammar: add a transition and the plot
+plays. The viewer interpolates between frames in the browser, with play,
+pause, scrubbing, speed control, and one-click video export.
+
+```python notest
+import pandas as pd
+gapminder = pd.read_csv("https://raw.githubusercontent.com/kirenz/datasets/master/gapminder.csv")
+
+(ggplot(gapminder, aes(x="gdpPercap", y="lifeExp", size="pop", colour="continent", group="country"))
+ + geom_point(alpha=0.7)
+ + scale_x_log10()
+ + transition_time("year")
+ + labs(title="{frame_time}", x="GDP per capita", y="Life expectancy"))
+```
+
+`{frame_time}` in the title shows the current year as it plays.
+`transition_states("phase")` steps through categories instead of time.
+
+<details>
+<summary>Run this without downloading anything (made-up gapminder-shaped data)</summary>
+
+```python
+import pandas as pd
+
+countries = {"Brazil": "Americas", "China": "Asia", "Egypt": "Africa",
+             "France": "Europe", "India": "Asia", "Mexico": "Americas"}
+gapminder = pd.DataFrame([
+    {"country": country, "continent": continent, "year": year,
+     "gdpPercap": 800 * (1.03 + 0.01 * i) ** (year - 1952),
+     "lifeExp": 45 + 0.35 * (year - 1952) + 2 * i,
+     "pop": 2e7 * (1.02 + 0.002 * i) ** (year - 1952)}
+    for i, (country, continent) in enumerate(countries.items())
+    for year in range(1952, 2008, 5)
+])
+
+(ggplot(gapminder, aes(x="gdpPercap", y="lifeExp", size="pop", colour="continent", group="country"))
+ + geom_point() + scale_x_log10() + transition_time("year") + labs(title="{frame_time}"))
+```
+
+</details>
+
+## 3D and point clouds
+
+Map `z` and the plot becomes a 3D scene you can orbit, zoom, and hover.
+Hundreds of thousands of points stay smooth because they're drawn on the
+GPU.
+
+```python
+import numpy as np
+
+rng = np.random.default_rng(0)
+arm = rng.integers(0, 2, 20_000)
+r = rng.gamma(2, 1.2, 20_000)
+theta = r * 0.9 + arm * np.pi + rng.normal(0, 0.25, 20_000)
+galaxy = pd.DataFrame({"x": r * np.cos(theta), "y": r * np.sin(theta),
+                       "z": rng.normal(0, 0.15, 20_000), "r": r})
+
+(ggplot(galaxy, aes(x="x", y="y", z="z", colour="r"))
+ + geom_point3d(size=0.01) + scale_colour_viridis_c(option="magma")
+ + coord_3d(elev=40) + theme_lidar() + guides(colour="none"))
+```
+
+<p>
+<img src="https://raw.githubusercontent.com/rleyvasal/plot3/main/docs/img/galaxy.gif" width="32%" alt="A 20,000-point spiral galaxy, orbiting">
+<img src="https://raw.githubusercontent.com/rleyvasal/plot3/main/docs/img/peaks.png" width="32%" alt="The peaks surface coloured by height">
+<img src="https://raw.githubusercontent.com/rleyvasal/plot3/main/docs/img/isosurface.png" width="32%" alt="Nested density isosurfaces of three clusters">
+</p>
+
+Surfaces, isosurfaces, and self-driving scenes use the same grammar:
+
+```python notest
+ggplot(grid, aes(x="x", y="y", z="height", fill="height")) + geom_surface()
+ggplot(points, aes(x="x", y="y", z="z")) + geom_isosurface(levels=[0.2, 0.5, 0.8])
+
+(ggplot(sweep, aes(x="x", y="y", z="z"))                 # a nuScenes / KITTI lidar sweep
+ + geom_point3d()                                         # coloured by height, as lidar viewers do
+ + geom_box3d(aes(length="l", width="w", height="h", angle="yaw", colour="class"), data=boxes)
+ + coord_3d(azim=180, elev=28, zoom=1.6)                 # chase camera behind the car
+ + theme_lidar())
+```
+
+`read_bin("scan.pcd.bin")` loads nuScenes-style point clouds, and NumPy
+arrays work by column position: `aes(x=0, y=1, z=2, colour=3)`. Camera,
+aspect, and point-budget options are in the
+[reference](docs/reference.md#api-reference) under `coord_3d`.
+
+## One figure, two outputs
+
+The same object is an interactive figure in the notebook and a publication
+figure on disk, with real fonts, correct DPI metadata, and `theme_bw` by
+default.
+
+```python notest
+ggsave("fig1.pdf", p, width=3.5, height=2.6, units="in")         # vector, one journal column
+ggsave("fig1.png", p, width=7, height=4.5, units="in", dpi=300)   # two columns
+ggsave("fig1.html", p)                                            # interactive page to share
+```
+
+## It's ggplot2
+
+If you know ggplot2, you already know plot3: `+` layers, `aes()`, geoms,
+stats, scales, facets, themes, `labs()`, and patchwork's `|` and `/`, with
+ggplot2's names and defaults.
+
+```python
+rng = np.random.default_rng(1)
+trial = pd.DataFrame({"arm": rng.choice(["placebo", "low", "high"], 150),
+                      "dose": rng.uniform(0, 10, 150)})
+trial["response"] = 2 + 0.6 * trial.dose + 1.5 * (trial.arm == "high") + rng.normal(0, 1.2, 150)
+
+a = (ggplot(trial, aes(x="dose", y="response", colour="arm"))
+     + geom_point(alpha=0.7) + geom_smooth(method="lm"))
+b = (ggplot(trial, aes(x="arm", y="response", fill="arm"))
+     + geom_violin() + geom_jitter(width=0.1, height=0) + theme(legend_position="none"))
+fig = (a | b) + plot_annotation(title="Response by dose and arm", tag_levels="A")
+```
+
+<img src="https://raw.githubusercontent.com/rleyvasal/plot3/main/docs/img/ggplot2_compose.png" alt="Two-panel figure: scatter with linear fits, and violins by arm">
+
+Everything else you'd expect is there, including histograms, densities,
+boxplots, bar positions, `stat_summary`, error bars, heatmaps, hexbins, 2D
+densities, `facet_wrap` / `facet_grid`, Brewer, viridis, and Okabe–Ito
+scales, date axes, `theme()` with `element_*()`, and `coord_flip` /
+`coord_polar`. See the **[full reference](docs/reference.md)** for what
+plot3 supports and how it differs from ggplot2, or use the
+[ggplot2 docs](https://ggplot2.tidyverse.org/reference/) directly; the
+names match.
+
+In notebooks, bare column names work as in R: `aes(x=dose, y=response)`.
+
+## Notebooks, SolveIt, and CRAFT
+
+- **Jupyter / SolveIt**: bare column names and backticks work in `aes()`,
+  `facet_wrap()`, and `facet_grid()` (`aes(x=`First Name`)`). Toggle with
+  `enable_r_style()` / `disable_r_style()`. `.py` files keep quoted strings.
+- **SolveIt** draws figures inline and hides their HTML from the model's
+  context (`autohide(False)` to opt out).
+- **VS Code notebooks** block WebGL in output cells, so plot3 opens figures
+  in your browser (`PLOT3_DISPLAY=browser|iframe` to force a mode). The page
+  is written to `.plot3_preview/latest.html` in the notebook's folder, or to
+  the system temp folder when that folder is read-only.
+- **CRAFT / `%gpu`**: the same `ggplot(...)` code runs on the remote kernel;
+  stats run where the data lives and only a compact payload comes back.
+
+```text
+%run /path/to/plot3/plot3.py        # loads plot3 locally and seeds the GPU kernel
+%plot3 df x=wt y=mpg color=cyl       # optional shortcut magic
+```
+
+## Install
+
+```bash
+pip install "plot3[jupyter,export]"
+```
+
+Python 3.10 or newer; NumPy and pandas are the only required packages.
+
+| Extra | Adds |
+|---|---|
+| `export` | `cairosvg`: PNG with real fonts and PDF. Needs the Cairo C library (`brew install cairo`, `apt install libcairo2`). SVG needs nothing. |
+| `fast` | `contourpy`: faster implicit-curve contours (matplotlib users have it) |
+| `jupyter` | IPython integration (bare column names, `%plot3`) |
+| `polars` | Polars tables |
+
+The latest unreleased code installs from GitHub with
+`pip install "plot3[jupyter,export] @ git+https://github.com/rleyvasal/plot3"`.
+
+## Development
+
+```bash
+git clone https://github.com/rleyvasal/plot3 && cd plot3
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev,jupyter,export]"
+pytest -q                       # includes every example in this README and docs/reference.md
+python examples/showcase_2d.py  # 2D gallery in the browser
+python examples/showcase_3d.py  # 3D gallery
+```
+
+The code is in `plot3/`: `geoms.py` (grammar objects), `scaling.py`
+(scale functions), `build.py` (stats to a figure spec), `stat2d.py` and
+`flip.py` (statistical layers), `static.py` (PNG/SVG/PDF), `viewer.py` (the
+WebGL viewer), `expr.py` / `function.py` / `calculus.py` (formulas),
+`compose.py` (multi-panel figures). See [CHANGELOG.md](CHANGELOG.md) for
+changes between versions.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

plot3-0.5.1/plot3/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.5.1"

{plot3-0.4.2 → plot3-0.5.1}/plot3/build.py

@@ -440,6 +440,22 @@ def _apply_fill(mapping: dict, kind: str) -> dict:
     return out
 
 
+def _layer_mapping(base_mapping, geom) -> dict:
+    """The plot's mapping with the layer's own on top, fill resolved per side.
+
+    A set colour (``geom_point(colour="black")`` under ``aes(colour=g)``)
+    replaces the inherited colour mapping for that layer, as in ggplot2, so
+    the layer neither recolours nor needs the column. Filled layers keep
+    it: there ``colour=`` is the outline.
+    """
+    kind = getattr(geom, "kind", None)
+    mapping = _apply_fill(dict(base_mapping), kind)
+    if getattr(geom, "const_color", None) is not None and kind not in _FILL_KINDS:
+        mapping.pop("color", None)
+    mapping.update(_apply_fill(dict(geom.mapping), kind))
+    return mapping
+
+
 _REF_KINDS = frozenset({"hline", "vline", "abline"})
 _MM_TO_PX = 96.0 / 25.4
 
@@ -571,8 +587,7 @@ def expand_stat_geom(
         layers = expand_vector_field(geom, transition, slider)
         return layers[0] if len(layers) == 1 else layers
     # Resolve fill per mapping, so a layer's own colour beats a base fill.
-    mapping = _apply_fill(dict(base_mapping), geom.kind)
-    mapping.update(_apply_fill(dict(geom.mapping), geom.kind))
+    mapping = _layer_mapping(base_mapping, geom)
     if geom.kind == "box3d":
         from plot3.stats3d import box3d_layers
 
@@ -976,8 +991,8 @@ def expand_stat_geom(
             indices = np.zeros((0, 3), dtype=np.int32)
         colour_by = getattr(geom, "colour_by", "level")
         map_kwargs: dict = {"x": "x", "y": "y", "z": "z"}
-        if colour_by == "level" and "colour" in vertices.columns:
-            map_kwargs["colour"] = "colour"
+        if colour_by == "level" and "level" in vertices.columns:
+            map_kwargs["colour"] = "level"
         out = _Geom(
             aes(**map_kwargs),
             color=geom.const_color,
@@ -990,6 +1005,7 @@ def expand_stat_geom(
         out.wireframe = bool(getattr(geom, "wireframe", False))
         out._indices = indices
         out._iso_levels = used
+        out._colour_title = "level"
         return out
     return geom
 
@@ -1963,8 +1979,7 @@ def build_spec(g: ggplot) -> tuple[dict, list[tuple[str, str]]]:
         if getattr(geom, "_replace_mapping", False):
             m = dict(geom.mapping)
         else:
-            m = _apply_fill(dict(g.mapping), geom.kind)
-            m.update(_apply_fill(dict(geom.mapping), geom.kind))
+            m = _layer_mapping(g.mapping, geom)
         if "x" not in m or "y" not in m:
             raise ValueError("aes(x=, y=) are required (bar/histogram/density supply y)")
         if geom.kind == "surface" and "z" not in m: