/ 
PDL-DSP-Windows-0.002
River stage one • 1 direct dependent • 2 total dependents
/ PDL::DSP::Windows

mkwindows.pl

Script to write Windows.pm.

------------------------------------------------------------------- Routines to write code defining pdls of range of points used in window functions. -------------------------------------------------------------------

-------------------------------------------------------------------

Specification for subroutines generating specific named window functions.

%window_definitions -- hash defining window functions. Information
in this hash describes how to write the window function sub, write
the documentation, and anything else.

hash key -- 'subname'; the subroutine name for the window function

 For each hash key 'subname', the value is a hash ref with the following keys. Most
 of these are optional. Or supply undef to be explicit.
 
arrcode  -- code ref that writes code generating 
    an pdl array of points used in several windows. 
    Eg $N points from -1 to 1 , or cos(0) to cos(PI), etc.

arrcode1 -- another array of points. Some windows need two.

wincode -- code written into window sub beneath the code generated by arrcode.
    The string 'arr' will be substituted with code generating a piddle defined
    by arrcode.

periodic_wincode -- like wincode, but defines code for periodic window function. For most
      windows, wincode is sufficient, because a parameter is passed to arrcode which
      is sufficient to choose between symmetric and periodic. In more complicated cases,
      wincode is used for symmetric, and periodic_wincode for periodic.

noper -- If set, no periodic version of the window is generated.

params -- parameter(s) that the window function takes (other than $N).
       (a string or array of strings)

fn -- A window name for use in docs. If omitted, the capitalized sub name is used. If string
      begins with '*', then an entire descriptive sentence is expected, rather than
      just a proper name.

pfn -- An optional shorter window name. If 'fn' is long, pfn is returned by method get_name.
       For use in plot titles, etc. Also written first in main doc entry for 'subname'.

descr -- An optional description written into the doc for 'subname'.

alias -- other names for the window function. This is only used in the documentation.
         string or array of strings. It is not an alias for any software identifier.p

note -- A note written at the end of the doc entry for this window 'subname'.

ref -- number for citing our source for the window definition. This cites a source listed
       at the bottom of the docs.

seealso -- link to other routines in this package

octave, matlab -- equivalent routine name in alien software

skip -- skip this window definition. Do not process it. For debugging/broken code.

-------------------------------------------------------------------

$prname$sig

$print_fullname$fullname$ref$descr$alias$periodic$codedoc$note$octave$matlab$seealso

Symmetric window functions

EOL

 foreach (sort keys %winsubs ) {
     print_func_doc1($_);
  }

return();  ##### skip the periodic functions

print $OH <<"EOL";

Periodic window functions

EOL

foreach (sort keys %winpersubs ) {
    my $nameper = add_periodic_name_suffix(1,$_);
    print_func_doc1($_,$nameper);
}

}

-------------------------------------------------------------------

Writing file below this line

-------------------------------------------------------------------

NAME

PDL::DSP::Windows - Window functions for signal processing

SYNOPSIS

use PDL;
use PDL::DSP::Windows('window');
my $samples = window( 10, 'tukey', { params => .5 });

use PDL;
use PDL::DSP::Windows;
my $win = new PDL::DSP::Windows(10, 'tukey', { params => .5 });
print $win->coherent_gain , "\n";
$win->plot;

DESCRIPTION

This module provides symmetric and periodic (DFT-symmetric) window functions for use in filtering and spectral analysis. It provides a high-level access subroutine "window". This functional interface is sufficient for getting the window samples. For analysis and plotting, etc. an object oriented interface is provided. The functional subroutines must be either explicitly exported, or fully qualified. In this document, the word function refers only to the mathematical window functions, while the word subroutine is used to describe code.

Window functions are also known as apodization functions or tapering functions. In this module, each of these functions maps a sequence of $N integers to values called a samples. (To confuse matters, the word sample also has other meanings when describing window functions.) The functions are often named for authors of journal articles. Be aware that across the literature and software, some functions referred to by several different names, and some names refer to several different functions. As a result, the choice of window names is somewhat arbitrary.

The "kaiser" window function requires PDL::GSLSF::BESSEL. The "dpss" window function requires PDL::LinearAlgebra. But the remaining window functions may be used if these modules are not installed.

The most common and easiest usage of this module is indirect, via some higher-level filtering interface, such as PDL::DSP::Fir::Simple. The next easiest usage is to return a pdl of real-space samples with the subroutine "window". Finally, for analyzing window functions, object methods, such as "new", "plot", "plot_freq" are provided.

