Photon Distribution Analysis class for computing histograms. More...

#include <Pda.h>

Public Member Functions
void	evaluate ()
	Computes the S1S2 histogram.

	Pda (int hist2d_nmax=300, int hist2d_nmin=5, double background_ch1=0.0, double background_ch2=0.0, std::vector< double > pF=std::vector< double >())
	Constructor for creating a new Pda object.

	~Pda ()=default

void	append (double amplitude, double probability_ch1)
	Appends a species to the Pda object.

void	clear_probability_ch1 ()
	Clears the model and removes all species from the Pda object.

void	get_amplitudes (double *output_view, int n_output)
	Returns the amplitudes of the species.

void	set_amplitudes (double *input, int n_input)
	Sets the amplitudes of the species.

void	set_callback (PdaCallback *cb)
	Set the callback (cb) for the computation of a 1D histogram.

void	get_S1S2_matrix (double *output, int n_output1, int *n_output2)

void	set_probability_spectrum_ch1 (double *input, int n_input)

void	get_probabilities_ch1 (double *output_view, int n_output)
	Returns the amplitudes of the species.

void	set_probabilities_ch1 (double *input, int n_input)
	Sets the theoretical probabilities for detecting a species in the first channel.

void	get_probability_spectrum_ch1 (double *output, int n_output)
	Get the theoretical probability spectrum of detecting a photon in the first channel.

void	setPF (double *input, int n_input)
	Set the probability P(F).

void	getPF (double *output_view, int n_output)
	Get the probability P(F).

void	get_1dhistogram (double *histogram_x, int n_histogram_x, double *histogram_y, int n_histogram_y, double x_max=1000.0, double x_min=0.01, int n_bins=81, bool log_x=true, std::vector< double > s1s2=std::vector< double >(), int n_min=-1, bool skip_zero_photon=true, std::vector< double > amplitudes=std::vector< double >(), std::vector< double > probabilities_ch1=std::vector< double >())
	Computes a 1D histogram from the 2D counting array of the two channels.

unsigned int	get_max_number_of_photons () const
	Get the maximum number of photons in the S1S2 matrix.

void	set_max_number_of_photons (unsigned int nmax)
	Set the maximum number of photons in the S1S2 matrix.

unsigned int	get_min_number_of_photons () const
	Get the minimum number of photons in the S1S2 matrix.

void	set_min_number_of_photons (unsigned int nmin)
	Set the minimum number of photons in the S1S2 matrix.

double	get_ch1_background () const
	Get the background in the green channel.

void	set_ch1_background (double bg)
	Set the background in the first channel.

double	get_ch2_background () const
	Get the background in the second channel.

void	set_ch2_background (double br)
	Set the background in the second channel.

bool	is_valid_sgsr () const
	Check if the S1S2 histogram is valid.

void	set_valid_sgsr (bool v)
	Set the S1S2 histogram validity (for testing purposes).

Static Public Member Functions
static void	compute_experimental_histograms (TTTR tttr_data, double s1s2, int dim1, int dim2, double ps, int dim_ps, int *tttr_indices, int n_tttr_indices, std::vector< int > channels_1, std::vector< int > channels_2, int maximum_number_of_photons, int minimum_number_of_photons, double minimum_time_window_length)
	Computes experimental histograms.

static void	S1S2_pF (std::vector< double > &S1S2, std::vector< double > &pF, unsigned int Nmax, double background_ch1, double background_ch2, std::vector< double > &p_ch1, std::vector< double > &amplitudes)
	Calculates p(G,R) for several ratios using the same P(F).

static void	conv_pF (std::vector< double > &S1S2, const std::vector< double > &F1F2, unsigned int Nmax, double background_ch1, double background_ch2)
	Convolves the fluorescence matrix F1F2 with the background to yield the signal matrix S1S2.

