diff --git a/benchmarks/uipsf/real/m2_pairs/z_direction.py b/benchmarks/uipsf/real/m2_pairs/z_direction.py new file mode 100644 index 00000000..b5dfd9c8 --- /dev/null +++ b/benchmarks/uipsf/real/m2_pairs/z_direction.py @@ -0,0 +1,155 @@ +"""Which way does M2's stage z go? The metadata's direction against what the images show, without any model. + + python z_direction.py [--movie-early 2200] [--movie-late 30000] + +Every SMAPpy path assumes that a larger ``ZPositionUm`` is the objective raised: the focus moves from below +the glass into the buffer. Bead stacks (`calibrate.input.read_bead_stacks`) order their planes by increasing +``ZPositionUm``; molecule sweeps (`molecule_stack.stage_z_um`) take z = −(stage z − focus); in situ's focus is +how far the objective was raised above the coverslip's focus (docs/uipsf/conventions.md, "Positions and the +sign of z"). If on M2 ``ZPositionUm`` were the other way round -- another focus device, or a piezo counting +down -- beads and sweeps would learn the twin of the true pupil (astigmatism and spherical flipped, z mirrored) +and could not tell: molecules and beads on the glass see no depth, so for them the twin is nearly degenerate. +A cell can: its molecules sit above the glass, behind the index mismatch. The twin test preferring the +mirrored pupil by 800-1500 nats in every M2 in situ run (architecture.md, "In situ against molecule stacks on +M2") is what an inverted stage z would give. + +Three checks: + +1. **The metadata.** For every bead stack and molecule sweep file: which frame tags name a z (the key + ``ZPositionUm`` comes from, and any PI or focus device beside it), the first and last value, and whether z + rises along the frames. +2. **The stack's elongation against stage z.** Each spot's elliptical Gaussian (`molecule_stack.first_spots`) + per frame, the median log₂(σx/σy) of each stage z. An astigmatic PSF goes from one elongation to the other + through focus; which one is at the *smallest* ``ZPositionUm`` is the one of molecules *above* the focus if + the convention holds. +3. **The movie's molecules on the glass.** In the nucleus movie the glass molecules appear only in the first + ~2200 frames, and the focus is inside the nucleus, above them: they are *below* the focus, and the most + defocused spots of the early frames. Their elongation is the excess of the early frames' log₂(σx/σy) over + the late frames' at the extremes. + +What to read: if the convention holds, the movie's glass molecules (below focus) are elongated the *opposite* +way to the sweeps' spots at the smallest stage z (above focus). The same way means ``ZPositionUm`` runs +opposite to what the code assumes for these files, and every M2 bead and sweep model is the twin. +""" +import argparse +import glob +import os +import sys + +import numpy as np + +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +from heights import MOVIE, ROOT # noqa: E402 + +SETS = {"beads": "261112_MR_Intercalib2_Beads_1_700/*/*.ome.tif", + "ab": "261112_MR_Intercalib2_AB_50ms_coverslip/*/*.ome.tif"} +FAR = 0.4 # |log₂(σx/σy)| beyond which a spot counts as clearly elongated + + +def read_with_tags(path, frames=None): + """The file's frames (all, or ``frames`` = (start, stop)) and its frame tags, as `molecule_stack.read_file` + reads them.""" + from smappy.frametags import FrameTags + from smappy.io.tiff import open_stack + source = open_stack(path) + source.tags = FrameTags() + start, stop = (0, None) if frames is None else frames + out = [block for _, block in source.frames(chunk=200, start=start, stop=stop)] + return np.concatenate(out), source + + +def z_keys(source) -> dict: + """Every frame tag whose name says z, focus or PI: {name: (first, last)} where the values are numbers.""" + table = source.tags.table() if source.tags is not None else {} + out = {} + for key, values in table.items(): + k = key.lower() + if "z" in k.split("-")[-1] or "focus" in k or "pi" in k.split("-")[0] or "zposition" in k: + try: + v = np.asarray(values, float) + except (TypeError, ValueError): + continue + if v.size: + out[key] = (float(v[0]), float(v[-1]), float(np.ptp(v))) + return out + + +def elongation(spots) -> np.ndarray: + return np.log2(np.asarray(spots["sigma_x_pix"]) / np.asarray(spots["sigma_y_pix"])) + + +def stack_check(name, pattern): + from smappy.calibrate.molecule_stack import first_spots, stage_z_um + files = sorted(glob.glob(os.path.join(ROOT, pattern))) + print(f"\n== {name}: {len(files)} files") + lows, highs = [], [] + for path in files: + frames, source = read_with_tags(path) + z = stage_z_um(source, path) + print(f" {os.path.basename(os.path.dirname(path)) or os.path.basename(path)}: {len(frames)} frames") + for key, (a, b, span) in z_keys(source).items(): + print(f" tag {key}: first {a:.3f}, last {b:.3f}, range {span:.3f}") + if z is None or len(z) != len(frames) or np.ptp(z) == 0: + print(" no usable stage z") + continue + rising = np.mean(np.diff(z) > 0) + print(f" stage z (ZPositionUm): {z[0]:.3f} -> {z[-1]:.3f} µm, rising in {rising:.0%} of steps") + spots = first_spots(frames) + e = elongation(spots) + zs = z[np.asarray(spots["frame"], int)] + lo, hi = np.quantile(z, [0.1, 0.9]) + bright = np.asarray(spots["photons"]) > np.nanmedian(spots["photons"]) + e_lo, e_hi = e[(zs <= lo) & bright], e[(zs >= hi) & bright] + lows.append(e_lo) + highs.append(e_hi) + print(f" log2(sx/sy), bright spots: at the lowest 10% of stage z {np.nanmedian(e_lo):+.2f} (n {len(e_lo)})," + f" at the highest 10% {np.nanmedian(e_hi):+.2f} (n {len(e_hi)})") + if lows: + lo, hi = np.concatenate(lows), np.concatenate(highs) + print(f" all {name}: smallest stage z {np.nanmedian(lo):+.2f}, largest {np.nanmedian(hi):+.2f}") + return float(np.nanmedian(lo)), float(np.nanmedian(hi)) + return None + + +def movie_check(early_frames: int, late_start: int): + from smappy.calibrate.molecule_stack import first_spots + path = sorted(glob.glob(os.path.join(ROOT, MOVIE)))[0] + print(f"\n== movie {os.path.basename(path)}: frames 0-{early_frames} against {late_start}-" + f"{late_start + early_frames}") + out = {} + for label, span in (("early", (0, early_frames)), ("late", (late_start, late_start + early_frames))): + frames, _ = read_with_tags(path, span) + spots = first_spots(frames) + bright = np.asarray(spots["photons"]) > np.nanmedian(spots["photons"]) + out[label] = elongation(spots)[bright] + e = out[label] + print(f" {label:5s}: {len(e)} bright spots; elongated log2(sx/sy) > +{FAR}: {np.mean(e > FAR):.1%}, " + f"< -{FAR}: {np.mean(e < -FAR):.1%}; median {np.nanmedian(e):+.2f}") + plus = np.mean(out["early"] > FAR) - np.mean(out["late"] > FAR) + minus = np.mean(out["early"] < -FAR) - np.mean(out["late"] < -FAR) + side = "+" if plus > minus else "-" + print(f" the early frames' excess (the glass molecules, below focus): {plus:+.1%} at sx > sy, " + f"{minus:+.1%} at sy > sx -> elongated {side}") + return side + + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument("--movie-early", type=int, default=2200) + ap.add_argument("--movie-late", type=int, default=30000) + a = ap.parse_args() + stacks = {name: stack_check(name, pattern) for name, pattern in SETS.items()} + glass = movie_check(a.movie_early, a.movie_late) + print("\n== verdict") + for name, r in stacks.items(): + if r is None: + continue + low_side = "+" if r[0] > 0 else "-" + agree = low_side != glass + print(f" {name}: spots at the smallest stage z elongated {low_side}, the movie's glass molecules {glass}: " + + ("opposite, as the convention says (smallest z = focus below the glass)" if agree else + "THE SAME: the stage z runs opposite to the code's convention for these files")) + + +if __name__ == "__main__": + main() diff --git a/docs/uipsf/architecture.md b/docs/uipsf/architecture.md index 8378b92f..723bf8d4 100644 --- a/docs/uipsf/architecture.md +++ b/docs/uipsf/architecture.md @@ -2767,6 +2767,15 @@ better): - A tilt held at the edge's value (along y) in situ, to see what the pupil does with it. - Learning the index per height range, or an index gradient. +**The stage's direction** (`z_direction.py`, written after the follow-up, not yet run). The twin test prefers the +mirrored pupil by 800-1500 nats in every M2 in situ run. That is what a stage z running opposite to the code's +convention would give: every path takes a larger ``ZPositionUm`` as the objective raised (beads order their planes +by it, sweeps take z = −(stage z − focus), in situ's focus is the objective's rise above the coverslip), and beads +and molecules on the glass see no depth, so they would learn the twin without noticing. The script prints the +files' z tags and their direction, the sweeps' and bead stacks' spot elongation at the smallest and largest stage +z, and the elongation of the movie's glass molecules (below the focus, in its first ~2200 frames). If the +convention holds, the glass molecules are elongated the opposite way to the spots at the smallest stage z. + ## 4Pi from beads (October 2026; `docs/4pi.md` D7 and §8) ```