AutoMorphoTrack 2.4.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.4.0 → automorphotrack-2.5.0}/MANIFEST.in

@@ -1,6 +1,8 @@
 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

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.4.0 → automorphotrack-2.5.0}/automorphotrack/__init__.py

@@ -33,7 +33,7 @@
 #     )
 # ============================================================
 
-__version__ = "2.4.0"
+__version__ = "2.5.0"
 __author__ = "Armin Bayati"
 
 # --- Utility Imports ---

automorphotrack-2.5.0/automorphotrack/refined/__init__.py

@@ -0,0 +1,8 @@
+"""Versioned particle segmentation and association; frozen validated API is unchanged."""
+
+from .segmentation import SpotConfig, segment_spots
+from .tracking import TrackingConfig, link_spots
+from .pipeline import RefinedConfig, analyze_movie, run_pipeline
+
+__all__ = ["SpotConfig", "segment_spots", "TrackingConfig", "link_spots",
+           "RefinedConfig", "analyze_movie", "run_pipeline"]

automorphotrack-2.5.0/automorphotrack/refined/__main__.py

@@ -0,0 +1,20 @@
+"""Command-line access to the separately versioned particle pipeline."""
+import argparse
+import json
+from pathlib import Path
+from .pipeline import RefinedConfig, run_pipeline
+
+
+def main():
+    parser=argparse.ArgumentParser(description='AutoMorphoTrack 2.5 particle analysis')
+    parser.add_argument('input',help='One TIFF movie')
+    parser.add_argument('--out',required=True,help='New output directory')
+    parser.add_argument('--config',help='Explicit JSON configuration')
+    args=parser.parse_args()
+    config=RefinedConfig.from_dict(json.loads(Path(args.config).read_text())) if args.config else RefinedConfig()
+    result=run_pipeline(args.input,args.out,config)
+    print(json.dumps({'status':'completed','source_sha256':result['manifest']['source_sha256'],
+                      'observations':result['manifest']['observations']},indent=2))
+
+
+if __name__=='__main__':main()

automorphotrack-2.5.0/automorphotrack/refined/pipeline.py

