# src/myoseg_core.py """ MyoSeg core — the analysis engine with no Streamlit dependency. Everything that *computes* lives here; streamlit_app.py only draws the UI. The same functions are meant to back every front end: • the Streamlit app (today) • a chat assistant panel (LLM calls these as tools) • an MCP server / REST API (other AI assistants call these) • batch scripts and the paper's validation notebooks Main entry points ----------------- load_model(path, device) -> (model, info) prepare_inputs(rgb, params) -> (x, myc_full) predict_probs(model, x, device) -> probs (2, H, W) ProbCache -> skip the U-Net when only postprocessing changes analyze_probs(probs, myc_full, p) -> masks + labels + metrics analyze_image(model, rgb, p, ...) -> one call: inference (cached) + analysis compare_presets(probs, myc_full, p) -> metrics for every preset, no extra inference quality_check(rgb, params, probs) -> image-quality warnings (cheap, no AI) diagnose(metrics, params) -> plain-language issues + suggested parameter changes Results are numerically identical to streamlit_app v9; the speedups come from cropping per-object work to bounding boxes and from caching model output. """ from __future__ import annotations import hashlib import os import warnings from collections import OrderedDict from copy import deepcopy import numpy as np import scipy.ndimage as ndi import torch import torch.nn as nn from PIL import Image from skimage import measure from skimage.feature import peak_local_max from skimage.morphology import disk, remove_small_objects from skimage.segmentation import relabel_sequential, watershed CORE_VERSION = "core-1.0" # scikit-image 0.26 deprecates `min_size` / `*_axis_length`. Behaviour is unchanged # until 2.0 (pinned below that in requirements.txt), so keep the logs readable. warnings.filterwarnings("ignore", message=r".*(min_size|axis_length).*deprecated", category=FutureWarning) # ───────────────────────────────────────────────────────────────────────────── # Parameters and presets # ───────────────────────────────────────────────────────────────────────────── PRESETS = { "Training defaults": {"thr_nuc": 0.45, "thr_myo": 0.23, "min_nuc_area": 20, "min_myo_area": 200, "nuc_close_radius": 2, "myo_open_radius": 1, "myo_erode_radius": 7, "min_myo_aspect_ratio": 0.0, "myo_max_area_px": 3200, "myo_split_min_seeds": 2}, "Standard": {"thr_nuc": 0.45, "thr_myo": 0.40, "min_nuc_area": 20, "min_myo_area": 500, "nuc_close_radius": 2, "myo_open_radius": 2, "myo_erode_radius": 2, "min_myo_aspect_ratio": 0.0, "myo_max_area_px": 20000, "myo_split_min_seeds": 2}, "Dense culture rescue": {"thr_nuc": 0.42, "thr_myo": 0.28, "min_nuc_area": 15, "min_myo_area": 250, "nuc_close_radius": 2, "myo_open_radius": 1, "myo_erode_radius": 4, "min_myo_aspect_ratio": 0.0, "myo_max_area_px": 6000, "myo_split_min_seeds": 2}, "Sparse cleanup": {"thr_nuc": 0.45, "thr_myo": 0.45, "min_nuc_area": 20, "min_myo_area": 800, "nuc_close_radius": 2, "myo_open_radius": 2, "myo_erode_radius": 2, "min_myo_aspect_ratio": 1.5, "myo_max_area_px": 25000, "myo_split_min_seeds": 3}, # Chosen by cross-validated search against 55 manually counted wells (passages 7-20; # P9 w1 and P15 w1 excluded: their image files have no MyHC channel), # model sha256 49cb24ea7cfb…, Oct 2026 — see tuning/tune.py and tuning/out/. "Tuned to manual counts": {"thr_nuc": 0.55, "min_nuc_area": 8, "nuc_close_radius": 0, "nuc_ws_min_distance": 4, "nuc_ws_min_area": 6, "thr_myo": 0.26, "min_myo_area": 500, "myo_open_radius": 1, "myo_erode_radius": 5, "min_myo_aspect_ratio": 0.0, "myo_max_area_px": 6000, "myo_split_min_seeds": 2, "fi_method": "cytoplasm-hole", "hole_ratio_thr": 0.9, "myhc_mask": "separated", "apply_split_to_metrics": True}, } # Presets that reproduce v9 exactly (used by the equivalence test). V9_PRESETS = ("Training defaults", "Standard", "Dense culture rescue", "Sparse cleanup") # Everything the pipeline needs, with the app's sidebar defaults. DEFAULT_PARAMS = { # input mapping / preprocessing (changing these requires new inference) "src_myo": "Red", "inv_myo": False, "src_nuc": "Blue", "inv_nuc": False, "image_size": 512, # Remove burned-in white annotations (scale bars, text) before analysis. Fluorescence in a # red/blue image is never bright in all three channels, so those pixels are zeroed. "mask_overlays": True, # test-time augmentation: "none" (v9 behaviour), "flip4" (4 flips), "d8" (4 rotations x 2 flips). # The model was trained with flip/rot90 augmentation, so these views are in-distribution. "tta": "none", # fusion-index method "fi_method": "cytoplasm-hole", # or "pixel-overlap" "hole_ratio_thr": 0.78, "ring_width": 6, "min_overlap_frac": 0.10, # nuclei watershed "nuc_ws_min_distance": 3, "nuc_ws_min_area": 6, # calibration "px_um": 1.0, # Off by default so metrics match v9 / the validation data. When True, the # nucleus-seeded myotube split (myo_max_area_px) is applied BEFORE counting, # so presets that rely on splitting also change myotube_count / FI. "apply_split_to_metrics": False, # Which myotube mask decides MyHC+ / fused nuclei: # "separated" (v9): the eroded+re-dilated mask used for counting myotubes. Bridge-breaking # also trims thin myotube parts, so nuclei there are lost as MyHC+. # "full": the mask WITHOUT bridge-breaking erosion. Separated myotubes are grown # back into it (geodesic flood), and thin myotubes deleted by erosion # come back as their own objects. Counts keep the separation, MyHC+ # keeps the full cytoplasm. "myhc_mask": "separated", # Thin-myotube recovery (0 = off, v9 behaviour). Bridge-breaking erosion deletes myotubes # only a few pixels wide. With a value > 0, any myotube in the un-eroded mask that erosion # removed completely is put back if its centre-line (skeleton) is at least this many px long. "recover_thin_min_length": 0, **PRESETS["Training defaults"], } # Parameters whose change does NOT require re-running the U-Net. INFERENCE_KEYS = ("src_myo", "inv_myo", "src_nuc", "inv_nuc", "image_size", "tta", "mask_overlays") def make_params(preset: str | None = None, **overrides) -> dict: """Full parameter dict: defaults → preset → overrides. Unknown keys are rejected.""" p = deepcopy(DEFAULT_PARAMS) if preset: if preset not in PRESETS: raise ValueError(f"Unknown preset {preset!r}. Options: {list(PRESETS)}") p.update(PRESETS[preset]) unknown = set(overrides) - set(p) if unknown: raise ValueError(f"Unknown parameter(s): {sorted(unknown)}") p.update(overrides) return p # ───────────────────────────────────────────────────────────────────────────── # Small helpers # ───────────────────────────────────────────────────────────────────────────── def _as_bool_c_array(mask) -> np.ndarray: return np.ascontiguousarray(np.asarray(mask, dtype=bool)) def _safe_binary_dilation(mask, footprint): return ndi.binary_dilation(_as_bool_c_array(mask), structure=np.asarray(footprint, dtype=bool)) def _safe_binary_erosion(mask, footprint): return ndi.binary_erosion(_as_bool_c_array(mask), structure=np.asarray(footprint, dtype=bool)) def _safe_binary_opening(mask, footprint): return ndi.binary_opening(_as_bool_c_array(mask), structure=np.asarray(footprint, dtype=bool)) def _safe_binary_closing(mask, footprint): return ndi.binary_closing(_as_bool_c_array(mask), structure=np.asarray(footprint, dtype=bool)) def sha256_file(path: str) -> str: h = hashlib.sha256() with open(path, "rb") as f: for chunk in iter(lambda: f.read(1024 * 1024), b""): h.update(chunk) return h.hexdigest() def array_hash(arr: np.ndarray) -> str: """Content hash of an image array (shape + dtype + bytes).""" h = hashlib.sha1() h.update(str(arr.shape).encode()); h.update(str(arr.dtype).encode()) h.update(np.ascontiguousarray(arr).tobytes()) return h.hexdigest() def resize_u8_to_float01(ch_u8: np.ndarray, W: int, H: int, resample=Image.BILINEAR) -> np.ndarray: im = Image.fromarray(ch_u8, mode="L").resize((W, H), resample=resample) return np.array(im, dtype=np.float32) / 255.0 def get_channel(rgb_u8: np.ndarray, source: str) -> np.ndarray: if source == "Red": return rgb_u8[..., 0] if source == "Green": return rgb_u8[..., 1] if source == "Blue": return rgb_u8[..., 2] return (0.299*rgb_u8[..., 0] + 0.587*rgb_u8[..., 1] + 0.114*rgb_u8[..., 2]).astype(np.uint8) def load_rgb(path_or_bytes) -> np.ndarray: """Load any supported image as uint8 RGB.""" import io src = io.BytesIO(path_or_bytes) if isinstance(path_or_bytes, (bytes, bytearray)) else path_or_bytes return np.array(Image.open(src).convert("RGB"), dtype=np.uint8) # ───────────────────────────────────────────────────────────────────────────── # Model # ───────────────────────────────────────────────────────────────────────────── class DoubleConv(nn.Module): def __init__(self, in_ch, out_ch): super().__init__() self.net = nn.Sequential( nn.Conv2d(in_ch, out_ch, 3, padding=1), nn.BatchNorm2d(out_ch), nn.ReLU(True), nn.Conv2d(out_ch, out_ch, 3, padding=1), nn.BatchNorm2d(out_ch), nn.ReLU(True), ) def forward(self, x): return self.net(x) class UNet(nn.Module): def __init__(self, in_ch=2, out_ch=2, base=32): super().__init__() self.d1 = DoubleConv(in_ch, base); self.p1 = nn.MaxPool2d(2) self.d2 = DoubleConv(base, base*2); self.p2 = nn.MaxPool2d(2) self.d3 = DoubleConv(base*2, base*4); self.p3 = nn.MaxPool2d(2) self.d4 = DoubleConv(base*4, base*8); self.p4 = nn.MaxPool2d(2) self.bn = DoubleConv(base*8, base*16) self.u4 = nn.ConvTranspose2d(base*16, base*8, 2, 2); self.du4 = DoubleConv(base*16, base*8) self.u3 = nn.ConvTranspose2d(base*8, base*4, 2, 2); self.du3 = DoubleConv(base*8, base*4) self.u2 = nn.ConvTranspose2d(base*4, base*2, 2, 2); self.du2 = DoubleConv(base*4, base*2) self.u1 = nn.ConvTranspose2d(base*2, base, 2, 2); self.du1 = DoubleConv(base*2, base) self.out = nn.Conv2d(base, out_ch, 1) def forward(self, x): d1=self.d1(x); p1=self.p1(d1) d2=self.d2(p1); p2=self.p2(d2) d3=self.d3(p2); p3=self.p3(d3) d4=self.d4(p3); p4=self.p4(d4) b=self.bn(p4) x=self.u4(b); x=torch.cat([x,d4],1); x=self.du4(x) x=self.u3(x); x=torch.cat([x,d3],1); x=self.du3(x) x=self.u2(x); x=torch.cat([x,d2],1); x=self.du2(x) x=self.u1(x); x=torch.cat([x,d1],1); x=self.du1(x) return self.out(x) def load_model(path: str, device: str = "cpu"): """Load U-Net weights from a local .pt file. Returns (model, info).""" ckpt = torch.load(path, map_location=device, weights_only=False) state = ckpt["model"] if isinstance(ckpt, dict) and "model" in ckpt else ckpt model = UNet(in_ch=2, out_ch=2, base=32) model.load_state_dict(state) model.to(device).eval() info = { "path": str(path), "sha256": sha256_file(path), "size_mb": round(os.path.getsize(path) / 1e6, 2), "train_args": ckpt.get("args") if isinstance(ckpt, dict) else None, "architecture": "unet_v1", } return model, info def remove_overlays(rgb_u8: np.ndarray, level: int = 150) -> np.ndarray: """Zero burned-in white/grey annotations (scale bars, text): pixels bright in ALL channels.""" if rgb_u8.ndim != 3 or rgb_u8.shape[2] < 3: return rgb_u8 white = rgb_u8[..., :3].min(axis=2) > level if not white.any(): return rgb_u8 white = ndi.binary_dilation(white, iterations=2) out = rgb_u8.copy() out[white] = 0 return out def prepare_inputs(rgb_u8: np.ndarray, params: dict): """Channel mapping + resize. Returns (x float32 (2,H,W), myc_full uint8 full-res MyHC).""" if params.get("mask_overlays", True): rgb_u8 = remove_overlays(rgb_u8) ch1 = get_channel(rgb_u8, params["src_myo"]) ch2 = get_channel(rgb_u8, params["src_nuc"]) if params["inv_myo"]: ch1 = 255 - ch1 if params["inv_nuc"]: ch2 = 255 - ch2 myc_full = ch1.copy() H = W = int(params["image_size"]) x1 = resize_u8_to_float01(ch1, W, H, Image.BILINEAR) x2 = resize_u8_to_float01(ch2, W, H, Image.BILINEAR) return np.stack([x1, x2], 0).astype(np.float32), myc_full TTA_MODES = {"none": 1, "flip4": 4, "d8": 8} def _d4(t: torch.Tensor, k: int) -> torch.Tensor: """k-th element of the dihedral group on the last two dims (k<4: rotate k*90°, k>=4: flip then rotate).""" if k >= 4: t = torch.flip(t, dims=(-1,)) return torch.rot90(t, k % 4, dims=(-2, -1)) def _d4_inv(t: torch.Tensor, k: int) -> torch.Tensor: t = torch.rot90(t, -(k % 4), dims=(-2, -1)) if k >= 4: t = torch.flip(t, dims=(-1,)) return t _TTA_VIEWS = {"none": [0], "flip4": [0, 4, 6, 2], "d8": list(range(8))} # flip4 = id, h-flip, v-flip, 180° def predict_probs(model, x: np.ndarray, device: str = "cpu", tta: str = "none", return_std: bool = False): """ U-Net probabilities (2, H, W). With tta != "none", every view is run in one batch, mapped back, and averaged (after the sigmoid). return_std also gives the per-pixel standard deviation across views — a direct measure of how much the model's answer depends on orientation (None when tta == "none"). """ if tta not in _TTA_VIEWS: raise ValueError(f"tta must be one of {list(_TTA_VIEWS)}") x_t = torch.from_numpy(x).unsqueeze(0).to(device) views = _TTA_VIEWS[tta] with torch.inference_mode(): if views == [0]: probs = torch.sigmoid(model(x_t)).cpu().numpy()[0] return (probs, None) if return_std else probs batch = torch.cat([_d4(x_t, k) for k in views], 0) out = torch.sigmoid(model(batch)) out = torch.stack([_d4_inv(out[i], k) for i, k in enumerate(views)], 0).cpu().numpy() probs, std = out.mean(0), out.std(0) return (probs, std) if return_std else probs def uncertainty_score(probs: np.ndarray, tta_std: np.ndarray | None = None, region_thr: float = 0.1) -> dict: """ Per-image uncertainty, 0 (sure) … 1 (coin-flip), for nuclei and myotubes. entropy mean binary entropy of the probability over candidate pixels (p > region_thr) — background far from any object is ignored, otherwise every image would look "confident". disagreement mean TTA standard deviation over the same pixels (TTA only). uncertainty the headline number: mean of the two channels' entropy. """ out = {} ents = [] for i, name in enumerate(("nuclei", "myotube")): p = np.clip(probs[i].astype(np.float64), 1e-6, 1 - 1e-6) region = p > region_thr if region.sum() == 0: ent = 0.0 else: pr = p[region] ent = float((-(pr * np.log2(pr) + (1 - pr) * np.log2(1 - pr))).mean()) out[f"{name}_entropy"] = round(ent, 4) ents.append(ent) if tta_std is not None: out[f"{name}_tta_disagreement"] = round(float(tta_std[i][region].mean()) if region.any() else 0.0, 4) out["uncertainty"] = round(float(np.mean(ents)), 4) return out def model_confidence(probs: np.ndarray) -> float: """Legacy confidence used by the retrain queue (mean of per-channel max prob).""" return float(np.mean([probs[0].max(), probs[1].max()])) class ProbCache: """ Small LRU cache of U-Net probability maps. Key = (image content hash, channel mapping, input size, model sha). Thresholds, postprocessing, FI method and calibration are NOT part of the key, so changing any of them reuses the cached model output. """ def __init__(self, max_items: int = 64): self.max_items = max_items self._d: OrderedDict = OrderedDict() self.hits = 0 self.misses = 0 @staticmethod def key(img_hash: str, params: dict, model_sha: str) -> tuple: return (img_hash, model_sha) + tuple(params[k] for k in INFERENCE_KEYS) def get(self, k): if k in self._d: self._d.move_to_end(k) self.hits += 1 return self._d[k] self.misses += 1 return None def put(self, k, value): self._d[k] = value self._d.move_to_end(k) while len(self._d) > self.max_items: self._d.popitem(last=False) def __len__(self): return len(self._d) # ───────────────────────────────────────────────────────────────────────────── # Postprocessing # ───────────────────────────────────────────────────────────────────────────── def postprocess_masks(nuc_mask, myo_mask, min_nuc_area=20, min_myo_area=500, nuc_close_radius=2, myo_open_radius=2, myo_erode_radius=2, min_myo_aspect_ratio=0.0): """ Nuclei: optional closing, then remove small objects. Myotubes: opening → erode+dilate (bridge breaking) → size filter → optional aspect-ratio filter. No closing for myotubes (merges neighbours). """ nuc_bin = nuc_mask.astype(bool) if int(nuc_close_radius) > 0: nuc_bin = _safe_binary_closing(nuc_bin, disk(int(nuc_close_radius))) nuc_clean = remove_small_objects(nuc_bin, min_size=int(min_nuc_area)).astype(np.uint8) myo_bin = myo_mask.astype(bool) if int(myo_open_radius) > 0: myo_bin = _safe_binary_opening(myo_bin, disk(int(myo_open_radius))) if int(myo_erode_radius) > 0: se = disk(int(myo_erode_radius)) myo_bin = _safe_binary_erosion(myo_bin, se) myo_bin = _safe_binary_dilation(myo_bin, se) myo_bin = remove_small_objects(myo_bin, min_size=int(min_myo_area)) if float(min_myo_aspect_ratio) > 0: myo_bin = _filter_by_aspect_ratio(myo_bin, float(min_myo_aspect_ratio)) return nuc_clean, myo_bin.astype(np.uint8) def _filter_by_aspect_ratio(mask_bin: np.ndarray, min_aspect: float) -> np.ndarray: """Keep regions with major/minor axis ratio >= min_aspect (lookup table, one pass).""" lab, n = ndi.label(mask_bin.astype(np.uint8)) keep_lut = np.zeros(n + 1, dtype=bool) for prop in measure.regionprops(lab): if prop.minor_axis_length > 0: keep_lut[prop.label] = (prop.major_axis_length / prop.minor_axis_length) >= min_aspect else: keep_lut[prop.label] = True # degenerate line-like → very elongated return keep_lut[lab] def label_cc(mask: np.ndarray) -> np.ndarray: lab, _ = ndi.label(mask.astype(np.uint8)) return lab def split_large_myotubes(myo_lab: np.ndarray, nuc_lab: np.ndarray, max_area_px: int = 0, min_seeds: int = 2) -> np.ndarray: """ Split oversized myotube regions with nucleus-seeded watershed. Same algorithm as v9; work is cropped to each region's bounding box and nucleus centroids are computed once instead of once per region. """ if max_area_px <= 0: return myo_lab out = myo_lab.copy() next_id = int(myo_lab.max()) + 1 H, W = myo_lab.shape # nucleus centroids once (label order preserved, matching v9's seed overwrite order) cents = [(p.label, int(p.centroid[0]), int(p.centroid[1])) for p in measure.regionprops(nuc_lab)] for prop in measure.regionprops(myo_lab): if prop.area <= max_area_px: continue r0, c0, r1, c1 = prop.bbox # 1-px zero border (or image edge) keeps the distance transform identical r0p, c0p, r1p, c1p = max(r0 - 1, 0), max(c0 - 1, 0), min(r1 + 1, H), min(c1 + 1, W) region_mask = myo_lab[r0p:r1p, c0p:c1p] == prop.label seeds = np.zeros(region_mask.shape, dtype=np.int32) seed_count = 0 for lbl, r, c in cents: if r0p <= r < r1p and c0p <= c < c1p and region_mask[r - r0p, c - c0p]: seeds[r - r0p, c - c0p] = lbl seed_count += 1 if seed_count < min_seeds: continue dist = ndi.distance_transform_edt(region_mask) result = watershed(-dist, seeds, mask=region_mask) sub_out = out[r0p:r1p, c0p:c1p] sub_out[region_mask] = 0 for sub_id in np.unique(result): if sub_id == 0: continue sub_mask = result == sub_id if sub_mask.sum() < 10: continue sub_out[sub_mask] = next_id next_id += 1 final, _, _ = relabel_sequential(out) return final def label_nuclei_watershed(nuc_bin: np.ndarray, min_distance: int = 3, min_nuc_area: int = 6) -> np.ndarray: """Split touching nuclei via distance-transform watershed.""" nuc_bin = remove_small_objects(nuc_bin.astype(bool), min_size=min_nuc_area) if nuc_bin.sum() == 0: return np.zeros_like(nuc_bin, dtype=np.int32) dist = ndi.distance_transform_edt(nuc_bin) coords = peak_local_max(dist, labels=nuc_bin, min_distance=min_distance, exclude_border=False) markers = np.zeros_like(nuc_bin, dtype=np.int32) for i, (r, c) in enumerate(coords, start=1): markers[r, c] = i if markers.max() == 0: return ndi.label(nuc_bin.astype(np.uint8))[0].astype(np.int32) return watershed(-dist, markers, mask=nuc_bin).astype(np.int32) # ───────────────────────────────────────────────────────────────────────────── # Metrics # ───────────────────────────────────────────────────────────────────────────── def compute_surface_area(myo_mask: np.ndarray, px_um: float = 1.0, labels: np.ndarray | None = None) -> dict: lab = label_cc(myo_mask) if labels is None else labels px_area = px_um ** 2 per = [round(prop.area * px_area, 2) for prop in measure.regionprops(lab)] return { "total_area_um2": round(sum(per), 2), "mean_area_um2": round(float(np.mean(per)) if per else 0.0, 2), "max_area_um2": round(float(np.max(per)) if per else 0.0, 2), "per_myotube_areas": per, } def classify_nucleus_in_myotube(nuc_coords: np.ndarray, myc_channel: np.ndarray, myo_mask_full: np.ndarray, ring_width: int = 6, hole_ratio_thr: float = 0.85) -> bool: """ Cytoplasm-hole test (after MyoFuse, Lair et al.): a fused nucleus displaces MyHC cytoplasm and creates a local intensity dip; a nucleus lying above or below a myotube in Z does not. fused ⇔ I_nucleus / I_ring < hole_ratio_thr. Identical result to v9, but the ring is built inside a crop of (nucleus bbox + ring_width) instead of a full-image mask per nucleus. """ rows, cols = nuc_coords[:, 0], nuc_coords[:, 1] H, W = myc_channel.shape in_myo = myo_mask_full[rows, cols] if in_myo.sum() == 0: return False I_nuc = float(myc_channel[rows, cols].mean()) pad = int(ring_width) + 1 r0, r1 = max(int(rows.min()) - pad, 0), min(int(rows.max()) + pad + 1, H) c0, c1 = max(int(cols.min()) - pad, 0), min(int(cols.max()) + pad + 1, W) fp = np.zeros((r1 - r0, c1 - c0), dtype=bool) fp[rows - r0, cols - c0] = True ring = _safe_binary_dilation(fp, disk(ring_width)) & ~fp & myo_mask_full[r0:r1, c0:c1].astype(bool) if ring.sum() < 4: return in_myo.mean() >= 0.10 I_ring = float(myc_channel[r0:r1, c0:c1][ring].mean()) if I_ring < 1e-6: return in_myo.mean() >= 0.10 return (I_nuc / I_ring) < hole_ratio_thr def compute_bio_metrics(nuc_mask, myo_mask, myc_channel_full=None, min_overlap_frac=0.10, nuc_ws_min_distance=3, nuc_ws_min_area=6, px_um=1.0, ring_width=6, hole_ratio_thr=0.85, myo_lab=None, return_labels=False, area_from_labels=False) -> dict: """ All biological metrics. With myc_channel_full → cytoplasm-hole FI; without → legacy pixel-overlap FI. myo_lab optional pre-labelled myotubes (e.g. after split_large_myotubes); default labels connected components of myo_mask (v9 behaviour). return_labels also return "_nuc_lab" / "_myo_lab" so callers don't recompute them. """ nuc_lab = label_nuclei_watershed(nuc_mask, min_distance=nuc_ws_min_distance, min_nuc_area=nuc_ws_min_area) if myo_lab is None: myo_lab = label_cc(myo_mask) total = int(nuc_lab.max()) if myc_channel_full is not None: H_full, W_full = myc_channel_full.shape nuc_lab_full = np.array(Image.fromarray(nuc_lab.astype(np.int32)).resize((W_full, H_full), Image.NEAREST)) myo_mask_full = np.array( Image.fromarray((myo_mask * 255).astype(np.uint8)).resize((W_full, H_full), Image.NEAREST)) > 0 myc_f = myc_channel_full.astype(np.float32) if myc_f.max() > 1.0: myc_f = myc_f / 255.0 else: nuc_lab_full = nuc_lab myo_mask_full = myo_mask.astype(bool) myc_f = None pos, nm = 0, {} per_nucleus = [] # (label, fused) — handy for explanations / QC for prop in measure.regionprops(nuc_lab_full): coords = prop.coords if myc_f is not None: is_fused = classify_nucleus_in_myotube(coords, myc_f, myo_mask_full, ring_width=ring_width, hole_ratio_thr=hole_ratio_thr) else: ids = myo_mask_full.astype(np.uint8)[coords[:, 0], coords[:, 1]] is_fused = ids.sum() / max(len(coords), 1) >= min_overlap_frac if is_fused: if myc_f is not None: r_m = np.clip((coords[:, 0] * nuc_lab.shape[0] / H_full).astype(int), 0, nuc_lab.shape[0] - 1) c_m = np.clip((coords[:, 1] * nuc_lab.shape[1] / W_full).astype(int), 0, nuc_lab.shape[1] - 1) ids_mt = myo_lab[r_m, c_m] else: ids_mt = myo_lab[coords[:, 0], coords[:, 1]] ids_mt = ids_mt[ids_mt > 0] if ids_mt.size > 0: unique, counts = np.unique(ids_mt, return_counts=True) nm.setdefault(int(unique[np.argmax(counts)]), []).append(prop.label) pos += 1 per_nucleus.append((int(prop.label), bool(is_fused))) per = [len(v) for v in nm.values()] fused = sum(n for n in per if n >= 2) fi = 100.0 * fused / total if total else 0.0 pct = 100.0 * pos / total if total else 0.0 avg = float(np.mean(per)) if per else 0.0 sa = compute_surface_area(myo_mask, px_um=px_um, labels=myo_lab if area_from_labels else None) out = { "total_nuclei": total, "myHC_positive_nuclei": int(pos), "myHC_positive_percentage": round(pct, 2), "nuclei_fused": int(fused), "myotube_count": int(len(per)), "avg_nuclei_per_myotube": round(avg, 2), "fusion_index": round(fi, 2), "total_area_um2": sa["total_area_um2"], "mean_area_um2": sa["mean_area_um2"], "max_area_um2": sa["max_area_um2"], "_per_myotube_areas": sa["per_myotube_areas"], "_bio_myo_ids": set(nm.keys()), "_total_cc_count": int(myo_lab.max()), } if return_labels: out["_nuc_lab"] = nuc_lab out["_myo_lab"] = myo_lab out["_per_nucleus_fused"] = per_nucleus return out PUBLIC_METRICS = ("total_nuclei", "myotube_count", "myHC_positive_nuclei", "myHC_positive_percentage", "nuclei_fused", "fusion_index", "avg_nuclei_per_myotube", "total_area_um2", "mean_area_um2", "max_area_um2") def public_metrics(m: dict) -> dict: return {k: m[k] for k in PUBLIC_METRICS if k in m} def recover_thin_myotubes(myo_raw: np.ndarray, myo_pp: np.ndarray, p: dict) -> np.ndarray: """Add back myotubes that bridge-breaking erosion removed entirely, if long enough.""" from skimage.morphology import skeletonize L = int(p.get("recover_thin_min_length", 0)) if L <= 0: return myo_pp base = myo_raw.astype(bool) if int(p["myo_open_radius"]) > 0: base = _safe_binary_opening(base, disk(int(p["myo_open_radius"]))) lab, n = ndi.label(base) if n == 0: return myo_pp has_core = np.zeros(n + 1, bool) has_core[np.unique(lab[myo_pp > 0])] = True skel_len = ndi.sum(skeletonize(base), lab, index=np.arange(n + 1)) keep = (~has_core) & (skel_len >= L) keep[0] = False return ((myo_pp > 0) | keep[lab]).astype(np.uint8) def full_myotube_mask(myo_raw: np.ndarray, p: dict) -> np.ndarray: """Myotube mask with the same cleanup EXCEPT the bridge-breaking erosion.""" m = myo_raw.astype(bool) if int(p["myo_open_radius"]) > 0: m = _safe_binary_opening(m, disk(int(p["myo_open_radius"]))) big = remove_small_objects(m, min_size=int(p["min_myo_area"])) if int(p.get("recover_thin_min_length", 0)) > 0: # keep long thin tubes too big = big | (recover_thin_myotubes(m, np.zeros_like(m, np.uint8), p) > 0) if float(p["min_myo_aspect_ratio"]) > 0: big = _filter_by_aspect_ratio(big, float(p["min_myo_aspect_ratio"])) return big def grow_labels_into(sep_lab: np.ndarray, full_mask: np.ndarray) -> np.ndarray: """ Expand separated myotube labels to fill the full mask (each pixel goes to the geodesically nearest separated myotube), then give every full-mask component with no separated myotube in it (thin tubes removed by erosion) its own label. """ full = full_mask.astype(bool) seeds = np.where(full, sep_lab, 0).astype(np.int32) if seeds.max() > 0: dist = ndi.distance_transform_edt(seeds == 0) # grow from seeds outward lab = watershed(dist, seeds, mask=full) else: lab = np.zeros(full.shape, np.int32) rest, n = ndi.label(full & (lab == 0)) if n: lab = np.where(rest > 0, rest + lab.max(), lab) return relabel_sequential(lab.astype(np.int32))[0] # ───────────────────────────────────────────────────────────────────────────── # One-call analysis # ───────────────────────────────────────────────────────────────────────────── def analyze_probs(probs: np.ndarray, myc_full: np.ndarray, params: dict, with_labels: bool = False) -> dict: """ Threshold → postprocess → metrics, from cached model output. This is the cheap part; call it as often as you like while tuning. Returns dict with nuc_raw, myo_raw, nuc_pp, myo_pp, metrics and — when with_labels — nuc_lab / myo_lab (myo_lab after the optional large-myotube split). """ p = params nuc_raw = (probs[0] > float(p["thr_nuc"])).astype(np.uint8) myo_raw = (probs[1] > float(p["thr_myo"])).astype(np.uint8) nuc_pp, myo_pp = postprocess_masks( nuc_raw, myo_raw, min_nuc_area=int(p["min_nuc_area"]), min_myo_area=int(p["min_myo_area"]), nuc_close_radius=int(p["nuc_close_radius"]), myo_open_radius=int(p["myo_open_radius"]), myo_erode_radius=int(p["myo_erode_radius"]), min_myo_aspect_ratio=float(p["min_myo_aspect_ratio"]), ) myo_pp = recover_thin_myotubes(myo_raw, myo_pp, p) use_hole = p["fi_method"] == "cytoplasm-hole" common = dict( myc_channel_full=myc_full if use_hole else None, min_overlap_frac=float(p["min_overlap_frac"]), nuc_ws_min_distance=int(p["nuc_ws_min_distance"]), nuc_ws_min_area=int(p["nuc_ws_min_area"]), px_um=float(p["px_um"]), ring_width=int(p["ring_width"]), hole_ratio_thr=float(p["hole_ratio_thr"]), ) split_lab = None need_split = int(p["myo_max_area_px"]) > 0 and (with_labels or p.get("apply_split_to_metrics")) if need_split: nuc_lab0 = label_nuclei_watershed(nuc_pp, min_distance=int(p["nuc_ws_min_distance"]), min_nuc_area=int(p["nuc_ws_min_area"])) split_lab = split_large_myotubes(label_cc(myo_pp), nuc_lab0, max_area_px=int(p["myo_max_area_px"]), min_seeds=int(p["myo_split_min_seeds"])) sep_lab = split_lab if p.get("apply_split_to_metrics") else None if p.get("myhc_mask", "separated") == "full": myo_full = full_myotube_mask(myo_raw, p) if sep_lab is None: sep_lab = label_cc(myo_pp) full_lab = grow_labels_into(sep_lab, myo_full) bio = compute_bio_metrics(nuc_pp, (full_lab > 0).astype(np.uint8), myo_lab=full_lab, return_labels=True, area_from_labels=True, **common) if with_labels: split_lab = full_lab else: bio = compute_bio_metrics(nuc_pp, myo_pp, myo_lab=sep_lab, return_labels=True, **common) bio["fi_method"] = p["fi_method"] result = {"nuc_raw": nuc_raw, "myo_raw": myo_raw, "nuc_pp": nuc_pp, "myo_pp": myo_pp} nuc_lab = bio.pop("_nuc_lab"); myo_lab_metrics = bio.pop("_myo_lab") result["per_nucleus_fused"] = bio.pop("_per_nucleus_fused") if with_labels: result["nuc_lab"] = nuc_lab result["myo_lab"] = split_lab if split_lab is not None else myo_lab_metrics result["metrics"] = bio return result def analyze_image(model, rgb_u8: np.ndarray, params: dict, device: str = "cpu", cache: ProbCache | None = None, model_sha: str = "", with_labels: bool = False) -> dict: """Inference (cached when possible) + analysis. Adds 'probs', 'tta_std', 'myc_full', 'confidence', 'uncertainty' (dict), 'cache_hit'.""" x, myc_full = prepare_inputs(rgb_u8, params) entry, hit = None, False if cache is not None: k = ProbCache.key(array_hash(rgb_u8), params, model_sha) entry = cache.get(k) hit = entry is not None if entry is None: entry = predict_probs(model, x, device, tta=params.get("tta", "none"), return_std=True) if cache is not None: cache.put(k, entry) probs, tta_std = entry res = analyze_probs(probs, myc_full, params, with_labels=with_labels) res.update(probs=probs, tta_std=tta_std, myc_full=myc_full, confidence=model_confidence(probs), uncertainty=uncertainty_score(probs, tta_std), cache_hit=hit) return res def compare_presets(probs: np.ndarray, myc_full: np.ndarray, params: dict, presets=None) -> dict: """Metrics under every preset, reusing one model output. {preset: public metrics}.""" out = {} for name in presets or PRESETS: p = {**params, **PRESETS[name]} out[name] = public_metrics(analyze_probs(probs, myc_full, p)["metrics"]) return out # ───────────────────────────────────────────────────────────────────────────── # Quality control (plain image statistics — no extra model) # ───────────────────────────────────────────────────────────────────────────── def _laplacian_var(ch_u8: np.ndarray) -> float: return float(ndi.laplace(ch_u8.astype(np.float32)).var()) def quality_check(rgb_u8: np.ndarray, params: dict, probs: np.ndarray | None = None) -> dict: """ Cheap image-quality checks. Returns {"stats": {...}, "warnings": [str, ...]}. Sharpness is reported as a raw number; it is only meaningful relative to other images from the same microscope — use batch_quality_outliers() for that. """ myc = get_channel(rgb_u8, params["src_myo"]) dapi = get_channel(rgb_u8, params["src_nuc"]) warnings = [] stats = {} for name, ch in (("myhc", myc), ("dapi", dapi)): sat = float((ch >= 255).mean()) stats[f"{name}_saturated_frac"] = round(sat, 4) stats[f"{name}_p99"] = int(np.percentile(ch, 99)) stats[f"{name}_sharpness"] = round(_laplacian_var(ch), 2) if sat > 0.01: warnings.append(f"{name.upper()} channel: {sat:.1%} of pixels are saturated — " "intensity-based steps (cytoplasm-hole FI) may be unreliable.") if stats[f"{name}_p99"] < 20: warnings.append(f"{name.upper()} channel is nearly empty (99th percentile = " f"{stats[f'{name}_p99']}). Check the channel mapping.") if params["src_myo"] == params["src_nuc"] and params["inv_myo"] == params["inv_nuc"]: warnings.append("MyHC and DAPI are mapped to the same channel.") else: a, b = myc.astype(np.float32).ravel(), dapi.astype(np.float32).ravel() if a.std() > 0 and b.std() > 0: corr = float(np.corrcoef(a, b)[0, 1]) stats["channel_correlation"] = round(corr, 3) if corr > 0.95: warnings.append(f"MyHC and DAPI channels are almost identical (r = {corr:.2f}); " "the image may be grayscale or the channels mis-mapped.") if probs is not None: for i, name in enumerate(("nuclei", "myotube")): pr = probs[i] active = pr > 0.3 unsure = float(((pr > 0.3) & (pr < 0.7)).sum() / max(active.sum(), 1)) stats[f"{name}_uncertain_frac"] = round(unsure, 3) if active.sum() > 100 and unsure > 0.5: warnings.append(f"Model is unsure about most {name} pixels ({unsure:.0%} between 0.3 and 0.7) — " "image may differ from the training data.") return {"stats": stats, "warnings": warnings} def batch_quality_outliers(qc_by_image: dict, factor: float = 0.33) -> dict: """Flag images whose sharpness is far below the batch median. {image: [warnings]}.""" flags = {} for ch in ("myhc", "dapi"): vals = {k: v["stats"].get(f"{ch}_sharpness") for k, v in qc_by_image.items()} vals = {k: v for k, v in vals.items() if v is not None} if len(vals) < 3: continue med = float(np.median(list(vals.values()))) for k, v in vals.items(): if med > 0 and v < factor * med: flags.setdefault(k, []).append( f"{ch.upper()} channel looks blurrier than the rest of the batch " f"(sharpness {v:.0f} vs median {med:.0f}).") return flags # ───────────────────────────────────────────────────────────────────────────── # Diagnosis (rules that turn metrics into explanations + parameter suggestions) # ───────────────────────────────────────────────────────────────────────────── def validation_flags(m: dict) -> list: """Same rules as the app's validation report, returned as a list.""" f = lambda k: float(m.get(k, 0) or 0) flags = [] if f("total_nuclei") <= 0: flags.append("empty nuclei count") if f("myotube_count") <= 0: flags.append("empty myotube count") if f("myHC_positive_nuclei") > f("total_nuclei") > 0: flags.append("MyHC+ nuclei exceeds total nuclei") if f("myotube_count") <= 2 and f("total_area_um2") > 10000: flags.append("possible merged myotube region") if f("max_area_um2") > 0 and f("mean_area_um2") > 0 and f("max_area_um2") >= 8 * f("mean_area_um2"): flags.append("one myotube area dominates field") if f("fusion_index") > 60: flags.append("very high fusion index") if f("fusion_index") < 1 and f("myotube_count") > 5: flags.append("very low fusion index") return flags def diagnose(metrics: dict, params: dict) -> list: """ Turn validation flags into structured findings: [{"issue", "explanation", "suggest": {param: value}}] Suggestions are starting points for the user (or an agent) to try with analyze_probs — they are never applied automatically. """ out = [] for flag in validation_flags(metrics): if flag in ("possible merged myotube region", "one myotube area dominates field"): out.append({ "issue": flag, "explanation": "Touching myotubes are probably being counted as one object, " "which lowers myotube_count and inflates per-myotube area.", "suggest": {**PRESETS["Dense culture rescue"], "apply_split_to_metrics": True}, }) elif flag == "very low fusion index": new_thr = round(min(float(params["hole_ratio_thr"]) + 0.07, 0.95), 2) out.append({ "issue": flag, "explanation": "Myotubes were found but almost no nuclei were classified as fused. " "The cytoplasm-hole threshold may be too strict for this staining, " "or MyHC is saturated (no visible dip under nuclei).", "suggest": {"hole_ratio_thr": new_thr} if params["fi_method"] == "cytoplasm-hole" else {"fi_method": "cytoplasm-hole"}, }) elif flag == "very high fusion index": out.append({ "issue": flag, "explanation": "Unusually high FI. With pixel-overlap, nuclei lying on top of myotubes " "are counted as fused (overestimation reported by Lair et al.).", "suggest": {"fi_method": "cytoplasm-hole"} if params["fi_method"] != "cytoplasm-hole" else {"hole_ratio_thr": round(max(float(params["hole_ratio_thr"]) - 0.05, 0.5), 2)}, }) elif flag == "empty myotube count": out.append({ "issue": flag, "explanation": "No myotubes passed the threshold and size filters.", "suggest": {"thr_myo": round(max(float(params["thr_myo"]) - 0.1, 0.05), 2), "min_myo_area": max(int(params["min_myo_area"]) // 2, 50)}, }) elif flag == "empty nuclei count": out.append({ "issue": flag, "explanation": "No nuclei detected — check that DAPI is mapped to the right channel.", "suggest": {"thr_nuc": round(max(float(params["thr_nuc"]) - 0.1, 0.05), 2)}, }) else: out.append({"issue": flag, "explanation": "Inconsistent counts — inspect this image manually.", "suggest": {}}) return out