Plugins / FLIMKit / Step by Step Guide · edit on GitHub

Step-by-Step Guide

A worked analysis of one field of view, Ado_1.ptu, from opening the file to exporting the maps, followed by a project folder with a z-stack, the tile stitching form, and a list of every file FLIMKit reads and writes. Every screenshot is the desktop GUI running from source (v0.13.5 plus the commits after it), and every number quoted was produced by those runs. Your numbers will differ with your data and your machine IRF, but the order of the steps and the reasons for each setting carry over.

Ado_1.ptu is a single 1024 x 1024 px field of view: 1,714,555 photons in channel 1, 529 TCSPC bins of 96.97 ps, a 19.505 MHz laser (51.27 ns period) and 127.5 s of acquisition.

Step 1: Open the file

Start the GUI (python main.py, or the compiled app) and stay in Single FOV Fit mode.

The window has four areas. The Project list on the left fills when you open a folder (Step 13). The settings form sits in the middle, with the Progress log, Fit Summary and Images tabs underneath. The FOV Preview on the right shows the intensity image, the lifetime map and the summed decay.

Input Files:

Load Ado_1.ptu. The preview draws the intensity image and the summed decay straight away, and the status line under the preview gives the image size and photon count.

If a Ado_1.roi_session.npz already sits next to the file, FLIMKit restores the last fit, the ROIs and the form settings from it instead of starting clean. The log says [Auto-Load] No session found when there isn't one.

Look at the decay before you change anything. This one rises at about 2.6 ns, decays over roughly three decades, and has a small peak at about 47 ns. That peak is the start of the next laser period, and FLIMKit finds it and cuts the fit window short of it on its own (Step 6).

Step 2: Choose the IRF

The instrument response function is the largest single source of systematic error in a reconvolution fit, and it matters most for the shortest component. The ⓘ next to each section heading opens the same explanations inside the app.

The Machine IRF path box appears under the options when a machine IRF method is picked, filled with your default. The default can be changed in File > Preferences... > Files (Machine IRF Setup). For Ado_1.ptu I used Machine IRF, since there is no LAS X export for this file.

Step 3: Set the fitting parameters

Step 4: Masking and thresholding

Ado_1.ptu ran at 0.0007 photons per pulse (0.07%), so pile-up correction stays off. I left the mask off for the first fits to show what it changes in Step 8.

Step 5: Expert settings

Expert Settings opens a dialog shared by the single FOV and tile pipelines. When anything in it differs from the defaults, an orange "Custom expert settings active" line appears above the run button.

For Ado_1.ptu I left everything at the defaults until Step 7.

Step 6: Run a fast fit first

With Fast mode and 2 components, Run Single-FOV Fit took a few seconds.

The Progress log records every choice the fit made, so it's the first place to look when a result seems wrong.

Section [1] reads the file header, and section [2] gives the count rate and photons per pulse used to decide on pile-up correction. Section [5] shows the fit window chosen: here FLIMKit found the next-period artefact at bin 484 (46.93 ns) and fitted bins 19-464 (1.84-44.99 ns) automatically.

The 2-exponential result was τ₁ = 4.04 ns and τ₂ = 0.61 ns with χ²_r(tail) = 18.29, and the residuals have a clear wave across the first 20 ns. That structure means the model is missing something. Changing to 3 components and running again dropped χ²_r(tail) to 1.53 and flattened the residuals, so I kept three. A lower χ² on its own doesn't justify an extra component, since more parameters always fit better. Check that the new lifetimes are physically distinct and that the residuals improved.

Step 7: Full fit and binning

With 3 components, switch Fitting mode to Full and run again. A progress window counts the pixels as they're fitted.

At binning 1 only 34,680 of 507,977 signal pixels (6.8%) reached the 10-photon minimum, which the log flags as PHOTON-STARVED. When most of the image is starved, FLIMKit says so when the fit finishes and suggests a binning.

Binning sums an N x N block of pixels into one decay before fitting, trading resolution for photons per pixel. With Spatial binning set to 8 in Expert Settings, the map filled in.

The per-pixel fit keeps the summed-fit lifetimes and fits only the amplitudes in each pixel, unless Free τ per pixel is on. The map is the amplitude-weighted mean lifetime per pixel. The background between the cells now fills with noise-dominated values, which the next step removes.

