classdef recursiveAR < recursiveARX
    %recursiveAR  Estimate AR models using recursive estimation algorithms
    %
    %   Estimate the coefficients of the AR models of the following form:
    %     A(q) y(t) =  e(t)
    %   where y(t) is the output measurement. A(q) is a polynomial of the
    %   time-delay operator 1/q, whose coefficients are estimated. e(t) is
    %   an unknown scalar that represents white noise.
    %
    %   X = recursiveAR returns the recursiveAR estimator system object, X,
    %   to estimate 1 parameter in A(q). The initial guess for the
    %   parameter is 'eps'.
    %
    %   X = recursiveAR(na) returns the recursiveAR estimator system
    %   object, X, to estimate na parameters in A(q). na is a positive
    %   scalar.
    %
    %   X = recursiveAR(na,A0) returns the recursiveAR estimator system
    %   object, X, with initial guess for the polynomial coefficients in
    %   A0. A0 is a row vector of length na+1 and its first element must be
    %   1.
    %
    %   X = recursiveAR(na,'PropertyName',PropertyValue) returns a
    %   recursiveAR estimator object, X, with each specified property set
    %   to the specified value.
    %
    %   step method syntax:
    %
    %   [A,yHat] = step(X, y) carries out the recursive algorithm over the
    %   measurement y(t). A is the current parameter estimates for A(q).
    %   yHat is the estimate of y(t) based on A and the past values of y.
    %
    %   recursiveAR methods:
    %
    %   step     - See above description for use of this method
    %   release  - Allow property value and input characteristics changes
    %   clone    - Create another recursiveAR System object with same property values
    %   isLocked - Locked status (logical)
    %   <a href="matlab:help matlab.System/reset   ">reset</a>    - Reset the internal states to initial conditions
    %
    %   recursiveAR properties:
    %
    %   InitialA                   - The initial polynomial coefficients of A(q)
    %   EstimationMethod           - 'ForgettingFactor' (Default),
    %                                'KalmanFilter', 'Gradient' or
    %                                'NormalizedGradient'
    %   ForgettingFactor           - Forgetting factor, only used by the
    %                                ForgettingFactor algorithm
    %   ProcessNoiseCovariance     - The covariance of the process noise acting
    %                                on the parameter values. Only used by the
    %                                KalmanFilter algorithm
    %   AdaptationGain             - Adaptation gain, only used by the
    %                                Gradient and NormalizedGradient
    %                                algorithms
    %   NormalizationBias          - Bias on adaptation gain scaling. Only 
    %                                used by the NormalizedGradient algorithm    
    %   InitialParameterCovariance - Initial value for covariance of the
    %                                parameter estimation error
    %   EnableAdaptation           - Can be used to enable/disable the
    %                                parameter (theta) adaptation
    %
    %   EXAMPLE: Estimating a time-invariant AR model
    %      % Construct the estimator.
    %      X = recursiveAR(6); % na=6
    %      % Provide initial parameter guesses (optional).
    %      X.InitialA = [1 -0.6 -0.4 -0.1 0.1 0.1 0.1];
    %      % Provide variances of initial parameter guesses (optional).
    %      X.InitialParameterCovariance = 0.1;
    %      % Load the estimation data.
    %      load iddata9 z9;
    %      % Call the estimator's step command with the output data one piece at a
    %      % time to update parameters. This illustrates online operation of the
    %      % estimator.
    %      for kk=1:numel(z9.y);
    %          [A,yHat] = step(X,z9.y(kk));
    %      end
    %      % Take a snapshot of the current model parameters.
    %      sysX = idpoly(X);
    %      % Set the sample time of the model snapshot from the data.
    %      sysX.Ts = z9.Ts;
    %      % Compare 
    %      compare(z9,sysX);
    %
    % See also ar, recursiveARMA, recursiveARX, recursiveARMAX,
    % recursiveOE, recursiveBJ, recursiveLS
    
    %   Copyright 2015-2018 The MathWorks, Inc.
    
    %#codegen
    
    methods
        function this = recursiveAR(varargin)
            this@recursiveARX(varargin{:});
        end
    end
    
    methods(Access = protected)
        function setInitialParameters(this,tunablePropNVPairs,firstNVIndex,varargin)
            setInitialPolynomialCoefficients(this,'A',2,tunablePropNVPairs,firstNVIndex,varargin{:});
        end

        function setInitialIOBuffers(this,tunablePropNVPairs)
            % Set initial input-output buffers during object construction
            
            % These properties are only used with History='Finite'
            if ~this.IsHistoryFinite_
                return;
            end
            
            % Assign InitialOutputs
            if ~isempty(tunablePropNVPairs.InitialOutputs)
                this.InitialOutputs = cast(tunablePropNVPairs.InitialOutputs, this.DataType);
            else
                this.InitialOutputs = cast(0, this.DataType); % scalar will be expanded in .set method
            end
        end        
        
        function validateOrdersPreSetImpl(~,val)
            % Orders must be a positive integer scalar. Finite, integer
            % checks are done in the superclass
            validateattributes(val,{'numeric'},{'scalar','positive'},'','Orders',1);
        end
        
        function setOrdersImpl(this,val)
            this.na = val(1);
        end
        
        function [A,yHat] = stepImpl(this,y)
            [A,~,yHat] = stepImpl@recursiveARX(this,y,cast(0,'like',y));
        end
        
        function validateInputsImpl(this,y)
            validateInputsImpl@recursiveARX(this,y,cast(0,'like',y));
        end
        
        function s = getDiscreteStateImpl(this)
            % Present estimator states to the user
            s = getDiscreteStateImpl@idRecursivePolynomialModelEstimator(this);
            s.A = this.A;
        end
        
        function isInactive = isInactivePropertyImpl(this,propName)
            % Hide the unused properties of the superclass
            isInactive = isInactivePropertyImpl@recursiveARX(this,propName);
            if isInactive
                return;
            end
            switch propName
                case {'InitialB','B','InitialInputs'}
                    isInactive = true();
            end
        end
    end
    
    methods(Static,Access=protected)
        function orders = defaultOrders()
            orders = 1;
        end
        
        function val = latestPossibleNVPairPosition()
            val = 3;
        end
    end    
end

% LocalWords:  online nontunable
