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

phasorpy/io/__init__.py

@@ -47,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

@@ -157,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']
@@ -173,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
@@ -327,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 (
@@ -141,7 +122,8 @@ 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.
+    the LAS X FLIM/FCS documentation. They are not corrected for the IRF
+    position.
 
     Parameters
     ----------
@@ -185,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')
     ... )
@@ -195,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
 
@@ -215,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),
@@ -236,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

@@ -95,7 +95,7 @@ def phasor_to_ometiff(
     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.
 
@@ -135,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:
@@ -166,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')
 
@@ -226,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

@@ -172,7 +172,7 @@ def signal_from_ptu(
     keepdims : bool, optional, default: False
         If true, return reduced axes as size-one dimensions.
     **kwargs
-        Additional arguments passed to :py:meth:`PtuFile.decode_image`
+        Optional arguments passed to :py:meth:`PtuFile.decode_image`
         or :py:meth:`PtuFile.decode_histogram`.
 
     Returns
@@ -562,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
@@ -863,7 +863,7 @@ def signal_from_pqbin(
             raise ValueError('invalid PicoQuant BIN file header')
 
         shape = size_y, size_x, size_h
-        data = numpy.empty(shape, '<u4')
+        data = numpy.empty(shape, dtype='<u4')
         if fh.readinto(data) != size:
             raise ValueError('invalid PicoQuant BIN data size')
 

phasorpy/io/_simfcs.py

@@ -97,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
@@ -272,7 +272,7 @@ def phasor_from_simfcs_referenced(
     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
@@ -294,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.
@@ -322,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
     -------
@@ -338,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
     --------
@@ -365,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

phasorpy/lifetime.py

@@ -276,13 +276,13 @@ def phasor_from_lifetime(
     """
     if unit_conversion < 1e-16:
         raise ValueError(f'{unit_conversion=} < 1e-16')
-    frequency = numpy.atleast_1d(
-        numpy.ascontiguousarray(frequency, dtype=numpy.float64)
+    frequency = numpy.array(
+        frequency, dtype=numpy.float64, ndmin=1, order='C', copy=None
     )
     if frequency.ndim != 1:
         raise ValueError('frequency is not one-dimensional array')
-    lifetime = numpy.atleast_1d(
-        numpy.ascontiguousarray(lifetime, dtype=numpy.float64)
+    lifetime = numpy.array(
+        lifetime, dtype=numpy.float64, ndmin=1, order='C', copy=None
     )
     if lifetime.ndim > 2:
         raise ValueError('lifetime must be one- or two-dimensional array')
@@ -296,8 +296,8 @@ def phasor_from_lifetime(
         lifetime = lifetime.reshape(-1, 1)  # move components to last axis
         fraction = numpy.ones_like(lifetime)  # not really used
     else:
-        fraction = numpy.atleast_1d(
-            numpy.ascontiguousarray(fraction, dtype=numpy.float64)
+        fraction = numpy.array(
+            fraction, dtype=numpy.float64, ndmin=1, order='C', copy=None
         )
         if fraction.ndim > 2:
             raise ValueError('fraction must be one- or two-dimensional array')
@@ -1021,8 +1021,8 @@ def phasor_to_lifetime_search(
     if dtype.char not in {'f', 'd'}:
         raise ValueError(f'{dtype=} is not a floating point type')
 
-    real = numpy.ascontiguousarray(real, dtype)
-    imag = numpy.ascontiguousarray(imag, dtype)
+    real = numpy.ascontiguousarray(real, dtype=dtype)
+    imag = numpy.ascontiguousarray(imag, dtype=dtype)
 
     if real.shape != imag.shape:
         raise ValueError(f'{real.shape=} != {imag.shape=}')
@@ -1134,7 +1134,7 @@ def phasor_to_apparent_lifetime(
     (array([inf, 0]), array([inf, 0]))
 
     """
-    omega = numpy.array(frequency, dtype=numpy.float64)  # makes copy
+    omega = numpy.asarray(frequency, dtype=numpy.float64, copy=True)
     omega *= math.pi * 2.0 * unit_conversion
     return _phasor_to_apparent_lifetime(  # type: ignore[no-any-return]
         real, imag, omega, **kwargs
@@ -1218,7 +1218,7 @@ def phasor_from_apparent_lifetime(
     (array([1, 0.0]), array([0, 0.0]))
 
     """
-    omega = numpy.array(frequency, dtype=numpy.float64)  # makes copy
+    omega = numpy.asarray(frequency, dtype=numpy.float64, copy=True)
     omega *= math.pi * 2.0 * unit_conversion
     if modulation_lifetime is None:
         return _phasor_from_single_lifetime(  # type: ignore[no-any-return]
@@ -1302,7 +1302,7 @@ def phasor_to_normal_lifetime(
     array([1.989, 1.989])
 
     """
-    omega = numpy.array(frequency, dtype=numpy.float64)  # makes copy
+    omega = numpy.asarray(frequency, dtype=numpy.float64, copy=True)
     omega *= math.pi * 2.0 * unit_conversion
     return _phasor_to_normal_lifetime(  # type: ignore[no-any-return]
         real, imag, omega, **kwargs
@@ -1445,7 +1445,7 @@ def lifetime_fraction_to_amplitude(
     array([0.2, 0.2])
 
     """
-    t = numpy.array(fraction, dtype=numpy.float64)  # makes copy
+    t = numpy.asarray(fraction, dtype=numpy.float64, copy=True)
     t /= numpy.sum(t, axis=axis, keepdims=True)
     numpy.true_divide(t, lifetime, out=t)
     return t
@@ -1757,7 +1757,7 @@ def polar_to_apparent_lifetime(
     (array([1.989, 1.989]), array([1.989, 2.411]))
 
     """
-    omega = numpy.array(frequency, dtype=numpy.float64)  # makes copy
+    omega = numpy.asarray(frequency, dtype=numpy.float64, copy=True)
     omega *= math.pi * 2.0 * unit_conversion
     return _polar_to_apparent_lifetime(  # type: ignore[no-any-return]
         phase, modulation, omega, **kwargs
@@ -1829,7 +1829,7 @@ def polar_from_apparent_lifetime(
     (array([0.7854, 0.7854]), array([0.7071, 0.6364]))
 
     """
-    omega = numpy.array(frequency, dtype=numpy.float64)  # makes copy
+    omega = numpy.asarray(frequency, dtype=numpy.float64, copy=True)
     omega *= math.pi * 2.0 * unit_conversion
     if modulation_lifetime is None:
         return _polar_from_single_lifetime(  # type: ignore[no-any-return]
@@ -1923,7 +1923,7 @@ def phasor_from_fret_donor(
     (array([0.1766, 0.2737, 0.1466]), array([0.3626, 0.4134, 0.2534]))
 
     """
-    omega = numpy.array(frequency, dtype=numpy.float64)  # makes copy
+    omega = numpy.asarray(frequency, dtype=numpy.float64, copy=True)
     omega *= math.pi * 2.0 * unit_conversion
     return _phasor_from_fret_donor(  # type: ignore[no-any-return]
         omega,
@@ -2041,7 +2041,7 @@ def phasor_from_fret_acceptor(
     (array([0.1996, 0.05772, 0.2867]), array([0.3225, 0.3103, 0.4292]))
 
     """
-    omega = numpy.array(frequency, dtype=numpy.float64)  # makes copy
+    omega = numpy.asarray(frequency, dtype=numpy.float64, copy=True)
     omega *= math.pi * 2.0 * unit_conversion
     return _phasor_from_fret_acceptor(  # type: ignore[no-any-return]
         omega,