Home > classes > @miir > miir.m

miir

PURPOSE ^

MIIR IIR filter object class constructor.

SYNOPSIS ^

function f = miir(varargin)

DESCRIPTION ^

 MIIR IIR filter object class constructor.

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

 DESCRIPTION: MIIR IIR filter object class constructor.
              Create an miir object.

 CONSTRUCTOR: f = miir()
                  creates an empty miir object.

              f = miir(fi)
                  creates a copy of the input miir object, fi.

              f = miir(a,b,fs)
                  creates an miir object from the coefficient vectors 'a' and 'b' **.
                  The sample rate for which the filter is designed should
                  be specified as well.

              f = miir('foo_iir.fil')
                  create an miir object from a LISO IIR .fil file.

              f = miir(pl)
                  create an miir 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>>
              'fc'     - corner frequencies.
                         This is a two element vector for bandpass
                         and bandreject filters.
                         <<default: 0.25 or [0.1 0.2]>>
              'ripple' - Specify pass/stop-band ripple for bandpass
                         and bandreject filters
                         <<default: 0.5>>

 EXAMPLE 1:   Create a default lowpass filter.

              >> f = miir(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('order', 1))
              >> pl = append(pl, param('gain', 2.0))
              >> pl = append(pl, param('fs', 1000))
              >> pl = append(pl, param('fc', 200))
              >> f = miir(pl)

 NOTES:
         ** The convention used here for naming the filter coefficients is
            the opposite to MATLAB's convention. The rescursion formula
            for this convention is

               b(1)*y(n) = a(1)*x(n) + a(2)*x(n-1) + ... + a(na+1)*x(n-na)
                           - b(2)*y(n-1) - ... - b(nb+1)*y(n-nb)


 VERSION:     $Id: miir.m,v 1.30 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 defined

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

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

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

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

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

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

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

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SUBFUNCTIONS ^

SOURCE CODE ^

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

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