Time-Tagged Time-Resolved (TTTR) data class. More...

#include <TTTR.h>

Inheritance diagram for TTTR:

Public Member Functions
std::shared_ptr< TTTR >	Get ()
	Returns a shared pointer to the current instance of TTTR.

void	copy_from (const TTTR &p2, bool include_big_data=true)
	Copies information from another TTTR object.

int	read_file (const char *fn=nullptr, int container_type=-1)
	Reads TTTR data from a file into the TTTR object.

void	append_events (unsigned long long macro_times, int n_macrotimes, unsigned short micro_times, int n_microtimes, signed char routing_channels, int n_routing_channels, signed char event_types, int n_event_types, bool shift_macro_time=true, long long macro_time_offset=0)
	Appends events to the TTTR object.

void	append_event (unsigned long long macro_time, unsigned short micro_time, signed char routing_channel, signed char event_type, bool shift_macro_time=true, long long macro_time_offset=0)
	Appends a single event to the TTTR object.

void	append (const TTTR *other, bool shift_macro_time=true, long long macro_time_offset=0)
	Appends events from another TTTR object to the current TTTR object.

size_t	size ()
	Returns the number of valid events in the TTTR data.

void	get_used_routing_channels (signed char *output, int n_output)
	Retrieves the used routing channel numbers from the TTTR data.

void	get_macro_times (unsigned long long *output, int n_output)
	Retrieves the macro times of valid TTTR events.

void	get_micro_times (unsigned short *output, int n_output)
	Retrieves the micro times of valid TTTR events.

void	get_intensity_trace (int *output, int n_output, double time_window_length=1.0)
	Computes and returns an intensity trace for a specified integration window.

void	get_routing_channel (signed char *output, int n_output)
	Returns an array containing the routing channel numbers of the valid TTTR events.

void	get_event_type (signed char *output, int n_output)
	Returns an array containing the event types of the valid TTTR events.

unsigned int	get_number_of_micro_time_channels ()
	Returns the number of micro time channels that fit between two macro time clocks.

size_t	get_n_valid_events ()
	Returns the number of valid events in the TTTR file.

std::string	get_tttr_container_type ()
	Returns the container type used to open the TTTR file.

std::shared_ptr< TTTR >	select (int *selection, int n_selection)
	Creates a new TTTR object by selecting specific events based on the provided indices.

	TTTR ()
	Default constructor for the TTTR (Time-Tagged Time-Resolved) class.

	TTTR (const TTTR &p2)
	Copy constructor for the TTTR (Time-Tagged Time-Resolved) class.

	TTTR (const char *filename, int container_type, bool read_input)

	TTTR (const char *filename, int container_type)

	TTTR (const char filename, const char container_type)

	TTTR (unsigned long long macro_times, int n_macrotimes, unsigned short micro_times, int n_microtimes, signed char routing_channels, int n_routing_channels, signed char event_types, int n_event_types, bool find_used_channels=true)

	TTTR (const TTTR &parent, int *selection, int n_selection, bool find_used_channels=true)

	~TTTR ()

std::string	get_filename ()

std::shared_ptr< TTTR >	get_tttr_by_selection (int *selection, int n_selection)

void	get_ranges_by_time_window (int *output, int n_output, double minimum_window_length, double maximum_window_length=-1, int minimum_number_of_photons_in_time_window=-1, int maximum_number_of_photons_in_time_window=-1, double macro_time_calibration=-1, bool invert=false)
	Returns time windows (tw), i.e., the start and the stop indices for a minimum tw size, a minimum number of photons in a tw.

void	get_selection_by_channel (int *output, int n_output, signed char *input, int n_input)
	Get events indices by the routing channel number.

std::shared_ptr< TTTR >	get_tttr_by_channel (signed char *input, int n_input)
	Get a TTTR object based on a selection by routing channel numbers.

void	get_selection_by_count_rate (int *output, int n_output, double time_window, int n_ph_max, bool invert=false, bool make_mask=false)
	Get indices where the count rate is below a specified maximum.

std::shared_ptr< TTTR >	get_tttr_by_count_rate (double time_window, int n_ph_max, bool invert=false, bool make_mask=false)
	Get a TTTR object filtered by count rate criteria.

void	get_time_window_ranges (int *output, int n_output, double minimum_window_length, int minimum_number_of_photons_in_time_window, int maximum_number_of_photons_in_time_window=-1, double maximum_window_length=-1.0, double macro_time_calibration=-1, bool invert=false)
	Get time windows (tw) based on specified criteria.

TTTRHeader *	get_header ()
	Get the header as a map of strings.

void	set_header (TTTRHeader *v)
	Set the header for the TTTR object.