@@ -0,0 +1,134 @@
+"""Recorded single- or multichannel particle analysis, separate from the frozen core."""
+
+from dataclasses import dataclass, field, asdict
+from pathlib import Path
+from datetime import datetime, timezone
+import hashlib
+import json
+import platform
+from importlib import metadata
+import numpy as np
+import pandas as pd
+import tifffile
+from .segmentation import SpotConfig, segment_spots
+from .tracking import TrackingConfig, link_spots
+from ..validated.io import normalize_axes, sha256_file
+from ..validated.config import PipelineConfig as MeasurementConfig
+from ..validated.core import measure_shapes, motility_from_tracks, colocalization_metrics
+
+
+@dataclass(frozen=True)
+class RefinedConfig:
+    axes: str | None = None
+    axes_override_reason: str | None = None
+    channels: tuple[int, ...] = (0,)
+    spot: SpotConfig = field(default_factory=SpotConfig)
+    tracking: TrackingConfig = field(default_factory=TrackingConfig)
+    min_observations: int = 3
+    pixel_size_um: float | None = None
+    frame_interval_s: float | None = None
+    calibration_source: str | None = None
+    sample_id: str = "sample"
+
+    def __post_init__(self):
+        if not isinstance(self.spot, SpotConfig) or not isinstance(self.tracking, TrackingConfig):
+            raise TypeError("Expected SpotConfig and TrackingConfig")
+        if (not self.channels or len(set(self.channels)) != len(self.channels)
+                or any(isinstance(x, bool) or not isinstance(x, int) or x < 0 for x in self.channels)):
+            raise ValueError("channels must contain distinct nonnegative integers")
+        if isinstance(self.min_observations, bool) or not isinstance(self.min_observations, int) or self.min_observations < 1:
+            raise ValueError("min_observations must be a positive integer")
+        if not self.sample_id:
+            raise ValueError("sample_id must be nonempty")
+        MeasurementConfig(pixel_size_um=self.pixel_size_um, frame_interval_s=self.frame_interval_s)
+        if (self.pixel_size_um is not None or self.frame_interval_s is not None) and not self.calibration_source:
+            raise ValueError("Physical calibration requires calibration_source")
+
+    @classmethod
+    def from_dict(cls, values):
+        values=dict(values)
+        if 'spot' in values: values['spot']=SpotConfig(**values['spot'])
+        if 'tracking' in values: values['tracking']=TrackingConfig(**values['tracking'])
+        if 'channels' in values: values['channels']=tuple(values['channels'])
+        return cls(**values)
+
+
+def analyze_movie(images, config=None):
+    """Analyze a nonnegative TYX array; label IDs remain tied to recorded detections."""
+    config=config or RefinedConfig()
+    images=np.asarray(images)
+    if images.ndim != 3 or not all(images.shape):
+        raise ValueError("Expected a nonempty TYX array")
+    if len(images) < config.min_observations:
+        raise ValueError("Movie is shorter than min_observations; set that value explicitly for brief or static inputs")
+    raw_labels=[];points=[];thresholds=[]
+    for frame, im in enumerate(images):
+        lab,xy,meta=segment_spots(im,config.spot)
+        raw_labels.append(lab);points.append(xy);thresholds.append(dict(Frame=frame,**meta))
+    raw_labels=np.asarray(raw_labels)
+    raw_tracks=link_spots(points,config.tracking)
+    counts=raw_tracks.groupby('Track_ID').size()
+    keep=counts[counts>=config.min_observations].index
+    tracks=raw_tracks[raw_tracks.Track_ID.isin(keep)].copy()
+    labels=np.zeros_like(raw_labels)
+    for frame in range(len(images)):
+        allowed=tracks.loc[tracks.Frame.eq(frame),'Label'].to_numpy()
+        labels[frame]=np.where(np.isin(raw_labels[frame],allowed),raw_labels[frame],0)
+    measurement=MeasurementConfig(pixel_size_um=config.pixel_size_um,frame_interval_s=config.frame_interval_s)
+    shapes,_=measure_shapes(labels,measurement,labeled=True)
+    shapes=shapes.rename(columns={'X':'Mask_Centroid_X','Y':'Mask_Centroid_Y'})
+    shapes=shapes.merge(tracks[['Frame','Label','X','Y','Track_ID']],on=['Frame','Label'],how='left',validate='one_to_one')
+    # The frozen measurement routine independently computes actual frame intervals.
+    steps,motility,per_frame=motility_from_tracks(tracks,measurement)
+    return dict(labels=labels,raw_labels=raw_labels,tracks=tracks,raw_tracks=raw_tracks,
+                shapes=shapes,steps=steps,motility=motility,motility_per_frame=per_frame,
+                thresholds=pd.DataFrame(thresholds))
+
+
+def run_pipeline(input_path, out_dir, config=None):
+    """Write all inputs, settings, source identities, and quantitative outputs.
+
+    For exactly two selected channels, retained foreground masks also define the
+    full-field colocalization measurements. This does not establish contact.
+    """
+    config=config or RefinedConfig()
+    if not isinstance(config,RefinedConfig): raise TypeError("config must be RefinedConfig")
+    out=Path(out_dir)
+    if out.exists() and any(out.iterdir()): raise FileExistsError(f"Output directory is not empty: {out}")
+    with tifffile.TiffFile(input_path) as tf:
+        if len(tf.series)!=1: raise ValueError("Extract one TIFF series before analysis")
+        series=tf.series[0];native_axes=series.axes;array=series.asarray()
+    axes=config.axes or native_axes
+    if axes!=native_axes and not config.axes_override_reason:
+        raise ValueError("An axes override requires axes_override_reason")
+    stack=normalize_axes(array,axes)
+    if max(config.channels)>=stack.shape[-1]: raise ValueError("Selected channel is outside the image")
+    channels={channel:analyze_movie(stack[...,channel],config) for channel in config.channels}
+    out.mkdir(parents=True,exist_ok=True)
+    for channel,result in channels.items():
+        for name,value in result.items():
+            path=out/f'channel_{channel}_{name}'
+            if isinstance(value,pd.DataFrame): value.to_csv(path.with_suffix('.csv'),index=False)
+            else: tifffile.imwrite(path.with_suffix('.tif'),value,compression='deflate',metadata={'axes':'TYX'},photometric='minisblack')
+    if len(config.channels)==2:
+        a,b=config.channels
+        values=[dict(Frame=f,**colocalization_metrics(stack[f,...,a],stack[f,...,b],channels[a]['labels'][f]>0,channels[b]['labels'][f]>0)) for f in range(len(stack))]
+        pd.DataFrame(values).to_csv(out/'colocalization.csv',index=False)
+    source={p.name:sha256_file(p) for p in sorted(Path(__file__).parent.glob('*.py'))}
+    frozen={p.name:sha256_file(p) for p in sorted((Path(__file__).parent.parent/'validated').glob('*.py'))}
+    manifest=dict(schema_version=1,algorithm_version='2.5.0',namespace='automorphotrack.refined',
+        created_utc=datetime.now(timezone.utc).isoformat(),input_sha256=sha256_file(input_path),
+        input_name=Path(input_path).name,native_axes=native_axes,effective_axes=axes,
+        canonical_shape=list(stack.shape),configuration=asdict(config),
+        source_files_sha256=source,source_sha256=hashlib.sha256(json.dumps(source,sort_keys=True).encode()).hexdigest(),
+        frozen_measurement_sha256=hashlib.sha256(json.dumps(frozen,sort_keys=True).encode()).hexdigest(),
+        python=platform.python_version(),platform=platform.platform(),
+        dependencies={name:metadata.version(name) for name in ['numpy','scipy','pandas','scikit-image','tifffile']},
+        observations={str(k):dict(raw=len(v['raw_tracks']),retained=len(v['tracks'])) for k,v in channels.items()},
+        limitations=['Intensity-support masks are not validated organelle membrane boundaries.',
+                     'Minimum track length can exclude real brief events.',
+                     'Ambiguous and gap links are excluded from adjacent-step speeds.',
+                     'No inferred fission, fusion, or membrane contact.'],
+        output_files={p.name:sha256_file(p) for p in sorted(out.iterdir()) if p.is_file()})
+    (out/'run_manifest.json').write_text(json.dumps(manifest,indent=2,allow_nan=False)+'\n')
+    return dict(channels=channels,manifest=manifest)

