Measurement Classes

The Time Tagger library includes several classes that implement various measurements. All measurements are derived from a base class called ‘IteratorBase’ that is described further down. As the name suggests, it uses the iterator programming concept.

All measurements provide a small number of methods to start and stop the execution and to access the accumulated data. In a typical application, the following steps are performed (see example):

  1. Create an instance of a measurement

  2. Wait for some time

  3. Retrieve the data accumulated by the measurement by calling a .getData() method.

Available measurement classes

Note

In MATLAB, the Measurement names have common prefix TT*. For example: Correlation is named as TTCorrelation. This prevents possible name collisions with existing MATLAB or user functions.

Correlation

Auto- and Cross-correlation measurement.

CountBetweenMarkers

Counts tags on one channel within bins which are determined by triggers on one or two other channels. Uses a static buffer output. Use this to implement a gated counter, a counter synchronized to external signals, etc.

Counter

Counts the clicks on one or more channels with a fixed bin width and a circular buffer output.

Countrate

Average tag rate on one or more channels.

Flim

Fluorescence lifetime imaging.

IteratorBase

Base class for implementing custom measurements (only C++ and Python).

Histogram

A simple histogram of time differences. This can be used to measure lifetime, for example.

Histogram2D

A 2-dimensional histogram of time differences. This can be used in measurements similar to 2D NRM spectroscopy.

HistogramLogBins

Accumulates time differences into a histogram with logarithmic increasing bin sizes.

Scope

Detects the rising and falling edges on a channel to visualize the incoming signals similar to an ultrafast logic analyzer.

StartStop

Accumulates a histogram of time differences between pairs of tags on two channels. Only the first stop tag after a start tag is considered. Subsequent stop tags are discarded. The histogram length is unlimited. Bins and counts are stored in an array of tuples.

TimeDifferences

Accumulates the time differences between tags on two channels in one or more histograms. The sweeping through of histograms is optionally controlled by one or two additional triggers.

TimeDifferencesND

A multidimensional implementation of the TimeDifferences measurement for asynchronous next histogram triggers.

SynchronizedMeasurements

Helper class that allows synchronization of the measurement classes.

Dump

Deprecated - please use FileWriter instead. Dump measurement writes all time-tags into a file.

TimeTagStream

This class provides you with access to the time-tag stream and allows you to implement your own on-the-fly processing. See Raw Time-Tag-Stream access to get on overview about the possibilities for the raw time-tag-stream access.

FileWriter

This class writes time-tags into a file with a lossless compression and is replaces the Dump class.

FileReader

Allows you to read time-tags from a file written by the FileWriter.

Common methods

clear()

Discards accumulated measurement data, initializes the data buffer with zero values, and resets the state to the initial state.

start()

Starts or continues data acquisition. This method is implicitly called when a measurement object is created.

startFor(duration[, clear=True])

Starts or continues the data acquisition for the given duration (in ps). After the duration time, the method stop() is called and isRunning() will return False. Whether the accumulated data is cleared at the beginning of startFor() is controlled with the second parameter clear, which is True by default.

stop()

After calling this method, the measurement will stop processing incoming tags. Use start() or startFor() to continue or restart the measurement.

isRunning()

Returns True if the measurement is collecting the data. This method will returns False if the measurement was stopped manually by calling stop() or automatically after calling startFor() and the duration has passed.

Note

All measurements start accumulating data immediately after their creation.

Returns

True/False

Return type

bool

waitUntilFinished(timeout)

Blocks the execution until the measurement has finished. Can be used with startFor().

Parameters

timeout (int) – optional, default: -1. timeout in milliseconds. Negative means no timeout, zero returns immediately.

Returns

True if the measurement has finished, false on timeout

Return type

bool

getCaptureDuration()

Total capture duration since the measurement creation or last call to clear().

Returns

Capture duration in ps

Return type

int

Event counting

Countrate

../_images/Countrate.svg

Measures the average count rate on one or more channels. Specifically, it determines the counts per second on the specified channels starting from the very first tag arriving after the instantiation or last call to clear() of the measurement.

class Countrate(tagger, channels)
Parameters
  • tagger (TimeTagger) – time tagger object instance

  • channels (list[int]) – channels for which the average count rate is measured

See all common methods

getData()
Returns

Average count rate in counts per second.

Return type

1D_array[float]

getCountsTotal()
Returns

The total number of events since the instantiation of this object.

Return type

1D_array[int]

Counter

../_images/Counter.svg

Time trace of the count rate on one or more channels. Specifically, this measurement repeatedly counts tags on one or more channels within a time interval binwidth and stores the results in a two-dimensional array of size ‘number of channels’ by ‘n_values’. The array is treated as a circular buffer, which means all values in the array are shifted by one position when a new value is generated. The last entry in the array is always the most recent value.

class Counter(tagger, channels, binwidth, n_values)
Parameters
  • tagger (TimeTagger) – time tagger object

  • channels (list[int]) – channels used for counting tags

  • binwidth (int) – bin width in ps

  • n_values (int) – number of bins (data buffer size)

See all common methods

getData()
Returns

An array of size ‘number of channels’ by n_values containing the current values of the circular buffer (counts in each bin).

Return type

2D_array[int]

getIndex()
Returns

A vector of size n_values containing the time bins in ps.

Return type

1D_array[int]

CountBetweenMarkers

../_images/CountBetweenMarkers.svg

