Fir.pm

filter: Statementstmt 91.5% 87 / 95 Branchbran 65.3% 17 / 26 Conditioncond 33.3% 2 / 6 MC/DCmcdc 0.0% 0 / 3 Subroutinesub 100% 13 / 13 Podpod 100% 4 / 4 totaltotal 83.6% 123 / 147 CC 16 SCAR 22.4
CC
16
Cov
83%
firwin
17.5
spectral_inverse
2.0
ir_sinc
2.0
CRAP 9.4
↑ Summary Fir/Simple.pm »
1 package PDL::DSP::Fir;
2  
3 2 ▶use 5.008;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 2 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 2 our $VERSION = '0.008';
8  
9 2 ▶use base 'Exporter';
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 2 ▶use PDL::LiteF;
Subroutine BEGIN: called CC=1 SCAR=0.0
12 2 ▶use PDL::NiceSlice;
Subroutine BEGIN: called CC=1 SCAR=0.0
13 2 ▶use PDL::Options;
Subroutine BEGIN: called CC=1 SCAR=0.0
14 2 ▶use constant PI => 4 * atan2(1, 1);
Subroutine BEGIN: called CC=1 SCAR=0.0
15 #use PDL::Constants qw(PI);
16 2 ▶use PDL::DSP::Windows;
Subroutine BEGIN: called CC=1 SCAR=0.0
17  
18 2 our @ISA = qw(Exporter);
19 2 our @EXPORT_OK = qw( firwin ir_sinc ir_hisinc spectral_inverse spectral_reverse );
20  
21 2 ▶$PDL::onlinedoc->scan(__FILE__) if $PDL::onlinedoc;
Branch: 1 branch
BranchTrueFalseTotal
if $PDL::onlinedoc 0 2 2
22  
23 =head1 NAME
24  
25 PDL::DSP::Fir - Finite impulse response filter kernels.
26  
27 =head1 SYNOPSIS
28  
29 use PDL;
30 use PDL::DSP::Fir qw( firwin );
31  
32 # return a 10 sample lowpass filter kernel
33 # with a cutoff at 90% of the Nyquist frequency.
34 $kernel = firwin( N => 10, fc => 0.9 );
35  
36 # Equivalent way of calling.
37 $kernel = firwin( { N => 10, fc => 0.9 } );
38  
39 =head1 DESCRIPTION
40  
41 This module provides routines to create one-dimensional finite impulse
42 response (FIR) filter kernels. This distribution inlcudes
43 a simple interface for filtering in L<PDL::DSP::Fir::Simple>.
44  
45 The routine L</firwin> returns a filter kernel constructed
46 from windowed sinc functions. Available filters are lowpass,
47 highpass, bandpass, and bandreject. The window functions are
48 in the module L<PDL::DSP::Windows>.
49  
50 Below, the word B<order> refers to the number of elements in the filter
51 kernel.
52  
53 No functions are exported be default.
54  
55 =head1 FUNCTIONS
56  
57 =head2 firwin
58  
59  
60 =head3 Usage
61  
62 =for usage
63  
64 $kern = firwin({OPTIONS});
65 $kern = firwin(OPTIONS);
66  
67 =for ref
68  
69 Returns a filter kernel (a finite impulse response function)
70 to be convolved with data.
71  
72 The kernel is built from windowed sinc functions. With the
73 option C<type =E<gt> 'window'> no sinc is used, rather the
74 kernel is just the window. The options may be passed as
75 a list of key-value pairs, or as an anonymous hash.
76  
77 =head3 OPTIONS
78  
79 =over
80  
81 =item N
82  
83 order of filter. This is the number of elements in
84 the returned kernel pdl.
85  
86 =item type
87  
88 Filter type. One of C<lowpass>, C<highpass>, C<bandpass>,
89 C<bandstop>, C<window>. Aliases for C<bandstop> are C<bandreject> and C<notch>.
90 Default is C<lowpass>. For C<bandpass> and C<bandstop> the number of samples
91 L</N> must be odd.
92 If B<type> is C<window>, then the kernel returned is just the window function.
93  
94 =item fc
95  
96 Cutoff frequency for low- and highpass filters as a fraction of
97 the Nyquist frequency. Must be a number between
98 C<0> and C<1>. No default value.
99  
100 =item fclo, fchi
101  
102 Lower and upper cutoff frequencies for bandpass and bandstop filters.
103 No default values.
104  
105 =back
106  
107 All other options to L</firwin> are passed to the function
108 L<PDL::DSP::Windows/window>.
109  
110 =cut
111  
112 9 ▶sub firwin {
Subroutine firwin: called CC=14 SCAR=28.6
Pod documented
113 9 ▶ barf 'PDL::DSP::Fir::firwin() called with no arguments.' unless @_;
Branch: 1 branch
BranchTrueFalseTotal
unless @_ 0 9 9
114 9 my $iopts;
115 9 ▶ if (@_ == 1) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_ == 1) { } 8 1 9
116 8 ▶ barf "PDL::DSP::FIR::firwin: single argument not a hashref"
Branch: 1 branch
BranchTrueFalseTotal
unless ref $_[0] eq "HASH" 0 8 8
117 unless ref($_[0]) eq 'HASH';
118 8 $iopts = $_[0];
119 }
120 else {
121 1 my %hash = @_;
122 1 $iopts = \%hash;
123 }
124 9 my $opt = new PDL::Options(
125 {
126 N => undef,
127 type => 'lowpass',
128 window => undef,
129 fc => undef,
130 fclo => undef,
131 fchi => undef,
132 });
133 9 my $opts = $opt->options($iopts);
134 9 my $winopts = { N => $opts->{N} };
135 9 ▶ if (defined $opts->{window} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $opts->{"window"}) 0 9 9
136 0 my $w = $opts->{window};
137 0 ▶ if ( ref $w ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $w) { } 0 0 0
138 0 foreach my $wkey (keys %{$w}) {
139 0 $winopts->{$wkey} = $w->{$wkey};
140 }
141 }
142 else {
143 0 $winopts->{NAME} = $w;
144 }
145 }
146 9 my $type = $opts->{type};
147 9 my $win = PDL::DSP::Windows::window($winopts);
148 9 my ($ir,$kernel);
149 9 ▶ if ($type eq 'lowpass') {
Branch: 5 branches
BranchTrueFalseTotal
if ($type eq 'lowpass') { } 6 3 9
elsif ($type eq 'highpass') { } 1 2 3
elsif ($type eq 'window') { } 0 2 2
elsif ($type eq 'bandpass') { } 1 1 2
elsif ($type eq 'bandstop' or $type eq 'bandreject' or $type eq 'notch') { } 1 0 1
150 6 $ir = ir_sinc($opts->{fc},$opts->{N});
151 6 $kernel = $ir * $win;
152 6 $kernel /= $kernel->sum;
153 }
154 elsif ($type eq 'highpass') {
155 1 $ir = ir_sinc($opts->{fc},$opts->{N});
156 1 $kernel = $ir * $win;
157 1 $kernel /= $kernel->sum;
158 1 $kernel = spectral_inverse($kernel);
159 }
160 elsif ($type eq 'window') {
161 0 $kernel = $win/$win->sum;
162 }
163 elsif ($type eq 'bandpass') {
164 1 my $ir1 = ir_sinc($opts->{fclo},$opts->{N});
165 1 my $ir2 = ir_sinc($opts->{fchi},$opts->{N});
166 1 my $fir1 = $ir1 * $win;
167 1 $fir1 /= $fir1->sum;
168 1 my $fir2 = $ir2 * $win;
169 1 $fir2 /= $fir2->sum;
170 1 $fir2 = spectral_inverse($fir2);
171 1 $kernel = spectral_inverse($fir1 + $fir2);
172 }
173 ▶ elsif ($type eq 'bandstop' or $type eq 'bandreject' or $type eq 'notch') {
Condition33%2/6
$type eq "bandstop" or $type eq "bandreject" or $type eq "notch"
l!l&&r!l&&!r
100
$type eq "bandstop" or $type eq "bandreject"
l!l&&r!l&&!r
100
MC/DC0%0/3
$type eq "bandstop" or $type eq "bandreject" or $type eq "notch"
$type eq "bandstop" $type eq "bandreject" $type eq "notch"
Truth table25%1/4
A or B or C
A= $type eq "bandstop"B= $type eq "bandreject"C= $type eq "notch"
ABCresult
1XX1
01X1
0011
0000
174 1 my $ir1 = ir_sinc($opts->{fclo},$opts->{N});
175 1 my $ir2 = ir_sinc($opts->{fchi},$opts->{N});
176 1 my $fir1 = $ir1 * $win;
177 1 $fir1 /= $fir1->sum;
178 1 my $fir2 = $ir2 * $win;
179 1 $fir2 /= $fir2->sum;
180 1 $fir2 = spectral_inverse($fir2);
181 1 $kernel = $fir1 + $fir2;
182 }
183 else {
184 0 barf "PDL::DSP::FIR::firwin: Unknown impulse response '$type'\n";
185 }
186 9 return $kernel;
187 }
188  
189 =pod
190  
191 The following three functions are called by the C<firwin>, but
192 may also be useful by themselves, for instance, to construct more
193 complicated filters.
194  
195 =head2 ir_sinc
196  
197 =for usage
198  
199 $sinc = ir_sinc($f_cut, $N);
200  
201 =for ref
202  
203 Return an C<$N> point sinc function representing a lowpass filter
204 with cutoff frequency C<$f_cut>.
205  
206 C<$f_cut> must be between 0 and 1, with 1 being Nyquist freq.
207 The output pdl is the function C<sin( $f_cut * $x ) / $x> where
208 $x is pdl of C<$N> uniformly spaced values ranging from
209 C< - PI * ($N-1)/2> through C<PI * ($N-1)/2>. For what it's
210 worth, a bit of efficiency is gained by computing the index
211 at which C<$x> is zero, rather than searching for it.
212  
213 =cut
214  
215 15 ▶sub ir_sinc {
Subroutine ir_sinc: called CC=2 SCAR=6.9
Pod documented
216 15 my ($f_cut,$N) = @_;
217 15 my $lim = PI * ($N-1)/2;
218 15 my $x = zeroes($N)->xlinvals(-$lim,$lim);
219 15 my $res = sin( $f_cut * $x ) / $x;
220 15 ▶ $res->slice(int($N/2)) .= $f_cut if $N % 2; # fix nan at x=0
Branch: 1 branch
BranchTrueFalseTotal
if $N % 2 10 5 15
221 15 $res;
222 }
223  
224 =head2 spectral_inverse
225  
226 =for usage
227  
228 $fir_inv = spectral_inverse($fir);
229  
230 =for ref
231  
232 Return output kernel whose spectrum is the inverse of the spectrum
233 of the input kernel.
234  
235 The number of samples in the input kernel must be odd.
236 Input C<$fir> and output C<$fir_inv> are real-space FIR filter kernels.
237 The spectrum of the output kernel is the additive inverse
238 with respect to 1 of the spectrum of the input kernel.
239  
240 =cut
241  
242 6 ▶sub spectral_inverse {
Subroutine spectral_inverse: called CC=2 SCAR=7.0
Pod documented
243 6 my ($fir) = @_;
244 6 my $L = $fir->nelem;
245 6 ▶ barf "spectral_inverse: L=$L is not odd\n" unless $L % 2;
Branch: 1 branch
BranchTrueFalseTotal
unless $L % 2 0 6 6
246 6 my $mid = ($L-1)/2;
247 6 my $ifir = -$fir;
248 6 $ifir->slice($mid) += 1;
249 6 $ifir;
250 }
251  
252 =head2 spectral_reverse
253  
254 =for usage
255  
256 $fir_rev = spectral_reverse($fir);
257  
258 =for ref
259  
260 Return output kernel whose spectrum is the reverse of the spectrum
261 of the input kernel.
262  
263 That is, the spectrum is mirrored about the center frequency.
264  
265 =cut
266  
267 4 ▶sub spectral_reverse {
Subroutine spectral_reverse: called CC=1 SCAR=0.0
Pod documented
268 4 my ($fir) = @_;
269 4 my $ofir = $fir->copy;
270 4 $ofir->slice('0:-1:2') *= -1;
271 4 $ofir;
272 }
273  
274 =head1 AUTHOR
275  
276 John Lapeyre, C<< <jlapeyre at cpan.org> >>
277  
278 =head1 ACKNOWLEDGEMENTS
279  
280 =head1 LICENSE AND COPYRIGHT
281  
282 Copyright 2012 John Lapeyre.
283  
284 This program is free software; you can redistribute it and/or modify it
285 under the terms of either: the GNU General Public License as published
286 by the Free Software Foundation; or the Artistic License.
287  
288 See http://dev.perl.org/licenses/ for more information.
289  
290  
291 =cut
292  
293 2 1; # End of PDL::DSP::Fir
↑ Summary Fir/Simple.pm »