{
 "cells": [
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    ".. _regression_tutorial:\n",
    "\n",
    ".. currentmodule:: seaborn"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Estimating regression fits\n",
    "=========================="
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Many datasets contain multiple quantitative variables, and the goal of an analysis is often to relate those variables to each other. We :ref:`previously discussed <distribution_tutorial>` functions that can accomplish this by showing the joint distribution of two variables. It can be very helpful, though, to use statistical models to estimate a simple relationship between two noisy sets of observations. The functions discussed in this chapter will do so through the common framework of linear regression.\n",
    "\n",
    "In the spirit of Tukey, the regression plots in seaborn are primarily intended to add a visual guide that helps to emphasize patterns in a dataset during exploratory data analyses. That is to say that seaborn is not itself a package for statistical analysis. To obtain quantitative measures related to the fit of regression models, you should use `statsmodels <https://www.statsmodels.org/>`_. The goal of seaborn, however, is to make exploring a dataset through visualization quick and easy, as doing so is just as (if not more) important than exploring a dataset through tables of statistics."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "hide"
    ]
   },
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import seaborn as sns\n",
    "import matplotlib.pyplot as plt\n",
    "sns.set_theme(color_codes=True)\n",
    "np.random.seed(sum(map(ord, \"regression\")))"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Functions for drawing linear regression models\n",
    "----------------------------------------------\n",
    "\n",
    "The two functions that can be used to visualize a linear fit are :func:`regplot` and :func:`lmplot`.\n",
    "\n",
    "In the simplest invocation, both functions draw a scatterplot of two variables, ``x`` and ``y``, and then fit the regression model ``y ~ x`` and plot the resulting regression line and a 95% confidence interval for that regression:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tips = sns.load_dataset(\"tips\")\n",
    "sns.regplot(x=\"total_bill\", y=\"tip\", data=tips);"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.lmplot(x=\"total_bill\", y=\"tip\", data=tips);"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "These functions draw similar plots, but :func:`regplot` is an :doc:`axes-level function </tutorial/function_overview>`, and :func:`lmplot` is a figure-level function. Additionally, :func:`regplot` accepts the ``x`` and ``y`` variables in a variety of formats including simple numpy arrays, :class:`pandas.Series` objects, or as references to variables in a :class:`pandas.DataFrame` object passed to `data`. In contrast, :func:`lmplot` has `data` as a required parameter and the `x` and `y` variables must be specified as strings. Finally, only :func:`lmplot` has `hue` as a parameter.\n",
    "\n",
    "The core functionality is otherwise similar, though, so this tutorial will focus on :func:`lmplot`:.\n",
    "\n",
    "It's possible to fit a linear regression when one of the variables takes discrete values, however, the simple scatterplot produced by this kind of dataset is often not optimal:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.lmplot(x=\"size\", y=\"tip\", data=tips);"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "One option is to add some random noise (\"jitter\") to the discrete values to make the distribution of those values more clear. Note that jitter is applied only to the scatterplot data and does not influence the regression line fit itself:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.lmplot(x=\"size\", y=\"tip\", data=tips, x_jitter=.05);"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "A second option is to collapse over the observations in each discrete bin to plot an estimate of central tendency along with a confidence interval:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.lmplot(x=\"size\", y=\"tip\", data=tips, x_estimator=np.mean);"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Fitting different kinds of models\n",
    "---------------------------------\n",
    "\n",
    "The simple linear regression model used above is very simple to fit, however, it is not appropriate for some kinds of datasets. The `Anscombe's quartet <https://en.wikipedia.org/wiki/Anscombe%27s_quartet>`_ dataset shows a few examples where simple linear regression provides an identical estimate of a relationship where simple visual inspection clearly shows differences. For example, in the first case, the linear regression is a good model:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "anscombe = sns.load_dataset(\"anscombe\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.lmplot(x=\"x\", y=\"y\", data=anscombe.query(\"dataset == 'I'\"),\n",
    "           ci=None, scatter_kws={\"s\": 80});"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "The linear relationship in the second dataset is the same, but the plot clearly shows that this is not a good model:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.lmplot(x=\"x\", y=\"y\", data=anscombe.query(\"dataset == 'II'\"),\n",
    "           ci=None, scatter_kws={\"s\": 80});"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "In the presence of these kind of higher-order relationships, :func:`lmplot` and :func:`regplot` can fit a polynomial regression model to explore simple kinds of nonlinear trends in the dataset:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.lmplot(x=\"x\", y=\"y\", data=anscombe.query(\"dataset == 'II'\"),\n",
    "           order=2, ci=None, scatter_kws={\"s\": 80});"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "A different problem is posed by \"outlier\" observations that deviate for some reason other than the main relationship under study:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.lmplot(x=\"x\", y=\"y\", data=anscombe.query(\"dataset == 'III'\"),\n",
    "           ci=None, scatter_kws={\"s\": 80});"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "In the presence of outliers, it can be useful to fit a robust regression, which uses a different loss function to downweight relatively large residuals:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.lmplot(x=\"x\", y=\"y\", data=anscombe.query(\"dataset == 'III'\"),\n",
    "           robust=True, ci=None, scatter_kws={\"s\": 80});"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "When the ``y`` variable is binary, simple linear regression also \"works\" but provides implausible predictions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tips[\"big_tip\"] = (tips.tip / tips.total_bill) > .15\n",
    "sns.lmplot(x=\"total_bill\", y=\"big_tip\", data=tips,\n",
    "           y_jitter=.03);"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "The solution in this case is to fit a logistic regression, such that the regression line shows the estimated probability of ``y = 1`` for a given value of ``x``:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.lmplot(x=\"total_bill\", y=\"big_tip\", data=tips,\n",
    "           logistic=True, y_jitter=.03);"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Note that the logistic regression estimate is considerably more computationally intensive (this is true of robust regression as well). As the confidence interval around the regression line is computed using a bootstrap procedure, you may wish to turn this off for faster iteration (using ``ci=None``).\n",
    "\n",
    "An altogether different approach is to fit a nonparametric regression using a `lowess smoother <https://en.wikipedia.org/wiki/Local_regression>`_. This approach has the fewest assumptions, although it is computationally intensive and so currently confidence intervals are not computed at all:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.lmplot(x=\"total_bill\", y=\"tip\", data=tips,\n",
    "           lowess=True, line_kws={\"color\": \"C1\"});"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "The :func:`residplot` function can be a useful tool for checking whether the simple regression model is appropriate for a dataset. It fits and removes a simple linear regression and then plots the residual values for each observation. Ideally, these values should be randomly scattered around ``y = 0``:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.residplot(x=\"x\", y=\"y\", data=anscombe.query(\"dataset == 'I'\"),\n",
    "              scatter_kws={\"s\": 80});"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "If there is structure in the residuals, it suggests that simple linear regression is not appropriate:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.residplot(x=\"x\", y=\"y\", data=anscombe.query(\"dataset == 'II'\"),\n",
    "              scatter_kws={\"s\": 80});"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Conditioning on other variables\n",
    "-------------------------------\n",
    "\n",
    "The plots above show many ways to explore the relationship between a pair of variables. Often, however, a more interesting question is \"how does the relationship between these two variables change as a function of a third variable?\" This is where the main differences between :func:`regplot` and :func:`lmplot` appear. While :func:`regplot` always shows a single relationship, :func:`lmplot` combines :func:`regplot` with :class:`FacetGrid` to show multiple fits using `hue` mapping or faceting.\n",
    "\n",
    "The best way to separate out a relationship is to plot both levels on the same axes and to use color to distinguish them:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.lmplot(x=\"total_bill\", y=\"tip\", hue=\"smoker\", data=tips);"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Unlike :func:`relplot`, it's not possible to map a distinct variable to the style properties of the scatter plot, but you can redundantly code the `hue` variable with marker shape:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.lmplot(x=\"total_bill\", y=\"tip\", hue=\"smoker\", data=tips,\n",
    "           markers=[\"o\", \"x\"], palette=\"Set1\");"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "To add another variable, you can draw multiple \"facets\" with each level of the variable appearing in the rows or columns of the grid:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.lmplot(x=\"total_bill\", y=\"tip\", hue=\"smoker\", col=\"time\", data=tips);"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.lmplot(x=\"total_bill\", y=\"tip\", hue=\"smoker\",\n",
    "           col=\"time\", row=\"sex\", data=tips, height=3);"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Plotting a regression in other contexts\n",
    "---------------------------------------\n",
    "\n",
    "A few other seaborn functions use :func:`regplot` in the context of a larger, more complex plot. The first is the :func:`jointplot` function that we introduced in the :ref:`distributions tutorial <distribution_tutorial>`. In addition to the plot styles previously discussed, :func:`jointplot` can use :func:`regplot` to show the linear regression fit on the joint axes by passing ``kind=\"reg\"``:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.jointplot(x=\"total_bill\", y=\"tip\", data=tips, kind=\"reg\");"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Using the :func:`pairplot` function with ``kind=\"reg\"`` combines :func:`regplot` and :class:`PairGrid` to show the linear relationship between variables in a dataset. Take care to note how this is different from :func:`lmplot`. In the figure below, the two axes don't show the same relationship conditioned on two levels of a third variable; rather, :func:`PairGrid` is used to show multiple relationships between different pairings of the variables in a dataset:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.pairplot(tips, x_vars=[\"total_bill\", \"size\"], y_vars=[\"tip\"],\n",
    "             height=5, aspect=.8, kind=\"reg\");"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Conditioning on an additional categorical variable is built into both of these functions using the ``hue`` parameter:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.pairplot(tips, x_vars=[\"total_bill\", \"size\"], y_vars=[\"tip\"],\n",
    "             hue=\"smoker\", height=5, aspect=.8, kind=\"reg\");"
   ]
  }
 ],
 "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
}
