LAL  7.2.0.1-a5e7375

Detailed Description

This header file provides routines and structures to create and store window functions (also called a taper, lag window, or apodization function).

Synopsis

#include <lal/Window.h>

The Header Window.h package defines two data types, the REAL4Window and REAL8Window types. These are suitable for storing window function data, providing storage for a sequence of samples as well as metadata about the window such as the sum-of-squarse of the samples. The package also provides a collection of functions to construct a variety of pre-defined window functions.

The use of window functions in signal analysis is well documented in many places.

Definitions of most of the window functions can be found in Numerical Recipes [24] equations 13.4.13-13.4.15. Definitions of the remaining windows can be found in Spectral analysis for physical applications [23] Section 6.11. Definition of the Kaiser window can be found in Discrete-time Signal Processing by Oppenheim and Schafer, p.474.

These functions create or destroy a time-domain window function in a vector of specified length. If you wish to construct a custom window, call XLALCreateRectangularREAL8Window() (or the REAL4 version), then replace the samples inside it with your own, and update the sumofsquares and sum elements. If the window function proves useful, consider adding it here so that others can benefit.

It is convenient to describe the windows as functions on the normalized domain \(y \in [-1, 1]\). The window is zero outside this domain. The window functions defined in this package are as follows.

Rectangle

\begin{equation} w(y) = 1. \end{equation}

Hann

\begin{equation} w(y) = \cos^2 \frac{\pi}{2} y. \end{equation}

Welch

\begin{equation} w(y) = 1 - y^2. \end{equation}

Bartlett

\begin{equation} w(y) = 1 - |y|. \end{equation}

Parzen

