Add API examples

doc/_docstrings/objects.Perc.ipynb

@@ -0,0 +1,130 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2d44a326-029b-47ff-b560-5f4b6a4bb73f",
+   "metadata": {
+    "tags": [
+     "hide"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "import seaborn.objects as so\n",
+    "from seaborn import load_dataset\n",
+    "diamonds = load_dataset(\"diamonds\")"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "65e975a2-2559-4bf1-8851-8bbbf52bf22d",
+   "metadata": {},
+   "source": [
+    "The default behavior computes the quartiles and min/max of the input data:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "36f927f5-3b64-4871-a355-adadc4da769b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "p = (\n",
+    "    so.Plot(diamonds, \"cut\", \"price\")\n",
+    "    .scale(y=\"log\")\n",
+    ")\n",
+    "p.add(so.Dot(), so.Perc())"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "feba1b99-0f71-4b18-8e7e-bd5470cc2d0c",
+   "metadata": {},
+   "source": [
+    "Passing an integer will compute that many evenly-spaced percentiles:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f030dd39-1223-475a-93e1-1759a8971a6c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "p.add(so.Dot(), so.Perc(20))"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "85bd754b-122e-4475-8727-2d584a90a38e",
+   "metadata": {},
+   "source": [
+    "Passing a list will compute exactly those percentiles:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2fde7549-45b5-411a-afba-eb0da754d9e9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "p.add(so.Dot(), so.Perc([10, 25, 50, 75, 90]))"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "7be16a13-dfc8-4595-a904-42f9be10f4f6",
+   "metadata": {},
+   "source": [
+    "Combine with a range mark to show a percentile interval:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "05c561c6-0449-4a61-96d1-390611a1b694",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "(\n",
+    "    so.Plot(diamonds, \"price\", \"cut\")\n",
+    "    .add(so.Dots(pointsize=1, alpha=.2), so.Jitter(.3))\n",
+    "    .add(so.Range(color=\"k\"), so.Perc([25, 75]), so.Shift(y=.2))\n",
+    "    .scale(x=\"log\")\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d464157c-3187-49c1-9cd8-71f284ce4c50",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "py310",
+   "language": "python",
+   "name": "py310"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}