Counts events on a single channel within the time indicated by a “start” and “stop” signals. The bin edges between which counts are accumulated are determined by one or more hardware triggers. Specifically, the measurement records data into a vector of length n_values (initially filled with zeros). It waits for tags on the begin_channel. When a tag is detected on the begin_channel it starts counting tags on the click_channel. When the next tag is detected on the begin_channel it stores the current counter value as the next entry in the data vector, resets the counter to zero and starts accumulating counts again. If an end_channel is specified, the measurement stores the current counter value and resets the counter when a tag is detected on the end_channel rather than the begin_channel. You can use this, e.g., to accumulate counts within a gate by using rising edges on one channel as the begin_channel and falling edges on the same channel as the end_channel. The accumulation time for each value can be accessed via getBinWidths(). The measurement stops when all entries in the data vector are filled.

class CountBetweenMarkers(tagger, click_channel, begin_channel, end_channel, n_values)
Parameters
  • tagger (TimeTagger) – time tagger object

  • click_channel (int) – channel on which clicks are received, gated by begin_channel and end_channel

  • begin_channel (int) – channel that triggers the beginning of counting and stepping to the next value

  • end_channel (int) – channel that triggers the end of counting

  • n_values (int) – number of values stored (data buffer size)

See all common methods

getData()
Returns

Array of size n_values containing the acquired counter values.

Return type

1D_array[int]

getIndex()
Returns

Vector of size n_values containing the time in ps of each start click in respect to the very first start click.

Return type

1D_array[int]

getBinWidths()
Returns

Vector of size n_values containing the time differences of ‘start -> (next start or stop)’ for the acquired counter values.

Return type

1D_array[int]

ready()
Returns

True when the entire array is filled.

Return type

bool

Time histograms

This section describes various measurements that calculate time differences between events and accumulate the results into a histogram.

StartStop

../_images/StartStop.svg

A simple start-stop measurement. This class performs a start-stop measurement between two channels and stores the time differences in a histogram. The histogram resolution is specified beforehand (binwidth) but the histogram range (number of bins) is unlimited. It is adapted to the largest time difference that was detected. Thus, all pairs of subsequent clicks are registered. Only non-empty bins are recorded.

class StartStop(tagger, click_channel, start_channel, binwidth)
Parameters
  • tagger (TimeTagger) – time tagger object instance

  • click_channel (int) – channel on which stop clicks are received

  • start_channel (int) – channel on which start clicks are received

  • binwidth (int) – bin width in ps

See all common methods

getData()
Returns

An array of tuples (array of shape Nx2) containing the times (in ps) and counts of each bin. Only non-empty bins are returned.

Return type

2D_array[int]

Histogram

../_images/Histogram.svg

Accumulate time differences into a histogram. This is a simple multiple start, multiple stop measurement. This is a special case of the more general TimeDifferences measurement. Specifically, the measurement waits for clicks on the start_channel, and for each start click, it measures the time difference between the start clicks and all subsequent clicks on the click_channel and stores them in a histogram. The histogram range and resolution are specified by the number of bins and the bin width specified in ps. Clicks that fall outside the histogram range are ignored. Data accumulation is performed independently for all start clicks. This type of measurement is frequently referred to as a ‘multiple start, multiple stop’ measurement and corresponds to a full auto- or cross-correlation measurement.

class Histogram(tagger, click_channel, start_channel, binwidth, n_bins)
Parameters
  • tagger (TimeTagger) – time tagger object instance

  • click_channel (int) – channel on which clicks are received

  • start_channel (int) – channel on which start clicks are received

  • binwidth (int) – bin width in ps

  • n_bins (int) – the number of bins in the histogram

See all common methods

getData()
Returns

A one-dimensional array of size n_bins containing the histogram.

Return type

1D_array[int]

getIndex()
Returns

A vector of size n_bins containing the time bins in ps.

Return type

1D_array[int]

HistogramLogBins

The HistogramLogBins measurement is similar to Histogram but the bin widths are spaced logarithmically.

../_images/HistogramLogBins.svg
class HistogramLogBins
Parameters
  • tagger (TimeTagger) – time tagger object instance

  • click_channel (int) – channel on which clicks are received

  • start_channel (int) – channel on which start clicks are received

  • exp_start (float) – exponent 10^exp_start in seconds where the very first bin begins

  • exp_stop (float) – exponent 10^exp_stop in seconds where the very last bin ends

  • n_bins (int) – the number of bins in the histogram

Note

After initializing the measurement (or after an overflow) no data is accumulated in the histogram until the full histogram duration has passed to ensure a balanced count accumulation over the full histogram.

See all common methods

getData()
Returns

A one-dimensional array of size n_bins containing the histogram.

Return type

1D_array[int]

getDataNormalizedCountsPerPs()
Returns

The counts normalized by the binwidth of each bin.

Return type

1D_array[float]

getDataNormalizedG2()

The counts normalized by the binwidth of each bin and the average count rate. This matches the implementation of Correlation.getDataNormalized()

g^{(2)}(\tau) = \frac{\Delta{t}}{binwidth(\tau) \cdot N_1 \cdot N_2} \cdot histogram(\tau)

where \Delta{t} is the capture duration, N_1 and N_2 are number of events in each channel.

Returns

The counts normalized by the binwidth of each bin and the average count rate.

Return type

1D_array[float]

getBinEdges()
Returns

A vector of size n_bins+1 containing the bin edges in picoseconds.

Return type

1D_array[int]

Histogram2D

../_images/Histogram2D.svg

