plotjs 0.0.2__tar.gz → 0.0.3__tar.gz

{plotjs-0.0.2 → plotjs-0.0.3}/.gitignore

@@ -28,3 +28,7 @@ sandbox/
 
 *.svg
 !coverage-badge.svg
+
+scripts/release.sh
+
+/.quarto/

plotjs-0.0.3/Makefile

@@ -0,0 +1,20 @@
+.PHONY: all examples coverage
+
+examples:
+	quarto render docs/index.qmd
+	uv run docs/guides/advanced/advanced.py
+	uv run docs/guides/css/css.py
+	uv run docs/guides/javascript/javascript.py
+
+gallery:
+	quarto render docs/gallery/index.qmd
+
+coverage:
+	uv run coverage run --source=plotjs -m pytest
+	uv run coverage report -m
+	uv run coverage xml
+	uv run genbadge coverage -i coverage.xml
+	rm coverage.xml
+
+test:
+	uv run pytest

{plotjs-0.0.2/plotjs.egg-info → plotjs-0.0.3}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: plotjs
-Version: 0.0.2
-Summary: Bridge between static matplotlib and interactive storytelling
+Version: 0.0.3
+Summary: Turn static matplotlib charts into interactive web visualizations
 Author-email: Joseph Barbier <joseph.barbierdarnal@mail.com>
 License-Expression: MIT
 Project-URL: Homepage, https://y-sunflower.github.io/plotjs/
@@ -11,7 +11,7 @@ Project-URL: Repository, https://github.com/y-sunflower/plotjs
 Keywords: matplotlib,interactive,javascript,web,css,d3,mpld3,plotnine
 Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: OS Independent
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -20,11 +20,18 @@ Requires-Dist: matplotlib>=3.10.0
 Requires-Dist: narwhals>=2.0.0
 Dynamic: license-file
 
-# `plotjs`: bridge between static matplotlib and interactive storytelling
+![](./coverage-badge.svg)
 
