Skip to content

Commit

Permalink
Add docstrings and API examples for remaining transform objects (#3088)
Browse files Browse the repository at this point in the history 
* Add docstrings for Agg and Est stats

* Add Dodge docstring

* Add docstrings for Stack and Shift

* Add Norm docstring
  • Loading branch information
@mwaskom
mwaskom committed Oct 17, 2022
1 parent a42d62d commit 0f92224
Show file tree
Hide file tree
Showing 8 changed files with 813 additions and 0 deletions.
140 changes: 140 additions & 0 deletions doc/_docstrings/objects.Agg.ipynb
View file
@@ -0,0 +1,140 @@
{
"cells": [
{
"cell_type": "code",
"execution_count": null,
"id": "0d053943-66c9-410d-ad65-ce91f1c1ff48",
"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": "51b029af-b83b-4ae0-a6ff-f48bf9692518",
"metadata": {},
"source": [
"The default behavior is to aggregate by taking a mean over each group:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "28451b4e-9f4e-4604-b2b9-6138c4f51436",
"metadata": {},
"outputs": [],
"source": [
"p = so.Plot(diamonds, \"clarity\", \"carat\")\n",
"p.add(so.Bar(), so.Agg())"
]
},
{
"cell_type": "raw",
"id": "53859a3b-051c-423d-97ef-b03f647268b7",
"metadata": {},
"source": [
"Other aggregation functions can be selected by name if they are pandas methods:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "5beaac3a-b9f7-4acc-81c7-480599e3675e",
"metadata": {},
"outputs": [],
"source": [
"p.add(so.Bar(), so.Agg(\"median\"))"
]
},
{
"cell_type": "raw",
"id": "2d318ee3-56c1-4fd4-99a5-fa87db770f67",
"metadata": {},
"source": [
"It's also possible to pass an arbitrary aggregation function:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "bd11e289-7274-464a-b781-06fb756cf8de",
"metadata": {},
"outputs": [],
"source": [
"p.add(so.Bar(), so.Agg(lambda x: x.quantile(.75) - x.quantile(.25)))"
]
},
{
"cell_type": "raw",
"id": "555394c1-25f8-4932-94d1-f67a8a9fa1c6",
"metadata": {},
"source": [
"When other mapping variables are assigned, they'll be used to define aggregation groups. With some marks, it may be helpful to use additional transforms, such as :class:`objects.Dodge`:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "5755cdeb-1d1a-4434-9cc5-91024735eb4e",
"metadata": {},
"outputs": [],
"source": [
"p.add(so.Bar(), so.Agg(), so.Dodge(), color=\"cut\")"
]
},
{
"cell_type": "raw",
"id": "07eb1150-db57-4a58-b830-8a7aba9f46ec",
"metadata": {},
"source": [
"The variable that gets aggregated depends on the orientation of the layer, which is usually inferred from the coordinate variable types (but may also be specified with the `orient` parameter in :meth:`objects.Plot.add`):"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "1bdcc970-1b6c-4a3d-b0bc-6c7a625163ff",
"metadata": {},
"outputs": [],
"source": [
"so.Plot(diamonds, \"carat\", \"clarity\").add(so.Bar(), so.Agg())"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "ad8006ff-5472-4345-9537-a5680c519f4f",
"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
}
198 changes: 198 additions & 0 deletions doc/_docstrings/objects.Dodge.ipynb
View file
@@ -0,0 +1,198 @@
{
"cells": [
{
"cell_type": "code",
"execution_count": null,
"id": "4d44a940-db84-4e16-bc83-e67d08d6d56a",
"metadata": {
"tags": [
"hide"
]
},
"outputs": [],
"source": [
"import seaborn.objects as so\n",
"from seaborn import load_dataset\n",
"tips = load_dataset(\"tips\").astype({\"time\": str})"
]
},
{
"cell_type": "raw",
"id": "ce99e1a1-c213-478f-a5bc-d19e2c4d70db",
"metadata": {},
"source": [
"This transform modifies both the width and position (along the orientation axis) of marks that would otherwise overlap:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "f6a84062-2c2b-4a45-91cb-77f29462104d",
"metadata": {},
"outputs": [],
"source": [
"(\n",
" so.Plot(tips, \"day\", color=\"time\")\n",
" .add(so.Bar(), so.Count(), so.Dodge())\n",
")"
]
},
{
"cell_type": "raw",
"id": "55d3a9a8-c973-4e91-9f3a-bc137df15f48",
"metadata": {},
"source": [
"By default, empty space may appear when variables are not fully crossed:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "08ae1c65-5ad9-47a3-a8f3-d901bd4821f2",
"metadata": {},
"outputs": [],
"source": [
"p = so.Plot(tips, \"day\", color=\"time\")\n",
"p.add(so.Bar(), so.Count(), so.Dodge())"
]
},
{
"cell_type": "raw",
"id": "2125f07d-4210-4d49-8761-bcfa3f9c67f5",
"metadata": {},
"source": [
"The `empty` parameter handles this case; use it to fill out the space:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "c2314343-de73-45d7-9595-acf5f7d62e93",
"metadata": {},
"outputs": [],
"source": [
"p.add(so.Bar(), so.Count(), so.Dodge(empty=\"fill\"))"
]
},
{
"cell_type": "raw",
"id": "08f4382c-842e-4777-a452-1d88251da6e7",
"metadata": {},
"source": [
"Or center the marks while using a consistent width:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "1e0745e4-be11-4703-bf9c-4b13cbb76e91",
"metadata": {},
"outputs": [],
"source": [
"p.add(so.Bar(), so.Count(), so.Dodge(empty=\"drop\"))"
]
},
{
"cell_type": "raw",
"id": "7d29ec53-caef-4cff-9828-dc242adb5c49",
"metadata": {},
"source": [
"Use `gap` to add a bit of spacing between dodged marks:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "342aca16-c67b-4bc4-9101-fec6c398aa0f",
"metadata": {},
"outputs": [],
"source": [
"p = so.Plot(tips, \"day\", \"total_bill\", color=\"sex\")\n",
"p.add(so.Bar(), so.Agg(\"sum\"), so.Dodge(gap=.1))"
]
},
{
"cell_type": "raw",
"id": "68b52dcb-c5e7-4186-b61f-e96fac5f4d40",
"metadata": {},
"source": [
"When multiple semantic variables are used, each distinct group will be dodged:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "497f3e3b-39bc-4381-85bb-be5bb5c60b1f",
"metadata": {},
"outputs": [],
"source": [
"p.add(so.Dot(), so.Dodge(), fill=\"smoker\")"
]
},
{
"cell_type": "raw",
"id": "795835d2-904f-4343-89c2-b91be9c1c504",
"metadata": {},
"source": [
"Use `by` to dodge only a subset of variables:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "da01f6c0-c425-409c-a010-5cb52a794dc9",
"metadata": {},
"outputs": [],
"source": [
"p.add(so.Dot(), so.Dodge(by=[\"color\"]), fill=\"smoker\")"
]
},
{
"cell_type": "raw",
"id": "77de77da-2fad-4374-9d14-90520e448c90",
"metadata": {},
"source": [
"When combining with other transforms (such as :class:`Jitter` or :class:`Stack`), be mindful of the order that they are applied in:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "29ccabd6-6bd5-4563-a337-f8f8d25f7dad",
"metadata": {},
"outputs": [],
"source": [
"p.add(so.Dot(), so.Dodge(), so.Jitter())"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "a73fe9a5-c717-41fd-874e-be72334ea6d4",
"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
}

0 comments on commit 0f92224

Please sign in to comment.