This measurement is a 2-dimensional version of the Histogram measurement. The measurement accumulates two-dimensional histogram where stop signals from two separate channels define the bin coordinate. For instance, this kind of measurement is similar to that of typical 2D NMR spectroscopy. The data within the histogram is acquired via a single-start, single-stop analysis for each axis.

class Histogram2D(tagger, start_channel, stop_channel_1, stop_channel_2, binwidth_1, binwidth_2, n_bins_1, n_bins_2)
Parameters
  • tagger (TimeTagger) – time tagger object

  • start_channel (int) – channel on which start clicks are received

  • stop_channel_1 (int) – channel on which stop clicks for the time axis 1 are received

  • stop_channel_2 (int) – channel on which stop clicks for the time axis 2 are received

  • binwidth_1 (int) – bin width in ps for the time axis 1

  • binwidth_2 (int) – bin width in ps for the time axis 2

  • n_bins_1 (int) – the number of bins along the time axis 1

  • n_bins_2 (int) – the number of bins along the time axis 2

See all common methods

getData()
Returns

A two-dimensional array of size n_bins_1 by n_bins_2 containing the 2D histogram.

Return type

2D_array[int]

getIndex()

Returns a 3D array containing two coordinate matrices (meshgrid) for time bins in ps for the time axes 1 and 2. For details on meshgrid please take a look at the respective documentation either for Matlab or Python NumPy.

Returns

A three-dimensional array of size n_bins_1 x n_bins_2 x 2

Return type

3D_array[int]

getIndex_1()
Returns

A vector of size n_bins_1 containing the bin locations in ps for the time axis 1.

Return type

1D_array[int]

getIndex_2()
Returns

A vector of size n_bins_2 containing the bin locations in ps for the time axis 2.

Return type

1D_array[int]

Correlation

../_images/Correlation.svg

Accumulates time differences between clicks on two channels into a histogram, where all ticks are considered both as “start” and “stop” clicks and both positive and negative time differences are considered.

class Correlation(tagger, channel_1, channel_2, binwidth, n_bins)
Parameters
  • tagger (TimeTagger) – time tagger object

  • channel_1 (int) – channel on which (stop) clicks are received

  • channel_2 (int) – channel on which reference clicks (start) are received (when left empty or set to CHANNEL_UNUSED -> an auto-correlation measurement is performed, which is the same as setting channel_1 = channel_2)

  • binwidth (int) – bin width in ps

  • n_bins (int) – the number of bins in the resulting histogram

See all common methods

getData()
Returns

A one-dimensional array of size n_bins containing the histogram.

Return type

1D_array[int]

getDataNormalized()

Return the data normalized as:

g^{(2)}(\tau) = \frac{\Delta{t}}{binwidth \cdot N_1 \cdot N_2} \cdot histogram(\tau)

where \Delta{t} is the capture duration, N_1 and N_2 are number of events in each channel.

Returns

Data normalized by the binwidth and the average count rate.

Return type

1D_array[float]

getIndex()
Returns

A vector of size n_bins containing the time bins in ps.

Return type

1D_array[int]

TimeDifferences

../_images/TimeDifferences.svg

A multidimensional histogram measurement with the option up to include three additional channels that control how to step through the indices of the histogram array. This is a very powerful and generic measurement. You can use it to record cross-correlation, lifetime measurements, fluorescence lifetime imaging and many more measurements based on pulsed excitation. Specifically, the measurement waits for a tag on the start_channel, then measures the time difference between the start tag and all subsequent tags on the click_channel and stores them in a histogram. If no start_channel is specified, the click_channel is used as start_channel corresponding to an auto-correlation measurement. The histogram has a number n_bins of bins of bin width binwidth. Clicks that fall outside the histogram range are discarded. Data accumulation is performed independently for all start tags. This type of measurement is frequently referred to as ‘multiple start, multiple stop’ measurement and corresponds to a full auto- or cross-correlation measurement.

The data obtained from subsequent start tags can be accumulated into the same histogram (one-dimensional measurement) or into different histograms (two-dimensional measurement). In this way, you can perform more general two-dimensional time-difference measurements. The parameter n_histograms specifies the number of histograms. After each tag on the next_channel, the histogram index is incremented by one and reset to zero after reaching the last valid index. The measurement starts with the first tag on the next_channel.

You can also provide a synchronization trigger that resets the histogram index by specifying a sync_channel. The measurement starts when a tag on the sync_channel arrives with a subsequent tag on next_channel. When a rollover occurs, the accumulation is stopped until the next sync and subsequent next signal. A sync signal before a rollover will stop the accumulation, reset the histogram index and a subsequent signal on the next_channel starts the accumulation again.

Typically, you will run the measurement indefinitely until stopped by the user. However, it is also possible to specify the maximum number of rollovers of the histogram index. In this case, the measurement stops when the number of rollovers has reached the specified value. This means that for both a one-dimensional and for a two-dimensional measurement, it will measure until the measurement went through the specified number of rollovers / sync tags.

class TimeDifferences(tagger, click_channel, start_channel, next_channel, sync_channel, binwidth, n_bins, n_histograms)
Parameters
  • tagger (TimeTagger) – time tagger object instance

  • click_channel (int) – channel on which stop clicks are received

  • start_channel (int) – channel that sets start times relative to which clicks on the click channel are measured

  • next_channel (int) – channel that increments the histogram index

  • sync_channel (int) – channel that resets the histogram index to zero

  • binwidth (int) – binwidth in picoseconds

  • n_bins (int) – number of bins in each histogram

  • n_histograms (int) – number of histograms

