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 mfir object.
   f = mfir(fi)   - creates a copy of the input mfir object, fi.
   f = mfir(a)    - creates an mfir object based on the magnitude of the
                    input AO/fsdata object a.
   f = mfir(c,fs) - creates an mfir object based on the vector of input
                    coefficients c.
                    The sample rate for which the filter is designed should
                    be specified as well.
   f = mfir(pl)   - create an mfir object from the description given in the
                    parameter list.

 Parameters for standard filters:

              'type'   - '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+1>>
              'fc'     - corner frequencies.
                         This is a two element vector for bandpass
                         and bandreject filters.
                         <<default: 0.25 or [0.1 0.2]>>
              'win'    - Specify window function used in filter design
                         <<default: Hamming>>

 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 retrieving from repository:

   'Hostname' - construct an AO by retrieving it from an LTPDA repository
                specified by the given hostname. Only those objects which
                are mfir objects are returned.
                Additional parameters:
                'Database'   - The database name [default: 'ltpda']
                'ID'         - A vector of object IDs.

 EXAMPLE 1:   Create a default lowpass filter.

              >> f = mfir(plist())

 EXAMPLE 2:   Create an order 1+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('order', 1))
              >> pl = append(pl, param('gain', 2.0))
              >> pl = append(pl, param('fs', 1000))
              >> pl = append(pl, param('fc', 200))
              >> f = mfir(pl)


 VERSION:     $Id: mfir.m,v 1.26 2008/02/24 10:15:55 hewitson Exp $

 HISTORY:     09-02-2007 M Hewitson
                 Creation
              11-02-2008 M Hueller
                 Help fixed
                 Default parameter list redefined

 The following call returns a parameter list object that contains the
 default parameter values:

 >> pl = mfir(mfir,'Params')

 The following call returns a string that contains the routine CVS version:

 >> version = mfir(mfir,'Version')

 The following call returns a string that contains the routine category:

 >> category = mfir(mfir,'Category')

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

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 mfir object.
0006 %   f = mfir(fi)   - creates a copy of the input mfir object, fi.
0007 %   f = mfir(a)    - creates an mfir object based on the magnitude of the
0008 %                    input AO/fsdata object a.
0009 %   f = mfir(c,fs) - creates an mfir object based on the vector of input
0010 %                    coefficients c.
0011 %                    The sample rate for which the filter is designed should
0012 %                    be specified as well.
0013 %   f = mfir(pl)   - create an mfir object from the description given in the
0014 %                    parameter list.
0015 %
0016 % Parameters for standard filters:
0017 %
0018 %              'type'   - 'highpass', 'lowpass',
0019 %                         'bandpass', 'bandreject'.
0020 %                         <<default: 'lowpass'>>
0021 %              'gain'   - gain of filter
0022 %                         <<default: 1.0>>
0023 %              'fs'     - sample frequency to design for
0024 %                         <<default: 1Hz>>
0025 %              'order'  - order of filter
0026 %                         <<default: 1+1>>
0027 %              'fc'     - corner frequencies.
0028 %                         This is a two element vector for bandpass
0029 %                         and bandreject filters.
0030 %                         <<default: 0.25 or [0.1 0.2]>>
0031 %              'win'    - Specify window function used in filter design
0032 %                         <<default: Hamming>>
0033 %
0034 % Parameters for filter design from AO/fsdata:
0035 %   'method' - design method:
0036 %              'frequency-sampling' - uses fir2()
0037 %              'least-squares'      - uses firls()
0038 %              'Parks-McClellan'    - uses firpm()
0039 %   'Win'    - Window function for frequency-sampling method
0040 %   'N'      - filter order
0041 %
0042 % Parameters for retrieving from repository:
0043 %
0044 %   'Hostname' - construct an AO by retrieving it from an LTPDA repository
0045 %                specified by the given hostname. Only those objects which
0046 %                are mfir objects are returned.
0047 %                Additional parameters:
0048 %                'Database'   - The database name [default: 'ltpda']
0049 %                'ID'         - A vector of object IDs.
0050 %
0051 % EXAMPLE 1:   Create a default lowpass filter.
0052 %
0053 %              >> f = mfir(plist())
0054 %
0055 % EXAMPLE 2:   Create an order 1+1 highpass filter with high frequency gain 2.
0056 %              Filter is designed for 1kHz sampled data and has a cut-off
0057 %              frequency of 200Hz.
0058 %
0059 %              >> pl = plist();
0060 %              >> pl = append(pl, param('type', 'highpass'))
0061 %              >> pl = append(pl, param('order', 1))
0062 %              >> pl = append(pl, param('gain', 2.0))
0063 %              >> pl = append(pl, param('fs', 1000))
0064 %              >> pl = append(pl, param('fc', 200))
0065 %              >> f = mfir(pl)
0066 %
0067 %
0068 % VERSION:     $Id: mfir.m,v 1.26 2008/02/24 10:15:55 hewitson Exp $
0069 %
0070 % HISTORY:     09-02-2007 M Hewitson
0071 %                 Creation
0072 %              11-02-2008 M Hueller
0073 %                 Help fixed
0074 %                 Default parameter list redefined
0075 %
0076 % The following call returns a parameter list object that contains the
0077 % default parameter values:
0078 %
0079 % >> pl = mfir(mfir,'Params')
0080 %
0081 % The following call returns a string that contains the routine CVS version:
0082 %
0083 % >> version = mfir(mfir,'Version')
0084 %
0085 % The following call returns a string that contains the routine category:
0086 %
0087 % >> category = mfir(mfir,'Category')
0088 %
0089 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0090 
0091 ALGONAME = mfilename;
0092 VERSION  = '$Id: mfir.m,v 1.26 2008/02/24 10:15:55 hewitson Exp $';
0093 CATEGORY = 'Constructor';
0094 
0095 %%%%%   Is this a 'Params' call?     %%%%%
0096 if  (nargin == 2 || nargin == 3) && ischar(varargin{2})
0097   if isa(varargin{1}, 'mfir')
0098     if strcmpi(varargin{2}, 'Params')
0099       if nargin == 2
0100         f = getDefaultPlist();
0101       else 
0102         f = getDefaultPlist(varargin{3});
0103       end
0104       return
0105     elseif strcmpi(varargin{2}, 'Version')
0106       f = VERSION;
0107       return
0108     elseif strcmpi(varargin{2}, 'Category')
0109       f = CATEGORY;
0110       return
0111     end
0112   elseif isa(varargin{1}, 'ao')
0113     if strcmpi(varargin{2}, 'Params')
0114       f = getDefaultPlist('From AO');
0115       return
0116     end
0117   end
0118 end
0119 
0120 switch nargin
0121 
0122   %%%%%%%%%%  f = mfir()   %%%%%%%%%%
0123   % create default mfir object
0124   case 0
0125     f = init(VERSION);
0126 
0127     % Copy, standard
0128   case 1
0129 
0130     %%%%%%%%%%%% From File %%%%%%%%%%%%%
0131     if ischar(varargin{1})
0132 
0133       filename = varargin{1};
0134       [path, name, ext, vers] = fileparts(filename);
0135       switch ext
0136         case '.mat'
0137           f = load(filename);
0138           f = f.a;
0139         case '.xml'
0140           root_node = xmlread(filename);
0141           f = ltpda_xmlread(root_node, 'mfir');
0142         otherwise
0143           error('### Unknown file type.');
0144       end
0145       %%%%%%%%%%  f = mfir(mfir)   %%%%%%%%%%
0146     elseif isa(varargin{1}, 'mfir')
0147       f = varargin{1};
0148       f.version = VERSION;
0149 
0150       %%%%%%%%%%  f = mfir(ao)   %%%%%%%%%%
0151     elseif isa(varargin{1}, 'ao')
0152       pl = getDefaultPlist('From AO');
0153       f  = mfirFromAO(ALGONAME, VERSION, varargin{1}, pl);
0154 
0155       %%%%%%%%%%  f = mfir(struct)   %%%%%%%%%%
0156     elseif isstruct(varargin{1})
0157 
0158       f = init(VERSION);
0159 
0160       fields = fieldnames(varargin{1});
0161       for ii = 1:length(fields)
0162         field = fields{ii};
0163 
0164         %%% plist -> plist-object
0165         if strcmp(field, 'plist')
0166           if isstruct(varargin{1}.(field))
0167             f.(field) = plist(varargin{1}.(field));
0168           else
0169             f.(field) = varargin{1}.(field);
0170           end
0171           %%% created -> time-object
0172         elseif strcmp(field, 'created')
0173           created = varargin{1}.created;
0174           if isstruct(created)
0175             created = time(created);
0176           end
0177           f.created     = created;
0178           %%% All other
0179         else
0180           try
0181             f.(field) = varargin{1}.(field);
0182           catch
0183             error('### The field ''%s'' in the struct is not a mfir property.', field)
0184           end
0185         end
0186       end
0187 
0188       %%%%%%%%%%  f = mfir(plist)   %%%%%%%%%%
0189       % Parameter list
0190     elseif isa(varargin{1}, 'plist')
0191 
0192       pl       = varargin{1};
0193       type     = find(pl, 'type');
0194       pzm      = find(pl, 'pzmodel');
0195       hostname = find(pl, 'hostname');
0196       
0197       f = init(VERSION);
0198 
0199       % deal with empty plist
0200       if isempty(type) && isempty(pzm) && isempty(hostname)
0201         type = 'lowpass';
0202       end
0203 
0204       if ~isempty(type)
0205         % check and fill parameter list
0206         plo = parseFilterParams(pl);
0207         switch type
0208           case 'lowpass'
0209             f = mklowpass(f, plo);
0210           case 'highpass'
0211             f = mkhighpass(f, plo);
0212           case 'bandpass'
0213             f = mkbandpass(f, plo);
0214           case 'bandreject'
0215             f = mkbandreject(f, plo);
0216           otherwise
0217             error('### unknown standard filter type in mfir constructor.');
0218         end
0219         f.infile  = '';
0220         f.plist   = plo;
0221         f.created = time;
0222         f.version = VERSION;
0223       elseif ~isempty(pzm)
0224 
0225         fs = find(pl, 'fs');
0226         if isempty(fs)
0227           % get max freq in pzmodel
0228           fs = 8*getupperFreq(pzm);
0229           warning([sprintf('!!! no sample rate specified. Designing for fs=%2.2fHz.', fs)...
0230             sprintf('\nThe filter will be redesigned later when used.')]);
0231 
0232         end
0233         % make MFIR filter
0234         f = tomfir(pzm, plist('fs', fs));
0235         f = set(f, 'name', get(pzm, 'name'));
0236         f = set(f, 'plist', pl);
0237 
0238       elseif ~isempty(hostname)
0239         
0240         f = mfirFromRepository(pl, VERSION, ALGONAME);
0241         % remove connection if it's there
0242         f.plist = remove(pl, 'conn');
0243         
0244       else
0245         error('### unknown constructor type for mfir.');
0246       end
0247     else
0248       error('### unknown constructor type for mfir.');
0249     end
0250 
0251   case 2 % pzmodel followed by plist
0252 
0253     % From spectrum
0254     %%%%%%%%%%% From DATABASE
0255     if isa(varargin{1}, 'database')
0256       f = retrieve(varargin{1}, varargin{2:end});
0257 
0258       %%%%%%%%%%  f = mfir(pzmodel, plist)   %%%%%%%%%%
0259     elseif isa(varargin{1}, 'pzmodel')
0260       pzm = varargin{1};
0261       if ~isa(pzm, 'pzmodel')
0262         error('### unknown constructor type for mfir.');
0263       end
0264       pl = varargin{2};
0265       if ~isa(pl, 'plist')
0266         error('### unknown constructor type for mfir.');
0267       end
0268 
0269       pl = append(pl, param('pzmodel', pzm));
0270 
0271       f = mfir(pl);
0272 
0273       %%%%%%%%%%  f = mfir(ao, plist)   %%%%%%%%%%
0274     elseif isa(varargin{1}, 'ao')
0275 
0276       if isa(varargin{2}, 'plist')
0277         pl = combine(varargin{2}, getDefaultPlist('From AO'));
0278       else
0279         pl = getDefaultPlist('From AO');
0280       end
0281       f = mfirFromAO(ALGONAME, VERSION, varargin{1}, pl);
0282 
0283       %%%%%%%%%%%% From a coeffs %%%%%%%%%%%%%
0284     elseif isnumeric(varargin{1})
0285       a      = varargin{1};
0286       fs     = varargin{2};
0287 
0288       % Checking the coefficients are listed in rows
0289       if size(a,1)~=1
0290         a = a';
0291       end
0292 
0293       f         = init(VERSION);
0294       f.name    = 'from coeffs';
0295       f.fs      = fs;
0296       f.ntaps   = length(a);
0297       f.a       = a;
0298       f.gd      = (f.ntaps)/2;
0299       f.gain    = 1;
0300       f.histout = zeros(1,f.ntaps-1);   % initialise output history
0301 
0302     else
0303       error('### Unknown constructor method.');
0304     end
0305   otherwise
0306     error('### incorrect input arguments for mfir constructor.');
0307 end
0308 
0309 end
0310 
0311 
0312 %--------------------------------------------------------------------------
0313 % construct an mfir from a repository
0314 %
0315 function fs = mfirFromRepository(pl, VERSION, ALGONAME)
0316 
0317 dpl = getDefaultPlist('From Repository');
0318 pl  = combine(pl, dpl);
0319 
0320 % Get parameters
0321 conn = find(pl, 'conn');
0322 hostname = find(pl, 'hostname');
0323 database = find(pl, 'database');
0324 ids      = find(pl, 'id');
0325 
0326 % do we have a connection?
0327 closeConn = 0;
0328 if isempty(conn)
0329   closeConn = 1;
0330   % Connect to repository
0331   conn = mysql_connect(hostname, database);
0332 end
0333 if ~isa(conn, 'database')
0334   error('### connection failed.');
0335 end
0336 % Get each ID
0337 Nids = length(ids);
0338 fs  = [];
0339 for kk=1:Nids
0340 
0341   %---- This id
0342   id = ids(kk);
0343   disp(sprintf('  - retrieving ID %d', id));
0344 
0345   %---- check ID object type
0346   tt = mysql_getObjType(conn, id);
0347   %---- If this is an mfir
0348   if strcmp(tt, mfilename)
0349     %---- call database constructor
0350     a = ltpda_obj_retrieve(conn, id);
0351     %---- Add history
0352     %---- Add to output array
0353     fs = [fs a];
0354   else
0355     warning('    !skipping ID %d, type %s', id, tt);
0356   end
0357 
0358 end
0359 
0360 % close connection
0361 if closeConn
0362   close(conn);
0363 end
0364 
0365 end
0366 
0367 %--------------------------------------------------------------------------
0368 % create FIR filter from magnitude of input AO/fsdata
0369 function filt = mfirFromAO(ALGONAME, VERSION, a, pl)
0370 
0371 %% Check that a.data is a fsdata object
0372 if ~isa(a.data, 'fsdata')
0373   error('### Please use an analysis object with a fsdata data object to create a mfir object.');
0374 end
0375 
0376 N      = find(pl, 'N');
0377 win    = find(pl, 'Win');
0378 method = find(pl, 'method');
0379 
0380 fs = a.data.fs;
0381 f  = a.data.x;
0382 xx = abs(a.data.y);
0383 g  = 1; %median(xx);
0384 
0385 ffm = f/(fs/2);
0386 switch method
0387   case 'frequency-sampling'
0388     % check window
0389     if length(win.win) ~= N+1
0390       warning('!!! resizing window function to match desired filter order.');
0391       if strcmp(win.name, 'Kaiser') || strcmp(win.name, 'Flattop')
0392         win = specwin(win.name, N+1, win.psll);
0393       else
0394         win = specwin(win.name, N+1);
0395       end
0396     end
0397     disp('** designing filter using frequency-sampling method [help fir2]');
0398     mtaps = fir2(N, ffm, xx, win.win);
0399   case 'least-squares'
0400     error('### this design method is not working properly yet.');
0401     if mod(length(ffm),2)
0402       ffm = ffm(1:end-1);
0403       xx  = xx(1:end-1);
0404     end
0405     disp('** designing filter using least-squares method [help firls]');
0406     mtaps = firls(N, ffm, xx);
0407   case 'Parks-McClellan'
0408     error('### this design method is not working properly yet.');
0409     disp('** designing filter using Parks-McClellan method [help firpm]');
0410     mtaps = firpm(N, ffm, xx);
0411   otherwise
0412     error('### unknown filter design method.');
0413 end
0414 
0415 % Make mfir object
0416 filt          = init(VERSION);
0417 filt.name     = sprintf('fir(%s)', a.name);
0418 filt.fs       = fs;
0419 filt.ntaps    = length(mtaps);
0420 filt.a        = mtaps;
0421 filt.gd       = (filt.ntaps+1)/2;
0422 filt.gain     = g;
0423 filt.histout  = zeros(1,filt.ntaps-1);   % initialise output history
0424 filt.infile   = '';
0425 filt.plist    = pl;
0426 filt.created  = time;
0427 filt.version  = VERSION;
0428 end
0429 
0430 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0431 %
0432 % FUNCTION:    getDefaultPL
0433 %
0434 % DESCRIPTION: Get default params
0435 %
0436 % HISTORY:     11-02-2008 M Hueller
0437 %                 Creation
0438 %
0439 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0440 function pl = getDefaultPlist(varargin)
0441 
0442 
0443 % list of available parameter sets
0444 sets = {'Standard Type', 'From AO', 'From pzmodel', 'From Repository',...
0445   'From Plist'};
0446 
0447 if nargin == 0
0448   pl = sets;
0449   return
0450 end
0451 
0452 set = varargin{1};
0453 
0454 switch set
0455   case 'From Repository'
0456     pl = plist('hostname', 'localhost', 'database', 'ltpda', 'ID', []);
0457   case 'Standard Type'
0458     pl = plist('type','lowpass',...
0459       'gain',  1.0, ...
0460       'fs', 1.0, ...
0461       'order', 1, ...
0462       'fc', 0.1, ... 
0463       'win', 'Hamming');
0464   case 'From AO'
0465     N  = 512;
0466     pl = plist(param('N', N));
0467     pl = append(pl, param('method', 'frequency-sampling'));
0468     pl = append(pl, param('Win', specwin('Hanning', N+1)));
0469   case 'From pzmodel'
0470     pl = plist('pzmodel', []);
0471   case 'From Plist'
0472     pl = plist('Plist', []);
0473   otherwise
0474     pl = plist();
0475 end
0476 
0477 end
0478 
0479 %%%%%%%%%%%%%%%%%%%%%%%%   define mfir properties   %%%%%%%%%%%%%%%%%%%%%%%%%
0480 
0481 function f = init(VERSION)
0482 f.name    = 'None';
0483 f.fs      = 0;
0484 f.ntaps   = 0;
0485 f.a       = [];
0486 f.gd      = 0;
0487 f.gain    = 0;
0488 f.histout = [];
0489 f.infile  = '';
0490 f.plist   = plist();
0491 f.created = time;
0492 f.version = VERSION;
0493 f         = class(f, 'mfir');
0494 end
0495 
0496 %%%%%%%%%%%%%%%%%%%%%%%%%%   Create mfir object   %%%%%%%%%%%%%%%%%%%%%%%%%%%

Generated on Fri 07-Mar-2008 15:46:43 by m2html © 2003