From 44754e3b92c54f5ba7ad36a9c4958e7ff9cc6598 Mon Sep 17 00:00:00 2001 From: Julien Barnier Date: Sun, 26 May 2024 17:34:48 +0200 Subject: [PATCH] doc: update introduction notebook to "format" API --- examples/introduction.ipynb | 209 ++++++++++++++++++++---------------- 1 file changed, 118 insertions(+), 91 deletions(-) diff --git a/examples/introduction.ipynb b/examples/introduction.ipynb index df0bd1e..6696093 100644 --- a/examples/introduction.ipynb +++ b/examples/introduction.ipynb @@ -13,7 +13,7 @@ "\n", "## Getting started\n", "\n", - "First, we install the package:" + "First, we install the package:\n" ] }, { @@ -33,7 +33,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "For the simplest case we only need to import the `Plot` class:" + "For the simplest case we only need to import the `Plot` class:\n" ] }, { @@ -50,7 +50,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "We can then generate our first plots by passing a plot specification to the `Plot.plot()` method:" + "We can then generate our first plots by passing a plot specification to the `Plot.plot()` method:\n" ] }, { @@ -60,16 +60,27 @@ "outputs": [], "source": [ "import polars as pl\n", - "penguins = pl.read_csv(\"https://github.com/juba/pyobsplot/raw/main/doc/data/penguins.csv\")\n", "\n", - "Plot.plot({\n", - " \"grid\": True,\n", - " \"marks\": [\n", - " Plot.dot(penguins, {\n", - " \"x\": \"culmen_length_mm\", \"y\": \"culmen_depth_mm\", \"fill\": \"island\", \"tip\": True\n", - " })\n", - " ]\n", - "})" + "penguins = pl.read_csv(\n", + " \"https://github.com/juba/pyobsplot/raw/main/doc/data/penguins.csv\"\n", + ")\n", + "\n", + "Plot.plot(\n", + " {\n", + " \"grid\": True,\n", + " \"marks\": [\n", + " Plot.dot(\n", + " penguins,\n", + " {\n", + " \"x\": \"culmen_length_mm\",\n", + " \"y\": \"culmen_depth_mm\",\n", + " \"fill\": \"island\",\n", + " \"tip\": True,\n", + " },\n", + " )\n", + " ],\n", + " }\n", + ")" ] }, { @@ -78,15 +89,23 @@ "metadata": {}, "outputs": [], "source": [ - "Plot.plot({\n", - " \"grid\": True,\n", - " \"marginRight\": 80,\n", - " \"color\": {\"legend\": True},\n", - " \"marks\": [\n", - " Plot.rectY(penguins, Plot.binX({\"y\": \"count\"}, {\"x\": \"body_mass_g\", \"fill\": \"island\", \"fy\": \"island\"})),\n", - " Plot.ruleY([0])\n", - " ]\n", - "})" + "Plot.plot(\n", + " {\n", + " \"grid\": True,\n", + " \"marginRight\": 80,\n", + " \"color\": {\"legend\": True},\n", + " \"marks\": [\n", + " Plot.rectY(\n", + " penguins,\n", + " Plot.binX(\n", + " {\"y\": \"count\"},\n", + " {\"x\": \"body_mass_g\", \"fill\": \"island\", \"fy\": \"island\"},\n", + " ),\n", + " ),\n", + " Plot.ruleY([0]),\n", + " ],\n", + " }\n", + ")" ] }, { @@ -96,7 +115,7 @@ "source": [ "## Generator object\n", "\n", - "Using `Plot.plot()` allows to create plots with the default settings. To go a bit further we can create a *plot generator object* by importing the `Obsplot` class and calling it:" + "Using `Plot.plot()` allows to create plots with the default settings. To go a bit further we can create a _plot generator object_ by importing the `Obsplot` class and calling it:\n" ] }, { @@ -115,7 +134,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "To produce plots with this generator object, we pass it a specification like we did with `Plot.plot()`:" + "To produce plots with this generator object, we pass it a specification like we did with `Plot.plot()`:\n" ] }, { @@ -124,18 +143,21 @@ "metadata": {}, "outputs": [], "source": [ - "op({\n", - " \"color\": {\"legend\": True},\n", - " \"marginLeft\": 80,\n", - " \"marginRight\": 80,\n", - " \"x\": {\"inset\": 20},\n", - " \"grid\": True,\n", - " \"marks\": [\n", - " Plot.boxX(penguins, {\n", - " \"x\": \"body_mass_g\", \"fill\": \"island\", \"y\": \"island\", \"fy\": \"species\"\n", - " })\n", - " ]\n", - "})" + "op(\n", + " {\n", + " \"color\": {\"legend\": True},\n", + " \"marginLeft\": 80,\n", + " \"marginRight\": 80,\n", + " \"x\": {\"inset\": 20},\n", + " \"grid\": True,\n", + " \"marks\": [\n", + " Plot.boxX(\n", + " penguins,\n", + " {\"x\": \"body_mass_g\", \"fill\": \"island\", \"y\": \"island\", \"fy\": \"species\"},\n", + " )\n", + " ],\n", + " }\n", + ")" ] }, { @@ -143,7 +165,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "A generator object allows, for example, to directly call a mark function:" + "A generator object allows, for example, to directly call a mark function:\n" ] }, { @@ -160,11 +182,11 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## jsdom renderer\n", + "## Output formats\n", "\n", - "By default, plots are created as Jupyter widgets, using the `widget` renderer. `pyobsplot` provides another renderer, called `jsdom`, which generates plots directly as SVG or HTML.\n", + "By default, plots are created as Jupyter widgets. `pyobsplot` also allows to output plots to SVG, PNG and static HTML formats.\n", "\n", - "To use this renderer, we need to have a working installation of a recent node.js version:" + "To use these formats, we need to have a working installation of a recent node.js version:\n" ] }, { @@ -187,7 +209,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "And we need to install the `pyobsplot` npm package:" + "And we need to install the `pyobsplot` npm package:\n" ] }, { @@ -204,7 +226,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Then we can create a new plot generator object, this time using the `jsdom` renderer:" + "Then, when creating a new plot generator object, we can specify an output `format`:\n" ] }, { @@ -213,7 +235,7 @@ "metadata": {}, "outputs": [], "source": [ - "op_jsdom = Obsplot(renderer=\"jsdom\")" + "op_jsdom = Obsplot(format=\"png\")" ] }, { @@ -221,7 +243,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "The plots generated with this object will be created directly as SVG or HTML." + "The plots generated with this object will be created directly as PNG images.\n" ] }, { @@ -232,26 +254,28 @@ "source": [ "ca55 = pl.read_csv(\"https://github.com/juba/pyobsplot/raw/main/doc/data/ca55-south.csv\")\n", "\n", - "op_jsdom({\n", - " \"x\": {\"axis\": None},\n", - " \"y\": {\"axis\": None},\n", - " \"inset\": 10,\n", - " \"marginBottom\": 2,\n", - " \"height\": 500,\n", - " \"color\": {\"type\": \"diverging\"},\n", - " \"marks\": [\n", - " Plot.raster(\n", - " ca55,\n", - " {\n", - " \"x\": \"LONGITUDE\",\n", - " \"y\": \"LATITUDE\",\n", - " \"fill\": \"MAG_IGRF90\",\n", - " \"interpolate\": \"random-walk\",\n", - " },\n", - " ),\n", - " Plot.frame(),\n", - " ],\n", - "})\n" + "op_jsdom(\n", + " {\n", + " \"x\": {\"axis\": None},\n", + " \"y\": {\"axis\": None},\n", + " \"inset\": 10,\n", + " \"marginBottom\": 2,\n", + " \"height\": 500,\n", + " \"color\": {\"type\": \"diverging\"},\n", + " \"marks\": [\n", + " Plot.raster(\n", + " ca55,\n", + " {\n", + " \"x\": \"LONGITUDE\",\n", + " \"y\": \"LATITUDE\",\n", + " \"fill\": \"MAG_IGRF90\",\n", + " \"interpolate\": \"random-walk\",\n", + " },\n", + " ),\n", + " Plot.frame(),\n", + " ],\n", + " }\n", + ")" ] }, { @@ -259,7 +283,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Sometimes a plot specification includes some JavaScript code. To add those to a plot specification we have to pass it as a string and wrap it into the `js()` method:" + "Sometimes a plot specification includes some JavaScript code. To add those to a plot specification we have to pass it as a string and wrap it into the `js()` method:\n" ] }, { @@ -268,37 +292,40 @@ "metadata": {}, "outputs": [], "source": [ - "from pyobsplot import js\n", "from datetime import datetime\n", "\n", - "ipos = pl.read_csv(\"https://github.com/juba/pyobsplot/raw/main/doc/data/ipos.csv\", try_parse_dates=True).filter(\n", - " pl.col(\"date\") > datetime(1991, 1, 1)\n", - ")\n", + "from pyobsplot import js\n", "\n", + "ipos = pl.read_csv(\n", + " \"https://github.com/juba/pyobsplot/raw/main/doc/data/ipos.csv\", try_parse_dates=True\n", + ").filter(pl.col(\"date\") > datetime(1991, 1, 1))\n", "\n", - "op_jsdom({\n", - " \"insetRight\": 10,\n", - " \"height\": 600,\n", - " \"width\": 600,\n", - " \"marks\": [\n", - " Plot.dot(\n", - " ipos, Plot.dodgeY({\"x\": \"date\", \"r\": \"rMVOP\", \"fill\": \"currentColor\"})\n", - " ),\n", - " Plot.text(\n", - " ipos,\n", - " Plot.dodgeY(\n", - " {\n", - " \"filter\": js(\"(d) => d.rMVOP > 5e3\"),\n", - " \"x\": \"date\",\n", - " \"r\": \"rMVOP\",\n", - " \"text\": js(\"d => (d.rMVOP / 1e3).toFixed()\"),\n", - " \"fill\": \"white\",\n", - " \"fontWeight\": \"bold\",\n", - " }\n", + "\n", + "op_jsdom(\n", + " {\n", + " \"insetRight\": 10,\n", + " \"height\": 600,\n", + " \"width\": 600,\n", + " \"marks\": [\n", + " Plot.dot(\n", + " ipos, Plot.dodgeY({\"x\": \"date\", \"r\": \"rMVOP\", \"fill\": \"currentColor\"})\n", + " ),\n", + " Plot.text(\n", + " ipos,\n", + " Plot.dodgeY(\n", + " {\n", + " \"filter\": js(\"(d) => d.rMVOP > 5e3\"),\n", + " \"x\": \"date\",\n", + " \"r\": \"rMVOP\",\n", + " \"text\": js(\"d => (d.rMVOP / 1e3).toFixed()\"),\n", + " \"fill\": \"white\",\n", + " \"fontWeight\": \"bold\",\n", + " }\n", + " ),\n", " ),\n", - " ),\n", - " ],\n", - "})" + " ],\n", + " }\n", + ")" ] } ], @@ -318,7 +345,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.11" + "version": "3.11.9" }, "orig_nbformat": 4 },