See all common methods

getData()
Returns

A two-dimensional array of size n_bins by n_histograms containing the histograms.

Return type

2D_array[int]

getIndex()
Returns

A vector of size n_bins containing the time bins in ps.

Return type

1D_array[int]

setMaxCounts()

Sets the number of rollovers at which the measurement stops integrating. To integrate infinitely, set the value to 0, which is the default value.

getCounts()
Returns

The number of rollovers (histogram index resets).

Return type

int

ready()
Returns

True when the required number of rollovers set by setMaxCounts() has been reached.

Return type

bool

Overflow handling

The different ways overflows are handled depend on whether a next_channel and a sync_channel is defined:

sync_channel and next_channel are both defined

the measurement stops integrating at an overflow and continues with the next signal on the sync_channel

only next_channel is defined

the histogram index is reset at the overflow and the next signal on the next_channel starts the integration again

sync_channel and next_channel are both undefined

the accumulation continues

TimeDifferencesND

../_images/TimeDifferencesND.svg

Accumulates the time differences between clicks on two channels in a multi-dimensional histogram.

This is a multidimensional implementation of the TimeDifferences measurement class. Please read their documentation first.

This measurement class extends the TimeDifferences interface for a multidimensional number of histograms. It captures many multiple start - multiple stop histograms, but with many asynchronous next_channel triggers. After each tag on each next_channel, the histogram index of the associated dimension is incremented by one and reset to zero after reaching the last valid index. The elements of the parameter n_histograms specify the number of histograms per dimension. The accumulation starts when next_channel has been triggered on all dimensions.

You should provide a synchronization trigger by specifying a sync_channel per dimension. It will stop the accumulation when an associated histogram index rollover occurs. A sync event will also stop the accumulation, reset the histogram index of the associated dimension, and a subsequent event on the corresponding next_channel starts the accumulation again. The synchronization is done asynchronous, so an event on the next_channel increases the histogram index even if the accumulation is stopped. The accumulation starts when a tag on the sync_channel arrives with a subsequent tag on next_channel for all dimensions.

Please use TimeTagger.setInputDelay() to adjust the latency of all channels. In general, the order of the provided triggers including maximum jitter should be:

old start trigger –> all sync triggers –> all next triggers –> new start trigger

class TimeDifferencesND(tagger, click_channel, start_channel, next_channels, sync_channels, n_histograms, binwidth, n_bins)
Parameters
  • tagger (TimeTagger) – time tagger object instance

  • click_channel (int) – channel on which stop clicks are received

  • start_channel (int) – channel that sets start times relative to which clicks on the click channel are measured

  • next_channels (list[int]) – vector of channels that increments the histogram index

  • sync_channels (list[int]) – vector of channels that resets the histogram index to zero

  • n_histograms (int) – vector of numbers of histograms per dimension

  • binwidth (int) – width of one histogram bin in ps

  • n_bins (int) – number of bins in each histogram

See all common methods

See methods of TimeDifferences class.

Fluorescence-lifetime imaging (FLIM)

This section describes the Flim realated measurements classes of the Time Tagger API.

Flim

Changed in version 2.7.2.

Note

The Flim (beta) implementation is a not final yet. It has a very advanced functionality, but details are subject to change. Please give us feedback (support@swabianinstruments.com) when you encounter issues or when you have ideas for additional functionality.

../_images/Flim.svg

Fluorescence-lifetime imaging microscopy (FLIM) is an imaging technique for producing an image based on the differences in the exponential decay rate of the fluorescence from a sample.

Fluorescence lifetimes can be determined in the time domain by using a pulsed source. When a population of Fluorophores is excited by an ultrashort or delta-peak pulse of light, the time-resolved fluorescence will decay exponentially.

This measurement implements a line scan in a FLIM image that consists of a sequence of pixels. This could either represent a single line of the image, or - if the image is represented as a single meandering line - this could represent the entire image.

There are two different classes to support the FLIM measurement: Flim and FlimBase. Flim provides a versatile high-level API. FlimBase instead provides the essential functionality with no overhead to perform Flim measurements. FlimBase is based on a callback approach.

Please visit the Python example folder for a reference implementation.

Note

Up to version 2.7.0, the FLIM implementation was very limited and has been rewritten completely with 2.7.2. You can use the following 1 to 1 replacement to get the old FLIM behavior:

# FLIM up to version 2.7.0:
Flim(tagger, click_channel=1, start_channel=2, next_channel=3,
    binwidth=100, n_bins=1000, n_pixels=320*240)

# FLIM 2.7.0 replacement using TimeDifferences
TimeDifferences(tagger, click_channel=1, start_channel=2,
    next_channel=3, sync_channel=CHANNEL_UNUSED,
    binwidth=100, n_bins=1000, n_histograms=320*240)
class Flim(tagger, start_channel, click_channel, pixel_begin_channel, n_pixels, n_bins, binwidth[, pixel_end_channel=CHANNEL_UNUSED, frame_begin_channel=CHANNEL_UNUSED, finish_after_outputframe=0, n_frame_average=1, pre_initialize=True])

High-Level class for implementing FLIM measurements. The Flim class includes buffering of images and several analysis methods.

The methods are split into different groups.

The getCurrent... references the active frame.

The getReady... references the last full frame acquired.

