plot3 0.5.0__tar.gz → 0.6.0__tar.gz

{plot3-0.5.0 → plot3-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plot3
-Version: 0.5.0
+Version: 0.6.0
 Summary: ggplot2 grammar of graphics for Python: interactive WebGL figures and journal-ready PNG, SVG, and PDF
 Author: Rigoberto Leyva Salmeron
 License-Expression: MIT

plot3-0.6.0/plot3/__version__.py

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

{plot3-0.5.0 → plot3-0.6.0}/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
 
@@ -1964,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:
@@ -3717,7 +3731,13 @@ def facet_cells(g: ggplot) -> dict:
     facet = g.facet
     if g.data is None:
         raise ValueError("ggplot has no data")
-    force = _global_numeric_domains(g) if facet.scales == "fixed" else {}
+    # ggplot2: "fixed" shares every axis, "free" none, "free_x" / "free_y"
+    # all but that one.
+    freed = {"fixed": set(), "free_x": {"x"}, "free_y": {"y"}}.get(facet.scales)
+    force = (
+        {ax: dom for ax, dom in _global_numeric_domains(g).items() if ax not in freed}
+        if freed is not None else {}
+    )
     colour_levels = _facet_colour_levels(g)
 
     def child(panel):
@@ -3731,6 +3751,9 @@ def facet_cells(g: ggplot) -> dict:
     header = {
         key: g.labs.get(key) for key in ("title", "subtitle", "caption", "tag") if g.labs.get(key)
     }
+    # Panels hide their own legends; the figure draws one unless
+    # theme(legend_position="none") asks for none.
+    legend = _legend_position_spec(getattr(g, "legend_position", None))
     cells: list[dict] = []
     if not isinstance(facet, _facet_grid):
         column = facet.variable
@@ -3750,7 +3773,8 @@ def facet_cells(g: ggplot) -> dict:
             row, col = divmod(index, ncol)
             cells.append({"row": row, "col": col, "fig": panel, "strip": label})
         return {"ncol": ncol, "nrow": nrow, "cells": cells, "col_strips": None,
-                "row_strips": None, "header": header, "kind": "wrap"}
+                "row_strips": None, "header": header, "kind": "wrap",
+                "legend": legend}
 
     for column in (facet.rows, facet.cols):
         if column is not None and not has_column(g.data, column):
@@ -3779,6 +3803,7 @@ def facet_cells(g: ggplot) -> dict:
         "row_strips": [_strip_text(facet, facet.rows, v) for v in row_levels] if facet.rows else None,
         "header": header,
         "kind": "grid",
+        "legend": legend,
     }
 
 
@@ -3860,7 +3885,7 @@ def _build_doc_faceted(g: ggplot, facet) -> str:
     first_spec, _pairs = build_spec(first)
     shared_x = str((first_spec.get("labs") or {}).get("x") or "")
     shared_y = str((first_spec.get("labs") or {}).get("y") or "")
-    legend_html = _facet_legend_html(first_spec, theme)
+    legend_html = "" if layout.get("legend") == "none" else _facet_legend_html(first_spec, theme)
     cells: list[str] = []
     total_kb = 0
     count = 0

{plot3-0.5.0 → plot3-0.6.0}/plot3/geoms.py

@@ -1184,13 +1184,14 @@ class geom_smooth(_Geom):
     ``method="loess"`` (default, local quadratic with ``span``) or ``"lm"``
     (a straight line). ``se=True`` shades the ``level`` confidence band,
     using Student's t like R. ``aes(colour=)`` fits each group.
+    ``linetype`` dashes the fitted line (``"dashed"``, ``"dotted"``, …).
     """
 
     kind = "smooth"
 
     def __init__(
         self, mapping=None, *, method="loess", se=True, level=0.95,
-        span=0.75, n=80, linewidth=2.0, **kw,
+        span=0.75, n=80, linewidth=2.0, linetype=None, **kw,
     ):
         super().__init__(mapping, **kw)
         self.method = method
@@ -1199,6 +1200,8 @@ class geom_smooth(_Geom):
         self.span = float(span)
         self.n = int(n)
         self.linewidth = float(linewidth)
+        dash_pattern(linetype)
+        self.linetype = linetype
 
 
 class stat_summary(_Geom):
@@ -1751,6 +1754,14 @@ class geom_violin(_Geom):
         self.linewidth = float(linewidth)
 
 
+_FACET_SCALES = ("fixed", "free", "free_x", "free_y")
+
+
+def _check_facet_scales(scales) -> None:
+    if scales not in _FACET_SCALES:
+        raise ValueError("scales must be 'fixed', 'free', 'free_x', or 'free_y'")
+
+
 class facet_wrap:
     """Wrap panels by a discrete column (ggplot2 ``facet_wrap``).
 
