phasorpy 0.6__cp311-cp311-win_arm64.whl → 0.7__cp311-cp311-win_arm64.whl

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
+        Additional 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.
@@ -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, '<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)

phasorpy/io/_simfcs.py

@@ -12,6 +12,7 @@ __all__ = [
     'signal_from_z64',
 ]
 
+import math
 import os
 import struct
 import zlib
@@ -75,9 +76,11 @@ def phasor_to_simfcs_referenced(
         Harmonics must be starting at and increasing by one.
     size : int, optional
         Size of X and Y dimensions of square-sized images stored in file.
+        Must be in range [4, 65535].
         By default, ``size = min(256, max(4, sizey, sizex))``.
     dims : sequence of str, optional
         Character codes for `mean` dimensions used to format file names.
+        Only used when chunking multi-dimensional data into multiple files.
 
     See Also
     --------
@@ -180,17 +183,21 @@ def phasor_from_simfcs_referenced(
 ) -> tuple[NDArray[Any], NDArray[Any], NDArray[Any], dict[str, Any]]:
     """Return phasor coordinates and metadata from SimFCS REF or R64 file.
 
-    SimFCS referenced REF and R64 files contain phasor coordinate images
-    (encoded as phase and modulation) for two harmonics.
+    SimFCS referenced REF and R64 files contain square-shaped phasor
+    coordinate images (encoded as phase and modulation) for two harmonics.
     Phasor coordinates from lifetime-resolved signals are calibrated.
+    Variants of referenced files (RE<n>) written by other software may
+    contain up to eight harmonics and may be uncalibrated.
 
     Parameters
     ----------
     filename : str or Path
-        Name of SimFCS REF or R64 file to read.
-    harmonic : int or sequence of int, optional
+        Name of SimFCS REF, R64, or RE<n> file to read.
+    harmonic : int, sequence of int, or 'all', optional
         Harmonic(s) to include in returned phasor coordinates.
         By default, only the first harmonic is returned.
+        If 'all', return all available harmonics.
+        If int or sequence, return specified harmonic(s).
 
     Returns
     -------
@@ -203,7 +210,7 @@ def phasor_from_simfcs_referenced(
         Image of imaginary component of phasor coordinates.
         Multiple harmonics, if any, are in the first axis.
     attrs : dict
-        Select metadata:
+        Select metadata containing:
 
         - ``'dims'`` (tuple of str):
           :ref:`Axes codes <axes>` for `mean` image dimensions.
@@ -211,7 +218,7 @@ def phasor_from_simfcs_referenced(
     Raises
     ------
     lfdfiles.LfdfileError
-        File is not a SimFCS REF or R64 file.
+        File is not a SimFCS REF, R64, or RE<n> file.
 
     See Also
     --------
@@ -219,7 +226,7 @@ def phasor_from_simfcs_referenced(
 
     Notes
     -----
-    The implementation is based on the
+    The implementation for reading R64 files is based on the
     `lfdfiles <https://github.com/cgohlke/lfdfiles/>`__ library.
 
     Examples
@@ -232,17 +239,35 @@ def phasor_from_simfcs_referenced(
     array([[...]], dtype=float32)
 
     """
-    import lfdfiles
-
     ext = os.path.splitext(filename)[-1].lower()
     if ext == '.r64':
+        import lfdfiles
+
         with lfdfiles.SimfcsR64(filename) as r64:
             data = r64.asarray()
-    elif ext == '.ref':
-        with lfdfiles.SimfcsRef(filename) as ref:
-            data = ref.asarray()
+    elif ext.startswith('.re') and len(ext) == 4:
+        if ext[-1] == 'f':
+            num_images = 5
+        elif ext[-1].isdigit():
+            # non-SimFCS referenced files containing other number of harmonics
+            num_images = int(ext[-1]) * 2 + 1
+        else:
+            raise ValueError(
+                f'file extension must be .ref, .r64, or .re<n>, not {ext!r}'
+            )
+        size = os.path.getsize(filename)
+        if (
+            size > 4294967295
+            or size % (num_images * 4)
+            or not math.sqrt(size // (num_images * 4)).is_integer()
+        ):
+            raise ValueError(f'{filename!r} is not a valid referenced file')
+        size = int(math.sqrt(size // (num_images * 4)))
+        data = numpy.fromfile(filename, dtype='<f4').reshape((-1, size, size))
     else:
-        raise ValueError(f'file extension must be .ref or .r64, not {ext!r}')
+        raise ValueError(
+            f'file extension must be .ref, .r64, or .re<n>, not {ext!r}'
+        )
 
     harmonic, keep_harmonic_dim = parse_harmonic(harmonic, data.shape[0] // 2)
 
@@ -289,7 +314,7 @@ def signal_from_fbd(
     frame : int, optional
         If None (default), return all frames.
         If < 0, integrate time axis, else return specified frame.
-    channel : int, optional
+    channel : int or None, optional
         Index of channel to return.
         By default, return the first channel.
         If None, return all channels.
@@ -530,7 +555,7 @@ def signal_from_bh(
     Returns
     -------
     xarray.DataArray
-        TCSPC histogram with ref:`axes codes <axes>` ``'HYX'``,
+        TCSPC histogram with :ref:`axes codes <axes>` ``'HYX'``,
         shape ``(256, 256, 256)``, and type ``float32``.
 
     Raises
@@ -587,7 +612,7 @@ def signal_from_bhz(
     Returns
     -------
     xarray.DataArray
-        TCSPC histogram with ref:`axes codes <axes>` ``'HYX'``,
+        TCSPC histogram with :ref:`axes codes <axes>` ``'HYX'``,
         shape ``(256, 256, 256)``, and type ``float32``.
 
     Raises