static void	poisson_0toN (std::vector< double > &return_p, int start_idx, double lam, int return_dim)
	Writes a Poisson distribution with an average lam for 0..N into a vector starting at a specified index.

Protected Attributes
unsigned int	_n_2d_max = 300
	Maximum number of photons in the SgSr histogram.

unsigned int	_n_2d_min = 3
	Minimum number of photons.

double	_bg_ch1 = 0.0
	Background in the first channel (in FRET green channel)

double	_bg_ch2 = 0.0
	Background in the second channel (in FRET red channel)

std::vector< double >	_S1S2

std::vector< double >	pF
	Probability P(F) of having a certain amount of photons.

Detailed Description

Photon Distribution Analysis class for computing histograms.

Constructor & Destructor Documentation

◆ Pda()

Pda::Pda	(	int	hist2d_nmax = 300,
		int	hist2d_nmin = 5,
		double	background_ch1 = 0.0,
		double	background_ch2 = 0.0,
		std::vector< double >	pF = std::vector<double>() )

inline

Constructor for creating a new Pda object.

Initializes a Pda object for computing Photon Distribution Analysis histograms.

Parameters

hist2d_nmax	The maximum number of photons.
hist2d_nmin	The minimum number of photons considered.
background_ch1	Background level in the first channel (green channel).
background_ch2	Background level in the second channel (red channel).
pF	Probability distribution of having a certain number of photons.

◆ ~Pda()

Pda::~Pda ( )

default

Member Function Documentation

◆ append()

void Pda::append	(	double	amplitude,
		double	probability_ch1 )

inline

Appends a species to the Pda object.

A species is defined by the amplitude (fraction) and the probability of detecting a photon in the first detection channel.

Parameters

amplitude	The amplitude (fraction) of the species.
probability_ch1	The probability of detecting the species in the first detection channel.

◆ clear_probability_ch1()

void Pda::clear_probability_ch1 ( )

inline

Clears the model and removes all species from the Pda object.

◆ compute_experimental_histograms()

static void Pda::compute_experimental_histograms	(	TTTR *	tttr_data,
		double **	s1s2,
		int *	dim1,
		int *	dim2,
		double **	ps,
		int *	dim_ps,
		int **	tttr_indices,
		int *	n_tttr_indices,
		std::vector< int >	channels_1,
		std::vector< int >	channels_2,
		int	maximum_number_of_photons,
		int	minimum_number_of_photons,
		double	minimum_time_window_length )

static

Computes experimental histograms.

This static method computes experimental histograms based on the provided TTTR data.

Parameters

tttr_data[in]	TTTR data input.
s1s2[out]	Output S1S2 matrix.
dim1[out]	Output dimension 1 of the S1S2 matrix.
dim2[out]	Output dimension 2 of the S1S2 matrix.
ps[out]	Output PS matrix.
dim_ps[out]	Output dimension of the PS matrix.
tttr_indices[out]	Output TTTR indices.
n_tttr_indices[out]	Output number of TTTR indices.
channels_1[in]	Routing channel numbers used for the first channel in the S1S2 matrix. Photons with this channel number are counted and increment values in the S1S2 matrix.
channels_2[in]	Routing channel numbers used for the second channel in the S1S2 matrix. Photons with this channel number are counted and increment values in the S1S2 matrix.
maximum_number_of_photons[in]	Maximum number of photons in the computed S1S2 matrix.
minimum_number_of_photons[in]	Minimum number of photons in a time window and in the S1S2 matrix.
minimum_time_window_length[in]	Minimum length of a time window in milliseconds.

◆ conv_pF()

static void Pda::conv_pF	(	std::vector< double > &	S1S2,
		const std::vector< double > &	F1F2,
		unsigned int	Nmax,
		double	background_ch1,
		double	background_ch2 )

static

Convolves the fluorescence matrix F1F2 with the background to yield the signal matrix S1S2.

This static method convolves the fluorescence matrix F1F2 with the background to produce the signal matrix S1S2.