@@ -1762,7 +1773,8 @@ class facet_wrap:
         Panel grid size. If both are omitted, the grid is ggplot2's: 3 panels
         in a row, 4 in 2 x 2, 5 or 6 in 2 rows of 3, 7 to 9 in 3 x 3.
     scales:
-        ``"fixed"`` (shared domains across panels) or ``"free"`` (per-panel).
+        ``"fixed"`` (shared domains across panels), ``"free"`` (per-panel),
+        or ``"free_x"`` / ``"free_y"`` (only that axis per-panel).
     """
 
     def __init__(
@@ -1792,8 +1804,7 @@ class facet_wrap:
                     f"(got {facets!r})"
                 )
             name = candidates[0]
-        if scales not in {"fixed", "free"}:
-            raise ValueError("scales must be 'fixed' or 'free'")
+        _check_facet_scales(scales)
         if ncol is not None and ncol < 1:
             raise ValueError("ncol must be positive")
         if nrow is not None and nrow < 1:
@@ -1812,7 +1823,8 @@ class facet_grid:
     ``facet_grid(rows="sex", cols="day")`` or the formula ``"sex ~ day"``
     (``". ~ day"`` for columns only). Column labels sit above the top row and
     row labels to the right, as in ggplot2. ``scales="fixed"`` (default)
-    shares axes across panels; ``"free"`` lets each panel fit its data.
+    shares axes across panels; ``"free"`` lets each panel fit its data, and
+    ``"free_x"`` / ``"free_y"`` free one axis only.
     """
 
     def __init__(self, facets: str | None = None, *, rows=None, cols=None, scales: str = "fixed",
@@ -1839,8 +1851,7 @@ class facet_grid:
         cols = _as_column_name(cols) if cols is not None else None
         if rows is None and cols is None:
             raise ValueError("facet_grid() needs rows=, cols=, or both")
-        if scales not in {"fixed", "free"}:
-            raise ValueError("scales must be 'fixed' or 'free'")
+        _check_facet_scales(scales)
         self.rows = rows
         self.cols = cols
         self.scales = scales

{plot3-0.5.0 → plot3-0.6.0}/plot3/masking.py

@@ -263,6 +263,30 @@ class Plot3MaskTransformer(ast.NodeTransformer):
     def _mask_selector(self, node: ast.AST) -> ast.AST:
         return MaskSelectors(self._known()).visit(node)
 
+    def _mask_aes_value(self, node: ast.AST) -> ast.AST:
+        """``colour = factor(cyl)`` → ``colour = "factor(cyl)"``.
+
+        aes() reads expressions over columns as strings (``"log10(pop)"``,
+        ``"dose > 5"``). An expression whose bare names are all columns is
+        passed whole; quoting each name (``factor("cyl")``) breaks it.
+        Expressions over notebook variables or modules are left alone.
+        """
+        if isinstance(node, (ast.Name, ast.Constant)) or _is_bt_call(node):
+            return self._mask_selector(node)
+        known = self._known()
+        called = {
+            id(call.func) for call in ast.walk(node)
+            if isinstance(call, ast.Call) and isinstance(call.func, ast.Name)
+        }
+        names = [
+            item for item in ast.walk(node)
+            if isinstance(item, ast.Name) and id(item) not in called
+        ]
+        backticks = any(_is_bt_call(item) for item in ast.walk(node))
+        if names and not backticks and all(item.id not in known for item in names):
+            return ast.copy_location(ast.Constant(value=ast.unparse(node)), node)
+        return self._mask_selector(node)
+
     def visit_Call(self, node: ast.Call) -> ast.AST:
         # Always recurse so nested aes(...) inside geom_point(aes(...)) is seen.
         if not isinstance(node.func, ast.Name):
@@ -276,9 +300,9 @@ class Plot3MaskTransformer(ast.NodeTransformer):
 
         if name == "aes":
             # All positional + keyword values are column selectors.
-            node.args = [self._mask_selector(a) for a in node.args]
+            node.args = [self._mask_aes_value(a) for a in node.args]
             node.keywords = [
-                ast.keyword(arg=kw.arg, value=self._mask_selector(kw.value))
+                ast.keyword(arg=kw.arg, value=self._mask_aes_value(kw.value))
                 for kw in node.keywords
             ]
             return node

{plot3-0.5.0 → plot3-0.6.0}/plot3/stat2d.py

@@ -609,6 +609,7 @@ def smooth(geom: _Geom, mapping: dict, data: Any):
     curve = _layer(
         "line", pd.concat(lines, ignore_index=True), line_map, geom,
         _groups=starts, linewidth=float(getattr(geom, "linewidth", 2.0) or 2.0),
+        linetype=getattr(geom, "linetype", None),
     )
     _title(curve, "y", ycol)
     _title(curve, "x", xcol)

{plot3-0.5.0 → plot3-0.6.0}/plot3/static.py

@@ -659,7 +659,7 @@ def _draw_facets(panels, layout, first_spec, theme, width, height, base_pt, comm
     # One legend for the figure, from the first panel (colour levels are
     # shared, so every panel has the same keys).
     legend_spec = dict(first_spec, legendPosition="right")
-    metrics = _legend_metrics(
+    metrics = None if layout.get("legend") == "none" else _legend_metrics(
         legend_spec, theme, fonts, raw_labs.get("color") or "",
         max_box=(width * 0.3, height - head - foot),
     )

{plot3-0.5.0 → plot3-0.6.0}/plot3.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plot3
-Version: 0.5.0
+Version: 0.6.0
 Summary: ggplot2 grammar of graphics for Python: interactive WebGL figures and journal-ready PNG, SVG, and PDF
 Author: Rigoberto Leyva Salmeron
 License-Expression: MIT

{plot3-0.5.0 → plot3-0.6.0}/tests/test_facets_compose.py

@@ -163,3 +163,49 @@ def test_composition_saves_static_and_html(tmp_path, plots):
     assert doc.count("<iframe") == 3
     assert "Overview" in doc
     assert re.search(r"flex-direction:row", doc) and re.search(r"flex-direction:column", doc)
+
+
+def _facet_frame():
+    import pandas as pd
+
+    return pd.DataFrame({
+        "g": ["a"] * 3 + ["b"] * 3,
+        "x": [1, 2, 3, 10, 20, 30],
+        "y": [1.0, 2.0, 3.0, 100.0, 200.0, 300.0],
+    })
+
+
+def test_facet_free_y_frees_only_y():
+    from plot3 import aes, facet_wrap, geom_point, ggplot
+    from plot3.build import facet_cells
+
+    layout = facet_cells(ggplot(_facet_frame(), aes(x="x", y="y")) + geom_point() + facet_wrap("g", scales="free_y"))
+    forced = [cell["fig"]._force_scales for cell in layout["cells"]]
+    assert all(set(f) == {"x"} and f["x"] == (1.0, 30.0) for f in forced)
+    layout = facet_cells(ggplot(_facet_frame(), aes(x="x", y="y")) + geom_point() + facet_wrap("g", scales="free_x"))
+    assert all(set(cell["fig"]._force_scales) == {"y"} for cell in layout["cells"])
+
+
+def test_facet_scales_rejects_unknown_values():
+    import pytest
+
+    from plot3 import facet_grid, facet_wrap
+
+    with pytest.raises(ValueError, match="free_y"):
+        facet_wrap("g", scales="loose")
+    facet_grid("g ~ .", scales="free_x")
+
+
+def test_facet_legend_position_none_hides_the_figure_legend(tmp_path):
+    from plot3 import aes, facet_wrap, geom_point, ggplot, ggsave, theme
+    from plot3.build import build_doc
+
+    p = (ggplot(_facet_frame(), aes(x="x", y="y", colour="g")) + geom_point()
+         + facet_wrap("g") + theme(legend_position="none"))
+    assert "id='flegend'" not in build_doc(p)
+    out = tmp_path / "f.svg"
+    ggsave(str(out), p)
+    assert ">a<" in out.read_text()  # strip label
+    shown = tmp_path / "shown.svg"
+    ggsave(str(shown), ggplot(_facet_frame(), aes(x="x", y="y", colour="g")) + geom_point() + facet_wrap("g"))
+    assert shown.read_text().count(">a<") > out.read_text().count(">a<")  # legend key too

{plot3-0.5.0 → plot3-0.6.0}/tests/test_grammar.py

@@ -97,3 +97,41 @@ def test_scale_colour_viridis_on_points(cloud):
 def test_unknown_add_raises(cars):
     with pytest.raises(TypeError, match="cannot add"):
         _ = ggplot(cars, aes(x="wt", y="mpg")) + 123
+
+
+def test_set_colour_replaces_inherited_colour_mapping():
+    # ggplot2: geom_point(colour = "black") under aes(colour = g) draws black,
+    # and the layer's own data need not have g.
+    import pandas as pd
+
+    from plot3 import aes, geom_boxplot, geom_point, ggplot
+    from plot3.build import build_spec
+
+    df = pd.DataFrame({"x": [1, 2, 3], "y": [1, 2, 3], "g": ["a", "b", "c"]})
+    centre = pd.DataFrame({"x": [2], "y": [2]})
+    spec, _ = build_spec(
+        ggplot(df, aes(x="x", y="y", colour="g")) + geom_point()
+        + geom_point(data=centre, colour="black", shape="cross")
+    )
+    assert spec["layers"][0].get("color") is not None
+    assert spec["layers"][1].get("color") is None
+    assert spec["layers"][1]["constColor"] == "#000000"
+    # A filled layer keeps its mapped fill under a set outline colour.
+    spec, _ = build_spec(
+        ggplot(df, aes(x="g", y="y", fill="g")) + geom_boxplot(colour="black")
+    )
+    assert spec["layers"][0].get("color") is not None
+
+
+def test_geom_smooth_takes_a_linetype():
+    import pandas as pd
+    import pytest
+
+    from plot3 import aes, geom_smooth, ggplot
+    from plot3.build import build_spec
+
+    df = pd.DataFrame({"x": [1, 2, 3, 4], "y": [1.0, 2.5, 2.9, 4.2]})
+    spec, _ = build_spec(ggplot(df, aes(x="x", y="y")) + geom_smooth(method="lm", se=False, linetype="dashed"))
+    assert [layer.get("dash") for layer in spec["layers"] if layer["kind"] == "line"] == [[4.0, 4.0]]
+    with pytest.raises(ValueError):
+        geom_smooth(linetype="wavy")

{plot3-0.5.0 → plot3-0.6.0}/tests/test_masking.py

@@ -183,3 +183,17 @@ def test_facet_wrap_masked_end_to_end(cars):
     fig = ggplot(cars, aes(x="wt", y="mpg")) + geom_point() + fac
     html = fig._repr_html_()
     assert "iframe" in html or "three" in html.lower() or len(html) > 100
+
+
+def test_aes_expression_over_columns_passes_whole():
+    # aes(colour = factor(cyl)) in a notebook: aes() reads "factor(cyl)";
+    # quoting each name (factor("cyl")) would break it.
+    from plot3.masking import apply_masking, default_known_names
+
+    known = default_known_names({"np", "scale"})
+    assert apply_masking("aes(colour=factor(cyl))", known=known) == "aes(colour='factor(cyl)')"
+    assert apply_masking("aes(x=log10(pop), y=lifeExp)", known=known) == "aes(x='log10(pop)', y='lifeExp')"
+    assert apply_masking("aes(colour=cyl > 4)", known=known) == "aes(colour='cyl > 4')"
+    # Notebook variables and modules keep the old behaviour.
+    assert apply_masking("aes(x=np.log(x))", known=known) == "aes(x=np.log('x'))"
+    assert apply_masking("aes(x=wt)", known=known) == "aes(x='wt')"

plot3-0.5.0/plot3/__version__.py

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