size_t	get_n_events ()
	Returns the number of events in the TTTR file, or the number of selected events if a selection is applied.

bool	write (std::string filename, TTTRHeader *header=nullptr)
	Writes the contents of an opened TTTR file to a new TTTR file.

void	write_spc132_events (FILE fp, TTTR tttr)
	Write events from the TTTR object to a file as SPC-132.

void	write_hht3v2_events (FILE fp, TTTR tttr)
	Write events from the TTTR object to a file as HHT3v2.

void	write_header (std::string &fn, TTTRHeader *header=nullptr)
	Writes the header information to a TTTR file.

void	shift_macro_time (int shift)
	Shifts the macro time by adding an integer value to each macro time entry.

TTTR *	operator+ (const TTTR *other) const
	Adds the events of another TTTR object to the current TTTR object.

void	get_microtime_histogram (double *histogram, int n_histogram, double *time, int n_time, unsigned short micro_time_coarsening=1)
	Computes and returns a histogram of the TTTR data's micro times.

double	mean_lifetime (TTTR tttr_irf=nullptr, int m0_irf=1, int m1_irf=1, std::vector< int > tttr_indices=nullptr, double dt=-1.0, int min_ph=1)
	Computes the mean lifetime by moments of decay and instrument response.

double	get_count_rate (std::vector< int > *tttr_indices=nullptr, double macrotime_resolution=-1.0)
	Gets the count rate.

double	get_mean_microtime (std::vector< int > *tttr_indices=nullptr, double microtime_resolution=-1.0, int minimum_number_of_photons=1)
	Gets the mean microtime.

Static Public Member Functions
static size_t	get_number_of_records_by_file_size (std::FILE *fp, size_t offset, size_t bytes_per_record)
	Determines the number of records in a TTTR file (not for use with HDF5).

static void	compute_microtime_histogram (TTTR tttr_data, double output, int n_output, double *time, int n_time, unsigned short micro_time_coarsening=1, std::vector< int > *tttr_indices=nullptr)
	Computes a histogram of the TTTR data's micro times.

static double	compute_mean_lifetime (TTTR tttr_data, TTTR tttr_irf=nullptr, double m0_irf=1, double m1_irf=0, std::vector< int > tttr_indices=nullptr, double dt=-1.0, int minimum_number_of_photons=1, std::vector< double > background=nullptr, double m0_bg=0.0, double m1_bg=0.0, double background_fraction=-1.0)
	Computes the mean lifetime by the moments of the decay and the instrument response function.

static double	compute_count_rate (TTTR tttr_data, std::vector< int > tttr_indices=nullptr, double macrotime_resolution=-1.0)
	Computes the count rate.

static double	compute_mean_microtime (TTTR tttr_data, std::vector< int > tttr_indices=nullptr, double microtime_resolution=-1.0, int minimum_number_of_photons=1)
	Computes the mean microtime.

Protected Member Functions
void	find_used_routing_channels ()
	Traverses the routing channel array and identifies used routing channel numbers.

Protected Attributes
std::vector< signed char >	used_routing_channels
	A routing channel is a numeric identifier associated with each photon in the time-tagged time-resolved (TTTR) data. It signifies the path or channel through which the photon is detected or routed.

Friends
class	CLSMImage

class	TTTRRange

class	TTTRMask

class	CorrelatorPhotonStream

Detailed Description

Time-Tagged Time-Resolved (TTTR) data class.

The TTTR class represents Time-Tagged Time-Resolved data, which is commonly used in time-correlated single-photon counting (TCSPC) experiments. It inherits from std::enable_shared_from_this to facilitate shared ownership through std::shared_ptr.

The class includes friend declarations for CLSMImage, TTTRRange, TTTRMask, and CorrelatorPhotonStream classes, allowing these classes to access the private and protected members of TTTR.

TTTR data typically consists of time-tagged events, and this class provides functionality to work with and analyze such data.

Note: This class is designed to be used in conjunction with other classes such as CLSMImage, TTTRRange, TTTRMask, and CorrelatorPhotonStream.

See also: CLSMImage; TTTRRange; TTTRMask; CorrelatorPhotonStream

Constructor & Destructor Documentation

◆ TTTR() [1/7]

TTTR::TTTR ( )

Default constructor for the TTTR (Time-Tagged Time-Resolved) class.

This constructor initializes a TTTR object with default values.

◆ TTTR() [2/7]

TTTR::TTTR ( const TTTR & p2 )

Copy constructor for the TTTR (Time-Tagged Time-Resolved) class.

This constructor creates a new TTTR object by copying the information from another TTTR object.

Parameters

p2	The TTTR object from which the information is copied.

◆ TTTR() [3/7]

TTTR::TTTR	(	const char *	filename,
		int	container_type,
		bool	read_input )