Parameters

S1S2[out]	Output signal matrix.
F1F2[in]	Input fluorescence matrix.
Nmax	Maximum number of photons.
background_ch1	Background in the green channel.
background_ch2	Background in the red channel.

◆ evaluate()

void Pda::evaluate ( )

Computes the S1S2 histogram.

This function computes the S1S2 histogram based on the specified parameters, such as the maximum and minimum number of photons, background levels, and the probability distribution.

◆ get_1dhistogram()

void Pda::get_1dhistogram	(	double **	histogram_x,
		int *	n_histogram_x,
		double **	histogram_y,
		int *	n_histogram_y,
		double	x_max = 1000.0,
		double	x_min = 0.01,
		int	n_bins = 81,
		bool	log_x = true,
		std::vector< double >	s1s2 = std::vector< double >(),
		int	n_min = -1,
		bool	skip_zero_photon = true,
		std::vector< double >	amplitudes = std::vector< double >(),
		std::vector< double >	probabilities_ch1 = std::vector< double >() )

Computes a 1D histogram from the 2D counting array of the two channels.

This method calculates a 1D histogram based on the 2D counting array of the two channels.

Parameters

histogram_x[out]	Histogram X-axis.
n_histogram_x[out]	Dimension of the X-axis.
histogram_y[out]	Array containing the computed histogram.
n_histogram_y[out]	Dimension of the histogram.
x_max[in]	Maximum x-value of the histogram.
x_min[in]	Minimum x-value of the histogram.
n_bins[in]	Number of histogram bins.
log_x[in]	If set to true (default is true), x-axis values are logarithmically spaced; otherwise, linear spacing.
s1s2[in]	Optional input for the S1S2 matrix. If nullptr (default), the Pda object's S1S2 matrix is used for computation. If not nullptr and both n_histogram_x and n_histogram_y > 0, this input is used as the S1S2 matrix. Input matrix must be quadratic.
n_min[in]	Minimum number of photons in the histogram. If -1 (default), the number set when the Pda object was instantiated is used.
skip_zero_photon[in]	When true, only s1s2 matrix elements i,j (i>0 and j>0) are considered.
amplitudes[in]	Species amplitudes (optional). Updates the s1s2 matrix of the object.
probabilities_ch1[in]	Theoretical probabilities of detecting the species in channel 1 (optional). Updates the s1s2 matrix of the object.

◆ get_amplitudes()

void Pda::get_amplitudes	(	double **	output_view,
		int *	n_output )

inline

Returns the amplitudes of the species.

Parameters

output_view[out]	A C type array containing the amplitude of the species.
n_output[out]	The number of species.

◆ get_ch1_background()

double Pda::get_ch1_background ( ) const

inline

Get the background in the green channel.

This method returns the background value in the green channel.

Returns: The background value in the green channel.

◆ get_ch2_background()

double Pda::get_ch2_background ( ) const

inline

Get the background in the second channel.

This method returns the background value in the second channel.

Returns: The background value in the second channel.

◆ get_max_number_of_photons()

unsigned int Pda::get_max_number_of_photons ( ) const

inline

Get the maximum number of photons in the S1S2 matrix.

This method returns the maximum number of photons that the S1S2 matrix can accommodate.

Returns: The maximum number of photons in the S1S2 matrix.

◆ get_min_number_of_photons()

unsigned int Pda::get_min_number_of_photons ( ) const

inline

Get the minimum number of photons in the S1S2 matrix.

This method retrieves the minimum number of photons that the S1S2 matrix can have.

Returns: The minimum number of photons.

◆ get_probabilities_ch1()

void Pda::get_probabilities_ch1	(	double **	output_view,
		int *	n_output )

inline

Returns the amplitudes of the species.

Parameters

output_view[out]	A C type array containing the amplitude of the species.
n_output[out]	The number of species.

◆ get_probability_spectrum_ch1()

