Home > classes > @mfir > mfir.m

mfir

PURPOSE ^

MFIR FIR filter object class constructor.

SYNOPSIS ^

function f = mfir(varargin)

DESCRIPTION ^

 MFIR FIR filter object class constructor.
     Create an mfir object.

   f = mfir()    - creates an empty miir object.
   f = mfir(fi)  - creates a copy of the input miir object, fi.
   f = mfir(a)   - creates a an miir object based on the magnitude of the
                   input AO/fsdata object.
   f = mfir(pl)  - create an miir object from the description given in the
                   parameter list.

 Parameters for filter design from AO/fsdata:
   'method' - design method:
              'frequency-sampling' - uses fir2()
              'least-squares'      - uses firls()
              'Parks-McClellan'    - uses firpm()
   'Win'    - Window function for frequency-sampling method
   'N'      - filter order

 Parameters for standard filters:

   'type'   - one of 'highpass', 'lowpass', 'bandpass', 'bandreject'.
              [default: 'lowpass']
   'gain'   - gain of filter [default: 1.0]
   'fs'     - sample frequency to design for [default: 1Hz]
   'order'  - order of filter [default: 1]
   'fc'     - corner frequencies. This is a two element vector for bandpass
              and bandreject filters. [default: 0.25 or [0.1 0.3] ]
   'Win'    - Specify window function used in filter design [default: Hamming]

 Example 1:

 Create a default lowpass filter.
   >> f = mfir(plist())

 Example 2:

 Create an order 1 highpass filter with high frequency gain 2. Filter is
 designed for 1kHz sampled data and has a cut-off frequency of 200Hz.
   >> pl = plist();
   >> pl = append(pl, param('type', 'highpass'))
   >> pl = append(pl, param('gain', 2.0))
   >> pl = append(pl, param('fs', 1000))
   >> pl = append(pl, param('fc', 200))
   >> f = mfir(pl)


 M Hewitson 09-02-07

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SUBFUNCTIONS ^

SOURCE CODE ^