Step 8: Mask out the background

Tick Apply cell mask (Cellpose-SAM) and run again.

The map now covers the segmented cells only. The summed decay is built from those pixels too, so the global fit changes with it: τ = 5.81, 1.94 and 0.398 ns and χ²_r(tail) = 1.244. Cellpose missed part of one cell at the top left here, so check the mask (saved as <prefix>_cell_mask.png) before trusting the per-cell statistics.

Fit Summary tab, row by row:

Running the same fit twice gives identical numbers, since both optimisers are seeded. I refitted Ado_1 from a project folder in Step 13 and every value matched to the last digit.

The figures the fit saves

Every fit saves its figures next to the output prefix without being asked. These are from the masked 8 x 8 fit above.

<prefix>_summed_<n>exp.png is the summed fit.

<prefix>_pixelmaps_<n>exp.png is the per-pixel fit, only written by Full fits.

The top row is the photon count per pixel, the intensity-weighted mean lifetime and the amplitude-weighted mean lifetime. The bottom row is the amplitude fraction of each component, on a fixed 0 to 1 scale. The lifetime and intensity colour ranges run from the 2nd to the 98th percentile of the fitted pixels, so they won't match the range set in the preview, and unmasked background shows up as noise the same way it does on screen.

<prefix>_lifetime_hist_<n>exp.png is the distribution of per-pixel lifetimes.

Each pixel's intensity-weighted mean lifetime, weighted by its photon count, with the weighted mean as a dashed line: 2.840 ns here, against 2.834 ns from the summed fit. The preview map shows the amplitude-weighted lifetime by default, so the histogram and the map aren't showing the same quantity.

<prefix>_cell_mask.png is the Cellpose mask at the full image resolution, white for the pixels kept. Check it against the intensity image before trusting per-cell numbers.

The PNG export in Step 11 writes separate figures: <scan>_summed_decay.png is the decay, IRF and fit from the preview over the whole time range, without residuals.

Step 9: Adjust the display

The FLIM Color Scale panel under the preview changes the picture, never the fitted values.

The colour scale is saved into the session file, so it comes back when the file is reopened.

Step 10: Measure regions of interest

Open the ROI Analysis tab, pick a drawing mode and drag on either image.

The table gives, per region, the mean, median and standard deviation of the pixel lifetimes and the photon count. The ellipse over the lower cell gave τ_mean = 1.22 ns (median 1.18, SD 0.21) from 163,093 photons, and the rectangle over the upper cell 1.22 ns (median 1.19, SD 0.23) from 138,519. Regions are written to the session file as soon as they're drawn.

Fit ROI Decay re-fits a region from the raw file rather than taking values from the whole-FOV fit. It sums every photon inside the outline at full resolution, so the FOV fit's binning, photon threshold and background mask don't apply to it. It reuses the IRF from the last FOV fit. If there isn't one it falls back to a 0.2 ns Gaussian on the decay peak, and the IRF label in the results window says which was used. The FOV fit and the lifetime map are left as they were.

Step 11: Export

Export Images..., under the Fit Summary table, saves the images shown in the preview.

Every export is named after the scan, so the PNG export of Ado_1.ptu writes Ado_1_intensity.png, Ado_1_lifetime.png and Ado_1_summed_decay.png, and exporting several files into one folder doesn't overwrite anything. What else the fit writes by itself is listed in Step 16.

Step 12: Phasor analysis

Switch the mode to Phasor Analysis. The file and the machine IRF carry over from the fit form.

On the plot, a click places an elliptical cursor and the matching pixels light up in the image above. The toolbar above the plot has Clear all and Undo, Save session, Ellipse or Polygon cursors, the Radius and Minor/major sliders for the cursor shape, and Fit Cursor Decay / View Fit to fit the summed decay of the pixels under a cursor.

Ado_1.ptu gave 48,357 valid pixels at 19.5 MHz. A cursor of radius 0.05 on the main cloud of the raw phasor took 6,259 pixels with a phase lifetime τ_φ of 2.20-2.71 ns (median 2.45 ns).

The raw cloud is wide because each pixel carries few photons. Phasor filter smooths the G and S coordinates in image space, which pulls the cloud together without changing where it sits:

Apply runs the filter and Reset goes back to the raw data. With the wavelet filter and the same cursor, the count went to 13,771 pixels and τ_φ to 2.20-2.70 ns (median 2.43 ns).

