phasorpy.io#

Read and write time-resolved and hyperspectral image file formats.

The phasorpy.io module provides functions to:

read and write phasor coordinate images in OME-TIFF format, which can be imported in Bio-Formats and Fiji:
- phasor_to_ometiff()
- phasor_from_ometiff()
read and write phasor coordinate images in SimFCS referenced R64 format:
- phasor_to_simfcs_referenced()
- phasor_from_simfcs_referenced()
read time-resolved and hyperspectral image data and metadata (as relevant to phasor analysis) from many file formats used in bio-imaging:
- read_lsm() - Zeiss LSM
- read_ifli() - ISS IFLI
- read_sdt() - Becker & Hickl SDT
- read_ptu() - PicoQuant PTU
- read_fbd() - FLIMbox FBD
- read_flif() - FlimFast FLIF
- read_b64() - SimFCS B64
- read_z64() - SimFCS Z64
- read_bhz() - SimFCS BHZ
- read_bh() - SimFCS B&H
Support for other file formats is being considered:
- OME-TIFF
- Zeiss CZI
- Leica LIF
- Nikon ND2
- Olympus OIB/OIF
- Olympus OIR

The functions are implemented as minimal wrappers around specialized third-party file reader libraries, currently tifffile, ptufile, sdtfile, and lfdfiles. For advanced or unsupported use cases, consider using these libraries directly.

The read functions typically have the following signature:

read_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 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)

Axes character codes 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 axes character codes. 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 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)

phasorpy.io.phasor_from_ometiff(filename, /, *, harmonic=None)[source]#

Return phasor images and metadata from OME-TIFF written by PhasorPy.

Parameters:

filename (str or Path) – Name of OME-TIFF file to read.
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.
real (ndarray) – Image of real component of phasor coordinates.
imag (ndarray) – Image of imaginary component of phasor coordinates.
attrs (dict) – Select metadata:
- 'axes' (str): Character codes for mean image dimensions.
- 'harmonic' (int or list of int): Harmonic(s) present in real and imag. If a scalar, real and imag are single harmonic and contain no harmonic axes. If a list, real and imag contain one or more harmonics in the first axis.
- 'frequency' (float, optional): Fundamental frequency of time-resolved phasor coordinates.
- 'description' (str, optional): OME dataset plain-text description.

Raises:

tifffile.TiffFileError – File is not a TIFF file.
ValueError – File is not an OME-TIFF containing phasor coordinates.
IndexError – Requested harmonic is not found in file.

See also

phasorpy.io.phasor_to_ometiff

Notes

Scalar or one-dimensional phasor coordinates stored in the file are returned as two-dimensional images (three-dimensional if multiple harmonics are present).

Examples

>>> mean, real, imag = numpy.random.rand(3, 32, 32, 32)
>>> phasor_to_ometiff(
...     '_phasorpy.ome.tif', mean, real, imag, axes='ZYX', frequency=80.0
... )
>>> mean, real, imag, attrs = phasor_from_ometiff('_phasorpy.ome.tif')
>>> mean
array(...)
>>> mean.dtype
dtype('float32')
>>> mean.shape
(32, 32, 32)
>>> attrs['axes']
'ZYX'
>>> attrs['frequency']
80.0
>>> attrs['harmonic']
1

phasorpy.io.phasor_from_simfcs_referenced(filename, /, *, harmonic=None)[source]#

Return phasor coordinate images from SimFCS referenced (REF, R64) file.

SimFCS referenced REF and R64 files contain phasor coordinate images (encoded as phase and modulation) for two harmonics. Phasor coordinates from lifetime-resolved signals are calibrated.

Parameters:

filename (str or Path) – Name of REF or R64 file to read.
harmonic (int or sequence of int, optional) – Harmonic(s) to include in returned phasor coordinates. By default, only the first harmonic is returned.

Returns:

mean (ndarray) – Average intensity image.
real (ndarray) – Image of real component of phasor coordinates. Multiple harmonics, if any, are in the first axis.
imag (ndarray) – Image of imaginary component of phasor coordinates. Multiple harmonics, if any, are in the first axis.

