# publicbgamari/photon-tools

### Subversion checkout URL

You can clone with HTTPS or Subversion.

Python utilities for working with photon timestamp data

Fetching latest commit…

Cannot retrieve the latest commit at this time

 corr @ f79326d doc photon_tools picoharp tests .gitignore .gitmodules COPYING Makefile bin_photons blink_removal.py fcs-corr fcs-fit install.sh lifetime-deconvolve plot-bins plot-fret plot-photons readme.mkd rm-times rm-times-auto setup.py splice-times trim-stamps wavelet_denoise.py

# photon-tools - Tools for analysis of single-photon measurement data

photon-tools is a collection of tools for the manipulation and analysis of photon timestamp data, particularly from FRET and FCS experiments.

## Installation: the two-minute version

To install photon-tools on Ubuntu,

 $sudo apt-get install python python-numpy python-scipy python-matplotlib \ build-essential cython libboost-all-dev$ git clone git://github.com/bgamari/photon-tools.git
$cd photon-tools$ ./install.sh


## Installation: the unabridged version

Many of these utilities are written in Python and generally require Python 2.6 or greater along with numpy. In particular, some optimized modules require Cython. Utilities capable of producing plots require the matplotlib python plotting library. On the whole, photon-tools depends on,

• Gnu make
• Python >= 2.6
• Numpy
• Scipy
• Matplotlib >= 1.2 (due to issue #1246)
• Cython >= 0.15
• Boost

The scripts and libraries included in photon-tools can be installed like any Python distutils package,

 $sudo ./setup.py install  Note that running scripts within the photon-tools/ root directory will require that the Cython code is built in-place, due to limitations of Python's module name resolution scheme. To do this, one must run, $ ./setup.py build_ext --inplace


## Supported formats

Utilities requiring timestamp data as input accept data in the following formats,

• Raw 64-bit integer timestamps (read as little endian)
• Picoquant PT2
• Goldner FPGA timetagger .timetag files

In all of these cases, the utilities will attempt to figure out the period of the timebase (known as the jiffy) from whatever metadata is available in the format.

## Tools

The tools that photon-tools provides are command-line utilities following typical UNIX argument conventions. That is, most arguments are delimited by a dash and have both a long form (--output) and a short form (-o).

Below is a set of simple examples describing basic usage of the tools. These are, however, only basic examples and do not show all of the features of these tools. Full help for each utility is always available with from --help.

### plot-bins

The plot-bins utility produces a binned timeseries plot of a photon timestamp data set. This is useful to quickly visualize the trajectory of an experiment. For example, to get a high-level view of the intensity in a FRET experiment, one might want to plot the binned intensity over a long duration (say 5 rows of 20 seconds each) with a bin width of 10 ms,

 $plot-bins --rows=5 --row-width=20 --bin-width=1e-2 2012-07-26-run_013.timetag  This will produce a plot looking like, Note that plot-bins by default assumes a FRET experiment, taking channel 0 to be the donor and channel 1 to be the acceptor. This can be overridden with the --channel command (e.g. --channel=0=acceptor). ### fcs-corr In the case of an FCS experiment, the first task in the analysis process is generally to compute a correlation function. photon-tools provides the fcs-corr tool to conveniently compute and plot a correlation function from timestamp data. To compute and plot a correlation function from$\tau$of 1 microsecond to 1 second (which is the default range, but we will set it explicitly here for completeness), $ fcs-corr --min-lag=1e-6 --max-lag=1 2012-10-26-run_000.timetag


This will produce three files,

• 2012-10-25-run_001.timetag.acorr-0: the auto-correlation of channel 0
• 2012-10-25-run_001.timetag.acorr-1: the auto-correlation of channel 1
• 2012-10-25-run_001.timetag.xcorr-0-1: the cross-correlation of channels 0 and 1

Moreover, if we pass the --plot option a plot will be produced of each of these functions,

In addition, fcs-corr supports a simple means of afterpulsing correction correction. If we have a dataset with large afterpulsing signal,

We can take a dataset of uncorrelated emissions (say of a large background signal from room light) and correct for this contribution with,

$fcs-corr my-data.timetag -A room-light.timetag --plot  This will produce a signal with the afterpulsing contribution removed. Note, however, that the points at small lags will likely still be quite scattered due to count statistics, ### fcs-fit After one has computed the correlation function to a data set, it is typical that one would next fit a physically relevant model to the resulting function. The fcs-fit tool provides a means of fitting a model across one or several sets of observations. In the simplest case, it allows one to fit a single model (e.g. a three-dimensional diffusion model, --model=3d_diff) to a correlation function produced by fcs-corr, $ fcs-fit --plot -m3d_diff 9-24-2012-001.pt2.acorr-0
Fitting 1 curves against model 3d_diff

Initial parameters:
a  (fitted)   =    3.000e+00        Aspect ratio
F  (fixed )   =    0.000e+00        Fraction of particles in triplet state
tau_F  (fixed )   =    1.000e+00 us     Triplet state relaxation time
tau_d  (fitted)   =    1.000e+02 us     Diffusion time
n  (fitted)   =    5.000e-01        Concentration
offset  (fixed )   =    0.000e+00        Offset
alpha  (fixed )   =    1.000e+00        Anomalous diffusion exponent (1=normal diffusion)

Fitted parameters:
a  (fitted)   =    1.270e+01        Aspect ratio
F  (fixed )   =    0.000e+00        Fraction of particles in triplet state
tau_F  (fixed )   =    1.000e+00 us     Triplet state relaxation time
tau_d  (fitted)   =    1.370e+01 us     Diffusion time
n  (fitted)   =    3.810e+00        Concentration
offset  (fixed )   =    0.000e+00        Offset
alpha  (fixed )   =    1.000e+00        Anomalous diffusion exponent (1=normal diffusion)

Goodness of fit:
9-24-2012-001.pt2.acorr-0
Chi^2 = 1.642541e+02
Chi^2 / DOF = 1.013914


In the first block of this output we see the parameters of the model (3d_diff), along with their initial values and scope (e.g. whether the parameter is taken to be fixed or will be fitted). After this we see a similar list reflecting the parameter values resulting from the fit. Finally, we see some commonly used measures of goodness-of-fit.

Of course, things aren't always this easy. Fits are notoriously finicky in the presence of imperfect data as demonstrated in this example (omitting --model=3d_diff since this is the default),

 $fcs-fit 2012-10-25-run_001.timetag.acorr-0 -p Fitting 1 curves against model 3d_diff Initial Parameters: a (fitted) = 3.000e+00 Aspect ratio F (fixed ) = 0.000e+00 Fraction of particles in triplet state tau_F (fixed ) = 1.000e+00 us Triplet state relaxation time tau_d (fitted) = 1.000e+02 us Diffusion time n (fitted) = 5.000e-01 Concentration offset (fixed ) = 0.000e+00 Offset alpha (fixed ) = 1.000e+00 Anomalous diffusion exponent (1=normal diffusion) Failed to converge Fit failed to converge (flat axis)  Looking at the plot produced by fcs-corr, we find the reason for the fit failing is quite clear, Here we see a pronounced triplet artifact starting at around$\tau = $1 microsecond, in addition to a strong indication that the correlation function has not converged to zero a$\tau = 1$second. While the wisdom of forcing such flawed data to fit a model is of course questionable, we can nevertheless do so by cutting out the triplet (--early-cutoff=1e-6) and allowing the model to fit an offset (--set=fitted:offset=0.5), $ fcs-fit --plot 2012-10-25-run_001.timetag.acorr-0 -e 1e-6 -s fit:offset -s fit:tau_F -s fit:F
Fitting 1 curves against model 3d_diff

Initial parameters:
a  (fitted)   =    3.000e+00         Aspect ratio
F  (fixed )   =    0.000e+00         Fraction of particles in triplet state
tau_F  (fixed )   =    1.000e+00 us      Triplet state relaxation time
tau_d  (fitted)   =    1.000e+02 us      Diffusion time
n  (fitted)   =    5.000e-01         Concentration
offset  (fitted)   =    0.000e-01         Offset
alpha  (fixed )   =    1.000e+00         Anomalous diffusion exponent (1=normal diffusion)

Fitted parameters:
a  (fitted)   =    1.193e+01         Aspect ratio
F  (fitted)   =    2.128e-01         Fraction of particles in triplet state
tau_F  (fixed )   =    4.612e+01 us      Triplet state relaxation time
tau_d  (fitted)   =    3.919e+02 us      Diffusion time
n  (fitted)   =    3.146e-01         Concentration
offset  (fitted)   =    1.441e-01         Offset
alpha  (fixed )   =    1.000e+00         Anomalous diffusion exponent (1=normal diffusion)

Goodness of fit:
2012-10-25-run_001.timetag.acorr-0
Chi^2 = 3.26+02
Chi^2 / DOF = 2.13


Here, we have set the offset parameter of the model with an initial value (0.5) and allowed the parameter to be varied by the fit. We find that the fit now fits (only ever so slightly) better,

Occasionally one might want to fit several curves to a model sharing some set of parameters. For example, in an FCS experiment one might take several datasets on the same instrument expecting some parameters (e.g. the aspect ratio of the observation volume) to remain constant over the course of the day. In this case, one can fit these datasets collectively, sharing the common parameters. fcs-fit enables this sort of fit by using

Something went wrong with that request. Please try again.