Constructor that can read a file.

Parameters

filename	TTTR filename.
container_type	Container type as int: 0: PicoQuant PTU Container (PQ_PTU_CONTAINER) 1: PicoQuant HT3 Container (PQ_HT3_CONTAINER) 2: Becker & Hickl SPC-130 Container (BH_SPC130_CONTAINER) 3: Becker & Hickl SPC-600 with 256 channels Container (BH_SPC600_256_CONTAINER) 4: Becker & Hickl SPC-600 with 4096 channels Container (BH_SPC600_4096_CONTAINER) 5: Photon-HDF5 Container (PHOTON_HDF5_CONTAINER) 6: Carl Zeiss ConfoCor3 (CZ_CONFOCOR3_CONTAINER)
read_input	If true, reads the content of the file.

◆ TTTR() [4/7]

TTTR::TTTR	(	const char *	filename,
		int	container_type )

Constructor for TTTR object that reads the content of the file.

Parameters

filename TTTR filename.

container_type

Container type as int:

0: PicoQuant PTU Container (PQ_PTU_CONTAINER)
1: PicoQuant HT3 Container (PQ_HT3_CONTAINER)
2: Becker & Hickl SPC-130 Container (BH_SPC130_CONTAINER)
3: Becker & Hickl SPC-600 with 256 channels Container (BH_SPC600_256_CONTAINER)
4: Becker & Hickl SPC-600 with 4096 channels Container (BH_SPC600_4096_CONTAINER)
5: Photon-HDF5 Container (PHOTON_HDF5_CONTAINER)
6: Carl Zeiss ConfoCor3 (CZ_CONFOCOR3_CONTAINER)

◆ TTTR() [5/7]

TTTR::TTTR	(	const char *	filename,
		const char *	container_type )

Constructor for TTTR object.

Parameters

filename	TTTR filename.
container_type	Container type as string: "PTU": PicoQuant PTU Container "HT3": PicoQuant HT3 Container "SPC-130": Becker & Hickl SPC-130 Container "SPC-600_256": Becker & Hickl SPC-600 with 256 channels Container "SPC-600_4096": Becker & Hickl SPC-600 with 4096 channels Container "PHOTON-HDF5": Photon-HDF5 Container "CZ_CONFOCOR3_CONTAINER": Carl Zeiss ConfoCor3 Container

◆ TTTR() [6/7]

TTTR::TTTR	(	unsigned long long *	macro_times,
		int	n_macrotimes,
		unsigned short *	micro_times,
		int	n_microtimes,
		signed char *	routing_channels,
		int	n_routing_channels,
		signed char *	event_types,
		int	n_event_types,
		bool	find_used_channels = true )

Constructor for TTTR object using arrays of TTTR events.

If arrays of different sizes are used to initialize a TTTR object, the shortest array among all provided arrays is used to construct the TTTR object.

Parameters

macro_times	Array containing the macro times.
n_macrotimes	Number of macro times.
micro_times	Array containing the microtimes.
n_microtimes	Length of the micro time array.
routing_channels	Routing channel array.
n_routing_channels	Length of the routing channel array.
event_types	Array of event types.
n_event_types	Number of elements in the event type array.
find_used_channels	If set to true (default), searches all indices to find the used routing channels.

◆ TTTR() [7/7]

TTTR::TTTR	(	const TTTR &	parent,
		int *	selection,
		int	n_selection,
		bool	find_used_channels = true )

Constructor for creating a new TTTR object containing records specified in the selection array.

The selection array is an array of indices. The events with indices in the selection array are copied in the order of the selection array to a new TTTR object.

Parameters

parent	Parent TTTR object from which to select records.
selection	Array of indices specifying the selected records.
n_selection	Number of elements in the selection array.
find_used_channels	If set to true (default), searches all indices to find the used routing channels.

◆ ~TTTR()

TTTR::~TTTR ( )

Destructor for TTTR class. Releases any allocated resources and cleans up the TTTR object.

Member Function Documentation

◆ append()

void TTTR::append	(	const TTTR *	other,
		bool	shift_macro_time = true,
		long long	macro_time_offset = 0 )

Appends events from another TTTR object to the current TTTR object.

Appends events from another TTTR object (other) to the current TTTR object. Optionally shifts macro times and applies an offset to the macro times.

Parameters

other	Pointer to the TTTR object containing events to append.
shift_macro_time	Flag indicating whether to shift macro times.
macro_time_offset	Offset applied to macro times if shift_macro_time is true.

◆ append_event()

void TTTR::append_event	(	unsigned long long	macro_time,
		unsigned short	micro_time,
		signed char	routing_channel,
		signed char	event_type,
		bool	shift_macro_time = true,
		long long	macro_time_offset = 0 )

