{
 "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.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
