{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "f68b777f",
   "metadata": {},
   "source": [
    "# Pearson's Correlation\n",
    "\n",
    "Consider the following data from [^1], which studied the relationship between free proline (an amino acid) and total collagen (a protein often found in connective tissue) in unhealthy human livers.\n",
    "\n",
    "The `x` and `y` arrays below record measurements of the two compounds. The observations are paired: each free proline measurement was taken from the same liver as the total collagen measurement at the same index."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "555457f4",
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "# total collagen (mg/g dry weight of liver)\n",
    "x = np.array([7.1, 7.1, 7.2, 8.3, 9.4, 10.5, 11.4])\n",
    "# free proline (μ mole/g dry weight of liver)\n",
    "y = np.array([2.8, 2.9, 2.8, 2.6, 3.5, 4.6, 5.0])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6fcb8fc7",
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "fig, ax = plt.subplots(figsize=(8, 5))\n",
    "ax.plot(x, y, '.')\n",
    "ax.set_xlabel(\"total collagen (mg/g)\")\n",
    "ax.set_ylabel(\"free proline (μ mole/g)\")\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "19a20bf8",
   "metadata": {},
   "source": [
    "These data were analyzed in [^2] using Spearman’s correlation coefficient, a statistic sensitive to monotonic correlation between the samples. Here, we will analyze the data using Pearson's correlation coefficient (`{class}`scipy.stats.pearsonr`) which is sensitive to linear correlation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8c2546b7",
   "metadata": {},
   "outputs": [],
   "source": [
    "from scipy import stats\n",
    "res = stats.pearsonr(x, y)\n",
    "res.statistic"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ed2b2e7a",
   "metadata": {},
   "source": [
    "The value of this statistic tends to be high (close to 1) for samples with a strongly positive linear correlation, low (close to -1) for samples with a strongly negative linear correlation, and small in magnitude (close to zero) for samples with weak linear correlation.\n",
    "\n",
    "The test is performed by comparing the observed value of the statistic against the null distribution: the distribution of statistic values derived under the null hypothesis that total collagen and free proline measurements are drawn from independent normal distributions.\n",
    "\n",
    "Under the null hypothesis, the population correlation coefficient is zero, and the sample correlation coefficent follows the beta distribution on the interval $(-1, 1)$ with shape parameters $a = b = \\frac{n}{2}-1$, where $n$ is the number of observations in each sample."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "098c1338",
   "metadata": {},
   "outputs": [],
   "source": [
    "n = len(x)  # len(x) == len(y)\n",
    "a = b = n/2 - 1  # shape parameter\n",
    "loc, scale = -1, 2  # support is (-1, 1)\n",
    "dist = stats.beta(a=a, b=b, loc=loc, scale=scale)\n",
    "r_vals = np.linspace(-1, 1, 1000)\n",
    "pdf = dist.pdf(r_vals)\n",
    "fig, ax = plt.subplots(figsize=(8, 5))\n",
    "def plot(ax):  # we'll re-use this\n",
    "    ax.plot(r_vals, pdf)\n",
    "    ax.set_title(\"Pearson's R Test Null Distribution\")\n",
    "    ax.set_xlabel(\"statistic\")\n",
    "    ax.set_ylabel(\"probability density\")\n",
    "plot(ax)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a622c796",
   "metadata": {},
   "source": [
    "The comparison is quantified by the p-value: the proportion of values in the null distribution as extreme or more extreme than the observed value of the statistic. In a two-sided test in which the statistic is positive, elements of the null distribution greater than the transformed statistic and elements of the null distribution less than the negative of the observed statistic are both considered \"more extreme\"."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7667b277",
   "metadata": {},
   "outputs": [],
   "source": [
    "fig, ax = plt.subplots(figsize=(8, 5))\n",
    "plot(ax)\n",
    "rs = res.statistic  # original statistic\n",
    "pvalue = dist.cdf(-rs) + dist.sf(rs)\n",
    "annotation = (f'p-value={pvalue:.4f}\\n(shaded area)')\n",
    "props = dict(facecolor='black', width=1, headwidth=5, headlength=8)\n",
    "_ = ax.annotate(annotation, (rs, 0.01), (0.25, 0.1), arrowprops=props)\n",
    "i = r_vals >= rs\n",
    "ax.fill_between(r_vals[i], y1=0, y2=pdf[i], color='C0')\n",
    "i = r_vals <= -rs\n",
    "ax.fill_between(r_vals[i], y1=0, y2=pdf[i], color='C0')\n",
    "ax.set_xlim(-1.1, 1.1)\n",
    "ax.set_ylim(0, 0.9)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "742b416f",
   "metadata": {},
   "outputs": [],
   "source": [
    "res.pvalue  # two-sided p-value"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cf5a1ccd",
   "metadata": {},
   "source": [
    "If the p-value is \"small\" - that is, if there is a low probability of sampling data from independent normal distributions that produces such an extreme value of the statistic - this may be taken as evidence against the null hypothesis in favor of the alternative: the distribution of total collagen and free proline are not independent. Note that:\n",
    "\n",
    "- The inverse is not true; that is, the test is not used to provide evidence for the null hypothesis.\n",
    "- The threshold for values that will be considered \"small\" is a choice that should be made before the data is analyzed [^3] with consideration of the risks of both false positives (incorrectly rejecting the null hypothesis) and false negatives (failure to reject a false null hypothesis).\n",
    "- Small p-values are not evidence for a large effect; rather, they can only provide evidence for a \"significant\" effect, meaning that they are unlikely to have occurred under the null hypothesis.\n",
    "\n",
    "Suppose that before performing the experiment, the authors had reason to predict a positive linear correlation between the total collagen and free proline measurements, and that they had chosen to assess the plausibility of the null hypothesis against a one-sided alternative: free proline has a positive linear correlation with total collagen. In this case, only those values in the null distribution that are as great or greater than the observed statistic would be considered more extreme."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "518364d7",
   "metadata": {},
   "outputs": [],
   "source": [
    "res = stats.pearsonr(x, y, alternative='greater')\n",
    "res.statistic\n",
    "fig, ax = plt.subplots(figsize=(8, 5))\n",
    "plot(ax)\n",
    "pvalue = dist.sf(rs)\n",
    "annotation = (f'p-value={pvalue:.6f}\\n(shaded area)')\n",
    "props = dict(facecolor='black', width=1, headwidth=5, headlength=8)\n",
    "_ = ax.annotate(annotation, (rs, 0.01), (0.86, 0.04), arrowprops=props)\n",
    "i = r_vals >= rs\n",
    "ax.fill_between(r_vals[i], y1=0, y2=pdf[i], color='C0')\n",
    "ax.set_xlim(0.85, 1)\n",
    "ax.set_ylim(0, 0.1)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "911dba2e",
   "metadata": {},
   "outputs": [],
   "source": [
    "res.pvalue  # one-sided p-value; half of the two-sided p-value"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0bf39202",
   "metadata": {},
   "source": [
    "Note that the beta distribution is the exact null distribution for samples of any size under this null hypothesis. We can check this by computing a Monte Carlo null distribution: explicitly drawing samples from independent normal distributions and computing Pearson's statistic for each pair."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "627158cc",
   "metadata": {},
   "outputs": [],
   "source": [
    "rng = np.random.default_rng(332520619051409741187796892627751113442)\n",
    "\n",
    "def statistic(x, y, axis):\n",
    "    return stats.pearsonr(x, y, axis=axis).statistic  # ignore pvalue\n",
    "    \n",
    "ref = stats.monte_carlo_test((x, y), rvs=(rng.standard_normal, rng.standard_normal),\n",
    "                             statistic=statistic, alternative='greater', n_resamples=9999)\n",
    "\n",
    "fig, ax = plt.subplots(figsize=(8, 5))\n",
    "plot(ax)\n",
    "ax.hist(ref.null_distribution, np.linspace(-1, 1, 26), density=True)\n",
    "ax.legend(['exact null distribution (independent, normally-distributed observations)',\n",
    "           f'Monte Carlo null distribution \\n({len(ref.null_distribution)} permutations)'])\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8362268c",
   "metadata": {},
   "source": [
    "This is often a reasonable null hypothesis to test, but in other cases, it may be more appropriate to perform a permutation test: Under the null hypothesis that total collagen and free proline are independent (but not necessarily normally distributed), each of the free proline measurements are equally likely to be observed with any of the total collagen measurements. Therefore, we can form an exact null distribution by calculating the statistic under each possible pairing of elements between `x` and `y`. This is the null distribution used when we provide `pearsonr` with `method=stats.PermutationMethod()`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "49708958",
   "metadata": {},
   "outputs": [],
   "source": [
    "res = stats.pearsonr(x, y, alternative='greater', method=stats.PermutationMethod())\n",
    "res.pvalue"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cd2c4fdb",
   "metadata": {},
   "source": [
    "## References\n",
    "\n",
    "[^1]: Kershenobich, D., Fierro, F. J., & Rojkind, M. (1970). The relationship\n",
    "between the free pool of proline and collagen content in human liver cirrhosis.\n",
    "The Journal of Clinical Investigation, 49(12), 2246-2249.\n",
    "\n",
    "[^2]: Hollander, M., Wolfe, D. A., & Chicken, E. (2013). Nonparametric\n",
    "statistical methods. John Wiley & Sons.\n",
    "\n",
    "[^3]: Phipson, B. and Smyth, G. K. (2010). \"Permutation P-values Should Never Be\n",
    "Zero: Calculating Exact P-values When Permutations Are Randomly Drawn.\"\n",
    "Statistical Applications in Genetics and Molecular Biology 9.1."
   ]
  }
 ],
 "metadata": {
  "jupytext": {
   "default_lexer": "ipython3",
   "text_representation": {
    "extension": ".md",
    "format_name": "myst",
    "format_version": 0.13,
    "jupytext_version": "1.16.4"
   }
  },
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