-`plotjs` is a proof of concept, inspired by [mpld3](https://github.com/mpld3/mpld3), to make matplotlib plots interactive (for the browser) with minimum user inputs.
+# `plotjs`: Turn static matplotlib charts into interactive web visualizations
 
-The goal is also to give users a large customization power.
+<img src="https://github.com/JosephBARBIERDARNAL/static/blob/main/python-libs/plotjs/image.png?raw=true" alt="plotjs logo" align="right" width="150px"/>
+
+`plotjs` is a Python package that transform matplotlib plots into interactive charts with minimum user inputs. You can:
+
+- control tooltip labels and grouping
+- add CSS
+- add JavaScript
+- and many more
 
 > Consider that the project is still **very unstable**.
 

plotjs-0.0.3/README.md

@@ -0,0 +1,32 @@
+![](./coverage-badge.svg)
+
+# `plotjs`: Turn static matplotlib charts into interactive web visualizations
+
+<img src="https://github.com/JosephBARBIERDARNAL/static/blob/main/python-libs/plotjs/image.png?raw=true" alt="plotjs logo" align="right" width="150px"/>
+
+`plotjs` is a Python package that transform matplotlib plots into interactive charts with minimum user inputs. You can:
+
+- control tooltip labels and grouping
+- add CSS
+- add JavaScript
+- and many more
+
+> Consider that the project is still **very unstable**.
+
+[Online demo](https://y-sunflower.github.io/plotjs/)
+
+<br><br>
+
+## Installation
+
+From PyPI:
+
+```
+pip install plotjs
+```
+
+Latest dev version:
+
+```
+pip install git+https://github.com/y-sunflower/plotjs.git
+```

{plotjs-0.0.2 → plotjs-0.0.3}/coverage-badge.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="114" height="20" role="img" aria-label="coverage: 92.48%"><title>coverage: 92.48%</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="114" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="53" height="20" fill="#4c1"/><rect width="114" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="315" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="510">coverage</text><text x="315" y="140" transform="scale(.1)" fill="#fff" textLength="510">coverage</text><text aria-hidden="true" x="865" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="430">92.48%</text><text x="865" y="140" transform="scale(.1)" fill="#fff" textLength="430">92.48%</text></g></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="114" height="20" role="img" aria-label="coverage: 92.19%"><title>coverage: 92.19%</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="114" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="53" height="20" fill="#4c1"/><rect width="114" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="315" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="510">coverage</text><text x="315" y="140" transform="scale(.1)" fill="#fff" textLength="510">coverage</text><text aria-hidden="true" x="865" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="430">92.19%</text><text x="865" y="140" transform="scale(.1)" fill="#fff" textLength="430">92.19%</text></g></svg>

plotjs-0.0.3/docs/developers/contributing.md

@@ -0,0 +1,68 @@
+`plotjs` is still in a very early stage, but contributions is still welcomed!
+
+The best way to help the development is to:
+
+- list the bugs you found by opening [GitHub issues](https://github.com/y-sunflower/plotjs/issues){target="_blank"}
+- list the features you'd like to see by opening [GitHub issues](https://github.com/y-sunflower/plotjs/issues){target="_blank"}
+
+## Setting up your environment
+
+### Install for development
+
+- Fork the repository to your own GitHub account.
+
+- Clone your forked repository to your local machine (ensure you have [Git installed](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)):
+
+```bash
+git clone https://github.com/github_user_name/plotjs.git
+cd plotjs
+git remote add upstream https://github.com/y-sunflower/plotjs.git
+```
+
+- Create a new branch:
+
+```bash
+git checkout -b my-feature
+```
+
+- Set up your Python environment (ensure you have [uv installed](https://docs.astral.sh/uv/getting-started/installation/)):
+
+```bash
+uv sync --all-groups --dev
+uv run pre-commit install
+uv pip install -e .
+```
+
+## Code
+
+You can now make changes to the package and start coding!
+
+### Run the test
+
+- Test that everything works correctly by running:
+
+```bash
+uv run pytest
+```
+
+### Preview documentation locally
+
+```bash
+uv run mkdocs serve
+```
+
+## Push changes
+
+- Commit and push your changes:
+
+```bash
+git add -A
+git commit -m "description of what you did"
+git push
+```
+
+- Navigate to your fork on GitHub and click the "Compare & pull request" button to open a new pull request.
+
+Congrats! Once your PR is merged, it will be part of `plotjs`.
+
+<br>

plotjs-0.0.3/docs/developers/how-it-works.md

@@ -0,0 +1,158 @@
+Transforming a static plot into something interactive can't be done (unfortunately) just by saying "make this interactive."
+
+But that doesn't mean we have to do mystic things to make it work, because **yes**, that's perfectly possible without weird hacking stuff.
+
+## Overview
+
+There are two ways to tackle this problem:
+
+- Take a matplotlib Figure (an instance containing all plot elements) and convert it to a more common format such as JSON. We call this **serialization**. Then, with this JSON file, we recreate the figure with an interactive tool such as D3.js (that's what [mpld3](https://github.com/mpld3/mpld3) does, by the way!).
+- Use the native matplotlib figure output format (especially SVG) and parse this instead (that's what `plotjs` does).
+
+The second option is **much simpler** (well, it depends), because we don't have to:
+
+- translate the figure to JSON (which can be painfully complex if you want to handle all edge cases and make it robust),
+- recreate the chart (browsers can display SVG perfectly).
+
+But it means we don't have full control over how the plot is structured (from the browser's point of view). We need to find a way to parse this SVG.
+
+## Parsing SVG
+
+For the moment, we just take the user's matplotlib figure and save it as SVG. This is just:
+
+```python
+fig.savefig("plot.svg")
+```
+
+Now, let's say the figure contains a scatter plot and we want to add a tooltip: when someone hovers their mouse over a point, it displays a label.
+
+The **core problem to solve** is: "how do I know what elements from the SVG are points?"
+
+If we're able to find a solution to this, then we're able to do pretty much **anything we want**.
+
+The thing is, there's nothing in the SVG output file that tells us "this element is a point from the scatter plot." **Even worse**, we don't even know if it's a scatter plot or something completely unrelated, like a choropleth map.
+
+For example, here is a polygon of a choropleth map:
+
+```svg
+<path d="M -5.94098 449.279178
+L -4.961244 447.127034
+L -4.623284 444.786333
+L -3.951831 442.584471
+L -5.459995 439.551953
+L -5.763812 436.050818
+L -3.764043 431.650797
+L -2.459548 432.213824
+L 0.368893 433.425033
+L 4.436122 437.74466
+L 5.072043 439.840475
+L 2.799722 444.523728
+L 1.620088 448.292228
+L 0.147953 450.236113
+L -1.691322 450.601856
+L -2.215184 449.161231
+L -3.074426 448.947286
+L -4.263489 450.334887
+z
+" clip-path="url(#pf43ab1627f)" style="fill: #424186"/>
+```
+
+Here is a point from a scatter plot:
+
+```svg
+<use
+   xlink:href="#m81e2893e84"
+   x="145.978182"
+   y="144.288"
+   style="fill: #1f77b4;
+   stroke: #1f77b4"
+/>
+```
+
+Here is a line from a line chart:
+
+```svg
+<g id="line2d_19">
+   <path d="M 73.832727 295.488
+L 154.996364 235.008
+L 236.16 174.528
+L 317.323636 114.048
+L 398.487273 53.568
+"
+   clip-path="url(#pd511a61f39)"
+   style="fill: none;
+   stroke: #1f77b4;
+   stroke-width: 1.5;
+   stroke-linecap: square" />
+</g>
+```
+
+If you pay close attention, you'll see potential patterns in the structure of certain elements.
+
+That's exactly what we'll use to determine what kind of plot elements we have.
+
+> Note: determining the kind of plot elements could have been done (partially) from the Python side, but this felt easier to me to do from the JavaScript side.
+
+The next step is to understand matplotlib's underlying objects (called [artists](https://matplotlib.org/stable/users/explain/artists/artist_intro.html){target="\_blank"}) and how that translates to SVG.
+
+## TL;DR: Artists in matplotlib
+
+In matplotlib, artists are all the visual elements you see on a plot. There is the `Artist` base class, and all other artists inherit from this class.
+
+For example:
+
+- the `scatter()` function returns a `PathCollection` object, a subclass of `Artist`,
+- the `plot()` function returns a `Line2D` object, a subclass of `Artist`,
+- and so on.
+
+## Selecting artists from SVG
+
+In the SVG output of `savefig("plot.svg")`, we can find some info about what object was used.
+
+For example, all `PathCollection` objects look like `<g id="PathCollection_1">`, `<g id="PathCollection_2">`. And since `PathCollection` is just one or multiple points, we can easily know how many scatter plots there are.
+
+For lines, they are represented by `Line2D`. In the SVG, they look like `<g id="line2d_1">`, `<g id="line2d_2">`, etc. With this, we can easily detect that there are lines in the chart.
+
+But there's a major issue here: not all `PathCollection` elements are relevant, same for `Line2D`, and so on.
+
+By "relevant," I mean those we want to add interactivity to. For example, what elements here are considered to be a `Line2D`?
+
+![](../img/how-it-works-1.png)
+
+At first, I thought there were three: one for each main line. But in practice, it's much more:
+
+![](../img/how-it-works-2.png)
+
+What that means is that we can't just select all `Line2D` elements and give them a hover effect, for instance. We need to find a way to discriminate relevant lines (the three big ones) from the other ones.
+
+## Filtering artists from SVG
+
+This section might not be up to date with the latest version, but it'll give you an idea of how `plotjs` detects what is a "core" plot element and what is not.
+
+It mostly consists of handling edge cases here, and is very different depending on the plot element (`Line2D`, `PathCollection`, etc.).
+
+For example, in order to select only "core" `Line2D` elements (the three colored ones in the previous image), we do:
+
+```javascript
+const lines = svg.selectAll('g[id^="line2d"] path').filter(function () {
+  const clip = d3.select(this).attr("clip-path");
+
+  return (
+    // keep only <path> with clip-path attribute
+    clip &&
+    // that starts with "url("
+    clip.startsWith("url(") &&
+    // and are not child of a #matplotlib.axis
+    !this.closest('g[id^="matplotlib.axis"]')
+  );
+});
+```
+
+The idea is basically:
+
+- select all `Line2D` elements with the first line,
+- filter to remove non-wanted `Line2D` elements.
+
+This gives us a `lines` variable that only contains the lines of interest!
+
+The logic is the same for other plot elements: bars, points, polygons, etc.

plotjs-0.0.3/docs/gallery/index.md

@@ -0,0 +1,85 @@
+
+
+This page contains all the `plotjs` examples from this website.
+
+**TODO: make this page less ugly and add more diverse examples.**
+
+<div style="display: flex;">
+
+<iframe width="100%" height="300" src="../iframes/quickstart8.html" style="flex: 1; border: none;">
+
+</iframe>
+
+<iframe width="100%" height="300" src="../iframes/quickstart.html" style="flex: 1; border: none;">
+
+</iframe>
+
+</div>
+
+<div style="display: flex;">
+
+<iframe width="100%" height="300" src="../iframes/quickstart4.html" style="flex: 1; border: none;">
+
+</iframe>
+
+<iframe width="100%" height="300" src="../iframes/quickstart5.html" style="flex: 1; border: none;">
+
+</iframe>
+
+</div>
+
+<div style="display: flex;">
+
+<iframe width="100%" height="300" src="../iframes/quickstart9.html" style="flex: 1; border: none;">
+
+</iframe>
+
+<iframe width="100%" height="300" src="../iframes/CSS.html" style="flex: 1; border: none;">
+
+</iframe>
+
+</div>
+
+<div style="display: flex;">
+
+<iframe width="100%" height="300" src="../iframes/quickstart2.html" style="flex: 1; border: none;">
+
+</iframe>
+
+<iframe width="100%" height="300" src="../iframes/javascript.html" style="flex: 1; border: none;">
+
+</iframe>
+
+</div>
+
+<div style="display: flex;">
+
+<iframe width="100%" height="300" src="../iframes/quickstart3.html" style="flex: 1; border: none;">
+
+</iframe>
+
+<iframe width="100%" height="300" src="../iframes/javascript2.html" style="flex: 1; border: none;">
+
+</iframe>
+
+</div>
+
+<div style="display: flex;">
+
+<iframe width="100%" height="300" src="../iframes/CSS-2.html" style="flex: 1; border: none;">
+
+</iframe>
+
+<iframe width="100%" height="300" src="../iframes/quickstart6.html" style="flex: 1; border: none;">
+
+</iframe>
+
+</div>
+
+<div style="display: flex;">
+
+<iframe width="100%" height="300" src="../iframes/quickstart7.html" style="flex: 1; border: none;">
+
+</iframe>
+
+</div>

plotjs-0.0.3/docs/gallery/index.qmd

@@ -0,0 +1,31 @@
+---
+format: gfm
+from: markdown-smart
+---
+
+This page contains all the `plotjs` examples from this website.
+
+**TODO: make this page less ugly and add more diverse examples.**
+
+```{python}
+# | echo: false
+# | output: asis
+from pathlib import Path
+
+html_files = list(Path("../iframes").rglob("*.html"))
+html_paths = [str(path) for path in html_files]
+
+
+# Split the list into chunks of 2
+def chunks(lst, n):
+    for i in range(0, len(lst), n):
+        yield lst[i : i + n]
+
+
+for pair in chunks(html_paths, 2):
+    print('<div style="display: flex;">')
+    for html_path in pair:
+        iframe = f'<iframe width="100%" height="300" src="{html_path}" style="flex: 1; border: none;"></iframe>'
+        print(iframe)
+    print("</div>")
+```

plotjs-0.0.3/docs/guides/css/CSS.py

@@ -0,0 +1,56 @@
+import matplotlib.pyplot as plt
+from plotjs import MagicPlot, data, css
+
+df = data.load_iris()
+
+fig, ax = plt.subplots()
+ax.scatter(
+    df["sepal_length"],
+    df["sepal_width"],
+    c=df["species"].astype("category").cat.codes,
+    s=300,
+    alpha=0.5,
+    ec="black",
+)
+ax.set_xlabel("Sepal Length")
+ax.set_ylabel("Sepal Width")
+
+df["tooltip"] = (
+    "Sepal length = "
+    + df["sepal_length"].astype(str)
+    + "<br>"
+    + "Sepal width = "
+    + df["sepal_width"].astype(str)
+    + "<br>"
+    + df["species"].str.upper()
+)
+
+(
+    MagicPlot()
+    .add_tooltip(labels=df["tooltip"])
+    .add_css(".tooltip {background: red; color: blue;}")
+    .save("docs/iframes/CSS.html")
+)
+
+
+(
+    MagicPlot()
+    .add_tooltip(labels=df["tooltip"])
+    .add_css(css.from_dict({".tooltip": {"background": "red", "color": "blue"}}))
+)
+
+(
+    MagicPlot()
+    .add_tooltip(
+        labels=df["tooltip"],
+    )
+    .add_css(css.from_dict({".tooltip": {"color": "blue"}}))
+    .add_css(css.from_dict({".tooltip": {"background": "red"}}))
+)
+
+(
+    MagicPlot()
+    .add_tooltip(labels=df["tooltip"])
+    .add_css(css.from_file("docs/static/style.css"))
+    .save("docs/iframes/CSS-2.html")
+)

plotjs-0.0.3/docs/guides/css/index.md

@@ -0,0 +1,121 @@
+With `plotjs`, you can add your own CSS for advanced plot customization. Here's how it works.
+
+## What is CSS?
+
+CSS has two main components:
+
+- **Selectors**: which elements the style applies to
+- **Rules**: a set of `key: value` pairs defining the style
+
+A basic CSS rule looks like this:
+
+```css
+.tooltip {
+  background: red;
+  color: blue;
+}
+```
+
+This means: _"For all elements with class `tooltip`, set the background to red and the text color to blue."_
+
+## Applying CSS to a plot
+
+You can directly apply a CSS string to your plot:
+
+```python
+(
+    MagicPlot()
+    .add_tooltip(labels=df["tooltip"])
+    .add_css(".tooltip { background: red; color: blue; }")
+)
+```
+
+<iframe width="800" height="600" src="../../iframes/css.html" style="border:none;"></iframe>
+
+> CSS doesn’t require indentation: one-liners work fine.
+
+## Using a Python dictionary
+
+For better readability and reusability, you can define CSS as a dictionary using `plotjs.css.from_dict()`:
+
+```python
+from plotjs import css
+
+(
+    MagicPlot()
+    .add_tooltip(labels=df["tooltip"])
+    .add_css(css.from_dict({
+        ".tooltip": {
+            "background": "red",
+            "color": "blue"
+        }
+    }))
+)
+```
+
+Method chaining also works if you want to split styles:
+
+```python
+(
+    MagicPlot()
+    .add_tooltip(labels=df["tooltip"])
+    .add_css(css.from_dict({".tooltip": {"color": "blue"}}))
+    .add_css(css.from_dict({".tooltip": {"background": "red"}}))
+)
+```
+
+## Loading CSS from a file
+
+If your CSS is stored in a `.css` file like:
+
+```css
+.tooltip {
+  background: pink;
+  color: yellow;
+}
+```
+
+You can load it with:
+
+```python
+from plotjs import css
+
+(
+    MagicPlot()
+    .add_tooltip(labels=df["tooltip"])
+    .add_css(css.from_file("docs/static/style.css"))
+)
+```
+
+<iframe width="800" height="600" src="../../iframes/css-2.html" style="border:none;"></iframe>
+
+## Selectable elements
+
+To style or add interactivity, you need to select elements using the DOM[^1]. These are the most common selectors:
+
+### Plot elements
+
+- `.point`: scatter plot points
+- `.line`: line chart lines
+- `.area`: area chart fills
+- `.bar`: bar chart bars
+- `.plot-element`: all of the above
+
+You can combine with `.hovered` or `.not-hovered`, e.g., `.point.hovered`.
+
+### Misc
+
+- `.tooltip`: tooltip shown on hover
+- `svg`: the entire SVG element
+
+???+ question
+
+    Something missing? Please [open an issue](https://github.com/y-sunflower/plotjs/issues)!
+
+## Default CSS
+
+You can find the default CSS applied by plotjs [here](https://github.com/y-sunflower/plotjs/blob/main/plotjs/static/default.css)
+
+## Appendix
+
+[^1]: The DOM (Document Object Model) is like a tree structure representing your webpage. JavaScript and CSS use it to select, modify, and interact with elements dynamically.