phasorpy 0.5__cp312-cp312-win_amd64.whl → 0.7__cp312-cp312-win_amd64.whl

phasorpy/io/__init__.py

@@ -0,0 +1,138 @@
+"""Read and write time-resolved and hyperspectral image file formats.
+
+The ``phasorpy.io`` module provides functions to:
+
+- read time-resolved and hyperspectral signals, as well as metadata from
+  many file formats used in bio-imaging:
+
+  - :py:func:`signal_from_lif` - Leica LIF and XLEF
+  - :py:func:`signal_from_lsm` - Zeiss LSM
+  - :py:func:`signal_from_ptu` - PicoQuant PTU
+  - :py:func:`signal_from_pqbin` - PicoQuant BIN
+  - :py:func:`signal_from_sdt` - Becker & Hickl SDT
+  - :py:func:`signal_from_fbd` - FLIMbox FBD
+  - :py:func:`signal_from_flimlabs_json` - FLIM LABS JSON
+  - :py:func:`signal_from_imspector_tiff` - ImSpector FLIM TIFF
+  - :py:func:`signal_from_flif` - FlimFast FLIF
+  - :py:func:`signal_from_b64` - SimFCS B64
+  - :py:func:`signal_from_z64` - SimFCS Z64
+  - :py:func:`signal_from_bhz` - SimFCS BHZ
+  - :py:func:`signal_from_bh` - SimFCS B&H
+
+- read phasor coordinates, lifetime images, and metadata from
+  specialized file formats:
+
+  - :py:func:`phasor_from_ometiff` - PhasorPy OME-TIFF
+  - :py:func:`phasor_from_ifli` - ISS IFLI
+  - :py:func:`phasor_from_lif` - Leica LIF and XLEF
+  - :py:func:`phasor_from_flimlabs_json` - FLIM LABS JSON
+  - :py:func:`phasor_from_simfcs_referenced` - SimFCS REF and R64
+  - :py:func:`lifetime_from_lif` - Leica LIF and XLEF
+
+- write phasor coordinate images to OME-TIFF and SimFCS file formats:
+
+  - :py:func:`phasor_to_ometiff`
+  - :py:func:`phasor_to_simfcs_referenced`
+
+  Support for other file formats is being considered:
+
+  - OME-TIFF
+  - Zeiss CZI
+  - Nikon ND2
+  - Olympus OIB/OIF
+  - Olympus OIR
+
+The functions are implemented as minimal wrappers around specialized
+third-party file reader libraries, currently
+`tifffile <https://github.com/cgohlke/tifffile>`_,
+`ptufile <https://github.com/cgohlke/ptufile>`_,
+`liffile <https://github.com/cgohlke/liffile>`_,
+`sdtfile <https://github.com/cgohlke/sdtfile>`_, and
+`lfdfiles <https://github.com/cgohlke/lfdfiles>`_.
+For advanced or unsupported use cases, consider using these libraries directly.
+
+The signal-reading functions typically have the following signature::
+
+    signal_from_ext(
+        filename: str | PathLike,
+        /,
+        **kwargs
+    ): -> xarray.DataArray
+
+where ``ext`` indicates the file format and ``kwargs`` are optional arguments
+passed to the underlying file reader library or used to select which data is
+returned. The returned `xarray.DataArray
+<https://docs.xarray.dev/en/stable/user-guide/data-structures.html>`_
+contains an N-dimensional array with labeled coordinates, dimensions, and
+attributes:
+
+- ``data`` or ``values`` (*array_like*)
+
+  Numpy array or array-like holding the array's values.
+
+- ``dims`` (*tuple of str*)
+
+  :ref:`Axes character codes <axes>` for each dimension in ``data``.
+  For example, ``('T', 'C', 'Y', 'X')`` defines the dimension order in a
+  4-dimensional array of a time-series of multi-channel images.
+
+- ``coords`` (*dict_like[str, array_like]*)
+
+  Coordinate arrays labelling each point in the data array.
+  The keys are :ref:`axes character codes <axes>`.
+  Values are 1-dimensional arrays of numbers or strings.
+  For example, ``coords['C']`` could be an array of emission wavelengths.
+
+- ``attrs`` (*dict[str, Any]*)
+
+  Arbitrary metadata such as measurement or calibration parameters required to
+  interpret the data values.
+  For example, the laser repetition frequency of a time-resolved measurement.
+
+.. _axes:
+
+Axes character codes from the OME model and tifffile library are used as
+``dims`` items and ``coords`` keys:
+
+- ``'X'`` : width (OME)
+- ``'Y'`` : height (OME)
+- ``'Z'`` : depth (OME)
+- ``'S'`` : sample (color components or phasor coordinates)
+- ``'I'`` : sequence (of images, frames, or planes)
+- ``'T'`` : time (OME)
+- ``'C'`` : channel (OME. Acquisition path or emission wavelength)
+- ``'A'`` : angle (OME)
+- ``'P'`` : phase (OME. In LSM, ``'P'`` maps to position)
+- ``'R'`` : tile (OME. Region, position, or mosaic)
+- ``'H'`` : lifetime histogram (OME)
+- ``'E'`` : lambda (OME. Excitation wavelength)
+- ``'F'`` : frequency (ISS)
+- ``'Q'`` : other (OME. Harmonics in PhasorPy TIFF)
+- ``'L'`` : exposure (FluoView)
+- ``'V'`` : event (FluoView)
+- ``'M'`` : mosaic (LSM 6)
+- ``'J'`` : column (NDTiff)
+- ``'K'`` : row (NDTiff)
+
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []
+
+from .._utils import init_module
+from ._flimlabs import *
+from ._leica import *
+from ._ometiff import *
+from ._other import *
+from ._simfcs import *
+
+# The `init_module()` function dynamically populates the `__all__` list with
+# all public symbols imported from submodules or defined in this module.
+# Any name not starting with an underscore will be automatically exported
+# when using "from phasorpy.io import *"
+
+init_module(globals())
+del init_module
+
+# flake8: noqa: F401, F403

phasorpy/io/_flimlabs.py

@@ -0,0 +1,360 @@
+"""Read FLIM LABS file formats."""
+
+from __future__ import annotations
+
+__all__ = ['phasor_from_flimlabs_json', 'signal_from_flimlabs_json']
+
+import json
+from typing import TYPE_CHECKING
+
+from .._utils import parse_harmonic, xarray_metadata
+
+if TYPE_CHECKING:
+    from .._typing import (
+        Any,
+        DataArray,
+        DTypeLike,
+        Literal,
+        NDArray,
+        PathLike,
+        Sequence,
+    )
+
+import numpy
+
+
+def phasor_from_flimlabs_json(
+    filename: str | PathLike[Any],
+    /,
+    channel: int | None = 0,
+    harmonic: int | Sequence[int] | Literal['all'] | str | None = None,
+) -> tuple[NDArray[Any], NDArray[Any], NDArray[Any], dict[str, Any]]:
+    """Return phasor coordinates and metadata from FLIM LABS JSON phasor file.
+
+    FLIM LABS JSON files may contain calibrated phasor coordinates
+    (possibly for multiple channels and harmonics) and metadata from
+    digital frequency-domain measurements.
+
+    Parameters
+    ----------
+    filename : str or Path
+        Name of FLIM LABS JSON phasor file to read.
+        The file name usually contains the string "_phasor".
+    channel : int, optional
+        Index of channel to return.
+        By default, return the first channel.
+        If None, return all channels.
+    harmonic : int, sequence of int, or 'all', optional
+        Harmonic(s) to return from file.
+        If None (default), return the first harmonic stored in the file.
+        If `'all'`, return all harmonics as stored in file.
+        If a list, the first axes of the returned `real` and `imag` arrays
+        contain specified harmonic(s).
+        If an integer, the returned `real` and `imag` arrays are single
+        harmonic and have the same shape as `mean`.
+
+    Returns
+    -------
+    mean : ndarray
+        Average intensity image.
+        Zeroed if an intensity image is not present in file.
+    real : ndarray
+        Image of real component of phasor coordinates.
+    imag : ndarray
+        Image of imaginary component of phasor coordinates.
+    attrs : dict
+        Select metadata:
+
+        - ``'dims'`` (tuple of str):
+          :ref:`Axes codes <axes>` for `mean` image dimensions.
+        - ``'samples'`` (int):
+          Number of time bins (always 256).
+        - ``'harmonic'`` (int or list of int):
+          Harmonic(s) of `real` and `imag`.
+          Single int if one harmonic, list if multiple harmonics.
+        - ``'frequency'`` (float):
+          Laser repetition frequency in MHz.
+        - ``'flimlabs_header'`` (dict):
+          FLIM LABS file header.
+
+    Raises
+    ------
+    ValueError
+        File is not a FLIM LABS JSON file containing phasor coordinates.
+    IndexError
+        Harmonic or channel not found in file.
+
+    See Also
+    --------
+    phasorpy.io.signal_from_flimlabs_json
+
+    Examples
+    --------
+    >>> mean, real, imag, attrs = phasor_from_flimlabs_json(
+    ...     fetch('Convallaria_m2_1740751781_phasor_ch1.json'), harmonic='all'
+    ... )
+    >>> real.shape
+    (3, 256, 256)
+    >>> attrs['dims']
+    ('Y', 'X')
+    >>> attrs['harmonic']
+    [1, 2, 3]
+    >>> attrs['frequency']  # doctest: +NUMBER
+    40.00
+
+    """
+    with open(filename, 'rb') as fh:
+        try:
+            data = json.load(fh)
+        except Exception as exc:
+            raise ValueError('not a valid JSON file') from exc
+
+    if (
+        'header' not in data
+        or 'phasors_data' not in data
+        or 'laser_period_ns' not in data['header']
+        or 'file_id' not in data['header']
+        # or data['header']['file_id'] != [73, 80, 71, 49]  # 'IPG1'
+    ):
+        raise ValueError(
+            'not a FLIM LABS JSON file containing phasor coordinates'
+        )
+
+    header = data['header']
+    phasor_data = data['phasors_data']
+
+    harmonics = []
+    channels = []  # 1-based
+    for d in phasor_data:
+        h = d['harmonic']
+        if h not in harmonics:
+            harmonics.append(h)
+        c = d['channel']
+        if c not in channels:
+            channels.append(c)
+    harmonics = sorted(harmonics)
+    channels = sorted(channels)
+
+    if channel is not None:
+        if channel + 1 not in channels:
+            raise IndexError(f'{channel=}')
+        channel += 1  # 1-based index
+
+    if isinstance(harmonic, str) and harmonic == 'all':
+        harmonic = harmonics
+        keep_harmonic_axis = True
+    else:
+        harmonic, keep_harmonic_axis = parse_harmonic(harmonic, harmonics[-1])
+    if any(h not in harmonics for h in harmonic):
+        raise IndexError(f'{harmonic=} not in {harmonics!r}')
+    harmonic_index = {h: i for i, h in enumerate(harmonic)}
+
+    nharmonics = len(harmonic)
+    nchannels = len(channels) if channel is None else 1
+    height = header['image_height']
+    width = header['image_width']
+    dtype = numpy.float32
+
+    shape: tuple[int, ...] = nharmonics, nchannels, height, width
+    axes: str = 'CYX'
+    mean = numpy.zeros(shape[1:], dtype)
+    real = numpy.zeros(shape, dtype)
+    imag = numpy.zeros(shape, dtype)
+
+    for d in phasor_data:
+        h = d['harmonic']
+        if h not in harmonic_index:
+            continue
+        h = harmonic_index[h]
+        if channel is not None:
+            if d['channel'] != channel:
+                continue
+            c = 0
+        else:
+            c = channels.index(d['channel'])
+
+        real[h, c] = numpy.asarray(d['g_data'], dtype)
+        imag[h, c] = numpy.asarray(d['s_data'], dtype)
+
+    if 'intensities_data' in data:
+        from .._phasorpy import _flimlabs_mean
+
+        mean.shape = nchannels, height * width
+        _flimlabs_mean(
+            mean,
+            data['intensities_data'],
+            -1 if channel is None else channels.index(channel),
+        )
+        mean.shape = shape[1:]
+        # JSON cannot store NaN values
+        nan_mask = mean == 0
+        real[:, nan_mask] = numpy.nan
+        imag[:, nan_mask] = numpy.nan
+        del nan_mask
+
+    if nchannels == 1:
+        axes = axes[1:]
+        mean = mean[0]
+        real = real[:, 0]
+        imag = imag[:, 0]
+
+    if not keep_harmonic_axis:
+        real = real[0]
+        imag = imag[0]
+
+    attrs = {
+        'dims': tuple(axes),
+        'samples': 256,
+        'harmonic': harmonic if keep_harmonic_axis else harmonic[0],
+        'frequency': 1000.0 / header['laser_period_ns'],
+        'flimlabs_header': header,
+    }
+
+    return mean, real, imag, attrs
+
+
+def signal_from_flimlabs_json(
+    filename: str | PathLike[Any],
+    /,
+    *,
+    channel: int | None = 0,
+    dtype: DTypeLike | None = None,
+) -> DataArray:
+    """Return TCSPC histogram and metadata from FLIM LABS JSON imaging file.
+
+    FLIM LABS JSON imaging files contain encoded, multi-channel TCSPC
+    histograms and metadata from digital frequency-domain measurements.
+
+    Parameters
+    ----------
+    filename : str or Path
+        Name of FLIM LABS JSON imaging file to read.
+        The file name usually contains the string "_imaging" or "_phasor".
+    channel : int, optional
+        Index of channel to return.
+        By default, return the first channel.
+        If None, return all channels.
+    dtype : dtype_like, optional, default: uint16
+        Unsigned integer type of TCSPC histogram.
+        Increase the bit-depth for high photon counts.
+
+    Returns
+    -------
+    xarray.DataArray
+        TCSPC histogram with :ref:`axes codes <axes>` depending on
+        `channel` parameter:
+
+        - Single channel: axes ``'YXH'``
+        - Multiple channels: axes ``'CYXH'``
+
+        Type specified by ``dtype`` parameter.
+
+        - ``coords['H']``: delay-times of histogram bins in ns.
+        - ``coords['C']``: channel indices (if multiple channels).
+        - ``attrs['frequency']``: laser repetition frequency in MHz.
+        - ``attrs['flimlabs_header']``: FLIM LABS file header.
+
+    Raises
+    ------
+    ValueError
+        If file is not a valid JSON file.
+        If file is not a FLIM LABS JSON file containing TCSPC histogram.
+        If `dtype` is not an unsigned integer type.
+    IndexError
+        If `channel` is out of range.
+
+    See Also
+    --------
+    phasorpy.io.phasor_from_flimlabs_json
+
+    Examples
+    --------
+    >>> signal = signal_from_flimlabs_json(
+    ...     fetch('Convallaria_m2_1740751781_phasor_ch1.json')
+    ... )
+    >>> signal.values
+    array(...)
+    >>> signal.shape
+    (256, 256, 256)
+    >>> signal.dims
+    ('Y', 'X', 'H')
+    >>> signal.coords['H'].data
+    array(...)
+    >>> signal.attrs['frequency']  # doctest: +NUMBER
+    40.0
+
+    """
+    with open(filename, 'rb') as fh:
+        try:
+            data = json.load(fh)
+        except Exception as exc:
+            raise ValueError('not a valid JSON file') from exc
+
+    if (
+        'header' not in data
+        or 'laser_period_ns' not in data['header']
+        or 'file_id' not in data['header']
+        or ('data' not in data and 'intensities_data' not in data)
+    ):
+        raise ValueError(
+            'not a FLIM LABS JSON file containing TCSPC histogram'
+        )
+
+    if dtype is None:
+        dtype = numpy.uint16
+    else:
+        dtype = numpy.dtype(dtype)
+        if dtype.kind != 'u':
+            raise ValueError(f'{dtype=} is not an unsigned integer type')
+
+    header = data['header']
+    nchannels = len([c for c in header['channels'] if c])
+    height = header['image_height']
+    width = header['image_width']
+    frequency = 1000.0 / header['laser_period_ns']
+
+    if channel is not None:
+        if channel >= nchannels or channel < 0:
+            raise IndexError(f'{channel=} out of range[0, {nchannels=}]')
+        nchannels = 1
+
+    if 'data' in data:
+        # file_id = [73, 77, 71, 49]  # 'IMG1'
+        intensities_data = data['data']
+    else:
+        # file_id = [73, 80, 71, 49]  # 'IPG1'
+        intensities_data = data['intensities_data']
+
+    from .._phasorpy import _flimlabs_signal
+
+    signal = numpy.zeros((nchannels, height * width, 256), dtype)
+    _flimlabs_signal(
+        signal,
+        intensities_data,
+        -1 if channel is None else channel,
+    )
+
+    if channel is None and nchannels > 1:
+        signal.shape = (nchannels, height, width, 256)
+        axes = 'CYXH'
+    else:
+        signal.shape = (height, width, 256)
+        axes = 'YXH'
+
+    coords: dict[str, Any] = {}
+    coords['H'] = numpy.linspace(
+        0.0, header['laser_period_ns'], 256, endpoint=False
+    )
+    if channel is None and nchannels > 1:
+        coords['C'] = numpy.asarray(
+            [i for i, c in enumerate(header['channels']) if c]
+        )
+
+    metadata = xarray_metadata(axes, signal.shape, filename, **coords)
+    attrs = metadata['attrs']
+    attrs['frequency'] = frequency
+    attrs['flimlabs_header'] = header
+
+    from xarray import DataArray
+
+    return DataArray(signal, **metadata)