Trigger Interpolation

Detailed Description

This module implements several algorithms for performing sub-sample interpolation of peaks in the output of a matched filter.

The interface for each algorithm is the same. To illustrate, here is a description of the interface for the 'QuadraticFit' algorithm.

In this example, the interpolation will take into account a given sample, the 5 samples before, and the 5 samples after, for a total of 11 samples.

To apply the interpolant to a time series, call XLALTriggerInterpolateQuadraticFit. It is requried that |y[0]| >= |y[i]| for all i from -window to +window. Suppose that you have a complex array y:

COMPLEX16 y[] = {...};

and suppose that the maximum of |y[i]| occurs at i = 8. To interpolate the time and complex value at which the maximum occurs, do the following:

double tmax;
COMPLEX16 ymax;
int result = XLALTriggerInterpolateQuadraticFit(interp, &tmax, &ymax, &y[8], 5);

Upon success, the return value is zero, the interpolated index of the maximum sample is 8 + *tmax, and the interpolated value is in ymax. Upon failure, the return value is nonzero and neither *tmax nor *ymax are modified.

The recommended algorithms are XLALTriggerInterpolateCubicSplineAmpPhase. and XLALTriggerInterpolateQuadraticFit. The XLALTriggerInterpolateCubicSpline and XLALTriggerInterpolateLanczos methods should not be used because they tend to exhibit oscillations between samples and may perform no better than the nearest-neighbor method; these two functions are preserved only for historical interest. The XLALTriggerInterpolateCubicSplineAmpPhase method is preferred over the XLALTriggerInterpolateQuadraticFit method because the former provides a continuous and smooth model for the signal at all times, whereas the latter does not.

Prototypes
int	XLALTriggerInterpolateCubicSplineAmpPhase (double *tmax, COMPLEX16 *ymax, const COMPLEX16 *y, unsigned int window)
	Catmull-Rom cubic spline interpolation on amplitude phase. More...
int	XLALTriggerInterpolateCubicSpline (double *tmax, COMPLEX16 *ymax, const COMPLEX16 *y, unsigned int window)
	Catmull-Rom cubic spline interpolation. More...
int	XLALTriggerInterpolateLanczos (double *tmax, COMPLEX16 *ymax, const COMPLEX16 *y, unsigned int window)
	Lanczos interpolation. More...
int	XLALTriggerInterpolateNearestNeighbor (double *tmax, COMPLEX16 *ymax, const COMPLEX16 *y, unsigned int window)
	Nearest-neighbor interpolation. More...
int	XLALTriggerInterpolateQuadraticFit (double *tmax, COMPLEX16 *ymax, const COMPLEX16 *y, unsigned int window)
	Quadratic fit. More...

Function Documentation

XLALTriggerInterpolateCubicSplineAmpPhase()

int XLALTriggerInterpolateCubicSplineAmpPhase	(	double *	tmax,
		COMPLEX16 *	ymax,
		const COMPLEX16 *	y,
		unsigned int	window
	)

Catmull-Rom cubic spline interpolation on amplitude phase.

Find the Catmull-Rom cubic spline interpolants that pass through the amplitude and phase of the data.

Warning

It is an error if the window size is less than 2.

Definition at line 315 of file TriggerInterpolate.c.

XLALTriggerInterpolateCubicSpline()

int XLALTriggerInterpolateCubicSpline	(	double *	tmax,
		COMPLEX16 *	ymax,
		const COMPLEX16 *	y,
		unsigned int	window
	)

Catmull-Rom cubic spline interpolation.

Find the Catmull-Rom cubic spline interpolants that pass through the real and imaginary parts of the data. Find the interpolated time by solving for the maximum of the sum of the squares of the two spline interpolants.

Warning

It is an error if the window size is less than 2.

Definition at line 233 of file TriggerInterpolate.c.

XLALTriggerInterpolateLanczos()

int XLALTriggerInterpolateLanczos	(	double *	tmax,
		COMPLEX16 *	ymax,
		const COMPLEX16 *	y,
		unsigned int	window
	)

Lanczos interpolation.

Convolve the data with a Lanczos reconstruction kernel and find the maximum of the absolute value using a one-dimensional numerical method.

Warning

It is an error if the window size is less than 1.

Definition at line 425 of file TriggerInterpolate.c.

XLALTriggerInterpolateNearestNeighbor()

int XLALTriggerInterpolateNearestNeighbor	(	double *	tmax,
		COMPLEX16 *	ymax,
		const COMPLEX16 *	y,
		unsigned int	window
	)

Nearest-neighbor interpolation.

Perform trivial, nearest-neighbor interpolation. Always sets *tmax = 0, *ymax = data[0].

XLALTriggerInterpolateQuadraticFit()

int XLALTriggerInterpolateQuadraticFit	(	double *	tmax,
		COMPLEX16 *	ymax,
		const COMPLEX16 *	y,
		unsigned int	window
	)

Quadratic fit.

Fit a quadratic function to the absolute value of the data. Report the sample index of the vertex if the vertex is a maximum. Note that this is not actually an interpolant because it is not guaranteed to agree with the input data points, and that it always sets *ymax = data[0].

Warning

It is an error if the window size is less than 1.

Definition at line 489 of file TriggerInterpolate.c.