MyoSeg / src /myoseg_core.py
skarugu's picture
Upload myoseg_core.py
e0677c3 verified
Raw History Blame Contribute Delete
45.5 kB
# 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