AutoMorphoTrack 2.1.0__tar.gz → 2.5.0__tar.gz

automorphotrack-2.5.0/CITATION.cff

@@ -0,0 +1,12 @@
+cff-version: 1.2.0
+message: "Cite this release for the particle revision and reproduction materials."
+type: software
+title: "AutoMorphoTrack 2.5.0: particle refinement and manuscript revision"
+authors:
+  - family-names: Bayati
+    given-names: Armin
+version: 2.5.0
+date-released: 2026-11-14
+repository-code: "https://github.com/abayatibrain/AutoMorphoTrack"
+url: "https://github.com/abayatibrain/AutoMorphoTrack/releases/tag/v2.5.0"
+license: MIT

automorphotrack-2.5.0/MANIFEST.in

@@ -0,0 +1,12 @@
+include README.md
+include LICENSE.md
+include pyproject.toml
+include CITATION.cff
+recursive-include examples *.py *.ipynb
+recursive-include automorphotrack *.py
+
+recursive-include validation *.json *.py *.tif *.csv
+recursive-include docs *.md
+recursive-include tests *.py
+prune integration
+prune release_artifacts

automorphotrack-2.5.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: automorphotrack
+Version: 2.5.0
+Summary: Automated pipeline for mitochondrial and lysosomal detection, tracking, morphology, and colocalization analysis in microscopy images.
+Author-email: "Armin Bayati, Ph.D." <a.bayati.brain@gmail.com>
+License: MIT
+Project-URL: Documentation, https://github.com/abayatibrain/AutoMorphoTrack
+Project-URL: Source, https://github.com/abayatibrain/AutoMorphoTrack
+Project-URL: Tracker, https://github.com/abayatibrain/AutoMorphoTrack/issues
+Keywords: image-processing,microscopy,organelle-tracking,mitochondria,lysosomes,colocalization,live-cell-imaging
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: numpy>=2.0
+Requires-Dist: pandas>=2.2
+Requires-Dist: matplotlib>=3.6.0
+Requires-Dist: seaborn>=0.12.0
+Requires-Dist: opencv-python>=4.6.0
+Requires-Dist: scikit-image>=0.25
+Requires-Dist: scipy>=1.13
+Requires-Dist: tifffile>=2024.8
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == "mcp"
+Provides-Extra: compressed-tiff
+Requires-Dist: imagecodecs>=2024.1; extra == "compressed-tiff"
+Provides-Extra: napari
+Requires-Dist: napari>=0.4.18; extra == "napari"
+Requires-Dist: magicgui>=0.7.0; extra == "napari"
+Requires-Dist: qtpy>=2.3.0; extra == "napari"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Dynamic: license-file
+
+# AutoMorphoTrack 2.5.0
+
+AutoMorphoTrack 2.5.0 requires Python 3.11 or later and has two explicitly versioned analysis routes. The automorphotrack.validated namespace conserves the 18 modules of core 1.1.0rc2. The automorphotrack.refined namespace includes five additional modules that provide particle detection and association, described below, and make use of the unchanged baseline measurement modules. NumPy, pandas, SciPy, scikit-image, and tifffile are the main dependencies. The two implementations are distinguishable by their source, and examples show which route produced a given result.
+
+## Installation
+
+```sh
+python -m pip install "automorphotrack==2.5.0"
+```
+
+Minimal Debian and Ubuntu systems may need libxcb1, libgl1, and libglib2.0-0 for the OpenCV import. The GitHub CI matrix completed wheel and source installations on Windows, Linux, and macOS with Python 3.11 and 3.12, and retained test reports, dependency versions, source checks, and known-motion outputs.
+
+## Particle pipeline
+
+```python
+from automorphotrack.refined import RefinedConfig, run_pipeline
+config = RefinedConfig(channels=(0, 1), sample_id="recording")
+result = run_pipeline("recording.ome.tif", "new_results", config)
+```
+
+```sh
+amt-refined recording.ome.tif --out new_results --config configuration.json
+```
+
+The particle example uses a two-channel synthetic movie with known motion. Run the guarded adapter from the release directory after installing the 2.5.0 wheel. It checks the 18 baseline and five particle modules before importing the numerical implementation. Use a new output directory for every run. For a static image, set min_observations to 1. Particle support masks have not been validated to be mitochondrial membrane boundaries. The default setting requires three observations, thus short-lived events will not be retained and retained masks and motion summaries will not reflect these. Raw outputs preserve these events.
+
+The input must identify time, channel, and spatial axes. Calibration requires a recorded source; otherwise motion remains in pixels per frame. Label masks and track IDs are linked through each frame's Label column. A different configuration requires its own evaluation.
+
+## Recorded validation
+
+Six reserved movies contain 145 annotated trajectories and 2,764 adjacent reference links. Mean accepted-link recall for the frozen default and fixed top-hat configurations was 0.014 and 0.212, respectively. With the particle pipeline, mean accepted-link recall was 0.696, and mean localization recall was 0.768. The new pipeline recovered 2,024 accepted reference links, and four additional accepted links related to different annotated identities, giving conditional precision of 2,024/2,028 among the links with two reference-matched endpoints. Remaining predictions were left unverified. Thirteen trajectories were completely missed, and 33 were fully recovered with accepted links, compared to 41 missed and two fully recovered with the top-hat configuration. Accepted-link recall was 0.739 with a 5-pixel tolerance and 0.587 with a 2-pixel tolerance. Individual reserved movies yielded accepted-link recall from 0.408 to 0.911. Supplementary Fig. 10 and Table 9 show the paired comparisons and their shortcomings.
+
+The original 50 synthetic sequences, when rerun, yielded mean Dice scores of 0.877, 0.752 and 0.532, for the new particle masks, the fixed top-hat configuration and the frozen default, respectively. Mean instance precision and accepted-link recall increased from 0.407 to 0.966 and 0.178 to 0.965, respectively. The two baselines reproduced their earlier results to within an absolute error of 10^-12. Transfer to the external mitochondrial masks was limited. Without the length filter, the selected detector yielded mean Dice scores of 0.369 and 0.060 for the seven MoDL SIM patches and the 13 Myofibril patches, respectively. The MoDL score was still below the earlier top-hat result of 0.421. The particle pipeline thus does not replace target-specific segmentation validation for elongated or densely packed mitochondria.
+
+AutoMorphoTrack 2.5.0 passed 72 tests in each of 12 GitHub CI installations. It built wheels and source distributions for Windows, Linux, and macOS, with Python 3.11 and 3.12. All installations kept the 18 baseline and five particle source modules. Each test compared 19 baseline and 19 particle CSV or TIFFs with recorded references. Integer masks were exact, and for baseline and particle outputs, numerical tolerances were 10^-12 and 10^-9, respectively. The test failed initially on Windows due to Git line-ending conversion which changed the source hashes. Enforcing LF line endings solved this, and the numerical code remained the same. The OpenCV import failure and its system-library remedy documented for minimal Linux remain documented.
+
+Supplementary figures and tables are in the manuscript files attached to [release v2.5.0](https://github.com/abayatibrain/AutoMorphoTrack/releases/tag/v2.5.0). The [reproduction archive](https://github.com/abayatibrain/AutoMorphoTrack/releases/download/v2.5.0/AMT_Revision_Reproducibility_v2.5.0.zip) includes the development protocol, every candidate result, reserved-movie outputs, controls, and prior analyses. [The 12-job CI run](https://github.com/abayatibrain/AutoMorphoTrack/actions/runs/43602083124) records Windows, Linux, and macOS installations.
+
+Biological source: [Richens et al., PLOS Biology 2025](https://doi.org/10.1371/journal.pbio.3003099), [data version 1](https://doi.org/10.17863/CAM.114338), CC BY 4.0. All 12 movies had been assessed with the baseline before six were reserved from the new parameter selection. This is a within-study split. Manual annotations cover a subset of vesicles; unmatched predictions remain unverified.
+
+## Reproducible integration
+
+For the 2.5.0 route, Gemini wrote a new adapter and Codex ran the captured source against the installed wheel. The first adapter returned a file-hash mapping where the contract required a digest string. A focused change resolved that metadata error. The corrected adapter, the Codex adapter, a standalone command line, and an executed Jupyter notebook reproduced the 19 reference particle files exactly on the local host. Altered manifests and source files were rejected before analysis. The Codex guard verifies all 23 modules across both numerical namespaces. Prior to the requests, Argon High was selected in Gemini, but the interface changed its model label after the responses; the underlying model identity was not verified. These records test software integration, and numerical reproducibility, without constituting independent biological validation by either assistant.
+
+The runnable adapter is `examples/refined_verified.py`. The notebook is `examples/Refined_Pipeline.ipynb`. Keep both source manifests under version control. Run a fixture after changing an adapter, configuration, preprocessing step, environment, or downstream calculation. Source integrity alone does not validate those changes.
+
+```sh
+python -I examples/refined_verified.py --input validation/refined_motion.ome.tif --out new_fixture_results --config validation/refined_motion_config.json --validation-dir validation
+```
+
+## Baseline route
+
+Install the pinned 2.5.0 wheel in a virtual environment. Use amt-refined, or import RefinedConfig and run_pipeline from automorphotrack.refined, for the particle pipeline. The amt-validated command retains the baseline implementation for Figures 1-17 and Supplementary Figures 1-9. Supplementary Figure 10 reports the new particle evaluation. The automorphotrack and amt commands remain unchanged. The compressed-tiff extra supplies a TIFF decoder.
+
+```sh
+amt-validated recording.ome.tif --out baseline_results --config baseline_configuration.json
+```
+
+| Implementation | Modules | Source digest |
+| --- | ---: | --- |
+| automorphotrack.validated, core 1.1.0rc2 | 18 | 8a4125a5ebe2b49e019f79b783503f31403a24ea3134d2d10b1bd4610ac3bce8 |
+| automorphotrack.refined, package 2.5.0 | 5 | dcacbe6eede1cfef2cfa165418f8e0c9428aafebf3632a27a6a7655e3605f3a6 |
+
+## License and citation
+
+Software: MIT. External datasets retain their individual licenses, recorded in the reproduction archive. See `CITATION.cff` for this release.
+
+Bayati A, Schumacher JG, Chen X. AutoMorphoTrack. [eLife reviewed preprint 109936, version 1](https://doi.org/10.7554/eLife.109936.1). This is the older preprint, preceding the v2.5.0 particle revision. The revised manuscript is deposited with the current GitHub release.

automorphotrack-2.5.0/README.md

@@ -0,0 +1,68 @@
+# AutoMorphoTrack 2.5.0
+
+AutoMorphoTrack 2.5.0 requires Python 3.11 or later and has two explicitly versioned analysis routes. The automorphotrack.validated namespace conserves the 18 modules of core 1.1.0rc2. The automorphotrack.refined namespace includes five additional modules that provide particle detection and association, described below, and make use of the unchanged baseline measurement modules. NumPy, pandas, SciPy, scikit-image, and tifffile are the main dependencies. The two implementations are distinguishable by their source, and examples show which route produced a given result.
+
+## Installation
+
+```sh
+python -m pip install "automorphotrack==2.5.0"
+```
+
+Minimal Debian and Ubuntu systems may need libxcb1, libgl1, and libglib2.0-0 for the OpenCV import. The GitHub CI matrix completed wheel and source installations on Windows, Linux, and macOS with Python 3.11 and 3.12, and retained test reports, dependency versions, source checks, and known-motion outputs.
+
+## Particle pipeline
+
+```python
+from automorphotrack.refined import RefinedConfig, run_pipeline
+config = RefinedConfig(channels=(0, 1), sample_id="recording")
+result = run_pipeline("recording.ome.tif", "new_results", config)
+```
+
+```sh
+amt-refined recording.ome.tif --out new_results --config configuration.json
+```
+
+The particle example uses a two-channel synthetic movie with known motion. Run the guarded adapter from the release directory after installing the 2.5.0 wheel. It checks the 18 baseline and five particle modules before importing the numerical implementation. Use a new output directory for every run. For a static image, set min_observations to 1. Particle support masks have not been validated to be mitochondrial membrane boundaries. The default setting requires three observations, thus short-lived events will not be retained and retained masks and motion summaries will not reflect these. Raw outputs preserve these events.
+
+The input must identify time, channel, and spatial axes. Calibration requires a recorded source; otherwise motion remains in pixels per frame. Label masks and track IDs are linked through each frame's Label column. A different configuration requires its own evaluation.
+
+## Recorded validation
+
+Six reserved movies contain 145 annotated trajectories and 2,764 adjacent reference links. Mean accepted-link recall for the frozen default and fixed top-hat configurations was 0.014 and 0.212, respectively. With the particle pipeline, mean accepted-link recall was 0.696, and mean localization recall was 0.768. The new pipeline recovered 2,024 accepted reference links, and four additional accepted links related to different annotated identities, giving conditional precision of 2,024/2,028 among the links with two reference-matched endpoints. Remaining predictions were left unverified. Thirteen trajectories were completely missed, and 33 were fully recovered with accepted links, compared to 41 missed and two fully recovered with the top-hat configuration. Accepted-link recall was 0.739 with a 5-pixel tolerance and 0.587 with a 2-pixel tolerance. Individual reserved movies yielded accepted-link recall from 0.408 to 0.911. Supplementary Fig. 10 and Table 9 show the paired comparisons and their shortcomings.
+
+The original 50 synthetic sequences, when rerun, yielded mean Dice scores of 0.877, 0.752 and 0.532, for the new particle masks, the fixed top-hat configuration and the frozen default, respectively. Mean instance precision and accepted-link recall increased from 0.407 to 0.966 and 0.178 to 0.965, respectively. The two baselines reproduced their earlier results to within an absolute error of 10^-12. Transfer to the external mitochondrial masks was limited. Without the length filter, the selected detector yielded mean Dice scores of 0.369 and 0.060 for the seven MoDL SIM patches and the 13 Myofibril patches, respectively. The MoDL score was still below the earlier top-hat result of 0.421. The particle pipeline thus does not replace target-specific segmentation validation for elongated or densely packed mitochondria.
+
+AutoMorphoTrack 2.5.0 passed 72 tests in each of 12 GitHub CI installations. It built wheels and source distributions for Windows, Linux, and macOS, with Python 3.11 and 3.12. All installations kept the 18 baseline and five particle source modules. Each test compared 19 baseline and 19 particle CSV or TIFFs with recorded references. Integer masks were exact, and for baseline and particle outputs, numerical tolerances were 10^-12 and 10^-9, respectively. The test failed initially on Windows due to Git line-ending conversion which changed the source hashes. Enforcing LF line endings solved this, and the numerical code remained the same. The OpenCV import failure and its system-library remedy documented for minimal Linux remain documented.
+
+Supplementary figures and tables are in the manuscript files attached to [release v2.5.0](https://github.com/abayatibrain/AutoMorphoTrack/releases/tag/v2.5.0). The [reproduction archive](https://github.com/abayatibrain/AutoMorphoTrack/releases/download/v2.5.0/AMT_Revision_Reproducibility_v2.5.0.zip) includes the development protocol, every candidate result, reserved-movie outputs, controls, and prior analyses. [The 12-job CI run](https://github.com/abayatibrain/AutoMorphoTrack/actions/runs/43602083124) records Windows, Linux, and macOS installations.
+
+Biological source: [Richens et al., PLOS Biology 2025](https://doi.org/10.1371/journal.pbio.3003099), [data version 1](https://doi.org/10.17863/CAM.114338), CC BY 4.0. All 12 movies had been assessed with the baseline before six were reserved from the new parameter selection. This is a within-study split. Manual annotations cover a subset of vesicles; unmatched predictions remain unverified.
+
+## Reproducible integration
+
+For the 2.5.0 route, Gemini wrote a new adapter and Codex ran the captured source against the installed wheel. The first adapter returned a file-hash mapping where the contract required a digest string. A focused change resolved that metadata error. The corrected adapter, the Codex adapter, a standalone command line, and an executed Jupyter notebook reproduced the 19 reference particle files exactly on the local host. Altered manifests and source files were rejected before analysis. The Codex guard verifies all 23 modules across both numerical namespaces. Prior to the requests, Argon High was selected in Gemini, but the interface changed its model label after the responses; the underlying model identity was not verified. These records test software integration, and numerical reproducibility, without constituting independent biological validation by either assistant.
+
+The runnable adapter is `examples/refined_verified.py`. The notebook is `examples/Refined_Pipeline.ipynb`. Keep both source manifests under version control. Run a fixture after changing an adapter, configuration, preprocessing step, environment, or downstream calculation. Source integrity alone does not validate those changes.
+
+```sh
+python -I examples/refined_verified.py --input validation/refined_motion.ome.tif --out new_fixture_results --config validation/refined_motion_config.json --validation-dir validation
+```
+
+## Baseline route
+
+Install the pinned 2.5.0 wheel in a virtual environment. Use amt-refined, or import RefinedConfig and run_pipeline from automorphotrack.refined, for the particle pipeline. The amt-validated command retains the baseline implementation for Figures 1-17 and Supplementary Figures 1-9. Supplementary Figure 10 reports the new particle evaluation. The automorphotrack and amt commands remain unchanged. The compressed-tiff extra supplies a TIFF decoder.
+
+```sh
+amt-validated recording.ome.tif --out baseline_results --config baseline_configuration.json
+```
+
+| Implementation | Modules | Source digest |
+| --- | ---: | --- |
+| automorphotrack.validated, core 1.1.0rc2 | 18 | 8a4125a5ebe2b49e019f79b783503f31403a24ea3134d2d10b1bd4610ac3bce8 |
+| automorphotrack.refined, package 2.5.0 | 5 | dcacbe6eede1cfef2cfa165418f8e0c9428aafebf3632a27a6a7655e3605f3a6 |
+
+## License and citation
+
+Software: MIT. External datasets retain their individual licenses, recorded in the reproduction archive. See `CITATION.cff` for this release.
+
+Bayati A, Schumacher JG, Chen X. AutoMorphoTrack. [eLife reviewed preprint 109936, version 1](https://doi.org/10.7554/eLife.109936.1). This is the older preprint, preceding the v2.5.0 particle revision. The revised manuscript is deposited with the current GitHub release.

{automorphotrack-2.1.0 → automorphotrack-2.5.0}/automorphotrack/__init__.py

@@ -33,7 +33,7 @@
 #     )
 # ============================================================
 
-__version__ = "2.1.0"
+__version__ = "2.5.0"
 __author__ = "Armin Bayati"
 
 # --- Utility Imports ---
@@ -64,30 +64,45 @@ from automorphotrack.validation import (
     validate_segmentation,
     sensitivity_analysis,
     validate_tracking,
-    generate_validation_report
+    generate_validation_report,
+    generate_synthetic_ground_truth,
 )
 
+# --- Adaptive segmentation backends (R2.4) ---
+from automorphotrack.adaptive_segmentation import (
+    segment,
+    segment_otsu,
+    segment_sauvola,
+    segment_niblack,
+    segment_local_otsu,
+    segment_subtracted,
+    BACKENDS as SEGMENTATION_BACKENDS,
+)
+
+# --- Benchmarking against other tools (R1.2 / R2.3) ---
+from automorphotrack import benchmarking
+
+# --- Stats annotation helper (R2.5.iv) ---
+from automorphotrack.utils import annotate_stats
+
 # --- Convenience Alias (optional shortcut API) ---
 __all__ = [
-    "ensure_dir",
-    "save_high_dpi",
-    "upscale_frame",
-    "write_video",
-    "detect_organelles",
-    "count_lysosomes_per_frame",
-    "classify_morphology",
-    "analyze_shape_features",
-    "profile_shape_data",
-    "track_organelles",
-    "track_overlay",
-    "analyze_motility",
-    "analyze_colocalization",
-    "summarize_integrated_data",
-    "analyze_temporal_dynamics",
-    "analyze_spatial_statistics",
+    # utilities
+    "ensure_dir", "save_high_dpi", "upscale_frame", "write_video",
+    "annotate_stats",
+    # pipeline
+    "detect_organelles", "count_lysosomes_per_frame",
+    "classify_morphology", "analyze_shape_features", "profile_shape_data",
+    "track_organelles", "track_overlay", "analyze_motility",
+    "analyze_colocalization", "summarize_integrated_data",
+    "analyze_temporal_dynamics", "analyze_spatial_statistics",
     "analyze_network_topology",
-    "validate_segmentation",
-    "sensitivity_analysis",
-    "validate_tracking",
-    "generate_validation_report"
+    # validation
+    "validate_segmentation", "sensitivity_analysis", "validate_tracking",
+    "generate_validation_report", "generate_synthetic_ground_truth",
+    # adaptive segmentation backends
+    "segment", "segment_otsu", "segment_sauvola", "segment_niblack",
+    "segment_local_otsu", "segment_subtracted", "SEGMENTATION_BACKENDS",
+    # benchmarking
+    "benchmarking",
 ]

automorphotrack-2.5.0/automorphotrack/adaptive_segmentation.py

@@ -0,0 +1,121 @@
+# ============================================================
+# AutoMorphoTrack – Adaptive Segmentation Backends
+# ============================================================
+# Author: Armin Bayati, Ph.D.
+#
+# Reviewer #2 (R2.4) noted that pure Otsu thresholding plus morphological
+# opening is sensitive to SNR, background heterogeneity, bleaching, and
+# organelle density. This module provides drop-in alternative backends so
+# users can swap the segmentation step without modifying the rest of the
+# pipeline:
+#
+#     - segment_otsu          : the default global-threshold path
+#     - segment_sauvola       : Sauvola adaptive thresholding for uneven background
+#     - segment_niblack       : Niblack adaptive thresholding
+#     - segment_local_otsu    : Otsu inside a sliding window for very large fields
+#     - segment_subtracted    : rolling-ball / top-hat background subtraction
+#                               followed by Otsu (handles bleaching/heterogeneity)
+#
+# All backends expose the same signature::
+#
+#     mask = segment_<name>(image, **kwargs)
+#
+# where ``image`` is a 2D float array in [0, 1] and ``mask`` is a 2D bool
+# array. This lets the validation.sensitivity_analysis sweep run against any
+# of them.
+# ============================================================
+
+from __future__ import annotations
+
+import numpy as np
+from skimage.filters import (
+    threshold_otsu, threshold_sauvola, threshold_niblack, threshold_local
+)
+from skimage.morphology import (
+    remove_small_objects, binary_opening, disk, white_tophat
+)
+from skimage.segmentation import clear_border
+
+
+def _clean(mask: np.ndarray, min_size: int = 3,
+           opening_radius: int = 1,
+           clear_borders: bool = True) -> np.ndarray:
+    if opening_radius > 0:
+        mask = binary_opening(mask, footprint=disk(opening_radius))
+    if clear_borders:
+        mask = clear_border(mask)
+    if min_size > 0:
+        mask = remove_small_objects(mask, max(1, int(min_size)))
+    return mask.astype(bool)
+
+
+def segment_otsu(image: np.ndarray, thr_factor: float = 0.8,
+                 min_size: int = 3, **clean_kwargs) -> np.ndarray:
+    """Global Otsu (the default path), exposed for completeness."""
+    thr = threshold_otsu(image) * thr_factor
+    return _clean(image > thr, min_size=min_size, **clean_kwargs)
+
+
+def segment_sauvola(image: np.ndarray, window_size: int = 25,
+                    k: float = 0.2, min_size: int = 3,
+                    **clean_kwargs) -> np.ndarray:
+    """Sauvola adaptive thresholding (handles uneven illumination)."""
+    if window_size % 2 == 0:
+        window_size += 1
+    thr_map = threshold_sauvola(image, window_size=window_size, k=k)
+    return _clean(image > thr_map, min_size=min_size, **clean_kwargs)
+
+
+def segment_niblack(image: np.ndarray, window_size: int = 25,
+                    k: float = 0.2, min_size: int = 3,
+                    **clean_kwargs) -> np.ndarray:
+    """Niblack adaptive thresholding."""
+    if window_size % 2 == 0:
+        window_size += 1
+    thr_map = threshold_niblack(image, window_size=window_size, k=k)
+    return _clean(image > thr_map, min_size=min_size, **clean_kwargs)
+
+
+def segment_local_otsu(image: np.ndarray, block_size: int = 51,
+                       offset: float = 0.0, min_size: int = 3,
+                       **clean_kwargs) -> np.ndarray:
+    """Tile-wise local Otsu via skimage.filters.threshold_local."""
+    if block_size % 2 == 0:
+        block_size += 1
+    thr_map = threshold_local(image, block_size=block_size, offset=offset)
+    return _clean(image > thr_map, min_size=min_size, **clean_kwargs)
+
+
+def segment_subtracted(image: np.ndarray, background_radius: int = 25,
+                       thr_factor: float = 0.8, min_size: int = 3,
+                       **clean_kwargs) -> np.ndarray:
+    """Top-hat background subtraction + Otsu.
+
+    Equivalent to ImageJ/FIJI's rolling-ball background subtraction step. Use
+    when the field of view has slow intensity gradients from out-of-focus
+    haze, photobleaching, or uneven illumination.
+    """
+    bg_subtracted = white_tophat(image, footprint=disk(background_radius))
+    if bg_subtracted.max() <= 0:
+        return np.zeros_like(image, dtype=bool)
+    bg_subtracted = bg_subtracted / bg_subtracted.max()
+    thr = threshold_otsu(bg_subtracted) * thr_factor
+    return _clean(bg_subtracted > thr, min_size=min_size, **clean_kwargs)
+
+
+BACKENDS = {
+    "otsu": segment_otsu,
+    "sauvola": segment_sauvola,
+    "niblack": segment_niblack,
+    "local_otsu": segment_local_otsu,
+    "subtracted": segment_subtracted,
+}
+
+
+def segment(image: np.ndarray, backend: str = "otsu", **kwargs) -> np.ndarray:
+    """Dispatch to a named backend. ``backend`` is one of ``BACKENDS``."""
+    if backend not in BACKENDS:
+        raise ValueError(
+            f"Unknown backend '{backend}'. Choices: {sorted(BACKENDS)}"
+        )
+    return BACKENDS[backend](image, **kwargs)

automorphotrack-2.5.0/automorphotrack/benchmarking.py

@@ -0,0 +1,188 @@
+# ============================================================
+# AutoMorphoTrack – Benchmarking & Comparative Positioning
+# ============================================================
+# Author: Armin Bayati, Ph.D.
+#
+# Reviewer #1 (R1.2) and Reviewer #2 (R2.3) asked for explicit comparison to
+# established tools: CellProfiler, MiNA, MitoGraph, Mitochondria Analyzer,
+# and learning-based tools like CellPose / StarDist.
+#
+# AutoMorphoTrack does not re-implement those packages — that would
+# duplicate excellent existing work. Instead, this module:
+#
+#   1. Provides exporters that translate AMT outputs into the CSV layouts
+#      those tools consume / produce, so users can directly compare results
+#      side-by-side.
+#   2. Provides importers for the other tools' outputs so AMT can compute
+#      Dice/IoU/Pearson agreement between its segmentations and theirs.
+#   3. Provides a "comparison table" generator that summarises pairwise
+#      agreement across morphology metrics, useful as supplementary material
+#      in publications.
+#
+# The supported tools are:
+#   - CellProfiler (CSV per object)
+#   - MiNA (FIJI plugin; tabular network stats)
+#   - MitoGraph (.gnet / .csv per cell)
+#   - Mitochondria Analyzer (FIJI; per-image summary)
+#   - CellPose / StarDist (label-image masks, np.uint16)
+#
+# Each importer is tolerant: it tries to find the relevant columns by
+# regex-matching common naming conventions so the user does not have to
+# rename anything by hand.
+# ============================================================
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Mapping
+
+import numpy as np
+import pandas as pd
+
+from automorphotrack.validation import validate_segmentation
+
+
+# ------------------------------------------------------------------
+# AMT → other tools (exporters)
+# ------------------------------------------------------------------
+def export_for_cellprofiler(shape_metrics_csv: str | Path,
+                            out_path: str | Path) -> Path:
+    """Write a CSV in a CellProfiler-friendly schema.
+
+    CellProfiler MeasureObjectSizeShape output uses columns like
+    ``AreaShape_Area``, ``AreaShape_Eccentricity``, etc. We map AMT columns
+    to that schema so users can drop the CSV into a CellProfiler analysis
+    workflow without rewriting downstream scripts.
+    """
+    df = pd.read_csv(shape_metrics_csv)
+    mapping = {
+        "Area": "AreaShape_Area",
+        "Eccentricity": "AreaShape_Eccentricity",
+        "Solidity": "AreaShape_Solidity",
+        "Circularity": "AreaShape_FormFactor",   # CellProfiler's name
+        "Aspect_Ratio": "AreaShape_MajorAxisLength_over_MinorAxisLength",
+        "Orientation": "AreaShape_Orientation",
+        "Frame": "Image_Metadata_Frame",
+    }
+    df = df.rename(columns={k: v for k, v in mapping.items() if k in df.columns})
+    df["ImageNumber"] = df.get("Image_Metadata_Frame", 0) + 1
+    df["ObjectNumber"] = range(1, len(df) + 1)
+    out_path = Path(out_path)
+    df.to_csv(out_path, index=False)
+    return out_path
+
+
+def export_for_mina(shape_metrics_csv: str | Path,
+                    out_path: str | Path) -> Path:
+    """Write a CSV in MiNA-style per-mitochondrion network table.
+
+    MiNA reports ``Mean Length``, ``Mean Area``, ``Footprint``, ``Mean
+    Branch Length`` — AMT does not compute branch topology, so the columns
+    we cannot fill are left blank (NaN). This keeps the schema compatible
+    while making the gap explicit.
+    """
+    df = pd.read_csv(shape_metrics_csv)
+    out = pd.DataFrame({
+        "Frame": df.get("Frame"),
+        "Mean Length": np.nan,
+        "Mean Area": df.get("Area"),
+        "Footprint": df.get("Area"),
+        "Mean Branch Length": np.nan,
+        "Eccentricity": df.get("Eccentricity"),
+        "Solidity": df.get("Solidity"),
+        "Form Factor": df.get("Circularity"),
+    })
+    out_path = Path(out_path)
+    out.to_csv(out_path, index=False)
+    return out_path
+
+
+def export_for_mitograph(shape_metrics_csv: str | Path,
+                         out_path: str | Path) -> Path:
+    """Write a MitoGraph-style per-cell summary CSV."""
+    df = pd.read_csv(shape_metrics_csv)
+    grouped = df.groupby("Frame").agg(
+        total_area=("Area", "sum"),
+        mean_area=("Area", "mean"),
+        n_objects=("Area", "size"),
+        mean_aspect_ratio=("Aspect_Ratio", "mean"),
+        mean_solidity=("Solidity", "mean"),
+    ).reset_index()
+    grouped.columns = [
+        "Image", "Total_Volume_um3", "Mean_Volume_um3",
+        "N_Mitochondria", "Mean_Aspect_Ratio", "Mean_Solidity",
+    ]
+    out_path = Path(out_path)
+    grouped.to_csv(out_path, index=False)
+    return out_path
+
+
+# ------------------------------------------------------------------
+# Other tools → AMT (importers + agreement)
+# ------------------------------------------------------------------
+def load_cellprofiler_csv(path: str | Path) -> pd.DataFrame:
+    """Parse a CellProfiler ``Per_Object.csv`` into AMT's shape-metric schema."""
+    df = pd.read_csv(path)
+    rename = {}
+    for c in df.columns:
+        if re.fullmatch(r"AreaShape_Area", c): rename[c] = "Area"
+        elif re.fullmatch(r"AreaShape_Eccentricity", c): rename[c] = "Eccentricity"
+        elif re.fullmatch(r"AreaShape_Solidity", c): rename[c] = "Solidity"
+        elif re.fullmatch(r"AreaShape_FormFactor", c): rename[c] = "Circularity"
+        elif re.fullmatch(r"AreaShape_Orientation", c): rename[c] = "Orientation"
+        elif "MajorAxisLength_over_MinorAxisLength" in c: rename[c] = "Aspect_Ratio"
+        elif "Frame" in c: rename[c] = "Frame"
+    return df.rename(columns=rename)
+
+
+def load_label_mask(path: str | Path) -> np.ndarray:
+    """Load a CellPose / StarDist label image as a binary mask."""
+    import tifffile
+    img = tifffile.imread(str(path))
+    return (img > 0).astype(bool)
+
+
+def agreement(amt_mask: np.ndarray, other_mask: np.ndarray) -> Mapping[str, float]:
+    """Compute Dice / IoU / precision / recall / F1 between two binary masks."""
+    return validate_segmentation(amt_mask.astype(bool), other_mask.astype(bool))
+
+
+def comparison_table(amt_shape_csv: str | Path,
+                     other_shape_csv: str | Path,
+                     other_tool_name: str = "Other") -> pd.DataFrame:
+    """Build a side-by-side morphology comparison table.
+
+    Per-metric this reports: mean ± std for AMT, mean ± std for the other
+    tool, the Spearman rank correlation between matched objects (where
+    matching is by ``Frame`` and row order), and a percentage absolute
+    difference of the means.
+    """
+    from scipy.stats import spearmanr
+
+    a = pd.read_csv(amt_shape_csv)
+    b = pd.read_csv(other_shape_csv)
+    metrics = ["Area", "Eccentricity", "Solidity", "Circularity", "Aspect_Ratio"]
+    rows = []
+    for m in metrics:
+        if m not in a.columns or m not in b.columns:
+            continue
+        av, bv = a[m].dropna(), b[m].dropna()
+        n = min(len(av), len(bv))
+        if n < 3:
+            continue
+        rho, p = spearmanr(av.iloc[:n], bv.iloc[:n])
+        mean_a, mean_b = av.mean(), bv.mean()
+        pct_diff = 100 * abs(mean_a - mean_b) / max(abs(mean_a), abs(mean_b), 1e-9)
+        rows.append({
+            "Metric": m,
+            "AMT_mean": round(mean_a, 4),
+            "AMT_std": round(av.std(), 4),
+            f"{other_tool_name}_mean": round(mean_b, 4),
+            f"{other_tool_name}_std": round(bv.std(), 4),
+            "Spearman_rho": round(float(rho), 4),
+            "p_value": round(float(p), 6),
+            "Percent_diff_means": round(pct_diff, 2),
+            "N": n,
+        })
+    return pd.DataFrame(rows)