phasorpy/phasorpy

An open-source Python library for the analysis of fluorescence lifetime and hyperspectral images using the phasor approach

PhasorPy

PhasorPy is an open-source Python library for the analysis of fluorescence lifetime and hyperspectral images using the phasor approach.

• License: MIT
• Documentation: phasorpy.org
• Source code: github.com/phasorpy/phasorpy
• Bug reports and questions: github.com/phasorpy/phasorpy/issues

PhasorPy is a community-maintained project. Contributions in the form of bug reports, bug fixes, feature implementations, documentation, datasets, and enhancement proposals are welcome.

The development of the PhasorPy library is supported by the Chan Zuckerberg Initiative.

phasorpy's Issues

Support Zeiss CZI files

These resources may be useful for implementing a file reader for the Zeiss CZI/ZISRAW file format:

• The CZI file format specification can be requested from Zeiss.

• A collection of CZI files can be found at https://forum.image.sc/t/would-anyone-have-a-palm-czi-example-file/85900. It does not include hyperspectral fluorescence images.

• pylibCZIrw/libCZIrw is the official implementation by Zeiss for reading CZI files. It is release under LGPL license, which is compatible with MIT.

• aicsimageio provides a wrapper for pylibCZIrw. It is BSD licensed, but indirectly uses the GPL licensed Bio-Formats library, which is incompatible with MIT. Aicsimageio also supports ND2 and LIF files.

• czifile is an independent implementation released under BSD license. It is currently unmaintained and has known issues with multi-resolution images. The library could be resuscitated by the PhasorPy project.

• Hyperspectral CZI files can be created by exporting hyperspectral LSM files from the Zeiss ZEN lite software.

The only native, non-exported hyperspectral CZI file available to us (Q 5719_a.czi) apparently stores two acquisition channels with a spectral scans each in a single dimension. No available software can correctly separate the spectral scans from the acquisition channel.

polar_from_reference does not match polar_from_reference_phasor and phasor_transform

I am rewriting many functions of the phasor module to use numpy universal functions implemented in Cython and got test failures in test_polar_from_reference. It looks like the return values of polar_from_reference do not match polar_from_reference_phasor and what is expected by the phasor_transform function:

polar_from_reference:

phasorpy/src/phasorpy/phasor.py

Lines 737 to 738 in c2f1262

	phase_zero = measured_phase - known_phase
	modulation_zero = measured_modulation / known_modulation

polar_from_reference_phasor:

phasorpy/src/phasorpy/phasor.py

Lines 676 to 677 in c2f1262

	phase_zero = known_phi - measured_phi
	modulation_zero = known_mod / measured_mod

Add methods for center of mass of phasor coordinates calculation

This issue proposes the implementation of new methods to the phasor_center function for computing the center of mass from phasor coordinates. Already implemented methods include 'mean' and 'median' (spatial median).

The new methods include but are not limited to:

• 'kmeans': K-Means is an iterative clustering algorithm assigning data points to centroids for center of mass computation, optimizing within-cluster variance.
• 'geometric_median': Optimal center point minimizing total geometric distance, surpassing spatial median in robustness to outliers and sensitivity to spatial arrangement.

The implementation of 'kmeans' has been delayed to avoid adding 'sklearn' as a dependence in the proyect. Similar with 'geometric_median' which might need 'scipy' as a dependence.

The methods should be implemented as private helper functions for phasor_center.

`phasor_center` does not allow to pass keyword arguments to numpy functions

The function phasor_center from the phasor module doesn't accept as input keyword arguments that can be passed to numpy base functions in the different methods that are supported by phasor_center. Both mean and median methods already have the possibility to accept keyword arguments that are passed to numpy functions.

Multiple component analysis

This issue proposes the addition of a phasorpy.components module for the analysis and quantification of multiple components, both for fluorescence lifetime and spectral imaging. The following list encompasses some, but not all, of the features useful for component analysis that are proposed to be implemented:

• Location of second unknown component when location of only one is known.
• Histogram distribution of points across line that joins two components
• The contribution of two components in a phasor point when the location of pure individual species is known.
• Contribution of three and four components in a phasor point when the location of pure individual species is known (mathematical solution by solving equations system).
• Contribution of three and four components in a phasor point when the location of pure individual species is known (graphical solution with moving cursors).
• Blind component analysis: method using more than one harmonic to resolve components and their fractional intensities when location of pure species is unknown.

Tutorial for phasorpy?

Is there a tutorial of how to use the phasorpy? like script of how to read in and process the tif stack or ptu, etc.? thaks in advance!