Raises:

lfdfiles.LfdfileError – File is not a SimFCS REF or R64 file.

Examples

>>> phasor_to_simfcs_referenced(
...     '_phasorpy.r64', *numpy.random.rand(3, 32, 32)
... )
>>> mean, real, imag = phasor_from_simfcs_referenced('_phasorpy.r64')
>>> mean
array([[...]], dtype=float32)

phasorpy.io.phasor_to_ometiff(filename, mean, real, imag, /, *, frequency=None, harmonic=None, axes=None, dtype=None, description=None, **kwargs)[source]#

Write phasor coordinate images and metadata to OME-TIFF file.

The OME-TIFF format is compatible with Bio-Formats and Fiji.

By default, write phasor coordinates as single precision floating point values to separate image series. Write images larger than (1024, 1024) as (256, 256) tiles, datasets larger than 2 GB as BigTIFF, and datasets larger than 8 KB zlib-compressed.

This file format is experimental and might be incompatible with future versions of this library. It is intended for temporarily exchanging phasor coordinates with other software, not as a long-term storage solution.

Parameters:

filename (str or Path) – Name of OME-TIFF file to write.
mean (array_like) – Average intensity image. Write to image series named ‘Phasor mean’.
real (array_like) – Image of real component of phasor coordinates. Multiple harmonics, if any, must be in the first dimension. Write to image series named ‘Phasor real’.
imag (array_like) – Image of imaginary component of phasor coordinates. Multiple harmonics, if any, must be in the first dimension. Write to image series named ‘Phasor imag’.
frequency (float, optional) – Fundamental frequency of time-resolved phasor coordinates. Write to image series named ‘Phasor frequency’.
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’. Only needed if harmonics are not starting at and increasing by one.
axes (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) – 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 tifffile.TiffWriter and tifffile.TiffWriter.write(). For example, compression=None writes image data uncompressed.

See also

phasorpy.io.phasor_from_ometiff

Notes

Scalar or one-dimensional phasor coordinate arrays are written as images.

The OME-TIFF format is specified in the OME Data Model and File Formats Documentation.

The 6D, 7D and 8D storage extension is used to store multi-harmonic phasor coordinates. The modulo type for the first, harmonic dimension is “other”.

Examples

>>> mean, real, imag = numpy.random.rand(3, 32, 32, 32)
>>> phasor_to_ometiff(
...     '_phasorpy.ome.tif', mean, real, imag, axes='ZYX', frequency=80.0
... )

phasorpy.io.phasor_to_simfcs_referenced(filename, mean, real, imag, /, *, size=None, axes=None)[source]#

Write phasor coordinate images to SimFCS referenced R64 file(s).

SimFCS referenced R64 files store square-shaped (commonly 256x256) images of the average intensity, and the calibrated phasor coordinates (encoded as phase and modulation) of two harmonics as ZIP-compressed, single precision floating point arrays. The file format does not support any metadata.

Images with more than two dimensions or larger than square size are chunked to square-sized images and saved to separate files with a name pattern, for example, “filename_T099_Y256_X000.r64”. Images or chunks with less than two dimensions or smaller than square size are padded with NaN values.

Parameters:

filename (str or Path) – Name of SimFCS referenced R64 file to write. The file extension must be .r64.
mean (array_like) – Average intensity image.
real (array_like) – Image of real component of calibrated phasor coordinates. Multiple harmonics, if any, must be in the first dimension. Harmonics must be starting at and increasing by one.
imag (array_like) – Image of imaginary component of calibrated phasor coordinates. Multiple harmonics, if any, must be in the first dimension. 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. By default, size = min(256, max(4, sizey, sizex)).
axes (str, optional) – Character codes for mean dimensions used to format file names.

Examples

>>> mean, real, imag = numpy.random.rand(3, 32, 32)
>>> phasor_to_simfcs_referenced('_phasorpy.r64', mean, real, imag)

phasorpy.io.read_b64(filename, /)[source]#

