{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Tutorial 8: Using Prefab Pipelines\n",
    "\n",
    "Building a pipeline from scratch gives you full control, but PhenoTypic\n",
    "also ships **prefab pipelines** — pre-configured `ImagePipeline` subclasses\n",
    "tuned for common organisms and plate types. In this tutorial you will\n",
    "survey the available prefabs, apply one, and compare results.\n",
    "\n",
    "**What you will learn:**\n",
    "\n",
    "1. What prefab pipelines are and when to use them\n",
    "2. Survey the available prefabs\n",
    "3. Apply a prefab pipeline\n",
    "4. Compare results from different prefabs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Imports"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from phenotypic.data import load_synth_yeast_plate"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Available Prefab Pipelines\n",
    "\n",
    "Each prefab is an `ImagePipeline` subclass with operations and measurements\n",
    "already configured. Choose based on your organism and plate conditions.\n",
    "\n",
    "| Prefab | Best for | Strategy |\n",
    "|--------|----------|----------|\n",
    "| `HeavyOtsuPipeline` | General-purpose yeast, clean plates | Multi-stage Otsu with refinement |\n",
    "| `HeavyWatershedPipeline` | Touching or clustered colonies | Watershed segmentation |\n",
    "| `RoundPeaksPipeline` | Round colonies, lightweight | Peak detection |\n",
    "| `HeavyRoundPeaksPipeline` | Round colonies needing refinement | Extended peak detection |\n",
    "| `FilamentousFungiPipeline` | Filamentous fungi (*Neurospora*, etc.) | BM3D denoise + specialized detector |\n",
    "| `GridSectionPipeline` | Pre-tiled grid sections | Section-level processing |"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Apply HeavyOtsuPipeline\n",
    "\n",
    "Let's start with the most general-purpose option — `HeavyOtsuPipeline`.\n",
    "It chains Gaussian blur, CLAHE, median filtering, Sobel edge enhancement,\n",
    "Otsu detection, and several refinement steps (morphological opening,\n",
    "border removal, small-object removal, mask fill)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from phenotypic.prefab import HeavyOtsuPipeline\n",
    "\n",
    "plate = load_synth_yeast_plate()\n",
    "heavy_otsu = HeavyOtsuPipeline()\n",
    "result_otsu = heavy_otsu.apply(plate)\n",
    "result_otsu.dash(overlay=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(f\"HeavyOtsuPipeline detected {result_otsu.num_objects} colonies\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Apply RoundPeaksPipeline\n",
    "\n",
    "Now let's try `RoundPeaksPipeline` — a lighter approach that uses peak\n",
    "detection to find circular colonies. It is faster but may miss irregular\n",
    "or faint colonies."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from phenotypic.prefab import RoundPeaksPipeline\n",
    "\n",
    "plate2 = load_synth_yeast_plate()\n",
    "round_peaks = RoundPeaksPipeline()\n",
    "result_rp = round_peaks.apply(plate2)\n",
    "result_rp.dash(overlay=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(f\"RoundPeaksPipeline detected {result_rp.num_objects} colonies\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Compare\n",
    "\n",
    "Different prefabs produce different results on the same plate. The best\n",
    "choice depends on your colonies, your imaging conditions, and what you\n",
    "need to measure. A quick visual comparison and colony count helps you\n",
    "decide."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(f\"HeavyOtsuPipeline:   {result_otsu.num_objects} colonies\")\n",
    "print(f\"RoundPeaksPipeline:  {result_rp.num_objects} colonies\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Prefabs Include Measurements\n",
    "\n",
    "Prefab pipelines come with measurements pre-configured, so you can call\n",
    "`.apply_and_measure()` directly — no need to add your own `meas` list."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plate3 = load_synth_yeast_plate()\n",
    "df = heavy_otsu.apply_and_measure(plate3)\n",
    "print(f\"{len(df)} colonies measured across {df.shape[1]} features\")\n",
    "df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Summary\n",
    "\n",
    "Prefab pipelines are the fastest path from plate image to results:\n",
    "\n",
    "- **`HeavyOtsuPipeline`** — robust general-purpose detection with refinement\n",
    "- **`RoundPeaksPipeline`** — lightweight peak-based detection for round colonies\n",
    "- **`HeavyWatershedPipeline`** — for touching or clustered colonies\n",
    "- **`FilamentousFungiPipeline`** — specialized for branching fungal morphology\n",
    "- All prefabs support `.apply()`, `.apply_and_measure()`, `.to_json()`, etc.\n",
    "\n",
    "Choose based on your organism, plate conditions, and desired accuracy.\n",
    "When a prefab is close but not quite right, use it as a starting point\n",
    "and customize the parameters.\n",
    "\n",
    "**Next up:** [Tutorial 9: Diagnosing Image Quality](09_diagnosing_image_quality.ipynb) —\n",
    "assess plate quality before choosing a pipeline."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3.11.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}