gennoiseds.m

递归贝叶斯估计的工具包

function NoiseDS = gennoiseds(ArgDS)

% GENNOISEDS    Generates a NoiseDS data structure describing a noise source.
%
%   NoiseDS = gennoiseds(ArgDS)
%
%   This function generates a ReBEL noise source which is encapsulated in the NoiseDS data structure.
%   All arguments to the function are passed via the ArgDS argument data structure which has the
%   following fields, depending on the required noise source type:
%
%   1) Gaussian Noise Source   :  Single Gaussian noise source
%
%      ArgDS.type    : (string)    'gaussian'
%           .cov_type : (string)    'full'       full covariance matrix (default value)
%                                  'diag'       single diagonal covariance
%                                  'sqrt'       square-root form (lower triangular Cholesky factor)
%                                  'sqrt-diag'  square-root single diagonal form
%           .tag     : (string)     ID tag      (default='')
%           .dim     : (scalar)     noise vector length
%           .mu      : (c-vector)   mean vector
%           .cov     : (matrix)     covariance matrix (should comply with cov_type)
%
%   2) Combination Gaussian Noise Source : Combination of N independent Gaussian sources. All Gaussian
%                                          sources must have the same cov_type.
%
%      ArgDS.type     : (string)      'combo-gaussian'
%           .tag      : (string)      ID tag
%           .dim      : (scalar)      noise vector length
%           .noiseSources : (cell array)  cell array of N Guassian noise sources (NoiseDS data structures)
%
%
%   3) Generic Combination Noise Source : Combination of N independent noise sources.
%
%      ArgDS.type     : (string)      'combo'
%           .tag      : (string)      ID tag
%           .dim      : (scalar)      noise vector length
%           .noiseSources : (cell array)  cell array of N noise sources (NoiseDS data structure)
%
%
%   4) Scalar Gamma noise source
%
%      ArgDS.type     : (string)      'gamma'
%           .tag      : (string)      ID tag
%           .dim      : (scalar)      1 (multivariate Gamma noise not yet supported)
%           .alpha    : (scalar)      alpha parameter
%           .beta     : (scalar)      beta parameter
%
%
%   5) Gaussian Mixture noise Source
%
%      ArgDS.type     : (string)   'gmm'
%           .cov_type  : (string)   'full'       full covariance matrix (default value)
%                                  'diag'       single diagonal covariance
%                                  'sqrt'       square-root form (lower triangular Cholesky factor)
%                                  'sqrt-diag'  square-root single diagonal form
%           .tag     : (string)     ID tag      (default='')
%           .dim     : (scalar)     noise vector dimension
%           .M       : (scalar)     number of Gaussian component densities
%           .mu      : (dim-by-M matrix)  noise mean vectors of M mixture components
%           .cov     : (dim-by-dim-by-M matrix)  noise covariance matrices of N mixture components (should comply with cov_type)
%           .weights : (1-by-N vector)    mixing weights (priors) of mixture components
%
%
%   The generated noise source data structure, NoiseDS, has the following required fields. Depending on the noise source
%   type, the data structure may also have other type dependent fields. See documentation for full details.
%
%     NoiseDS.type       : (string) data structure type : 'NoiseDS'
%            .ns_type    : (string) noise source type
%            .dim        : (scalar) noise source dimension
%            .sample     : (function handle) Function to generate N noise source samples
%            .likelihood : (finction handle) Function to evaluate the likelihood of a given noise source sample
%            .update     : (function handle) <<optional>> Function to update the internal structure of noise source.
%                                            This is not required of all noise sources.
%
%   See also
%     CONSISTENT, GENSYSNOISEDS
%

%   Copyright  (c) Rudolph van der Merwe (2002)
%
%   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 by contacting
%   [e-mail].  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 & TYPE INDEPENDENT STRUCTURE ASSIGNMENT ---------------------------------------------

if (nargin ~= 1), error(' [ gennoiseds ] Incorrect number of inputs'); end

