Photonscore Matlab Toolbox

MATLAB® computing environment has been our data analysis workign horse for many years we were working in research. As a company we are happy to share our well-tested toolbox for FLIM analysis with our customers.

A complete example of using a toolbox to analyse MIET data set. Full source code and datafiles are available here (1.92 Gb).

Matlab functions
Syntax
h = edges_hist_1d(x, edges)
h = edges_hist_1d(x, edges, w)
Description

edges_hist_1d builds one-dimensional histogram with bins defined by edges parameter of values x with corresponding weights w. When the w parameter is not given the weight of every value of x is assumed to be 1.

Parameters

x
Vector of numeric values to put into the histogram.

edges
Sorted vector on numeric values defining the edges of the bins.

w
Vector of numeric values of the weights of corresponding values.

Return Values

h
Vector of length length(edges)-1</span of numeric values of the histogram.

Examples

Build a histogram of the values sequence from 1 to 5 into two-bin histogram.

>> photonscore.edges_hist_1d([1 2 3 4 5], [0 3 10], [1 10 2 3 4])

ans =

11 9

Here the first bin results in 11 because only two values 1 and 2 fall into the interval [0; 3). These values have corresponding weights of 1 and 10 that in sum yields 11. The second bin is the sum of the weights 2, 3 and 4 corresponding to the values 3, 4 and 5. In this example unweighted (e.g. the weight of every value is 1) equivalent of x is:

>> x = [1 … % w = 1
        2 2 2 2 2 2 2 2 2 2 … % w = 10
        3 3 … % w = 2
        4 4 4 … % w = 3
        5 5 5 5] % w = 4

x =

Columns 1 through 11

1 2 2 2 2 2 2 2 2 2 2

Columns 12 through 20

3 3 4 4 4 5 5 5 5

>> photonscore.edges_hist_1d(x, [0 3 10])

ans =

11 9

Syntax
info = photonscore.file_info(filename)
Description
file_info(filename) retrieves metadata from the file given by filename.
Parameters
filename String specifying path to a .PHOTONS file.
Return values
info Structure holding file information with the following fields:
  • aat_frequencty
    Numeric value specifying frequency of absolute arrival time clock in Hz.
  • created
    String value formatted as a date and time of file eation.
  • detector_guid
    String holding globally unique LINCam system identifier.
  • dt_channel
    Numeric value of ΔT channel width in picoseconds.
  • dt_bias
    Numeric value of TAC bias as set by the user in acquisition program.
  • duration
    Numeric value of total duration of the recorded photon streams in seconds.
  • file_guid
    String holding globally unique file identifier.
  • photons_count
    Numeric 64 bit integer numeric value of total number of recorded photons.
  • raw_info_
    cell array of all metadata read from the file in raw form;
Examples
Get the information about gfp.photons file. 
>> photonscore.file_info('gfp.photons')

ans =

  struct with fields:

     photons_count: 59905889
         raw_info_: {26×3 cell}
           created: '2019-02-28 14:31:23.166'
         file_guid: '{d47b5c6b-bd16-401a-97ea-e63e58e872ee}'
           dt_bias: 4095
        dt_channel: 23.2900
    aat_frequencty: 100000000
     detector_guid: '{961a443c-697d-426b-b991-2abe8485695c}'
          duration: 353.4260
The structure above reports there are about 59.9 million photons in this recording that lasted for 5 minutes and 53.426 seconds (353.4260).
Syntax
data = file_read(filename, dataset)
data = file_read(filename, dataset, offset, count)
Description
data = file_read(filename, dataset)
Retrieves all the data from the .PHOTONS of named dataset in the the file filename.
data = file_read(filename, dataset, offset, count)
Reads a subset of count long elements from dataset starting from the element pointed by offset.
Parameters
filename
String specifying the name of .PHOTONS file.
dataset
String specifying fully qualified dataset name in the .PHOTONS file given by filename parameter.
offset
Numeric value specifying the place to start reading the data. This is 0-based index. Prefer using uint64 type value to be able addressing the offsets in large datasets.
count
Numeric value specifying the amount of data to read.
Return values
data
Vector of read values.
Examples
Read an all x positions of the photons in the file 'gfp.photons': 
>> photonscore.file_read('gfp.photons', '/photons/x')
ans =

  59905889×1 uint16 column vector

   2904
   1519
   1876
   1803
   1997
   1858
   1379
   2111
   3467
   1867
   ....
