phasorpy 0.6__cp313-cp313-win_amd64.whl → 0.8__cp313-cp313-win_amd64.whl

phasorpy/io/__init__.py

@@ -8,6 +8,7 @@ The ``phasorpy.io`` module provides functions to:
   - :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
@@ -46,7 +47,8 @@ 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
+`sdtfile <https://github.com/cgohlke/sdtfile>`_,
+`fbdfile <https://github.com/cgohlke/fbdfile>`_, and
 `lfdfiles <https://github.com/cgohlke/lfdfiles>`_.
 For advanced or unsupported use cases, consider using these libraries directly.
 

phasorpy/io/_flimlabs.py

@@ -67,10 +67,13 @@ def phasor_from_flimlabs_json(
 
         - ``'dims'`` (tuple of str):
           :ref:`Axes codes <axes>` for `mean` image dimensions.
-        - ``'harmonic'`` (int):
-          Harmonic of `real` and `imag`.
+        - ``'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):
-          Fundamental frequency of time-resolved phasor coordinates in MHz.
+          Laser repetition frequency in MHz.
         - ``'flimlabs_header'`` (dict):
           FLIM LABS file header.
 
@@ -154,9 +157,9 @@ def phasor_from_flimlabs_json(
 
     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)
+    mean = numpy.zeros(shape[1:], dtype=dtype)
+    real = numpy.zeros(shape, dtype=dtype)
+    imag = numpy.zeros(shape, dtype=dtype)
 
     for d in phasor_data:
         h = d['harmonic']
@@ -170,8 +173,8 @@ def phasor_from_flimlabs_json(
         else:
             c = channels.index(d['channel'])
 
-        real[h, c] = numpy.asarray(d['g_data'], dtype)
-        imag[h, c] = numpy.asarray(d['s_data'], dtype)
+        real[h, c] = numpy.asarray(d['g_data'], dtype=dtype)
+        imag[h, c] = numpy.asarray(d['s_data'], dtype=dtype)
 
     if 'intensities_data' in data:
         from .._phasorpy import _flimlabs_mean
@@ -231,27 +234,34 @@ def signal_from_flimlabs_json(
         Index of channel to return.
         By default, return the first channel.
         If None, return all channels.
-    dtype : dtype-like, optional, default: uint16
+    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>` ``'CYXH'`` and
-        type specified in ``dtype``:
+        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
-        File is not a FLIM LABS JSON file containing TCSPC histogram.
-        `dtype` is not an unsigned integer.
+        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
-        Channel out of range.
+        If `channel` is out of range.
 
     See Also
     --------
@@ -271,7 +281,7 @@ def signal_from_flimlabs_json(
     >>> signal.coords['H'].data
     array(...)
     >>> signal.attrs['frequency']  # doctest: +NUMBER
-    40.00
+    40.0
 
     """
     with open(filename, 'rb') as fh:
@@ -317,7 +327,7 @@ def signal_from_flimlabs_json(
 
     from .._phasorpy import _flimlabs_signal
 
-    signal = numpy.zeros((nchannels, height * width, 256), dtype)
+    signal = numpy.zeros((nchannels, height * width, 256), dtype=dtype)
     _flimlabs_signal(
         signal,
         intensities_data,

phasorpy/io/_leica.py

@@ -82,7 +82,6 @@ def phasor_from_lif(
     import liffile
 
     image = '' if image is None else f'.*{image}.*/'
-    samples = 1
 
     with liffile.LifFile(filename) as lif:
         try:
@@ -100,27 +99,9 @@ def phasor_from_lif(
             ) from exc
 
         attrs: dict[str, Any] = {'dims': dims, 'coords': coords}
-        flim = im.parent_image
-        if flim is not None and isinstance(flim, liffile.LifFlimImage):
-            xml = flim.parent.xml_element
-            frequency = xml.find('.//Dataset/RawData/LaserPulseFrequency')
-            if frequency is not None and frequency.text is not None:
-                attrs['frequency'] = float(frequency.text) * 1e-6
-                clock_period = xml.find('.//Dataset/RawData/ClockPeriod')
-                if clock_period is not None and clock_period.text is not None:
-                    tmp = float(clock_period.text) * float(frequency.text)
-                    samples = int(round(1.0 / tmp))
-                    attrs['samples'] = samples
-            channels = []
-            for channel in xml.findall(
-                './/Dataset/FlimData/PhasorData/Channels'
-            ):
-                ch = liffile.xml2dict(channel)['Channels']
-                ch.pop('PhasorPlotShapes', None)
-                channels.append(ch)
-            attrs['flim_phasor_channels'] = channels
-            attrs['flim_rawdata'] = flim.attrs.get('RawData', {})
+        _flim_metadata(im.parent_image, attrs)
 
+    samples = attrs.get('samples', 1)
     if samples > 1:
         mean /= samples
     return (
@@ -140,6 +121,9 @@ def lifetime_from_lif(
 
     Leica image files may contain fluorescence lifetime images and metadata
     from the analysis of FLIM measurements.
+    The lifetimes are average photon arrival times ("Fast FLIM") according to
+    the LAS X FLIM/FCS documentation. They are not corrected for the IRF
+    position.
 
     Parameters
     ----------
@@ -151,7 +135,7 @@ def lifetime_from_lif(
     Returns
     -------
     lifetime : ndarray
-        Fluorescence lifetime image in ns.
+        Fast FLIM lifetime image in ns.
     intensity : ndarray
         Fluorescence intensity image.
     stddev : ndarray
@@ -183,6 +167,8 @@ def lifetime_from_lif(
 
     Examples
     --------
+    Read Fast FLIM lifetime and related images from a Leica image file:
+
     >>> lifetime, intensity, stddev, attrs = lifetime_from_lif(
     ...     fetch('FLIM_testdata.lif')
     ... )
@@ -193,6 +179,12 @@ def lifetime_from_lif(
     >>> attrs['frequency']
     19.505
 
+    Calibrate the Fast FLIM lifetime for IRF position:
+
+    >>> frequency = attrs['frequency']
+    >>> reference = attrs['flim_phasor_channels'][0]['AutomaticReferencePhase']
+    >>> lifetime -= math.radians(reference) / (2 * math.pi) / frequency * 1000
+
     """
     import liffile
 
@@ -213,18 +205,7 @@ def lifetime_from_lif(
             ) from exc
 
         attrs: dict[str, Any] = {'dims': dims, 'coords': coords}
-        flim = im.parent_image
-        if flim is not None and isinstance(flim, liffile.LifFlimImage):
-            xml = flim.parent.xml_element
-            frequency = xml.find('.//Dataset/RawData/LaserPulseFrequency')
-            if frequency is not None and frequency.text is not None:
-                attrs['frequency'] = float(frequency.text) * 1e-6
-                clock_period = xml.find('.//Dataset/RawData/ClockPeriod')
-                if clock_period is not None and clock_period.text is not None:
-                    tmp = float(clock_period.text) * float(frequency.text)
-                    samples = int(round(1.0 / tmp))
-                    attrs['samples'] = samples
-            attrs['flim_rawdata'] = flim.attrs.get('RawData', {})
+        _flim_metadata(im.parent_image, attrs)
 
     return (
         lifetime.astype(numpy.float32),
@@ -234,6 +215,29 @@ def lifetime_from_lif(
     )
 
 
+def _flim_metadata(flim: Any | None, attrs: dict[str, Any]) -> None:
+    """Add FLIM metadata to attrs."""
+    import liffile
+
+    if flim is not None and isinstance(flim, liffile.LifFlimImage):
+        xml = flim.parent.xml_element
+        frequency = xml.find('.//Dataset/RawData/LaserPulseFrequency')
+        if frequency is not None and frequency.text is not None:
+            attrs['frequency'] = float(frequency.text) * 1e-6
+            clock_period = xml.find('.//Dataset/RawData/ClockPeriod')
+            if clock_period is not None and clock_period.text is not None:
+                tmp = float(clock_period.text) * float(frequency.text)
+                samples = int(round(1.0 / tmp))
+                attrs['samples'] = samples
+        channels = []
+        for channel in xml.findall('.//Dataset/FlimData/PhasorData/Channels'):
+            ch = liffile.xml2dict(channel)['Channels']
+            ch.pop('PhasorPlotShapes', None)
+            channels.append(ch)
+        attrs['flim_phasor_channels'] = channels
+        attrs['flim_rawdata'] = flim.attrs.get('RawData', {})
+
+
 def signal_from_lif(
     filename: str | PathLike[Any],
     /,

phasorpy/io/_ometiff.py

@@ -81,22 +81,21 @@ def phasor_to_ometiff(
     harmonic : int or sequence of int, optional
         Harmonics present in the first dimension of `real` and `imag`, if any.
         Write to image series named 'Phasor harmonic'.
-        It is only needed if harmonics are not starting at and increasing by
-        one.
+        Only needed if harmonics are not starting at and increasing by one.
     dims : sequence of str, optional
         Character codes for `mean` image dimensions.
         By default, the last dimensions are assumed to be 'TZCYX'.
         If harmonics are present in `real` and `imag`, an "other" (``Q``)
         dimension is prepended to axes for those arrays.
         Refer to the OME-TIFF model for allowed axes and their order.
-    dtype : dtype-like, optional
+    dtype : dtype_like, optional
         Floating point data type used to store phasor coordinates.
         The default is ``float32``, which has 6 digits of precision
         and maximizes compatibility with other software.
     description : str, optional
         Plain-text description of dataset. Write as OME dataset description.
     **kwargs
-        Additional arguments passed to :py:class:`tifffile.TiffWriter` and
+        Optional arguments passed to :py:class:`tifffile.TiffWriter` and
         :py:meth:`tifffile.TiffWriter.write`.
         For example, ``compression=None`` writes image data uncompressed.
 
@@ -136,9 +135,9 @@ def phasor_to_ometiff(
     if dtype.kind != 'f':
         raise ValueError(f'{dtype=} not a floating point type')
 
-    mean = numpy.asarray(mean, dtype)
-    real = numpy.asarray(real, dtype)
-    imag = numpy.asarray(imag, dtype)
+    mean = numpy.asarray(mean, dtype=dtype)
+    real = numpy.asarray(real, dtype=dtype)
+    imag = numpy.asarray(imag, dtype=dtype)
     datasize = mean.nbytes + real.nbytes + imag.nbytes
 
     if real.shape != imag.shape:
@@ -167,7 +166,9 @@ def phasor_to_ometiff(
             raise ValueError('invalid harmonic')
 
     if frequency is not None:
-        frequency_array = numpy.atleast_2d(frequency).astype(numpy.float64)
+        frequency_array = numpy.array(
+            frequency, dtype=numpy.float64, ndmin=2, copy=None
+        )
         if frequency_array.size > 1:
             raise ValueError('frequency must be scalar')
 
@@ -227,7 +228,7 @@ def phasor_to_ometiff(
 
         if harmonic is not None:
             tif.write(
-                numpy.atleast_2d(harmonic).astype(numpy.uint32),
+                numpy.array(harmonic, dtype=numpy.uint32, ndmin=2),
                 metadata={'Name': 'Phasor harmonic'},
             )
 

phasorpy/io/_other.py

@@ -8,11 +8,13 @@ __all__ = [
     'phasor_from_ifli',
     'signal_from_imspector_tiff',
     'signal_from_lsm',
+    'signal_from_pqbin',
     'signal_from_ptu',
     'signal_from_sdt',
 ]
 
 import os
+import struct
 from typing import TYPE_CHECKING
 from xml.etree import ElementTree
 
@@ -48,7 +50,7 @@ def signal_from_sdt(
     filename : str or Path
         Name of Becker & Hickl SDT file to read.
     index : int, optional, default: 0
-        Index of dataset to read in case the file contains multiple datasets.
+        Index of dataset to read if the file contains multiple datasets.
 
     Returns
     -------
@@ -63,7 +65,7 @@ def signal_from_sdt(
     Raises
     ------
     ValueError
-        File is not a SDT file containing TCSPC histogram.
+        File is not an SDT file containing TCSPC histogram.
 
     Notes
     -----
@@ -127,6 +129,7 @@ def signal_from_ptu(
     channel: int | None = 0,
     dtime: int | None = 0,
     keepdims: bool = False,
+    **kwargs: Any,
 ) -> DataArray:
     """Return TCSPC histogram and metadata from PicoQuant PTU T3 mode file.
 
@@ -141,7 +144,7 @@ def signal_from_ptu(
         Indices for all dimensions of image mode files:
 
         - ``None``: return all items along axis (default).
-        - ``Ellipsis``: return all items along multiple axes.
+        - ``Ellipsis`` (``...``): return all items along multiple axes.
         - ``int``: return single item along axis.
         - ``slice``: return chunk of axis.
           ``slice.step`` is a binning factor.
@@ -149,7 +152,7 @@ def signal_from_ptu(
 
     trimdims : str, optional, default: 'TCH'
         Axes to trim.
-    dtype : dtype-like, optional, default: uint16
+    dtype : dtype_like, optional, default: uint16
         Unsigned integer type of TCSPC histogram.
         Increase the bit depth to avoid overflows when integrating.
     frame : int, optional
@@ -168,6 +171,9 @@ def signal_from_ptu(
         Overrides `selection` for axis ``H``.
     keepdims : bool, optional, default: False
         If true, return reduced axes as size-one dimensions.
+    **kwargs
+        Optional arguments passed to :py:meth:`PtuFile.decode_image`
+        or :py:meth:`PtuFile.decode_histogram`.
 
     Returns
     -------
@@ -214,6 +220,8 @@ def signal_from_ptu(
     import ptufile
     from xarray import DataArray
 
+    kwargs.pop('records', None)
+
     with ptufile.PtuFile(filename, trimdims=trimdims) as ptu:
         if not ptu.is_t3:
             raise ValueError(f'{ptu.filename!r} is not a T3 mode PTU file')
@@ -226,6 +234,7 @@ def signal_from_ptu(
                 dtime=dtime,
                 keepdims=keepdims,
                 asxarray=True,
+                **kwargs,
             )
             assert isinstance(data, DataArray)
         elif ptu.measurement_submode == 1:
@@ -233,7 +242,7 @@ def signal_from_ptu(
             if dtime == -1:
                 raise ValueError(f'{dtime=} not supported for point mode')
             data = ptu.decode_histogram(
-                dtype=dtype, dtime=dtime, asxarray=True
+                dtype=dtype, dtime=dtime, asxarray=True, **kwargs
             )
             assert isinstance(data, DataArray)
             if channel is not None:
@@ -263,7 +272,7 @@ def signal_from_lsm(
 ) -> DataArray:
     """Return hyperspectral image and metadata from Zeiss LSM file.
 
-    LSM files contain multi-dimensional images and metadata from laser
+    Zeiss LSM files contain multi-dimensional images and metadata from laser
     scanning microscopy measurements. The file format is based on TIFF.
 
     Parameters
@@ -542,7 +551,7 @@ def phasor_from_ifli(
         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 : int, sequence of int, 'any', or 'all', optional
         Harmonic(s) to return from file.
         If None (default), return the first harmonic stored in file.
         If `'all'`, return all harmonics of first frequency stored in file.
@@ -553,7 +562,7 @@ def phasor_from_ifli(
         If an integer, the returned `real` and `imag` arrays are single
         harmonic and have the same shape as `mean`.
     **kwargs
-        Additional arguments passed to :py:meth:`lfdfiles.VistaIfli.asarray`,
+        Optional arguments passed to :py:meth:`lfdfiles.VistaIfli.asarray`,
         for example ``memmap=True``.
 
     Returns
@@ -780,3 +789,102 @@ def signal_from_flif(
     from xarray import DataArray
 
     return DataArray(data, **metadata)
+
+
+def signal_from_pqbin(
+    filename: str | PathLike[Any],
+    /,
+) -> DataArray:
+    """Return TCSPC histogram and metadata from PicoQuant BIN file.
+
+    PicoQuant BIN files contain TCSPC histograms with limited metadata.
+
+    Parameters
+    ----------
+    filename : str or Path
+        Name of PicoQuant BIN file to read.
+
+    Returns
+    -------
+    xarray.DataArray
+        TCSPC histogram with :ref:`axes codes <axes>` ``'YXH'``,
+        and type ``uint32``.
+
+        - ``coords['H']``: delay-times of histogram bins in ns.
+        - ``attrs['frequency']``: repetition frequency in MHz.
+          This assumes that the histogram contains exactly one period.
+
+    Raises
+    ------
+    ValueError
+        File is not a PicoQuant BIN file.
+
+    Examples
+    --------
+    >>> signal = signal_from_pqbin('picoquant.bin')  # doctest: +SKIP
+    >>> signal.values  # doctest: +SKIP
+    array(...)
+    >>> signal.dtype  # doctest: +SKIP
+    dtype('uint32')
+    >>> signal.shape  # doctest: +SKIP
+    (256, 256, 2000)
+    >>> signal.dims  # doctest: +SKIP
+    ('Y', 'X', 'H')
+    >>> signal.coords['H'].data  # doctest: +SKIP
+    array([0, ..., 49.975])
+    >>> signal.attrs['frequency']  # doctest: +SKIP
+    19.99
+
+    """
+    with open(filename, 'rb') as fh:
+        header = fh.read(20)
+        if len(header) != 20:
+            raise ValueError(
+                f'invalid PicoQuant BIN header length {len(header)} != 20'
+            )
+        (size_x, size_y, pixel_resolution, size_h, tcspc_resolution) = (
+            struct.unpack('<IIfIf', header)
+        )
+        size = size_y * size_x * size_h * 4
+
+        # check the header values against arbitrary but reasonable limits
+        # to detect invalid files and prevent memory errors
+        if (
+            size <= 0
+            or size > 2**35 - 1  # 32 GiB
+            or size_x > 16384
+            or size_y > 16384
+            or size_h > 16384
+            or pixel_resolution < 0.0
+            or pixel_resolution > 1.0
+            or tcspc_resolution <= 0.0
+            or tcspc_resolution > 1.0
+        ):
+            raise ValueError('invalid PicoQuant BIN file header')
+
+        shape = size_y, size_x, size_h
+        data = numpy.empty(shape, dtype='<u4')
+        if fh.readinto(data) != size:
+            raise ValueError('invalid PicoQuant BIN data size')
+
+    metadata = xarray_metadata(
+        ('Y', 'X', 'H'),
+        shape,
+        filename,
+        attrs={
+            'frequency': 1000.0 / (size_h * tcspc_resolution),  # MHz
+            'pixel_resolution': pixel_resolution,  # um
+            'tcspc_resolution': tcspc_resolution,  # ns
+        },
+        Y=numpy.linspace(
+            0, size_y * pixel_resolution * 1e-6, size_y, endpoint=False
+        ),
+        X=numpy.linspace(
+            0, size_x * pixel_resolution * 1e-6, size_x, endpoint=False
+        ),
+        H=numpy.linspace(0, size_h * tcspc_resolution, size_h, endpoint=False),
+    )
+
+    from xarray import DataArray
+
+    return DataArray(data, **metadata)