The getSummed... operates on all frames which have been captured so far including or excluding the current active frame via the optional parameter only_ready_frames.

The get...Ex returns instead of an array, a FlimFrameInfo which contains more information than only the raw array.

The class provides an frameReady() callback, which can be used to analyze the data when a frame is completed.

Parameters
  • tagger (TimeTagger) – time tagger object instance

  • start_channel (int) – channel on which clicks are received for the time differences histogramming

  • click_channel (int) – start_channel channel on which start clicks are received for the time differences histogramming

  • pixel_begin_channel (int) – start of a pixel (histogram)

  • n_pixels (int) – number of pixels (histograms) of one frame

  • n_bins (int) – number of histogram bins for each pixel

  • binwidth (int) – bin size in picoseconds

  • pixel_end_channel (int) – end marker of a pixel - incoming clicks on the click_channel will be ignored afterward. (optional)

  • frame_begin_channel (int) – start the frame, or reset the pixel index. (optional)

  • finish_after_outputframe (int) – sets the number of frames stored within the measurement class. After reaching the number, the measurement will stop. If the number is 0, one frame is stored and the measurement runs continuously. (optional, default: 0)

  • n_frame_average (int) – average multiple input frames into one output frame, (optional, default: 1)

  • pre_initialize (bool) – initializes the measurement on constructing. (optional)

See all common methods

getCurrentFrame()
Returns

The histograms for all pixels of the currently active frame.

Return type

3D_array[int]

getCurrentFrameEx()
Returns

The currently active frame.

Return type

FlimFrameInfo

getCurrentFrameIntensity()
Returns

The intensities of all pixels of the currently active frame. The pixel intensity is defined by the number of counts acquired within the pixel divided by the respective integration time.

Return type

2D_array[float]

getFramesAcquired()
Returns

The number of frames that have been completed so far, since the creation / last clear of the object.

Return type

int

getIndex()
Returns

A vector of size n_bins containing the time bins in ps.

Return type

1D_array[int]

getReadyFrame([index =-1])
Parameters

index (int) – Index of the frame to be obtained. If -1, the last frame which has been completed is returned. (optional)

Returns

The histograms for all pixels according to the frame index given. If the index is -1, it will return the last frame, which has been completed. When stop_after_outputframe is 0, the index value must be -1. If index >= stop_after_outputframe, it will throw an error.

Return type

3D_array[int]

getReadyFrameEx([index =-1])
Parameters

index (int) – Index of the frame to be obtained. If -1, the last frame which has been completed is returned. (optional)

Returns

The frame according to the index given. If the index is -1, it will return the last completed frame. When stop_after_outputframe is 0, index must be -1. If index >= stop_after_outputframe, it will throw an error.

Return type

FlimFrameInfo

getReadyFrameIntensity([index =-1])
Parameters

index (int) – Index of the frame to be obtained. If -1, the last frame which has been completed is returned. (optional)

Returns

The intensities according to the frame index given. If the index is -1, it will return the intensity of the last frame, which has been completed. When stop_after_outputframe is 0, the index value must be -1. If index >= stop_after_outputframe, it will throw an error. The pixel intensity is defined by the number of counts acquired within the pixel divided by the respective integration time.

Return type

2D_array[float]

getSummedFrames([only_ready_frames=True, clear_summed=False])
Parameters
  • only_ready_frames – If true, only the finished frames are added. On false, the currently active frame is aggregated. (optional)

  • clear_summed – If true, the summed frames memory will be cleared. (optional)

Returns

The histograms for all pixels. The counts within the histograms are integrated since the start or the last clear of the measurement.

Return type

2D_array[int]

getSummedFramesEx([only_ready_frames=True, clear_summed=False])
Parameters
  • only_ready_frames (bool) – If true, only the finished frames are added. On false, the currently active frame is aggregated. (optional)

  • clear_summed (bool) – If true, the summed frames memory will be cleared. (optional)

Returns

A FlimFrameInfo that represents the sum of all acquired frames.

Return type

FlimFrameInfo

getSummedFramesIntensity([only_ready_frames=True, clear_summed=False])
Parameters
  • only_ready_frames (bool) – If true, only the finished frames are added. On false, the currently active frame is aggregated. (optional)

  • clear_summed (bool) – If true, the summed frames memory will be cleared. (optional)

Returns

The intensities of all pixels summed over all acquired frames. The pixel intensity is the number of counts within the pixel divided by the integration time.

Return type

2D_array[float]

isAcquiring()
Returns

A boolean which tells the user if the class is still acquiring data. It can only reach the false state for stop_after_outputframe > 0. This should differ from isRunning() as once rendering is done, it can’t be started again.

Return type

bool

frameReady(frame_number, data, pixel_begin_times, pixel_end_times, frame_begin_time, frame_end_time)
Parameters
  • frame_number (int) – current Frame number

  • data (list[int]) – raw histogram data for all pixels

  • pixel_begin_times (list[int]) – start time for each pixel

  • pixel_end_times (list[int]) – end time for each pixel

  • frame_begin_time (int) – start time of the frame

  • frame_end_time (int) – end time of the frame

The method is called when a frame is completed. Compared to on_frame_end(), it provides various related data when invoked.

on_frame_end()

Virtual function which can be overwritten in C++. The method is called when a frame is completed.

FlimFrameInfo

This is a simple class that contains FLIM frame data and provides convenience accessor methods.

Note

Objects of this class are returned by the methods of the FLIM classes. Normally user will not construct FlimFrameInfo objects themselves.