if ~isstruct(ArgDS), error(' [ gennoiseds ] The input argument to this function must be an argument data structure.'); end

if ~(isfield(ArgDS,'type') & ischar(ArgDS.type))
  error(' [ gennoiseds ] The argument data structure must have a ''type'' field, specifying the desired noise source type. This field must be a string.');
else
  Noise.type = ArgDS.type;       % assign noise source type
end

if isfield(ArgDS,'tag')          % assign tag
  if ischar(ArgDS.tag)
    Noise.tag = ArgDS.tag;
  else
    error(' [ gennoiseds ] The ''tag'' field must be a string.');
  end
else
  Noise.tag = '';
end

if (isfield(ArgDS,'dim') & isnumeric(ArgDS.dim) & (length(ArgDS.dim(:))==1))   %-- Check for and assign noise source dimension
  Noise.dim  = ArgDS.dim;
else
  error(' [ gennoiseds ] Noise source dimension not specified or not a scalar.');
end


%--- BUILD NOISE SOURCE DEPENDENT ON TYPE ----------------------------------------------------

switch (Noise.type)

%=============================================================================================
case 'gamma'

    if (Noise.dim~=1)
        error(' [ gennoiseds::gamma ] Multivariate Gamma noise not supported yet.');
    end

    if isfield(ArgDS,'alpha') & isnumeric(ArgDS.alpha) & (size(ArgDS.alpha) == [1 1])
        Noise.alpha = ArgDS.alpha;
    else
        error(' [ gennoiseds::gamma ] Alpha parameter must be a scalar');
    end

    if isfield(ArgDS,'beta') & isnumeric(ArgDS.beta) & (size(ArgDS.beta) == [1 1])
        Noise.beta = ArgDS.beta;
    else
        error(' [ gennoiseds::gamma ] Beta parameter must be a scalar');
    end

    Noise.mu = Noise.alpha*Noise.beta;
    Noise.cov = Noise.alpha*(Noise.beta^2);

    NoiseDS.type = 'NoiseDS';
    NoiseDS.ns_type = Noise.type;
    NoiseDS.tag = Noise.tag;
    NoiseDS.dim = Noise.dim;
    NoiseDS.alpha = Noise.alpha;
    NoiseDS.beta = Noise.beta;
    NoiseDS.mu = Noise.mu;
    NoiseDS.cov = Noise.cov;
    NoiseDS.sample = @sample_gamma;
    NoiseDS.likelihood = @likelihood_gamma;