automorphotrack-2.5.0/automorphotrack/refined/segmentation.py

@@ -0,0 +1,85 @@
+"""Noise-scaled spot detection with explicit, bounded instance masks."""
+
+from dataclasses import dataclass
+import math
+import numpy as np
+from scipy.ndimage import gaussian_filter, gaussian_laplace
+from skimage.feature import peak_local_max
+from skimage.segmentation import watershed
+from skimage.measure import regionprops
+
+
+@dataclass(frozen=True)
+class SpotConfig:
+    sigma_px: float = 1.5
+    background_sigma_px: float = 6.0
+    threshold_snr: float = 3.0
+    min_distance_px: int = 3
+    support_fraction: float = 0.2
+    max_radius_px: float = 4.5
+    min_area_px: int = 3
+
+    def __post_init__(self):
+        for name in ("sigma_px", "background_sigma_px", "threshold_snr", "max_radius_px"):
+            value = getattr(self, name)
+            if not math.isfinite(value) or value <= 0:
+                raise ValueError(f"{name} must be positive and finite")
+        if self.background_sigma_px <= self.sigma_px:
+            raise ValueError("background_sigma_px must exceed sigma_px")
+        if not 0 < self.support_fraction < 1:
+            raise ValueError("support_fraction must lie between zero and one")
+        for name in ("min_distance_px", "min_area_px"):
+            value = getattr(self, name)
+            if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+                raise ValueError(f"{name} must be a positive integer")
+
+
+def segment_spots(image, config=None):
+    """Return instance labels, intensity-weighted positions, and detector metadata.
+
+    Positions use positive background-subtracted intensity inside each mask.
+    These intensity support regions are not validated physical organelle borders.
+    No temporal information or reference annotations enter segmentation.
+    """
+    config = config or SpotConfig()
+    image = np.asarray(image, dtype=float)
+    if image.ndim != 2 or not image.size or not np.isfinite(image).all() or np.any(image < 0):
+        raise ValueError("Expected a finite, nonnegative, nonempty YX image")
+    empty = np.zeros(image.shape, np.uint32)
+    if np.ptp(image) == 0:
+        return empty, np.empty((0, 2)), {"noise_response": 0.0, "threshold": 0.0, "detections": 0}
+    background = gaussian_filter(image, config.background_sigma_px)
+    foreground = image - background
+    response = -gaussian_laplace(foreground, config.sigma_px) * config.sigma_px ** 2
+    # A robust response-scale estimate includes correlated acquisition noise.
+    median = float(np.median(response))
+    noise = float(np.median(np.abs(response - median)) / 0.6744897501960817)
+    noise = max(noise, np.finfo(float).eps * max(float(image.max()), 1.0))
+    threshold = config.threshold_snr * noise
+    peaks = peak_local_max(response, min_distance=config.min_distance_px,
+                           threshold_abs=threshold, exclude_border=False)
+    if not len(peaks):
+        return empty, np.empty((0, 2)), {"noise_response": noise, "threshold": threshold, "detections": 0}
+    markers = np.zeros(image.shape, np.int32)
+    markers[tuple(peaks.T)] = np.arange(1, len(peaks) + 1)
+    smooth = gaussian_filter(foreground, max(config.sigma_px / 2, 0.5))
+    labels = watershed(-smooth, markers, mask=smooth > 0)
+    coords = []
+    result = empty.copy()
+    for region in regionprops(labels):
+        index = region.label - 1
+        y, x = peaks[index]
+        pixels = region.coords
+        py, px = pixels.T
+        keep = ((py - y) ** 2 + (px - x) ** 2 <= config.max_radius_px ** 2)
+        keep &= smooth[py, px] >= max(smooth[y, x] * config.support_fraction, 0)
+        py, px = py[keep], px[keep]
+        if len(py) < config.min_area_px:
+            continue
+        weights = np.maximum(smooth[py, px], 0)
+        if weights.sum() <= 0:
+            continue
+        coords.append([float(np.average(py, weights=weights)), float(np.average(px, weights=weights))])
+        result[py, px] = len(coords)
+    return result, np.asarray(coords).reshape(-1, 2), {
+        "noise_response": noise, "threshold": threshold, "detections": len(coords)}