Return intensity image and metadata from SimFCS B64 file.

B64 files contain one or more square intensity image(s), a carpet of lines, or a stream of intensity data. B64 files contain no metadata.

Parameters:

filename (str or Path) – Name of SimFCS B64 file to read.

Returns:

Stack of square-sized intensity images of type int16.

Return type:

xarray.DataArray

Raises:

lfdfiles.LfdFileError – File is not a SimFCS B64 file.
ValueError – File does not contain an image stack.

Examples

>>> data = read_b64(fetch('simfcs.b64'))
>>> data.values
array(...)
>>> data.dtype
dtype('int16')
>>> data.shape
(22, 1024, 1024)
>>> data.dtype
dtype('int16')
>>> data.dims
('I', 'Y', 'X')

phasorpy.io.read_bh(filename, /)[source]#

Return image and metadata from SimFCS B&H file.

B&H files contain time-domain fluorescence lifetime histogram data, acquired from Becker & Hickl(r) TCSPC cards, or converted from other data sources. B&H files contain no metadata.

Parameters:: filename (str or Path) – Name of SimFCS B&H file to read.
Returns:: Time-domain fluorescence lifetime histogram with axes 'HYX', shape (256, 256, 256), and type float32.
Return type:: xarray.DataArray
Raises:: lfdfiles.LfdFileError – File is not a SimFCS B&H file.

Examples

>>> data = read_bh(fetch('simfcs.b&h'))
>>> data.values
array(...)
>>> data.dtype
dtype('float32')
>>> data.shape
(256, 256, 256)
>>> data.dims
('H', 'Y', 'X')

phasorpy.io.read_bhz(filename, /)[source]#

Return image and metadata from SimFCS BHZ file.

BHZ files contain time-domain fluorescence lifetime histogram data, acquired from Becker & Hickl(r) TCSPC cards, or converted from other data sources. BHZ files contain no metadata.

Parameters:: filename (str or Path) – Name of SimFCS BHZ file to read.
Returns:: Time-domain fluorescence lifetime histogram with axes 'HYX', shape (256, 256, 256), and type float32.
Return type:: xarray.DataArray
Raises:: lfdfiles.LfdFileError – File is not a SimFCS BHZ file.

Examples

>>> data = read_bhz(fetch('simfcs.bhz'))
>>> data.values
array(...)
>>> data.dtype
dtype('float32')
>>> data.shape
(256, 256, 256)
>>> data.dims
('H', 'Y', 'X')

phasorpy.io.read_fbd(filename, /, *, frame=None, channel=None, keepdims=True, laser_factor=-1.0)[source]#

Return frequency-domain image and metadata from FLIMbox FBD file.

FDB files contain encoded data from the FLIMbox device, which can be decoded to photon arrival windows, channels, and global times. The encoding scheme depends on the FLIMbox device’s firmware. The FBD file format is undocumented.

This function may fail to produce expected results when files use unknown firmware, do not contain image scans, settings were recorded incorrectly, scanner and FLIMbox frequencies were out of sync, or scanner settings were changed during acquisition.

Parameters:

filename (str or Path) – Name of FLIMbox FBD file to read.
frame (int, optional) – If None (default), return all frames. If < 0, integrate time axis, else return specified frame.
channel (int, optional) – If None (default), return all channels, else return specified channel.
keepdims (bool, optional) – If true (default), reduced axes are left as size-one dimension.
laser_factor (float, optional) – Factor to correct dwell_time/laser_frequency.

Returns:

Frequency-domain image histogram with axes codes 'TCYXH' and type uint16:

coords['H']: phases in radians.
attrs['frequency']: repetition frequency in MHz.

Return type:

xarray.DataArray

Raises:

lfdfiles.LfdFileError – File is not a FLIMbox FBD file.

Examples

>>> data = read_fbd(fetch('convallaria_000$EI0S.fbd'))  
>>> data.values  
array(...)
>>> data.dtype  
dtype('uint16')
>>> data.shape  
(9, 2, 256, 256, 64)
>>> data.dims  
('T', 'C', 'Y', 'X', 'H')
>>> data.coords['H'].data  
array(...)
>>> data.attrs['frequency']  
40.0

