geninfds.m

有关kalman滤波及其一些变形滤波算法

function InferenceDS = geninfds(ArgDS)

% GENINFDS  Generate inference data structure from a generalized state space model and user defined inference parameters.
%
%   InferenceDS = geninfds(ArgDS)
%
%   This function generates a ReBEL inference data structure from a generalized state space model (gssm) data
%   structure. This inference data structure is used by all ReBEL estimation algorithms. All the parameters and
%   information needed to build the data structures are passed into the function by means of a user defined argument
%   data structure, ArgDS. The specifics of the input and output parameters are given
%   below.
%
%   INPUT ARGUMENT DATA STRUCTURE FIELDS  : ArgDS._______
%
%     .type               : (string)      Inference (estimation) type : 'state', 'parameter' or 'joint'
%     .tag                : (string)      Arbitrary user defined ID tag string
%     .model              : (gssm)        Generalized state space model descriptor (see gssm.m)
%
%     .paramParamIdxVec   : (r-vector)   <<OPTIONAL for parameter and joint estimation, not used by state estimation>>
%                                         Index vector containing indices of a subset of parameters which must be
%                                         estimated. Default (if ommitted) is to estimate all parameters.
%     .paramFunSelect     : (string)     <<OPTIONAL for parameter estimation, not used by state and joint estimation>>
%                                         String indicating which of the state-transition 'ffun' or state-observation
%                                         'hfun' functions should be used as the functional unit for parameter estimation.
%                                         The default value for this field (if ommitted) is 'both' which uses both functions,
%                                         i.e. obs=hfun(ffun(x)). One can also specify 'both-p' which uses both functions
%                                         in a parallel combination, i.e. obs = [ffun(x)]
%                                                                               [hfun(x)]
%     .paramFFunOutIdxVec : (r-vector)   <<OPTIONAL for parameter estimation, not used by state and joint estimation>>
%                                         Index vector containing indices of a subset of the output of FFUN which must be
%                                         used for parameter estimation observations. This argument is only used if
%                                         .paramFunSelect = 'both' or 'ffun'. The default is to use all FFUN outputs.
%     .paramHFunOutIdxVec : (r-vector)   <<OPTIONAL for parameter estimation, not used by state and joint estimation>>
%                                         Index vector containing indices of a subset of the output of HFUN which must be
%                                         used for parameter estimation observations. This argument is only used if
%                                         .paramFunSelect = 'both' or 'hfun'. The default is to use all HFUN outputs.
%
%
%   OUTPUT ARGUMENTS
%
%     InferenceDS         : inference data structure
%
%     See also
%     GSSM, GENNOISEDS, GENSYSNOISEDS, CONSIST
%
%   Copyright (c) Oregon Health & Science University (2006)
%
%   This file is part of the ReBEL Toolkit. The ReBEL Toolkit is available free for
%   academic use only (see included license file) and can be obtained from
%   http://choosh.csee.ogi.edu/rebel/.  Businesses wishing to obtain a copy of the
%   software should contact [e-mail] for commercial licensing information.
%
%   See LICENSE (which should be part of the main toolkit distribution) for more
%   detail.

%========================================================================================================


%--- ERROR CHECKING -------------------------------------------------------------------------------------

if (nargin < 1)
    error(' [ geninfds ] Not enough inputs.');
end

if ~isstruct(ArgDS)
    error(' [ geninfds ] Input argument must be an argument data structure ArgDS.');
end

mf = checkstructfields(ArgDS,'type','model');  % Check existence of required data structure fields
if ~isempty(mf)
    error([' [ geninfds ] Argument data structure does not contain the following required fields : ' mf]);
end

if ~ischar(ArgDS.type)
    error(' [ geninfds ] ArgDS.type must be a string indicating the inference type, i.e. ''state'', ''parameter'' or ''joint''.');
end


%--- BUILD INFERENCE DATA STRUCTURE ----------------------------------------------------------------------

InferenceDS.type    = 'InferenceDS';   % data structure type
InferenceDS.inftype = ArgDS.type;      % inference type


if isfield(ArgDS,'tag'),
    InferenceDS.tag  = ArgDS.tag;                         % ID tag
else
    InferenceDS.tag  = '';
end

if ~isempty(consistent(ArgDS.model,'gssm'));                 % check for consistentency of GSSM data structure
    error([' [ geninfds ] There is an inconsistentency with the supplied GSSM data structure subfield. Please use ' ...
           'the CONSIST function on the GSSM model to determine the exact problem.']);
