{
 "cells": [
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    ".. _relational_tutorial:\n",
    "\n",
    ".. currentmodule:: seaborn"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Visualizing statistical relationships\n",
    "=====================================\n",
    "\n",
    "Statistical analysis is a process of understanding how variables in a dataset relate to each other and how those relationships depend on other variables. Visualization can be a core component of this process because, when data are visualized properly, the human visual system can see trends and patterns that indicate a relationship.\n",
    "\n",
    "We will discuss three seaborn functions in this tutorial. The one we will use most is :func:`relplot`. This is a :doc:`figure-level function <function_overview>` for visualizing statistical relationships using two common approaches: scatter plots and line plots. :func:`relplot` combines a :class:`FacetGrid` with one of two axes-level functions:\n",
    "\n",
    "- :func:`scatterplot` (with ``kind=\"scatter\"``; the default)\n",
    "- :func:`lineplot` (with ``kind=\"line\"``)\n",
    "\n",
    "As we will see, these functions can be quite illuminating because they use simple and easily-understood representations of data that can nevertheless represent complex dataset structures. They can do so because they plot two-dimensional graphics that can be enhanced by mapping up to three additional variables using the semantics of hue, size, and style."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import pandas as pd\n",
    "import matplotlib.pyplot as plt\n",
    "import seaborn as sns\n",
    "sns.set_theme(style=\"darkgrid\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "hide"
    ]
   },
   "outputs": [],
   "source": [
    "%matplotlib inline\n",
    "np.random.seed(sum(map(ord, \"relational\")))"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    ".. _scatterplot_tutorial:\n",
    "\n",
    "Relating variables with scatter plots\n",
    "-------------------------------------\n",
    "\n",
    "The scatter plot is a mainstay of statistical visualization. It depicts the joint distribution of two variables using a cloud of points, where each point represents an observation in the dataset. This depiction allows the eye to infer a substantial amount of information about whether there is any meaningful relationship between them.\n",
    "\n",
    "There are several ways to draw a scatter plot in seaborn. The most basic, which should be used when both variables are numeric, is the :func:`scatterplot` function. In the :ref:`categorical visualization tutorial <categorical_tutorial>`, we will see specialized tools for using scatterplots to visualize categorical data. The :func:`scatterplot` is the default ``kind`` in :func:`relplot` (it can also be forced by setting ``kind=\"scatter\"``):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tips = sns.load_dataset(\"tips\")\n",
    "sns.relplot(data=tips, x=\"total_bill\", y=\"tip\")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "While the points are plotted in two dimensions, another dimension can be added to the plot by coloring the points according to a third variable. In seaborn, this is referred to as using a \"hue semantic\", because the color of the point gains meaning:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.relplot(data=tips, x=\"total_bill\", y=\"tip\", hue=\"smoker\")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "To emphasize the difference between the classes, and to improve accessibility, you can use a different marker style for each class:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.relplot(\n",
    "    data=tips,\n",
    "    x=\"total_bill\", y=\"tip\", hue=\"smoker\", style=\"smoker\"\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "It's also possible to represent four variables by changing the hue and style of each point independently. But this should be done carefully, because the eye is much less sensitive to shape than to color:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.relplot(\n",
    "    data=tips,\n",
    "    x=\"total_bill\", y=\"tip\", hue=\"smoker\", style=\"time\",\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "In the examples above, the hue semantic was categorical, so the default :ref:`qualitative palette <palette_tutorial>` was applied. If the hue semantic is numeric (specifically, if it can be cast to float), the default coloring switches to a sequential palette:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.relplot(\n",
    "    data=tips, x=\"total_bill\", y=\"tip\", hue=\"size\",\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "In both cases, you can customize the color palette. There are many options for doing so. Here, we customize a sequential palette using the string interface to :func:`cubehelix_palette`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.relplot(\n",
    "    data=tips, \n",
    "    x=\"total_bill\", y=\"tip\",\n",
    "    hue=\"size\", palette=\"ch:r=-.5,l=.75\"\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "The third kind of semantic variable changes the size of each point:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.relplot(data=tips, x=\"total_bill\", y=\"tip\", size=\"size\")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Unlike with :func:`matplotlib.pyplot.scatter`, the literal value of the variable is not used to pick the area of the point. Instead, the range of values in data units is normalized into a range in area units. This range can be customized:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.relplot(\n",
    "    data=tips, x=\"total_bill\", y=\"tip\",\n",
    "    size=\"size\", sizes=(15, 200)\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "More examples for customizing how the different semantics are used to show statistical relationships are shown in the :func:`scatterplot` API examples."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    ".. _lineplot_tutorial:\n",
    "\n",
    "Emphasizing continuity with line plots\n",
    "--------------------------------------\n",
    "\n",
    "Scatter plots are highly effective, but there is no universally optimal type of visualisation. Instead, the visual representation should be adapted for the specifics of the dataset and to the question you are trying to answer with the plot.\n",
    "\n",
    "With some datasets, you may want to understand changes in one variable as a function of time, or a similarly continuous variable. In this situation, a good choice is to draw a line plot. In seaborn, this can be accomplished by the :func:`lineplot` function, either directly or with :func:`relplot` by setting ``kind=\"line\"``:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dowjones = sns.load_dataset(\"dowjones\")\n",
    "sns.relplot(data=dowjones, x=\"Date\", y=\"Price\", kind=\"line\")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Aggregation and representing uncertainty\n",
    "~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n",
    "\n",
    "More complex datasets will have multiple measurements for the same value of the ``x`` variable. The default behavior in seaborn is to aggregate the multiple measurements at each ``x`` value by plotting the mean and the 95% confidence interval around the mean:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fmri = sns.load_dataset(\"fmri\")\n",
    "sns.relplot(data=fmri, x=\"timepoint\", y=\"signal\", kind=\"line\")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "The confidence intervals are computed using bootstrapping, which can be time-intensive for larger datasets. It's therefore possible to disable them:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.relplot(\n",
    "    data=fmri, kind=\"line\",\n",
    "    x=\"timepoint\", y=\"signal\", errorbar=None,\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Another good option, especially with larger data, is to represent the spread of the distribution at each timepoint by plotting the standard deviation instead of a confidence interval:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.relplot(\n",
    "    data=fmri, kind=\"line\",\n",
    "    x=\"timepoint\", y=\"signal\", errorbar=\"sd\",\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "To turn off aggregation altogether, set the ``estimator`` parameter to ``None`` This might produce a strange effect when the data have multiple observations at each point."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.relplot(\n",
    "    data=fmri, kind=\"line\",\n",
    "    x=\"timepoint\", y=\"signal\",\n",
    "    estimator=None,\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Plotting subsets of data with semantic mappings\n",
    "~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n",
    "\n",
    "The :func:`lineplot` function has the same flexibility as :func:`scatterplot`: it can show up to three additional variables by modifying the hue, size, and style of the plot elements. It does so using the same API as :func:`scatterplot`, meaning that we don't need to stop and think about the parameters that control the look of lines vs. points in matplotlib.\n",
    "\n",
    "Using semantics in :func:`lineplot` will also determine how the data get aggregated. For example, adding a hue semantic with two levels splits the plot into two lines and error bands, coloring each to indicate which subset of the data they correspond to."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.relplot(\n",
    "    data=fmri, kind=\"line\",\n",
    "    x=\"timepoint\", y=\"signal\", hue=\"event\",\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Adding a style semantic to a line plot changes the pattern of dashes in the line by default:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.relplot(\n",
    "    data=fmri, kind=\"line\",\n",
    "    x=\"timepoint\", y=\"signal\",\n",
    "    hue=\"region\", style=\"event\",\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "But you can identify subsets by the markers used at each observation, either together with the dashes or instead of them:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.relplot(\n",
    "    data=fmri, kind=\"line\",\n",
    "    x=\"timepoint\", y=\"signal\", hue=\"region\", style=\"event\",\n",
    "    dashes=False, markers=True,\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "As with scatter plots, be cautious about making line plots using multiple semantics. While sometimes informative, they can also be difficult to parse and interpret. But even when you are only examining changes across one additional variable, it can be useful to alter both the color and style of the lines. This can make the plot more accessible when printed to black-and-white or viewed by someone with color blindness:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.relplot(\n",
    "    data=fmri, kind=\"line\",\n",
    "    x=\"timepoint\", y=\"signal\", hue=\"event\", style=\"event\",\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "When you are working with repeated measures data (that is, you have units that were sampled multiple times), you can also plot each sampling unit separately without distinguishing them through semantics. This avoids cluttering the legend:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.relplot(\n",
    "    data=fmri.query(\"event == 'stim'\"), kind=\"line\",\n",
    "    x=\"timepoint\", y=\"signal\", hue=\"region\",\n",
    "    units=\"subject\", estimator=None,\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "The default colormap and handling of the legend in :func:`lineplot` also depends on whether the hue semantic is categorical or numeric:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dots = sns.load_dataset(\"dots\").query(\"align == 'dots'\")\n",
    "sns.relplot(\n",
    "    data=dots, kind=\"line\",\n",
    "    x=\"time\", y=\"firing_rate\",\n",
    "    hue=\"coherence\", style=\"choice\",\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "It may happen that, even though the ``hue`` variable is numeric, it is poorly represented by a linear color scale. That's the case here, where the levels of the ``hue`` variable are logarithmically scaled. You can provide specific color values for each line by passing a list or dictionary:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "palette = sns.cubehelix_palette(light=.8, n_colors=6)\n",
    "sns.relplot(\n",
    "    data=dots, kind=\"line\", \n",
    "    x=\"time\", y=\"firing_rate\",\n",
    "    hue=\"coherence\", style=\"choice\", palette=palette,\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Or you can alter how the colormap is normalized:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from matplotlib.colors import LogNorm\n",
    "palette = sns.cubehelix_palette(light=.7, n_colors=6)\n",
    "sns.relplot(\n",
    "    data=dots.query(\"coherence > 0\"), kind=\"line\",\n",
    "    x=\"time\", y=\"firing_rate\",\n",
    "    hue=\"coherence\", style=\"choice\",\n",
    "    hue_norm=LogNorm(),\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "The third semantic, size, changes the width of the lines:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.relplot(\n",
    "    data=dots, kind=\"line\",\n",
    "    x=\"time\", y=\"firing_rate\",\n",
    "    size=\"coherence\", style=\"choice\",\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "While the ``size`` variable will typically be numeric, it's also possible to map a categorical variable with the width of the lines. Be cautious when doing so, because it will be difficult to distinguish much more than \"thick\" vs \"thin\" lines. However, dashes can be hard to perceive when lines have high-frequency variability, so using different widths may be more effective in that case:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.relplot(\n",
    "    data=dots, kind=\"line\",\n",
    "    x=\"time\", y=\"firing_rate\",\n",
    "    hue=\"coherence\", size=\"choice\", palette=palette,\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Controlling sorting and orientation\n",
    "~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n",
    "\n",
    "Because :func:`lineplot` assumes that you are most often trying to draw ``y`` as a function of ``x``, the default behavior is to sort the data by the ``x`` values before plotting. However, this can be disabled:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "healthexp = sns.load_dataset(\"healthexp\").sort_values(\"Year\")\n",
    "sns.relplot(\n",
    "    data=healthexp, kind=\"line\",\n",
    "    x=\"Spending_USD\", y=\"Life_Expectancy\", hue=\"Country\",\n",
    "    sort=False\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "It's also possible to sort (and aggregate) along the y axis:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.relplot(\n",
    "    data=fmri, kind=\"line\",\n",
    "     x=\"signal\", y=\"timepoint\", hue=\"event\",\n",
    "    orient=\"y\",\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Showing multiple relationships with facets\n",
    "------------------------------------------\n",
    "\n",
    "We've emphasized in this tutorial that, while these functions *can* show several semantic variables at once, it's not always effective to do so. But what about when you do want to understand how a relationship between two variables depends on more than one other variable?\n",
    "\n",
    "The best approach may be to make more than one plot. Because :func:`relplot` is based on the :class:`FacetGrid`, this is easy to do. To show the influence of an additional variable, instead of assigning it to one of the semantic roles in the plot, use it to \"facet\" the visualization. This means that you make multiple axes and plot subsets of the data on each of them:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.relplot(\n",
    "    data=tips,\n",
    "    x=\"total_bill\", y=\"tip\", hue=\"smoker\", col=\"time\",\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "You can also show the influence of two variables this way: one by faceting on the columns and one by faceting on the rows. As you start adding more variables to the grid, you may want to decrease the figure size. Remember that the size :class:`FacetGrid` is parameterized by the height and aspect ratio of *each facet*:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "hide"
    ]
   },
   "outputs": [],
   "source": [
    "subject_number = fmri[\"subject\"].str[1:].astype(int)\n",
    "fmri= fmri.iloc[subject_number.argsort()]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.relplot(\n",
    "    data=fmri, kind=\"line\",\n",
    "    x=\"timepoint\", y=\"signal\", hue=\"subject\",\n",
    "    col=\"region\", row=\"event\", height=3,\n",
    "    estimator=None\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "When you want to examine effects across many levels of a variable, it can be a good idea to facet that variable on the columns and then \"wrap\" the facets into the rows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.relplot(\n",
    "    data=fmri.query(\"region == 'frontal'\"), kind=\"line\",\n",
    "    x=\"timepoint\", y=\"signal\", hue=\"event\", style=\"event\",\n",
    "    col=\"subject\", col_wrap=5,\n",
    "    height=3, aspect=.75, linewidth=2.5,\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "These visualizations, which are sometimes called \"lattice\" plots or \"small-multiples\", are very effective because they present the data in a format that makes it easy for the eye to detect both overall patterns and deviations from those patterns. While you should make use of the flexibility afforded by :func:`scatterplot` and :func:`relplot`, always try to keep in mind that several simple plots are usually more effective than one complex plot."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "celltoolbar": "Tags",
  "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": 4
}
