Restructure and consolidate notebooks for new-user clarity

- Rename example_notebooks with Step-prefixed ordering (Step1–Step4a/b)
- Move calibration notebooks (AreaCalibration, CellMask) to Optional_ prefix
  since they only need re-running when changing microscope/objective
- Create 00_START_HERE.ipynb explaining workflow, step order, and optional branches
- Consolidate 3 ASAP BoxPlots notebooks (Neurons/Microglia/Astrocytes) into one
  parameterised ASAP_Cell_Plots_BoxPlots.ipynb with cell_type + table_name params
- Consolidate 2 ASAP HC visualisation notebooks into one
  ASAP_Cell_Plots_HC_Visualisation.ipynb with cell_type + path params
- Fix NameError bug in Optional_CellMask_SizeThresholding (image_size was unassigned)
- Add path-edit warning to Optional_TwoColourCoincidencePlot

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: JBeckwith

example_notebooks/00_START_HERE.ipynb

@@ -0,0 +1,34 @@
+{
+ "nbformat": 4,
+ "nbformat_minor": 5,
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.10.0"
+  }
+ },
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": "# pyRASP — Start Here\n\nWelcome to **pyRASP**, a toolkit for single-molecule imaging analysis of 3D z-stacks.\n\nThis folder (`example_notebooks/`) contains step-by-step notebooks for a new user. Work through the numbered notebooks in order, then add Optional notebooks as needed.\n\n---\n\n## Installation check"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": "# Run this cell to verify pyRASP is importable before proceeding\nimport sys\nsys.path.append('..')\n\nfrom src import RASPRoutines, AnalysisFunctions, IOFunctions, PlottingFunctions\nprint(\"pyRASP imported successfully.\")"
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": "---\n\n## Core pipeline\n\n| Notebook | What it does |\n|---|---|\n| `Step1_RadialityCalibration.ipynb` | **Run first.** Calibrates the radiality threshold from negative-control images. Saves parameters to disk. Required for any spot detection. |\n| `Step2_SingleImageAnalysis.ipynb` | Visual QC on one image: plots detected spots before committing to the full folder run. |\n| `Step3_ImageFolderAnalysis.ipynb` | Runs `analyse_images()` on an entire folder. Produces `spot_analysis.csv` and `largeobject_analysis.csv`. |\n| `Step4a_LargeObject_CellColocalisation.ipynb` | Re-runs LO-to-cell colocalisation on existing CSVs (uses `lo_colocalise_wrapper()`). Needs Step 3 output. |\n| `Step4b_CountPunctaInCells.ipynb` | Counts spots per individual cell (uses `count_puncta_in_individual_cells_threshold_3D()`). Needs Step 3 output. |\n\n---\n\n## Optional — calibration (once per microscope setup)\n\nThese only need to be run when changing microscope or objective. If you have already calibrated these values, skip them.\n\n| Notebook | What it does |\n|---|---|\n| `Optional_AreaCalibration.ipynb` | Calibrates the area threshold that distinguishes diffraction-limited puncta from large aggregates. |\n| `Optional_CellMask_SizeThresholding.ipynb` | Visual tool for choosing cell-size thresholds. |\n\n---\n\n## Optional — spatial statistics (needs Step 3 output)\n\nThese can be run in any order after Step 3:\n\n| Notebook | What it does |\n|---|---|\n| `Optional_SpotToSpot_RDF.ipynb` | Auto-correlation RDF: do spots cluster with themselves? |\n| `Optional_SpotToMask_RDF.ipynb` | Spot-to-mask RDF: do spots avoid or seek the cell boundary? |\n| `Optional_TwoPunctaSets_RDF.ipynb` | Cross-channel RDF: do channel-1 and channel-2 spots co-cluster? |\n| `Optional_SpotToSpotCoincidence.ipynb` | Coincidence fraction: what fraction of C1 spots co-localise with C2? |\n| `Optional_TwoColourCoincidencePlot.ipynb` | Two-colour coincidence visualisation. **Edit paths before running.** |\n| `Optional_CellPunctumPlot.ipynb` | Per-cell punctum analysis plot. |\n\n---\n\n## Real-data worked examples\n\nFor end-to-end worked examples on real ASAP data, see `../testing_notebooks/worked_examples/`:\n\n- `FullPipeline_LargeAggregates_20260326.ipynb` — calibrate → analyse → LO-in-cell → plots\n- `FullPipeline_Oligomers_20260326.ipynb` — calibrate → analyse → count per cell → box plots\n- `FullPipeline_Puncta_20260529.ipynb` — collaborator dataset (note: incomplete)"
+  }
+ ]
+}

…e_notebooks/Step2a_AreaCalibration.ipynb …notebooks/Optional_AreaCalibration.ipynbexample_notebooks/Step2a_AreaCalibration.ipynb renamed to example_notebooks/Optional_AreaCalibration.ipynb example_notebooks/Step2a_AreaCalibration.ipynb renamed to example_notebooks/Optional_AreaCalibration.ipynb

@@ -99,15 +99,7 @@
      ]
     }
    ],
-   "source": [
-    "image_size = \n",
-    "for k in np.arange(len(areas)):\n",
-    "    coords = pil[k]\n",
-    "    xm = coords[:, 0]\n",
-    "    ym = coords[:, 1]\n",
-    "    if (np.any(xm > image_size[0])) or (np.any(ym > image_size[1])):\n",
-    "        print(k)"
-   ]
+   "source": "image_size = cell_mask_old.shape  # (height, width) of the 2D projected mask\nfor k in np.arange(len(areas)):\n    coords = pil[k]\n    xm = coords[:, 0]\n    ym = coords[:, 1]\n    if (np.any(xm > image_size[0])) or (np.any(ym > image_size[1])):\n        print(k)"
   },
   {
    "cell_type": "code",
@@ -139,4 +131,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

…s/Step2b_CellMask_SizeThresholding.ipynb …Optional_CellMask_SizeThresholding.ipynbexample_notebooks/Step2b_CellMask_SizeThresholding.ipynb renamed to example_notebooks/Optional_CellMask_SizeThresholding.ipynb example_notebooks/Step2b_CellMask_SizeThresholding.ipynb renamed to example_notebooks/Optional_CellMask_SizeThresholding.ipynb

@@ -69,6 +69,11 @@
     "z_plane = 10  # middle of stacks"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": "> **Edit before running:** The cell below contains hardcoded file paths. Replace `analysis_file_c1`, `analysis_file_c2`, and the image filename with paths to your own data before running."
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -233,4 +238,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}