Appends a single event to the TTTR object.

Appends a single event represented by macro_time, micro_time, routing_channel, and event_type to the TTTR object.

Parameters

macro_time	Macro time value for the event.
micro_time	Micro time value for the event.
routing_channel	Routing channel value for the event.
event_type	Event type value for the event.
shift_macro_time	Flag indicating whether to shift macro time.
macro_time_offset	Offset applied to macro time if shift_macro_time is true.

◆ append_events()

void TTTR::append_events	(	unsigned long long *	macro_times,
		int	n_macrotimes,
		unsigned short *	micro_times,
		int	n_microtimes,
		signed char *	routing_channels,
		int	n_routing_channels,
		signed char *	event_types,
		int	n_event_types,
		bool	shift_macro_time = true,
		long long	macro_time_offset = 0 )

Appends events to the TTTR object.

Appends events represented by macro_times, micro_times, routing_channels, and event_types to the TTTR object. The sizes of the input arrays (n_macrotimes, n_microtimes, n_routing_channels, n_event_types) must be equal.

Parameters

macro_times	Array of macro time values.
n_macrotimes	Number of elements in the macro_times array.
micro_times	Array of micro time values.
n_microtimes	Number of elements in the micro_times array.
routing_channels	Array of routing channel values.
n_routing_channels	Number of elements in the routing_channels array.
event_types	Array of event type values.
n_event_types	Number of elements in the event_types array.
shift_macro_time	Flag indicating whether to shift macro times.
macro_time_offset	Offset applied to macro times if shift_macro_time is true.

◆ compute_count_rate()

static double TTTR::compute_count_rate	(	TTTR *	tttr_data,
		std::vector< int > *	tttr_indices = nullptr,
		double	macrotime_resolution = -1.0 )

static

Computes the count rate.

Parameters

tttr_data	TTTR object for which the count rate is computed.
tttr_indices	Optional indices for selecting a subset of the TTTR.
macrotime_resolution	If negative (default), reads macrotime resolution from header (slow).

Returns: Count rate.

◆ compute_mean_lifetime()

static double TTTR::compute_mean_lifetime	(	TTTR *	tttr_data,
		TTTR *	tttr_irf = nullptr,
		double	m0_irf = 1,
		double	m1_irf = 0,
		std::vector< int > *	tttr_indices = nullptr,
		double	dt = -1.0,
		int	minimum_number_of_photons = 1,
		std::vector< double > *	background = nullptr,
		double	m0_bg = 0.0,
		double	m1_bg = 0.0,
		double	background_fraction = -1.0 )

static

Computes the mean lifetime by the moments of the decay and the instrument response function.

The computed lifetime is the first lifetime determined by the method of moments (Irvin Isenberg, 1973, Biophysical journal).

Parameters

tttr_data	TTTR object for which the lifetime is computed.
tttr_irf	TTTR object that is used as IRF.
m0_irf	Number of counts in the IRF (used if no TTTR object for IRF provided).
m1_irf	First moment of the IRF (used if no TTTR object for IRF provided).
tttr_indices	Optional list of indices for selecting a subset of the TTTR.
dt	Time resolution of the micro time. If not provided, extracted from the header (slow).
minimum_number_of_photons	Minimum number of photons. If fewer photons are in the dataset, returns -1 as computed lifetime.
background	Background pattern.
m0_bg	Sum of background photons (overwritten if the background pattern is not empty).
m1_bg	First moment of the background pattern (overwritten if the background pattern is not empty).
background_fraction	Background fraction (if negative, the background is not scaled).

Returns: The computed lifetime.

◆ compute_mean_microtime()

static double TTTR::compute_mean_microtime	(	TTTR *	tttr_data,
		std::vector< int > *	tttr_indices = nullptr,
		double	microtime_resolution = -1.0,
		int	minimum_number_of_photons = 1 )

static

Computes the mean microtime.

Parameters

tttr_data	TTTR object for which the mean microtime is computed.
tttr_indices	Optional indices for selecting a subset of the TTTR.
microtime_resolution	If negative (default), reads microtime resolution from header (slow).
minimum_number_of_photons	Minimum number of photons. If less, returns -1 as computed mean microtime.

Returns: The computed mean microtime.

◆ compute_microtime_histogram()

static void TTTR::compute_microtime_histogram	(	TTTR *	tttr_data,
		double **	output,
		int *	n_output,
		double **	time,
		int *	n_time,
		unsigned short	micro_time_coarsening = 1,
		std::vector< int > *	tttr_indices = nullptr )

static

Computes a histogram of the TTTR data's micro times.

Parameters