Read five x positions starting from the forth value: 
>> photonscore.file_read('gfp.photons', '/photons/x', 3, 5)

ans =

  5×1 uint16 column vector

   1803
   1997
   1858
   1379
   2111
Note that to start reading from the 4th element, e.g. 1803 offset parameter value 3 is given.
Syntax
rgb = photonscore.flim.iw_tau(i, l);
rgb = photonscore.flim.iw_tau(i, l, pal);
rgb = photonscore.flim.iw_tau(i, ri, l, rt, pal);
Description
iw_tau(i, l) computes rgb image of the intensity i weighted lifetime l using 'preview.png' palette iw_tau(i, l, pal) computes rgb image of the intensity i weighted lifetime l using pal palette. iw_tau(i, ri, l, rt, pal) computes rgb image of the intensity weighted i lifetime l using pal palette cropping the dynamic range of intensity i into the range ri and limiting values of l into rl range. There are four palettes bundled with Photonscore toolbox:
Parameters
i
Numeric matrix of intensity values.
ri
Display range of intensity values. If this parameter is not provided the range would be generated to show the intensity from 0 counts up to a value that cut the to 10% off.
i
Numeric matrix of lifetime values.
li
Display range of lifetime values. If this parameter is not provided the range would be generated to show the lifetimes cutting 5% of lower values and 5% of the higher values. In other words the range would be adjusted to show 90% of the whole range of lifetime values.
pal
Filename of the palette image file or numeric array of of size N×M×3. If the string is provided the function will try to read it with imread function in the working directory. Than the build-in palettes path will be used to find the file.
Syntax
[medi, mea] = photonscore.flim.medimean(fl)
[medi, mea] = photonscore.flim.medimean(fl, range)
Description
medimean(fl, range) loops through the sorted dataset fl computed by flim.sort function and returns median and mean lifetime images where dt falls inside range.
Parameters
fl
Sorted dataset structure.
range
A numeric two element vector of values constraining the range of time values.
Syntax
fli = photonscore.flim.sort(x, x_min, x_max, x_bins, y, dt)
fli = photonscore.flim.sort(x, x_min, x_max, x_bins, ...
                            y, y_min, y_max, y_bins, dt)
Description
photonscore.flim.sort builds a 2D histogram of the positions x and y in the half-closed intervals [x_min, x_max) and [x_min, x_max) with the number of bins defined by x_bins and y_bins. If the histogramming options for y are not provided those for x are used, e.g. y_min = x_min, y_max = x_max and y_bins = x_bins. The values of dt are ordered from smaller to larger. To illustrate the operation of the sorting function consider the dataset of 2×2 positional bins marked with the colors and corresponding dt values: FLIM Sort After applying photonscore.flim.sort the resulting image (histogram) and the corresponding time values would look like shown here: FLIM Sort The benefit of this data organization is an ability to extract very fast fluorescence decays for corresponding positions.
Parameters
x, y
Vectors of 16-bit unsigned integer values to form the intensity image.
x_min, x_max, x_bins
Numeric values defining the histogram interval for values x.
y_min, y_may, y_bins
Numeric values defining the histogram interval for values y.
dt
Vectors of of 16-bit unsigned integer values of the decay.
Return values
fli structure with the following fields:
  • image x_bins×y_bins matrix of integer values holding number of counts of the bin.
  • time is the vector of sorted numeric values of dt parameter.
Example
To reproduce the results depicted above one can use the following code fragment: 
>> x  = uint16([2 1 2 2 1 1 2 2 1 1 2 2 1 1 1 2 1 2 1]);
>> y  = uint16([2 1 1 2 1 2 1 2 2 1 1 2 2 1 2 2 2 1 2]);
>> dt = uint16([1 2 7 4 7 3 1 6 3 2 4 5 8 9 2 5 7 1 2]);
>> fl = photonscore.flim.sort(x, 1, 3, 2, y, dt);
Evaluating the results would yield: 
>> fl

fl =

  struct with fields:

    image: [2×2 int32]
     time: [19×1 uint16]

>> fl.image'

ans =

  2×2 int32 matrix

   4   4
   6   5

>> fl.time'

