{
 "cells": [
  {
   "cell_type": "raw",
   "id": "fb8e120d-5dcf-483b-a0d1-74857d09ce7d",
   "metadata": {},
   "source": [
    ".. currentmodule:: seaborn.objects"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9252d5a5-8af1-4f99-b799-ee044329fb23",
   "metadata": {
    "tags": [
     "hide"
    ]
   },
   "outputs": [],
   "source": [
    "import seaborn.objects as so\n",
    "from seaborn import load_dataset\n",
    "penguins = load_dataset(\"penguins\")\n",
    "diamonds = load_dataset(\"diamonds\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ae85e302-354c-46ca-a17f-aaec7ed1cbd6",
   "metadata": {},
   "source": [
    "Assigning a faceting variable will create multiple subplots and plot subsets of the data on each of them:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d65405fd-cf28-4248-8e51-1aa1999354a2",
   "metadata": {},
   "outputs": [],
   "source": [
    "p = so.Plot(penguins, \"bill_length_mm\", \"bill_depth_mm\").add(so.Dots())\n",
    "p.facet(\"species\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2b9630aa-3b46-4e72-82ef-5717c2d8c686",
   "metadata": {},
   "source": [
    "Multiple faceting variables can be defined to create a two-dimensional grid:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1857144f-1373-4704-9332-d3fc649ceb9d",
   "metadata": {},
   "outputs": [],
   "source": [
    "p.facet(\"species\", \"sex\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7664e2d2-c254-44b4-9973-88e1d013fb3d",
   "metadata": {},
   "source": [
    "Facet variables can be provided as references to the global plot data or as vectors:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6569616d-480b-4b8c-a761-f5bd2bde60e3",
   "metadata": {},
   "outputs": [],
   "source": [
    "p.facet(penguins[\"island\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "198f63a0-bb0f-40c4-b790-bd15f8656acb",
   "metadata": {},
   "source": [
    "With a single faceting variable, arrange the facets or limit to a subset by passing a list of levels to `order`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b1344f7f-50d0-4592-b4fb-ab81d97a4798",
   "metadata": {},
   "outputs": [],
   "source": [
    "p.facet(\"species\", order=[\"Gentoo\", \"Adelie\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2090297c-414f-4448-a930-5b6f0de18deb",
   "metadata": {},
   "source": [
    "With multiple variables, pass `order` as a dictionary:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "58ed1b13-71a7-462a-af99-78be566268a6",
   "metadata": {},
   "outputs": [],
   "source": [
    "p.facet(\"species\", \"sex\", order={\"col\": [\"Gentoo\", \"Adelie\"], \"row\": [\"Female\", \"Male\"]})"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e440f14d-24b2-4f83-a247-0bb917f9f4c3",
   "metadata": {},
   "source": [
    "When the faceting variable has multiple levels, you can `wrap` it to distribute subplots across both dimensions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "92baf66c-6dd9-4f50-adf2-386c4daab094",
   "metadata": {},
   "outputs": [],
   "source": [
    "p = so.Plot(diamonds, x=\"carat\", y=\"price\").add(so.Dots())\n",
    "p.facet(\"color\", wrap=4)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8d0872cb-e261-4796-b81e-a416fea85201",
   "metadata": {},
   "source": [
    "Wrapping works only when there is a single variable, but you can wrap in either direction:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c5a66a64-bfba-437c-80be-1311e85cf5a5",
   "metadata": {},
   "outputs": [],
   "source": [
    "p.facet(row=\"color\", wrap=2)"
   ]
  },
  {
   "cell_type": "raw",
   "id": "e1bdaad7-5883-45ad-af39-c10183569bdc",
   "metadata": {},
   "source": [
    "Use :meth:`Plot.share` to specify whether facets should be scaled the same way:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "14c1f977-79d4-4f9c-a846-1fd70ad3569e",
   "metadata": {},
   "outputs": [],
   "source": [
    "p.facet(\"clarity\", wrap=3).share(x=False)"
   ]
  },
  {
   "cell_type": "raw",
   "id": "a4fc64d9-b7ba-4061-8160-63d8fd89e47a",
   "metadata": {},
   "source": [
    "Use :meth:`Plot.label` to tweak the titles:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4206b12c-d7a3-419f-b278-6edfe487c5de",
   "metadata": {},
   "outputs": [],
   "source": [
    "p.facet(\"color\").label(title=\"{} grade\".format)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "28b4fb9d-2bb0-40ff-a541-5f300aca6200",
   "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
}
