Skip to content

Commit

Permalink
doc: update introduction notebook to "format" API
Browse files Browse the repository at this point in the history
  • Loading branch information
@juba
juba committed May 26, 2024
1 parent f096815 commit 44754e3
Showing 1 changed file with 118 additions and 91 deletions.
209 changes: 118 additions & 91 deletions examples/introduction.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
"\n",
"## Getting started\n",
"\n",
"First, we install the package:"
"First, we install the package:\n"
]
},
{
Expand All @@ -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"
]
},
{
Expand All @@ -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"
]
},
{
Expand All @@ -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",
")"
]
},
{
Expand All @@ -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",
")"
]
},
{
Expand All @@ -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"
]
},
{
Expand All @@ -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"
]
},
{
Expand All @@ -124,26 +143,29 @@
"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",
")"
]
},
{
"attachments": {},
"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"
]
},
{
Expand All @@ -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"
]
},
{
Expand All @@ -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"
]
},
{
Expand All @@ -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"
]
},
{
Expand All @@ -213,15 +235,15 @@
"metadata": {},
"outputs": [],
"source": [
"op_jsdom = Obsplot(renderer=\"jsdom\")"
"op_jsdom = Obsplot(format=\"png\")"
]
},
{
"attachments": {},
"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"
]
},
{
Expand All @@ -232,34 +254,36 @@
"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",
")"
]
},
{
"attachments": {},
"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"
]
},
{
Expand All @@ -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",
")"
]
}
],
Expand All @@ -318,7 +345,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.10.11"
"version": "3.11.9"
},
"orig_nbformat": 4
},
Expand Down

0 comments on commit 44754e3

Please sign in to comment.