phasorpy 0.1__cp313-cp313-win_amd64.whl → 0.3__cp313-cp313-win_amd64.whl

phasorpy/io.py

@@ -16,6 +16,7 @@ The ``phasorpy.io`` module provides functions to:
 - read time-resolved and hyperspectral image data and metadata (as relevant
   to phasor analysis) from many file formats used in bio-imaging:
 
+  - :py:func:`read_imspector_tiff` - ImSpector FLIM TIFF
   - :py:func:`read_lsm` - Zeiss LSM
   - :py:func:`read_ifli` - ISS IFLI
   - :py:func:`read_sdt` - Becker & Hickl SDT
@@ -123,6 +124,7 @@ __all__ = [
     'read_fbd',
     'read_flif',
     'read_ifli',
+    'read_imspector_tiff',
     # 'read_lif',
     'read_lsm',
     # 'read_nd2',
@@ -290,11 +292,9 @@ def phasor_to_ometiff(
             imag = imag.reshape(1, -1)
 
     if harmonic is not None:
-        harmonic_array = numpy.atleast_1d(harmonic)
-        if harmonic_array.ndim > 1 or harmonic_array.size != nharmonic:
+        harmonic, _ = parse_harmonic(harmonic)
+        if len(harmonic) != nharmonic:
             raise ValueError('invalid harmonic')
-        samples = int(harmonic_array.max()) * 2 + 1
-        harmonic, _ = parse_harmonic(harmonic, samples)
 
     if frequency is not None:
         frequency_array = numpy.atleast_2d(frequency).astype(numpy.float64)
@@ -488,7 +488,7 @@ def phasor_from_ometiff(
 
         has_harmonic_dim = tif.series[1].ndim > tif.series[0].ndim
         nharmonics = tif.series[1].shape[0] if has_harmonic_dim else 1
-        maxharmonic = nharmonics
+        harmonic_max = nharmonics
         for i in (3, 4):
             if len(tif.series) < i + 1:
                 break
@@ -499,10 +499,10 @@ def phasor_from_ometiff(
             elif series.name == 'Phasor harmonic':
                 if not has_harmonic_dim and data.size == 1:
                     attrs['harmonic'] = int(data.item(0))
-                    maxharmonic = attrs['harmonic']
+                    harmonic_max = attrs['harmonic']
                 elif has_harmonic_dim and data.size == nharmonics:
                     attrs['harmonic'] = data.tolist()
-                    maxharmonic = max(attrs['harmonic'])
+                    harmonic_max = max(attrs['harmonic'])
                 else:
                     logger.warning(
                         f'harmonic={data} does not match phasor '
@@ -535,7 +535,7 @@ def phasor_from_ometiff(
             imag = tif.series[2].asarray()
         else:
             # specified harmonics
-            harmonic, keepdims = parse_harmonic(harmonic, 2 * maxharmonic + 1)
+            harmonic, keepdims = parse_harmonic(harmonic, harmonic_max)
             try:
                 if isinstance(harmonic_stored, list):
                     index = [harmonic_stored.index(h) for h in harmonic]
@@ -769,7 +769,7 @@ def phasor_from_simfcs_referenced(
     else:
         raise ValueError(f'file extension must be .ref or .r64, not {ext!r}')
 
-    harmonic, keep_harmonic_dim = parse_harmonic(harmonic, data.shape[0])
+    harmonic, keep_harmonic_dim = parse_harmonic(harmonic, data.shape[0] // 2)
 
     mean = data[0].copy()
     real = numpy.empty((len(harmonic),) + mean.shape, numpy.float32)
@@ -889,6 +889,146 @@ def read_lsm(
     return DataArray(data, **metadata)
 
 
+def read_imspector_tiff(
+    filename: str | PathLike[Any],
+    /,
+) -> DataArray:
+    """Return FLIM image stack and metadata from ImSpector TIFF file.
+
+    Parameters
+    ----------
+    filename : str or Path
+        Name of ImSpector FLIM TIFF file to read.
+
+    Returns
+    -------
+    xarray.DataArray
+        TCSPC image stack.
+        Usually, a 3-to-5-dimensional array of type ``uint16``.
+
+        - ``coords['H']``: times of histogram bins.
+        - ``attrs['frequency']``: repetition frequency in MHz.
+
+    Raises
+    ------
+    tifffile.TiffFileError
+        File is not a TIFF file.
+    ValueError
+        File is not an ImSpector FLIM TIFF file.
+
+    Examples
+    --------
+    >>> data = read_imspector_tiff(fetch('Embryo.tif'))
+    >>> data.values
+    array(...)
+    >>> data.dtype
+    dtype('uint16')
+    >>> data.shape
+    (56, 512, 512)
+    >>> data.dims
+    ('H', 'Y', 'X')
+    >>> data.coords['H'].data  # dtime bins
+    array(...)
+    >>> data.attrs['frequency']  # doctest: +NUMBER
+    80.109
+
+    """
+    from xml.etree import ElementTree
+
+    import tifffile
+
+    with tifffile.TiffFile(filename) as tif:
+        tags = tif.pages.first.tags
+        omexml = tags.valueof(270, '')
+        make = tags.valueof(271, '')
+
+        if (
+            make != 'ImSpector'
+            or not omexml.startswith('<?xml version')
+            or len(tif.series) != 1
+            or not tif.is_ome
+        ):
+            raise ValueError(f'{tif.filename} is not an ImSpector TIFF file')
+
+        series = tif.series[0]
+        ndim = series.ndim
+        axes = series.axes
+        shape = series.shape
+
+        if ndim < 3 or not axes.endswith('YX'):
+            raise ValueError(
+                f'{tif.filename} is not an ImSpector FLIM TIFF file'
+            )
+
+        data = series.asarray()
+
+    attrs: dict[str, Any] = {}
+    coords = {}
+    physical_size = {}
+
+    root = ElementTree.fromstring(omexml)
+    ns = {
+        '': 'http://www.openmicroscopy.org/Schemas/OME/2008-02',
+        'ca': 'http://www.openmicroscopy.org/Schemas/CA/2008-02',
+    }
+
+    description = root.find('.//Description', ns)
+    if (
+        description is not None
+        and description.text
+        and description.text != 'not_specified'
+    ):
+        attrs['description'] = description.text
+
+    pixels = root.find('.//Image/Pixels', ns)
+    assert pixels is not None
+    for ax in 'TZYX':
+        attrib = 'TimeIncrement' if ax == 'T' else f'PhysicalSize{ax}'
+        if ax not in axes or attrib not in pixels.attrib:
+            continue
+        size = float(pixels.attrib[attrib])
+        physical_size[ax] = size
+        coords[ax] = numpy.linspace(
+            0.0,
+            size,
+            shape[axes.index(ax)],
+            endpoint=False,
+            dtype=numpy.float64,
+        )
+
+    axes_labels = root.find('.//ca:CustomAttributes/AxesLabels', ns)
+    if (
+        axes_labels is None
+        or 'X' not in axes_labels.attrib
+        or 'TCSPC' not in axes_labels.attrib['X']
+        or 'FirstAxis' not in axes_labels.attrib
+        or 'SecondAxis' not in axes_labels.attrib
+    ):
+        raise ValueError(f'{tif.filename} is not an ImSpector FLIM TIFF file')
+
+    if axes_labels.attrib['FirstAxis'].endswith('TCSPC T'):
+        ax = axes[-3]
+        assert axes_labels.attrib['FirstAxis-Unit'] == 'ns'
+    elif axes_labels.attrib['SecondAxis'].endswith('TCSPC T') and ndim > 3:
+        ax = axes[-4]
+        assert axes_labels.attrib['SecondAxis-Unit'] == 'ns'
+    else:
+        raise ValueError(f'{tif.filename} is not an ImSpector FLIM TIFF file')
+    axes = axes.replace(ax, 'H')
+    coords['H'] = coords[ax]
+    del coords[ax]
+
+    attrs['frequency'] = float(
+        1000.0 / (shape[axes.index('H')] * physical_size[ax])
+    )
+
+    metadata = _metadata(axes, shape, filename, attrs=attrs, **coords)
+
+    from xarray import DataArray
+
+    return DataArray(data, **metadata)
+
+
 def read_ifli(
     filename: str | PathLike[Any],
     /,
@@ -944,8 +1084,8 @@ def read_ifli(
     (256, 256, 4, 3)
     >>> data.dims
     ('Y', 'X', 'F', 'S')
-    >>> data.coords['F'].data
-    array([8.033...])
+    >>> data.coords['F'].data  # doctest: +NUMBER
+    array([8.033e+07, 1.607e+08, 2.41e+08, 4.017e+08])
     >>> data.coords['S'].data
     array(['mean', 'real', 'imag'], dtype='<U4')
     >>> data.attrs
@@ -1037,8 +1177,8 @@ def read_sdt(
     ('Y', 'X', 'H')
     >>> data.coords['H'].data
     array(...)
-    >>> data.attrs['frequency']
-    79...
+    >>> data.attrs['frequency']  # doctest: +NUMBER
+    79.99
 
     """
     import sdtfile
@@ -1150,7 +1290,7 @@ def read_ptu(
     ('T', 'Y', 'X', 'C', 'H')
     >>> data.coords['H'].data
     array(...)
-    >>> data.attrs['frequency']
+    >>> data.attrs['frequency']  # doctest: +NUMBER
     78.02
 
     """
@@ -1223,8 +1363,8 @@ def read_flif(
     ('H', 'Y', 'X')
     >>> data.coords['H'].data
     array(...)
-    >>> data.attrs['frequency']
-    80.65...
+    >>> data.attrs['frequency']  # doctest: +NUMBER
+    80.65
 
     """
     import lfdfiles