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.
- nanoobjectdetection/__init__.py +24 -0
- nanoobjectdetection/__main__.py +6 -0
- nanoobjectdetection/application.py +670 -0
- nanoobjectdetection/auto_parameters.py +177 -0
- nanoobjectdetection/calibration.py +64 -0
- nanoobjectdetection/config.py +202 -0
- nanoobjectdetection/drift.py +47 -0
- nanoobjectdetection/gpu.py +126 -0
- nanoobjectdetection/hindrance.py +56 -0
- nanoobjectdetection/legacy_config.py +157 -0
- nanoobjectdetection/legacy_outputs.py +121 -0
- nanoobjectdetection/localization.py +73 -0
- nanoobjectdetection/msd.py +215 -0
- nanoobjectdetection/pipeline.py +874 -0
- nanoobjectdetection/plotting.py +234 -0
- nanoobjectdetection/preprocessing.py +56 -0
- nanoobjectdetection/progress.py +32 -0
- nanoobjectdetection/quality.py +133 -0
- nanoobjectdetection/statistics.py +59 -0
- nanoobjectdetection/stitching.py +97 -0
- nanoobjectdetection/storage.py +187 -0
- nanoobjectdetection/synthetic.py +28 -0
- nanoobjectdetection/tracking.py +75 -0
- nanoobjectdetection/trajectory_processing.py +81 -0
- nanoobjectdetection/ultra_uniform.py +52 -0
- nanoobjectdetection-2.0.0.dist-info/METADATA +249 -0
- nanoobjectdetection-2.0.0.dist-info/RECORD +31 -0
- nanoobjectdetection-2.0.0.dist-info/WHEEL +5 -0
- nanoobjectdetection-2.0.0.dist-info/entry_points.txt +2 -0
- nanoobjectdetection-2.0.0.dist-info/top_level.txt +2 -0
- nanoobjectdetection_2_0/__init__.py +30 -0
|
@@ -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)
|