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

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
     --------
@@ -94,7 +97,7 @@ def phasor_to_simfcs_referenced(
         raise ValueError(f'file extension {ext} != .r64')
 
     # TODO: delay conversions to numpy arrays to inner loop
-    mean = numpy.asarray(mean, numpy.float32)
+    mean = numpy.asarray(mean, dtype=numpy.float32)
     phi, mod = phasor_to_polar(real, imag, dtype=numpy.float32)
     del real
     del imag
@@ -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,22 +239,40 @@ 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)
 
     mean = data[0].copy()
-    real = numpy.empty((len(harmonic),) + mean.shape, numpy.float32)
+    real = numpy.empty((len(harmonic),) + mean.shape, dtype=numpy.float32)
     imag = numpy.empty_like(real)
     for i, h in enumerate(harmonic):
         h = (h - 1) * 2 + 1
@@ -269,10 +294,11 @@ def signal_from_fbd(
     channel: int | None = 0,
     keepdims: bool = False,
     laser_factor: float = -1.0,
+    **kwargs: Any,
 ) -> DataArray:
     """Return phase histogram and metadata from FLIMbox FBD file.
 
-    FDB files contain encoded cross-correlation phase histograms from
+    FBD files contain encoded cross-correlation phase histograms from
     digital frequency-domain measurements using a FLIMbox device.
     The encoding scheme depends on the FLIMbox device's firmware.
     The FBD file format is undocumented.
@@ -289,7 +315,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.
@@ -297,6 +323,8 @@ def signal_from_fbd(
         If true, return reduced axes as size-one dimensions.
     laser_factor : float, optional
         Factor to correct dwell_time/laser_frequency.
+    **kwargs
+        Optional arguments passed to :py:class:`fbdfile.FbdFile`.
 
     Returns
     -------
@@ -313,13 +341,13 @@ def signal_from_fbd(
 
     Raises
     ------
-    lfdfiles.LfdFileError
+    ValueError
         File is not a FLIMbox FBD file.
 
     Notes
     -----
     The implementation is based on the
-    `lfdfiles <https://github.com/cgohlke/lfdfiles/>`__ library.
+    `fbdfile <https://github.com/cgohlke/fbdfile/>`__ library.
 
     Examples
     --------
@@ -340,12 +368,12 @@ def signal_from_fbd(
     40.0
 
     """
-    import lfdfiles
+    import fbdfile
 
     integrate_frames = 0 if frame is None or frame >= 0 else 1
 
-    with lfdfiles.FlimboxFbd(filename, laser_factor=laser_factor) as fbd:
-        data = fbd.asimage(None, None, integrate_frames=integrate_frames)
+    with fbdfile.FbdFile(filename, laser_factor=laser_factor, **kwargs) as fbd:
+        data = fbd.asimage(integrate_frames=integrate_frames)
         if integrate_frames:
             frame = None
         copy = False
@@ -530,7 +558,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 +615,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