plotjs 0.0.6__py3-none-any.whl

plotjs/javascript.py

@@ -0,0 +1,23 @@
+def from_file(javascript_file: str) -> str:
+    """
+    Get raw javascript from a javascript file.
+    This function just reads the js from a given
+    file.
+
+    Args:
+        javascript_file: Path to a js file.
+
+    Returns:
+        A string of raw javascript.
+
+    Examples:
+        ```python
+        from plotjs import javascript
+
+        javascript.from_file("path/to/script.js")
+        ```
+    """
+    with open(javascript_file, "r") as f:
+        js: str = f.read()
+
+    return js

plotjs/main.py

@@ -0,0 +1,359 @@
+import os
+import io
+import random
+import uuid
+from typing import Optional
+
+import numpy as np
+from pathlib import Path
+from jinja2 import Environment, FileSystemLoader
+from narwhals.typing import SeriesT
+import matplotlib.pyplot as plt
+from matplotlib.figure import Figure
+from matplotlib.axes import Axes
+
+from plotjs.utils import _vector_to_list, _get_and_sanitize_js
+from plotjs import css, javascript
+
+MAIN_DIR: str = Path(__file__).parent
+TEMPLATE_DIR: str = MAIN_DIR / "static"
+CSS_PATH: str = os.path.join(TEMPLATE_DIR, "default.css")
+JS_PARSER_PATH: str = os.path.join(TEMPLATE_DIR, "plotparser.js")
+
+env: Environment = Environment(loader=FileSystemLoader(str(TEMPLATE_DIR)))
+
+
+class PlotJS:
+    """
+    Class to convert static matplotlib plots to interactive charts.
+
+    Attributes:
+        - additional_css: All the CSS added via `add_css()`
+        - additional_javascript: All the JavaScript added via `add_javascript()`
+    """
+
+    def __init__(
+        self,
+        fig: Figure | None = None,
+        **savefig_kws: dict,
+    ):
+        """
+        Initiate an `PlotJS` instance to convert matplotlib
+        figures to interactive charts.
+
+        Args:
+            fig: An optional matplotlib figure. If None, uses `plt.gcf()`.
+            savefig_kws: Additional keyword arguments passed to `plt.savefig()`.
+        """
+        if fig is None:
+            fig: Figure = plt.gcf()
+        buf: io.StringIO = io.StringIO()
+
+        # temporary change svg hashsalt and id for reproductibility
+        # https://matplotlib.org/stable/users/explain/customizing.html#the-default-matplotlibrc-file
+        plt.rcParams["svg.hashsalt"] = "svg-hashsalt"
+        plt.rcParams["svg.id"] = "svg-id"
+        fig.savefig(buf, format="svg", **savefig_kws)
+        plt.rcParams["svg.hashsalt"] = None
+        plt.rcParams["svg.id"] = None
+
+        buf.seek(0)
+        self._svg_content = buf.getvalue()
+
+        self._axes: list[Axes] = fig.get_axes()
+
+        self.additional_css = ""
+        self.additional_javascript = ""
+        self._hover_nearest = False
+        self._template = env.get_template("template.html")
+
+        with open(CSS_PATH) as f:
+            self._default_css = f.read()
+
+        self._js_parser = _get_and_sanitize_js(
+            file_path=JS_PARSER_PATH,
+            after_pattern=r"class PlotSVGParser.*",
+        )
+
+        rnd = random.Random(22022001)
+        self._uuid = uuid.UUID(int=rnd.getrandbits(128))
+
+    def add_tooltip(
+        self,
+        *,
+        labels: list | tuple | np.ndarray | SeriesT | None = None,
+        groups: list | tuple | np.ndarray | SeriesT | None = None,
+        tooltip_x_shift: int = 0,
+        tooltip_y_shift: int = 0,
+        hover_nearest: bool = False,
+        ax: Axes | None = None,
+    ) -> "PlotJS":
+        """
+        Add a tooltip to the interactive plot. You can set either
+        just `labels`, just `groups`, both or none.
+
+        Args:
+            labels: An iterable containing the labels for the tooltip.
+                It corresponds to the text that will appear on hover.
+            groups: An iterable containing the group for tooltip. It
+                corresponds to how to 'group' the tooltip. The easiest
+                way to understand this argument is to check the examples
+                below. Also note that the use of this argument is required
+                to 'connect' the legend with plot elements.
+            tooltip_x_shift: Number of pixels to shift the tooltip from
+                the cursor, on the x axis.
+            tooltip_y_shift: Number of pixels to shift the tooltip from
+                the cursor, on the y axis.
+            hover_nearest: When `True`, hover the nearest plot element.
+            ax: A matplotlib Axes. If `None` (default), uses first Axes.
+
+        Returns:
+            self: Returns the instance to allow method chaining.
+
+        Examples:
+            ```python
+            PlotJS(...).add_tooltip(
+                labels=["S&P500", "CAC40", "Sunflower"],
+            )
+            ```
+
+            ```python
+            PlotJS(...).add_tooltip(
+                labels=["S&P500", "CAC40", "Sunflower"],
+                columns=["S&P500", "CAC40", "Sunflower"],
+            )
+            ```
+
+            ```python
+            PlotJS(...).add_tooltip(
+                labels=["S&P500", "CAC40", "Sunflower"],
+                hover_nearest=True,
+            )
+            ```
+        """
+        self._tooltip_x_shift = tooltip_x_shift
+        self._tooltip_y_shift = tooltip_y_shift
+
+        if ax is None:
+            ax: Axes = self._axes[0]
+        self._legend_handles, self._legend_handles_labels = (
+            ax.get_legend_handles_labels()
+        )
+
+        if labels is None:
+            self._tooltip_labels = []
+        else:
+            self._tooltip_labels = _vector_to_list(labels)
+            self._tooltip_labels.extend(self._legend_handles_labels)
+        if groups is None:
+            self._tooltip_groups = list(range(len(self._tooltip_labels)))
+        else:
+            self._tooltip_groups = _vector_to_list(groups)
+            self._tooltip_groups.extend(self._legend_handles_labels)
+
+        if not hasattr(self, "_axes_tooltip"):
+            self._axes_tooltip: dict = dict()
+        axe_idx: int = self._axes.index(ax) + 1
+        axe_tooltip: dict[str, dict] = {
+            f"axes_{axe_idx}": {
+                "tooltip_labels": self._tooltip_labels,
+                "tooltip_groups": self._tooltip_groups,
+                "hover_nearest": "true" if hover_nearest else "false",  # js boolean
+            }
+        }
+        self._axes_tooltip.update(axe_tooltip)
+
+        return self
+
+    def add_css(
+        self,
+        from_string: Optional[str] = None,
+        *,
+        from_dict: Optional[dict] = None,
+        from_file: Optional[str] = None,
+    ) -> "PlotJS":
+        """
+        Add CSS to the final HTML output. This function allows you to override
+        default styles or add custom CSS rules.
+
+        See the [CSS guide](../guides/css/index.md) for more info on how to work with CSS.
+
+        Args:
+            from_string: CSS rules to apply, as a string.
+            from_dict: CSS rules to apply, as a dictionnary.
+            from_file: CSS rules to apply from a CSS file.
+
+        Returns:
+            self: Returns the instance to allow method chaining.
+
+        Examples:
+            ```python
+            PlotJS(...).add_css('.tooltip {"color": "red";}')
+            ```
+
+            ```python
+
+            PlotJS(...).add_css(from_file="path/to/styles.css")
+            ```
+
+            ```python
+            from plotjs import css
+
+            PlotJS(...).add_css(from_dict={".tooltip": {"color": "red";}})
+            ```
+
+            ```python
+            from plotjs import css
+
+            PlotJS(...).add_css(
+                from_dict={".tooltip": {"color": "red";}},
+            ).add_css(
+                from_dict={".tooltip": {"background": "blue";}},
+            )
+            ```
+        """
+        if from_string:
+            self.additional_css += from_string
+        elif from_dict:
+            self.additional_css += css.from_dict(from_dict)
+        elif from_file:
+            self.additional_css += css.from_file(from_file)
+        else:
+            raise ValueError(
+                "Must provide at least one of: `from_string`, `from_dict`, `from_file`."
+            )
+        return self
+
+    def add_javascript(
+        self, from_string: Optional[str] = None, *, from_file: Optional[str] = None
+    ) -> "PlotJS":
+        """
+        Add custom JavaScript to the final HTML output. This function allows
+        users to enhance interactivity, define custom behaviors, or extend
+        the existing chart logic.
+
+        Args:
+            from_string: JavaScript code to include, as a string.
+            from_file: JavaScript code to apply from a JS file.
+
+        Returns:
+            self: Returns the instance to allow method chaining.
+
+        Examples:
+            ```python
+            PlotJS(...).add_javascript("console.log('Custom JS loaded!');")
+            ```
+
+            ```python
+            from plotjs import javascript
+
+            custom_js = javascript.from_file("script.js")
+            PlotJS(...).add_javascript(custom_js)
+            ```
+        """
+        if from_string:
+            self.additional_javascript += from_string
+        elif from_file:
+            self.additional_javascript += javascript.from_file(from_file)
+        else:
+            raise ValueError(
+                "Must provide at least one of: `from_string`, `from_file`."
+            )
+        return self
+
+    def save(
+        self,
+        file_path: str,
+        favicon_path: str = "https://github.com/JosephBARBIERDARNAL/static/blob/main/python-libs/plotjs/favicon.ico?raw=true",
+        document_title: str = "Made with plotjs",
+    ) -> "PlotJS":
+        """
+        Save the interactive matplotlib plots to an HTML file.
+
+        Args:
+            file_path: Where to save the HTML file. If the ".html"
+                extension is missing, it's added.
+            favicon_path: Path to a favicon file, remote or local.
+                The default is the logo of plotjs.
+            document_title: String used for the page title (the title
+                tag inside the head of the html document).
+
+        Returns:
+            The instance itself to allow method chaining.
+
+        Examples:
+            ```python
+            PlotJS(...).save("index.html")
+            ```
+
+            ```python
+            PlotJS(...).save("path/to/my_chart.html")
+            ```
+        """
+        self._favicon_path = favicon_path
+        self._document_title = document_title
+
+        self._set_html()
+
+        if not file_path.endswith(".html"):
+            file_path += ".html"
+        with open(file_path, "w") as f:
+            f.write(self.html)
+
+        return self
+
+    def as_html(self) -> str:
+        """
+        Retrieve the interactive plot as an HTML string.
+        This can be useful to display the plot in
+        environment such as marimo, or do advanced customization.
+
+        Returns:
+            A string with all the HTML of the plot.
+
+        Examples:
+            ```python
+            import marimo as mo
+            from plotjs import PlotJS, data
+
+            df = data.load_iris()
+
+            html_plot = (
+                PlotJS(fig=fig)
+                .add_tooltip(labels=df["species"])
+                .as_html()
+            )
+
+            # display in marimo
+            mo.iframe(html_plot)
+            ```
+        """
+        self._set_html()
+        return self.html
+
+    def _set_plot_data_json(self) -> None:
+        if not hasattr(self, "_tooltip_labels"):
+            self.add_tooltip()
+
+        self.plot_data_json = {
+            "tooltip_labels": self._tooltip_labels,
+            "tooltip_groups": self._tooltip_groups,
+            "tooltip_x_shift": self._tooltip_x_shift,
+            "tooltip_y_shift": self._tooltip_y_shift,
+            "hover_nearest": self._hover_nearest,
+            "axes": self._axes_tooltip,
+        }
+
+    def _set_html(self) -> None:
+        self._set_plot_data_json()
+        self.html: str = self._template.render(
+            uuid=str(self._uuid),
+            default_css=self._default_css,
+            js_parser=self._js_parser,
+            additional_css=self.additional_css,
+            additional_javascript=self.additional_javascript,
+            svg=self._svg_content,
+            plot_data_json=self.plot_data_json,
+            favicon_path=self._favicon_path,
+            document_title=self._document_title,
+        )