phasorpy.io.read_flif(filename, /)[source]#

Return frequency-domain image and metadata from FlimFast FLIF file.

FlimFast FLIF files contain camera images and metadata from frequency-domain fluorescence lifetime measurements.

Parameters:

filename (str or Path) – Name of FlimFast FLIF file to read.

Returns:

Frequency-domain phase images with axes codes 'THYX' and type uint16:

coords['H']: phases in radians.
attrs['frequency']: repetition frequency in MHz.
attrs['ref_phase']: measured phase of reference.
attrs['ref_mod']: measured modulation of reference.
attrs['ref_tauphase']: lifetime from phase of reference.
attrs['ref_taumod']: lifetime from modulation of reference.

Return type:

xarray.DataArray

Raises:

lfdfiles.LfdFileError – File is not a FlimFast FLIF file.

Examples

>>> data = read_flif(fetch('flimfast.flif'))
>>> data.values
array(...)
>>> data.dtype
dtype('uint16')
>>> data.shape
(32, 220, 300)
>>> data.dims
('H', 'Y', 'X')
>>> data.coords['H'].data
array(...)
>>> data.attrs['frequency']
80.65...

phasorpy.io.read_ifli(filename, /, *, channel=0, **kwargs)[source]#

Return image and metadata from ISS IFLI file.

ISS VistaVision IFLI files contain phasor coordinates for several positions, wavelengths, time points, channels, slices, and frequencies from analog or digital frequency-domain fluorescence lifetime measurements.

Parameters:

filename (str or Path) – Name of ISS IFLI file to read.
channel (int, optional) – Index of channel to return. The first channel is returned by default.
**kwargs – Additional arguments passed to lfdfiles.VistaIfli.asarray(), for example memmap=True.

Returns:

Average intensity and phasor coordinates. An array of up to 8 dimensions with axes codes 'RCTZYXFS' and type float32. The last dimension contains mean, real, and imag phasor coordinates.

coords['F']: modulation frequencies.
coords['C']: emission wavelengths, if any.
attrs['ref_tau']: reference lifetimes.
attrs['ref_tau_frac']: reference lifetime fractions.
attrs['ref_phasor']: reference phasor coordinates for all frequencies.

Return type:

xarray.DataArray

Raises:

lfdfiles.LfdFileError – File is not an ISS IFLI file.

Examples

>>> data = read_ifli(fetch('frequency_domain.ifli'))
>>> data.values
array(...)
>>> data.dtype
dtype('float32')
>>> data.shape
(256, 256, 4, 3)
>>> data.dims
('Y', 'X', 'F', 'S')
>>> data.coords['F'].data
array([8.033...])
>>> data.coords['S'].data
array(['mean', 'real', 'imag'], dtype='<U4')
>>> data.attrs
{'ref_tau': (2.5, 0.0), 'ref_tau_frac': (1.0, 0.0), 'ref_phasor': array...}

phasorpy.io.read_lsm(filename, /)[source]#

Return hyperspectral image and metadata from Zeiss LSM file.

LSM files contain multi-dimensional images and metadata from laser scanning microscopy measurements. The file format is based on TIFF.

Parameters:

filename (str or Path) – Name of OME-TIFF file to read.

Returns:

Hyperspectral image data. Usually, a 3-to-5-dimensional array of type uint8 or uint16.

Return type:

xarray.DataArray

Raises:

tifffile.TiffFileError – File is not a TIFF file.
ValueError – File is not an LSM file or does not contain hyperspectral image.

Examples

>>> data = read_lsm(fetch('paramecium.lsm'))
>>> data.values
array(...)
>>> data.dtype
dtype('uint8')
>>> data.shape
(30, 512, 512)
>>> data.dims
('C', 'Y', 'X')
>>> data.coords['C'].data  # wavelengths
array(...)