else
    model = ArgDS.model;
    InferenceDS.model = model;                            % embed GSSM model
end



switch ArgDS.type

    %---
    %--- STATE ESTIMATION  --------------------------------------------------------------------------------
    %---
    case 'state'

        %--- dimensions & other detail ---
        InferenceDS.statedim = model.statedim;                % state dimension
        InferenceDS.obsdim   = model.obsdim;                  % observation dimension
        InferenceDS.U1dim    = model.U1dim;                   % exogenous input 1 dimension
        InferenceDS.U2dim    = model.U2dim;                   % exogenous input 2 dimension
        InferenceDS.Vdim = model.pNoise.dim;                  % process noise dimension
        InferenceDS.Ndim = model.oNoise.dim;                  % observation noise dimension

        %--- function handles ---
        InferenceDS.ffun = @ffun_state;
        InferenceDS.hfun = @hfun_state;
        if isfield(model, 'prior'),
            InferenceDS.prior = @prior_state;
        end
        if isfield(model,'likelihood'),
            InferenceDS.likelihood = @likelihood_state;
        end
        if isfield(model,'innovation'),
            InferenceDS.innovation = @innovation_state;
        else
            InferenceDS.innovation = [];
        end
        if isfield(model,'linearize'),
            InferenceDS.linearize = @linearize_state;             % linearization function functionhandle
        else
            InferenceDS.linearize = @linearize_generic;           % generic (perturbation based linearization)
        end

        %--- other stuff ---
        % Index vectors indicating the presence of angular components in the state and observation vectors
        if isfield(model,'stateAngleCompIdxVec'),
            InferenceDS.stateAngleCompIdxVec = model.stateAngleCompIdxVec;
        else
            InferenceDS.stateAngleCompIdxVec = [];
        end
        if isfield(model,'obsAngleCompIdxVec'),
            InferenceDS.obsAngleCompIdxVec = model.obsAngleCompIdxVec;
        else
            InferenceDS.obsAngleCompIdxVec = [];
        end


    %---
    %--- PARAMETER ESTIMATION ----------------------------------------------------------------------------
    %---
    case 'parameter'

        % Check parameter index vector
        if ~isfield(ArgDS,'paramParamIdxVec')
            paramParamIdxVec = 1:model.paramdim;
        else
            paramParamIdxVec = ArgDS.paramParamIdxVec;
            % Check vector entries
            if ((max(paramParamIdxVec) > model.paramdim) | (min(paramParamIdxVec) < 1))
                error(' [ geninfds::parameter ] Parameter index vector has illegal entries');
            end
            % Check for duplicate index entries
            if checkdups(paramParamIdxVec)
                error(' [ geninfds::parameter ] Duplicate parameter index vector entries not allowed.');
            end
        end
        InferenceDS.paramParamIdxVec = paramParamIdxVec;                      % copy index vector in InferenceDS

        % Check parameter function select argument
        if ~isfield(ArgDS,'paramFunSelect')
            paramFunSelect = 'both';
        elseif stringmatch(ArgDS.paramFunSelect,{'ffun','hfun','both-p','both'})
            paramFunSelect = ArgDS.paramFunSelect;
        else
            error(' [ geninfds::parameter ] Unknown value used for paramFunSelect');
        end
        InferenceDS.paramFunSelect = paramFunSelect;                          % copy parameter function select string

        % Check ffun and hfun output index vectors
        if stringmatch(paramFunSelect,{'both-p','ffun'})
            if ~isfield(ArgDS,'paramFFunOutIdxVec')
                paramFFunOutIdxVec = 1:model.statedim;
            else
                paramFFunOutIdxVec = ArgDS.paramFFunOutIdxVec;
                % Check vector entries
                if ((max(paramFFunOutIdxVec) > model.statedim) | (min(paramFFunOutIdxVec) < 1))
                    error(' [ geninfds::parameter ] FFUN output index vector has illegal entries');
                end
                % Check for duplicate index entries
                if checkdups(paramFFunOutIdxVec)
                    error(' [ geninfds::parameter ] Duplicate FFUN output index vector entries not allowed.');
                end
            end
            InferenceDS.paramFFunOutIdxVec = paramFFunOutIdxVec;                  % copy ffun output
        end
        if stringmatch(paramFunSelect,{'both','hfun','both-p'})
            if ~isfield(ArgDS,'paramHFunOutIdxVec')
                paramHFunOutIdxVec = 1:model.obsdim;
            else
                paramHFunOutIdxVec = ArgDS.paramHFunOutIdxVec;
                % Check vector entries
                if ((max(paramHFunOutIdxVec) > model.obsdim) | (min(paramHFunOutIdxVec) < 1))
                    error(' [ geninfds::parameter ] HFUN output index vector has illegal entries');
                end
                % Check for duplicate index entries
                if checkdups(paramHFunIdxVec)
                    error(' [ geninfds::parameter ] Duplicate HFUN output index vector entries not allowed.');
                end
            end
            InferenceDS.paramHFunOutIdxVec = paramHFunOutIdxVec;                  % copy ffun output
        end



        %-- Setup rest of structure

        switch paramFunSelect

        %...................................................................................................................
        case 'both'

            %--- dimensions & other detail ---
            InferenceDS.statedim = length(paramParamIdxVec);                 % state dimension
            InferenceDS.obsdim = length(paramHFunOutIdxVec);                 % observation dimension
            InferenceDS.U1dim = 0;                                           % expgenous input 1 dimension
            InferenceDS.U2dim = model.U1dim + model.statedim + model.U2dim;  % exogenous input 2 dimension
            InferenceDS.Vdim = InferenceDS.statedim;                         % process noise dimension
            InferenceDS.Ndim = model.Vdim + model.Ndim;                      % observation noise dimension

            %--- functions ---
            InferenceDS.ffun = @ffun_parameter;                             % state transition function functionhandle
            InferenceDS.hfun = @hfun_parameter_both;                        % state observation function functionhandle
            if isfield(model,'linearize')
                InferenceDS.linearize = @linearize_parameter_both;          % linearization function functionhandle
            else
                InferenceDS.linearize = @linearize_generic;
            end
            InferenceDS.prior = @prior_parameter;
            if isfield(model,'likelihood'),
                InferenceDS.likelihood = @likelihood_parameter_both;
            end
            if isfield(model,'innovation'),
                InferenceDS.innovation = @innovation_state;
            else
                InferenceDS.innovation = [];
            end

            %--- copy/setup fixed linear model parameters ---
            InferenceDS.A = eye(InferenceDS.statedim);
            InferenceDS.B = [];
            InferenceDS.G = eye(InferenceDS.statedim);

            %--- other stuff ---
            % Index vectors indicating the presence of angular components in the state and observation vectors
            InferenceDS.stateAngleCompIdxVec = [];
            InferenceDS.obsAngleCompIdxVec = [];
            if isfield(model,'obsAngleCompIdxVec'),
               for k=1:length(model.obsAngleCompIdxVec),
                 idx = find(InferenceDS.paramHFunOutIdxVec == model.obsAngleCompIdxVec(k));
                 InferenceDS.obsAngleCompIdxVec = [InferenceDS.obsAngleCompIdxVec idx];
               end
            end


        %...................................................................................................................
        case 'both-p'

            %--- dimensions & other detail ---
            InferenceDS.statedim = length(paramParamIdxVec);                        % state dimension
            InferenceDS.obsdim = length(paramFFunOutIdxVec) + length(paramHFunOutIdxVec); % observation dimension
            InferenceDS.U1dim = 0;                                                  % exogenous input 1 dimension
            InferenceDS.U2dim = model.U1dim + 2*model.statedim + model.U2dim;       % exogenous input 2 dimension
            InferenceDS.Vdim = InferenceDS.statedim;                                % process noise dimension
            InferenceDS.Ndim = model.Vdim+model.Ndim;                               % observation noise dimension

            %--- functions ---
            InferenceDS.ffun = @ffun_parameter;                               % state transition function functionhandle
            InferenceDS.hfun = @hfun_parameter_bothp;                         % state observation function functionhandle
            if isfield(model,'linearize')
                InferenceDS.linearize = @linearize_parameter_bothp;           % linearization function functionhandle
            else
                InferenceDS.linearize = @linearize_generic;
            end
            InferenceDS.prior = @prior_parameter;
            if (isfield(model,'likelihood') & isfield(model,'prior')),
                InferenceDS.likelihood = @likelihood_parameter_bothp;
            end
            InferenceDS.innovation = [];

            %--- copy/setup fixed linear model parameters ---
            InferenceDS.A = eye(InferenceDS.statedim);
            InferenceDS.B = [];
            InferenceDS.G = eye(InferenceDS.statedim);

            %--- other stuff ---
            % Index vectors indicating the presence of angular components in the state and observation vectors