plotjs/static/default.css

@@ -0,0 +1,40 @@
+:root {
+  --default-opacity: 1;
+  --default-not-hovered-opacity: 0.2;
+  --default-transition: opacity 0.1s ease;
+}
+
+svg {
+  width: 100%;
+  height: auto;
+}
+
+.tooltip {
+  position: absolute;
+  background: #001d3d;
+  padding: 8px 12px;
+  border-radius: 6px;
+  color: #ffffff;
+  font-size: 14px;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
+  pointer-events: none;
+  display: none;
+  font-family: "Helvetica Neue", "Arial", sans-serif;
+}
+
+.plot-element {
+  opacity: var(--default-opacity);
+  transition: var(--default-transition);
+}
+
+.plot-element:hover {
+  opacity: var(--default-opacity);
+}
+
+.plot-element.not-hovered {
+  opacity: var(--default-not-hovered-opacity);
+}
+
+.plot-element.hovered {
+  opacity: var(--default-opacity);
+}

plotjs/static/plotparser.js

@@ -0,0 +1,229 @@
+import * as d3 from "d3-selection";
+
+/**
+ * Core utility for parsing and interacting with matplotlib-generated SVG outputs.
+ * Provides methods to query common plot elements (bars, points, lines, areas),
+ * and to attach interactive hover tooltips.
+ *
+ * Example usage:
+ * ```js
+ * const parser = new PlotSVGParser(svg, tooltip, xShift, yShift);
+ * const points = parser.findPoints(svg, "axes_1", tooltipGroups);
+ * parser.setHoverEffect(points, "axes_1", tooltipLabels, tooltipGroups, "block", true);
+ * ```
+ */
+export default class PlotSVGParser {
+  /**
+   * Create a new parser bound to an SVG figure.
+   *
+   * @param {d3.Selection} svg - D3 selection of the target SVG element (e.g. the entire plot).
+   * @param {d3.Selection} tooltip - D3 selection of the tooltip container (e.g. a div).
+   * @param {number} tooltip_x_shift - Horizontal offset for tooltip positioning.
+   * @param {number} tooltip_y_shift - Vertical offset for tooltip positioning.
+   */
+  constructor(svg, tooltip, tooltip_x_shift, tooltip_y_shift) {
+    this.svg = svg;
+    this.tooltip = tooltip;
+    this.tooltip_x_shift = tooltip_x_shift;
+    this.tooltip_y_shift = tooltip_y_shift;
+  }
+
+  /**
+   * Find bar elements (`patch` groups with clipping) inside a given axes.
+   *
+   * @param {d3.Selection} svg - D3 selection of the SVG element.
+   * @param {string} axes_class - ID of the axes group (e.g. "axes_1").
+   * @returns {d3.Selection} D3 selection of bar elements.
+   */
+  findBars(svg, axes_class) {
+    // select all #patch within the specific axes
+    const bars = svg
+      .selectAll(`g#${axes_class} g[id^="patch"]`)
+      .filter(function () {
+        const path = d3.select(this).select("path");
+        // that have a clip-path attribute
+        const clip = path.attr("clip-path");
+        // starting with "url("
+        return clip && clip.startsWith("url(");
+      });
+
+    bars.attr("class", "bar plot-element");
+
+    console.log(`Found ${bars.size()} "bar" element`);
+    return bars;
+  }
+
+  /**
+   * Find scatter plot points inside a given axes.
+   * Handles both `<use>` and `<path>` fallback cases,
+   * and assigns `data-group` attributes based on tooltip groups.
+   *
+   * @param {d3.Selection} svg - D3 selection of the SVG element.
+   * @param {string} axes_class - ID of the axes group (e.g. "axes_1").
+   * @param {string[]} tooltip_groups - Group identifiers for tooltips, parallel to points.
+   * @returns {d3.Selection} D3 selection of point elements.
+   */
+  findPoints(svg, axes_class, tooltip_groups) {
+    let points = svg.selectAll(
+      `g#${axes_class} g[id^="PathCollection"] g[clip-path] use`
+    );
+
+    if (points.empty()) {
+      // fallback: no <use> found → grab <path> instead
+      points = svg.selectAll(`g#${axes_class} g[id^="PathCollection"] path`);
+    }
+
+    points.each(function (_, i) {
+      d3.select(this).attr("data-group", tooltip_groups[i]);
+    });
+    points.attr("class", "point plot-element");
+
+    console.log(`Found ${points.size()} "point" element`);
+    return points;
+  }
+
+  /**
+   * Find line elements (`line2d` paths) inside a given axes,
+   * excluding axis grid lines.
+   *
+   * @param {d3.Selection} svg - D3 selection of the SVG element.
+   * @param {string} axes_class - ID of the axes group.
+   * @returns {d3.Selection} D3 selection of line elements.
+   */
+  findLines(svg, axes_class) {
+    // select all <path> of Line2D elements within the specific axes
+    const lines = svg
+      .selectAll(`g#${axes_class} g[id^="line2d"] path`)
+      .filter(function () {
+        return !this.closest('g[id^="matplotlib.axis"]');
+      });
+
+    lines.attr("class", "line plot-element");
+
+    console.log(`Found ${lines.size()} "line" element`);
+    return lines;
+  }
+
+  /**
+   * Find filled area elements (`FillBetweenPolyCollection` paths) inside a given axes.
+   *
+   * @param {d3.Selection} svg - D3 selection of the SVG element.
+   * @param {string} axes_class - ID of the axes group.
+   * @returns {d3.Selection} D3 selection of area elements.
+   */
+  findAreas(svg, axes_class) {
+    // select all <path> of FillBetweenPolyCollection elements within the specific axes
+    const areas = svg.selectAll(
+      `g#${axes_class} g[id^="FillBetweenPolyCollection"] path`
+    );
+    areas.attr("class", "area plot-element");
+
+    console.log(`Found ${areas.size()} "area" element`);
+    return areas;
+  }
+
+  /**
+   * Compute the nearest element to the mouse cursor from a set of elements.
+   * Uses bounding box centers for distance.
+   * This function is used when the `hover_nearest` argument is true.
+   *
+   * @param {number} mouseX - X coordinate of the mouse relative to SVG.
+   * @param {number} mouseY - Y coordinate of the mouse relative to SVG.
+   * @param {d3.Selection} elements - Selection of candidate elements.
+   * @returns {Element|null} The nearest DOM element or `null`.
+   */
+  nearestElementFromMouse(mouseX, mouseY, elements) {
+    let nearestElem = null;
+    let minDist = Infinity;
+
+    elements.each(function (_, i) {
+      const bbox = this.getBBox();
+      const cx = bbox.x + bbox.width / 2;
+      const cy = bbox.y + bbox.height / 2;
+      const dist = Math.hypot(mouseX - cx, mouseY - cy);
+      if (dist < minDist) {
+        minDist = dist;
+        nearestElem = this;
+      }
+    });
+
+    return nearestElem;
+  }
+
+  /**
+   * Attach hover interaction and tooltip display to plot elements.
+   * Can highlight nearest element (if enabled) or hovered element directly.
+   *
+   * @param {d3.Selection} plot_element - Selection of plot elements (points, lines, etc.).
+   * @param {string} axes_class - ID of the axes group.
+   * @param {string[]} tooltip_labels - Tooltip labels for each element.
+   * @param {string[]} tooltip_groups - Group identifiers for each element.
+   * @param {"block"|"none"} show_tooltip - Whether to display tooltips.
+   * @param {boolean} hover_nearest - If true, highlight nearest element instead of hovered one.
+   */
+  setHoverEffect(
+    plot_element,
+    axes_class,
+    tooltip_labels,
+    tooltip_groups,
+    show_tooltip,
+    hover_nearest
+  ) {
+    const self = this;
+    const axesGroup = this.svg.select(`g#${axes_class}`);
+    const getHoveredIndex = hover_nearest
+      ? (event) => {
+          const [mouseX, mouseY] = d3.pointer(event);
+          const allElements = axesGroup.selectAll(".plot-element");
+          const nearestElem = self.nearestElementFromMouse(
+            mouseX,
+            mouseY,
+            allElements
+          );
+          return nearestElem ? allElements.nodes().indexOf(nearestElem) : null;
+        }
+      : (event) => plot_element.nodes().indexOf(event.currentTarget);
+
+    const mousemoveHandler = (event) => {
+      const hoveredIndex = getHoveredIndex(event);
+      const allElements = axesGroup.selectAll(".plot-element");
+
+      allElements.classed("hovered", false).classed("not-hovered", false);
+
+      if (hoveredIndex !== null) {
+        const hoveredGroup = tooltip_groups[hoveredIndex];
+
+        allElements
+          .filter((_, j) => tooltip_groups[j] === hoveredGroup)
+          .classed("hovered", true);
+
+        allElements
+          .filter((_, j) => tooltip_groups[j] !== hoveredGroup)
+          .classed("not-hovered", true);
+
+        self.tooltip
+          .style("display", show_tooltip)
+          .style("left", event.pageX + self.tooltip_x_shift + "px")
+          .style("top", event.pageY + self.tooltip_y_shift + "px")
+          .html(tooltip_labels[hoveredIndex]);
+      } else {
+        self.tooltip.style("display", "none");
+      }
+    };
+
+    if (hover_nearest) {
+      axesGroup.on("mousemove", mousemoveHandler).on("mouseout", () => {
+        axesGroup
+          .selectAll(".plot-element")
+          .classed("hovered", false)
+          .classed("not-hovered", false);
+        self.tooltip.style("display", "none");
+      });
+    } else {
+      plot_element.on("mouseover", mousemoveHandler).on("mouseout", () => {
+        plot_element.classed("hovered", false).classed("not-hovered", false);
+        self.tooltip.style("display", "none");
+      });
+    }
+  }
+}