AutoMorphoTrack 2.1.0__tar.gz → 2.4.0__tar.gz

automorphotrack-2.4.0/MANIFEST.in

@@ -0,0 +1,10 @@
+include README.md
+include LICENSE.md
+include pyproject.toml
+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.4.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: automorphotrack
+Version: 2.4.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
+
+AutoMorphoTrack 2.4.0 includes the frozen quantitative core described in the revised eLife manuscript. It can be launched through the automorphotrack.validated namespace or via the amt-validated command. The current 2.x APIs, GUI, and MCP interface are also available and are not covered in this manuscript.
+
+## Installation
+
+```sh
+python -m pip install "automorphotrack==2.4.0"
+```
+
+Python >=3.11
+
+## Manuscript analysis
+
+```python
+from automorphotrack.validated import PipelineConfig, run_pipeline
+config = PipelineConfig(axes="TCYX", mito_channel=0, lyso_channel=1)
+result = run_pipeline("recording.tif", "results", config)
+```
+
+```sh
+amt-validated recording.tif --out results --config configuration.json
+```
+
+Provide true axes and channel mappings. Physical calibration is not required; uncalibrated motion is in pixels per frame. The pipeline retains masks, objects, accepted links, tables, configuration, input identity, and source hashes. Adapters should invoke the validated namespace and leave the source unaltered. An unaltered core does not guarantee correctness on a new image domain.
+
+## Validation scope
+
+The revision assesses segmentation on a set of 7 public microscopy studies, of which 6 are confocal. It describes the study-specific limitations and provides failed cases. Representative example image crops are regions from a single recording. The benchmark does not prove membrane contact, or functional interaction, nor does it prove identity tracking in biological data in general.
+
+The public release candidate passed 51 software tests on the local macOS arm64 host. An installed-wheel check verified 18 modules of the core and compared 19 CSV and TIFF files to the known-motion fixture. Both channels contained a tracked object with an expected mean speed of 1 pixel per frame. The separate command-line route was also successfully completed. Numerical and execution consistency for the known-motion fixture were evaluated; these tests do not prove correctness for new biological images.
+
+## Release identities
+
+| Item | Identifier |
+| --- | --- |
+| Public distribution | 2.4.0 |
+| Manuscript namespace | automorphotrack.validated |
+| Frozen core version | 1.1.0rc2 |
+| Core digest | 8a4125a5ebe2b49e019f79b783503f31403a24ea3134d2d10b1bd4610ac3bce8 |
+| Source manifest | validation/core_manifest.json |
+| Earlier interfaces | docs/V2_INTERFACE.md |
+| Release records | docs/VALIDATED_CORE.md |
+
+## License and citation
+
+MIT license
+
+Bayati A, Schumacher JG, Chen X. AutoMorphoTrack. eLife reviewed preprint 109936. https://doi.org/10.7554/eLife.109936.1

automorphotrack-2.4.0/README.md

@@ -0,0 +1,49 @@
+# AutoMorphoTrack
+
+AutoMorphoTrack 2.4.0 includes the frozen quantitative core described in the revised eLife manuscript. It can be launched through the automorphotrack.validated namespace or via the amt-validated command. The current 2.x APIs, GUI, and MCP interface are also available and are not covered in this manuscript.
+
+## Installation
+
+```sh
+python -m pip install "automorphotrack==2.4.0"
+```
+
+Python >=3.11
+
+## Manuscript analysis
+
+```python
+from automorphotrack.validated import PipelineConfig, run_pipeline
+config = PipelineConfig(axes="TCYX", mito_channel=0, lyso_channel=1)
+result = run_pipeline("recording.tif", "results", config)
+```
+
+```sh
+amt-validated recording.tif --out results --config configuration.json
+```
+
+Provide true axes and channel mappings. Physical calibration is not required; uncalibrated motion is in pixels per frame. The pipeline retains masks, objects, accepted links, tables, configuration, input identity, and source hashes. Adapters should invoke the validated namespace and leave the source unaltered. An unaltered core does not guarantee correctness on a new image domain.
+
+## Validation scope
+
+The revision assesses segmentation on a set of 7 public microscopy studies, of which 6 are confocal. It describes the study-specific limitations and provides failed cases. Representative example image crops are regions from a single recording. The benchmark does not prove membrane contact, or functional interaction, nor does it prove identity tracking in biological data in general.
+
+The public release candidate passed 51 software tests on the local macOS arm64 host. An installed-wheel check verified 18 modules of the core and compared 19 CSV and TIFF files to the known-motion fixture. Both channels contained a tracked object with an expected mean speed of 1 pixel per frame. The separate command-line route was also successfully completed. Numerical and execution consistency for the known-motion fixture were evaluated; these tests do not prove correctness for new biological images.
+
+## Release identities
+
+| Item | Identifier |
+| --- | --- |
+| Public distribution | 2.4.0 |
+| Manuscript namespace | automorphotrack.validated |
+| Frozen core version | 1.1.0rc2 |
+| Core digest | 8a4125a5ebe2b49e019f79b783503f31403a24ea3134d2d10b1bd4610ac3bce8 |
+| Source manifest | validation/core_manifest.json |
+| Earlier interfaces | docs/V2_INTERFACE.md |
+| Release records | docs/VALIDATED_CORE.md |
+
+## License and citation
+
+MIT license
+
+Bayati A, Schumacher JG, Chen X. AutoMorphoTrack. eLife reviewed preprint 109936. https://doi.org/10.7554/eLife.109936.1

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

@@ -33,7 +33,7 @@
 #     )
 # ============================================================
 
-__version__ = "2.1.0"
+__version__ = "2.4.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.4.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.4.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)