%=============================================================================================
case 'gaussian'

    %-- check for and assign cov_type
    if isfield(ArgDS,'cov_type')
        if (ischar(ArgDS.cov_type) & stringmatch(ArgDS.cov_type,{'full','diag','sqrt','sqrt-diag'}))
            Noise.cov_type = ArgDS.cov_type;
        else
            error(' [ gennoiseds::gaussian ] Noise source cov_type not recognized or not a string.');
        end
    else
        warning(' [ gennoiseds::gaussian ] Covariance type field .cov_type not assigned!. Assuming default value, ''full''');
        Noise.cov_type = 'full';             % default cov_type
    end

    %-- assign noise source mean vector
    if ~isfield(ArgDS,'mu')
        Noise.mu = zeros(Noise.dim,1);    % default value
    else
        Noise.mu = ArgDS.mu;
    end

    if ~isfield(ArgDS,'cov')
      warning(' [ gennoiseds::gaussian ] Covariance field .cov not assigned!. Assuming default unity value.');
    end

    %-- assign rest of noise source structure
    switch (Noise.cov_type)

    %.............................................................................................
    case 'full'

        %-- assign noise source covariance structure
        if ~isfield(ArgDS,'cov')
            Noise.cov = eye(Noise.dim);    % default value
        elseif (isnumeric(ArgDS.cov) & (size(ArgDS.cov) == [Noise.dim Noise.dim]))
            Noise.cov = ArgDS.cov;
        else
            error([' [ gennoiseds::gaussian::full ] Noise source covariance matrix of incorrect ' ...
                   'dimensions or type.']);
        end

    %.............................................................................................
    case 'diag'

        %-- assign noise source covariance structure
        if ~isfield(ArgDS,'cov')
            Noise.cov = eye(Noise.dim);           % default value
        elseif (isnumeric(ArgDS.cov) & (size(ArgDS.cov) == [Noise.dim Noise.dim]))
            % check if covariance only has entries on the diagonal
            if (ArgDS.cov==diag(diag(ArgDS.cov)))
                Noise.cov = ArgDS.cov;              % assign covariance matrix
            else
                error([' [ gennoiseds::gaussian::diag ] Diagonal Guassian noise source cannot ' ...
                       'have non-zero off diagonal values in the covariance matrix.']);
            end
        else
            error([' [ gennoiseds::gaussian::diag ] Noise source covariance matrix of incorrect ' ...
                  'dimensions or type.']);
        end

    %.............................................................................................
    case 'sqrt'

        %-- assign noise source covariance structure
        if ~isfield(ArgDS,'cov')
            Noise.cov = eye(Noise.dim);    % default value
        elseif (isnumeric(ArgDS.cov) & (size(ArgDS.cov) == [Noise.dim Noise.dim]))
            Noise.cov = ArgDS.cov;
        else
            error([' [ gennoiseds::gaussian::sqrt ] Noise source covariance matrix of incorrect ' ...
                   'dimensions or type.']);
        end


    %.............................................................................................
    case 'sqrt-diag'

        %-- assign noise source covariance structure
        if ~isfield(ArgDS,'cov')
            Noise.cov = eye(Noise.dim);            % default value
        elseif (isnumeric(ArgDS.cov) & (size(ArgDS.cov) == [Noise.dim Noise.dim]))
            % check if covariance only has entries on the diagonal
            if (ArgDS.cov == diag(diag(ArgDS.cov)))
                Noise.cov = ArgDS.cov;               % assign covariance matrix
            else
                error([' [ gennoiseds::gaussian::sqrt-diag ] Diagonal Guassian noise source ' ...
                       'cannot have non-zero off diagonal values in the covariance matrix.']);
            end
        else
            error([' [ gennoiseds::gaussian::sqrt-diag ] Noise source covariance matrix of ' ...
                   'incorrect dimensions or type.']);
        end

    %.............................................................................................
    otherwise
        error(' [ gennoiseds::gaussian ] Unkown noise source cov_type.');
    end


    % Restructure NoiseDS data structure
    NoiseDS.type = 'NoiseDS';
    NoiseDS.ns_type = Noise.type;
    NoiseDS.cov_type = Noise.cov_type;
    NoiseDS.tag = Noise.tag;
    NoiseDS.dim = Noise.dim;
    NoiseDS.mu = Noise.mu;
    NoiseDS.cov = Noise.cov;
    NoiseDS.sample = @gaussample;
    NoiseDS.update = @update_gaussian;
    NoiseDS.likelihood = @gauseval;