Support Leica LIF files

LIF (Leica Image File) is the native file format of the LAS X microscope software by Leica Microsystems CMS GmbH.

LIF file produced by the STELLARIS 8 FALCON FLIM Microscope are of particular interest for this project.

LIF files can be read by the Bio-Formats and readlif libraries. However, both libraries are GPL licensed and support for FLIM data is limited.

LIF files can be viewed with the free LASX Office software.

Sample files:

• Public sample images from OME
• FLIM testdata on figshare
• PTU exported from Leica LAS, discussed on Image.sc

Support PicoQuant PT3 and PTU files

Dr Evangelos Sisamakis, Product Manager Microscopy at PicoQuant GmbH, kindly provided some resources, which may facilitate implementing a file reader for the PicoQuant PT3 and PTU file formats.

The demo workspace dataset contains data files used in the SymPhoTime Analysis tutorials.

The SPT 64 tutorials dataset contains data files for the Lifetime-Fitting Using the FLIM Analysis tutorial.

The Luminosa software can be used freely to open data files taken with a Luminosa system.

A few Python scripts (but no ready to use library) are available to read PTU and PT3 files:

• Python/Read_PTU.py: official reference implementation

• readPTU_FLIM.py

• picoquantio: unreleased Python package

• snAPI wrapper: for time traces and correlation curves, not images

The data T3-mode formats are described at https://www.tcspc.com/doku.php/glossary:t3-mode.

Following steps

Following steps are (Jan):

1. @schutyb

• Enhace #20
• Implement a tools module with:
• Median filtering using, scikit-image, scipy, maybe others.
• Thresholding

2. @bruno-pannunzio

• Creat a 2d histigram like https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.hist2d.html#matplotlib-pyplot-hist2d to store the phasor counting, it may be useful later for ellipsis.
• Same for dc histogram.
• FLIM calibration.

Then:

1. Implement cursors to performe reciprocity principle. There is somethings done here https://github.com/schutyb/rep-hsipy
2. Creat a lut for each ROI
3. Export the analysis, which include: cursors position on the phasors, pseudocolor image, filtered phasor...
4. Two component analysis
5. N-Component analysis: implement two ways, Alex wich is done here in Matlab https://github.com/ubaimaging/LaurdanCilia and then Tamara implemented in Python for HSI. Then implement Enrico´s analysis.
6. Ellipsis. Suman Ranjit´s paper.
7. FRET
8. Multidimensional phasors.

FLIM calibration

This issue contemplates the implementation of function and/or methods to perform the calibration of FLIM data. Calibration is mandatory when working with FLIM images to account for the instrument response function (IRF) and delays in the electronics. Calibration standards are often selected to have a mono-exponential decay with known lifetime. The known lifetime values for different fluorophores can be found in:

https://iss.com/resources#lifetime-data-of-selected-fluorophores

After calibration, multiple images can be compared when transformed in the phasor data, even if they were acquired with different conditions.

Implementation of the calibration should consider an input of FLIM data from an image to be analyzed and FLIM data from a reference image with a fluorophore of known lifetime.

The function `phasor_calibrate` can't handle multiple harmonic calibration

The function phasor_calibrate from the phasor module can't handle multiple harmonic calibration at the same time. Although the skip_axes argument is in place to be used as an indicator of the harmonic content, the broadcasting is not done correctly, particularly by the function phasor_transform of the phasor module which is called by phasor_calibrate.

Add a lifetime calculator module

This issue proposes the addition of a phasorpy.lifetime module for fluorescence lifetime and energy transfer (FRET) calculations with the following features:

• calculate phasor coordinates from time- and frequency-domain signals
• convert between
  • phasor coordinates
  • phase and modulation
  • apparent single lifetimes
  • lifetime mixtures with fractional intensities or pre-exponential amplitudes
• reference phasor coordinates
• generate synthetic signals, time domain decay and frequency domain wave
• calculate FRET as a function of
  • donor and acceptor lifetime
  • FRET efficiency
  • donors with FRET
  • donor in acceptor channel
  • direct acceptor excitation
  • donor and acceptor channel background
  • frequency
• n-dimensional aware

Implementations of exponential or global fitting are not planned.

Some of the implementation can be taken from the vLFD Lifetime Demo (written in ~2007). That requires the following steps:

• port code from Python 2 to 3
• replace C extension module with numpy or Cython
• make n-dimensional aware
• add tests
• add documentation
• convert interactive app to tutorial or console script