tttr_data	Pointer to the TTTR object containing the data.
output	Pointer to which the histogram will be written (memory is allocated by the method).
n_output	Pointer to the number of points in the histogram.
time	Pointer to the time axis of the histogram (memory is allocated by the method).
n_time	Pointer to the number of points in the time axis.
micro_time_coarsening	A factor by which the micro times in the TTTR object are divided (default value is 1).
tttr_indices	Optional pointer to store the indices of TTTR events used in the histogram.

◆ copy_from()

void TTTR::copy_from	(	const TTTR &	p2,
		bool	include_big_data = true )

Copies information from another TTTR object.

This function allows copying information from another TTTR object, including optional components based on the specified parameters.

Parameters

p2	The TTTR object from which the information is copied.
include_big_data	If true, macro time, micro time, etc., are also copied. Otherwise, only essential information is copied.

◆ find_used_routing_channels()

void TTTR::find_used_routing_channels ( )

protected

Traverses the routing channel array and identifies used routing channel numbers.

Traverses the routing channel array and populates the protected attribute used_routing_channels with the routing channel numbers that are in use.

◆ Get()

std::shared_ptr< TTTR > TTTR::Get ( )

inline

Returns a shared pointer to the current instance of TTTR.

This function is used to create a shared pointer to the current instance of the TTTR class. It allows managing the ownership of the object using shared pointers.

Returns: A shared pointer to the current instance of TTTR.

◆ get_count_rate()

double TTTR::get_count_rate	(	std::vector< int > *	tttr_indices = nullptr,
		double	macrotime_resolution = -1.0 )

inline

Gets the count rate.

Parameters

tttr_indices	Optional indices for selecting a subset of the TTTR.
macrotime_resolution	If negative (default), reads macrotime resolution from header (slow).

Returns: Count rate.

◆ get_event_type()

void TTTR::get_event_type	(	signed char **	output,
		int *	n_output )

Returns an array containing the event types of the valid TTTR events.

The event types are stored in the output array, and the number of elements in the array is returned through the n_output parameter.

Parameters

output	Pointer to the array to store the event types.
n_output	Pointer to the number of elements in the output array.

◆ get_filename()

std::string TTTR::get_filename ( )

Getter for the filename of the TTTR file.

Returns: The filename of the TTTR file.

◆ get_header()

TTTRHeader * TTTR::get_header ( )

Get the header as a map of strings.

Returns: Pointer to the TTTRHeader object representing the header information. If no header is present, returns nullptr.

◆ get_intensity_trace()

void TTTR::get_intensity_trace	(	int **	output,
		int *	n_output,
		double	time_window_length = 1.0 )

Computes and returns an intensity trace for a specified integration window.

The intensity trace is calculated based on the integration time windows, and the result is stored in the output array. The number of points in the intensity trace is returned through the n_output parameter.

Parameters

output	Pointer to the array to store the intensity trace.
n_output	Pointer to the number of points in the intensity trace.
time_window_length	The length of the integration time windows in units of milliseconds.

◆ get_macro_times()

void TTTR::get_macro_times	(	unsigned long long **	output,
		int *	n_output )

Retrieves the macro times of valid TTTR events.

This function populates the provided output array with the macro times of the valid TTTR events. The number of elements in the output array is stored in the n_output parameter.

Parameters

output	Pointer to the output array to be populated.
n_output	Pointer to the number of elements in the output array.

◆ get_mean_microtime()

double TTTR::get_mean_microtime	(	std::vector< int > *	tttr_indices = nullptr,
		double	microtime_resolution = -1.0,
		int	minimum_number_of_photons = 1 )

inline

Gets the mean microtime.

Parameters

tttr_indices	Optional indices for selecting a subset of the TTTR.
microtime_resolution	If negative (default), reads microtime resolution from header (slow).
minimum_number_of_photons	Minimum number of photons. If less, returns -1 as computed mean microtime.

Returns: The computed mean microtime.

◆ get_micro_times()

void TTTR::get_micro_times	(	unsigned short **	output,
		int *	n_output )

Retrieves the micro times of valid TTTR events.

This function populates the provided output array with the micro times of the valid TTTR events. The number of elements in the output array is stored in the n_output parameter.

Parameters

output	Pointer to the output array to be populated.
n_output	Pointer to the number of elements in the output array.

◆ get_microtime_histogram()

void TTTR::get_microtime_histogram	(	double **	histogram,
		int *	n_histogram,
		double **	time,
		int *	n_time,
		unsigned short	micro_time_coarsening = 1 )

inline

Computes and returns a histogram of the TTTR data's micro times.

Parameters

histogram	Pointer to which the histogram will be written (memory is allocated by the method).
n_histogram	Pointer to the number of points in the histogram.
time	Pointer to the time axis of the histogram (memory is allocated by the method).
n_time	Pointer to the number of points in the time axis.
micro_time_coarsening	A factor by which the micro times in the TTTR object are divided (default value is 1).

