Merge pull request #31 from y-sunflower/develop

support for multiple axes, among others

Author: JosephBARBIERDARNAL

README.md

@@ -1,10 +1,15 @@
 ![](./coverage-badge.svg)
 
-# `plotjs`: bridge between static matplotlib and interactive storytelling
+# `plotjs`: Turn static matplotlib charts into interactive web visualizations
 
-`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.
+<img src="https://github.com/JosephBARBIERDARNAL/static/blob/main/python-libs/plotjs/image.png?raw=true" alt="plotjs logo" align="right" width="150px"/>
 
-The goal is also to give users a large customization power.
+`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**.
 

docs/developers/how-it-works.md

@@ -1,36 +1,36 @@
-Transforming a static plot into something that you can interact with can't be done (unfortunately) just by saying "make this interactive".
+Transforming a static plot into something interactive can't be done (unfortunately) just by saying "make this interactive."
 
-But that does not mean we have to do mystic things to make it to work, because, **yes** that's perfectly possible without weird hacking stuff.
+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 2 ways to tackle this problem:
+There are two ways to tackle this problem:
 
-- Take a matplotlib Figure (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 btw!).
-- Use native matplotlib figure output format (especially SVG) and parse this instead (that's what `plotjs` does).
+- 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
+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 egde cases and make it robust).
-- recreate the chart: browsers can display SVG perfectly.
+- 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 that we don't have full control over how the plot is structured (from the browser point of view). We need to find a way to parse this SVG.
+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 user's matplotlib figure and save it as SVG. This is just:
+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 scatterplot we want to add a tooltip: when someone passes his mouse over a point, it displays a label.
+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"?
+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 that, 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 that's a scatter plot or something completly unrelated like a choropleth map.
+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:
 
@@ -91,47 +91,47 @@ If you pay close attention, you'll see potential patterns in the structure of ce
 
 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 it from the JavaScript side.