ans =

  1×19 uint16 row vector

   2   2   7   9   1   1   4   7   2   2   3   3   7   8   1   4   5   5   6
Syntax
h = hist_1d(x, x_min, x_max, x_bins)
h = hist_1d(x, x_min, x_max, x_bins, type)

h = hist_2d(x, x_min, x_max, x_bins, y)
h = hist_2d(x, x_min, x_max, x_bins, y, type)
h = hist_2d(x, x_min, x_max, x_bins,...
            y, y_min, y_max, y_bins)
h = hist_2d(x, x_min, x_max, x_bins,...
            y, y_min, y_max, y_bins, type)

h = hist_3d(x, x_min, x_max, x_bins, y, z)
h = hist_3d(x, x_min, x_max, x_bins, y, z, type)
h = hist_3d(x, x_min, x_max, x_bins,...
            y,...
            z, z_min, z_max, z_bins)
h = hist_3d(x, x_min, x_max, x_bins,...
            y,...
            z, z_min, z_max, z_bins, type)
h = hist_3d(x, x_min, x_max, x_bins,...
            y, y_min, y_max, y_bins,...
            z, z_min, z_max, z_bins)
h = hist_3d(x, x_min, x_max, x_bins,...
            y, y_min, y_max, y_bins, ...
            z, z_min, z_max, z_bins, type)
Description
hist_1d builds one-dimensional histogram of the values x in the half-closed interval [x_min, x_max) that is split into x_bins equally sized bins. hist_2d build two-dimensional histogram of the values x and y in half-closed intervals [x_min, x_max) for x and [y_min, y_max) for y split into x_bins and y_bins respectively. hist_3d build three-dimensional histogram of the values x, y and z in half-closed intervals [x_min, x_max) for x, [y_min, y_max) for y and [z_min, z_max) for z split into x_bins, y_bins and z_bins respectively.
Parameters
x, y, z
Vectors of numeric values of the same numeric type to form the histogram.
x_min, x_max, x_bins
Numeric values defining the histogram interval for values x.
y_min, y_may, y_bins
Numeric values defining the histogram interval for values y.
z_min, z_maz, z_bins
Numeric values defining the histogram interval for values z.
type
String value that defines the resulting histogram type. Supported types are: uint8, uint16, uint32, int8,int16, int32, single and double
Return values
Returns a histogram as a vector of numeric values.
Examples
In this example the function count the number of events falling into the intervals [2, 3) and [3, 4]. From the input vector only value 2 falls into the first bin and two values (3 and 3.4) are inside the second interval. 
>> photonscore.hist_1d([1 2 3 3.4 5 10], 2, 4, 2)

ans =

     1
     2
Here we build a histogram of normally distributed values in a range [-3, 3) with 100 bins. 
>> x = -3:0.06:2.94;
>> h = photonscore.hist_1d(randn(1000, 1), -3, 3, 100);
>> stairs(x, h)
Gaussian distribution This example uses 10000 normally distributed values for x values and distorted for y. 
>> x = randn(10000, 1);
>> y = randn(10000, 1)/3 + x.^3/3;
>> imagesc(photonscore.hist_2d(x, -3, 3, 100, y))
>> colorbar
Distorted 2D gaussian distribution
Syntax
data = read_photons(filename)
data = read_photons(filename, range_seconds)
Description
read_photon(filename)
Reads all the photons attributes into the structure data.
read_photon(filename, range_seconds)
Reads a subset of photons data acquired within specified range.
Parameters
filename
String specifying the name of .PHOTONS file.
range_seconds
Two element vector of numeric values specifying the range of data in seconds.
Return values
data Structure holding the requested range of the data with the fields:
  • x
    Horisontal photon position
  • y
    Vertical photon position
  • dt
    Picosecond timing
Examples
Read the whole file into the memory. 
>> photonscore.read_photons('gfp.photons')

ans =

  struct with fields:

     x: [59905824×1 uint16]
     y: [59905824×1 uint16]
    dt: [59905824×1 uint16]
Read the photons detected within 1.2 seconds starting from the second 3. 
>> photonscore.read_photons('gfp.photons', [3 4.2])

ans =

  struct with fields:

     x: [203613×1 uint16]
     y: [203613×1 uint16]
    dt: [203613×1 uint16]