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.9 2007/08/31 17:40:08 hewitson 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         try
0101           if strcmp(field, 'plist')
0102             if isstruct(varargin{1}.(field))
0103               f.(field) = plist(varargin{1}.(field));
0104             else
0105               f.(field) = varargin{1}.(field);
0106             end
0107           else
0108             f.(field) = varargin{1}.(field);
0109           end
0110         catch
0111           error('### The field ''%s'' in the struct is not a mfir property.', field)
0112         end
0113       end
0114 
0115     %%%%%%%%%%  f = mfir(plist)   %%%%%%%%%%
0116     % Parameter list
0117     elseif isa(varargin{1}, 'plist')
0118 
0119       pl   = varargin{1};
0120       type = find(pl, 'type');
0121       pzm  = find(pl, 'pzmodel');
0122 
0123       f = init(VERSION);
0124 
0125       % deal with empty plist
0126       if isempty(type) && isempty(pzm)
0127         type = 'lowpass';
0128       end      
0129       
0130       if ~isempty(type)
0131         % check and fill parameter list
0132         plo = parseFilterParams(pl);
0133         switch type
0134           case 'lowpass'
0135             f = mklowpass(f, plo);
0136           case 'highpass'
0137             f = mkhighpass(f, plo);
0138           case 'bandpass'
0139             f = mkbandpass(f, plo);
0140           case 'bandreject'
0141             f = mkbandreject(f, plo);
0142           otherwise
0143             error('### unknown standard filter type in miir constructor.');
0144         end
0145         f.infile  = '';
0146         f.plist   = plo;
0147         f.created = time;
0148         f.version = VERSION;
0149       elseif ~isempty(pzm)
0150 
0151         fs = find(pl, 'fs');
0152         if isempty(fs)
0153           % get max freq in pzmodel
0154           fs = 8*getupperFreq(pzm);
0155           warning([sprintf('!!! no sample rate specified. Designing for fs=%2.2fHz.', fs)...
0156                    sprintf('\nThe filter will be redesigned later when used.')]);
0157 
0158         end
0159         % make MIIR filter
0160         f = tomfir(pzm, plist('fs', fs));
0161         f = set(f, 'name', get(pzm, 'name'));
0162         f = set(f, 'plist', pl);
0163 
0164       else
0165         error('### unknown constructor type for mfir.');
0166       end
0167     else
0168       error('### unknown constructor type for mfir.');
0169     end
0170 
0171   case 2 % pzmodel followed by plist
0172 
0173     % From spectrum
0174     %%%%%%%%%%% From DATABASE
0175     if isa(varargin{1}, 'database')        
0176       f = retrieve(varargin{1}, varargin{2:end});
0177     %%%%%%%%%%  f = mfir(pzmodel, plist)   %%%%%%%%%%
0178     elseif isa(varargin{1}, 'pzmodel')
0179       pzm = varargin{1};
0180       if ~isa(pzm, 'pzmodel')
0181         error('### unknown constructor type for mfir.');
0182       end
0183       pl = varargin{2};
0184       if ~isa(pl, 'plist')
0185         error('### unknown constructor type for mfir.');
0186       end
0187 
0188       pl = append(pl, param('pzmodel', pzm));
0189 
0190       f = mfir(pl);
0191 
0192     %%%%%%%%%%  f = mfir(ao, plist)   %%%%%%%%%%
0193     elseif isa(varargin{1}, 'ao')
0194 
0195       if isa(varargin{2}, 'plist')
0196         pl = combine(varargin{2}, getDefaultPlist());
0197       else
0198         pl = getDefaultPlist();
0199       end
0200       f = mfirFromAO(ALGONAME, VERSION, varargin{1}, pl);
0201 
0202     else
0203       error('### Unknown constructor method.');
0204     end
0205   otherwise
0206     error('### incorrect input arguments for miir constructor.');
0207 end
0208 
0209 end
0210 
0211 %--------------------------------------------------------------------------
0212 % create FIR filter from magnitude of input AO/fsdata
0213 function filt = mfirFromAO(ALGONAME, VERSION, a, pl)
0214 
0215 
0216   N      = find(pl, 'N');
0217   win    = find(pl, 'Win');
0218   method = find(pl, 'method');
0219 
0220   d  = a.data;
0221   fs = d.fs;
0222   f  = d.f;
0223   xx = abs(d.xx);
0224   g  = 1; %median(xx);
0225   % xx = xx / g;
0226 
0227   ffm = f/(fs/2);
0228   switch method
0229     case 'frequency-sampling'
0230       % check window
0231       if length(win.win) ~= N+1
0232         warning('!!! resizing window function to match desired filter order.');
0233         if strcmp(win.name, 'Kaiser') || strcmp(win.name, 'Flattop')
0234           win = specwin(win.name, N+1, win.psll);
0235         else
0236           win = specwin(win.name, N+1);
0237         end
0238       end
0239       disp('** designing filter using frequency-sampling method [help fir2]');
0240       mtaps = fir2(N, ffm, xx, win.win);
0241     case 'least-squares'
0242       error('### this design method is not working properly yet.');
0243       if mod(length(ffm),2)
0244         ffm = ffm(1:end-1);
0245         xx  = xx(1:end-1);
0246       end
0247       disp('** designing filter using least-squares method [help firls]');
0248       mtaps = firls(N, ffm, xx);
0249     case 'Parks-McClellan'
0250       error('### this design method is not working properly yet.');
0251       disp('** designing filter using Parks-McClellan method [help firpm]');
0252       mtaps = firpm(N, ffm, xx);
0253     otherwise
0254       error('### unknown filter design method.');
0255   end
0256 
0257   % Make mfir object
0258   filt          = init(VERSION);
0259   filt.name     = sprintf('fir(%s)', a.name);
0260   filt.fs       = fs;
0261   filt.ntaps    = length(mtaps);
0262   filt.a        = mtaps;
0263   filt.gd       = (filt.ntaps+1)/2;
0264   filt.g        = g;
0265   filt.histout  = zeros(1,filt.ntaps-1);   % initialise output history
0266   filt.infile   = '';
0267   filt.plist    = plist();
0268   filt.created  = time;
0269   filt.version  = VERSION;
0270 end
0271 
0272 %--------------------------------------------------------------------------
0273 % default plist
0274 function pl = getDefaultPlist()
0275 
0276   N  = 512;
0277   pl = plist(param('N', N));
0278   pl = append(pl, param('method', 'frequency-sampling'));
0279   pl = append(pl, param('Win', specwin('Hanning', N+1)));
0280 
0281 end
0282 
0283 %%%%%%%%%%%%%%%%%%%%%%%%   define mfir properties   %%%%%%%%%%%%%%%%%%%%%%%%%
0284 
0285 function f = init(VERSION)
0286   f.name    = 'None';
0287   f.fs      = 0;
0288   f.ntaps   = 0;
0289   f.a       = [];
0290   f.gd      = 0;
0291   f.g       = 0;
0292   f.histout = [];
0293   f.infile  = '';
0294   f.plist   = plist();
0295   f.created = time;
0296   f.version = VERSION;
0297   f         = class(f, 'mfir');
0298 end
0299 
0300 %%%%%%%%%%%%%%%%%%%%%%%%%%   Create mfir object   %%%%%%%%%%%%%%%%%%%%%%%%%%%

Generated on Mon 03-Sep-2007 12:12:34 by m2html © 2003