calcfiltinit.m

阵列信号处理的工具箱

function [methodCalc, weightMatrix, basisMat, freqPos] = calcfiltinit(method, sizeSigIn, steMat,  taperCoeff, interCorrMat, orthBeamFlag, extraParam, normType, normLevel)

%CALCFILTINIT Preparing the linear filtering with "calcfiltproc" of several signal vectors.
%
%--------
%Synopsis:
%  [methodCalc, weightMatrix, basisMat, freqPos] = calcfiltinit(method, 
%    sizeSigIn, steMat,  taperCoeff, interCorrMat, orthBeamFlag, extraParam,
%    normType, normLevel)
%
%Description:
%  This help text describes the filtering performed by the functions 
%  "calcfiltinit" and "calcfiltproc". The description of the filtering
%  methods are also valid both for functions calling "calcfiltinit" and 
%  "calcfiltproc".
%
%  This function "calcfiltinit" prepares the linear filtering of several
%  signal vectors with the function "calcfiltproc" by calculating the
%  filtering weights or coefficients. "calcfiltinit" must be called exactly
%  once before "calcfiltproc". "calcfiltproc" can then be called several
%  times with new signal vectors (snapshots) to be filtered. For examples 
%  of the use of these functions, see the function "calcfiltsig" and the
%  old version of "spafilt".
%
%  The functions "calcfiltinit" and "calcfiltproc" were designed to be
%  used in the toolbox DBT but probably it is possible to use them outside
%  DBT also.
%
%Output and Input:
%  methodCalc (StringT): The method to be used by the function "calcfiltproc".
%    This output parameter should be passed as the input parameter 
%    "method" to function "calcfiltproc".
%  weightMatrix (CxMatrixT): The filtering weights or coefficients to be
%    used by the function "calcfiltproc".
%    This output parameter should be passed as the input parameter 
%    "weightMatrix" to function "calcfiltproc".
%    In methods using these weights the filtering is performed by a matrix 
%    multiplication:
%      sigMatOut = weightMatrix' * sigMatIn ,
%    where "sigMatOut" and "sigMatIn" are the output and input signal
%    matrices respectively.
%  basisMat (CxMatrixT): After the filtering, the signal consists of the 
%    coefficients in the basis, which is made up of the columns of this
%    output matrix. "basisMat" is the memory of what is done with the signal 
%    during the filtering. "basisMat" is stored in the radar signal after
%    the linear filtering, which is necessary to make further processing
%    in the selected dimension possible.
%    "basisMat" is defined in the same way as "weightMatrix".    
%  freqPos (RealVectorT.'): Normalized frequencies of the output channels.
%    Not used.
%
%  method (StringT):Filtering method. See below for sections about each method.
%    = 'cbf', 'conv': Nonadaptive conventional beamforming or mathed 
%      filtering.
%    = 'acbf', 'aconv', 'atfir': Adaptive conventional beamforming or adaptive
%      mathed filtering.
%    = 'capon': Capons beamformer or filtering.
%    = 'fft : Discrete Fourier Transform Method.
%    = 'ifft : Inverse Discrete Fourier Transform Method. Not implemented.
%    = 'trans': Direct Transformation Matrix Method. Implementation not
%      finnished.
%    = 'intereigvec': SB Interference Eigenvector Method. Implementation not
%      finnished.
%    = 'dataeigvec': SB Data Eigenvector Method.
%    = 'music': MUSIC spectral estimation.
%  steMat (CxMatrixT): Steering matrix or filter coefficients.
%  taperCoeff (CxVectorT): Weights to weight the filter coefficients with.
%  normType [D](StringT): Type of normalization. Not implemented.
%  normLevel[D](): Normalization level. Not implemented.
%
%--------
%Nonadaptive Conventional Beamforming or Matched Filtering.
%Synopsis:
%  [sigMatOut, weightMatrix, basisMat, freqPos] = 
%    calcfiltinit(sigMatIn, 'cbf', sizeSigIn, steMat,  taperCoeff, [], 
%    orthBeamFlag, extraParam, normType, normLevel)
%
%  [sigMatOut, weightMatrix, basisMat, freqPos] = 
%    calcfiltinit(sigMatIn, 'conv', sizeSigIn, steMat,  taperCoeff, [], 
%    orthBeamFlag, extraParam, normType, normLevel)
%
%Output and Input:
%  steMat (CxMatrixT): Steering matrix.
%
%Description:
%  This is same same as conventional beamformimg or matched filtering.
%  The filter coefficients are taken from the input parameter "steMat",
%  which must in different column must contain the steering vectors or
%  signals to match to.
%  The filter coefficients are weighted by the input parameter "taperCoeff".
%
%Algoritm:
%
%--------
%Adaptive Conventional Beamforming or Matched Filtering.
%Synopsis:
%  [sigMatOut, weightMatrix, basisMat, freqPos] = 
%    calcfiltinit(sigMatIn, 'acbf', sizeSigIn, steMat,  taperCoeff, 
%    interCorrMat, orthBeamFlag, extraParam, normType, normLevel)
%
%  [sigMatOut, weightMatrix, basisMat, freqPos] = 
%    calcfiltinit(sigMatIn, 'aconv', sizeSigIn, steMat,  taperCoeff, 
%    interCorrMat, orthBeamFlag, extraParam, normType, normLevel)
%
%Output and Input:
%  steMat (CxMatrixT): Steering matrix.
%  interCorrMat (CxMatrixT): Interference signal correlation matrix.
%    This is used to adaptively suppress the interference.
%  extraParam (): Choice of adaptive interference suppression method.
%    Not implemented.
%
%Description:
%  This is same same as conventional beamformimg or matched filtering.
%  The filter coefficients are taken from the input parameter "steMat",
%  which must in different column must contain the steering vectors or
%  signals to match to.
%  The filter coefficients are weighted by the input parameter "taperCoeff".
%  If present the input parameter "interCorrMat" is used suppress interference,
%  e.g. jammers in beamforming.
%
%Algoritm:
%
%--------
%Capons Method.
%Synopsis:
%  [methodCalc, weightMatrix, basisMat, freqPos] = calcfiltinit('capon', 
%    sizeSigIn, steMat,  [], [], orthBeamFlag, [], normType, normLevel)
%
%Output and Input:
%
%Description:
%  Capon spectrum calculation [3]. A differens to the calculation in [3]
%  is that this function returns an "amplitude" spectrum and without
%  averaging over the snapshots.
% 
%  In the Capon method the filtering weights depend on signal to filter. 
%  Therefore the weights are not calculated in the function "calcfiltinit"
%  but in the function "calcfiltproc".
%
%  Because there will be several basis matrices (one for each call to the
%  function "calcfiltproc") and only one can be stored in the output 
%  radar signal, only the non-adapted steering matrix is stored as the basis 
%  matrix in the output radar signal.
% 
%  A warning message like:
%    Warning: Matrix is close to singular or badly scaled.
%         Results may be inaccurate. RCOND = 5.551115e-17.
%  is an indication of too few signal vector samples or snapshots.
%
%Algoritm:
%
%--------
%Discrete Fourier Transform Method.
%Synopsis:
%  [methodCalc, weightMatrix, basisMat, freqPos] = calcfiltinit('fft', 
%    sizeSigIn, [],  taperCoeff, [], [], extraParam, normType, normLevel)
%
%Output and Input:
%  extraParam (IntScalarT): Number of output channels, e.g. number of
%    output Doppler channels for Doppler filtering.
%
%Description:
%  Filtering using FFT.
%
%Algoritm:
%  See the matlab function "fft".
%
%Known Bugs:
%  The implementation only manages 1-dimensional signals.
%
%--------
%Inverse Discrete Fourier Transform Method.
%Synopsis:
%
%Output and Input:
%
%Description:
%  The implementation is not finnished.
%
%Algoritm:
%
%Known Bugs:
%  The implementation only manages 1-dimensional signals.
%
%--------
%Direct Transformation Matrix Method.
%Synopsis:
%  [methodCalc, weightMatrix, basisMat, freqPos] = calcfiltinit('trans', 
%    sizeSigIn, weightMatrix,  taperCoeff, [], [], extraParam, 
%    normType, normLevel)
%
%Output and Input:
%  weightMatrix (CxMatrixT): The matrix with filter weights or coefficients. 
%
%Description:
%  In this method the filtering is performed by a direct matrix 
%  multiplication:
%    sigMatOut = weightMatrix' * sigMatIn ,
%  where "sigMatOut" and "sigMatIn" are the output and input signal
%  matrices respectively.
%
%  The implementation is not tested.
%
%Algoritm:
%
%--------
%MUSIC.
%Synopsis:
%  [methodCalc, weightMatrix, basisMat, freqPos] = calcfiltinit('music',
%    sizeSigIn, steMat,  [], [], [], extraParam, 
%    normType, normLevel)
%
%Output and Input:
%  extraParam (IntScalarT): Number of signal sources.
%
%Description:
%  Returns the MUSIC "amplitude" spectrum (the square root of the 
%  spectrum in [3]).
%
%  Note, this method is non-linear. Other linear processing cannot be 
%  performed after this method. 
%  This method is actually a data reducing method. The dimension in the
%  signal which is used as snapshots is used up. For the function
%  "calcfiltproc" still to be able to return a "sigMatOut" matrix of size 
%  (signalVectorLength, numberOfSnapshots), the first column is copied
%  to all columns. It is advisable to remove, e.g. with the function 
%  "sigsubix", the copied columns after the filtering to save memory.
%  This method should be in the future function "calcspcproc" instead.
%
%Algoritm:
%
%--------
%Data Eigenvector Method.
%Synopsis:
%  [methodCalc, weightMatrix, basisMat] = calcfiltinit(method, 
%    sizeSigIn, steMat,  [], [], [], [], normType, normLevel)
%
%Output and Input:
%
%Description:
%  Filtering using the eigenvectors of the data correlation matrix as
%  filtering weights. The data correlation matrix is estimated by
%  the signal vectors of the input signal matrix "sigMatIn" in the 
%  function "calcfiltproc". The eigenvalues are sorted in descending
%  order and the eienvecors accordingly. 
%
%  The first element in the output vector is a a special mixture (see [4])
%  of the signal sources and corresponds to the largest eigenvalue.
%  The second element corresponds to the second element and so on.
%  More interesting than the output signal is often the used filtering
%  weights, which tells us how the mixture is made. This can be seen by
%  plotting the antenna pattern or the frequency function of the filter. 
%
%  The outputs signal length is always equal to input signal length.
%
%  In the Capon method the filtering weights depend on signal to filter. 
%  Therefore the weights are not calculated in the function "calcfiltinit"
%  but in the function "calcfiltproc".
%
%  Because there will be several basis matrices (one for each call to the
%  function "calcfiltproc") and only one can be stored in the output 
%  radar signal, ...
%
%Algoritm:
%
%Known Bugs:
%  There should be a special treatment, as with 'fft', of this method
%  in "puldfilt" etc. because the number of output channels cannot be
%  chosen by "freqChoice".  The number of output channels must be equal to the
%  number of input channels.
%
%--------
%Notations:
%  Data type names are shown in parentheses and they start with a capital
%  letter and end with a capital T. Data type definitions can be found in [1]
%  or by "help dbtdata".
%  [D] = This parameter can be omitted and then a default value is used.
%  When the [D]-input parameter is not the last used in the call, it must be
%  given the value [], i.e. an empty matrix.
%  ... = There can be more parameters. They are explained under respective
%  metod or choice.
%
%Examples:
%  See the code of the functions "spafilt" and "pulfilt".
%
%Software Quality:
%  (About what is done to ascertain software quality. What tests are done.)
%  This function is not tested yet.
%
%Known Bugs:
%  There should be input and output parameters for "freqPos", "doaPos", etc.
%  Is there a bug in method 'trans'? Look at the code!
%
%References:
%  [1]: Bj鰎klund S.: "DBT, A MATLAB Toolbox for Radar Signal Processing.
%    Reference Guide", FOA-D--9x-00xxx-408--SE, To be published.
%  [2]: Johnson D.H., Dudgeon D.E.: "Array Signal Processing, Concepts
%    and Techniques", Prentice Hall 1993, ISBN 0-13-048513-6.
%  [3]: Krim H., Viberg M.:"Two Decades of Array Signal Processing Research",
%    IEEE Signal Processing Magazine, July 1996, pp. 67-94.
%  [4]: Bj鰎klund S.: "Subspace Interpretation of Sensor Array Signals", 
%    FOA-R--99-00xxx-408--SE. Under preparation.
%
%See Also:
%  calcfiltproc

%   *  DBT, A Matlab Toolbox for Radar Signal Processing  *
% (c) FOA 1994-2000. See the file dbtright.m for copyright notice.
%
%  Start        : 980913 Svante Bj鰎klund (svabj).
%  Latest change: $Date: 2000/11/17 12:45:09 $ $Author: svabj $.
%  $Revision: 1.16 $
% *****************************************************************************

%  Move the filtering to after each method !?!


% ----------------------------------------------------------------------- %
% Handle input parameters
% ----------------------------------------------------------------------- %

if (nargin < 3)
  error('DBT-Error: To few input parameters.')
end

% ****************** Add missing input parameters ******************

arginNo=4;
if (nargin < arginNo)
  taperCoeff = [];
end
arginNo = arginNo +1;
if (nargin < arginNo)
  interCorrMat = [];
end