In the following, first the functional interface (non-object oriented) is described in "FUNCTIONAL INTERFACE". Next, the object methods are described in "METHODS". Next the low-level subroutines returning samples for each named window are described in "WINDOW FUNCTIONS". Finally, some support routines that may be of interest are described in "AUXILIARY SUBROUTINES".

FUNCTIONAL INTERFACE

window

$win = window({OPTIONS});
$win = window($N,{OPTIONS});
$win = window($N,$name,{OPTIONS});
$win = window($N,$name,$params,{OPTIONS});
$win = window($N,$name,$params,$periodic);

Returns an $N point window of type $name. The arguments may be passed positionally in the order $N,$name,$params,$periodic, or they may be passed by name in the hash OPTIONS.

EXAMPLES

# Each of the following return a 100 point symmetric hamming window.

  $win = window(100);
  $win = window(100, 'hamming');
  $win = window(100, { name => 'hamming' );
  $win = window({ N=> 100, name => 'hamming' );

# Each of the following returns a 100 point symmetric hann window.

  $win = window(100, 'hann');
  $win = window(100, { name => 'hann' );

# Returns a 100 point periodic hann window.

  $win = window(100, 'hann', { periodic => 1 } );

# Returns a 100 point symmetric Kaiser window with alpha=2.

  $win = window(100, 'kaiser', { params => 2 });

OPTIONS

The options follow default PDL::Options rules-- They may be abbreviated, and are case-insensitive.

name

(string) name of window function. Default: hamming. This selects one of the window functions listed below. Note that the suffix '_per', for periodic, may be ommitted. It is specified with the option periodic => 1

params

ref to array of parameter or parameters for the window-function subroutine. Only some window-function subroutines take parameters. If the subroutine takes a single parameter, it may be given either as a number, or a list of one number. For example 3 or [3].

N

number of points in window function (the same as the order of the filter) No default value.

periodic

If value is true, return a periodic rather than a symmetric window function. Default: 0 (that is, false. that is, symmetric.)

list_windows

list_windows
list_windows STR

list_windows prints the names all of the available windows. list_windows STR prints only the names of windows matching the string STR.

METHODS

new

my $win = new PDL::DSP::Windows(ARGS);

Create an instance of a Windows object. If ARGS are given, the instance is initialized. ARGS are interpreted in exactly the same way as arguments the subroutine "window".

For example:

my $win1 = new PDL::DSP::Windows(8,'hann');
my $win2 = new PDL::DSP::Windows( { N => 8, name => 'hann' } );

init

$win->init(ARGS);

Initialize (or reinitialize) a Windows object. ARGS are interpreted in exactly the same way as arguments the subroutine "window".

For example:

my $win = new PDL::DSP::Windows(8,'hann');
$win->init(10,'hamming');

samples

$win->samples();

Generate and return a reference to the piddle of $N samples for the window $win. This is the real-space representation of the window. The samples are stored in the object $win, but are regenerated every time samples is invoked. See the method "get_samples" below.

For example:

my $win = new PDL::DSP::Windows(8,'hann');
print $win->samples(), "\n";

get

my $windata = $win->get('samples');

Get an attribute (or list of attributes) of the window $win. If attribute samples is requested, then the samples are created with the method "samples" if they don't exist.

For example:

my $win = new PDL::DSP::Windows(8,'hann');
print $win->get('samples'), "\n";

get_samples

my $windata = $win->get_samples

Return a reference to the pdl of samples for the Window instance $win. The samples will be generated with the method "samples" if and only if they have not yet been generated.

get_modfreqs

my $winfreqs = $win->get_modfreqs

Return a reference to the pdl of the frequency response (modulus of the DFT) for the Window instance $win. The data are created with the method "freqs" if they don't exist.

get_params

my $params = $win->get_params

Create a new array containing the parameter values for the instance $win and return a reference to the array. Note that not all window types take parameters.

get_name

print  $win->get_name , "\n";

Return a name suitable for printing associated with the window $win. This is something like the name used in the documentation for the particular window function. This is static data and does not depend on the instance.

plot

$win->plot;

Plot the samples. Currently, only PDL::Graphics::Gnuplot is supported. The default display type is used.

plot_freq

Can be called like this

$win->plot_freq;

Or this

$win->plot_freq( {ordinate => ORDINATE });

Plot the frequency response (magnitude of the DFT of the window samples). The response is plotted in dB, and the frequency (by default) as a fraction of the Nyquist frequency. Currently, only PDL::Graphics::Gnuplot is supported. The default display type is used.

options

coord => COORD

This sets the units of frequency of the co-ordinate axis. COORD must be one of nyquist, for fraction of the nyquist frequency (range -1,1), sample, for fraction of the sampling frequncy (range -.5,.5), or bin for frequency bin number (range 0,$N-1). The default value is nyquist.

enbw

$win->enbw;

Compute and return the equivalent noise bandwidth of the window.

coherent_gain

$win->coherent_gain;

Compute and return the coherent gain (the dc gain) of the window. This is just the average of the samples.

process_gain

$win->coherent_gain;

Compute and return the processing gain (the dc gain) of the window. This is just the multiplicative inverse of the enbw.

scallop_loss

$win->scallop_loss;

**BROKEN**. Compute and return the scalloping loss of the window.

WINDOW FUNCTIONS

These window-function subroutines return a pdl of $N samples. For most windows, there are a symmetric and a periodic version. The symmetric versions are functions of $N points, uniformly spaced, and taking values from x_lo through x_hi. Here, a periodic function of $N points is equivalent to its symmetric counterpart of $N+1 points, with the final point omitted. The name of a periodic window-function subroutine is the same as that for the corresponding symmetric function, except it has the suffix _per. The descriptions below describe the symmetric version of each window.

The term 'Blackman-Harris family' is meant to include the Hamming family and the Blackman family. These are functions of sums of cosines.

Unless otherwise noted, the arguments in the cosines of all symmetric window functions are multiples of $N numbers uniformly spaced from 0 through 2 pi.

AUXILIARY SUBROUTINES

These subroutines are used internally, but are also available for export.

cos_mult_to_pow

Convert Blackman-Harris coefficients. The BH windows are usually defined via coefficients for cosines of integer multiples of an argument. The same windows may be written instead as terms of powers of cosines of the same argument. These may be computed faster as they replace evaluation of cosines with multiplications. This subroutine is used internally to implement the Blackman-Harris family of windows more efficiently.

This subroutine takes between 1 and 7 numeric arguments a0, a1, ...

It converts the coefficients of this

a0 - a1 cos(arg) + a2 cos( 2 * arg) - a3 cos( 3 * arg)  + ...

To the cofficients of this

c0 + c1 cos(arg) + c2 cos(arg)**2 + c3 cos(arg)**3  + ...

cos_pow_to_mult

This function is the inverse of "cos_mult_to_pow".

This subroutine takes between 1 and 7 numeric arguments c0, c1, ...

It converts the coefficients of this

c0 + c1 cos(arg) + c2 cos(arg)**2 + c3 cos(arg)**3  + ...

To the cofficients of this

a0 - a1 cos(arg) + a2 cos( 2 * arg) - a3 cos( 3 * arg)  + ...

chebpoly

chebpoly($n,$x)

Returns the value of the $n-th order Chebyshev polynomial at point $x. $n and $x may be scalar numbers, pdl's, or array refs. However, at least one of $n and $x must be a scalar number.

All mixtures of pdls and scalars could be handled much more easily as a PP routine. But, at this point PDL::DSP::Windows is pure perl/pdl, requiring no C/Fortran compiler.

REFERENCES

  1. Harris, F.J. On the use of windows for harmonic analysis with the discrete Fourier transform, Proceedings of the IEEE, 1978, vol 66, pp 51-83.

  2. Nuttall, A.H. Some windows with very good sidelobe behavior, IEEE Transactions on Acoustics, Speech, Signal Processing, 1981, vol. ASSP-29, pp. 84-91.

AUTHOR

John Lapeyre, <jlapeyre at cpan.org>

ACKNOWLEDGMENTS

For study and comparison, the author used documents or output from: Thomas Cokelaer's spectral analysis software; Julius O Smith III's Spectral Audio Signal Processing web pages; André Carezia's chebwin.m Octave code; Other code in the Octave signal package.

LICENSE AND COPYRIGHT

Copyright 2012 John Lapeyre.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

This software is neither licensed nor distributed by The MathWorks, Inc., maker and liscensor of MATLAB.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 1601:

Non-ASCII character seen before =encoding in 'André'. Assuming UTF-8