◆ get_n_events()

size_t TTTR::get_n_events ( )

Returns the number of events in the TTTR file, or the number of selected events if a selection is applied.

Returns: Number of events in the TTTR file or the number of selected events.

◆ get_n_valid_events()

size_t TTTR::get_n_valid_events ( )

Returns the number of valid events in the TTTR file.

This function retrieves and returns the total number of valid events present in the TTTR (Time-Tagged Time-Resolved) file.

Returns: Number of valid events in the TTTR file.

◆ get_number_of_micro_time_channels()

unsigned int TTTR::get_number_of_micro_time_channels ( )

Returns the number of micro time channels that fit between two macro time clocks.

This function calculates and returns the maximum valid number of micro time channels that fit between two macro time clocks.

Returns: Maximum valid number of micro time channels.

◆ get_number_of_records_by_file_size()

static size_t TTTR::get_number_of_records_by_file_size	(	std::FILE *	fp,
		size_t	offset,
		size_t	bytes_per_record )

static

Determines the number of records in a TTTR file (not for use with HDF5).

Calculates the number of records in the file based on the file size. If the offset is passed, the number of records is calculated using the file size, offset, and bytes_per_record. If the offset is not specified, the current location of the file pointer is used. If bytes_per_record is not specified, the attribute value bytes_per_record of the class instance is used.

Parameters

fp	The file pointer to the TTTR file.
offset	The offset for calculating the number of records.
bytes_per_record	The number of bytes per record.

Returns: Returns the calculated number of records.

◆ get_ranges_by_time_window()

void TTTR::get_ranges_by_time_window	(	int **	output,
		int *	n_output,
		double	minimum_window_length,
		double	maximum_window_length = -1,
		int	minimum_number_of_photons_in_time_window = -1,
		int	maximum_number_of_photons_in_time_window = -1,
		double	macro_time_calibration = -1,
		bool	invert = false )

inline

Returns time windows (tw), i.e., the start and the stop indices for a minimum tw size, a minimum number of photons in a tw.

Parameters

output	[out] Array containing the interleaved start and stop indices of the tws in the TTTR object.
n_output	[out] Length of the output array
minimum_window_length	[in] Minimum length of a tw (mandatory).
maximum_window_length	[in] Maximum length of a tw (optional).
minimum_number_of_photons_in_time_window	[in] Minimum number of photons a selected tw contains (optional)
maximum_number_of_photons_in_time_window	[in] Maximum number of photons a selected tw contains (optional)
macro_time_calibration	[in] Macro time calibration in units of the macro time resolution. If negative, the macro time resolution from the TTTR header is used.
invert	[in] If set to true, the selection criteria are inverted.

◆ get_routing_channel()

void TTTR::get_routing_channel	(	signed char **	output,
		int *	n_output )

Returns an array containing the routing channel numbers of the valid TTTR events.

The routing channel numbers are stored in the output array, and the number of elements in the array is returned through the n_output parameter.

Parameters

output	Pointer to the array to store the routing channel numbers.
n_output	Pointer to the number of elements in the output array.

◆ get_selection_by_channel()

void TTTR::get_selection_by_channel	(	int **	output,
		int *	n_output,
		signed char *	input,
		int	n_input )

Get events indices by the routing channel number.

This method retrieves an array containing the event/ photon indices of events with routing channel numbers found in the selection input array.

Parameters

output	[out] Indices of the selected events
n_output	[out] Number of selected events
input	[in] Routing channel numbers for selecting events
n_input	[in] Number of routing channels for selection

◆ get_selection_by_count_rate()

void TTTR::get_selection_by_count_rate	(	int **	output,
		int *	n_output,
		double	time_window,
		int	n_ph_max,
		bool	invert = false,
		bool	make_mask = false )

Get indices where the count rate is below a specified maximum.

This method returns an array of indices where the count rate, calculated within a sliding time window, is below a specified maximum.

Parameters

output	[out] Array containing the selected indices
n_output	[out] Number of elements in the output array
time_window	[in] Length of the time window in milliseconds
n_ph_max	[in] Maximum number of photons within a time window
invert	[in] If set to true, the selection criteria are inverted
make_mask	[in] If set to true, the output array will be a boolean mask

◆ get_time_window_ranges()

void TTTR::get_time_window_ranges	(	int **	output,
		int *	n_output,
		double	minimum_window_length,
		int	minimum_number_of_photons_in_time_window,
		int	maximum_number_of_photons_in_time_window = -1,
		double	maximum_window_length = -1.0,
		double	macro_time_calibration = -1,
		bool	invert = false )

Get time windows (tw) based on specified criteria.

