Timing signal modeling processors

Description

Processors for fitting and extrapolating timing models.

Functions
template<typename DataTypes = default_data_types, typename Downstream>
auto	tcspc::add_count_to_periodic_sequences (arg::count< std::size_t > count, Downstream downstream)
	Create a processor that emits a linear timing event based on tcspc::periodic_sequence_model_event by adding a fixed sequence length.
template<typename TickEvent, typename StartEvent, typename StopEvent, typename Downstream>
auto	tcspc::convert_sequences_to_start_stop (arg::count< std::size_t > count, Downstream downstream)
	Create a processor that converts sequences of ticks to sequences of start-stop event pairs with no gaps.
template<typename DataTypes = default_data_types, typename Downstream>
auto	tcspc::extrapolate_periodic_sequences (arg::tick_index< std::size_t > tick_index, Downstream downstream)
	Create a processor that emits an extrapolated one-shot timing event based on tcspc::periodic_sequence_model_event.
template<typename Event, typename DataTypes = default_data_types, typename Downstream>
auto	tcspc::fit_periodic_sequences (arg::length< std::size_t > length, arg::min_interval< double > min_interval, arg::max_interval< double > max_interval, arg::max_mse< double > max_mse, Downstream downstream)
	Create a processor that fits fixed-length periodic sequences of events and estimates the start time and interval.
template<typename DataTypes = default_data_types, typename Downstream>
auto	tcspc::retime_periodic_sequences (arg::max_time_shift< typename DataTypes::abstime_type > max_time_shift, Downstream downstream)
	Create a processor that adjusts the abstime of tcspc::periodic_sequence_model_event to be earlier than the modeled sequence.

Function Documentation

add_count_to_periodic_sequences()

template<typename DataTypes = default_data_types, typename Downstream>

auto tcspc::add_count_to_periodic_sequences	(	arg::count< std::size_t >	count,
		Downstream	downstream )

Create a processor that emits a linear timing event based on tcspc::periodic_sequence_model_event by adding a fixed sequence length.

Events of type tcspc::periodic_sequence_model_event (with matching abstime_type) are converted to tcspc::real_linear_timing_event with the same abstime, delay, and interval, and with the given count.

Typically, this processor is applied to the output of tcspc::retime_periodic_sequences().

All other events are passed through.

Template Parameters

DataTypes	data type set specifying abstime_type and emitted events
Downstream	downstream processor type

Parameters

count	sequence length to use
downstream	downstream processor

Returns

processor

Events handled

• tcspc::periodic_sequence_model_event<DT>: emit tcspc::real_linear_timing_event<DataTypes> with the same abstime, delay, and interval and added count.
• All other types: pass through with no action
• Flush: pass through with no action

convert_sequences_to_start_stop()

template<typename TickEvent, typename StartEvent, typename StopEvent, typename Downstream>

auto tcspc::convert_sequences_to_start_stop	(	arg::count< std::size_t >	count,
		Downstream	downstream )

Create a processor that converts sequences of ticks to sequences of start-stop event pairs with no gaps.

Every sequence of count + 1 events of type TickEvent is replaced by a series of StartEvent and StopEvent events that bracket each tick interval. The StopEvent for one interval and the StartEvent for the next interval are emitted with the same abstime.

This can be used to synthesize the start and stop events for tcspc::scan_histograms(), given a single sequence of timing markers. (Another method is to synthesize the stop events as a delayed copy of the start events, using tcspc::generate() with tcspc::one_shot_timing_generator.)

Attention

Beware of fencepost errors: count is the number of start-stop pairs in each sequence, which is one less than the number of ticks needed to produce them.

All other events are passed through.

Template Parameters

TickEvent	tick event type
StartEvent	start event type to emit
StopEvent	stop event type to emit
Downstream	downstream processor type

Parameters

count	sequence length of the emitted start-stop pairs
downstream	downstream processor

Returns

processor

Events handled

• TickEvent: emit StopEvent if not the first tick in a sequence, then StartEvent if not the last tick in a sequence, where a sequence is every series of count + 1 ticks
• All other types: pass through with no action
• Flush: pass through with no action

extrapolate_periodic_sequences()

template<typename DataTypes = default_data_types, typename Downstream>

auto tcspc::extrapolate_periodic_sequences	(	arg::tick_index< std::size_t >	tick_index,
		Downstream	downstream )

Create a processor that emits an extrapolated one-shot timing event based on tcspc::periodic_sequence_model_event.

