Time correlation processors

Description

Processors for time correlation.

Topics
	Pairing processors
	Processors for finding pairs of detection events.

Functions
template<typename EventList, typename NumericTraits = default_numeric_traits, typename Downstream>
auto	tcspc::recover_order (arg::time_window< typename NumericTraits::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 NumericTraits = default_numeric_traits, typename Downstream>
auto	tcspc::remove_time_correlation (Downstream downstream)
	Create a processor that removes the difftime from detection events.
template<typename NumericTraits = default_numeric_traits, 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 NumericTraits = default_numeric_traits, 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 NumericTraits = default_numeric_traits, 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 NumericTraits = default_numeric_traits, 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

recover_order()

template<typename EventList, typename NumericTraits = default_numeric_traits, typename Downstream>

auto tcspc::recover_order	(	arg::time_window< typename NumericTraits::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; every event type must be move-constructible and move-assignable (events are buffered and reordered in a vector). Const-lvalue inputs are additionally copied into the buffer, so a non-copy-constructible event type must be passed as an rvalue.
NumericTraits	numeric traits 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 NumericTraits = default_numeric_traits, typename Downstream>

auto tcspc::remove_time_correlation

(

Downstream

downstream

)

Create a processor that removes the difftime from detection events.

Template Parameters

NumericTraits	numeric traits specifying abstime_type and channel_type
Downstream	downstream processor type

Parameters

downstream

downstream processor

Returns

processor

Events handled

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

time_correlate_at_fraction()

template<typename NumericTraits = default_numeric_traits, 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

NumericTraits	numeric traits 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<NT>, 2>: emit tcspc::time_correlated_detection_event<NumericTraits> 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 NumericTraits = default_numeric_traits, 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

NumericTraits	numeric traits 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<NT>, 2>: emit tcspc::time_correlated_detection_event<NumericTraits> 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 NumericTraits = default_numeric_traits, 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

NumericTraits	numeric traits 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<NT>, 2>: emit tcspc::time_correlated_detection_event<NumericTraits> 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 NumericTraits = default_numeric_traits, 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

NumericTraits	numeric traits 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<NT>, 2>: emit tcspc::time_correlated_detection_event<NumericTraits> 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