Returns time windows (tw), i.e., the start and stop indices for a minimum tw size, a minimum number of photons in a tw.

Parameters

output[out]	Array containing the interleaved start and stop indices of the tws in the TTTR object.
n_output[out]	Length of the output array
minimum_window_length[in]	Minimum length of a tw in units of ms (mandatory).
minimum_number_of_photons_in_time_window[in]	Minimum number of photons a selected tw contains (optional) in units of seconds
maximum_number_of_photons_in_time_window[in]	Maximum number of photons a selected tw contains (optional)
maximum_window_length[in]	Maximum length of a tw (optional).
macro_time_calibration[in]	Macro time calibration in units of seconds. If negative, the macro time resolution from the header is used.
invert[in]	If set to true, the selection criteria are inverted.

◆ get_tttr_by_channel()

std::shared_ptr< TTTR > TTTR::get_tttr_by_channel	(	signed char *	input,
		int	n_input )

inline

Get a TTTR object based on a selection by routing channel numbers.

This method creates and returns a shared pointer to a TTTR object that contains only the events with routing channel numbers specified in the input array.

Parameters

input	[in] Routing channel numbers for selecting events
n_input	[in] Number of routing channels for selection

Returns: Shared pointer to the new TTTR object based on the specified selection

◆ get_tttr_by_count_rate()

std::shared_ptr< TTTR > TTTR::get_tttr_by_count_rate	(	double	time_window,
		int	n_ph_max,
		bool	invert = false,
		bool	make_mask = false )

inline

Get a TTTR object filtered by count rate criteria.

This method returns a TTTR object filtered based on count rate criteria.

Parameters

time_window	[in] Length of the time window in milliseconds
n_ph_max	[in] Maximum number of photons within a time window
invert	[in] If set to true, the count rate criteria are inverted
make_mask	[in] If set to true, the output array will be a boolean mask

Returns: A shared pointer to the filtered TTTR object

◆ get_tttr_by_selection()

std::shared_ptr< TTTR > TTTR::get_tttr_by_selection	(	int *	selection,
		int	n_selection )

inline

Get a pointer to a TTTR object that is based on a selection on the current TTTR object. A selection is an array of indices of the TTTR events.

Parameters

selection	Array of indices of TTTR events.
n_selection	Number of elements in the selection array.

Returns: A shared pointer to a new TTTR object based on the specified selection.

◆ get_tttr_container_type()

std::string TTTR::get_tttr_container_type ( )

inline

Returns the container type used to open the TTTR file.

This function retrieves and returns the container type that was used to open the TTTR (Time-Tagged Time-Resolved) file.

Returns: Container type used to open the TTTR file.

◆ get_used_routing_channels()

void TTTR::get_used_routing_channels	(	signed char **	output,
		int *	n_output )

Retrieves the used routing channel numbers from the TTTR data.

This function populates the provided output array with the routing channel numbers that are used in the TTTR file. The number of elements in the output array is stored in the n_output parameter.

Parameters

output	Pointer to the output array to be populated.
n_output	Pointer to the number of elements in the output array.

◆ mean_lifetime()

double TTTR::mean_lifetime	(	TTTR *	tttr_irf = nullptr,
		int	m0_irf = 1,
		int	m1_irf = 1,
		std::vector< int > *	tttr_indices = nullptr,
		double	dt = -1.0,
		int	min_ph = 1 )

inline

Computes the mean lifetime by moments of decay and instrument response.

Parameters

tttr_irf	TTTR object used as IRF.
m0_irf	Counts in the IRF (used if no TTTR object for IRF provided).
m1_irf	First moment of the IRF (used if no TTTR object for IRF provided).
tttr_indices	Optional indices for selecting a subset of the TTTR.
dt	Time resolution of the micro time. If not provided, extracted from the header (slow).
min_ph	Minimum number of photons. If fewer photons are in the dataset, returns -1 as computed lifetime.

Returns: Computed mean lifetime.

◆ operator+()

TTTR * TTTR::operator+ ( const TTTR * other ) const

inline

Adds the events of another TTTR object to the current TTTR object.

Parameters

other Pointer to the TTTR object whose events will be added.

Returns: Pointer to a new TTTR object containing the combined events.

◆ read_file()

int TTTR::read_file	(	const char *	fn = nullptr,
		int	container_type = -1 )

Reads TTTR data from a file into the TTTR object.

This function reads TTTR data from the specified file into the TTTR object. If the filename is not provided (default is nullptr), the filename attribute of the TTTR object is used. The container_type parameter specifies the type of container used in the file.

Parameters

fn	The filename to read. If nullptr (default), the TTTR object's filename is used.
container_type	The container type.

Returns: Returns 1 if the file is read without errors; otherwise, returns 0.

