{
 "nbformat": 4,
 "nbformat_minor": 5,
 "metadata": {
  "kernelspec": {
   "name": "python3",
   "display_name": "Python 3",
   "language": "python"
  },
  "language_info": {
   "name": "python"
  },
  "colab": {
   "name": "eigenvector.ipynb"
  }
 },
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "# eigenvector \u2014 Python demo\n\nNumerical companion to the entry [eigenvector](https://dictionaryofml.org/terms/eigenvector.html) of the [Dictionary of Applied Machine Learning](https://dictionaryofml.org/): it recomputes what the entry states and prints one line per check.\n\nNumerical companion to the glossary entry 'eigenvector'. Each day of 2024 at the GeoSphere Austria weather station Krems an der Donau (station id 3805) is a data point with two features, its lowest and its highest temperature in degrees Celsius. The demo computes the sample covariance matrix C of these days, verifies the defining equation C u = lambda u for its two eigenvectors, shows that an eigenvector is determined only up to a nonzero factor (the eigenspace is the nullspace of C - lambda I), checks that the eigenvectors of the symmetric C are orthogonal while those of a non-symmetric matrix need not be, and confirms the claim the entry's figure makes: the average squared distance of the days from the line through the sample mean along the leading eigenvector equals the other eigenvalue.\n\nRequires NumPy and Matplotlib only, and uses fixed seeds, so the printed numbers reproduce exactly. Generated from [`pythondemos/eigenvector.py`](https://dictionaryofml.org/terms/eigenvector.py); CC BY 4.0.\n\nBefore running a downloaded copy, scan it: `uvx bandit -q -t B102,B307,B602,B605 eigenvector.py` (B102,B307,B602,B605 are the exec, eval and shell checks of [bandit](https://bandit.readthedocs.io/)) reports nothing: the script runs no shell command and evaluates no generated code."
  },
  {
   "cell_type": "code",
   "metadata": {},
   "execution_count": null,
   "outputs": [],
   "source": "# Notebook shim: the script resolves output paths relative to __file__,\n# which a notebook kernel does not define; everything lands in the\n# working directory instead.\nimport os\n__file__ = os.path.join(os.getcwd(), \"eigenvector.py\")\nos.makedirs(\"pythondemos\", exist_ok=True)"
  },
  {
   "cell_type": "code",
   "metadata": {},
   "execution_count": null,
   "outputs": [],
   "source": "\"\"\"The eigenvectors of the sample covariance matrix of the daily\ntemperatures at Krems an der Donau: the two directions that the matrix only\nrescales, and the line that leaves the smallest average squared distance.\n\nPurpose\n-------\nNumerical companion to the glossary entry 'eigenvector'.  Each day of 2024\nat the GeoSphere Austria weather station Krems an der Donau (station id\n3805) is a data point with two features, its lowest and its highest\ntemperature in degrees Celsius.  The demo computes the sample covariance\nmatrix C of these days, verifies the defining equation C u = lambda u for\nits two eigenvectors, shows that an eigenvector is determined only up to a\nnonzero factor (the eigenspace is the nullspace of C - lambda I), checks\nthat the eigenvectors of the symmetric C are orthogonal while those of a\nnon-symmetric matrix need not be, and confirms the claim the entry's figure\nmakes: the average squared distance of the days from the line through the\nsample mean along the leading eigenvector equals the other eigenvalue.\n\nSelf-contained (numpy and matplotlib only), fixed seed; the GeoSphere\ndownload falls back to the committed CSV.\n\nBlocks\n------\n[B-data]       Daily lowest and highest temperature at Krems for 2024 (366\n               days, no missing value) and their sample covariance matrix.\n[B-def]        The defining equation C u = lambda u for the two\n               eigenvectors of C, with eigenvalues 130.9 and 7.9 squared\n               degrees.\n[B-eigenspace] An eigenvector is determined only up to a nonzero factor:\n               rescaling one gives an eigenvector with the same eigenvalue,\n               and the eigenvectors belonging to one eigenvalue together\n               with the zero vector are the nullspace of C - lambda I.  For\n               the matrix 2 I every nonzero vector is an eigenvector, so\n               that nullspace is the whole plane.\n[B-orthogonal] The eigenvectors of the symmetric C are orthogonal and are\n               returned with unit norm, while the eigenvectors of the\n               non-symmetric matrix [[1.3, 0.8], [0.4, 0.9]] are not\n               orthogonal.\n[B-line]       The average squared distance of the 366 days from the line\n               through the sample mean along the leading eigenvector equals\n               the smaller eigenvalue; a line rotated away from that\n               eigenvector leaves a larger average.  Writes the CSV files\n               of the entry's figure.\n\nOutputs\n-------\neigenvector_weather.csv    : date, lowest and highest temperature of each\n                             day of 2024 (committed copy).\neigenvector_points.csv     : the 366 days as points (x1 = lowest,\n                             x2 = highest temperature, degrees Celsius).\neigenvector_points_plot.csv: every 19th of those days, the 20 drawn in the\n                             entry's figure.\neigenvector_line1.csv      : the line through the sample mean along the\n                             leading eigenvector, as two endpoints.\neigenvector_line2.csv      : the line through the sample mean along the\n                             second eigenvector, as two endpoints.\neigenvector_residuals.csv  : the 20 distance segments of the drawn days\n                             from the first line, separated by nan rows.\neigenvector_rotated.csv    : the average squared distance from a line\n                             rotated by an angle against the leading\n                             eigenvector, over 181 angles.\neigenvector.png            : matplotlib preview (checking only).\n\nData generated by pythondemos/eigenvector.py.\n\"\"\"\n\n# /// script\n# requires-python = \">=3.10\"\n# dependencies = [\"matplotlib==3.10.7\", \"numpy==2.3.4\"]\n# ///\n\nimport json\nimport urllib.request\nfrom pathlib import Path\n\nimport numpy as np\nimport matplotlib\n\nmatplotlib.use(\"Agg\")\nimport matplotlib.pyplot as plt\n\nOUT_DIR = Path(__file__).parent\n\nrng = np.random.default_rng(42)\nreport = []\n\n\ndef check(name, ok):\n    report.append((name, bool(ok)))\n    print(f\"  [{'ok' if ok else 'FAIL'}] {name}\")"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "**[B-data]** Daily lowest and highest temperature at Krems for 2024 (366 days, no missing value) and their sample covariance matrix."
  },
  {
   "cell_type": "code",
   "metadata": {},
   "execution_count": null,
   "outputs": [],
   "source": "print(\"[B-data] daily lowest and highest temperature at Krems, 2024\")\nPARAMS = [\"tlmin\", \"tlmax\"]\nURL = (\"https://dataset.api.hub.geosphere.at/v1/station/historical/\"\n       f\"klima-v2-1d?parameters={','.join(PARAMS)}&station_ids=3805\"\n       \"&start=2024-01-01&end=2024-12-31\")\nCSV = OUT_DIR / \"eigenvector_weather.csv\"\ntry:\n    with urllib.request.urlopen(URL, timeout=120) as resp:\n        payload = json.load(resp)\n    params = payload[\"features\"][0][\"properties\"][\"parameters\"]\n    stamps = [stamp[:10] for stamp in payload[\"timestamps\"]]\n    X = np.stack([np.array(params[p][\"data\"], dtype=float) for p in PARAMS], 1)\n    with open(CSV, \"w\") as fh:\n        fh.write(\"date,\" + \",\".join(PARAMS) + \"\\n\")\n        for day, row in zip(stamps, X):\n            fh.write(day + \",\" + \",\".join(f\"{v:g}\" for v in row) + \"\\n\")\n    print(f\"    downloaded {len(X)} days\")\nexcept (OSError, KeyError, ValueError) as err:\n    print(f\"    download failed ({err}); reading {CSV.name}\")\n    rows = np.genfromtxt(CSV, delimiter=\",\", skip_header=1, dtype=str)\n    stamps = [str(s) for s in rows[:, 0]]\n    X = rows[:, 1:].astype(float)\n\nm = len(X)\ncheck(\"[B-data] 366 days, each with its lowest and its highest temperature\",\n      X.shape == (366, 2))\ncheck(\"[B-data] no day is missing a temperature\", bool(np.all(np.isfinite(X))))\ncheck(\"[B-data] the record matches the archive (Feb 1: -3.8 to 10.4 degrees)\",\n      stamps[31] == \"2024-02-01\" and bool(np.allclose(X[31], [-3.8, 10.4])))\nmu = X.mean(axis=0)\nC = (X - mu).T @ (X - mu) / m\ncheck(f\"[B-data] sample mean ({mu[0]:.1f}, {mu[1]:.1f}) degrees; the sample \"\n      \"covariance matrix is symmetric\", bool(np.allclose(C, C.T)))\nprint(f\"    C = [[{C[0, 0]:.1f}, {C[0, 1]:.1f}], [{C[1, 0]:.1f}, \"\n      f\"{C[1, 1]:.1f}]] squared degrees\")"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "**[B-def]** The defining equation C u = lambda u for the two eigenvectors of C, with eigenvalues 130.9 and 7.9 squared degrees."
  },
  {
   "cell_type": "code",
   "metadata": {},
   "execution_count": null,
   "outputs": [],
   "source": "print(\"[B-def] the defining equation C u = lambda u\")\nlam, U = np.linalg.eigh(C)\norder = np.argsort(lam)[::-1]                   # largest eigenvalue first\nlam, U = lam[order], U[:, order]\nfor j in (0, 1):                                # the sign of an eigenvector\n    if U[0, j] < 0:                             # is arbitrary; fix x1 > 0\n        U[:, j] = -U[:, j]\ncheck(\"[B-def] both eigenvectors satisfy C u = lambda u to within 1e-13\",\n      all(np.linalg.norm(C @ U[:, j] - lam[j] * U[:, j]) < 1e-13\n          for j in (0, 1)))\ncheck(f\"[B-def] the eigenvalues are {lam[0]:.1f} and {lam[1]:.1f} squared \"\n      \"degrees\", bool(np.allclose(np.round(lam, 1), [130.9, 7.9])))\nprint(f\"    u1 = ({U[0, 0]:.2f}, {U[1, 0]:.2f}), \"\n      f\"u2 = ({U[0, 1]:.2f}, {U[1, 1]:.2f})\")\ncheck(\"[B-def] neither eigenvector is the zero vector\",\n      all(np.linalg.norm(U[:, j]) > 0.5 for j in (0, 1)))\nnotan = np.array([1.0, 0.0])                    # a direction C does tilt\ncheck(\"[B-def] the first coordinate direction is not an eigenvector: \"\n      f\"C e1 = ({(C @ notan)[0]:.1f}, {(C @ notan)[1]:.1f}) is off its line\",\n      abs((C @ notan)[1]) > 1e-6)"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "**[B-eigenspace]** An eigenvector is determined only up to a nonzero factor: rescaling one gives an eigenvector with the same eigenvalue, and the eigenvectors belonging to one eigenvalue together with the zero vector are the nullspace of C - lambda I. For the matrix 2 I every nonzero vector is an eigenvector, so that nullspace is the whole plane."
  },
  {
   "cell_type": "code",
   "metadata": {},
   "execution_count": null,
   "outputs": [],
   "source": "print(\"[B-eigenspace] the eigenspace is the nullspace of C - lambda I\")\nFACTOR = -3.7\ncheck(f\"[B-eigenspace] rescaling u1 by {FACTOR} gives an eigenvector with \"\n      \"the same eigenvalue\",\n      np.linalg.norm(C @ (FACTOR * U[:, 0]) - lam[0] * (FACTOR * U[:, 0]))\n      < 1e-12)\nranks = [np.linalg.matrix_rank(C - lam[j] * np.eye(2)) for j in (0, 1)]\ncheck(\"[B-eigenspace] C - lambda I has rank 1 for both eigenvalues, so each \"\n      \"eigenspace is a line through the origin\", ranks == [1, 1])\ncheck(\"[B-eigenspace] u2 spans the nullspace of C - lambda_2 I\",\n      np.linalg.norm((C - lam[1] * np.eye(2)) @ U[:, 1]) < 1e-12)\ntwice = 2.0 * np.eye(2)                         # repeated eigenvalue 2\nprobe = rng.normal(size=(5, 2))\ncheck(\"[B-eigenspace] for 2 I every nonzero vector is an eigenvector with \"\n      \"eigenvalue 2, so the eigenspace is the whole plane\",\n      np.linalg.matrix_rank(twice - 2.0 * np.eye(2)) == 0\n      and bool(np.allclose(probe @ twice.T, 2.0 * probe)))"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "**[B-orthogonal]** The eigenvectors of the symmetric C are orthogonal and are returned with unit norm, while the eigenvectors of the non-symmetric matrix [[1.3, 0.8], [0.4, 0.9]] are not orthogonal."
  },
  {
   "cell_type": "code",
   "metadata": {},
   "execution_count": null,
   "outputs": [],
   "source": "print(\"[B-orthogonal] orthogonality of the eigenvectors\")\ncheck(f\"[B-orthogonal] the two eigenvectors of C are orthogonal (inner \"\n      f\"product {U[:, 0] @ U[:, 1]:.1e})\", abs(U[:, 0] @ U[:, 1]) < 1e-14)\ncheck(\"[B-orthogonal] both are returned with unit norm\",\n      all(abs(np.linalg.norm(U[:, j]) - 1.0) < 1e-14 for j in (0, 1)))\nA = np.array([[1.3, 0.8], [0.4, 0.9]])          # not symmetric\na1, a2 = np.array([2.0, 1.0]), np.array([-1.0, 1.0])\ncheck(\"[B-orthogonal] the non-symmetric matrix [[1.3, 0.8], [0.4, 0.9]] has \"\n      \"the eigenvectors (2, 1) and (-1, 1)\",\n      np.linalg.norm(A @ a1 - 1.7 * a1) < 1e-12\n      and np.linalg.norm(A @ a2 - 0.5 * a2) < 1e-12)\ncheck(f\"[B-orthogonal] those two are not orthogonal (inner product \"\n      f\"{a1 @ a2:.0f})\", abs(a1 @ a2) > 0.5)"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "**[B-line]** The average squared distance of the 366 days from the line through the sample mean along the leading eigenvector equals the smaller eigenvalue; a line rotated away from that eigenvector leaves a larger average. Writes the CSV files of the entry's figure."
  },
  {
   "cell_type": "code",
   "metadata": {},
   "execution_count": null,
   "outputs": [],
   "source": "print(\"[B-line] the average squared distance from the eigenvector line\")\nproj = (X - mu) @ U[:, 0]                       # coordinate along u1\nfoot = mu + proj[:, None] * U[:, 0]             # closest point on the line\ndist2 = np.sum((X - foot) ** 2, axis=1)\ncheck(f\"[B-line] the average squared distance of the {m} days from the line \"\n      f\"through the sample mean along u1 is {dist2.mean():.1f} squared \"\n      f\"degrees, the eigenvalue {lam[1]:.1f}\",\n      abs(dist2.mean() - lam[1]) < 1e-10)\ncheck(f\"[B-line] the two eigenvalues sum to the total variance \"\n      f\"{np.trace(C):.1f} squared degrees, so the line leaves \"\n      f\"{100 * lam[1] / np.trace(C):.1f} percent of it\",\n      abs(lam.sum() - np.trace(C)) < 1e-10)\nANGLE = np.deg2rad(30.0)\nnormal = -np.sin(ANGLE) * U[:, 0] + np.cos(ANGLE) * U[:, 1]\nrot2 = (((X - mu) @ normal) ** 2).mean()\ncheck(f\"[B-line] a line rotated by 30 degrees against u1 leaves the larger \"\n      f\"average {rot2:.1f} squared degrees\", rot2 > lam[1] + 1.0)\nangles = np.linspace(-90.0, 90.0, 181)\nnormals = (-np.sin(np.deg2rad(angles))[:, None] * U[:, 0]\n           + np.cos(np.deg2rad(angles))[:, None] * U[:, 1])\nsweep = np.einsum(\"aj,jk,ak->a\", normals, C, normals)\ncheck(\"[B-line] over 181 rotation angles the smallest average squared \"\n      \"distance is attained at 0 degrees, along u1\",\n      int(np.argmin(sweep)) == 90 and abs(sweep.min() - lam[1]) < 1e-10)\ndirs = (np.cos(np.deg2rad(angles))[:, None] * U[:, 0]\n        + np.sin(np.deg2rad(angles))[:, None] * U[:, 1])\nspread = np.einsum(\"aj,jk,ak->a\", dirs, C, dirs)\ncheck(f\"[B-line] the days spread most widely along u1: their average \"\n      f\"squared distance from the sample mean along it is \"\n      f\"{proj.var():.1f} squared degrees, the eigenvalue {lam[0]:.1f} \"\n      f\"and the largest over the 181 directions\",\n      abs(proj.var() - lam[0]) < 1e-10\n      and int(np.argmax(spread)) == 90)\n\nnp.savetxt(OUT_DIR / \"eigenvector_points.csv\", X, delimiter=\",\",\n           header=\"x1,x2\", comments=\"\", fmt=\"%.1f\")\n# the entry's figure draws every 19th day, 20 of the 366, so the distance\n# segments stay legible; the eigenvectors come from all 366 days\nX_plot = X[::19]\ncheck(\"[B-line] every 19th day gives 20 days for the entry's figure\",\n      X_plot.shape[0] == 20)\nnp.savetxt(OUT_DIR / \"eigenvector_points_plot.csv\", X_plot, delimiter=\",\",\n           header=\"x1,x2\", comments=\"\", fmt=\"%.1f\")\nspan1 = 1.04 * np.abs(proj).max()\nwith open(OUT_DIR / \"eigenvector_line1.csv\", \"w\") as fh:\n    fh.write(\"x1,x2\\n\")\n    for t in (-span1, span1):\n        p = mu + t * U[:, 0]\n        fh.write(f\"{p[0]:.3f},{p[1]:.3f}\\n\")\nspan2 = 2.6 * np.sqrt(lam[1])\nwith open(OUT_DIR / \"eigenvector_line2.csv\", \"w\") as fh:\n    fh.write(\"x1,x2\\n\")\n    for t in (-span2, span2):\n        p = mu + t * U[:, 1]\n        fh.write(f\"{p[0]:.3f},{p[1]:.3f}\\n\")\nfoot_plot = foot[::19]\nwith open(OUT_DIR / \"eigenvector_residuals.csv\", \"w\") as fh:\n    fh.write(\"x1,x2\\n\")\n    for point, base in zip(X_plot, foot_plot):\n        fh.write(f\"{point[0]:.3f},{point[1]:.3f}\\n\")\n        fh.write(f\"{base[0]:.3f},{base[1]:.3f}\\n\")\n        fh.write(\"nan,nan\\n\")\nwith open(OUT_DIR / \"eigenvector_rotated.csv\", \"w\") as fh:\n    fh.write(\"angle,avgdist2\\n\")\n    for angle, value in zip(angles, sweep):\n        fh.write(f\"{angle:.1f},{value:.4f}\\n\")\ncheck(\"[B-line] the segment file holds 20 segments separated by nan rows\",\n      sum(1 for line in (OUT_DIR / \"eigenvector_residuals.csv\")\n          .read_text().splitlines() if line == \"nan,nan\") == 20)\n\n# ------------------------------------------------------------- preview\nfig, ax = plt.subplots(1, 2, figsize=(11.5, 5.4),\n                       gridspec_kw=dict(width_ratios=[1.25, 1]))\nax[0].plot(X_plot[:, 0], X_plot[:, 1], \"o\", color=\"black\", ms=4.5,\n           label=\"20 of the 366 days (filled circles)\")\nline1 = np.array([mu - span1 * U[:, 0], mu + span1 * U[:, 0]])\nline2 = np.array([mu - span2 * U[:, 1], mu + span2 * U[:, 1]])\nax[0].plot(line1[:, 0], line1[:, 1], \"k-\", lw=1.4,\n           label=\"line along $u^{(1)}$ (solid line)\")\nax[0].plot(line2[:, 0], line2[:, 1], \"k--\", lw=1.2,\n           label=\"line along $u^{(2)}$ (dashed line)\")\nfor point, base in zip(X_plot, foot_plot):\n    ax[0].plot([point[0], base[0]], [point[1], base[1]], \"k:\", lw=1.0)\nax[0].plot([], [], \"k:\", lw=1.0, label=\"distance to the line (dotted)\")\nax[0].plot(mu[0], mu[1], \"x\", color=\"black\", ms=9, mew=2,\n           label=\"sample mean (cross)\")\nax[0].set_aspect(\"equal\")\nax[0].set_xlabel(\"lowest temperature of the day in degrees Celsius\")\nax[0].set_ylabel(\"highest temperature of the day in degrees Celsius\")\nax[0].set_title(\"[B-line] the eigenvector line and the distances to it\")\nax[0].legend(frameon=False, fontsize=8, loc=\"upper center\",\n             bbox_to_anchor=(0.5, -0.14), ncol=2)\nax[1].plot(angles, sweep, \"k-\", lw=1.4,\n           label=\"average squared distance (solid curve)\")\nax[1].plot([0.0], [lam[1]], \"o\", color=\"black\", ms=6,\n           label=f\"minimum $\\\\lambda_2 = {lam[1]:.1f}$ at 0 degrees (circle)\")\nax[1].set_xlabel(\"rotation of the line against $u^{(1)}$ in degrees\")\nax[1].set_ylabel(\"average squared distance in squared degrees\")\nax[1].set_title(\"[B-line] the eigenvector line is the closest line\")\nax[1].legend(frameon=False, fontsize=8, loc=\"upper center\")\nfig.suptitle(\"Eigenvectors of the sample covariance matrix of the days of \"\n             \"2024 at Krems an der Donau\")\nfig.tight_layout()\nfig.savefig(OUT_DIR / \"eigenvector.png\", dpi=110)\n\nprint(f\"\\n{sum(ok for _, ok in report)}/{len(report)} checks passed\")\nassert all(ok for _, ok in report)"
  }
 ]
}