The phasor session is saved as <file>_phasor.npz next to the data whenever a cursor or the filter changes. Loading the same file again recomputes the phasor with the current IRF and then puts the saved cursors and filter back on it, the same way a fit session comes back, and the log says [Auto-Load] Restored 1 cursor(s) and the wavelet filter from Ado_1_phasor.npz. Clear all and Reset start again from nothing.

Step 13: Work from a project folder

A project is a folder of acquisitions. File > Open Project Folder... lists every FLIM file in it, groups region_zX slices into z-stacks and picks up .xlif files for tiles. It writes a project.json into the folder to remember them. For this I made a folder holding Ado_1.ptu, Ado_2.ptu and the eight slices Series008_z1.ptu to Series008_z8.ptu.

Each row shows a session mark (○ nothing saved, ● a fit, ◐ a phasor, ◉ both) and the scan type (F for a field of view, Z for a z-stack, T for tiles from an XLIF). The footer counts scans and saved sessions. Clicking a row loads it into the right form, restoring its fit and ROIs when there is a session.

To fit several files the same way, fit one, keep it selected, and press Apply fit settings... under the list.

The dialog shows the model, IRF, lifetime bounds and display scales it will copy, and lists the other single-FOV files. Files that already have a fit are marked ● and their fit is replaced; ROIs aren't copied. I refitted Ado_1 in the project (3 components, machine IRF, cell mask, 8 x 8 binning) and applied it to Ado_2, which fitted to τ = 5.43, 1.58 and 0.264 ns with χ²_r(tail) = 2.29.

Clicking Ado_2 afterwards reloads its saved fit, residual plot included. The residuals are worked out from the saved decay and fitted curve. A session saved without the fitted curve has it rebuilt from the saved lifetimes, amplitudes, IRF shift and width and background, which gives back the same curve to rounding error.

Once two or more single-FOV files in the project have a fit, Export all... under the list exports them in one go. It has the same image, rendering and format options as the export dialog, and writes every file into one folder (exports in the project by default), each named after its scan. Each file is exported with its own saved display settings and ROIs. Two more boxes add each file's ROIs as <scan>_all_rois.geojson and its fit summary table as <scan>_fit_summary.txt, and a third adds the phasor plot and cursor image of every file that has a phasor session. A file with no ROIs gets no GeoJSON and a file with no phasor session gets no phasor PNGs, and the dialog at the end says which. Only fitted files are listed, so a file that has a phasor session but no fit isn't exported.

Step 14: Fit a z-stack

Selecting the Z row switches Analysis to Z-stack and fills the folder. The slider under the preview steps through the slices. The fit pools every slice to fit one set of lifetimes, then fits each slice per pixel with those lifetimes locked, so only the amplitudes change with depth (Timelapse and Z-stack Fitting). The form is the same as for a single FOV, and the button reads Run Z-stack Fit.

With the machine IRF and 2 components, the eight 256 x 256 slices (1,731,281 photons pooled) gave τ₁ = 3.48 ns and τ₂ = 0.572 ns, and per-slice amplitude-weighted means of 1.90-2.00 ns.

The residuals show why χ²_r(tail) came out at 688.9: this 25.7 ns period has a reflection peak at about 20 ns, and the whole period was fitted (bins 0-265).

Expert Settings apply to z-stacks the same way as to a single FOV. Setting Exclude bands to 19.6-21.2 dropped those bins from the fit, 248 of 265 fitted, and moved the pooled lifetimes to τ₁ = 3.66 ns and τ₂ = 0.604 ns. The calibrated tail χ² in Series008_reference_fit.json went from 159.6 to 21.1. It isn't near 1, so look at the residuals for what is left before trusting the absolute values. Spatial binning applies to every slice as well. The Images tab steps through the per-slice maps.

Step 15: Stitch tiles from an XLIF

Tile Stitch/Fit mode takes a tiled acquisition: the .xlif from the LAS X project's Metadata folder and the folder of PTU tiles exported with it.

Below the pipeline choice come the same IRF, model and masking sections as for a single FOV, then:

Step 16: What FLIMKit reads and writes

Files FLIMKit reads, apart from the FLIM data in Supported Input Formats:

Files FLIMKit writes: