#include <Correlator.h>

Public Member Functions
uint64_t	dt ()
	Compute the time difference in macro time units between the first and the last event.

	Correlator (std::shared_ptr< TTTR > tttr=nullptr, std::string method="wahl", int n_bins=17, int n_casc=25, bool make_fine=false)
	Correlator Constructor.

	~Correlator ()=default

void	set_n_casc (int n_casc)
	Set the number of cascades (blocks) of the correlation curve.

CorrelatorCurve *	get_curve ()
	Get the correlation curve.

unsigned int	get_n_casc ()
	Get the number of correlation blocks.

void	set_n_bins (int v)
	Set the number of equally spaced correlation channels per block.

unsigned int	get_n_bins () const
	Get the number of equally spaced correlation channels per block.

void	set_correlation_method (std::string cm)
	Set the correlation method.

std::string	get_correlation_method ()
	Get the name of the used correlation method.

void	set_microtimes (unsigned short tac_1, int n_tac_1, unsigned short tac_2, int n_tac_2, unsigned int number_of_microtime_channels)
	Add microtime information to the event stream.

void	set_macrotimes (unsigned long long t1, int n_t1, unsigned long long t2, int n_t2)
	Add macrotimes information to the event stream.

std::pair< std::vector< unsigned long long >, std::vector< unsigned long long > >	get_macrotimes ()
	Get event times of the first and second correlation channel.

void	set_events (unsigned long long t1, int n_t1, double weight_ch1, int n_weights_ch1, unsigned long long t2, int n_t2, double weight_ch2, int n_weights_ch2)
	Set time events and weights for the first and second correlation channels.

void	set_weights (double weight_ch1, int n_weights_ch1, double weight_ch2, int n_weights_ch2)
	Set weights used for correlation.

std::pair< std::vector< double >, std::vector< double > >	get_weights ()
	Get weights used for correlation.

void	get_x_axis (double *output, int n_output)
	Get correlation bins (axis)

void	get_corr_normalized (double *output, int n_output)
	Get the normalized correlation.

void	get_corr (double *output, int n_output)
	Get the (unnormalized) correlation.

void	run ()
	compute the correlation

void	set_tttr (std::shared_ptr< TTTR > tttr_1, std::shared_ptr< TTTR > tttr_2=nullptr, bool make_fine=false)
	Sets the time and the weights using TTTR objects.

std::pair< std::shared_ptr< TTTR >, std::shared_ptr< TTTR > >	get_tttr ()

void	set_filter (const std::map< short, std::vector< double > > &filter, const std::vector< unsigned int > &micro_times_1, const std::vector< signed char > &routing_channels_1, const std::vector< unsigned int > &micro_times_2, const std::vector< signed char > &routing_channels_2)
	Update weights based on a filter map and event information.

Public Attributes
CorrelatorPhotonStream	p1

CorrelatorPhotonStream	p2

CorrelatorCurve	curve

Static Protected Member Functions
static void	ccf_felekyan (const unsigned long long t1, const unsigned long long t2, const double weights1, const double weights2, unsigned int nc, unsigned int nb, unsigned int np1, unsigned int np2, const unsigned long long xdat, double corrl)

static void	normalize_ccf_felekyan (std::vector< unsigned long long > &x_axis, std::vector< double > &corr, std::vector< unsigned long long > &x_axis_normalized, std::vector< double > &corr_normalized, double cr1, double cr2, unsigned int n_bins, unsigned int n_casc, unsigned long long maximum_macro_time)

static void	ccf_wahl (size_t n_casc, size_t n_bins, std::vector< unsigned long long > &taus, std::vector< double > &corr, CorrelatorPhotonStream &p1, CorrelatorPhotonStream &p2)
	Calculates the cross-correlation between two event streams.

static void	normalize_ccf_wahl (double np1, uint64_t dt1, double np2, uint64_t dt2, std::vector< unsigned long long > &x_axis, std::vector< double > &corr, size_t n_bins)
	Normalize computed correlation.

static void	ccf_laurence (std::vector< unsigned long long > &taus, std::vector< double > &corr, CorrelatorPhotonStream &p1, CorrelatorPhotonStream &p2)
	Compute correlation on arbitray correlation axis.

static void	normalize_ccf_laurence (CorrelatorPhotonStream &p1, CorrelatorPhotonStream &p2, std::vector< unsigned long long > &x_axis, std::vector< double > &corr, std::vector< double > &corr_normalized)
	Normalize the correlation.

static void	normalize (Correlator *correlator, CorrelatorCurve &curve)
	Normalize the correlation curve.

Friends
class	CorrelatorCurve

class	CLSMImage

Constructor & Destructor Documentation

◆ Correlator()

Correlator::Correlator	(	std::shared_ptr< TTTR >	tttr = nullptr,
		std::string	method = "wahl",
		int	n_bins = 17,
		int	n_casc = 25,
		bool	make_fine = false )

Correlator Constructor.

Constructs a Correlator object with the specified parameters.

Parameters

[in]	tttr	Optional TTTR object. If provided, the macro and micro time calibration of the TTTR object header calibrate the correlator.
[in]	method	Name of the correlation method used by the correlator.
[in]	n_bins	Number of equally spaced correlation bins per block (determines correlation bins).
[in]	n_casc	Number of blocks (determines correlation bins).
[in]	make_fine	If true, macro and micro time are combined.

◆ ~Correlator()

Correlator::~Correlator ( )

default

Member Function Documentation

◆ ccf_felekyan()

static void Correlator::ccf_felekyan	(	const unsigned long long *	t1,
		const unsigned long long *	t2,
		const double *	weights1,
		const double *	weights2,
		unsigned int	nc,
		unsigned int	nb,
		unsigned int	np1,
		unsigned int	np2,
		const unsigned long long *	xdat,
		double *	corrl )

staticprotected

Compute the correlation for two macro time vectors and weight

Parameters

t1	macrotime vector of first correlation channel
t2	macrotime vector of second correlation channel
weights1	weights of first correlation channel
weights2	weights of second correlation channel
nc	number of evenly spaced elements per block
nb	number of blocks of increasing spacing
np1	number of photons in first channel
np2	number of photons in second channel
xdat	correlation time bins (timeaxis)
corrl	correlation output

◆ ccf_laurence()

static void Correlator::ccf_laurence	(	std::vector< unsigned long long > &	taus,
		std::vector< double > &	corr,
		CorrelatorPhotonStream &	p1,
		CorrelatorPhotonStream &	p2 )

staticprotected

Compute correlation on arbitray correlation axis.

Parameters

[in]	taus	correlation axis (bins)
[out]	corr	correlation
[in]	p1	first event stream
[in]	p2	second event stream

Based on: Fast, flexible algorithm for calculating photon correlations, Ted A. Laurence, Samantha Fore, Thomas Huser, Optics Express Vol. 31 No. 6, p.829

◆ ccf_wahl()

static void Correlator::ccf_wahl	(	size_t	n_casc,
		size_t	n_bins,
		std::vector< unsigned long long > &	taus,
		std::vector< double > &	corr,
		CorrelatorPhotonStream &	p1,
		CorrelatorPhotonStream &	p2 )

staticprotected

Calculates the cross-correlation between two event streams.

Cross-correlates two event stream using an approach that utilizes a linear spacing of the bins within a cascade and a logarithmic spacing of the cascades. The function works inplace. During the correlation the content of the event streams are modified.

Based on: Fast calculation of fluorescence correlation data with asynchronous time-correlated single-photon counting, Michael Wahl, Ingo Gregor, Matthias Patting, Joerg Enderlein, Optics Express Vol. 11, No. 26, p. 3383

Parameters

[in]	n_casc	The number of the cascades
[in]	n_bins	The number of bins per cascase
[in]	taus	Correlation bins
[out]	corr	Correlation
[in]	p1	Event stream of first correlation channel (time + weights)
[in]	p2	Event stream of second correlation channel (time + weights)

◆ dt()

uint64_t Correlator::dt ( )

Compute the time difference in macro time units between the first and the last event.

This function calculates the time difference in macro time units between the first and the last event in the event stream.

Returns: Time difference in macro time units.

◆ get_corr()

void Correlator::get_corr	(	double **	output,
		int *	n_output )

Get the (unnormalized) correlation.

Parameters

[out]	output	a pointer to an array that will contain the correlation
[out]	n_output	a pointer to the an integer that will contain the number of elements of the x-axis

◆ get_corr_normalized()

void Correlator::get_corr_normalized	(	double **	output,
		int *	n_output )

Get the normalized correlation.

Parameters

[out]	output	an array that containing normalized correlation
[out]	n_output	the number of elements of output

◆ get_correlation_method()

std::string Correlator::get_correlation_method ( )

inline

Get the name of the used correlation method.

Returns the name of the correlation method currently set in the correlator.

Returns: Name of the used correlation method.

◆ get_curve()

CorrelatorCurve * Correlator::get_curve ( )

inline

Get the correlation curve.

Computes the correlation (if necessary) and returns the correlation curve.

Returns: Correlation curve.

◆ get_macrotimes()

std::pair< std::vector< unsigned long long >, std::vector< unsigned long long > > Correlator::get_macrotimes ( )

inline

Get event times of the first and second correlation channel.

This function returns the event times of the first and second correlation channel.

Returns: A pair of vectors containing event times of the first and second correlation channel.

◆ get_n_bins()

unsigned int Correlator::get_n_bins ( ) const

inline

Get the number of equally spaced correlation channels per block.

Returns the number of equally spaced correlation channels per block in the correlation curve.

Returns: Number of equally spaced correlation channels per block.

◆ get_n_casc()

unsigned int Correlator::get_n_casc ( )

inline

Get the number of correlation blocks.

Returns the number of correlation blocks (cascades) in the correlation curve.

Returns: Number of correlation blocks.

◆ get_tttr()

std::pair< std::shared_ptr< TTTR >, std::shared_ptr< TTTR > > Correlator::get_tttr ( )

◆ get_weights()

std::pair< std::vector< double >, std::vector< double > > Correlator::get_weights ( )

inline

Get weights used for correlation.

This function retrieves the weights for the events in the first and second correlation channels.

Returns: A pair of vectors containing weights for the first and second correlation channels, respectively.

◆ get_x_axis()

void Correlator::get_x_axis	(	double **	output,
		int *	n_output )

Get correlation bins (axis)

Parameters

[out]	output	x_axis / time axis of the correlation
[out]	n_output	number of elements in the axis of the x-axis

◆ normalize()

static void Correlator::normalize	(	Correlator *	correlator,
		CorrelatorCurve &	curve )

staticprotected

Normalize the correlation curve.

This static function makes a copy of the current correlation curve, including the x-axis and corresponding correlation amplitudes, and calculates the values of the normalized correlation.

Parameters

[in]	correlator	Reads necessary normalization parameters from the correlator settings.
[in,out]	curve	Correlation curve to be normalized.

◆ normalize_ccf_felekyan()

static void Correlator::normalize_ccf_felekyan	(	std::vector< unsigned long long > &	x_axis,
		std::vector< double > &	corr,
		std::vector< unsigned long long > &	x_axis_normalized,
		std::vector< double > &	corr_normalized,
		double	cr1,
		double	cr2,
		unsigned int	n_bins,
		unsigned int	n_casc,
		unsigned long long	maximum_macro_time )

staticprotected

Parameters

x_axis	the uncorrected x-axis (the correlation times)
corr	the uncorrected correlation amplitudes
corr_normalized	the corrected correlation amplitudes (output)
x_axis_normalized	the corrected x-axis (output)
cr1	count rate in channel 1
cr2	count rate in channel 2
n_bins	number of evenly spaced elements per block
n_casc	number of blocks of increasing spacing
maximum_macro_time	the maximum macro time

Returns

◆ normalize_ccf_laurence()

static void Correlator::normalize_ccf_laurence	(	CorrelatorPhotonStream &	p1,
		CorrelatorPhotonStream &	p2,
		std::vector< unsigned long long > &	x_axis,
		std::vector< double > &	corr,
		std::vector< double > &	corr_normalized )

staticprotected

Normalize the correlation.

Parameters

[in]	p1	first event stream
[in]	p2	second event stream
[in]	x_axis	correlation bins
[in]	corr	correlation
[out]	corr_normalized	normalized correlation

◆ normalize_ccf_wahl()

static void Correlator::normalize_ccf_wahl	(	double	np1,
		uint64_t	dt1,
		double	np2,
		uint64_t	dt2,
		std::vector< unsigned long long > &	x_axis,
		std::vector< double > &	corr,
		size_t	n_bins )

staticprotected

Normalize computed correlation.

This normalization applied to correlation curves that were calculated using a linear/logrithmic binning.

Based on: Fast calculation of fluorescence correlation data with asynchronous time-correlated single-photon counting, Michael Wahl, Ingo Gregor, Matthias Patting, Joerg Enderlein, Optics Express Vol. 11, No. 26, p. 3383

Parameters

[in]	np1	The sum of the weights in the first correlation channel
[in]	dt1	The time difference between the first event and the last event in the first correlation channel
[in]	np2	The sum of the weights in the second correlation channel
[in]	dt2	The time difference between the first event and the last event in the second correlation channel
[in,out]	x_axis	The x-axis of the correlation
[in,out]	corr	The array that contains the original correlation that is modified in place.
[in]	n_bins	The number of bins per cascade of the correlation

◆ run()

void Correlator::run ( )

compute the correlation

Compute the correlation function. Usually calling this method is not necessary the the validity of the correlation function is tracked by the attribute is_valid.

◆ set_correlation_method()

void Correlator::set_correlation_method ( std::string cm )

inline

Set the correlation method.

This function sets the correlation method used by the correlator.

Parameters

[in] cm The name of the method. Options: "felekyan", "wahl", or "laurence".

References:

Felekyan, S., et al., 2005. Full correlation from picoseconds to seconds by time-resolved and time-correlated single photon detection. Review of Scientific Instruments, 76(8), p.083104.
Wahl, M., et al., 2003. Fast calculation of fluorescence correlation data with asynchronous time-correlated single-photon counting, Opt Express Vol. 11, No. 26, p. 3383.
Laurence, T.A., et al., 2006. Fast, flexible algorithm for calculating photon correlations, Opt Lett. 15;31(6):829-31.

◆ set_events()

void Correlator::set_events	(	unsigned long long *	t1,
		int	n_t1,
		double *	weight_ch1,
		int	n_weights_ch1,
		unsigned long long *	t2,
		int	n_t2,
		double *	weight_ch2,
		int	n_weights_ch2 )

Set time events and weights for the first and second correlation channels.

This function sets the time events and weights for the first and second correlation channels.

Parameters

[in]	t1	An array containing the time events of the first channel.
[in]	n_t1	The number of time events in the first channel.
[in]	weight_ch1	A vector of weights for the time events of the first channel.
[in]	n_weights_ch1	The number of weights for the first channel.
[in]	t2	An array containing the time events of the second channel.
[in]	n_t2	The number of time events in the second channel.
[in]	weight_ch2	A vector of weights for the time events of the second channel.
[in]	n_weights_ch2	The number of weights for the second channel.

◆ set_filter()

void Correlator::set_filter	(	const std::map< short, std::vector< double > > &	filter,
		const std::vector< unsigned int > &	micro_times_1,
		const std::vector< signed char > &	routing_channels_1,
		const std::vector< unsigned int > &	micro_times_2,
		const std::vector< signed char > &	routing_channels_2 )

Update weights based on a filter map and event information.

This function updates the weights. Non-zero weights are assigned a filter value based on a filter map and the micro time of the event.

Parameters

filter[in]	A map of filters where the first element in the map is the routing channel number, and the second element is a vector that maps a micro time to a filter value.
micro_times_1[in]	Micro times of events in the first correlation channel.
routing_channels_1[in]	Routing channels of events in the first correlation channel.
micro_times_2[in]	Micro times of events in the second correlation channel.
routing_channels_2[in]	Routing channels of events in the second correlation channel.

◆ set_macrotimes()

void Correlator::set_macrotimes	(	unsigned long long *	t1,
		int	n_t1,
		unsigned long long *	t2,
		int	n_t2 )

Add macrotimes information to the event stream.

This function adds macrotimes information to the event stream for correlation analysis.

Parameters

[in]	t1	Time events in the first correlation channel.
[in]	n_t1	The number of time events in the first channel.
[in]	t2	Time events in the second correlation channel.
[in]	n_t2	The number of time events in the second channel.

◆ set_microtimes()

void Correlator::set_microtimes	(	unsigned short *	tac_1,
		int	n_tac_1,
		unsigned short *	tac_2,
		int	n_tac_2,
		unsigned int	number_of_microtime_channels )

Add microtime information to the event stream.

This function adds microtime information to the event stream for correlation analysis.

Parameters

[in]	tac_1	The micro times of the first correlation channel.
[in]	n_tac_1	The number of events in the first correlation channel.
[in]	tac_2	The micro times of the second correlation channel.
[in]	n_tac_2	The number of events in the second correlation channel.
[in]	number_of_microtime_channels	The maximum number of TAC channels of the micro times.

◆ set_n_bins()

void Correlator::set_n_bins ( int v )

inline

Set the number of equally spaced correlation channels per block.

This function sets the number of equally spaced correlation channels per block and updates the correlation curve accordingly.

Parameters

[in] v Number of equally spaced correlation channels per block.

◆ set_n_casc()

void Correlator::set_n_casc ( int n_casc )

inline

Set the number of cascades (blocks) of the correlation curve.

This function sets the number of cascades (blocks) of the correlation curve and updates the curve accordingly.

Parameters

[in] n_casc Number of cascades (blocks) of the correlation curve.

◆ set_tttr()

void Correlator::set_tttr	(	std::shared_ptr< TTTR >	tttr_1,
		std::shared_ptr< TTTR >	tttr_2 = nullptr,
		bool	make_fine = false )

Sets the time and the weights using TTTR objects.

Set the event times (and weights) using TTTR objects. By default the weights are all set to one.

The header of the first TTTR object is used for calibration. Both TTTR objects should have the same calibration (this is not checked).

Parameters

[in]	tttr_1
[in]	tttr_2
[in]	make_fine	if true a full correlation is computed that uses the micro time in the TTTR objects (default is false).

◆ set_weights()

void Correlator::set_weights	(	double *	weight_ch1,
		int	n_weights_ch1,
		double *	weight_ch2,
		int	n_weights_ch2 )

Set weights used for correlation.

This function sets and updates weights for the events in the first and second correlation channels.

Parameters

[in]	weight_ch1	A vector of weights for the time events of the first channel.
[in]	n_weights_ch1	The number of weights for the first channel.
[in]	weight_ch2	A vector of weights for the time events of the second channel.
[in]	n_weights_ch2	The number of weights for the second channel.

Friends And Related Symbol Documentation

◆ CLSMImage

friend class CLSMImage

friend

◆ CorrelatorCurve

friend class CorrelatorCurve

friend

Member Data Documentation

◆ curve

CorrelatorCurve Correlator::curve

◆ p1

CorrelatorPhotonStream Correlator::p1

◆ p2

CorrelatorPhotonStream Correlator::p2

The documentation for this class was generated from the following file:

/builds/skf/tttrlib/include/Correlator.h

Public Member Functions

Public Attributes

Static Protected Member Functions

Friends

Constructor & Destructor Documentation

◆ Correlator()

◆ ~Correlator()

Member Function Documentation

◆ ccf_felekyan()

◆ ccf_laurence()

◆ ccf_wahl()

◆ dt()

◆ get_corr()

◆ get_corr_normalized()

◆ get_correlation_method()

◆ get_curve()

◆ get_macrotimes()

◆ get_n_bins()

◆ get_n_casc()

◆ get_tttr()

◆ get_weights()

◆ get_x_axis()

◆ normalize()

◆ normalize_ccf_felekyan()

◆ normalize_ccf_laurence()

◆ normalize_ccf_wahl()

◆ run()

◆ set_correlation_method()

◆ set_events()

◆ set_filter()

◆ set_macrotimes()

◆ set_microtimes()

◆ set_n_bins()

◆ set_n_casc()

◆ set_tttr()

◆ set_weights()

Friends And Related Symbol Documentation

◆ CLSMImage

◆ CorrelatorCurve

Member Data Documentation

◆ curve

◆ p1

◆ p2