diff --git a/doc/nextgen/api.rst b/doc/nextgen/api.rst index 5305a5bb37..a33c9d0e4d 100644 --- a/doc/nextgen/api.rst +++ b/doc/nextgen/api.rst @@ -22,6 +22,8 @@ Plot interface Plot.facet Plot.pair Plot.configure + Plot.limit + Plot.label Plot.on Plot.plot Plot.save @@ -36,6 +38,7 @@ Marks Area Bar + Bars Dot Line Lines diff --git a/doc/nextgen/conf.py b/doc/nextgen/conf.py index 29fe9ac22c..7620443b72 100644 --- a/doc/nextgen/conf.py +++ b/doc/nextgen/conf.py @@ -61,7 +61,7 @@ html_theme_options = { "show_prev_next": False, - "page_sidebar_items": [], + # "page_sidebar_items": [], } html_context = { @@ -69,6 +69,8 @@ "default_mode": "light" } +html_show_sourcelink = False + # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". @@ -77,10 +79,13 @@ html_logo = "_static/logo.svg" html_sidebars = { - # "**": [], - "demo": ["page-toc"] + "index": [], + "demo": ["page-toc.html"], } +html_context= { + "default_mode": "light", +} # -- Intersphinx ------------------------------------------------ diff --git a/doc/nextgen/demo.ipynb b/doc/nextgen/demo.ipynb index cc6e1dc24c..54ab7688e8 100644 --- a/doc/nextgen/demo.ipynb +++ b/doc/nextgen/demo.ipynb @@ -637,7 +637,7 @@ "metadata": {}, "outputs": [], "source": [ - "so.Plot(planets, x=\"distance\").add(so.Bar(), so.Hist()).scale(x=\"log\")" + "so.Plot(planets, x=\"distance\").add(so.Bars(), so.Hist()).scale(x=\"log\")" ] }, { @@ -660,7 +660,7 @@ " planets, x=\"distance\",\n", " color=(planets[\"number\"] > 1).rename(\"multiple\")\n", " )\n", - " .add(so.Bar(), so.Hist(), so.Dodge())\n", + " .add(so.Bars(), so.Hist(), so.Dodge())\n", " .scale(x=\"log\", color=so.Nominal())\n", ")" ] @@ -821,6 +821,34 @@ "Importantly, there's no distinction between \"axes-level\" and \"figure-level\" here. Any kind of plot can be faceted or paired by adding a method call to the `Plot` definition, without changing anything else about how you are creating the figure." ] }, + { + "cell_type": "markdown", + "id": "9933b5fa-5b1a-4e05-a4d3-b2142e5337ef", + "metadata": {}, + "source": [ + "------\n", + "\n", + "## Customization\n", + "\n", + "This API is less developed than other aspects of the new interface, but it will be possible to customize various aspects of the plot through the seaborn interface, without dropping down to matplotlib:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "61c2e0e2-1df5-466d-a17e-0bc64d21f9f9", + "metadata": {}, + "outputs": [], + "source": [ + "(\n", + " so.Plot(tips, \"day\", \"total_bill\", color=\"sex\")\n", + " .add(so.Bar(), so.Agg(), so.Dodge())\n", + " .scale(y=so.Continuous().label(like=\"${x:.0f}\"))\n", + " .label(x=str.capitalize, y=\"Total bill\", color=None)\n", + " .limit(y=(0, 28))\n", + ")" + ] + }, { "cell_type": "markdown", "id": "d1eff6ab-84dd-4b32-9923-3d29fb43a209", diff --git a/doc/nextgen/index.ipynb b/doc/nextgen/index.ipynb index a785218ef0..c58dbc406a 100644 --- a/doc/nextgen/index.ipynb +++ b/doc/nextgen/index.ipynb @@ -40,13 +40,21 @@ "id": "c76dbb00-20ee-4508-bca3-76a4763e5640", "metadata": {}, "source": [ - "## Testing the alpha release\n", + "## Testing the pre-release\n", "\n", - "If you're interested, please install the alpha and kick the tires. It is very far from complete, so expect some rough edges and instability! But feedback will be very helpful in pushing this towards a more stable broad release:\n", + "If you're interested, please install the pre-release and kick the tires. It is still a work in progress, so expect some rough edges and instability! But feedback will be very helpful in pushing this towards a more stable broad release:\n", "\n", - " pip install https://github.com/mwaskom/seaborn/archive/refs/tags/v0.12.0a0.tar.gz\n", + " pip install --pre seaborn" + ] + }, + { + "cell_type": "markdown", + "id": "f194cc12-856a-4261-8717-462c290c9e51", + "metadata": {}, + "source": [ + "## Preview components\n", "\n", - "The documentation is still a work in progress, but there's a reasonably thorough demo of the main parts, and some basic API documentation for the existing classes." + "The formal documentation is still a work-in-progress, so this preview serves as an introduction and reference for testing. There's a reasonably thorough demo of the main components and some basic API documentation for the existing classes:" ] }, { @@ -57,8 +65,8 @@ ".. toctree::\n", " :maxdepth: 1\n", "\n", - " demo\n", - " api" + " Demonstration \n", + " API Overview " ] }, { @@ -76,7 +84,7 @@ "\n", "So the new interface is designed to provide a more comprehensive experience, such that all of the steps involved in the creation of a reasonably-customized plot can be accomplished in the same way. And the compositional nature of the objects provides much more flexibility than currently exists in seaborn with a similar level of abstraction: this lets you focus on *what* you want to show rather than *how* to show it.\n", "\n", - "One will note that the result looks a bit (a lot?) like ggplot. That's not unintentional, but the goal is also *not* to \"port ggplot2 to Python\". (If that's what you're looking for, check out the very nice [plotnine](https://plotnine.readthedocs.io/en/stable/) package). There is an immense amount of wisdom in the grammar of graphics and in its particular implementation as ggplot2. But, as languages, R and Python are just too different for idioms from one to feel natural when translated literally into the other. So while I have taken much inspiration from ggplot (along with vega-lite, d3, and other great libraries), I've also made plenty of choices differently, for better or for worse." + "One will note that the result looks a bit (a lot?) like ggplot. That's not unintentional: while the original seaborn interface was never explicitly intended to implement a grammar of graphics, the redesign is. But the goal is also *not* to \"port ggplot2 to Python\". (If that's what you're looking for, check out the very nice [plotnine](https://plotnine.readthedocs.io/en/stable/) package). I do think that ggplot2 gets a lot right, especially its approach to layering. But, as languages, R and Python are just too different for idioms from one to feel natural when translated literally into the other. So while I have taken much inspiration from ggplot (along with vega-lite, d3, and other great libraries), I've also made plenty of choices differently, for better or for worse." ] }, { diff --git a/doc/nextgen/index.rst b/doc/nextgen/index.rst index a494884a31..f5001a59b0 100644 --- a/doc/nextgen/index.rst +++ b/doc/nextgen/index.rst @@ -37,27 +37,31 @@ with the new interface: -Testing the alpha release -------------------------- +Testing the pre-release +----------------------- -If you’re interested, please install the alpha and kick the tires. It is -very far from complete, so expect some rough edges and instability! But -feedback will be very helpful in pushing this towards a more stable -broad release: +If you’re interested, please install the pre-release and kick the tires. +It is still a work in progress, so expect some rough edges and +instability! But feedback will be very helpful in pushing this towards a +more stable broad release: :: - pip install https://github.com/mwaskom/seaborn/archive/refs/tags/v0.12.0a0.tar.gz + pip install --pre seaborn -The documentation is still a work in progress, but there’s a reasonably -thorough demo of the main parts, and some basic API documentation for -the existing classes. +Preview components +------------------ + +The formal documentation is still a work-in-progress, so this preview +serves as an introduction and reference for testing. There’s a +reasonably thorough demo of the main components and some basic API +documentation for the existing classes: .. toctree:: :maxdepth: 1 - demo - api + Demonstration + API Overview Background and goals -------------------- @@ -91,14 +95,15 @@ currently exists in seaborn with a similar level of abstraction: this lets you focus on *what* you want to show rather than *how* to show it. One will note that the result looks a bit (a lot?) like ggplot. That’s -not unintentional, but the goal is also *not* to “port ggplot2 to -Python”. (If that’s what you’re looking for, check out the very nice -`plotnine `__ package). -There is an immense amount of wisdom in the grammar of graphics and in -its particular implementation as ggplot2. But, as languages, R and -Python are just too different for idioms from one to feel natural when -translated literally into the other. So while I have taken much -inspiration from ggplot (along with vega-lite, d3, and other great -libraries), I’ve also made plenty of choices differently, for better or -for worse. +not unintentional: while the original seaborn interface was never +explicitly intended to implement a grammar of graphics, the redesign is. +But the goal is also *not* to “port ggplot2 to Python”. (If that’s what +you’re looking for, check out the very nice +`plotnine `__ package). I do +think that ggplot2 gets a lot right, especially its approach to +layering. But, as languages, R and Python are just too different for +idioms from one to feel natural when translated literally into the +other. So while I have taken much inspiration from ggplot (along with +vega-lite, d3, and other great libraries), I’ve also made plenty of +choices differently, for better or for worse.