void Pda::get_probability_spectrum_ch1	(	double **	output,
		int *	n_output )

inline

Get the theoretical probability spectrum of detecting a photon in the first channel.

The probability spectrum is an interleaved array of the amplitudes and the probabilities of detecting a photon in the first channel.

Parameters

output[out]	Array containing the probability spectrum.
n_output[out]	Number of elements in the output array.

◆ get_S1S2_matrix()

void Pda::get_S1S2_matrix	(	double **	output,
		int *	n_output1,
		int *	n_output2 )

inline

Returns the S1S2 matrix that contains the photon counts in the two channels

Parameters

output[out]	the S1S2 matrix
n_output1[out]	dimension 1 of the matrix
n_output2[out]	dimension 2 of the matrix

◆ getPF()

void Pda::getPF	(	double **	output_view,
		int *	n_output )

inline

Get the probability P(F).

Parameters

output_view[out]	A C type array containing the probability P(F).
n_output[out]	The number of elements in the output array.

◆ is_valid_sgsr()

bool Pda::is_valid_sgsr ( ) const

inline

Check if the S1S2 histogram is valid.

This method returns true if the S1S2 histogram is considered valid, meaning that it provides correct output for the given input parameters. The validity is set to true after calling the evaluate method.

Returns: True if the S1S2 histogram is valid, false otherwise.

◆ poisson_0toN()

static void Pda::poisson_0toN	(	std::vector< double > &	return_p,
		int	start_idx,
		double	lam,
		int	return_dim )

static

Writes a Poisson distribution with an average lam for 0..N into a vector starting at a specified index.

This static method generates a Poisson distribution with an average lam for values 0 to N and writes it into the vector starting at the specified index.

Parameters

return_p[in,out]	Vector to store the Poisson distribution.
start_idx	Starting index in the vector.
lam	Average lambda for the Poisson distribution.
return_dim	Dimension of the vector.

◆ S1S2_pF()

static void Pda::S1S2_pF	(	std::vector< double > &	S1S2,
		std::vector< double > &	pF,
		unsigned int	Nmax,
		double	background_ch1,
		double	background_ch2,
		std::vector< double > &	p_ch1,
		std::vector< double > &	amplitudes )

static

Calculates p(G,R) for several ratios using the same P(F).

This static method calculates p(G,R) for several ratios using the same P(F).

Parameters

S1S2[in]	See sgsr_pN.
pF[in]	Input P(F).
Nmax[in]	Maximum number of photons.
background_ch1[in]	Background in the green channel.
background_ch2[in]	Background in the red channel.
p_ch1[in]	Input probabilities for channel 1.
amplitudes[in]	Corresponding amplitudes.

◆ set_amplitudes()

void Pda::set_amplitudes	(	double *	input,
		int	n_input )

inline

Sets the amplitudes of the species.

Parameters

input[in]	A C type array that contains the amplitude of the species.
n_input[in]	The number of species.

◆ set_callback()

void Pda::set_callback ( PdaCallback * cb )

inline

Set the callback (cb) for the computation of a 1D histogram.

The cb function reduces two-dimensional values, i.e., the intensity in channel (ch1) and ch2, to a one-dimensional number. The cb is used to compute either FRET efficiencies, etc.

Parameters

cb[in] Object that computes the value on a 1D histogram.

◆ set_ch1_background()

void Pda::set_ch1_background ( double bg )

inline

Set the background in the first channel.

This method sets the background value in the green channel.

Parameters

bg	The background value to be set in the green channel.

◆ set_ch2_background()

void Pda::set_ch2_background ( double br )

inline

Set the background in the second channel.

This method sets the background value in the second channel.

Parameters

br	The background value to be set.

◆ set_max_number_of_photons()

void Pda::set_max_number_of_photons ( unsigned int nmax )

inline

Set the maximum number of photons in the S1S2 matrix.