class FlimFrameInfo
pixels

number of pixels of the frame

bins

number of bins of each histogram

frame_number

current frame number

pixel_count

current pixel position

getFrameNumber()
Returns

The frame number, starting from 0 for the very first frame acquired. If the index is -1, it is an invalid frame which is returned on error.

Return type

int

isValid()
Returns

A boolean which tells if this frame is valid or not. Invalid frames are possible on errors, such as asking for the last completed frame when no frame has been completed so far.

Return type

bool

getPixelPosition()
Returns

A value which tells how many pixels were processed for this frame.

Return type

int

getHistograms()
Returns

All histograms of the frame.

Return type

3D_array[int]

getIntensities()
Returns

The summed counts of each histogram divided by the integration time.

Return type

2D_array[float]

getSummedCounts()
Returns

The summed counts of each histogram.

Return type

2D_array[int]

getPixelBegins()
Returns

An array of the start timestamps of each pixel.

Return type

2D_array[int]

getPixelEnds()
Returns

An array of the end timestamps of each pixel.

Return type

2D_array[int]

FlimBase

The FlimBase provides only the most essential functionality for FLIM tasks. The benefit from the reduced functionality is that it is very memory and CPU efficient. The class provides the frameReady() callback, which must be used to analyze the data.

class FlimBase(tagger, start_channel, click_channel, pixel_begin_channel, n_pixels, n_bins, binwidth[, pixel_end_channel=CHANNEL_UNUSED, frame_begin_channel=CHANNEL_UNUSED, finish_after_outputframe=0, n_frame_average=1, pre_initialize=True])
Parameters
  • tagger (TimeTagger) – time tagger object instance

  • start_channel (int) – channel on which clicks are received for the time differences histogramming

  • click_channel (int) – start_channel channel on which start clicks are received for the time differences histogramming

  • pixel_begin_channel (int) – start of a pixel (histogram)

  • n_pixels (int) – number of pixels (histograms) of one frame

  • n_bins (int) – number of histogram bins for each pixel

  • binwidth (int) – bin size in picoseconds

  • pixel_end_channel (int) – end marker of a pixel - incoming clicks on the click_channel will be ignored afterward. (optional, default: CHANNEL_UNUSED)

  • frame_begin_channel (int) – start the frame, or reset the pixel index. (optional, default: CHANNEL_UNUSED)

  • finish_after_outputframe (int) – sets the number of frames stored within the measurement class. After reaching the number, the measurement will stop. If the number is 0 , one frame is stored and the measurement runs continuously. (optional, default: 0)

  • n_frame_average (int) – average multiple input frames into one output frame. (optional, default: 1)

  • pre_initialize (bool) – initializes the measurement on constructing. (optional, default: True)

See all common methods

isAcquiring()
Returns

A boolean which tells the user if the class is still acquiring data. It can only reach the false state for stop_after_outputframe > 0. This should differ from isRunning() as once rendering is done, it can’t be started again.

Return type

bool

frameReady(frame_number, data, pixel_begin_times, pixel_end_times, frame_begin_time, frame_end_time)
Parameters
  • frame_number (int) – current Frame number

  • data (2D_array[int]) – 2D array containing the raw histogram data for all pixels

  • pixel_begin_times (list[int]) – start time for each pixel

  • pixel_end_times (list[int]) – end time for each pixel

  • frame_begin_time (int) – start time of the frame

  • frame_end_time (int) – end time of the frame

The method is called when a frame is completed. Compared to on_frame_end(), it provides various related data when invoked.

on_frame_end()

Virtual function which can be overwritten in C++. The method is called when a frame is completed.

Time-tag-streaming

Measurement classes described in this section provide direct access to the time tag stream with minimal or no pre-processing.

Time tag format

The time tag contain essential information about the detected event and have the following format:

Size

Type

Description

8 bit

enum OverflowType

overflow type

8 bit

reserved

16 bit

uint16

number of missed events

32 bit

int32

channel number

64 bit

int64

time in ps from device start-up

class OverflowType

This enumeration describes the overflow condition.

TimeTag = 0

A normal event from any input channel, no overflow.

Error = 1

An error in the internal data processing, e.g. on plugging the external clock. This invalidates the global time.

OverflowBegin = 2

Marks the beginning of an interval with incomplete data because of too high data rates.

OverflowEnd = 3

Marks the end of the interval. All events, which were lost in this interval, have been handled

MissedEvents = 4

This virtual event signals the number of lost events per channel within an overflow interval. Might be sent repeatedly for larger number of lost events.

TimeTagStream

Access the time tag stream. A buffer of the size max_tags is filled with the incoming time tags. As soon as getData() is called the current buffer is returned and incoming tags are stored in a new, empty buffer.

class TimeTagStream(tagger, n_max_events, channels)
Parameters
  • tagger (TimeTagger) – time tagger object instance

  • n_max_events (int) – buffer size for storing time tags

  • channels (list[int]) – which are dumped to the file (when empty or not passed all active channels are dumped)

See all common methods

getData()
Returns

Returns a TimeTagStreamBuffer object and clears the internal buffer of the TimeTagStream measurement. Clearing the internal buffer on each call to getData() guarantees that consecutive calls to this method will return every time-tag only once, also with no data loss.

Return type

TimeTagStreamBuffer

class TimeTagStreamBuffer
getTimestamps()

Returns an array of timestamps.

Returns

