{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f2e5a85d-c710-492b-a4fc-09b45ae26471",
   "metadata": {
    "tags": [
     "hide"
    ]
   },
   "outputs": [],
   "source": [
    "import seaborn.objects as so\n",
    "from seaborn import load_dataset\n",
    "penguins = load_dataset(\"penguins\")"
   ]
  },
  {
   "cell_type": "raw",
   "id": "14b5927c-42f1-4934-adee-3d380b8b3228",
   "metadata": {},
   "source": [
    "When used without any arguments, a small amount of jitter will be applied along the orientation axis:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bc1b4941-bbe6-4afc-b51a-0ac67cbe417d",
   "metadata": {},
   "outputs": [],
   "source": [
    "(\n",
    "    so.Plot(penguins, \"species\", \"body_mass_g\")\n",
    "    .add(so.Dots(), so.Jitter())\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "id": "1101690e-6c19-4219-aa4e-180798454df1",
   "metadata": {},
   "source": [
    "The `width` parameter controls the amount of jitter relative to the spacing between the marks:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c4251b9d-8b11-4c2c-905c-2f3b523dee70",
   "metadata": {},
   "outputs": [],
   "source": [
    "(\n",
    "    so.Plot(penguins, \"species\", \"body_mass_g\")\n",
    "    .add(so.Dots(), so.Jitter(.5))\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "id": "38aa639a-356e-4674-970b-53d55379b2b7",
   "metadata": {},
   "source": [
    "The `width` parameter always applies to the orientation axis, so the direction of jitter will adapt along with the orientation:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1cfe1c07-7e81-45a0-a989-240503046133",
   "metadata": {},
   "outputs": [],
   "source": [
    "(\n",
    "    so.Plot(penguins, \"body_mass_g\", \"species\")\n",
    "    .add(so.Dots(), so.Jitter(.5))\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "id": "0f5de4cc-3383-4503-8b59-9c48230a12a5",
   "metadata": {},
   "source": [
    "Because the `width` jitter is relative, it can be used when the orientation axis is numeric without further tweaking:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c94c41e8-29c4-4439-a5d1-0b8ffb244890",
   "metadata": {},
   "outputs": [],
   "source": [
    "(\n",
    "    so.Plot(penguins[\"body_mass_g\"].round(-3), penguins[\"flipper_length_mm\"])\n",
    "    .add(so.Dots(), so.Jitter())\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "id": "dd982dfa-fd9f-4edc-8190-18f0e101ae1a",
   "metadata": {},
   "source": [
    "In contrast to `width`, the `x` and `y` parameters always refer to specific axes and control the jitter in data units:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b0f2e5ca-68ad-4439-a4ee-f32f65682e95",
   "metadata": {},
   "outputs": [],
   "source": [
    "(\n",
    "    so.Plot(penguins[\"body_mass_g\"].round(-3), penguins[\"flipper_length_mm\"])\n",
    "    .add(so.Dots(), so.Jitter(x=100))\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "id": "a90ba526-8043-42ed-8f57-36445c163c0d",
   "metadata": {},
   "source": [
    "Both `x` and `y` can be used in a single transform:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6c07ed1d-ac77-4b30-90a8-e1b8760f9fad",
   "metadata": {},
   "outputs": [],
   "source": [
    "(\n",
    "    so.Plot(\n",
    "        penguins[\"body_mass_g\"].round(-3),\n",
    "        penguins[\"flipper_length_mm\"].round(-1),\n",
    "    )\n",
    "    .add(so.Dots(), so.Jitter(x=200, y=5))\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bb04c7a2-93f0-44cf-aacf-0eb436d0f14b",
   "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
}