automorphotrack-2.5.0/automorphotrack/refined/tracking.py

@@ -0,0 +1,93 @@
+"""One-to-one, motion-assisted particle association with explicit ambiguity."""
+
+from dataclasses import dataclass
+import math
+import numpy as np
+import pandas as pd
+from scipy.optimize import linear_sum_assignment
+from scipy.spatial.distance import cdist
+
+
+@dataclass(frozen=True)
+class TrackingConfig:
+    max_distance_px: float = 6.0
+    ambiguity_margin_px: float = 0.5
+    prediction_weight: float = 0.0
+    max_gap_frames: int = 0
+
+    def __post_init__(self):
+        if not math.isfinite(self.max_distance_px) or self.max_distance_px <= 0:
+            raise ValueError("max_distance_px must be positive and finite")
+        if not math.isfinite(self.ambiguity_margin_px) or self.ambiguity_margin_px < 0:
+            raise ValueError("ambiguity_margin_px must be nonnegative and finite")
+        if not math.isfinite(self.prediction_weight) or not 0 <= self.prediction_weight <= 1:
+            raise ValueError("prediction_weight must lie between zero and one")
+        if isinstance(self.max_gap_frames, bool) or not isinstance(self.max_gap_frames, int) or not 0 <= self.max_gap_frames <= 2:
+            raise ValueError("max_gap_frames must be an integer from zero through two")
+
+
+COLUMNS = ["Frame", "Track_ID", "Label", "X", "Y", "Link_Status", "Link_Distance_px",
+           "Previous_Candidate_Count", "Current_Candidate_Count", "Delta_Frame",
+           "Prediction_Error_px", "Assignment_Margin_px"]
+
+
+def link_spots(centroids, config=None, labels_per_frame=None):
+    """Keep gaps and ambiguous links visible; never interpolate missing positions.
+
+    Accepted adjacent links require a clear distance margin in both directions.
+    Gap links have a separate status and are excluded from speed estimation.
+    """
+    config = config or TrackingConfig()
+    active, next_id, rows = {}, 0, []
+    for frame, points in enumerate(centroids):
+        current = np.asarray(points, dtype=float)
+        if current.size == 0:
+            current = np.empty((0, 2))
+        if current.ndim != 2 or current.shape[1] != 2 or not np.isfinite(current).all():
+            raise ValueError("Each frame must contain finite N by 2 row/column positions")
+        if labels_per_frame is not None and len(labels_per_frame[frame]) != len(current):
+            raise ValueError("Labels and positions must have equal lengths")
+        active = {k:v for k,v in active.items() if frame-v['frame'] <= config.max_gap_frames+1}
+        ids = sorted(active)
+        links = {}
+        allowed = np.zeros((len(ids),len(current)),bool)
+        distances = np.empty(allowed.shape)
+        raw = np.empty(allowed.shape)
+        if ids and len(current):
+            old = np.array([active[k]['point'] for k in ids])
+            dt = np.array([frame-active[k]['frame'] for k in ids])
+            predicted = old + np.array([active[k]['velocity'] for k in ids]) * dt[:,None] * config.prediction_weight
+            distances = cdist(predicted,current)
+            raw = cdist(old,current)
+            gates = config.max_distance_px * dt
+            allowed = (raw <= gates[:,None]) & (distances <= gates[:,None])
+            n,m=allowed.shape
+            # Dummy assignments permit births and losses instead of forcing links.
+            costs=np.full((n+m,m+n),1e12)
+            costs[:n,:m]=np.where(allowed,(distances/gates[:,None])**2,1e12)
+            costs[:n,m:]=0.5
+            costs[n:,:m]=0.5
+            costs[n:,m:]=0
+            a,b=linear_sum_assignment(costs)
+            links={int(j):int(i) for i,j in zip(a,b) if i<n and j<m and allowed[i,j]}
+        for j, point in enumerate(current):
+            if j in links:
+                i=links[j];tid=ids[i];previous=active[tid]
+                dt=frame-previous['frame']
+                other_row=np.where(allowed[i],distances[i],np.inf).copy();other_row[j]=np.inf
+                other_col=np.where(allowed[:,j],distances[:,j],np.inf).copy();other_col[i]=np.inf
+                margin=min(other_row.min(initial=np.inf),other_col.min(initial=np.inf))-distances[i,j]
+                clear=margin > config.ambiguity_margin_px
+                status=('matched' if dt==1 else 'gap') if clear else 'ambiguous'
+                velocity=(point-previous['point'])/dt if clear else np.zeros(2)
+                distance=float(raw[i,j]);error=float(distances[i,j])
+                pc=int(allowed[i].sum());cc=int(allowed[:,j].sum())
+            else:
+                tid=next_id;next_id+=1;dt=0
+                status='start' if frame==0 else 'birth_or_unmatched'
+                velocity=np.zeros(2);distance=error=margin=np.nan;pc=0
+                cc=int(allowed[:,j].sum())
+            active[tid]=dict(frame=frame,point=point.copy(),velocity=velocity)
+            label=labels_per_frame[frame][j] if labels_per_frame is not None else j+1
+            rows.append([frame,tid,label,float(point[1]),float(point[0]),status,distance,pc,cc,dt,error,margin])
+    return pd.DataFrame(rows,columns=COLUMNS)