Time correlation processors

Description

Processors for time correlation.

Topics
	Pairing processors
	Processors for finding pairs of detection events.

Functions
template<typename DataTypes = default_data_types, typename Downstream>
auto	tcspc::negate_difftime (Downstream downstream)
	Create a processor that changes the sign of difftime in time-correlated detection events.
template<typename EventList, typename DataTypes = default_data_types, typename Downstream>
auto	tcspc::recover_order (arg::time_window< typename DataTypes::abstime_type > time_window, Downstream downstream)
	Create a processor that sorts events by abstime, provided that they are out of order only within a bounded time window.
template<typename DataTypes = default_data_types, typename Downstream>
auto	tcspc::remove_time_correlation (Downstream downstream)
	Create a processor that removes the difftime from detection events.
template<typename DataTypes = default_data_types, bool UseStartChannel = false, typename Downstream>
auto	tcspc::time_correlate_at_fraction (arg::fraction< double > fraction, Downstream downstream)
	Create a processor that collapses detection pairs into time-correlated detection events at a fractional dividing point between the start and stop times of the pair.
template<typename DataTypes = default_data_types, bool UseStartChannel = false, typename Downstream>
auto	tcspc::time_correlate_at_midpoint (Downstream downstream)
	Create a processor that collapses detection pairs into time-correlated detection events at the midpoint between the start and stop times of the pair.
template<typename DataTypes = default_data_types, typename Downstream>
auto	tcspc::time_correlate_at_start (Downstream downstream)
	Create a processor that collapses detection pairs into time-correlated detection events at the start time of the pair.
template<typename DataTypes = default_data_types, typename Downstream>
auto	tcspc::time_correlate_at_stop (Downstream downstream)
	Create a processor that collapses detection pairs into time-correlated detection events at the stop time of the pair.

Function Documentation

negate_difftime()

template<typename DataTypes = default_data_types, typename Downstream>

auto tcspc::negate_difftime

(

Downstream

downstream

)

Create a processor that changes the sign of difftime in time-correlated detection events.

Template Parameters

DataTypes	data type set specifying difftime_type and output events
Downstream	downstream processor type (usually deduced)

Parameters

downstream

downstream processor

Returns

processor

Events handled

• tcspc::time_correlated_detection_event<DT>: pass through a copy (as tcspc::time_correlated_detection_event<DataTypes>) where the difftime has been negated
• All other types: pass through with no action
• Flush: pass through with no action

recover_order()

template<typename EventList, typename DataTypes = default_data_types, typename Downstream>

auto tcspc::recover_order	(	arg::time_window< typename DataTypes::abstime_type >	time_window,
		Downstream	downstream )

Create a processor that sorts events by abstime, provided that they are out of order only within a bounded time window.

Template Parameters

EventList	events to sort
DataTypes	data type set specifying abstime_type
Downstream	downstream processor type

Parameters

time_window	maximum abstime by which events are out of order; must not be negative
downstream	downstream processor

Returns

processor

Events handled

• Event (with abstime field): buffer and forward in abstime order once time_window has elapsed; throw data_validation_error if order could not be maintained due to event outside of time window
• Flush: emit any buffered Events in abstime order; pass through

remove_time_correlation()

template<typename DataTypes = default_data_types, typename Downstream>

auto tcspc::remove_time_correlation

(

Downstream

downstream

)

Create a processor that removes the difftime from detection events.

Template Parameters

DataTypes	data type set specifying abstime_type and channel_type
Downstream	downstream processor type

Parameters

downstream

downstream processor

Returns

processor

Events handled

• tcspc::time_correlated_detection_event<DT>: emit tcspc::detection_event<DataTypes>
• All other types: pass through with no action
• Flush: pass through with no action

time_correlate_at_fraction()

template<typename DataTypes = default_data_types, bool UseStartChannel = false, typename Downstream>

auto tcspc::time_correlate_at_fraction	(	arg::fraction< double >	fraction,
		Downstream	downstream )

Create a processor that collapses detection pairs into time-correlated detection events at a fractional dividing point between the start and stop times of the pair.

No reordering of events takes place. If the incoming events have their stop time in order and start time within a known time window of the stop time, then the output events are time-bound out-of-order with 1 - fraction times that window size.