This method sets the maximum number of photons that the S1S2 matrix can accommodate. It also resizes the internal S1S2 matrix accordingly.

Note: The size of the pF array must agree with the maximum number of photons.

Parameters

nmax[in] The maximum number of photons.

◆ set_min_number_of_photons()

void Pda::set_min_number_of_photons ( unsigned int nmin )

inline

Set the minimum number of photons in the S1S2 matrix.

This method sets the minimum number of photons that the S1S2 matrix can have. It also invalidates the current S1S2 matrix to ensure it is recomputed with the new minimum number of photons.

Parameters

nmin	The minimum number of photons to set.

◆ set_probabilities_ch1()

void Pda::set_probabilities_ch1	(	double *	input,
		int	n_input )

inline

Sets the theoretical probabilities for detecting a species in the first channel.

Parameters

input[in]	A C type array that contains the probabilities of the species.
n_input[in]	The number of species.

◆ set_probability_spectrum_ch1()

void Pda::set_probability_spectrum_ch1	(	double *	input,
		int	n_input )

inline

Set the theoretical probability spectrum of detecting a photon in the first channel

The probability spectrum is an interleaved array of the amplitudes and the probabilities of detecting a photon in the first channel

Parameters

input[in]	a C type array containing the probability spectrum
n_input[in]	the number of array elements

◆ set_valid_sgsr()

void Pda::set_valid_sgsr ( bool v )

inline

Set the S1S2 histogram validity (for testing purposes).

This method allows setting the validity of the S1S2 histogram explicitly, primarily intended for testing purposes.

Parameters

v[in] True to set the S1S2 histogram as valid, false otherwise.

◆ setPF()

void Pda::setPF	(	double *	input,
		int	n_input )

inline

Set the probability P(F).

Parameters

input[in]	A C type array containing the probability P(F).
n_input[in]	The number of elements in the input array.

Member Data Documentation

◆ _bg_ch1

double Pda::_bg_ch1 = 0.0

protected

Background in the first channel (in FRET green channel)

◆ _bg_ch2

double Pda::_bg_ch2 = 0.0

protected

Background in the second channel (in FRET red channel)

◆ _n_2d_max

unsigned int Pda::_n_2d_max = 300

protected

Maximum number of photons in the SgSr histogram.

◆ _n_2d_min

unsigned int Pda::_n_2d_min = 3

protected

Minimum number of photons.

◆ _S1S2

std::vector<double> Pda::_S1S2

protected

S1S2 histogram, a histogram of the counts in channel 1 and channel 2 in a FRET experiment ch1 and ch2 are green and red, respectively.

◆ pF

std::vector<double> Pda::pF

protected

Probability P(F) of having a certain amount of photons.

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

/builds/skf/tttrlib/include/Pda.h

Public Member Functions

Static Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Pda()

◆ ~Pda()

Member Function Documentation

◆ append()

◆ clear_probability_ch1()

◆ compute_experimental_histograms()

◆ conv_pF()

◆ evaluate()

◆ get_1dhistogram()

◆ get_amplitudes()

◆ get_ch1_background()

◆ get_ch2_background()

◆ get_max_number_of_photons()

◆ get_min_number_of_photons()

◆ get_probabilities_ch1()

◆ get_probability_spectrum_ch1()

◆ get_S1S2_matrix()

◆ getPF()

◆ is_valid_sgsr()

◆ poisson_0toN()

◆ S1S2_pF()

◆ set_amplitudes()

◆ set_callback()

◆ set_ch1_background()

◆ set_ch2_background()

◆ set_max_number_of_photons()

◆ set_min_number_of_photons()

◆ set_probabilities_ch1()

◆ set_probability_spectrum_ch1()

◆ set_valid_sgsr()

◆ setPF()

Member Data Documentation

◆ _bg_ch1

◆ _bg_ch2

◆ _n_2d_max

◆ _n_2d_min

◆ _S1S2

◆ pF