Event timestamps in picoseconds for all chosen channels.

Return type

list[int]

getChannels()

Returns an array of channel numbers for every timestamp.

Returns

Channel number for each detected event.

Return type

list[int]

getOverflows()

Deprecated since version 2.5.0.

Returns an array of overflow flags for every timestamp.

getEventTypes()

Returns an array of event type for every timestamp. See, Time tag format.

Returns

Event type value for each detected event.

Return type

1D_array(OverflowType)

getMissedEvents()

Returns an array of missed event counts during an overflow situation.

Returns

Missed events value for each detected event.

Return type

1D_array[int]

hasOverflows()

Returns True if overflow was detected in any of the tags received.

Returns

True/False

Return type

bool

FileWriter

Writes the time-tag-stream into a file in a binary format with a lossless compression. The estimated file size requirements are 2-4 bytes per event under typical conditions. The files produced by this measurement are significantly smaller than those created with the Dump class. The files created with FileWriter measurement can be read using FileReader or loaded into the Virtual Time Tagger.

The FileWriter is able to split the data into a separate file seamlessly when the file size reaches a maximal size. For the file splitting to work properly, the filename specified by the user will be extended with a suffix containing sequential counter, so the filenames will look like in the following example

fw = FileWriter(tagger, 'filename.ttbin', [1,2,3]) # Store tags from channels 1,2,3

# When splitting occurs the files with following names will be created
#    filename.ttbin     # the sequence header file with no data blocks
#    filename.1.ttbin   # the first file with data blocks
#    filename.2.ttbin
#    filename.3.ttbin
#    ...

In addition, the FileWriter will query and store the configuration of the Time Tagger in the same format as returned by the TimeTagger.getConfiguration() method. The configuration is always written into every file.

class FileWriter(tagger, filename, channels)
Parameters
  • tagger (TimeTagger) – time tagger object instance

  • filename (str) – name of the file to store to

  • channels (list[int]) – non-empty list of real or virtual channels

Class constructor. As with all other measurements, the data recording starts immediately after the class instantiation.

Note

Compared to the Dump measurement, the FileWriter requires explicit specification of the channels. If you want to store timetags from all input channels, you can query the list of all input channels with TimeTagger.getChannelList().

See all common methods

split([new_filename=""])

Close the current file and create a new one. If the new_filename is provided, the data writing will continue into the file with the new filename and the sequence counter will be reset to zero.

You can force the file splitting when you call this method without parameter or when the new_filename is an empty string.

Parameters

new_filename (str) – filename of the new file.

setMaxFileSize(max_file_size)

Set the maximum file size on disk. When this size is exceeded a new file will be automatically created to continue recording. The actual file size might be larger by one block. (default: ~1 GByte)

getMaxFileSize()
Returns

The maximal file size. See also FileWriter.setMaxFileSize().

Return type

int

getTotalEvents()
Returns

The total number of events written into the file(s).

Return type

int

getTotalSize()
Returns

The total number of bytes written into the file(s).

Return type

int

FileReader

This measurement allows you to read data files store with FileReader. The FileReader reads a data block of the specified size into a TimeTagStreamBuffer object and returns this object. The returned data object is exactly the same as returned by the TimeTagStream measurement and allows you to create a custom data processing algorithms that will work both, for reading from a file and for the on-the-fly processing.

The FileReader will automatically recognize if the files were split and read them too one by one.

Example:

# Lets assume we have following files created with the FileWriter
#  measurement.ttbin     # sequence header file with no data blocks
#  measurement.1.ttbin   # the first file with data blocks
#  measurement.2.ttbin
#  measurement.3.ttbin
#  measurement.4.ttbin
#  another_meas.ttbin
#  another_meas.1.ttbin

# Read all files in the sequence 'measurement'
fr = FileReader("measurement.ttbin")

# Read only the first data file
fr = FileReader("measurement.1.ttbin")

# Read only the first two files
fr = FileReader(["measurement.1.ttbin", "measurement.2.ttbin"])

# Read the sequence 'measurement' and then the sequence 'another_meas'
fr = FileReader(["measurement.ttbin", "another_meas.ttbin"])
class FileReader(filenames)

This is the class constructor. The FileReader automatically continues to read files that were split by the FileWriter.

Parameters

filenames (list[str]) – filename(s) of the files to read.

getData(size_t n_events)

Reads the next n_events and returns the buffer object with the specified number of timetags. The FileReader stores the current location in the data file and guarantees that every timetag is returned exactly once. If less than n_elements are returned, the reader has reached the end of the last file in the file-list filenames. To check if more data is available for reading, it is more convenient to use hasData().

Parameters

n_events (int) – Number of timetags to read from the file.

Returns

A buffer of size n_events.

Return type

TimeTagStreamBuffer

hasData()
Returns

True if more data is available for reading, False if all data has been read from all the files specified in the class constructor.

Return type

bool

getConfiguration()
Returns

A JSON formatted string that contains the Time Tagger configuration at the time of file creation.

Return type

str

Dump

Deprecated - please use FileWriter instead.

Writes the timetag stream into a file in a binary format. See also, Time tag format.

Please visit the programming examples provided in the installation folder of how to dump and load data.

class Dump(tagger, filename, max_tags, channels)
Parameters
  • tagger (TimeTagger) – time tagger object instance

  • filename (str) – name of the file to dump to

  • max_tags (int) – stop after this number of tags has been dumped. Negative values will dump forever

  • channels (list[int]) – list of real or virtual channels which are dumped to the file (when empty or not passed all active channels are dumped)