Events of type tcspc::periodic_sequence_model_event (with matching abstime_type) are converted to tcspc::real_one_shot_timing_event with the same abstime and a delay computed by extrapolating the model sequence to the given tick_index.

All other events are passed through.

Remarks

This is one way to synthesize an extra tick needed for use with tcspc::convert_sequences_to_start_stop().

Attention

The abstime of incoming events must be monotonically non-decreasing and must not wrap around. The abstime of the result must not overflow or underflow.

Template Parameters

DataTypes	data type set specifying abstime_type and emitted events
Downstream	downstream processor type

Parameters

tick_index	tick index to extrapolate to
downstream	downstream processor

Returns

processor

Events handled

• tcspc::periodic_sequence_model_event<DT>: emit tcspc::real_one_shot_timing_event<DataTypes> with the same abstime but the delay offset by interval times tick_index
• All other types: pass through with no action
• Flush: pass through with no action

fit_periodic_sequences()

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

auto tcspc::fit_periodic_sequences	(	arg::length< std::size_t >	length,
		arg::min_interval< double >	min_interval,
		arg::max_interval< double >	max_interval,
		arg::max_mse< double >	max_mse,
		Downstream	downstream )

Create a processor that fits fixed-length periodic sequences of events and estimates the start time and interval.

The processor accepts a single event type, Event. Every length events are grouped together and a model of regularly spaced events is fit to their abstimes. If the fit is successful (see below for criteria), then a tcspc::periodic_sequence_model_event is emitted, containing the fit results, upon receiving the last Event of the series. If the fit is not successful, processing is halted with an error.

The emitted event's abstime is set to the abstime of the last observed Event (during which handling the event is emitted). The emitted fit parameters consist of a start offset and interval. The start offset is relative to the emitted event's abstime.

The fit is considered successful if all of the following criteria are satisfied:

1. the mean squared error is no more than max_mse
2. the estimated event interval is within [min_interval, max_interval]

This processor does not pass through Event, but passes through any other event.

Attention

The abstime of incoming events must be monotonically non-decreasing and must not wrap around.

Template Parameters

Event	event whose timing is to be fit
DataTypes	data type set specifying data types for emitted event
Downstream	downstream processor type

Parameters

length	number of Event events in each sequence to fit
min_interval	minimum estimated event interval for the fit to be considered successful
max_interval	maximum estimated event interval for the fit to be considered successful
max_mse	allowed maximum mean squared error for the fit to be considered successful
downstream	downstream processor

Returns

processor

Events handled

• Event: buffer every length events, fit to model, then emit tcspc::periodic_sequence_model_event<DataTypes> with the fit results; throw tcspc::model_fit_error if fit criteria were not met
• All other types: pass through with no action
• Flush: pass through with no action

retime_periodic_sequences()

template<typename DataTypes = default_data_types, typename Downstream>

auto tcspc::retime_periodic_sequences	(	arg::max_time_shift< typename DataTypes::abstime_type >	max_time_shift,
		Downstream	downstream )

Create a processor that adjusts the abstime of tcspc::periodic_sequence_model_event to be earlier than the modeled sequence.

Events of type tcspc::periodic_sequence_model_event (with matching abstime_type) have their abstime and delay normalized, such that delay is at least 1.0 and no more than 2.0, without altering the modeled tick sequence.

This means that the events have an abstime before any of the modeled tick times of the sequences they represent, so that they can be used for event generation downstream.

The choice of the start_time range of [1.0, 2.0) (rather than [0.0, 1.0)) is to avoid subnormal floating point values.

If the adjustment would result in altering the abstime by more than max_time_shift (in either direction), processing is halted with an error. This can be used to help make sure that the emitted events have a monotonically increasing abstime.

If the adjustment would result in a negative abstime, but abstime_type is an unsigned integer type, processing is halted with an error.

No other events are handled (because this processor would cause their abstimes to be out of order).

Attention

The abstime of incoming events must be monotonically non-decreasing and must not wrap around. The abstime of the result must not overflow or underflow.

See also

tcspc::fit_periodic_sequences()

Template Parameters

DataTypes	data type set specifying abstime_type and emitted events
Downstream	downstream processor type

Parameters

max_time_shift	maximum allowed (absolute value of) timeshift
downstream	downstream processor

Returns

processor

Events handled

• tcspc::periodic_sequence_model_event<DT>: emit with normalized abstime and delay as tcspc::periodic_sequence_model_event<DataTypes>; throw tcspc::data_validation_error if the time shift or result range criteria are not met
• Flush: pass through with no action