{
  "cells": [
    {
      "cell_type": "markdown",
      "id": "plot-intro",
      "metadata": {},
      "source": "# Aner Plot: from observations to a story\n\nRun All with a compatible chart enabled Aner `0.0.2-dev.1` runtime and development editor extension 0.1.46. Charts appear under their producing cells in both production and development mode. This notebook uses shared variables. Every numeric dataset is synthetic; the offline USA/world maps use Natural Earth boundaries. See the [Aner Plot guide](https://anerlang.org/docs/plot) for the design, API, scientific limits, and geographic guidance. These development features are separate from published download versions.\n"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "plot-data-theme",
      "metadata": {},
      "outputs": [],
      "source": [
        "import aner.plot\n",
        "let weeks = List(1.0, 2.0, 3.0, 4.0, 5.0, 6.0)\n",
        "let response = List(12.0, 15.0, 14.0, 19.0, 21.0, 23.0)\n",
        "let reference = List(10.0, 12.0, 13.0, 14.0, 16.0, 17.0)\n",
        "let company = plot.theme(\"light\").company(\n",
        "    name: \"Example Research\",\n",
        "    background: \"#FFFFFF\",\n",
        "    foreground: \"#17233B\",\n",
        "    colors: List(\"#007C91\", \"#C6601D\", \"#6950A1\")\n",
        ")\n"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "plot-trend-context",
      "metadata": {},
      "source": "## Lead with a supported takeaway\n\nThe title states what these supplied values show. The axes include units; the caption identifies the data and comparison. The annotation labels an observation. The reference line is supplied, not fitted, and this example does not establish causality. A bare top level chart value displays automatically in a shared notebook session; `.show()` also works and is explicit inside functions or loops.\n"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "plot-trend",
      "metadata": {},
      "outputs": [],
      "source": [
        "let trend = plot.line(x: weeks, y: response)\n",
        "    .add_line(x: weeks, y: reference, name: \"Reference\")\n",
        "    .title(\"Response increased across six synthetic observations\")\n",
        "    .labels(x: \"Week\", y: \"Response (arbitrary units)\")\n",
        "    .caption(\"Synthetic sequences; reference values are supplied, not fitted.\")\n",
        "    .annotate(x: 6.0, y: 23.0, text: \"Last observation\")\n",
        "    .theme(company)\n",
        "    .size(width: 900, height: 560)\n",
        "trend\n"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "plot-theme-context",
      "metadata": {},
      "source": "## Reuse the chart with a dark theme\n\nChart modifiers return new snapshots. Changing the presentation for this output leaves `trend` unchanged. An arbitrary custom palette is not automatically perceptually uniform or accessible; retain text and legends as well as color.\n"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "plot-dark",
      "metadata": {},
      "outputs": [],
      "source": [
        "let dark = plot.theme(\"dark\").palette(colors: List(\"#79D2E0\", \"#FFBC78\", \"#C6ACFF\"))\n",
        "trend.theme(dark).show()\n"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "plot-scatter-context",
      "metadata": {},
      "source": "## Show individual observations\n\nScatter marks preserve the supplied pairs without implying interpolation between them. This chart performs no regression or statistical test.\n"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "plot-scatter",
      "metadata": {},
      "outputs": [],
      "source": [
        "plot.scatter(x: weeks, y: response)\n",
        "    .title(\"Six individual synthetic observations\")\n",
        "    .labels(\"Week\", \"Response (arbitrary units)\")\n",
        "    .theme(company)\n",
        "    .show()\n"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "plot-bars-context",
      "metadata": {},
      "source": "## Make aggregation explicit\n\nBars display the supplied values. The library does not infer group means, sample sizes, denominators, or confidence intervals. The values here are invented counts.\n"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "plot-bars",
      "metadata": {},
      "outputs": [],
      "source": [
        "plot.bar(labels: List(\"Control\", \"Treatment\"), values: List(12.0, 18.0))\n",
        "    .title(\"Supplied counts by synthetic group\")\n",
        "    .labels(\"Group\", \"Count\")\n",
        "    .caption(\"Two supplied counts; no automatic aggregation.\")\n",
        "    .theme(company)\n",
        "    .show()\n"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "plot-distribution-context",
      "metadata": {},
      "source": "## Examine the distribution before summarizing it\n\nThe histogram uses four equal width bins and observed counts. The box plot shows sample spread. Its quartiles and whiskers are not confidence intervals or a measurement error model. Six observations are too few to justify a complex density story. Each call to `.show()` creates an output in this cell.\n"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "plot-distributions",
      "metadata": {},
      "outputs": [],
      "source": [
        "plot.histogram(values: response, bins: 4)\n",
        "    .title(\"Distribution of six synthetic responses\")\n",
        "    .labels(\"Response (arbitrary units)\", \"Observed count\")\n",
        "    .caption(\"Four equal-width bins; counts are not probability density.\")\n",
        "    .theme(plot.theme(\"light\"))\n",
        "    .show()\n",
        "plot.box(values: response)\n",
        "    .title(\"Observed sample spread\")\n",
        "    .labels(\"Synthetic sample\", \"Response (arbitrary units)\")\n",
        "    .caption(\"Quartiles and whiskers summarize observations, not confidence intervals.\")\n",
        "    .show()\n"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "plot-heatmap-context",
      "metadata": {},
      "source": "## Keep matrix orientation explicit\n\nThe values are supplied in row major order: the first three form the first row. Colors encode supplied magnitudes; the chart does not compute correlation, cluster rows, or standardize the matrix.\n"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "plot-heatmap",
      "metadata": {},
      "outputs": [],
      "source": [
        "plot.heatmap(values: List(1.0, 2.0, 3.0, 4.0, 5.0, 6.0), rows: 2, columns: 3)\n",
        "    .title(\"Six supplied row-major measurements\")\n",
        "    .labels(\"Column\", \"Row\")\n",
        "    .caption(\"Synthetic cells; color represents the supplied value.\")\n",
        "    .show()\n"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "plot-map-context",
      "metadata": {},
      "source": "## Join geographic values by a stable String key\n\nThis custom fixture contains two invented rectangles. Supply other licensed local GeoJSON with `plot.geojson(path)` and a String property such as FIPS/GEOID. Coordinates are longitude, latitude. The next examples also provide ready to use bundled USA/world boundaries. Preserve boundary attribution, date, join coverage, and rate denominators in real analyses. Missing coverage is not zero.\n"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "plot-map",
      "metadata": {},
      "outputs": [],
      "source": [
        "let geometry = \"{\\\"type\\\":\\\"FeatureCollection\\\",\\\"features\\\":[{\\\"type\\\":\\\"Feature\\\",\\\"properties\\\":{\\\"code\\\":\\\"A\\\"},\\\"geometry\\\":{\\\"type\\\":\\\"Polygon\\\",\\\"coordinates\\\":[[[0,0],[2,0],[2,2],[0,2],[0,0]]]}},{\\\"type\\\":\\\"Feature\\\",\\\"properties\\\":{\\\"code\\\":\\\"B\\\"},\\\"geometry\\\":{\\\"type\\\":\\\"Polygon\\\",\\\"coordinates\\\":[[[2,0],[4,0],[4,2],[2,2],[2,0]]]}}]}\"\n",
        "plot.choropleth(geojson: geometry, property: \"code\", keys: List(\"A\", \"B\"), values: List(12.0, 18.0))\n",
        "    .title(\"Two invented regions, joined by String code\")\n",
        "    .caption(\"Synthetic geometry and values; not real USA or world boundaries.\")\n",
        "    .show()\n"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "plot-world-context",
      "metadata": {},
      "source": "## Offline world map\n\nNatural Earth 1:110m country boundaries are embedded in the native interpreter. Keys use Natural Earth's `ADM0_A3` codes, including USA, CAN, and FRA, rather than country names. These codes are not uniformly ISO codes. Only three synthetic values are supplied; other features have no data. The equirectangular preview is not equal area or a distance measurement. See [boundary source and attribution](https://anerlang.org/docs/plot#boundary-source-and-attribution) for the pinned source, public domain terms, hashes, and coverage.\n"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "plot-world",
      "metadata": {},
      "outputs": [],
      "source": [
        "plot.world(keys: List(\"USA\", \"CAN\", \"FRA\"), values: List(12.0, 9.0, 15.0))\n",
        "    .title(\"Synthetic values on an offline world map\")\n",
        "    .caption(\"Synthetic values; boundaries: Natural Earth 1:110m, admin-0 codes.\")\n",
        "    .show()\n"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "plot-usa-context",
      "metadata": {},
      "source": "## Offline USA state map\n\nThe bundled state layer includes all 50 states and DC, joined by uppercase postal codes. Alaska and Hawaii remain at their geographic positions without relocated insets. The four supplied values are synthetic; states without supplied values are no data, not zero. County boundaries and territories require other supplied geometry.\n"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "plot-usa",
      "metadata": {},
      "outputs": [],
      "source": [
        "plot.usa(keys: List(\"CA\", \"CO\", \"NY\", \"TX\"), values: List(18.0, 12.0, 15.0, 9.0))\n",
        "    .title(\"Synthetic values for four USA states\")\n",
        "    .caption(\"Synthetic values; other states have no data, not zero. Natural Earth boundaries.\")\n",
        "    .theme(company)\n",
        "    .show()\n"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "plot-export-context",
      "metadata": {},
      "source": "## Export a reviewed figure\n\nCall `trend.save(\"response-comparison.svg\")` in a new code cell to write a fresh SVG file. Existing files are not replaced. `trend.svg()` returns the SVG text, and `trend.summary()` returns a plain description. Export is explicit so Run All does not create files.\n\nSaved notebook outputs are historical artifacts. Editing data or themes does not recompute previous outputs; restart and run the notebook in order to verify a fresh analysis. SVG output does not restore live interpreter values.\n"
    }
  ],
  "metadata": {
    "kernelspec": {
      "name": "aner",
      "display_name": "Aner",
      "language": "aner"
    },
    "language_info": {
      "name": "aner",
      "file_extension": ".aner",
      "mimetype": "text/x-aner"
    },
    "aner": {
      "status": "example",
      "execution_mode": "persistent-session"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 5
}