./toolbox
dcshift.pro

Last modification date:

Wed Sep 28 13:27:10 2016

dcshift

procedure dcshift, dc, offset, [/wrap], [ftol=floating point], [/linear], [/quadratic], [/lsquadratic], [/spline], [/cubic], [/nowelsh], [/nopad], [blanks=variable], [ok=variable]

Procedure to shift data in a data container by a given number of channels.

Shift the data in the data container by the given number of channels (which may be a floating point number containing fractional channels) such that data in channel i before the shift is found in channel i+offset after the shift. The data's reference channel is also shifted so that features should remain stationary when displayed except when the x-axis is channels. Shifted data is replaced with zeros unless the /wrap keyword is set in which case the data wraps around as necessary during the shift. Data are first shifted by the nearest integer number of channels and then the result is shifted by the remaining fractional channel if that fraction channel is more than ftol.

Currently, the default fractional shifting is done using an FFT windowed using a Welch function to reduce ringing as a result of the FFT. Set ftol to a number >= 1 to turn off all fractional shifting. See below for alternative methods. FFT is the default because that is the method that UniPOPS used in its SHIFT verb.

Use one of xshift, vshift, or fshift to calculate the offset to align this data with data in an ongoing accumulation.

Windowing using the Welsh function reduces ringing at the expense of the high-order terms in the FFT. This very slightly broadens features. This can be turned off using the /nowelsh keyword.

The data are padded with 0s to the next higher power of two as an intermediate step (the final result will have the original size of the data). This is done to reduce ringing due to any discontinuities between the two ends of the data. This can be turned off using the /nopad keyword. If there are any bad data points, they are interpolated using a linear interpolation prior to the FFT and then reblanked after the FFT.

linear, quadratic, least squares quadratic, spline, and cubic interpolation are all available as alternatives to the default FFT based interpolation for the fractional part of the shift. The first 4 of these methods use the INTERPOL function and the cubic method uses the INTERPOLATE functions. Please see the IDL help on those functions for more information about them. The cubic function is a close approximation to a sinc function.

In some limited testing with GBT data, all of these interpolation methods agree reasonably well with each other. The linear interpolation is, not surprisingly, the fastest since it only uses 2 data points for each interpolated point. The quadratic and cubic methods both use 3 points for each interpolated point and both of those methods are not quite 2 times slower than the linear method. The FFT method (the default) is about another factor of 2 slower. Spline and least squares quadratic both use 4 data points for each interpolated point and they are substantially slower. Spline takes about 20 times longer and lsquadratic takes about 100 times as long as the linear interpolation.

If none of /linear, /spline, /quadratic, /lsquadratic, or /cubic are specified then an FFT is used for the fractional shift. It is an error to use more than one of these flags in the same call.

Uses

data_valid

Version

$Id$

Parameters
dc in/out, required variable	The data container to shift. The shift is done in place.
offset in, required floating point	The number of channels to shift the data (positive shifts things towards higher channels, negative shifts things towards lower channels).

Keywords
wrap in, optional boolean	Data shifted off one end of the array appears on the other end of the array (it wraps around as a result of the shift) when this is set. Otherwise, as data is shifted it is blanked (replaced by NaNs) and data shifted off the end is lost.
ftol in, optional floating point (def. 0.01)	Fractional shifts (the non-integer portion of offset) are only done when they are larger than ftol. Set this value to >= 1.0 to turn off all fractional shifts.
linear in, optional boolean	When set, use the linear interpolation provided by INTERPOL for any fractional shift larger than ftol.
quadratic in, optional boolean	When set, use the quadratic interpolation provided by INTERPOL for any fractional shift larger than ftol.
lsquadratic in, optional boolean	When set, use the lsquadratic (lest squares quadratic) interpolation provided by INTERPOL for any fractional shift larger than ftol.
spline in, optional boolean	When set, use the spline interpolation provided by INTERPOL for any fractional shift larger than ftol.
cubic in, optional boolean	When set, use the cubic interpolation provided by INTERPOLATE for any fractional shift larger than ftol. The value of the CUBIC keyword in the INTERPOLATE call is set to -0.5.
nowelsh in, optional boolean	When set, the shifted data is NOT windowed using the Welsh function. This is ignored when a non-FFT-based fraction shift is done
nopad in, optional boolean	When set, the data is NOT padded with 0s to the next higher power of 2 prior to the FFT and shift. The data are never padded for the non-FFT-based fractional shifts.
blanks out, optional variable	The shifted channel locations of all non-finite (blanks) channel values in the original, unshift data container. If there were no blank channels, this value is -1. If a blank channel is shifted out of the spectrum it is not included in this list (that may also result in a return value of -1). If there was a fractional shift and the resulting blank channel is now an extra channel wide then that is also reflected in this keyword. This array does not include the new blank values added during the shift to replace the shifted values. If the returned value is not -1 then all of the values in blanks are valid channel numbers and are blanked (not a number) in the shifted spectrum. This is primarily used by the dcfold procedure.
ok out, optional variable	This is set to 1 on success or 0 on failure (e.g. bad arguments).