flimkit 0.12.0__py3-none-any.whl

flimkit/formats/PTU/reader.py

@@ -0,0 +1,235 @@
+import math
+import numpy as np
+from pathlib import Path
+
+def _load_ptufile():
+    try:
+        import ptufile
+    except ImportError:
+        raise ImportError('ptufile is required to read PicoQuant .ptu files '
+                          '(pip install ptufile)')
+    return ptufile
+
+def _norm_channel(channel):
+    if not isinstance(channel, str):
+        return channel
+    channel = channel.strip()
+    if channel == '':
+        return None
+    if channel.isdigit():
+        return int(channel)
+    return None
+
+def _fit_bins(arr, n_bins):
+    h = arr.shape[-1]
+    if h == n_bins:
+        return arr
+    if h > n_bins:
+        return arr[..., :n_bins]
+    pad = [(0, 0)] * (arr.ndim - 1) + [(0, n_bins - h)]
+    return np.pad(arr, pad)
+
+def _reduce_yxh(arr, dims):
+    d = list(dims)
+    if arr.ndim != len(d):
+        d = d[-arr.ndim:]
+    drop = tuple(i for i, x in enumerate(d) if x not in ('Y', 'X', 'H'))
+    if drop:
+        arr = arr.sum(axis=drop)
+    d = [x for x in d if x in ('Y', 'X', 'H')]
+    return np.transpose(arr, [d.index(x) for x in ('Y', 'X', 'H') if x in d])
+
+def _bin_cube(cube, binning):
+    if binning <= 1:
+        return cube
+    ny, nx, nh = cube.shape
+    ny2, nx2 = (ny // binning) * binning, (nx // binning) * binning
+    cube = cube[:ny2, :nx2, :]
+    return cube.reshape(ny2 // binning, binning, nx2 // binning, binning, nh).sum(axis=(1, 3))
+
+def read_pck(path):
+    ptufile = _load_ptufile()
+    try:
+        with ptufile.PqFile(str(path)) as f:
+            tags = dict(f.tags)
+    except Exception as exc:
+        raise ValueError(f'Not a PicoQuant Check (.pck) file: {path!r}') from exc
+    hist = tags.get('ChkHistogram')
+    if hist is None:
+        raise ValueError(f'No ChkHistogram block in {path!r} - not a Check/IRF .pck?')
+    hist = np.frombuffer(np.asarray(hist).tobytes(), dtype='<u4')
+    n_chan = max(1, int(tags.get('ChkChannels', 1)))
+    if hist.size % n_chan == 0:
+        hist = hist.reshape(n_chan, hist.size // n_chan)
+    else:
+        hist = hist.reshape(1, hist.size)
+    return hist, tags
+
+class PTUFile:
+    def __init__(self, path, verbose=True):
+        self.path = str(path)
+        self.verbose = verbose
+        ptufile = _load_ptufile()
+        self._ptu = ptufile.PtuFile(self.path)
+        self._parse_meta()
+
+    def _parse_meta(self):
+        p = self._ptu
+        dims = dict(zip(p.dims, p.shape))
+        self.tcspc_res = float(p.tcspc_resolution)
+        gr = float(p.global_resolution) if p.global_resolution else 0.0
+        self.global_resolution = gr
+        self.sync_rate = (1.0 / gr) if gr else 0.0
+        self.period_ns = gr * 1e9
+        self.n_bins_stored = int(dims.get('H', 0))
+        if self.tcspc_res > 0 and gr > 0:
+            self.n_bins = int(math.ceil(gr / self.tcspc_res))
+        else:
+            self.n_bins = self.n_bins_stored
+        self.n_x = int(dims.get('X', 0))
+        self.n_y = int(dims.get('Y', 0))
+        self.is_image = bool(getattr(p, 'is_image', self.n_x > 0 and self.n_y > 0))
+        self._active = [int(c) for c in p.active_channels]
+        self.n_channels = len(self._active)
+        self.n_records = int(getattr(p, 'number_records', 0) or 0)
+        self.n_photons = int(getattr(p, 'number_photons', 0) or 0)
+        self.n_frames = int(getattr(p, 'number_images', 0) or 0) or 1
+        self.n_sync = int(getattr(p, 'global_acquisition_time', 0) or 0) or None
+        self.acq_time_s = float(getattr(p, 'acquisition_time', 0.0) or 0.0) or None
+        self.time_ns = (np.arange(self.n_bins) + 0.5) * self.tcspc_res * 1e9
+        self.photon_channel = None
+        self.tags = dict(p.tags)
+        self.rec_type = int(self.tags.get('TTResultFormat_TTTRRecType', 0))
+        self._total_photons = None
+        if self.verbose:
+            print(f"  PTU      : {Path(self.path).name}")
+            print(f"  RecType  : 0x{self.rec_type:08X}")
+            print(f"  TCSPC    : {self.n_bins} bins x {self.tcspc_res*1e12:.2f} ps")
+            if self.n_bins_stored > self.n_bins:
+                print(f"             ({self.n_bins_stored} stored, using {self.n_bins} within one laser period)")
+            print(f"  Laser    : {self.sync_rate/1e6:.3f} MHz  ({self.period_ns:.3f} ns)")
+            if self.is_image:
+                print(f"  Image    : {self.n_x} x {self.n_y} px, {self.n_channels} channel(s)")
+            else:
+                print(f"  Point    : {self.n_channels} channel(s)")
+            print(f"  Records  : {self.n_records:,}  ({self.n_photons:,} photons)")
+            if self.n_sync:
+                print(f"  Sync     : {self.n_sync:,} pulses over {self.acq_time_s or 0.0:.1f} s"
+                      f"  ({self.n_photons / self.n_sync:.4f} photons/pulse)")
+            print(' ')
+
+    def close(self):
+        try:
+            self._ptu.close()
+        except Exception:
+            pass
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        self.close()
+
+    @property
+    def photons_per_pulse(self):
+        if self._total_photons is None or not self.n_sync:
+            return None
+        return self._total_photons / self.n_sync
+
+    def _ch_pos(self, channel):
+        channel = int(channel)
+        if channel in self._active:
+            return self._active.index(channel)
+        if 0 <= channel < self.n_channels:
+            return channel
+        if self.n_channels == 1:
+            return 0
+        raise ValueError(f'Channel {channel} not in PTU active channels {self._active}')
+
+    def summed_decay(self, channel=None):
+        channel = _norm_channel(channel)
+        h = np.asarray(self._ptu.decode_histogram(asxarray=False), dtype=float)
+        if h.ndim == 1:
+            h = h[None, :]
+        if channel is None:
+            pos = int(np.argmax(h.sum(axis=1)))
+            self.photon_channel = self._active[pos] if self._active else 0
+        else:
+            pos = self._ch_pos(channel)
+        decay = _fit_bins(h[pos], self.n_bins).astype(float)
+        self._total_photons = int(decay.sum())
+        return decay
+
+    def _decode_cube(self, channel):
+        channel = _norm_channel(channel)
+        if channel is None:
+            if self.photon_channel is None:
+                self.summed_decay(channel=None)
+            channel = self.photon_channel
+        pos = self._ch_pos(channel)
+        p = self._ptu
+        dims = dict(zip(p.dims, p.shape))
+        ny, nx = int(dims.get('Y', 0)), int(dims.get('X', 0))
+        if ny == 0 or nx == 0:
+            raise RuntimeError('PTU has no scan image (point-mode); use summed_decay')
+        arr = np.asarray(p.decode_image(channel=pos, frame=-1, asxarray=False))
+        cube = _reduce_yxh(arr, p.dims)
+        return _fit_bins(cube, self.n_bins).astype(np.uint32)
+
+    def raw_pixel_stack(self, channel=None, binning=1):
+        cube = self._decode_cube(channel)
+        if binning > 1:
+            cube = _bin_cube(cube, binning)
+        self._total_photons = int(cube.sum())
+        return cube.astype(np.uint32)
+
+    def pixel_stack(self, channel=None, binning=1):
+        return self.raw_pixel_stack(channel=channel, binning=binning).astype(float)
+
+    def intensity_image(self, channel=None, binning=1):
+        return self.raw_pixel_stack(channel=channel, binning=binning).sum(axis=2)
+
+def _metadata(ptu, data):
+    return {
+        'frequency': ptu.sync_rate,
+        'tcspc_resolution': ptu.tcspc_res,
+        'shape': data.shape,
+        'dims': ('Y', 'X', 'H'),
+        'tags': ptu.tags,
+        'x_pixel_size': ptu.tags.get('ImgHdr_PixResol', ptu.tags.get('ImgHdr_PixRes', 0)),
+        'y_pixel_size': ptu.tags.get('ImgHdr_PixResol', ptu.tags.get('ImgHdr_PixRes', 0)),
+        'n_bins': ptu.n_bins,
+        'time_ns': ptu.time_ns,
+        'photon_channel': ptu.photon_channel,
+    }
+
+def read_ptu(path, binning=1, channel=None, verbose=False):
+    ptu = PTUFile(path, verbose=verbose)
+    data = ptu.pixel_stack(channel=channel, binning=binning)
+    metadata = _metadata(ptu, data)
+    return data, metadata
+
+def get_intensity_image(path, binning=1, channel=None):
+    data, metadata = read_ptu(path, binning=binning, channel=channel, verbose=False)
+    img = data.sum(axis=2)
+    return img, metadata
+
+def get_flim_data(path, binning=1, channel=None):
+    return read_ptu(path, binning=binning, channel=channel, verbose=False)
+
+def normalise_flim(flim):
+    if flim is None:
+        return None
+    if flim.ndim == 5:
+        return flim[0, :, :, 0, :]
+    if flim.ndim == 4:
+        if flim.shape[0] == 1:
+            return flim[0]
+        else:
+            return flim[:, :, 0, :]
+    if flim.ndim == 3:
+        return flim
+    return None
+
+def create_time_axis(n_bins, tcspc_resolution):
+    return np.arange(n_bins) * tcspc_resolution * 1e9

flimkit/formats/PTU/series.py

@@ -0,0 +1,258 @@
+import re
+import numpy as np
+from pathlib import Path
+
+TILE_ONLY_PATTERN = re.compile(r'^(?P<base>.+?)_s(?P<s>\d+)\.ptu$', re.IGNORECASE)
+
+def parse_series_name(name):
+    from ...utils.batch_fit import parse_timelapse_filename
+    name = str(name)
+    parsed = parse_timelapse_filename(name)
+    if parsed is not None:
+        region, t, s, z = parsed
+        return {
+            'file': name,
+            'base': region,
+            't': t,
+            's': s or 1,
+            'z': z or 1,
+            'has_t': True,
+            'has_z': z > 0,
+        }
+    m = TILE_ONLY_PATTERN.match(name)
+    if m is None:
+        return None
+    return {
+        'file': name,
+        'base': m.group('base'),
+        't': 1,
+        's': int(m.group('s')),
+        'z': 1,
+        'has_t': False,
+        'has_z': False,
+    }
+
+def index_ptu_series(ptu_dir, ptu_basename=None):
+    ptu_dir = Path(ptu_dir)
+    entries = []
+    for path in sorted(ptu_dir.glob('*.ptu')):
+        parsed = parse_series_name(path.name)
+        if parsed is None:
+            continue
+        if ptu_basename is not None and parsed['base'] != ptu_basename:
+            continue
+        entries.append(parsed)
+    if not entries:
+        raise RuntimeError(
+            f'No PTU files matching <base>_s<N>[_z<N>] found in {ptu_dir}'
+            + (f' for basename {ptu_basename!r}' if ptu_basename else ''))
+    bases = sorted({e['base'] for e in entries})
+    if len(bases) > 1:
+        raise RuntimeError(
+            f'Multiple series in {ptu_dir}: {bases}. Pass ptu_basename to pick one.')
+    planes = {}
+    for e in entries:
+        planes.setdefault((e['t'], e['z']), []).append(e)
+    for key in planes:
+        planes[key].sort(key=lambda e: e['s'])
+    tile_counts = {len(v) for v in planes.values()}
+    tiles = sorted({e['s'] for e in entries})
+    if len(tiles) < 2:
+        raise RuntimeError(
+            f'{bases[0]!r} has a single position, so there is nothing to stitch. '
+            'Use the timelapse or z-stack batch fit for single-position stacks.')
+    return {
+        'base': bases[0],
+        'planes': planes,
+        'timepoints': sorted({t for t, _ in planes}),
+        'z_planes': sorted({z for _, z in planes}),
+        'tiles': tiles,
+        'n_files': len(entries),
+        'is_ragged': len(tile_counts) > 1,
+        'has_t': any(e['has_t'] for e in entries),
+        'has_z': any(e['has_z'] for e in entries),
+    }
+
+def describe_series(index):
+    n_t = len(index['timepoints'])
+    n_z = len(index['z_planes'])
+    n_s = len(index['tiles'])
+    return (f"{index['base']!r}: {n_t} timepoint(s) x {n_s} tile(s) x {n_z} z-plane(s) "
+            f"= {index['n_files']} files")
+
+def _overlap_score(a, b, dy, dx, min_px):
+    h, w = a.shape
+    if abs(dy) >= h or abs(dx) >= w:
+        return None
+    pa = a[max(0, dy):min(h, h + dy), max(0, dx):min(w, w + dx)]
+    pb = b[max(0, -dy):min(h, h - dy), max(0, -dx):min(w, w - dx)]
+    if pa.size < min_px:
+        return None
+    pa = pa - pa.mean()
+    pb = pb - pb.mean()
+    den = np.sqrt(float((pa * pa).sum()) * float((pb * pb).sum()))
+    if den <= 0:
+        return None
+    return float((pa * pb).sum() / den), pa.size
+
+def register_tile_pair(image_a, image_b, coarse_step=4, refine_radius=8,
+                       min_overlap_frac=0.05, n_candidates=8):
+    a = np.log1p(np.asarray(image_a, dtype=float))
+    b = np.log1p(np.asarray(image_b, dtype=float))
+    if a.shape != b.shape:
+        raise ValueError(f'Tile shapes differ: {a.shape} vs {b.shape}')
+    h, w = a.shape
+    min_px = max(1, int(min_overlap_frac * a.size))
+    coarse = []
+    for dy in range(-h + 1, h, coarse_step):
+        for dx in range(-w + 1, w, coarse_step):
+            scored = _overlap_score(a, b, dy, dx, min_px)
+            if scored is None:
+                continue
+            coarse.append((scored[0], dy, dx, scored[1]))
+    if not coarse:
+        raise RuntimeError(
+            f'No candidate shift kept at least {100 * min_overlap_frac:.0f}% overlap')
+    coarse.sort(key=lambda c: (-c[0], -c[3]))
+    best = None
+    for _, cy, cx, _ in coarse[:n_candidates]:
+        for dy in range(cy - refine_radius, cy + refine_radius + 1):
+            for dx in range(cx - refine_radius, cx + refine_radius + 1):
+                scored = _overlap_score(a, b, dy, dx, min_px)
+                if scored is None:
+                    continue
+                r, n = scored
+                if best is None or r > best[0] + 1e-9 or (
+                        abs(r - best[0]) <= 1e-9 and n > best[3]):
+                    best = (r, dy, dx, n)
+    r, dy, dx, n_px = best
+    return {
+        'dy': int(dy),
+        'dx': int(dx),
+        'correlation': float(r),
+        'overlap_px': int(n_px),
+        'overlap_frac': float(n_px) / float(a.size),
+    }
+
+def recover_tile_positions(tile_images, min_correlation=0.3):
+    if len(tile_images) < 2:
+        raise ValueError('Need at least two tiles to recover positions')
+    shifts = {0: (0, 0)}
+    pairs = []
+    for i in range(1, len(tile_images)):
+        reg = register_tile_pair(tile_images[i - 1], tile_images[i])
+        if reg['correlation'] < min_correlation:
+            raise RuntimeError(
+                f'Tile {i-1} to {i} registration too weak '
+                f"(r={reg['correlation']:.3f} < {min_correlation}); "
+                f'supply tile positions from a .lif or .xlif instead')
+        prev_y, prev_x = shifts[i - 1]
+        shifts[i] = (prev_y + reg['dy'], prev_x + reg['dx'])
+        pairs.append(reg)
+    ys = [shifts[i][0] for i in range(len(tile_images))]
+    xs = [shifts[i][1] for i in range(len(tile_images))]
+    min_y, min_x = min(ys), min(xs)
+    positions = [{'pixel_y': ys[i] - min_y, 'pixel_x': xs[i] - min_x}
+                 for i in range(len(tile_images))]
+    return positions, pairs
+
+def refine_tile_positions(tile_images, positions, radius=60,
+                          min_overlap_frac=0.05):
+    if len(tile_images) < 2:
+        return [dict(p) for p in positions], []
+    imgs = [np.log1p(np.asarray(im, dtype=float)) for im in tile_images]
+    min_px = max(1, int(min_overlap_frac * imgs[0].size))
+    out = [dict(positions[0])]
+    refinements = []
+    for i in range(1, len(imgs)):
+        prev, cur = positions[i - 1], positions[i]
+        dy0 = cur['pixel_y'] - prev['pixel_y']
+        dx0 = cur['pixel_x'] - prev['pixel_x']
+        best = None
+        for dy in range(dy0 - radius, dy0 + radius + 1):
+            for dx in range(dx0 - radius, dx0 + radius + 1):
+                scored = _overlap_score(imgs[i - 1], imgs[i], dy, dx, min_px)
+                if scored is None:
+                    continue
+                r, n = scored
+                if best is None or r > best[0]:
+                    best = (r, dy, dx, n)
+        if best is None:
+            out.append(dict(cur))
+            refinements.append(None)
+            continue
+        r, dy, dx, n = best
+        start = _overlap_score(imgs[i - 1], imgs[i], dy0, dx0, min_px)
+        out.append({**cur,
+                    'pixel_y': out[i - 1]['pixel_y'] + dy,
+                    'pixel_x': out[i - 1]['pixel_x'] + dx})
+        refinements.append({
+            'shift_y': dy - dy0,
+            'shift_x': dx - dx0,
+            'correlation': float(r),
+            'correlation_before': float(start[0]) if start else float('nan'),
+            'overlap_px': int(n),
+        })
+    min_y = min(p['pixel_y'] for p in out)
+    min_x = min(p['pixel_x'] for p in out)
+    for p in out:
+        p['pixel_y'] -= min_y
+        p['pixel_x'] -= min_x
+    return out, refinements
+
+def _tile_intensity(ptu_path, rotate_cw, binning):
+    from .reader import PTUFile
+    ptu = PTUFile(str(ptu_path), verbose=False)
+    ptu.summed_decay()
+    img = ptu.intensity_image(channel=ptu.photon_channel, binning=binning)
+    if rotate_cw:
+        img = np.rot90(img, k=-1)
+    return img
+
+def recover_series_positions(ptu_dir, index, plane=None, rotate_tiles=True,
+                             binning=1, min_correlation=0.3, verbose=True):
+    ptu_dir = Path(ptu_dir)
+    if plane is None:
+        mid_t = index['timepoints'][len(index['timepoints']) // 2]
+        mid_z = index['z_planes'][len(index['z_planes']) // 2]
+        plane = (mid_t, mid_z)
+    entries = index['planes'].get(plane)
+    if not entries:
+        raise RuntimeError(f'Plane {plane} not present in series index')
+    if verbose:
+        print(f'Recovering tile positions from t={plane[0]} z={plane[1]} '
+              f'({len(entries)} tiles)...')
+    images = [_tile_intensity(ptu_dir / e['file'], rotate_tiles, binning)
+              for e in entries]
+    positions, pairs = recover_tile_positions(images, min_correlation=min_correlation)
+    tile_positions = []
+    for e, pos in zip(entries, positions):
+        tile_positions.append({
+            'file': e['file'],
+            's': e['s'],
+            'scan_index': e['s'] - 1,
+            'field_x': 0,
+            'field_y': e['s'] - 1,
+            'pos_x': 0.0,
+            'pos_y': 0.0,
+            'pixel_x': pos['pixel_x'],
+            'pixel_y': pos['pixel_y'],
+        })
+    if verbose:
+        for i, reg in enumerate(pairs):
+            print(f"  s{entries[i]['s']} to s{entries[i+1]['s']}: "
+                  f"dy={reg['dy']} dx={reg['dx']} r={reg['correlation']:.3f} "
+                  f"overlap={100 * reg['overlap_frac']:.1f}%")
+    return tile_positions, pairs
+
+def plane_tile_positions(reference_positions, entries):
+    by_tile = {p['s']: p for p in reference_positions}
+    out = []
+    for e in sorted(entries, key=lambda x: x['s']):
+        ref = by_tile.get(e['s'])
+        if ref is None:
+            raise RuntimeError(
+                f"Tile s{e['s']} has no recovered position; the reference plane "
+                f'was missing that tile')
+        out.append({**ref, 'file': e['file']})
+    return out