nanoobjectdetection 2.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,234 @@
1
+ """Diagnostic plots matching the 1.0 analysis views."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import time
6
+ from pathlib import Path
7
+
8
+ import numpy as np
9
+ import pandas as pd
10
+
11
+ from .msd import calculate_msd, estimate_diffusion
12
+ from .statistics import weighted_quantile
13
+
14
+
15
+ def _save(figure, path, **kwargs) -> None:
16
+ # Overwriting files on synced drives (OneDrive via WSL) can fail with EINVAL; retry after removing the old file.
17
+ for attempt in range(4):
18
+ try:
19
+ figure.savefig(path, **kwargs)
20
+ return
21
+ except OSError:
22
+ if attempt == 3:
23
+ raise
24
+ Path(path).unlink(missing_ok=True)
25
+ time.sleep(0.5)
26
+
27
+
28
+ def _statistics(values: np.ndarray) -> dict[str, float | tuple[float, float]]:
29
+ inverse = 1000.0 / values
30
+ inverse_mean = float(np.mean(inverse))
31
+ inverse_std = float(np.std(inverse, ddof=1)) if len(inverse) > 1 else 0.0
32
+ q16, q84 = np.quantile(inverse, [0.158655, 0.841345])
33
+ q023, q977 = np.quantile(inverse, [0.02275, 0.97725])
34
+ return {
35
+ "median": float(1000.0 / np.median(inverse)),
36
+ "mu": float(np.mean(values)),
37
+ "cv_inv": inverse_std / inverse_mean if inverse_mean else float("nan"),
38
+ "one_sigma": (float(1000.0 / q84), float(1000.0 / q16)),
39
+ "two_sigma": (float(1000.0 / q977), float(1000.0 / q023)),
40
+ }
41
+
42
+
43
+ def _dimension_title(dimension: str) -> str:
44
+ return {"x": "long.", "y": "trans.", "2d": "2d"}.get(dimension, dimension)
45
+
46
+
47
+ def _add_statistics_box(axis, values: np.ndarray) -> None:
48
+ stats = _statistics(values)
49
+ one = stats["one_sigma"]
50
+ two = stats["two_sigma"]
51
+ text = "\n".join(
52
+ [
53
+ f"median = {stats['median']:.1f} nm",
54
+ rf"$\mu$ = {stats['mu']:.1f} nm",
55
+ rf"$CV_{{\text{{inv}}}}$ = {stats['cv_inv']:.3f}",
56
+ rf"1$\sigma_q$ = [{one[0]:.1f}, {one[1]:.1f}] nm",
57
+ rf"2$\sigma_q$ = [{two[0]:.1f}, {two[1]:.1f}] nm",
58
+ ]
59
+ )
60
+ axis.text(
61
+ 0.55,
62
+ 0.95,
63
+ text,
64
+ transform=axis.transAxes,
65
+ va="top",
66
+ bbox={"boxstyle": "round", "facecolor": "honeydew", "alpha": 0.7},
67
+ )
68
+
69
+
70
+ def _add_reciprocal_gaussian_fit(axis, diameters: np.ndarray, peak: float) -> None:
71
+ """Plot the 1.0-style fit: Gaussian in inverse-size space, back-transformed and scaled to the histogram peak."""
72
+ inverse = 1000.0 / diameters
73
+ if len(inverse) < 2 or np.std(inverse) == 0:
74
+ return
75
+ grid = np.linspace(max(np.min(diameters) * 0.5, 1.0), min(np.max(diameters) * 1.5, 300.0), 1000)
76
+ mean, std = np.mean(inverse), np.std(inverse, ddof=1)
77
+ density = np.exp(-0.5 * ((1000.0 / grid - mean) / std) ** 2) / grid**2
78
+ axis.plot(grid, density / density.max() * peak, color="C3")
79
+
80
+
81
+ def _legacy_log_ticks(axis, x: np.ndarray, y: np.ndarray) -> None:
82
+ """Explicit tick labels instead of powers of ten, as in the 1.0 plots."""
83
+ from matplotlib.ticker import NullFormatter, ScalarFormatter
84
+
85
+ x_ticks = np.array([1, 3, 10, 30, 100, 300, 1000, 3000, 10000, 30000, 100000])
86
+ y_ticks = np.array([1, 2, 3, 4, 6, 10, 15, 20, 30, 40, 60, 80, 100, 150, 200, 300, 400, 600, 800, 1000])
87
+ x_low = x_ticks[x_ticks <= x.min()][-1] if (x_ticks <= x.min()).any() else x_ticks[0]
88
+ x_high = x_ticks[x_ticks >= x.max()][0] if (x_ticks >= x.max()).any() else x_ticks[-1]
89
+ y_low = y_ticks[y_ticks <= y.min()][-1] if (y_ticks <= y.min()).any() else y_ticks[0]
90
+ y_high = y_ticks[y_ticks >= y.max()][0] if (y_ticks >= y.max()).any() else y_ticks[-1]
91
+ axis.set_xticks(x_ticks)
92
+ axis.set_yticks(y_ticks)
93
+ axis.set_xlim(x_low, x_high)
94
+ axis.set_ylim(y_low, y_high)
95
+ for ticks in (axis.xaxis, axis.yaxis):
96
+ ticks.set_major_formatter(ScalarFormatter())
97
+ ticks.set_minor_formatter(NullFormatter())
98
+
99
+
100
+ def _valid_estimates(estimates: pd.DataFrame) -> pd.DataFrame:
101
+ return estimates.loc[
102
+ estimates["diameter_nm"].notna()
103
+ & np.isfinite(estimates["diameter_nm"])
104
+ & (estimates["diameter_nm"] > 0)
105
+ ].copy()
106
+
107
+
108
+ def _histogram(
109
+ values: pd.DataFrame,
110
+ output_dir: Path,
111
+ dimension: str,
112
+ weighted: bool,
113
+ plt,
114
+ ) -> str:
115
+ title_dimension = _dimension_title(dimension)
116
+ diameters = values["diameter_nm"].to_numpy(float)
117
+ if weighted:
118
+ diameters = np.repeat(
119
+ diameters, values["valid_frames"].to_numpy(dtype=int)
120
+ )
121
+ bin_size = 0.5
122
+ minimum = np.floor(np.min(diameters) / bin_size) * bin_size
123
+ maximum = np.ceil(np.max(diameters) / bin_size) * bin_size
124
+ bins = np.arange(minimum, maximum + bin_size, bin_size)
125
+ figure, axis = plt.subplots(figsize=(6, 6))
126
+ counts, _, _ = axis.hist(diameters, bins=bins, color="C0")
127
+ _add_reciprocal_gaussian_fit(axis, diameters, counts.max())
128
+ _add_statistics_box(axis, diameters)
129
+ weighting = "weighted by track length" if weighted else "each track counted once"
130
+ axis.set(
131
+ title=f"Amount of {title_dimension} trajectories analyzed = {len(values)}, {weighting}",
132
+ xlabel="Diameter [nm]",
133
+ ylabel="Absolute occurrence",
134
+ )
135
+ axis.set_xlim(10, 300)
136
+ axis.grid(True)
137
+ suffix = "weighted" if weighted else "unweighted"
138
+ legacy_dimension = {"x": "long", "y": "trans", "2d": "2d"}.get(dimension, dimension)
139
+ path = output_dir / f"Diameter_Histogramm-{legacy_dimension}-{suffix}.png"
140
+ _save(figure, path, dpi=150)
141
+ plt.close(figure)
142
+ return str(path)
143
+
144
+
145
+ def create_analysis_plots(
146
+ trajectories: pd.DataFrame,
147
+ estimates: pd.DataFrame,
148
+ output_dir: Path,
149
+ *,
150
+ pixel_size_um: float,
151
+ fps: float,
152
+ dimension: str,
153
+ max_lag: int | None,
154
+ dimension_label: str | None = None,
155
+ drift: pd.DataFrame | None = None,
156
+ ) -> dict[str, str]:
157
+ """Save 1.0-compatible plots for one MSD dimension."""
158
+ try:
159
+ import matplotlib.pyplot as plt
160
+ except ImportError as exc:
161
+ raise RuntimeError("Plot generation requires matplotlib.") from exc
162
+
163
+ output_dir.mkdir(parents=True, exist_ok=True)
164
+ label = dimension_label or dimension
165
+ paths: dict[str, str] = {}
166
+ title_dimension = _dimension_title(dimension)
167
+
168
+ figure, axis = plt.subplots(figsize=(10, 6))
169
+ for particle, group in trajectories.groupby("particle"):
170
+ axis.plot(group["x_corrected"], group["y_corrected"], linewidth=0.8, alpha=0.7)
171
+ axis.set(title=f"{title_dimension} drift-corrected trajectories", xlabel="x [pixel]", ylabel="y [pixel]")
172
+ legacy_label = {"x": "long", "y": "trans", "2d": "2d"}.get(dimension, dimension)
173
+ paths["trajectories_plot"] = str(output_dir / f"Trajectories_{legacy_label}.png")
174
+ _save(figure, paths["trajectories_plot"], dpi=150)
175
+ plt.close(figure)
176
+
177
+ figure, axis = plt.subplots(figsize=(10, 6))
178
+ for particle, group in trajectories.groupby("particle"):
179
+ msd = calculate_msd(group, dimension=dimension, max_lag=max_lag, pixel_size_um=pixel_size_um, fps=fps)
180
+ if len(msd) < 2:
181
+ continue
182
+ fit = estimate_diffusion(msd, dimension)
183
+ axis.plot(msd["time_s"], msd["msd_um2"], ".", alpha=0.45)
184
+ axis.plot(msd["time_s"], fit["intercept_um2"] + fit["slope_um2_s"] * msd["time_s"], linewidth=1)
185
+ axis.set(title=f"{title_dimension} MSD and linear fits", xlabel="lag time [s]", ylabel="MSD [um^2]")
186
+ paths["msd_plot"] = str(output_dir / f"MSD_fit_{legacy_label}.png")
187
+ _save(figure, paths["msd_plot"], dpi=150)
188
+ plt.close(figure)
189
+
190
+ valid = _valid_estimates(estimates)
191
+ if not valid.empty:
192
+ paths["diameter_histogram_unweighted"] = _histogram(valid, output_dir, label, False, plt)
193
+ paths["diameter_histogram_weighted"] = _histogram(valid, output_dir, label, True, plt)
194
+
195
+ figure, axis = plt.subplots(figsize=(10, 6))
196
+ brightness = valid["mean_brightness"].to_numpy(float) if "mean_brightness" in valid else np.ones(len(valid))
197
+ scatter = axis.scatter(
198
+ valid["valid_frames"], valid["diameter_nm"],
199
+ c=brightness, cmap="jet", alpha=0.9, edgecolors="black", linewidths=0.3,
200
+ )
201
+ colorbar = figure.colorbar(scatter, ax=axis)
202
+ colorbar.set_label("Mean Brightness")
203
+ axis.set(
204
+ title=f"{title_dimension.capitalize()} Particle size over tracking time",
205
+ xlabel="Trajectory length [frames]", ylabel="Diameter [nm]",
206
+ xscale="log", yscale="log",
207
+ )
208
+ _legacy_log_ticks(axis, valid["valid_frames"].to_numpy(float), valid["diameter_nm"].to_numpy(float))
209
+ axis.grid(alpha=0.25)
210
+ paths["diameter_over_trajectory_plot"] = str(
211
+ output_dir / f"DiameterOverTrajLength_{legacy_label}.png"
212
+ )
213
+ _save(figure, paths["diameter_over_trajectory_plot"], dpi=150)
214
+ plt.close(figure)
215
+
216
+ figure, axis = plt.subplots(figsize=(6, 6))
217
+ if drift is not None and {"frame", "drift_x", "drift_y"}.issubset(drift.columns):
218
+ axis.plot(drift["frame"], drift["drift_y"], label="transversal")
219
+ axis.plot(drift["frame"], drift["drift_x"], label="along fiber")
220
+ axis.legend()
221
+ else:
222
+ axis.text(
223
+ 0.5,
224
+ 0.5,
225
+ "No common drift estimate available",
226
+ ha="center",
227
+ va="center",
228
+ transform=axis.transAxes,
229
+ )
230
+ axis.set(title="accumulated drift", xlabel="frames", ylabel="drift [px]")
231
+ paths["global_drift_plot"] = str(output_dir / "Global_Drift.png")
232
+ _save(figure, paths["global_drift_plot"], dpi=150)
233
+ plt.close(figure)
234
+ return paths
@@ -0,0 +1,56 @@
1
+ """Array preprocessing that does not depend on the 1.0 package."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import numpy as np
6
+ from scipy.ndimage import gaussian_filter
7
+
8
+
9
+ def preprocess(
10
+ frames: np.ndarray,
11
+ remove_camera_offset: bool = True,
12
+ remove_laser_fluctuation: bool = False,
13
+ remove_static_background: bool = True,
14
+ background_method: str = "legacy_trimmed_mean",
15
+ enhance_snr: bool = False,
16
+ background: np.ndarray | None = None,
17
+ offset: float | None = None,
18
+ snr_sigma_px: float = 1.0,
19
+ ) -> np.ndarray:
20
+ """Return float32 frames after deterministic basic corrections."""
21
+ result = np.asarray(frames, dtype=np.float32).copy()
22
+ if remove_camera_offset:
23
+ result -= np.min(result) if offset is None else np.float32(offset)
24
+ if remove_laser_fluctuation:
25
+ frame_intensity = np.mean(result, axis=(1, 2))
26
+ reference = float(np.median(frame_intensity))
27
+ if reference > 0:
28
+ result /= np.maximum(frame_intensity[:, None, None] / reference, 1e-12)
29
+ if remove_static_background:
30
+ if background is not None:
31
+ background = np.asarray(background, dtype=np.float32)
32
+ elif background_method == "median":
33
+ background = np.median(result, axis=0, keepdims=True)
34
+ elif background_method == "legacy_trimmed_mean":
35
+ ordered = np.sort(result, axis=0)
36
+ first = int(0.3 * len(ordered))
37
+ last = max(first + 1, int(0.7 * len(ordered)))
38
+ background = np.mean(ordered[first:last], axis=0, keepdims=True)
39
+ else:
40
+ raise ValueError(
41
+ "background_method must be 'median' or 'legacy_trimmed_mean'"
42
+ )
43
+ result -= background
44
+ if enhance_snr:
45
+ result = gaussian_filter(result, sigma=(0, snr_sigma_px, snr_sigma_px))
46
+ return result
47
+
48
+
49
+ def to_uint16(frames: np.ndarray, scale_max: float | None = None) -> np.ndarray:
50
+ """Convert processed frames to positive uint16 without overflow."""
51
+ result = np.asarray(frames, dtype=np.float32)
52
+ result = np.maximum(result, 0)
53
+ maximum = float(np.max(result) if scale_max is None else scale_max)
54
+ if maximum == 0:
55
+ return np.zeros(result.shape, dtype=np.uint16)
56
+ return np.rint(result * (65535.0 / maximum)).astype(np.uint16)
@@ -0,0 +1,32 @@
1
+ """Progress reporting with a graceful fallback when tqdm is unavailable."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Iterable, Iterator
6
+ from typing import TypeVar
7
+
8
+ T = TypeVar("T")
9
+
10
+
11
+ def progress(
12
+ iterable: Iterable[T],
13
+ *,
14
+ desc: str,
15
+ total: int | None = None,
16
+ unit: str = "it",
17
+ ) -> Iterator[T]:
18
+ try:
19
+ from tqdm import tqdm
20
+ except ImportError:
21
+ yield from iterable
22
+ return
23
+ yield from tqdm(iterable, desc=desc, total=total, unit=unit)
24
+
25
+
26
+ def update(message: str) -> None:
27
+ try:
28
+ from tqdm import tqdm
29
+ except ImportError:
30
+ print(message, flush=True)
31
+ return
32
+ tqdm.write(message)
@@ -0,0 +1,133 @@
1
+ """Quality checks used before converting MSD fits into particle diameters."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import numpy as np
6
+ import pandas as pd
7
+ from math import erf, exp, sqrt
8
+
9
+ from .msd import calculate_msd, estimate_diffusion
10
+
11
+
12
+ def trajectory_quality(
13
+ trajectory: pd.DataFrame,
14
+ *,
15
+ dimension: str,
16
+ max_lag: int,
17
+ pixel_size_um: float,
18
+ fps: float,
19
+ minimum_pairs_at_max_lag: int = 5,
20
+ minimum_ks_significance: float = 0.01,
21
+ ks_method: str = "exact",
22
+ ) -> dict[str, float | bool | str]:
23
+ """Return explicit acceptance diagnostics for one linked trajectory."""
24
+ msd = calculate_msd(
25
+ trajectory,
26
+ dimension=dimension,
27
+ max_lag=max_lag,
28
+ pixel_size_um=pixel_size_um,
29
+ fps=fps,
30
+ )
31
+ if len(msd) < 2:
32
+ return {"accepted": False, "reason": "too_few_msd_points"}
33
+ if int(msd["pairs"].iloc[-1]) < minimum_pairs_at_max_lag:
34
+ return {"accepted": False, "reason": "too_few_pairs"}
35
+
36
+ fit = estimate_diffusion(msd, dimension)
37
+ if not np.isfinite(fit["diffusion_um2_s"]) or fit["diffusion_um2_s"] <= 0:
38
+ return {
39
+ "accepted": False,
40
+ "reason": "non_positive_diffusion",
41
+ "diffusion_um2_s": fit["diffusion_um2_s"],
42
+ }
43
+
44
+ values = trajectory.sort_values("frame")
45
+ coordinate = "x_corrected" if dimension in {"x", "2d"} else "y_corrected"
46
+ displacement = values[coordinate].diff().dropna().to_numpy(float)
47
+ if dimension == "2d":
48
+ dx = values["x_corrected"].diff().dropna().to_numpy(float)
49
+ dy = values["y_corrected"].diff().dropna().to_numpy(float)
50
+ displacement = np.hypot(dx, dy)
51
+ displacement = displacement[np.isfinite(displacement)]
52
+ if len(displacement) < minimum_pairs_at_max_lag:
53
+ return {"accepted": False, "reason": "too_few_displacements"}
54
+ mean = float(np.mean(displacement))
55
+ std = float(np.std(displacement))
56
+ if not np.isfinite(std) or std == 0:
57
+ return {"accepted": False, "reason": "zero_displacement_variance"}
58
+ ordered = np.sort(displacement)
59
+ cdf = np.array(
60
+ [0.5 * (1.0 + erf((value - mean) / (std * sqrt(2.0)))) for value in ordered]
61
+ )
62
+ sample_size = len(ordered)
63
+ ranks = np.arange(1, sample_size + 1, dtype=float)
64
+ statistic = float(
65
+ max(
66
+ np.max(ranks / sample_size - cdf),
67
+ np.max(cdf - (ranks - 1.0) / sample_size),
68
+ )
69
+ )
70
+ if ks_method == "legacy":
71
+ # Legacy formula: first term of the Kolmogorov series with N = trajectory length
72
+ pvalue = float(2.0 * exp(-2.0 * len(values) * statistic**2))
73
+ accepted = bool(pvalue >= minimum_ks_significance)
74
+ return {
75
+ "accepted": accepted,
76
+ "reason": "accepted" if accepted else "non_brownian",
77
+ "diffusion_um2_s": fit["diffusion_um2_s"],
78
+ "fit_points": fit["fit_points"],
79
+ "pairs_at_max_lag": float(msd["pairs"].iloc[-1]),
80
+ "ks_significance": pvalue,
81
+ }
82
+ scaled_statistic = (sqrt(sample_size) + 0.12 + 0.11 / sqrt(sample_size)) * statistic
83
+ pvalue = 0.0
84
+ for term in range(1, 101):
85
+ contribution = 2.0 * (-1.0) ** (term - 1) * exp(
86
+ -2.0 * term**2 * scaled_statistic**2
87
+ )
88
+ pvalue += contribution
89
+ if abs(contribution) < 1e-12:
90
+ break
91
+ pvalue = float(np.clip(pvalue, 0.0, 1.0))
92
+ accepted = bool(pvalue >= minimum_ks_significance)
93
+ return {
94
+ "accepted": accepted,
95
+ "reason": "accepted" if accepted else "non_brownian",
96
+ "diffusion_um2_s": fit["diffusion_um2_s"],
97
+ "fit_points": fit["fit_points"],
98
+ "pairs_at_max_lag": float(msd["pairs"].iloc[-1]),
99
+ "ks_significance": float(pvalue),
100
+ }
101
+
102
+
103
+ def filter_trajectories(
104
+ trajectories: pd.DataFrame,
105
+ *,
106
+ dimension: str,
107
+ max_lag: int,
108
+ pixel_size_um: float,
109
+ fps: float,
110
+ minimum_pairs_at_max_lag: int = 5,
111
+ minimum_ks_significance: float = 0.01,
112
+ ks_method: str = "exact",
113
+ ) -> tuple[pd.DataFrame, pd.DataFrame]:
114
+ """Filter trajectories and return accepted rows plus per-track diagnostics."""
115
+ diagnostics = []
116
+ accepted_ids: list[object] = []
117
+ for particle, group in trajectories.groupby("particle", sort=True):
118
+ result = trajectory_quality(
119
+ group,
120
+ dimension=dimension,
121
+ max_lag=max_lag,
122
+ pixel_size_um=pixel_size_um,
123
+ fps=fps,
124
+ minimum_pairs_at_max_lag=minimum_pairs_at_max_lag,
125
+ minimum_ks_significance=minimum_ks_significance,
126
+ ks_method=ks_method,
127
+ )
128
+ result["particle"] = particle
129
+ diagnostics.append(result)
130
+ if result["accepted"]:
131
+ accepted_ids.append(particle)
132
+ filtered = trajectories[trajectories["particle"].isin(accepted_ids)].reset_index(drop=True)
133
+ return filtered, pd.DataFrame(diagnostics)
@@ -0,0 +1,59 @@
1
+ """Weighted summary statistics for particle-size estimates."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import numpy as np
6
+ import pandas as pd
7
+
8
+
9
+ def weighted_quantile(
10
+ values: pd.Series | np.ndarray,
11
+ weights: pd.Series | np.ndarray,
12
+ quantile: float,
13
+ ) -> float:
14
+ """Return a quantile using non-negative observation weights."""
15
+ if not 0 <= quantile <= 1:
16
+ raise ValueError("quantile must be between 0 and 1")
17
+ values_array = np.asarray(values, dtype=float)
18
+ weights_array = np.asarray(weights, dtype=float)
19
+ valid = np.isfinite(values_array) & np.isfinite(weights_array) & (weights_array > 0)
20
+ if not np.any(valid):
21
+ return float("nan")
22
+ values_array = values_array[valid]
23
+ weights_array = weights_array[valid]
24
+ order = np.argsort(values_array)
25
+ values_array = values_array[order]
26
+ weights_array = weights_array[order]
27
+ cumulative = np.cumsum(weights_array)
28
+ return float(values_array[np.searchsorted(cumulative, quantile * cumulative[-1])])
29
+
30
+
31
+ def diameter_summary(estimates: pd.DataFrame) -> pd.DataFrame:
32
+ """Create unweighted, frame-weighted, and MSD-pair-weighted summaries."""
33
+ valid = estimates[
34
+ estimates["diameter_nm"].notna()
35
+ & np.isfinite(estimates["diameter_nm"])
36
+ & (estimates["diameter_nm"] > 0)
37
+ ].copy()
38
+ if valid.empty:
39
+ return pd.DataFrame(
40
+ columns=["weighting", "particles", "weight_sum", "median_nm", "q25_nm", "q75_nm"]
41
+ )
42
+ rows = []
43
+ weighting = {
44
+ "unweighted": np.ones(len(valid)),
45
+ "trajectory_frames": valid["trajectory_frames"].to_numpy(float),
46
+ "msd_pairs": valid["msd_pairs"].to_numpy(float),
47
+ }
48
+ for name, weights in weighting.items():
49
+ rows.append(
50
+ {
51
+ "weighting": name,
52
+ "particles": len(valid),
53
+ "weight_sum": float(weights.sum()),
54
+ "median_nm": weighted_quantile(valid["diameter_nm"], weights, 0.5),
55
+ "q25_nm": weighted_quantile(valid["diameter_nm"], weights, 0.25),
56
+ "q75_nm": weighted_quantile(valid["diameter_nm"], weights, 0.75),
57
+ }
58
+ )
59
+ return pd.DataFrame(rows)
@@ -0,0 +1,97 @@
1
+ """Stitching of trajectory fragments for videos that contain a single particle."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import numpy as np
6
+ import pandas as pd
7
+
8
+
9
+ def _fragment_table(trajectories: pd.DataFrame, edge_frames: int) -> pd.DataFrame:
10
+ rows = []
11
+ for particle, group in trajectories.sort_values("frame").groupby("particle"):
12
+ head, tail = group.iloc[:edge_frames], group.iloc[-edge_frames:]
13
+ rows.append(
14
+ {
15
+ "particle": particle,
16
+ "start": int(group["frame"].iloc[0]),
17
+ "end": int(group["frame"].iloc[-1]),
18
+ "start_x": head["x"].mean(),
19
+ "start_y": head["y"].mean(),
20
+ "end_x": tail["x"].mean(),
21
+ "end_y": tail["y"].mean(),
22
+ "mass": float(group["mass"].median()) if "mass" in group else 1.0,
23
+ }
24
+ )
25
+ return pd.DataFrame(rows)
26
+
27
+
28
+ def stitch_fragments(
29
+ trajectories: pd.DataFrame,
30
+ max_gap_frames: int,
31
+ max_distance_px: float,
32
+ distance_growth_px: float,
33
+ max_mass_ratio: float,
34
+ min_fragment_frames: int,
35
+ edge_frames: int = 5,
36
+ ) -> pd.DataFrame:
37
+ """Give fragments that plausibly belong to one particle the same ``particle`` id.
38
+
39
+ A fragment may follow another if it starts after the other ended, within
40
+ ``max_gap_frames``, and its first positions lie within
41
+ ``max_distance_px + distance_growth_px * sqrt(gap)`` of the other's last
42
+ positions (diffusion widens the allowed jump with the gap). Median masses must
43
+ agree within ``max_mass_ratio``. Pairs are accepted greedily, best first, and
44
+ every fragment gets at most one predecessor and one successor.
45
+ """
46
+ if trajectories.empty:
47
+ return trajectories.copy()
48
+ sizes = trajectories.groupby("particle")["frame"].transform("size")
49
+ kept = trajectories.loc[sizes >= min_fragment_frames].copy()
50
+ if kept.empty:
51
+ return kept.reset_index(drop=True)
52
+ fragments = _fragment_table(kept, edge_frames).sort_values("start").reset_index(drop=True)
53
+
54
+ candidates = []
55
+ for a in fragments.itertuples():
56
+ for b in fragments.itertuples():
57
+ gap = b.start - a.end
58
+ if a.particle == b.particle or gap < 1 or gap > max_gap_frames:
59
+ continue
60
+ limit = max_distance_px + distance_growth_px * np.sqrt(gap)
61
+ distance = float(np.hypot(b.start_x - a.end_x, b.start_y - a.end_y))
62
+ ratio = max(a.mass, b.mass) / max(min(a.mass, b.mass), 1e-12)
63
+ if distance <= limit and ratio <= max_mass_ratio:
64
+ candidates.append((distance / limit + 0.1 * np.log(ratio), a.particle, b.particle))
65
+ candidates.sort()
66
+
67
+ successor: dict = {}
68
+ has_predecessor: set = set()
69
+ for _, first, second in candidates:
70
+ if first in successor or second in has_predecessor:
71
+ continue
72
+ successor[first] = second
73
+ has_predecessor.add(second)
74
+
75
+ new_id = {}
76
+ for particle in fragments["particle"]:
77
+ if particle in has_predecessor:
78
+ continue
79
+ current = particle
80
+ while True:
81
+ new_id[current] = particle
82
+ if current not in successor:
83
+ break
84
+ current = successor[current]
85
+ kept["particle"] = kept["particle"].map(new_id)
86
+ return kept.reset_index(drop=True)
87
+
88
+
89
+ def keep_dominant_particle(trajectories: pd.DataFrame, criterion: str = "longest") -> pd.DataFrame:
90
+ """Keep one stitched trajectory: most detections ("longest") or most total mass ("brightest")."""
91
+ if criterion not in {"longest", "brightest"}:
92
+ raise ValueError("criterion must be 'longest' or 'brightest'")
93
+ if trajectories.empty:
94
+ return trajectories.copy()
95
+ grouped = trajectories.groupby("particle")
96
+ score = grouped["mass"].sum() if criterion == "brightest" else grouped["frame"].size()
97
+ return trajectories[trajectories["particle"] == score.idxmax()].reset_index(drop=True)