+> 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 underlying objects (called [artists](https://matplotlib.org/stable/users/explain/artists/artist_intro.html){target="\_blank"}) and how that translate to SVG.
+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.
 
-## TLDR: artists in matplotlib
+## 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 others artists inherits from this class.
+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
+- 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` object looks 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 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, there 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 the chart.
+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 is a major issue here: not all `PathCollection` are relevant, same for `Line2D`, and so on.
+But there's a major issue here: not all `PathCollection` elements are relevant, same for `Line2D`, and so on.
 
-By relevant I mean that we want to add interactivity to them. For example, what elements here are considered to be a `Line2D`:
+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 was 3: one for each main line. But in practice, it's much more:
+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 select all `Line2D` and give them an hover effect, for instance. We need to find a way to discriminate relevant lines (the 3 big ones) and the other ones.
+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 to the latest version, but it'll give you the idea of how `plotjs` detect what is a "core" plot elements, and what is not.
+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's mostly consist of handling edge cases here, and is very different depending on the plot element (`Line2D`, `PathCollection`, etc).
+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` (the 3 colored ones in the previous image), we do:
+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 () {
@@ -150,8 +150,8 @@ const lines = svg.selectAll('g[id^="line2d"] path').filter(function () {
 
 The idea is basically:
 
-- select all `Line2D` with the first line
-- filter to remove non-wanted `Line2D`
+- 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!
 

docs/guides/css/index.md

@@ -1,80 +1,85 @@
-With `plotjs`, you can add your own CSS for advanced plot customization. Let's see how it works.
+With `plotjs`, you can add your own CSS for advanced plot customization. Here's how it works.
 
-## Understanding CSS
+## What is CSS?
 
-CSS requires 2 things:
+CSS has two main components:
 
-- a selector: which elements should receive the style
-- a list of key-value pairs, where keys are the attribute we want to set and value the value for this attribute.
+- **Selectors**: which elements the style applies to
+- **Rules**: a set of `key: value` pairs defining the style
 
-A minimalist CSS code would be:
+A basic CSS rule looks like this:
 
-```CSS
+```css
 .tooltip {
-   background: red;
-   color: blue;
+  background: red;
+  color: blue;
 }
 ```
 
-Here we basically say _"To all objects of the class `tooltip`, set the `background` to `red` and the text `color` to `blue`."_
+This means: _"For all elements with class `tooltip`, set the background to red and the text color to blue."_
 
-Now let's add this CSS to our plot to change the tooltip:
+## 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;}")
+    .add_css(".tooltip { background: red; color: blue; }")
 )
 ```
 
 <iframe width="800" height="600" src="../../iframes/css.html" style="border:none;"></iframe>
 
-> Note that this does not require any indentation, contrary to Python. We can write CSS with a single line of code.
-
-## Pass CSS as a Python dictionnary
+> CSS doesn’t require indentation: one-liners work fine.
 
-Being able to pass CSS inside a string is convenient, but not very readable when you want to pass a lot of CSS.
+## Using a Python dictionary
 
-One option that you can use is to define your CSS via dictionnary. For this we need to import the css module from `plotjs`.
+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"}}))
+    .add_css(css.from_dict({
+        ".tooltip": {
+            "background": "red",
+            "color": "blue"
+        }
+    }))
 )
 ```
 
-Since `add_css()` returns the instance itself, you can do method chaining:
+Method chaining also works if you want to split styles:
 
 ```python
 (
     MagicPlot()
-    .add_tooltip(
-        labels=df["tooltip"],
-    )
+    .add_tooltip(labels=df["tooltip"])
     .add_css(css.from_dict({".tooltip": {"color": "blue"}}))
     .add_css(css.from_dict({".tooltip": {"background": "red"}}))
 )
 ```
 
-## Pass a CSS file
+## Loading CSS from a file
 
-Finally, if your CSS is in a CSS file, you can use `css.from_file()`. Assuming your CSS file looks like this:
+If your CSS is stored in a `.css` file like:
 
-```CSS
+```css
 .tooltip {
   background: pink;
   color: yellow;
 }
 ```
 
-We now do:
+You can load it with:
 
 ```python
+from plotjs import css
+
 (
     MagicPlot()
     .add_tooltip(labels=df["tooltip"])
@@ -84,29 +89,33 @@ We now do:
 
 <iframe width="800" height="600" src="../../iframes/css-2.html" style="border:none;"></iframe>
 
-## Elements to select
+## Selectable elements
 
-In order to apply CSS or [JavaScript](../javascript/index.md), you need to select elements from the DOM[^1]. You can find most of them using the [inspector](../troubleshooting/index.md) of your browser. All the common ones are defined below:
+To style or add interactivity, you need to select elements using the DOM[^1]. These are the most common selectors:
 
-#### Plot elements
+### Plot elements
 
-- `.point`: all points from a scatter plot
-- `.line`: all lines from a line chart
-- `.area`: all areas from an area chart
-- `.bar`: all bars from a bar chart
-- `.plot-element`: all previous elements (points, lines, areas and bars)
+- `.point`: scatter plot points
+- `.line`: line chart lines
+- `.area`: area chart fills
+- `.bar`: bar chart bars
+- `.plot-element`: all of the above
 
-For all of those previous elements, you can add `.hovered` or `.not-hovered` (e.g, `.point.not-hovered`) to, respectively, select currently hovered and not hovered elements.
+You can combine with `.hovered` or `.not-hovered`, e.g., `.point.hovered`.
 
-#### Misc
+### Misc
 
-- `.tooltip`: the tooltip displayed when hovering elements
-- `svg`: the entire SVG containing the chart
+- `.tooltip`: tooltip shown on hover
+- `svg`: the entire SVG element
 
 ???+ question
 
-    Something's missing? Please [tell me](https://github.com/y-sunflower/plotjs/issues) about it by opening a new issue!
+    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 a tree-like structure that represents all the elements of a web page, allowing JavaScript to read, change, and interact with them. Think of it as a live map of the webpage that your code can explore and update in real time.
+[^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.

docs/guides/customization/customization.py

@@ -1,8 +1,8 @@
-Under the hood, JavaScript is what is used to make the charts interactive. But `plotjs` allows anyone to add some more JavaScript for a finer control of what is happening and basically do whatever you want!
+Under the hood, JavaScript is what is used to make the charts interactive. But `plotjs` allows anyone to add some more JavaScript for finer control of what is happening and basically do whatever you want!
 
 ## Basic example
 
-Try to click on one of the point in the chart!
+Try to click on one of the points in the chart!
 
 ```python
 import matplotlib.pyplot as plt
@@ -43,10 +43,10 @@ d3.selectAll(".point").on("click", () =>
 );
 ```
 
-Here what it does:
+Here’s what it does:
 
-- select all points (e.g, from the scatter plot)
-- sets that when clicking one of the point
+- selects all points (e.g., from the scatter plot)
+- sets that when clicking one of the points
 - it displays a message
 
 ## Loading JavaScript from file
@@ -61,7 +61,7 @@ MagicPlot(fig=fig).add_javascript(
 )
 ```
 
-This allows you to write JavaScript in a separate file so that you can have a code formatter (prettier, etc), code completion, syntax highlighting, and so on. This is what is recommended to do if you're writing a significant amount of code.
+This allows you to write JavaScript in a separate file so that you can have a code formatter (prettier, etc.), code completion, syntax highlighting, and so on. This is what is recommended to do if you're writing a significant amount of code.
 
 ## Advanced usage
 
@@ -140,9 +140,9 @@ In order to apply [CSS](../css/index.md) or JavaScript, you need to select eleme
 - `.line`: all lines from a line chart
 - `.area`: all areas from an area chart
 - `.bar`: all bars from a bar chart
-- `.plot-element`: all previous elements (points, lines, areas and bars)
+- `.plot-element`: all previous elements (points, lines, areas, and bars)
 
-For all of those previous elements, you can add `.hovered` or `.not-hovered` (e.g, `.point.not-hovered`) to, respectively, select currently hovered and not hovered elements.
+For all of those previous elements, you can add `.hovered` or `.not-hovered` (e.g., `.point.not-hovered`) to, respectively, select currently hovered and not-hovered elements.
 
 #### Misc
 

docs/guides/customization/index.md

@@ -1,22 +1,22 @@
-Since `plotjs` does many things via JavaScript (e.g, in your browser when you open your html file), you may easily encounter "silent" errors.
+Since `plotjs` does many things via JavaScript (e.g., in your browser when you open your HTML file), you may easily encounter "silent" errors.
 
-In practice you will run you Python and everything will seems fine, but that does not mean what you'll see in the output is what you expected. There may multiple reasons for this. Here I'll explain common things that can happen, and how to debug them.
+In practice, you will run your Python and everything will seem fine, but that does not mean what you'll see in the output is what you expected. There may be multiple reasons for this. Here I'll explain common things that can happen, and how to debug them.
 
 ## Developer tools
 
 Your browser has a thing called developer tools. It allows you to view many things, but here we're mostly interested in its "console" section.
 
-The console displays all the messages, including error messages, that the web page encountered at some point. Many of them are not necessarly interesting and are standard messages, but some of them might come from `plotjs` doing something wrong.
+The console displays all the messages, including error messages, that the web page encountered at some point. Many of them are not necessarily interesting and are standard messages, but some of them might come from `plotjs` doing something wrong.
 
 How to open the developer tools is browser-specific, but there's likely a shortcut to make it convenient. For instance, on macOS + Firefox I use ++option+cmd+i++.
 
 ## Debug `plotjs`
 
 ### Workflow
 
-Since currently `plotjs` can't (yet) really be displayed in tools like Jupyter notebooks, marimo, etc, you have to open the output html file in your browser.
+Since currently `plotjs` can't (yet) really be displayed in tools like Jupyter notebooks, marimo, etc., you have to open the output HTML file in your browser.
 
-In order to have a comfortable workflow, it's recommend to have [`live-server`](https://www.npmjs.com/package/live-server) installed on your machine for automatic reload on file changes. Assuming you name your html file `mychart.html`, you'll just have to run `live-server mychart.html` and it'll open your plot in your default browser. Every time `mychart.html` is updated, it'll refresh the page. This makes debugging and iterating much faster and easier.
+In order to have a comfortable workflow, it's recommended to have [`live-server`](https://www.npmjs.com/package/live-server) installed on your machine for automatic reload on file changes. Assuming you name your HTML file `mychart.html`, you'll just have to run `live-server mychart.html` and it'll open your plot in your default browser. Every time `mychart.html` is updated, it'll refresh the page. This makes debugging and iterating much faster and easier.
 
 ### Debugging