phasorpy.io.read_ptu(filename, /, selection=None, *, trimdims=None, dtype=None, frame=None, channel=None, dtime=0, keepdims=True)[source]#

Return image histogram and metadata from PicoQuant PTU T3 mode file.

PTU files contain time-correlated single photon counting measurement data and instrumentation parameters.

Parameters:

filename (str or Path) – Name of PTU file to read.
selection (sequence of index types, optional) –
Indices for all dimensions:
- None: return all items along axis (default).
- Ellipsis: return all items along multiple axes.
- int: return single item along axis.
- slice: return chunk of axis. slice.step is binning factor. If slice.step=-1, integrate all items along axis.
trimdims (str, optional, default: 'TCH') – Axes to trim.
dtype (dtype-like, optional, default: uint16) – Unsigned integer type of image histogram array. Increase the bit depth to avoid overflows when integrating.
frame (int, optional) – If < 0, integrate time axis, else return specified frame. Overrides selection for axis T.
channel (int, optional) – If < 0, integrate channel axis, else return specified channel. Overrides selection for axis C.
dtime (int, optional, default: 0) – Specifies number of bins in image histogram. If 0 (default), return number of bins in one period. If < 0, integrate delay time axis. If > 0, return up to specified bin. Overrides selection for axis H.
keepdims (bool, optional, default: True) – If true (default), reduced axes are left as size-one dimension.

Returns:

Decoded TTTR T3 records as up to 5-dimensional image array with axes codes 'TYXCH' and type specified in dtype:

coords['H']: times of the histogram bins.
attrs['frequency']: repetition frequency in MHz.

Return type:

xarray.DataArray

Raises:

ptufile.PqFileError – File is not a PicoQuant PTU file or is corrupted.
ValueError – File is not a PicoQuant PTU T3 mode file containing time-correlated single photon counting data.

Examples

>>> data = read_ptu(fetch('hazelnut_FLIM_single_image.ptu'))
>>> data.values
array(...)
>>> data.dtype
dtype('uint16')
>>> data.shape
(5, 256, 256, 1, 132)
>>> data.dims
('T', 'Y', 'X', 'C', 'H')
>>> data.coords['H'].data
array(...)
>>> data.attrs['frequency']
78.02

phasorpy.io.read_sdt(filename, /, *, index=0)[source]#

Return time-resolved image and metadata from Becker & Hickl SDT file.

SDT files contain time-correlated single photon counting measurement data and instrumentation parameters.

Parameters:

filename (str or Path) – Name of SDT file to read.
index (int, optional, default: 0) – Index of dataset to read in case the file contains multiple datasets.

Returns:

Time correlated single photon counting image data with axes codes 'YXH' and type uint16, uint32, or float32.

coords['H']: times of the histogram bins.
attrs['frequency']: repetition frequency in MHz.

Return type:

xarray.DataArray

Raises:

ValueError – File is not an SDT file containing time-correlated single photon counting data.

Examples

>>> data = read_sdt(fetch('tcspc.sdt'))
>>> data.values
array(...)
>>> data.dtype
dtype('uint16')
>>> data.shape
(128, 128, 256)
>>> data.dims
('Y', 'X', 'H')
>>> data.coords['H'].data
array(...)
>>> data.attrs['frequency']
79...

phasorpy.io.read_z64(filename, /)[source]#

Return image and metadata from SimFCS Z64 file.

Z64 files contain stacks of square images such as intensity volumes or time-domain fluorescence lifetime histograms acquired from Becker & Hickl(r) TCSPC cards. Z64 files contain no metadata.

Parameters:: filename (str or Path) – Name of SimFCS Z64 file to read.
Returns:: Single or stack of square-sized images of type float32.
Return type:: xarray.DataArray
Raises:: lfdfiles.LfdFileError – File is not a SimFCS Z64 file.

Examples

>>> data = read_z64(fetch('simfcs.z64'))
>>> data.values
array(...)
>>> data.dtype
dtype('float32')
>>> data.shape
(256, 256, 256)
>>> data.dims
('Q', 'Y', 'X')