flimkit 0.12.0__py3-none-any.whl

flimkit/formats/ISS/reader.py

@@ -0,0 +1,223 @@
+import struct
+import numpy as np
+from pathlib import Path
+
+_FRAME_CH = 5
+_LINE_CH = 6
+_PIXEL_CH = 7
+_CLOCK_CH = 8
+
+_TAG_EXTS = {
+    'time': '.TAGTIME',
+    'channel': '.TAGCHANNEL',
+    'decay': '.TAGDECAY',
+}
+
+def _find_with_ext(stem, ext):
+    direct = Path(str(stem) + ext)
+    if direct.exists():
+        return direct
+    parent = stem.parent if str(stem.parent) else Path('.')
+    target = (stem.name + ext).lower()
+    if parent.exists():
+        for f in parent.iterdir():
+            if f.name.lower() == target:
+                return f
+    return None
+
+def _resolve_triplet(path):
+    p = Path(path)
+    stem = p.with_suffix('') if p.suffix.upper() in (e.upper() for e in _TAG_EXTS.values()) else p
+    out = {}
+    for key, ext in _TAG_EXTS.items():
+        cand = _find_with_ext(stem, ext)
+        if cand is None:
+            raise FileNotFoundError(f"Missing ISS TD-FLIM file '{stem.name}{ext}' next to {p}")
+        out[key] = cand
+    return out
+
+def _read_tag_file(path, byteorder, value_bytes):
+    dtype = np.dtype(f'{byteorder}i{value_bytes}')
+    with open(path, 'rb') as fh:
+        period = struct.unpack(f'{byteorder}i', fh.read(4))[0]
+        data = np.frombuffer(fh.read(), dtype=dtype)
+    return period, data
+
+class ISSFile:
+    def __init__(self, path, verbose=True, byteorder='<', n_bins=None):
+        self.path = str(path)
+        self.verbose = verbose
+        self.byteorder = byteorder
+        self.paths = _resolve_triplet(path)
+        self._total_photons = None
+        self._load()
+        self._parse_meta(n_bins=n_bins)
+    def _load(self):
+        p_t, self.arrival_ps = _read_tag_file(self.paths['time'], self.byteorder, 8)
+        p_c, self.channel = _read_tag_file(self.paths['channel'], self.byteorder, 4)
+        p_d, self.decay = _read_tag_file(self.paths['decay'], self.byteorder, 4)
+        periods = [p for p in (p_t, p_c, p_d) if p > 0]
+        self.period_ps = periods[0] if periods else 0
+        if len(set(periods)) > 1 and self.verbose:
+            print(f'  WARNING: excitation period differs across files: {p_t}, {p_c}, {p_d} ps')
+        n = min(self.arrival_ps.shape[0], self.channel.shape[0], self.decay.shape[0])
+        if not (self.arrival_ps.shape[0] == self.channel.shape[0] == self.decay.shape[0]):
+            if self.verbose:
+                print(f'  WARNING: event counts differ '
+                      f'(time={self.arrival_ps.shape[0]}, channel={self.channel.shape[0]}, '
+                      f'decay={self.decay.shape[0]}); truncating to {n}')
+            self.arrival_ps = self.arrival_ps[:n]
+            self.channel = self.channel[:n]
+            self.decay = self.decay[:n]
+    def _parse_meta(self, n_bins=None):
+        ach = np.abs(self.channel)
+        is_det = (ach >= 1) & (ach <= 4)
+        if n_bins is not None:
+            self.n_bins = int(n_bins)
+        else:
+            dec_ph = self.decay[is_det]
+            self.n_bins = int(dec_ph.max()) + 1 if dec_ph.size else 0
+        period_s = self.period_ps * 1e-12
+        self.frequency = (1.0 / period_s) if period_s > 0 else 0.0
+        self.period_ns = period_s * 1e9
+        self.tcspc_res = (period_s / self.n_bins) if self.n_bins > 0 else 0.0
+        self.time_ns = (np.arange(self.n_bins) + 0.5) * self.tcspc_res * 1e9
+        det = ach[is_det]
+        self.photon_channel = int(np.bincount(det, minlength=5)[1:5].argmax() + 1) if det.size else None
+        self.detector_channels = [int(c) for c in np.unique(det)] if det.size else []
+        self.sync_rate = self.frequency
+        self.n_records = int(self.channel.shape[0])
+        self.rec_type = None
+        is_frame = ach == _FRAME_CH
+        is_line = ach == _LINE_CH
+        is_pixel = ach == _PIXEL_CH
+        self.n_y = int(self._counts_since(is_frame, is_line).max()) if is_line.any() else 0
+        self.n_x = int(self._counts_since(is_line, is_pixel).max()) if is_pixel.any() else 0
+        self.tags = {
+            'ISS_ExcitationPeriod_ps': int(self.period_ps),
+            'ISS_NumEvents': int(self.channel.shape[0]),
+            'ISS_NumPhotons': int(is_det.sum()),
+            'ISS_DecayResolution': int(self.n_bins),
+            'ISS_DetectorChannels': self.detector_channels,
+            'ISS_ImageShape': (self.n_y, self.n_x),
+            'ISS_SourceFiles': {k: str(v) for k, v in self.paths.items()},
+        }
+        if self.verbose:
+            print(f"  ISS TD-FLIM : {self.paths['time'].stem}")
+            print(f'  Period   : {self.period_ns:.3f} ns  ({self.frequency/1e6:.3f} MHz)')
+            print(f'  TCSPC    : {self.n_bins} bins x {self.tcspc_res*1e12:.2f} ps')
+            print(f'  Events   : {self.channel.shape[0]:,}  (photons {int(is_det.sum()):,})')
+            print(f'  Channels : {self.detector_channels}')
+            print(' ')
+    def _counts_since(self, reset_mask, count_mask):
+        # counter that resets to 0 at every reset_mask event
+        n = reset_mask.shape[0]
+        cum = np.cumsum(count_mask.astype(np.int64))
+        reset_pos = np.where(reset_mask, np.arange(n), -1)
+        last = np.maximum.accumulate(reset_pos)
+        base = np.zeros(n, dtype=np.int64)
+        seen = last >= 0
+        base[seen] = cum[last[seen]]
+        return cum - base
+    def summed_decay(self, channel=None):
+        ach = np.abs(self.channel)
+        is_det = (ach >= 1) & (ach <= 4)
+        if channel is None:
+            channel = self.photon_channel
+        else:
+            channel = int(channel)
+        if channel is None:
+            return np.zeros(self.n_bins, dtype=float)
+        ph = is_det & (ach == channel)
+        dec = self.decay[ph]
+        dec = dec[(dec >= 0) & (dec < self.n_bins)].astype(np.int64)
+        decay = np.bincount(dec, minlength=self.n_bins).astype(float)
+        self._total_photons = int(decay.sum())
+        return decay[:self.n_bins]
+    n_sync = None
+
+    @property
+    def photons_per_pulse(self):
+        return None
+    def pixel_stack(self, channel=None, binning=1, n_x=None, n_y=None):
+        ach = np.abs(self.channel)
+        is_frame = ach == _FRAME_CH
+        is_line = ach == _LINE_CH
+        is_pixel = ach == _PIXEL_CH
+        is_det = (ach >= 1) & (ach <= 4)
+        if not is_line.any():
+            raise RuntimeError('No line markers (ch6) found; cannot build an image cube.')
+        # y/x are 0-based: line/pixel markers seen since the parent reset, minus one
+        y = self._counts_since(is_frame, is_line) - 1
+        x = self._counts_since(is_line, is_pixel) - 1
+        if channel is not None:
+            ph = is_det & (ach == int(channel))
+        else:
+            ph = is_det
+        dec = self.decay
+        valid = ph & (y >= 0) & (x >= 0) & (dec >= 0) & (dec < self.n_bins)
+        yv = y[valid].astype(np.int64)
+        xv = x[valid].astype(np.int64)
+        dv = dec[valid].astype(np.int64)
+        ny = int(n_y) if n_y is not None else (self.n_y or (int(yv.max()) + 1 if yv.size else 0))
+        nx = int(n_x) if n_x is not None else (self.n_x or (int(xv.max()) + 1 if xv.size else 0))
+        keep = (yv < ny) & (xv < nx)
+        yv, xv, dv = yv[keep], xv[keep], dv[keep]
+        if binning > 1:
+            yv = yv // binning
+            xv = xv // binning
+            ny = (ny + binning - 1) // binning
+            nx = (nx + binning - 1) // binning
+        if ny == 0 or nx == 0 or self.n_bins == 0:
+            return np.zeros((ny, nx, self.n_bins), dtype=np.uint32)
+        flat = (yv * nx + xv) * self.n_bins + dv
+        cube = np.bincount(flat, minlength=ny * nx * self.n_bins)
+        cube = cube.reshape(ny, nx, self.n_bins).astype(np.uint32)
+        self._total_photons = int(cube.sum())
+        if self.verbose:
+            print(f'  Built cube {cube.shape}  ({self._total_photons:,} photons)')
+        return cube
+    def raw_pixel_stack(self, channel=None, binning=1):
+        return self.pixel_stack(channel=channel, binning=binning)
+
+def read_iss(path, binning=1, channel=None, verbose=False):
+    iss = ISSFile(path, verbose=verbose)
+    data = iss.pixel_stack(channel=channel, binning=binning)
+    metadata = {
+        'frequency': iss.frequency,
+        'tcspc_resolution': iss.tcspc_res,
+        'shape': data.shape,
+        'dims': ('Y', 'X', 'H'),
+        'tags': iss.tags,
+        'x_pixel_size': 0,
+        'y_pixel_size': 0,
+        'n_bins': iss.n_bins,
+        'time_ns': iss.time_ns,
+        'photon_channel': iss.photon_channel,
+    }
+    return data, metadata
+
+def get_intensity_image(path, binning=1, channel=None):
+    data, metadata = read_iss(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_iss(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/PS/reader.py

@@ -0,0 +1,202 @@
+import numpy as np
+from pathlib import Path
+from photonsfile import read_header, read_attributes, has_dual_tdc, read_photons
+
+class PSFile:
+    def __init__(self, path, verbose=True, channel=None, pixels=512,
+                 n_bins=256, period_ns=None):
+        self.path = str(path)
+        self.verbose = verbose
+        self.header = read_header(self.path)
+        self.attrs = read_attributes(self.path)
+        self._names = [d['name'] for d in self.header['datasets']]
+        self.dual_tdc = has_dual_tdc(self.path)
+        self.pos_range = 1 << int(self.attrs.get('/photons/PositionBits', 12))
+        self.tac_range = 1 << int(self.attrs.get('/photons/TacBits', 12))
+        self.pixels = int(pixels)
+        self.n_bins = int(n_bins)
+        self.n_x = self.pixels
+        self.n_y = self.pixels
+        self._period_ns = period_ns
+        self._streams = None
+        self._total_photons = None
+        self.n_records = 0
+        self.n_channels = 1
+        self.photon_channel = 1
+        self.detector_channels = [1]
+        self._parse_meta(period_ns)
+
+    def _parse_meta(self, period_ns, announce=True):
+        # TacChannel = picoseconds per raw dt unit; dual-TDC dt is already in ps
+        tac_channel = self.attrs.get('/photons/TacChannel')
+        if period_ns and float(period_ns) > 0:
+            period_s = float(period_ns) * 1e-9
+            self.calib_source = 'user'
+        elif self.dual_tdc:
+            period_s = self.tac_range * 1e-12
+            self.calib_source = 'dual_tdc'
+        elif tac_channel:
+            period_s = self.tac_range * float(tac_channel) * 1e-12
+            self.calib_source = 'TacChannel'
+        else:
+            period_s = 0.0
+            self.calib_source = 'unknown'
+        if period_s > 0:
+            self.frequency = 1.0 / period_s
+            self.period_ns = period_s * 1e9
+            self.tcspc_res = period_s / self.n_bins
+        else:
+            self.frequency = 0.0
+            self.period_ns = 0.0
+            self.tcspc_res = 0.0
+        self.sync_rate = self.frequency
+        self.time_ns = (np.arange(self.n_bins) + 0.5) * self.tcspc_res * 1e9
+        self.dt_unit = 'ps' if self.dual_tdc else 'tac_bin'
+        self.tags = {
+            'PS_Magic': self.header['magic'],
+            'PS_Version': self.header['version'],
+            'PS_Datasets': self._names,
+            'PS_PositionRange': self.pos_range,
+            'PS_TacRange': self.tac_range,
+            'PS_TacBias': self.attrs.get('/photons/TacBias'),
+            'PS_TacChannel': self.attrs.get('/photons/TacChannel'),
+            'PS_TimerFrequency': self.attrs.get('/photons/TimerFrequency'),
+            'PS_DetectorGuid': self.attrs.get('/photons/DetectorGuid'),
+            'PS_Created': self.attrs.get('Created'),
+            'PS_Pixels': self.pixels,
+            'PS_DecayResolution': self.n_bins,
+            'PS_CalibrationSource': self.calib_source,
+            'PS_DetectorChannels': self.detector_channels,
+            'PS_SourceFile': self.path,
+        }
+        if self.verbose and announce:
+            print(f'  Photonscore : {Path(self.path).name}')
+            print(f'  Container   : {self.header["magic"]} v{self.header["version"]}')
+            print(f'  Image       : {self.pixels} x {self.pixels} px  '
+                  f'(from {self.pos_range} raw positions)')
+            print(f'  TCSPC       : {self.n_bins} bins over {self.tac_range} dt units  '
+                  f'({self.tcspc_res*1e12:.2f} ps/bin, {self.calib_source})')
+            if self.dual_tdc:
+                print('  Timing      : dual-TDC, dt = stop - start in ps '
+                      '(range set from data)')
+            if self.calib_source == 'unknown':
+                print('  NOTE        : dt->time calibration unknown; '
+                      'pass period_ns=<laser period ns> for a real time axis')
+            print(' ')
+
+    n_sync = None
+
+    @property
+    def photons_per_pulse(self):
+        return None
+
+    def _ensure_streams(self):
+        if self._streams is None:
+            self._streams = read_photons(self.path)
+            if self.dual_tdc and 'dt' in self._streams:
+                dt = np.asarray(self._streams['dt'])
+                dt = dt[dt >= 0]
+                if dt.size:
+                    self.tac_range = int(dt.max()) + 1
+                    self._parse_meta(self._period_ns, announce=False)
+        return self._streams
+
+    def _bin_positions(self, binning):
+        s = self._ensure_streams()
+        x = np.asarray(s['x']).astype(np.int64)
+        y = np.asarray(s['y']).astype(np.int64)
+        dt = np.asarray(s['dt']).astype(np.int64)
+        n = min(x.shape[0], y.shape[0], dt.shape[0])
+        x, y, dt = x[:n], y[:n], dt[:n]
+        valid = ((x >= 0) & (x < self.pos_range) & (y >= 0) & (y < self.pos_range)
+                 & (dt >= 0) & (dt < self.tac_range))
+        x, y, dt = x[valid], y[valid], dt[valid]
+        p = self.pixels
+        xi = (x * p) // self.pos_range
+        yi = (y * p) // self.pos_range
+        di = (dt * self.n_bins) // self.tac_range
+        if binning > 1:
+            xi = xi // binning
+            yi = yi // binning
+            p = (p + binning - 1) // binning
+        return xi, yi, di, p
+
+    def pixel_stack(self, channel=None, binning=1):
+        xi, yi, di, p = self._bin_positions(binning)
+        b = self.n_bins
+        if p == 0 or b == 0:
+            return np.zeros((p, p, b), dtype=np.uint32)
+        flat = (yi * p + xi) * b + di
+        cube = np.bincount(flat, minlength=p * p * b).reshape(p, p, b).astype(np.uint32)
+        self.n_y, self.n_x = cube.shape[0], cube.shape[1]
+        self._total_photons = int(cube.sum())
+        self.n_records = self._total_photons
+        if self.verbose:
+            print(f'  Built cube {cube.shape}  ({self._total_photons:,} photons)')
+        return cube
+
+    def raw_pixel_stack(self, channel=None, binning=1):
+        return self.pixel_stack(channel=channel, binning=binning)
+
+    def summed_decay(self, channel=None):
+        s = self._ensure_streams()
+        dt = np.asarray(s['dt']).astype(np.int64)
+        dt = dt[(dt >= 0) & (dt < self.tac_range)]
+        di = (dt * self.n_bins) // self.tac_range
+        decay = np.bincount(di, minlength=self.n_bins).astype(float)
+        self._total_photons = int(decay.sum())
+        return decay[:self.n_bins]
+
+    def intensity_image(self, channel=None, binning=1):
+        xi, yi, _, p = self._bin_positions(binning)
+        if p == 0:
+            return np.zeros((0, 0), dtype=np.uint64)
+        flat = yi * p + xi
+        img = np.bincount(flat, minlength=p * p).reshape(p, p).astype(np.uint64)
+        return img
+
+def _metadata(ps, data):
+    return {
+        'frequency': ps.frequency,
+        'tcspc_resolution': ps.tcspc_res,
+        'shape': data.shape,
+        'dims': ('Y', 'X', 'H'),
+        'tags': ps.tags,
+        'x_pixel_size': 0,
+        'y_pixel_size': 0,
+        'n_bins': ps.n_bins,
+        'time_ns': ps.time_ns,
+        'photon_channel': ps.photon_channel,
+    }
+
+def read_ps(path, binning=1, channel=None, verbose=False, pixels=512,
+            n_bins=256, period_ns=None):
+    ps = PSFile(path, verbose=verbose, pixels=pixels, n_bins=n_bins, period_ns=period_ns)
+    data = ps.pixel_stack(channel=channel, binning=binning)
+    metadata = _metadata(ps, data)
+    return data, metadata
+
+def get_flim_data(path, binning=1, channel=None, pixels=512, n_bins=256, period_ns=None):
+    return read_ps(path, binning=binning, channel=channel, verbose=False,
+                   pixels=pixels, n_bins=n_bins, period_ns=period_ns)
+
+def get_intensity_image(path, binning=1, channel=None, pixels=512, n_bins=256):
+    ps = PSFile(path, verbose=False, pixels=pixels, n_bins=n_bins)
+    img = ps.intensity_image(channel=channel, binning=binning)
+    metadata = _metadata(ps, np.empty(0))
+    metadata['shape'] = (ps.n_y, ps.n_x, ps.n_bins)
+    return img, metadata
+
+def normalise_flim(flim):
+    if flim is None:
+        return None
+    if flim.ndim == 5:
+        return flim[0, :, :, 0, :]
+    if flim.ndim == 4:
+        return flim[0] if flim.shape[0] == 1 else 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/decode.py

@@ -0,0 +1,27 @@
+import numpy as np
+from .reader import PTUFile, normalise_flim
+
+def create_time_axis(n_bins, tcspc_resolution):
+    return np.arange(n_bins) * tcspc_resolution * 1e9
+
+def get_flim_histogram_from_ptufile(
+    ptu_path,
+    rotate_cw=True,
+    binning=1,
+    channel=None
+):
+    ptu = PTUFile(str(ptu_path), verbose=False)
+    stack = ptu.raw_pixel_stack(channel=channel, binning=binning)
+    if stack.sum() == 0:
+        raise ValueError('PTU decoded to zero photons')
+    if rotate_cw:
+        stack = np.rot90(stack, k=-1, axes=(0, 1))
+    metadata = {
+        'tcspc_resolution': ptu.tcspc_res,
+        'n_time_bins': ptu.n_bins,
+        'tile_shape': (ptu.n_y // binning, ptu.n_x // binning),
+        'frequency': ptu.sync_rate,
+        'binning': binning,
+        'channel': channel,
+    }
+    return stack, metadata

flimkit/formats/PTU/phu.py

@@ -0,0 +1,85 @@
+import numpy as np
+from pathlib import Path
+
+def _load_ptufile():
+    try:
+        import ptufile
+    except ImportError:
+        raise ImportError('ptufile is required to read PicoQuant .phu files '
+                          '(pip install ptufile)')
+    return ptufile
+
+class PHUFile:
+    modality = 'time'
+
+    def __init__(self, path, verbose=True, channel=None, **kwargs):
+        self.path = str(path)
+        self.verbose = verbose
+        self.channel = channel
+        ptufile = _load_ptufile()
+        with ptufile.PhuFile(self.path) as f:
+            self._hist = [np.asarray(h, dtype=np.uint32) for h in f.histograms()]
+            self.tcspc_res = float(f.tcspc_resolution)
+            self._resolutions = [float(r) for r in f.histogram_resolutions]
+            self.tags = dict(f.tags)
+        self.n_channels = len(self._hist)
+        self.n_bins = int(max((h.size for h in self._hist), default=0))
+        self.n_x = 0
+        self.n_y = 0
+        self.is_image = False
+        self.time_ns = (np.arange(self.n_bins) + 0.5) * self.tcspc_res * 1e9
+        self.sync_rate = 0.0
+        self.period_ns = 0.0
+        self.photon_channel = None
+        self._total_photons = None
+        if self.verbose:
+            print(f'  PicoQuant PHU : {Path(self.path).name}')
+            print(f'  TCSPC    : {self.n_bins} bins x {self.tcspc_res*1e12:.2f} ps')
+            print(f'  Point    : no image (histogram mode), {self.n_channels} histogram(s)')
+            print(' ')
+
+    def _ch_index(self, channel):
+        if channel is None:
+            totals = [int(h.sum()) for h in self._hist]
+            idx = int(np.argmax(totals)) if totals else 0
+            self.photon_channel = idx + 1
+            return idx
+        c = int(channel)
+        idx = c - 1 if c >= 1 else c
+        return idx if 0 <= idx < self.n_channels else 0
+
+    def summed_decay(self, channel=None):
+        if not self._hist:
+            return np.zeros(self.n_bins, dtype=float)
+        idx = self._ch_index(self.channel if channel is None else channel)
+        decay = np.zeros(self.n_bins, dtype=float)
+        h = self._hist[idx]
+        decay[:h.size] = h
+        self._total_photons = int(decay.sum())
+        return decay
+
+    def pixel_stack(self, *args, **kwargs):
+        raise RuntimeError('PicoQuant .phu is histogram mode and has no scan image; '
+                           'use summed_decay')
+
+    def raw_pixel_stack(self, *args, **kwargs):
+        return self.pixel_stack()
+
+    @property
+    def photons_per_pulse(self):
+        return None
+
+def read_phu(path, channel=None, verbose=False):
+    phu = PHUFile(path, verbose=verbose)
+    decay = phu.summed_decay(channel=channel)
+    metadata = {
+        'frequency': phu.sync_rate,
+        'tcspc_resolution': phu.tcspc_res,
+        'shape': decay.shape,
+        'dims': ('H',),
+        'tags': phu.tags,
+        'n_bins': phu.n_bins,
+        'time_ns': phu.time_ns,
+        'photon_channel': phu.photon_channel,
+    }
+    return decay, metadata