Attention

The difference between the abstime of the start and stop event in each pair must be representable by abstime_type, difftime_type, and double without overflowing.

Template Parameters

DataTypes	data type set specifying abstime_type, channel_type, and difftime_type
UseStartChannel	if true, use the channel of the start of the pair as the channel of the emitted events; otherwise use the stop channel
Downstream	downstream processor type (usually deduced)

Parameters

fraction	the dividing fraction of start and stop time: 0.0 for start time; 1.0 for stop time; 0.5 for the midpoint
downstream	downstream processor

Returns

processor

Events handled

• tcspc::std::array<detection_event<DT>, 2>: emit tcspc::time_correlated_detection_event<DataTypes> with
  • abstime set to the fractional division point of the pair's abstimes
  • channel set to the channel of the first event of the pair if UseStartChannel is true, else of the second
  • difftime set to the abstime difference of the pair
• All other types: pass through with no action
• Flush: pass through with no action

time_correlate_at_midpoint()

template<typename DataTypes = default_data_types, bool UseStartChannel = false, typename Downstream>

auto tcspc::time_correlate_at_midpoint

(

Downstream

downstream

)

Create a processor that collapses detection pairs into time-correlated detection events at the midpoint between the start and stop times of the pair.

No reordering of events takes place. If the incoming events have their stop time in order and start time within a known time window of the stop time, then the output events are time-bound out-of-order with half of that window size.

Attention

The difference between the abstime of the start and stop event in each pair must be representable by both abstime_type and difftime_type without overflowing.

Template Parameters

DataTypes	data type set specifying abstime_type, channel_type, and difftime_type
UseStartChannel	if true, use the channel of the start of the pair as the channel of the emitted events; otherwise use the stop channel
Downstream	downstream processor type (usually deduced)

Parameters

downstream

downstream processor

Returns

processor

Events handled

• tcspc::std::array<detection_event<DT>, 2>: emit tcspc::time_correlated_detection_event<DataTypes> with
  • abstime set to the midpoint of the pair's abstimes
  • channel set to the channel of the first event of the pair if UseStartChannel is true, else of the second
  • difftime set to the abstime difference of the pair
• All other types: pass through with no action
• Flush: pass through with no action

time_correlate_at_start()

template<typename DataTypes = default_data_types, typename Downstream>

auto tcspc::time_correlate_at_start

(

Downstream

downstream

)

Create a processor that collapses detection pairs into time-correlated detection events at the start time of the pair.

No reordering of events takes place. If the incoming events have their stop time in order and start time within a known time window of the stop time, then the output events are time-bound out-of-order with that window size.

Attention

The difference between the abstime of the start and stop event in each pair must be representable by both abstime_type and difftime_type without overflowing.

Template Parameters

DataTypes	data type set specifying abstime_type, channel_type, and difftime_type
Downstream	downstream processor type (usually deduced)

Parameters

downstream

downstream processor

Returns

processor

Events handled

• tcspc::std::array<detection_event<DT>, 2>: emit tcspc::time_correlated_detection_event<DataTypes> with
  • abstime set equal to that of the first event of the pair
  • channel set to the channel of the first event of the pair
  • difftime set to the abstime difference of the pair
• All other types: pass through with no action
• Flush: pass through with no action

time_correlate_at_stop()

template<typename DataTypes = default_data_types, typename Downstream>

auto tcspc::time_correlate_at_stop

(

Downstream

downstream

)

Create a processor that collapses detection pairs into time-correlated detection events at the stop time of the pair.

No reordering of events takes place. The output events are in order if the stop times of the incoming pairs are in order.

Attention

The difference between the abstime of the start and stop event in each pair must be representable by both abstime_type and difftime_type without overflowing.

Template Parameters

DataTypes	data type set specifying abstime_type, channel_type, and difftime_type
Downstream	downstream processor type (usually deduced)

Parameters

downstream

downstream processor

Returns

processor

Events handled

• tcspc::std::array<detection_event<DT>, 2>: emit tcspc::time_correlated_detection_event<DataTypes> with
  • abstime set equal to that of the second event of the pair
  • channel set to the channel of the second event of the pair
  • difftime set to the abstime difference of the pair
• All other types: pass through with no action
• Flush: pass through with no action