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

Generated on Tue 22-Jan-2008 10:39:13 by m2html © 2003