%===================================================================================================
case 'combo-gaussian'

    if (~isfield(ArgDS,'noiseSources') | ~iscell(ArgDS.noiseSources))
        error([' [ gennoiseds::combo-gaussian ] Sub noise source field (ArgDS.noiseSources) is ' ...
               'missing or is not a cell array.']);
    end

    Noise.N = length(ArgDS.noiseSources);    % number of sub noise sources
    if (Noise.N < 2)
        error([' [ gennoiseds::combo-gaussian ] A combo-Gaussian noise sources needs at ' ...
               'least 2 sub noise sources.']);
    end

    noisetype = ArgDS.noiseSources{1}.ns_type;
    cov_type = ArgDS.noiseSources{1}.cov_type;

    % Check cov_type type for correctness
    if ~(stringmatch(noisetype,{'gaussian','combo-gaussian'}) & ...
         stringmatch(cov_type,{'full','diag','sqrt','sqrt-diag'}))
        error(['[ gennoiseds::combo-gaussian ] A combination Gaussian noise source can ' ...
               'only have Gaussian sub noise sources.']);
    end

    % check for consistentency of cov_type of sub noise sources
    for k=1:Noise.N
        subNoise = ArgDS.noiseSources{k};
        if ~stringmatch(subNoise.cov_type,cov_type)
            error('[ gennoiseds::combo-gaussian ] Sub noise sources does not have consistentent cov_types.');
        end
    end

    Noise.cov_type = cov_type;                    % assign cov_type

    Noise.mu   = zeros(Noise.dim,1);            % setup mean vector
    Noise.cov  = zeros(Noise.dim);              % setup covariance matrix

    Noise.idxArr = zeros(Noise.N,2);            % buffer for beginning and ending indeces of sub noise
                                                % source entries in global mean and covariance

    % Extract sub noise source detail and build combo noise source
    dim = 0;
    for j=1:Noise.N,
        subNoise = ArgDS.noiseSources{j};       % copy j'th sub noise source
        dim = dim + subNoise.dim;               % add sub noise dimension to global dimension
        ind1 = dim-subNoise.dim+1;              % calculate beginning index value
        ind2 = dim;                             % calculate ending index value
        Noise.idxArr(j,:) = [ind1 ind2];        % store indeces in index array
        Noise.mu(ind1:ind2,1) = subNoise.mu;    % copy sub noise source mean
        Noise.cov(ind1:ind2,ind1:ind2) = subNoise.cov;  % copy sub noise covariance
    end
    if (Noise.dim ~= dim),
        error([' [ gennoiseds::combo-gaussian ] Combinded noise vector dimension does ' ...
               'not agree with agregate dimension of sub noise sources.']);
    end

    % Restructure NoiseDS data structure
    NoiseDS.type = 'NoiseDS';
    NoiseDS.ns_type = Noise.type;
    NoiseDS.cov_type = Noise.cov_type;
    NoiseDS.tag = Noise.tag;
    NoiseDS.N = Noise.N;
    NoiseDS.idxArr = Noise.idxArr;
    NoiseDS.dim = Noise.dim;
    NoiseDS.mu = Noise.mu;
    NoiseDS.cov = Noise.cov;
    NoiseDS.noiseSources = ArgDS.noiseSources;
    NoiseDS.sample = @sample_combo_gaussian;
    NoiseDS.update = @update_combo_gaussian;
    NoiseDS.likelihood = @likelihood_combo_gaussian;

%==================================================================================================
case 'combo'

    if (~isfield(ArgDS,'noiseSources') | ~iscell(ArgDS.noiseSources))
        error([' [ gennoiseds::combo ] Sub noise source field (ArgDS.noiseSources) ' ...
               'is missing or is not a cell array.']);
    end

    Noise.N = length(ArgDS.noiseSources);     % number of sub noise sources
    if (Noise.N < 2)
      error('[ gennoiseds::combo-gaussian ] A combo-Gaussian noise sources needs at least 2 sub noise sources.');
    end

    Noise.noiseSources = ArgDS.noiseSources;  % copy cell-array of sub noise sources

    Gaussian_flag = 1;                        % flag to check for the possibility of a Gaussian combination

    Noise.idxArr = zeros(Noise.N,2);          % buffer for beginning and ending indeces of sub noise
                                              % source entries in global mean and covariance

    dim = 0;
    for j=1:Noise.N,
        subNoise = Noise.noiseSources{j};
        dim = dim + subNoise.dim;
        ind1 = dim-subNoise.dim+1;
        ind2 = dim;
        Noise.idxArr(j,:) = [ind1 ind2];
        if ~stringmatch(subNoise.ns_type,{'gaussian','combo-gaussian'})
            Gaussian_flag = 0;
        end
    end

    if (Noise.dim ~= dim),
        error([' [ gennoiseds::combo-gaussian ] Combinded noise vector dimension does ' ...
               'not agree with agregate dimension of sub noise sources.']);
    end

    % A Gaussian combination should always be constructed if  the underlying sub
    % noise sources are all Gaussian