{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "0",
   "metadata": {},
   "source": [
    "# Tutorial 16 - Plotext Advanced Workflows\n",
    "\n",
    "This tutorial focuses on practical terminal workflows that are easy to miss when moving from Matplotlib to the Plotext backend: layer-by-layer output, subplot dashboards, terminal-safe files, and backend limitations."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1",
   "metadata": {},
   "outputs": [],
   "source": [
    "from pathlib import Path\n",
    "\n",
    "import matplotlib.patches as patches\n",
    "import numpy as np\n",
    "\n",
    "from maxplotlib import Canvas"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2",
   "metadata": {},
   "source": [
    "## 1. Build a terminal dashboard\n",
    "\n",
    "`Canvas.subplots()` works with Plotext too. Keep subplot titles short enough for a terminal and render with `keep_colors=False` when the output will be logged or tested."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3",
   "metadata": {},
   "outputs": [],
   "source": [
    "canvas, axes = Canvas.subplots(nrows=1, ncols=2)\n",
    "x = np.linspace(0, 2 * np.pi, 80)\n",
    "\n",
    "axes[0].plot(x, np.sin(x), label=\"signal\")\n",
    "axes[0].set_title(\"Signal\")\n",
    "axes[0].set_grid(True)\n",
    "axes[0].set_legend(True)\n",
    "\n",
    "axes[1].bar([0, 1, 2], [4, 7, 3], label=\"count\")\n",
    "axes[1].set_xticks([0, 1, 2], labels=[\"A\", \"B\", \"C\"])\n",
    "axes[1].set_title(\"Counts\")\n",
    "\n",
    "print(canvas.render(backend=\"plotext\").build(keep_colors=False))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4",
   "metadata": {},
   "source": [
    "## 2. Add uncertainty and annotations\n",
    "\n",
    "Error bars accept scalar, symmetric-array, and Matplotlib's two-row asymmetric-array forms. Reference lines, text, and annotations are rendered as terminal primitives."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5",
   "metadata": {},
   "outputs": [],
   "source": [
    "x = np.arange(5)\n",
    "y = np.array([1.0, 1.8, 1.3, 2.5, 2.0])\n",
    "canvas, ax = Canvas.subplots()\n",
    "ax.errorbar(\n",
    "    x,\n",
    "    y,\n",
    "    yerr=[[0.1] * 5, [0.25] * 5],\n",
    "    label=\"observations\",\n",
    ")\n",
    "ax.axhline(y.mean(), color=\"yellow\")\n",
    "ax.annotate(\"peak\", xy=(3, 2.5), xytext=(2, 2.8))\n",
    "ax.set_title(\"Measurements\")\n",
    "ax.set_legend(True)\n",
    "\n",
    "print(canvas.render(backend=\"plotext\").build(keep_colors=False))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6",
   "metadata": {},
   "source": [
    "## 3. Render layers incrementally\n",
    "\n",
    "Layers are useful for progress reports and debugging. Pass a list to `render(..., layers=[...])`, or use `savefig(..., layer_by_layer=True)` to write successive text files."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7",
   "metadata": {},
   "outputs": [],
   "source": [
    "canvas, ax = Canvas.subplots()\n",
    "ax.plot(x, y, label=\"raw\", layer=0)\n",
    "ax.plot(x, np.maximum.accumulate(y), label=\"running max\", layer=1)\n",
    "ax.set_title(\"Layered diagnostics\")\n",
    "ax.set_legend(True)\n",
    "\n",
    "for selected_layers in ([0], [0, 1]):\n",
    "    text = canvas.render(backend=\"plotext\", layers=selected_layers).build(\n",
    "        keep_colors=False\n",
    "    )\n",
    "    print(f\"--- layers={selected_layers} ---\")\n",
    "    print(text)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8",
   "metadata": {},
   "source": [
    "## 4. Save terminal output\n",
    "\n",
    "Plotext output is text, not an image. Saving without ANSI colors makes the file portable to CI logs, issue trackers, and plain-text artifacts."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9",
   "metadata": {},
   "outputs": [],
   "source": [
    "output_path = Path(\"plotext-output.txt\")\n",
    "figure = canvas.render(backend=\"plotext\")\n",
    "figure.savefig(output_path, keep_colors=False)\n",
    "print(f\"wrote {output_path}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "10",
   "metadata": {},
   "source": [
    "## 5. Matrix plots and patches\n",
    "\n",
    "Matrix data is displayed with Plotext's heatmap primitive. Common Matplotlib patches are approximated by their polygon outline, which is useful for lightweight terminal diagnostics."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "11",
   "metadata": {},
   "outputs": [],
   "source": [
    "canvas, ax = Canvas.subplots()\n",
    "ax.add_imshow(np.arange(16).reshape(4, 4))\n",
    "ax.add_patch(patches.Rectangle((0.5, 0.5), 2, 2, fill=False, label=\"window\"))\n",
    "ax.add_colorbar(label=\"intensity\")\n",
    "ax.set_title(\"Matrix diagnostic\")\n",
    "ax.set_legend(True)\n",
    "\n",
    "print(canvas.render(backend=\"plotext\").build(keep_colors=False))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "12",
   "metadata": {},
   "source": [
    "## Current limitations\n",
    "\n",
    "The backend intentionally raises `NotImplementedError` for plot types that do not have a faithful Plotext 6 equivalent, such as histograms, pie charts, stem plots, and secondary/twin axes. Use Matplotlib or Plotly for those cases."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}