0001 function f = mfir(varargin)
0002 
0003 % MFIR FIR filter object class constructor.
0004 %     Create an mfir object.
0005 %
0006 %   f = mfir()    - creates an empty miir object.
0007 %   f = mfir(fi)  - creates a copy of the input miir object, fi.
0008 %   f = mfir(a)   - creates a an miir object based on the magnitude of the
0009 %                   input AO/fsdata object.
0010 %   f = mfir(pl)  - create an miir object from the description given in the
0011 %                   parameter list.
0012 %
0013 % Parameters for filter design from AO/fsdata:
0014 %   'method' - design method:
0015 %              'frequency-sampling' - uses fir2()
0016 %              'least-squares'      - uses firls()
0017 %              'Parks-McClellan'    - uses firpm()
0018 %   'Win'    - Window function for frequency-sampling method
0019 %   'N'      - filter order
0020 %
0021 % Parameters for standard filters:
0022 %
0023 %   'type'   - one of 'highpass', 'lowpass', 'bandpass', 'bandreject'.
0024 %              [default: 'lowpass']
0025 %   'gain'   - gain of filter [default: 1.0]
0026 %   'fs'     - sample frequency to design for [default: 1Hz]
0027 %   'order'  - order of filter [default: 1]
0028 %   'fc'     - corner frequencies. This is a two element vector for bandpass
0029 %              and bandreject filters. [default: 0.25 or [0.1 0.3] ]
0030 %   'Win'    - Specify window function used in filter design [default: Hamming]
0031 %
0032 % Example 1:
0033 %
0034 % Create a default lowpass filter.
0035 %   >> f = mfir(plist())
0036 %
0037 % Example 2:
0038 %
0039 % Create an order 1 highpass filter with high frequency gain 2. Filter is
0040 % designed for 1kHz sampled data and has a cut-off frequency of 200Hz.
0041 %   >> pl = plist();
0042 %   >> pl = append(pl, param('type', 'highpass'))
0043 %   >> pl = append(pl, param('gain', 2.0))
0044 %   >> pl = append(pl, param('fs', 1000))
0045 %   >> pl = append(pl, param('fc', 200))
0046 %   >> f = mfir(pl)
0047 %
0048 %
0049 % M Hewitson 09-02-07
0050 %
0051 
0052 ALGONAME = mfilename;
0053 VERSION  = '$Id: mfir.m,v 1.11 2007/10/24 10:55:11 ingo Exp $';
0054 
0055 
0056 switch nargin
0057 
0058   %%%%%%%%%%  f = mfir()   %%%%%%%%%%
0059   % create default mfir object
0060   case 0
0061     f = init(VERSION);
0062 
0063   % Copy, standard
0064   case 1
0065 
0066     %%%%%%%%%% Create from XML fragment %%%%%%%%%%%
0067     if isa(varargin{1}, 'org.apache.xerces.dom.DeferredElementImpl')
0068       f = fromxml(varargin{1});
0069     %%%%%%%%%%%% From File %%%%%%%%%%%%%
0070     elseif ischar(varargin{1})
0071 
0072       filename = varargin{1};
0073       [path, name, ext, vers] = fileparts(filename);
0074       switch ext
0075         case '.mat'
0076           f = load(filename);
0077         case '.xml'
0078           f = xmlparse(mfir, filename);
0079         otherwise
0080           error('### Unknown file type.');
0081       end
0082     %%%%%%%%%%  f = mfir(mfir)   %%%%%%%%%%
0083     elseif isa(varargin{1}, 'mfir')
0084       f = varargin{1};
0085       f.version = VERSION;
0086 
0087     %%%%%%%%%%  f = mfir(ao)   %%%%%%%%%%
0088     elseif isa(varargin{1}, 'ao')
0089       pl = getDefaultPlist();
0090       f  = mfirFromAO(ALGONAME, VERSION, varargin{1}, pl);
0091 
0092     %%%%%%%%%%  f = mfir(struct)   %%%%%%%%%%
0093     elseif isstruct(varargin{1})
0094 
0095       f = init(VERSION);
0096 
0097       fields = fieldnames(varargin{1});
0098       for ii = 1:length(fields)
0099         field = fields{ii};
0100 
0101         %%% plist -> plist-object
0102         if strcmp(field, 'plist')
0103           if isstruct(varargin{1}.(field))
0104             f.(field) = plist(varargin{1}.(field));
0105           else
0106             f.(field) = varargin{1}.(field);
0107           end
0108         %%% created -> time-object
0109         elseif strcmp(field, 'created')
0110           created = varargin{1}.created;
0111           if isstruct(created)
0112             created = time(created);
0113           end
0114           f.created     = created;
0115         %%% All other
0116         else
0117           try
0118             f.(field) = varargin{1}.(field);
0119           catch
0120             error('### The field ''%s'' in the struct is not a mfir property.', field)
0121           end
0122         end
0123       end
0124 
0125     %%%%%%%%%%  f = mfir(plist)   %%%%%%%%%%
0126     % Parameter list
0127     elseif isa(varargin{1}, 'plist')
0128 
0129       pl   = varargin{1};
0130       type = find(pl, 'type');
0131       pzm  = find(pl, 'pzmodel');
0132 
0133       f = init(VERSION);
0134 
0135       % deal with empty plist
0136       if isempty(type) && isempty(pzm)
0137         type = 'lowpass';
0138       end
0139 
0140       if ~isempty(type)
0141         % check and fill parameter list
0142         plo = parseFilterParams(pl);
0143         switch type
0144           case 'lowpass'
0145             f = mklowpass(f, plo);
0146           case 'highpass'
0147             f = mkhighpass(f, plo);
0148           case 'bandpass'
0149             f = mkbandpass(f, plo);
0150           case 'bandreject'
0151             f = mkbandreject(f, plo);
0152           otherwise
0153             error('### unknown standard filter type in miir constructor.');
0154         end
0155         f.infile  = '';
0156         f.plist   = plo;
0157         f.created = time;
0158         f.version = VERSION;
0159       elseif ~isempty(pzm)
0160 
0161         fs = find(pl, 'fs');
0162         if isempty(fs)
0163           % get max freq in pzmodel
0164           fs = 8*getupperFreq(pzm);
0165           warning([sprintf('!!! no sample rate specified. Designing for fs=%2.2fHz.', fs)...
0166                    sprintf('\nThe filter will be redesigned later when used.')]);
0167 
0168         end
0169         % make MIIR filter
0170         f = tomfir(pzm, plist('fs', fs));
0171         f = set(f, 'name', get(pzm, 'name'));
0172         f = set(f, 'plist', pl);
0173 
0174       else
0175         error('### unknown constructor type for mfir.');
0176       end
0177     else
0178       error('### unknown constructor type for mfir.');
0179     end
0180 
0181   case 2 % pzmodel followed by plist
0182 
0183     % From spectrum
0184     %%%%%%%%%%% From DATABASE
0185     if isa(varargin{1}, 'database')
0186       f = retrieve(varargin{1}, varargin{2:end});
0187     %%%%%%%%%%  f = mfir(pzmodel, plist)   %%%%%%%%%%
0188     elseif isa(varargin{1}, 'pzmodel')
0189       pzm = varargin{1};
0190       if ~isa(pzm, 'pzmodel')
0191         error('### unknown constructor type for mfir.');
0192       end
0193       pl = varargin{2};
0194       if ~isa(pl, 'plist')
0195         error('### unknown constructor type for mfir.');
0196       end
0197 
0198       pl = append(pl, param('pzmodel', pzm));
0199 
0200       f = mfir(pl);
0201 
0202     %%%%%%%%%%  f = mfir(ao, plist)   %%%%%%%%%%
0203     elseif isa(varargin{1}, 'ao')
0204 
0205       if isa(varargin{2}, 'plist')
0206         pl = combine(varargin{2}, getDefaultPlist());
0207       else
0208         pl = getDefaultPlist();
0209       end
0210       f = mfirFromAO(ALGONAME, VERSION, varargin{1}, pl);
0211 
0212     else
0213       error('### Unknown constructor method.');
0214     end
0215   otherwise
0216     error('### incorrect input arguments for miir constructor.');
0217 end
0218 
0219 end
0220 
0221 %--------------------------------------------------------------------------
0222 % create FIR filter from magnitude of input AO/fsdata
0223 function filt = mfirFromAO(ALGONAME, VERSION, a, pl)
0224 
0225 
0226   N      = find(pl, 'N');
0227   win    = find(pl, 'Win');
0228   method = find(pl, 'method');
0229 
0230   d  = a.data;
0231   fs = d.fs;
0232   f  = d.f;
0233   xx = abs(d.xx);
0234   g  = 1; %median(xx);
0235   % xx = xx / g;
0236 
0237   ffm = f/(fs/2);
0238   switch method
0239     case 'frequency-sampling'
0240       % check window
0241       if length(win.win) ~= N+1
0242         warning('!!! resizing window function to match desired filter order.');
0243         if strcmp(win.name, 'Kaiser') || strcmp(win.name, 'Flattop')
0244           win = specwin(win.name, N+1, win.psll);
0245         else
0246           win = specwin(win.name, N+1);
0247         end
0248       end
0249       disp('** designing filter using frequency-sampling method [help fir2]');
0250       mtaps = fir2(N, ffm, xx, win.win);
0251     case 'least-squares'
0252       error('### this design method is not working properly yet.');
0253       if mod(length(ffm),2)
0254         ffm = ffm(1:end-1);
0255         xx  = xx(1:end-1);
0256       end
0257       disp('** designing filter using least-squares method [help firls]');
0258       mtaps = firls(N, ffm, xx);
0259     case 'Parks-McClellan'
0260       error('### this design method is not working properly yet.');
0261       disp('** designing filter using Parks-McClellan method [help firpm]');
0262       mtaps = firpm(N, ffm, xx);
0263     otherwise
0264       error('### unknown filter design method.');
0265   end
0266 
0267   % Make mfir object
0268   filt          = init(VERSION);
0269   filt.name     = sprintf('fir(%s)', a.name);
0270   filt.fs       = fs;
0271   filt.ntaps    = length(mtaps);
0272   filt.a        = mtaps;
0273   filt.gd       = (filt.ntaps+1)/2;
0274   filt.gain     = g;
0275   filt.histout  = zeros(1,filt.ntaps-1);   % initialise output history
0276   filt.infile   = '';
0277   filt.plist    = plist();
0278   filt.created  = time;
0279   filt.version  = VERSION;
0280 end
0281 
0282 %--------------------------------------------------------------------------
0283 % default plist
0284 function pl = getDefaultPlist()
0285 
0286   N  = 512;
0287   pl = plist(param('N', N));
0288   pl = append(pl, param('method', 'frequency-sampling'));
0289   pl = append(pl, param('Win', specwin('Hanning', N+1)));
0290 
0291 end
0292 
0293 %%%%%%%%%%%%%%%%%%%%%%%%   define mfir properties   %%%%%%%%%%%%%%%%%%%%%%%%%
0294 
0295 function f = init(VERSION)
0296   f.name    = 'None';
0297   f.fs      = 0;
0298   f.ntaps   = 0;
0299   f.a       = [];
0300   f.gd      = 0;
0301   f.gain    = 0;
0302   f.histout = [];
0303   f.infile  = '';
0304   f.plist   = plist();
0305   f.created = time;
0306   f.version = VERSION;
0307   f         = class(f, 'mfir');
0308 end
0309 
0310 %%%%%%%%%%%%%%%%%%%%%%%%%%   Create mfir object   %%%%%%%%%%%%%%%%%%%%%%%%%%%

Generated on Fri 02-Nov-2007 19:39:27 by m2html © 2003