--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/m-toolbox/classes/@mfir/mfir.m	Wed Nov 23 19:22:13 2011 +0100
@@ -0,0 +1,497 @@
+% MFIR FIR filter object class constructor.
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% DESCRIPTION: MFIR FIR filter object class constructor.
+%              Create a mfir object.
+%
+% CONSTRUCTORS:
+%
+%       f = mfir()         - creates an empty mfir object.
+%       f = mfir(fi)       - creates a copy of the input mfir object, fi.
+%       f = mfir(a)        - creates a mfir object based on the magnitude of
+%                            the input AO/fsdata object a.
+%       f = mfir(pzm)      - creates a mfir object from a pole/zero model
+%       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(filename) - creates an mfir object loading the  mfir object from disk
+%       f = mfir(pl)       - creates an mfir object from the description given
+%                            in the parameter list.
+%
+%
+% Parameter sets examples for plist constructor:
+%
+% EXAMPLE 1:   Create an order 1 highpass filter with high frequency gain 2.
+%              Filter is designed for 10 Hz sampled data and has a cut-off
+%              frequency of 0.2 Hz.
+%
+%              >> pl = plist('type', 'highpass', ...
+%                            'order', 128,       ...
+%                            'gain',  2.0,       ...
+%                            'fs',    10,        ...
+%                            'fc',    0.2);
+%              >> f = mfir(pl)
+%
+% NOTES:
+%           ** The convention used here for naming the filter coefficients is
+%              the opposite to MATLAB's convention. The recursion formula
+%              for this convention is
+%
+%              y(n) = a(1)*x(n) + a(2)*x(n-1) + ... + a(na+1)*x(n-na)
+%
+% <a href="matlab:utils.helper.displayMethodInfo('mfir', 'mfir')">Parameters Description</a>
+%
+% VERSION:     $Id: mfir.m,v 1.117 2011/08/15 12:22:57 hewitson Exp $
+%
+% SEE ALSO:    miir, ltpda_filter, ltpda_uoh, ltpda_uo, ltpda_obj, plist
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+classdef mfir < ltpda_filter
+  
+  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+  %                            Property definition                            %
+  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+  
+  %---------- Public (read/write) Properties  ----------
+  properties
+  end
+  
+  %---------- Protected read-only Properties ----------
+  properties (SetAccess = protected)
+    gd      = []; %
+  end
+  
+  %---------- Protected read-only Properties ----------
+  properties (SetAccess = protected, Dependent = true)
+    ntaps % number of coefficients in the filter
+  end
+  
+  %---------- Private Properties ----------
+  properties (GetAccess = protected, SetAccess = protected)
+  end
+  
+  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+  %                          Check property setting                           %
+  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+  methods
+    function set.gd(obj, val)
+      if ~isempty(val)
+        if ~isnumeric(val) || ~isreal(val)
+          error('### The value for the property ''gd'' must be a real number(s)');
+        end
+      end
+      obj.gd = val;
+    end
+    function set.ntaps(obj, val)
+      error('### Don''t set the property ''ntaps''. It is computed by length(a).');
+    end
+  end
+  
+  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+  %                     Compute the Dependent properties                      %
+  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+  
+  methods
+    function val = get.ntaps(obj)
+      val = length(obj.a);
+    end
+  end
+  
+  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+  %                                Constructor                                %
+  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+  
+  methods
+    function obj = mfir(varargin)
+      
+      import utils.const.*
+      utils.helper.msg(msg.OMNAME, 'running %s/%s', mfilename('class'), mfilename);
+      
+      % Collect all mfir objects
+      [fs, invars, rest] = utils.helper.collect_objects(varargin(:), 'mfir');
+      
+      if isempty(rest) && ~isempty(fs)
+        % Do copy constructor and return
+        utils.helper.msg(msg.OPROC1, 'copy constructor');
+        obj = copy(fs, 1);
+        for kk=1:numel(obj)
+          obj(kk).addHistory(mfir.getInfo('mfir', 'None'), [], [], obj(kk).hist);
+        end
+        return
+      end
+      
+      switch nargin
+        case 0
+          %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+          %%%%%%%%%%%%%%%%%%%%%%%%%%%   no inputs   %%%%%%%%%%%%%%%%%%%%%%%%%%%
+          %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+          utils.helper.msg(msg.OPROC1, 'empty constructor');
+          obj.addHistory(mfir.getInfo('mfir', 'None'), plist(), [], []);
+          
+        case 1
+          %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+          %%%%%%%%%%%%%%%%%%%%%%%%%%%   one input   %%%%%%%%%%%%%%%%%%%%%%%%%%%
+          %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+          
+          if ischar(varargin{1})
+            %%%%%%%%%%  f = mfir('foo.xml')   %%%%%%%%%%
+            %%%%%%%%%%  f = mfir('foo.mat')   %%%%%%%%%%
+            utils.helper.msg(msg.OPROC1, 'constructing from file %s', varargin{1});
+            obj = fromFile(obj, plist('filename', varargin{1}));
+            
+          elseif isa(varargin{1}, 'ao')
+            %%%%%%%%%%  f = mfir(ao-object)   %%%%%%%%%%
+            utils.helper.msg(msg.OPROC1, 'constructing from AO %s', varargin{1}.name);
+            pl = mfir.getDefaultPlist('From AO');
+            pl = pset(pl, 'AO', varargin{1});
+            obj = fromAO(obj, pl);
+            
+          elseif isstruct(varargin{1})
+            %%%%%%%%%%  f = mfir(struct)   %%%%%%%%%%
+            utils.helper.msg(msg.OPROC1, 'constructing from struct');
+            obj = fromStruct(obj, varargin{1});
+            
+          elseif isa(varargin{1}, 'pzmodel')
+            %%%%%%%%%%  f = mfir(pzmodel-object)   %%%%%%%%%%
+            utils.helper.msg(msg.OPROC1, 'constructing from pzmodel %s', varargin{1}.name);
+            obj = fromPzmodel(obj, plist('pzmodel', varargin{1}));
+            
+          elseif isa(varargin{1}, 'plist')
+            %%%%%%%%%%  f = mfir(plist-object)   %%%%%%%%%%
+            %----------- plist
+            
+            pl       = varargin{1};
+            
+            % Selection of construction method
+            if pl.isparam('filename')
+              utils.helper.msg(msg.OPROC1, 'constructing from file %s', pl.find('filename'));
+              obj = fromFile(obj, pl);
+              
+            elseif pl.isparam('hostname') || pl.isparam('conn')
+              utils.helper.msg(msg.OPROC1, 'constructing from repository');
+              obj = obj.fromRepository(pl);
+              
+            elseif pl.isparam('type')
+              utils.helper.msg(msg.OPROC1, 'constructing standard %s filter', pl.find('type'));
+              obj = fromStandard(obj, pl);
+              
+            elseif pl.isparam('pzmodel')
+              utils.helper.msg(msg.OPROC1, 'constructing from pzmodel object');
+              obj = fromPzmodel(obj, pl);
+              
+            elseif pl.isparam('a')
+              utils.helper.msg(msg.OPROC1, 'constructing from A/B coefficients');
+              obj = fromA(obj, pl);
+              
+            elseif pl.isparam('AO')
+              utils.helper.msg(msg.OPROC1, 'constructing from AO');
+              obj = fromAO(obj, pl);
+              
+            elseif pl.isparam('built-in')
+              utils.helper.msg(msg.OPROC1, 'constructing from built-in model');
+              obj = fromModel(obj, pl);
+              
+            elseif pl.isparam('plist')
+              %--- Construct from plist
+              % if the plist is empty, we return an empty MFIR
+              ipl = find(pl, 'plist');
+              if nparams(ipl) == 0
+                obj = mfir();
+              else
+                % do plist constructor
+                obj = mfir(ipl);
+              end
+              
+            else
+              obj.setObjectProperties(pl);
+              obj.addHistory(mfir.getInfo('mfir', 'None'), pl, [], []);
+            end
+            
+          else
+            error('### Unknown 1 argument constructor.');
+          end
+        case 2
+          %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+          %%%%%%%%%%%%%%%%%%%%%%%%%%%   two input   %%%%%%%%%%%%%%%%%%%%%%%%%%%
+          %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+          
+          if isa(varargin{1}, 'ao')
+            %%%%%%%%%%  f = mfir(ao-object, plist-object)   %%%%%%%%%%
+            utils.helper.msg(msg.OPROC1, 'constructing from AO %s', varargin{1}.name);
+            obj = fromAO(obj, pset(varargin{2}, 'AO', varargin{1}));
+            
+          elseif (isa(varargin{1}, 'database') || isa(varargin{1}, 'mpipeline.repository.RepositoryConnection')) ...
+              && isnumeric(varargin{2})
+            %%%%%%%%%%  f = mfir(<database-object>, [IDs])   %%%%%%%%%%
+            utils.helper.msg(msg.OPROC1, 'retrieve from repository');
+            obj = obj.fromRepository(plist('conn', varargin{1}, 'id', varargin{2}));
+            
+          elseif isa(varargin{1}, 'pzmodel') && isa(varargin{2}, 'plist')
+            %%%%%%%%%%  f = mfir(pzmodel-object, plist-object)   %%%%%%%%%%
+            utils.helper.msg(msg.OPROC1, 'constructing from pzmodel %s', varargin{1}.name);
+            obj = fromPzmodel(obj, combine(plist('pzmodel', varargin{1}), varargin{2}));
+            
+          elseif isa(varargin{1}, 'mfir') && isa(varargin{2}, 'plist') && isempty(varargin{2}.params)
+            %%%%%%%%%%  f = mfir(mfir, <empty-plist>)   %%%%%%%%%%
+            obj = mfir(varargin{1});
+            
+          elseif isnumeric(varargin{1})
+            %%%%%%%%%%  f = mfir(a, fs)   %%%%%%%%%%
+            utils.helper.msg(msg.OPROC1, 'constructing from A coefficients');
+            obj = fromA(obj, plist('A', varargin{1}, 'fs', varargin{2}));
+            
+          elseif isa(varargin{1}, 'org.apache.xerces.dom.DeferredElementImpl') && ...
+              isa(varargin{2}, 'history')
+            %%%%%%%%%%   obj = mfir(DOM node, history-objects)   %%%%%%%%%%
+            obj = fromDom(obj, varargin{1}, varargin{2});
+            
+          elseif isa(varargin{1}, 'ltpda_uoh') && isa(varargin{2}, 'plist')
+            %%%%%%%%%%%   mfir(<ltpda_uoh>-object, plist-object)   %%%%%%%%%%
+            % always recreate from plist
+            
+            % If we are trying to load from file, and the file exists, do
+            % that. Otherwise, copy the input object.
+            if varargin{2}.isparam('filename')
+              if exist(fullfile('.', find(varargin{2}, 'filename')), 'file')==2
+                obj = mfir(varargin{2});
+              else
+                obj = mfir(varargin{1});
+              end
+            else
+              obj = mfir(varargin{2});
+            end
+          else
+            error('### Unknown 2 argument constructor.');
+          end
+          
+        otherwise
+          [firs, invars, rest] = utils.helper.collect_objects(args, 'mfir');
+          
+          %%% Do we have a list of MFIR objects as input
+          if ~isempty(firs) && isempty(rest)
+            obj = mfir(firs);
+          else
+            error('### Unknown number of arguments.');
+          end
+      end
+      
+    end % End constructor
+  end % End public methods
+  
+  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+  %                            Methods (static)                               %
+  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+  methods (Static)
+    
+    function mdls = getBuiltInModels(varargin)
+      mdls = ltpda_uo.getBuiltInModels('mfir');
+    end
+    
+    function out = VEROUT()
+      out = '$Id: mfir.m,v 1.117 2011/08/15 12:22:57 hewitson Exp $';
+    end
+    
+    function ii = getInfo(varargin)
+      ii = utils.helper.generic_getInfo(varargin{:}, 'mfir');
+    end
+    
+    function out = SETS()
+      out = [SETS@ltpda_uoh,    ...
+        {'From Standard Type'}, ...
+        {'From Pzmodel'},       ...
+        {'From A'},             ...
+        {'From AO'}];
+    end
+    
+    
+    function plout = getDefaultPlist(set)
+      persistent pl;
+      persistent lastset;
+      if exist('pl', 'var')==0 || isempty(pl) || ~strcmp(lastset, set)
+        pl = mfir.buildplist(set);
+        lastset = set;
+      end
+      plout = pl;
+    end
+    
+    function out = buildplist(set)
+      
+      if ~utils.helper.ismember(lower(mfir.SETS), lower(set))
+        error('### Unknown set [%s]', set);
+      end
+      
+      out = plist();
+      out = mfir.addGlobalKeys(out);
+      out = buildplist@ltpda_uoh(out, set);
+      
+      switch lower(set)
+        case 'from standard type'
+          
+          % Type
+          p = param({'type','Choose the filter type.'}, {2, {'highpass', 'lowpass', 'bandpass', 'bandreject'}, paramValue.SINGLE});
+          out.append(p);
+          
+          % Fc
+          p = param({'fc','The roll-off frequency [Hz].'},  paramValue.DOUBLE_VALUE([0.1 0.4]));
+          out.append(p);
+          
+          % Gain
+          p = param({'gain','The gain of the filter.'},  paramValue.DOUBLE_VALUE(1));
+          out.append(p);
+          
+          % Fs
+          p = param({'fs','The sampling frequency to design for.'}, paramValue.DOUBLE_VALUE(1));
+          out.append(p);
+          
+          % Order
+          p = param({'order', 'The filter order.'}, paramValue.DOUBLE_VALUE(128));
+          out.append(p);
+          
+          % Iunits
+          p = param({'iunits','The input units of the filter.'}, paramValue.EMPTY_STRING);
+          out.append(p);
+          
+          % Ounits
+          p = param({'ounits','The output units of the filter.'}, paramValue.EMPTY_STRING);
+          out.append(p);
+          
+        case 'from pzmodel'
+          
+          % Pzmodel
+          p = param({'pzmodel', 'A pole/zero model to design from.'}, {1, {pzmodel}, paramValue.OPTIONAL});
+          out.append(p);
+          
+          % Fs
+          p = param({'fs','The sampling frequency to design for.'}, paramValue.EMPTY_DOUBLE);
+          out.append(p);
+          
+          % Iunits
+          p = param({'iunits','The input units of the transfer function.'}, paramValue.EMPTY_STRING);
+          out.append(p);
+          
+          % Ounits
+          p = param({'ounits','The output units of the transfer function.'}, paramValue.EMPTY_STRING);
+          out.append(p);
+          
+        case 'from ao'
+          
+          % AO
+          p = param({'AO', 'The AO object to design from.'}, {1, {ao}, paramValue.OPTIONAL});
+          out.append(p);
+          
+          % N
+          p = param({'N', 'The filter order.'}, paramValue.DOUBLE_VALUE(512));
+          out.append(p);
+          
+          % Method
+          p = param({'Method', ['The filter design method:<ul>'...
+            '<li>''frequency-sampling'' - uses <a href="matlab:doc(''fir2'')">fir2()</a></li>',...
+            '<li>''least-squares''      - uses <a href="matlab:doc(''firls'')">firls()</a></li>',...
+            '<li>''Parks-McClellan''    - uses <a href="matlab:doc(''firpm'')">firpm()</a></li></ul>']}, {1, {'frequency-sampling', 'least-squares', 'Parks-McClellan'}, paramValue.SINGLE});
+          out.append(p);
+          
+          % Win
+          p = param({'win', 'A window to design with when using the frequency-sampling method.'}, paramValue.WINDOW);
+          out.append(p);
+          
+          % PSLL
+          p = param({'psll', 'If you specify a Kaiser window, you can also specify the PSLL.'}, paramValue.DOUBLE_VALUE(100));
+          out.append(p);
+          
+          % Iunits
+          p = param({'iunits','The input units of the transfer function.'}, paramValue.EMPTY_STRING);
+          out.append(p);
+          
+          % Ounits
+          p = param({'ounits','The output units of the transfer function.'}, paramValue.EMPTY_STRING);
+          out.append(p);
+          
+        case 'from a'
+          
+          % A
+          p = param({'a','Vector of A coefficients.'}, paramValue.EMPTY_DOUBLE);
+          out.append(p);
+          
+          % Fs
+          p = param({'fs','Sampling frequency of the filter.'}, paramValue.EMPTY_DOUBLE);
+          out.append(p);
+          
+          % Iunits
+          p = param({'iunits','The input units of the transfer function.'}, paramValue.EMPTY_STRING);
+          out.append(p);
+          
+          % Ounits
+          p = param({'ounits','The output units of the transfer function.'}, paramValue.EMPTY_STRING);
+          out.append(p);
+          
+      end
+    end
+    
+    function obj = initObjectWithSize(n,m)
+      obj = mfir.newarray([n m]);
+    end
+    
+  end % End static methods
+  
+  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+  %                         Methods (static, private)                         %
+  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+  
+  methods (Static, Access=private)
+    plo = parseFilterParams(pl)
+  end
+  
+  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+  %                         Methods (static, hidden)                          %
+  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+  
+  methods (Static = true, Hidden = true)
+    varargout = loadobj(varargin)
+    varargout = update_struct(varargin);
+  end
+  
+  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+  %                              Methods (public)                             %
+  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+  
+  methods
+    varargout = char(varargin)
+    varargout = copy(varargin)
+    varargout = display(varargin)
+    
+    varargout = setGd(varargin)
+  end
+  
+  methods (Hidden = true)
+    varargout = attachToDom(varargin)
+  end
+  
+  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+  %                              Methods (protected)                          %
+  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+  
+  methods (Access = protected)
+    varargout = fromStruct(varargin)
+    varargout = fromDom(varargin)
+  end
+  
+  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+  %                               Methods (private)                           %
+  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+  
+  methods (Access = private)
+    f = fromPzmodel(f, pli)
+    f = fromA(f, pli)
+    f = fromAO(f, pli)
+    f = fromStandard(f, pli)
+    
+    f = mklowpass(f, pl)
+    f = mkhighpass(f, pl)
+    f = mkbandpass(f, pl)
+    f = mkbandreject(f, pl)
+  end
+  
+end
+