◆ select()

std::shared_ptr< TTTR > TTTR::select	(	int *	selection,
		int	n_selection )

Creates a new TTTR object by selecting specific events based on the provided indices.

This function creates a new TTTR (Time-Tagged Time-Resolved) object by selecting specific events from the current TTTR object based on the provided indices.

Parameters

selection	Pointer to an array containing the indices of selected events.
n_selection	Number of elements in the selection array.

Returns: Shared pointer to the newly created TTTR object containing selected events.

◆ set_header()

void TTTR::set_header ( TTTRHeader * v )

Set the header for the TTTR object.

Parameters

v	Pointer to the TTTRHeader object containing the header information.

◆ shift_macro_time()

void TTTR::shift_macro_time ( int shift )

Shifts the macro time by adding an integer value to each macro time entry.

Parameters

shift The integer value added to each macro time entry.

◆ size()

size_t TTTR::size ( )

inline

Returns the number of valid events in the TTTR data.

This function is a wrapper for the get_n_valid_events() method and returns the total number of valid events in the TTTR data.

Returns: The number of valid events.

◆ write()

bool TTTR::write	(	std::string	filename,
		TTTRHeader *	header = nullptr )

Writes the contents of an opened TTTR file to a new TTTR file.

Parameters

filename	The filename for the new TTTR file.
header	Optional TTTRHeader to be written. If set to nullptr, no header is written (default is nullptr).

Returns: True if the write operation is successful, false otherwise.

◆ write_header()

void TTTR::write_header	(	std::string &	fn,
		TTTRHeader *	header = nullptr )

Writes the header information to a TTTR file.

Parameters

fn	The filename to write the header to.
header	Pointer to the TTTRHeader object containing header information.

◆ write_hht3v2_events()

void TTTR::write_hht3v2_events	(	FILE *	fp,
		TTTR *	tttr )

Write events from the TTTR object to a file as HHT3v2.

Parameters

fp	The FILE pointer for the output file.
tttr	The TTTR object containing the events to be written.

◆ write_spc132_events()

void TTTR::write_spc132_events	(	FILE *	fp,
		TTTR *	tttr )

Write events from the TTTR object to a file as SPC-132.

Parameters

fp	The FILE pointer for the output file.
tttr	The TTTR object containing the events to be written.

Friends And Related Symbol Documentation

◆ CLSMImage

friend class CLSMImage

friend

◆ CorrelatorPhotonStream

friend class CorrelatorPhotonStream

friend

◆ TTTRMask

friend class TTTRMask

friend

◆ TTTRRange

friend class TTTRRange

friend

Member Data Documentation

◆ used_routing_channels

std::vector<signed char> TTTR::used_routing_channels

protected

A routing channel is a numeric identifier associated with each photon in the time-tagged time-resolved (TTTR) data. It signifies the path or channel through which the photon is detected or routed.

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

/builds/skf/tttrlib/include/TTTR.h

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ TTTR() [1/7]

◆ TTTR() [2/7]

◆ TTTR() [3/7]

◆ TTTR() [4/7]

◆ TTTR() [5/7]

◆ TTTR() [6/7]

◆ TTTR() [7/7]

◆ ~TTTR()

Member Function Documentation

◆ append()

◆ append_event()

◆ append_events()

◆ compute_count_rate()

◆ compute_mean_lifetime()

◆ compute_mean_microtime()

◆ compute_microtime_histogram()

◆ copy_from()

◆ find_used_routing_channels()

◆ Get()

◆ get_count_rate()

◆ get_event_type()

◆ get_filename()

◆ get_header()

◆ get_intensity_trace()

◆ get_macro_times()

◆ get_mean_microtime()

◆ get_micro_times()

◆ get_microtime_histogram()

◆ get_n_events()

◆ get_n_valid_events()

◆ get_number_of_micro_time_channels()

◆ get_number_of_records_by_file_size()

◆ get_ranges_by_time_window()

◆ get_routing_channel()

◆ get_selection_by_channel()

◆ get_selection_by_count_rate()

◆ get_time_window_ranges()

◆ get_tttr_by_channel()

◆ get_tttr_by_count_rate()

◆ get_tttr_by_selection()

◆ get_tttr_container_type()

◆ get_used_routing_channels()

◆ mean_lifetime()

◆ operator+()

◆ read_file()

◆ select()

◆ set_header()

◆ shift_macro_time()

◆ size()

◆ write()

◆ write_header()

◆ write_hht3v2_events()

◆ write_spc132_events()

Friends And Related Symbol Documentation

◆ CLSMImage

◆ CorrelatorPhotonStream

◆ TTTRMask

◆ TTTRRange

Member Data Documentation

◆ used_routing_channels