clear()

Delete current data in the file and restart data storage.

stop()

Stops data recording and closes data file.

Scope

../_images/Scope.svg

The Scope class allows to visualize time tags for rising and falling edges in a time trace diagram similarly to an ultrafast logic analyzer. The trace recording is synchronized to a trigger signal which can be any physical or virtual channel. However, only physical channels can be specified to the event_channels parameter. Additionally, one has to specify the time window_size which is the timetrace duration to be recorded, the number of traces to be recorded and the maximum number of events to be detected. If n_traces < 1 then retriggering will occur infinitely, which is similar to the “normal” mode of an oscilloscope.

Note

Scope class implicitly enables the detection of positive and negative edges for every physical channel specified in event_channels. This accordingly doubles the data rate requirement per input.

class Scope(tagger, event_channels=[], trigger_channel, window_size, n_traces, n_max_events)
Parameters
  • tagger (TimeTagger) – TimeTagger object

  • event_channels (list[int]) – List of channels

  • trigger_channel (int) – Channel number of the trigger signal

  • window_size (int) – Time window in picoseconds

  • n_traces (int) – Number of trigger events to be detected

  • n_max_events (int) – Max number of events to be detected

See all common methods

getData()

Returns a tuple of the size equal to the number of event_channels, where each element is a tuple of Event.

Returns

Event list for each channel.

Return type

tuple[tuple[Event]]

class Event

Pair of the timestamp and the new state.

time
Type

int

state
Type

State

class State

Current input state. Can be unknown because no edge has been detected on the given channel after initialization or an overflow.

UNKNOWN
HIGH
LOW

Helper classes

SynchronizedMeasurements

The SynchronizedMeasurements class allows for synchronizing multiple measurement classes in a way that ensures all these measurements to start, stop simultaneously and operate on exactly the same time tags. You can pass a Time Tagger proxy-object returned by SynchronizedMeasurements.getTagger() to every measurement you create. This will simultaneously disable their autostart and register for synchronization.

class SynchronizedMeasurements(tagger)
Parameters

tagger (TimeTagger) – TimeTagger object

registerMeasurement(measurement)

Registers the measurement object into a pool of the synchronized measurements.

Note

Registration of the measurement classes with this method does not synchronize them. In order to start/stop/clear these measurements synchronously, call these functions on the SynchronizedMeasurements object after registering the measurement objects, which should be synchronized.

Parameters

measurement – Any measurement (IteratorBase) object.

unregisterMeasurement(measurement)

Unregisters the measurement object out of the pool of the synchronized measurements.

Note

This method does nothing if the provided measurement is not currently registered.

Parameters

measurement – Any measurement (IteratorBase) object.

start()

Calls start() for every registered measurement in a synchronized way.

startFor(duration[, clear=True])

Calls startFor() for every registered measurement in a synchronized way.

stop()

Calls stop() for every registered measurement in a synchronized way.

clear()

Calls clear() for every registered measurement in a synchronized way.

isRunning()

Calls isRunning() for every registered measurement and returns true if any measurement is running.

getTagger()

Returns a proxy tagger object which can be passed to the constructor of a measurement class to register the measurements at initialization to the synchronized measurement object. Those measurements will not start automatically.

Note

The proxy tagger object returned by getTagger() is not identical with the TimeTagger object created by createTimeTagger(). You can create synchronized measurements with the proxy object the following way:

tagger = TimeTagger.createTimeTagger()
syncMeas = TimeTagger.SynchronizedMeasurements(tagger)
taggerSync = syncMeas.getTagger()
counter = TimeTagger.Counter(taggerSync, [1, 2])
countrate = TimeTagger.Countrate(taggerSync, [3, 4])

Passing tagger as a constructor parameter would lead to the not synchronized behavior.

Custom Measurements

The class CustomMeasurement allows you to access the raw time tag stream with very little overhead. By inheriting from CustomMeasurement, you can implement your fully customized measurement class. The CustomMeasurement.process() method of this class will be invoked as soon as new data is available. Note that this functionality is only available for C++, C# and Python. You find examples of how to use the CustomMeasurement in your examples folder.

class CustomMeasurement(tagger)
Parameters

tagger (TimeTagger) – TimeTagger object

The constructor of the CustomMeasurement class itself takes only the parameter tagger. When you sub-class your own measurement, you can add to your constructor any parameters that are necessary for your measurement. You can find detailed examples in your example folder.

process(incoming_tags, begin_time, end_time)
Parameters
  • incoming_tags – Tag[][struct{type, missed_events, channel, time}], the chunk of time-tags to be processed in this call of process(). This is an external reference that is shared with other measurements and might be overwritten for the next call. So if you need to store tags, create a copy.

  • begin_time (int) – The begin time of the data chunk.

  • end_time (int) – The end time of the data chunk

Override the process() method to include your data processing. The method will be called by the Time Tagger backend when a new chunk of time-tags is available. You are free to execute any code you like, but be aware that this is the critical part when it comes to performance. In Python, it is advisable to use Numpy arrays for calculation or even pre-compiled code with Numba if an explicit iteration of the tags is necessary. Check the examples in your examples folder carefully on how to design the process() method.

Note

In Python, the incoming_tags are a structured Numpy array. You can access single tags as well as arrays of tag entries directly:

first_tag = incoming_tags[0]
all_timestamps = incoming_tags['time']

See all common methods