\begin{equation} w(y) = \left\{ \begin{array}{ll} 1 - 6 y^2 (1 - |y|) & |y| \leq 1 / 2, \\ 2 (1 - |y|)^3 & |y| > 1 / 2. \end{array}\right. \end{equation}

Papoulis

\begin{equation} w(y) = \frac{1}{\pi} \sin \pi |y| + (1 - |y|) \cos \pi |y|. \end{equation}

Hamming

\begin{equation} w(y) = 0.08 + 0.92 \cos^{2} \frac{\pi}{2} y. \end{equation}

This is the same as the Hann window, but with an additional DC bias, or "foot," of 0.08.

Kaiser

\begin{equation} w(y) = I_0 \left( \beta \sqrt{1-y^2} \right) / I_0(\beta), \end{equation}

where \(I_0(x)\) is the \(0\)th order, modified Bessel function of the first kind. The shape parameter \(\beta \in [0, \infty]\) sets the sharpness of the central peak. \(\beta = 0\) yields the rectangle window, \(\beta \rightarrow \infty\) yields a \(\delta\) function with a single non-zero sample in the middle. This window is difficult to compute for large \(\beta\), and an asymptotic approximation is used for \(\beta \ge 705\). A linearly-interpolated transition occurs between \(\beta = 695\) and \(\beta = 705\). Finite-difference derivatives of the window with respect to \(\beta\) are unlikely to work well in this regime.

Creighton

\begin{equation} w(y) = \exp \left( -\beta \frac{y^2}{1 - y^2} \right). \end{equation}

This window function is based on a fairly standard \(C_{\infty}\) test function used in distribution theory, e.g. Green's Functions and Boundary Value Problems [28] , by Stakgold. The shape parameter \(\beta \in [0, \infty]\) sets the sharpness of the central peak. \(\beta = 0\) yields the rectangle window, \(\beta \rightarrow \infty\) yields a \(\delta\) function with a single non-zero sample in the middle.

Tukey

\begin{equation} w(y) = \left\{ \begin{array}{ll} \sin^2 \left[ \frac{\pi}{2} (|y| - 1) / \beta \right] & |y| \geq 1 - \beta, \\ 1 & |y| < 1 - \beta. \end{array} \right. \end{equation}

The shape parameter \(\beta \in [0, 1]\) sets what fraction of the window is spanned by the tapers. \(\beta = 0\) yields the rectangle window, \(\beta = 1\) yields the Hann window.

Gauss

\begin{equation} w(y) = \exp \left( -\frac{1}{2} \beta^{2} y^{2} \right). \end{equation}

The shape parameter \(\beta \in [0, \infty]\) sets the sharpness of the central peak. \(\beta = 0\) yields the rectangle window, \(\beta \rightarrow \infty\) yields a \(\delta\) function with a single non-zero sample in the middle.

Lanczos

\begin{equation} w(y) = \frac{\sin \pi y}{\pi y}. \end{equation}

The Lanczos window is the central lobe of the sinc function. This is used, for example, in finite impulse response resampling to modulate a truncated sinc interpolating kernel.

These window functions are shown in this figure, showing various windows as functions of the normalized independend variable \(y\), choosing \(\beta = 6\) for the Kaiser window, \(\beta = 2\) for the Creighton window, \(\beta = 0.5\) for the Tukey window, and \(\beta = 3\) for the Gauss window.

window_t.png
Various windows as functions of the normalized independend variable y

For a vector of length \(L\) (an integer), the mapping from integer array index \(i\) to normalized co-ordinate \(y\) is

\begin{equation} y(i) = \left\{ \begin{array}{ll} 0 & L \le 1, \\ 2 i / (L - 1) - 1 & L > 1, \end{array} \right. \end{equation}

where \(0 \le i < L\), and floating-point division is used. This agrees with J. G. Proakis and D. G. Manolakis, Digital Signal Processing [25] , and MatLab. The first sample is \(y = -1\), the last sample is \(y = +1\). For odd-lengthed vectors, the middle sample is \(y = 0\), while for even-lengthed vectors \(y = 0\) occurs half-way between the two middle samples. Substituting \(y(i)\) into the definitions of the window functions above yields \(w(i)\), the value of the window function at the integer sample \(i\).

The Fourier transforms of the windows are shown as functions of \(1 / y\) in this figure, showing frequency behaviour of various windows as functions of the inverse of the normalized independend variable \(y\), choosing \(\beta = 6\) for the Kaiser window, \(\beta = 2\) for the Creighton window, \(\beta = 0.5\) for the Tukey window, and \(\beta = 3\) for the Gauss window.

window_f.png
Frequency behaviour of various windows as functions of the inverse of the normalized independend variable y

Since the Fourier transform of windowed data is the Fourier transform of the data convolved with the Fourier transform of the window, this figure is the major guideline for selecting a window. One can see that windows with a narrow central lobe tend to have higher sidelobes, and windows which suppress their low-order sidelobes tend to have more power in the high-order sidelobes. The choice of window thus depends on whether one is trying to resolve nearby spectral features of comparable magnitude (suggesting a rectangular or a Welch window), to reduce spectral bias and low-order sidelobes (a Hamming or Kaiser window), or to measure a broad spectrum with a large dynamical range (a Creighton or a Papoulis window).

Prototypes

REAL4WindowXLALCreateREAL4WindowFromSequence (REAL4Sequence *sequence)
 Single-precision version of XLALCreateREAL8WindowFromSequence(). More...
 
REAL8WindowXLALCreateREAL8WindowFromSequence (REAL8Sequence *sequence)
 Constructs a new REAL8Window from a REAL8Sequence. More...
 
REAL4WindowXLALCreateRectangularREAL4Window (UINT4 length)
 
REAL4WindowXLALCreateHannREAL4Window (UINT4 length)
 
REAL4WindowXLALCreateWelchREAL4Window (UINT4 length)
 
REAL4WindowXLALCreateBartlettREAL4Window (UINT4 length)
 
REAL4WindowXLALCreateParzenREAL4Window (UINT4 length)
 
REAL4WindowXLALCreatePapoulisREAL4Window (UINT4 length)
 
REAL4WindowXLALCreateHammingREAL4Window (UINT4 length)
 
REAL4WindowXLALCreateKaiserREAL4Window (UINT4 length, REAL4 beta)
 
REAL4WindowXLALCreateCreightonREAL4Window (UINT4 length, REAL4 beta)
 
REAL4WindowXLALCreateTukeyREAL4Window (UINT4 length, REAL4 beta)
 
REAL4WindowXLALCreateGaussREAL4Window (UINT4 length, REAL4 beta)
 
REAL4WindowXLALCreateLanczosREAL4Window (UINT4 length)
 
REAL8WindowXLALCreateRectangularREAL8Window (UINT4 length)
 
REAL8WindowXLALCreateHannREAL8Window (UINT4 length)
 
REAL8WindowXLALCreateWelchREAL8Window (UINT4 length)
 
REAL8WindowXLALCreateBartlettREAL8Window (UINT4 length)
 
REAL8WindowXLALCreateParzenREAL8Window (UINT4 length)
 
REAL8WindowXLALCreatePapoulisREAL8Window (UINT4 length)
 
REAL8WindowXLALCreateHammingREAL8Window (UINT4 length)
 
REAL8WindowXLALCreateKaiserREAL8Window (UINT4 length, REAL8 beta)
 
REAL8WindowXLALCreateCreightonREAL8Window (UINT4 length, REAL8 beta)
 
REAL8WindowXLALCreateTukeyREAL8Window (UINT4 length, REAL8 beta)
 
REAL8WindowXLALCreateGaussREAL8Window (UINT4 length, REAL8 beta)
 
REAL8WindowXLALCreateLanczosREAL8Window (UINT4 length)
 
void XLALDestroyREAL4Window (REAL4Window *window)
 
void XLALDestroyREAL8Window (REAL8Window *window)
 
REAL4SequenceXLALUnitaryWindowREAL4Sequence (REAL4Sequence *sequence, const REAL4Window *window)
 Single-precision version of XLALUnitaryWindowREAL8Sequence(). More...
 
COMPLEX8SequenceXLALUnitaryWindowCOMPLEX8Sequence (COMPLEX8Sequence *sequence, const REAL4Window *window)
 Single-precision complex version of XLALUnitaryWindowREAL8Sequence(). More...
 
REAL8SequenceXLALUnitaryWindowREAL8Sequence (REAL8Sequence *sequence, const REAL8Window *window)
 Multiply a REAL8Sequence in-place by a REAL8Window with a normalization that preserves the variance of a zero-mean stationary Gaussian random process. More...
 
COMPLEX16SequenceXLALUnitaryWindowCOMPLEX16Sequence (COMPLEX16Sequence *sequence, const REAL8Window *window)
 Double-precision complex version of XLALUnitaryWindowREAL8Sequence(). More...
 
REAL8WindowXLALCreateNamedREAL8Window (const char *windowName, REAL8 beta, UINT4 length)
 Generic window-function wrapper, allowing to select a window by its name. More...
 
REAL4WindowXLALCreateNamedREAL4Window (const char *windowName, REAL8 beta, UINT4 length)
 

Data Structures

struct  REAL4Window
 Structure for storing REAL4 window function data, providing storage for a sequence of samples as well as metadata about the window such as the sum-of-squarse of the samples. More...
 
struct  REAL8Window
 Structure for storing REAL8 window function data, providing storage for a sequence of samples as well as metadata about the window such as the sum-of-squarse of the samples. More...
 

Function Documentation

◆ XLALCreateREAL4WindowFromSequence()

REAL4Window* XLALCreateREAL4WindowFromSequence ( REAL4Sequence sequence)

Single-precision version of XLALCreateREAL8WindowFromSequence().

Definition at line 225 of file Window.c.

◆ XLALCreateREAL8WindowFromSequence()

REAL8Window* XLALCreateREAL8WindowFromSequence ( REAL8Sequence sequence)

Constructs a new REAL8Window from a REAL8Sequence.

The window "owns" the sequence, when the window is destroyed the sequence will be destroyed with it. If this function fails, the sequence is destroyed. The return value is the address of the newly allocated REAL8Window or NULL on failure.

Definition at line 204 of file Window.c.

◆ XLALCreateRectangularREAL4Window()

REAL4Window* XLALCreateRectangularREAL4Window ( UINT4  length)

Definition at line 685 of file Window.c.

◆ XLALCreateHannREAL4Window()

REAL4Window* XLALCreateHannREAL4Window ( UINT4  length)

Definition at line 691 of file Window.c.

◆ XLALCreateWelchREAL4Window()

REAL4Window* XLALCreateWelchREAL4Window ( UINT4  length)

Definition at line 697 of file Window.c.

◆ XLALCreateBartlettREAL4Window()

REAL4Window* XLALCreateBartlettREAL4Window ( UINT4  length)

Definition at line 703 of file Window.c.

◆ XLALCreateParzenREAL4Window()

REAL4Window* XLALCreateParzenREAL4Window ( UINT4  length)

Definition at line 709 of file Window.c.

◆ XLALCreatePapoulisREAL4Window()

REAL4Window* XLALCreatePapoulisREAL4Window ( UINT4  length)

Definition at line 715 of file Window.c.

◆ XLALCreateHammingREAL4Window()

REAL4Window* XLALCreateHammingREAL4Window ( UINT4  length)

Definition at line 721 of file Window.c.

◆ XLALCreateKaiserREAL4Window()

REAL4Window* XLALCreateKaiserREAL4Window ( UINT4  length,
REAL4  beta 
)

Definition at line 727 of file Window.c.

◆ XLALCreateCreightonREAL4Window()

REAL4Window* XLALCreateCreightonREAL4Window ( UINT4  length,
REAL4  beta 
)

Definition at line 733 of file Window.c.

◆ XLALCreateTukeyREAL4Window()

REAL4Window* XLALCreateTukeyREAL4Window ( UINT4  length,
REAL4  beta 
)

Definition at line 739 of file Window.c.

◆ XLALCreateGaussREAL4Window()

REAL4Window* XLALCreateGaussREAL4Window ( UINT4  length,
REAL4  beta 
)

Definition at line 745 of file Window.c.

◆ XLALCreateLanczosREAL4Window()

REAL4Window* XLALCreateLanczosREAL4Window ( UINT4  length)

Definition at line 751 of file Window.c.

◆ XLALCreateRectangularREAL8Window()

REAL8Window* XLALCreateRectangularREAL8Window ( UINT4  length)

Definition at line 350 of file Window.c.

◆ XLALCreateHannREAL8Window()

REAL8Window* XLALCreateHannREAL8Window ( UINT4  length)

Definition at line 367 of file Window.c.

◆ XLALCreateWelchREAL8Window()

REAL8Window* XLALCreateWelchREAL8Window ( UINT4  length)

Definition at line 384 of file Window.c.

◆ XLALCreateBartlettREAL8Window()

REAL8Window* XLALCreateBartlettREAL8Window ( UINT4  length)

Definition at line 402 of file Window.c.

◆ XLALCreateParzenREAL8Window()

REAL8Window* XLALCreateParzenREAL8Window ( UINT4  length)

Definition at line 421 of file Window.c.

◆ XLALCreatePapoulisREAL8Window()

REAL8Window* XLALCreatePapoulisREAL8Window ( UINT4  length)

Definition at line 442 of file Window.c.

◆ XLALCreateHammingREAL8Window()

REAL8Window* XLALCreateHammingREAL8Window ( UINT4  length)

Definition at line 461 of file Window.c.

◆ XLALCreateKaiserREAL8Window()

REAL8Window* XLALCreateKaiserREAL8Window ( UINT4  length,
REAL8  beta 
)

Definition at line 478 of file Window.c.

◆ XLALCreateCreightonREAL8Window()

REAL8Window* XLALCreateCreightonREAL8Window ( UINT4  length,
REAL8  beta 
)

Definition at line 563 of file Window.c.

◆ XLALCreateTukeyREAL8Window()

REAL8Window* XLALCreateTukeyREAL8Window ( UINT4  length,
REAL8  beta 
)

Definition at line 597 of file Window.c.

◆ XLALCreateGaussREAL8Window()

REAL8Window* XLALCreateGaussREAL8Window ( UINT4  length,
REAL8  beta 
)

Definition at line 623 of file Window.c.

◆ XLALCreateLanczosREAL8Window()

REAL8Window* XLALCreateLanczosREAL8Window ( UINT4  length)

Definition at line 650 of file Window.c.

◆ XLALDestroyREAL4Window()

void XLALDestroyREAL4Window ( REAL4Window window)

Definition at line 757 of file Window.c.

◆ XLALDestroyREAL8Window()

void XLALDestroyREAL8Window ( REAL8Window window)

Definition at line 668 of file Window.c.

◆ XLALUnitaryWindowREAL4Sequence()

REAL4Sequence* XLALUnitaryWindowREAL4Sequence ( REAL4Sequence sequence,
const REAL4Window window 
)

Single-precision version of XLALUnitaryWindowREAL8Sequence().

Definition at line 304 of file Window.c.

◆ XLALUnitaryWindowCOMPLEX8Sequence()

COMPLEX8Sequence* XLALUnitaryWindowCOMPLEX8Sequence ( COMPLEX8Sequence sequence,
const REAL4Window window 
)

Single-precision complex version of XLALUnitaryWindowREAL8Sequence().

Definition at line 324 of file Window.c.

◆ XLALUnitaryWindowREAL8Sequence()

REAL8Sequence* XLALUnitaryWindowREAL8Sequence ( REAL8Sequence sequence,
const REAL8Window window 
)

Multiply a REAL8Sequence in-place by a REAL8Window with a normalization that preserves the variance of a zero-mean stationary Gaussian random process.

If the window's length is N samples and its sum-of-squares is S, then the input sequence is multiplied by the window * \(\sqrt{N / S}\). Returns the address of the REAL8Sequence or NULL on failure.

Definition at line 264 of file Window.c.

◆ XLALUnitaryWindowCOMPLEX16Sequence()

COMPLEX16Sequence* XLALUnitaryWindowCOMPLEX16Sequence ( COMPLEX16Sequence sequence,
const REAL8Window window 
)

Double-precision complex version of XLALUnitaryWindowREAL8Sequence().

Definition at line 284 of file Window.c.

◆ XLALCreateNamedREAL8Window()

REAL8Window* XLALCreateNamedREAL8Window ( const char *  windowName,
REAL8  beta,
UINT4  length 
)

Generic window-function wrapper, allowing to select a window by its name.

windowBeta must be set to '0' for windows without parameter.

Definition at line 855 of file Window.c.

◆ XLALCreateNamedREAL4Window()

REAL4Window* XLALCreateNamedREAL4Window ( const char *  windowName,
REAL8  beta,
UINT4  length 
)

Definition at line 914 of file Window.c.