Home > wafo > kdetools > kdeoptset.m

kdeoptset

PURPOSE ^

Create or alter KDE OPTIONS structure.

SYNOPSIS ^

options = kdeoptset(varargin)

DESCRIPTION ^

 KDEOPTSET Create or alter KDE OPTIONS structure. 
  
   CALL:  options = kdeoptset(funcname,opts1,opts2,..,par1,val1,par2,val2,..); 
  
    options    = transformation options structure in which the named  
                 parameters have the specified values.   
    funcname   = string giving the name of the function for which default 
                 values for the options structure should be extracted. 
                 Options are 'kdebin', 'kde', 'fftkde'. 
    opts1, 
    opts2..    = options structures 
    par1,par2..= strings identifying the parameter to alter 
    val1,val2..= corresponding values the parameters are altered to. 
     
    KDEOPTSET combines the default options for a function given by FUNCNAME 
    with new options structures (OPTS1,OPTS2,...) and/or with the named 
    parameters (PAR1,PAR2,...) with the corresponding values (VAL1, VAL2,...). 
    The parameters are set in the same order as the input arguments. 
    Any parameters with non-empty values of the options struct overwrite 
    the corresponding old parameters.  
    The input arguments can be given in any order with one exception: 
    PARx and VALx must be given in pairs in that order. 
    Any unspecified parameters for PARx are set to [].  
    Parameters with value [] indicate to use the default value for that 
    parameter when OPTIONS is passed to the function. It is sufficient to 
    type only the 2 first characters to uniquely identify the parameter 
    or function name.  Upper case letters for parameter names and values 
    that are strings are ignored. If an invalid string is provided, the 
    default is used. 
     
    KDEOPTSET with no input arguments and no output arguments displays all  
    parameter names and their possible values. 
  
    KDEOPTSET with no input arguments creates an options structure 
    OPTIONS where all the fields are set to their default values. 
  
     
  KDEOPTSET PARAMETERS 
    kernel = String defining the kernel function. Options are: 
             'epanechnikov'  - Epanechnikov kernel. (default) 
             'biweight'      - Bi-weight kernel. 
             'triweight'     - Tri-weight kernel.   
             'triangular'    - Triangular kernel. 
             'gaussian'      - Gaussian kernel 
             'rectangular'   - Rectangular kernel.  
             'laplace'       - Laplace kernel. 
             'logistic'      - Logistic kernel. 
    hs     = smooting parameter vector/matrix. 
             (default compute from data using hsMethod) 
  hsMethod = string defining the method to compute the  smooting 
             parameter vector/matrix, hs, if not explicitly given. 
             Valid options are one of the methods: 
             'hns', 'hos', 'hldpi', 'hbcv', 'hste', 'hboot', 'hlscv', 
             'hscv', 'hstt' 
             (default 'hns')   
    alpha  = sensitivity parameter               (default 0 regular KDE) 
             A good choice might be alpha = 0.5 ( or 1/D) 
             alpha = 0      Regular  KDE (hs is constant) 
             0 < alpha <= 1 Adaptive KDE (Make hs change)   
    L2     = vector of transformation parameters (default 1 no transformation) 
             or a cellarray of transformations parameters 
             or non-parametric transformations. 
             t(xi;L2) = xi^L2*sign(L2)   for L2(i) ~= 0 
             t(xi;L2) = log(xi)          for L2(i) == 0  
             If single value of L2 is given then the transformation 
             is the same in all directions. 
    inc    = scalar defining the dimension of kde (default 128) 
             (A value below 50 is very fast to compute but may give some 
             inaccuracies.  Values between 100 and 500 give very accurate  
             results)  (Only used in function kdebin.) 
    
   Note that only the first 4 letters of the kernel name is needed.  
   If L2~=1 KDE transforms the data before estimation. The final estimate 
   is obtained by transforming back by a simple change of variables. 
   Beaware of spurious spikes close to the edges when L2~=1. 
   These spikes are due to numerical problems close to the edges. 
  
  (1) If a single non-zero value of hs is given then smoothing is the  
      same in all directions. 
  (2) If hs = [H1, H2] then smoothing is by H1 in the 1'st direction and H2 
      in the 2'nd direction.  If hs = 0 or hs = [] is specified, automatic  
      values are used computed with hsMethod.  
  (3) If hs = [H1, H3;H3 ,H2] then the smoothing can be in orientations 
      different from those of the co-ordinate directions.   
      Example: HS=(.3*eye(D))*sqrtm(cov(data)) 
      Note: det(HS)>0 
   
   If hs is too large we over smooth introducing a large bias 
   in the estimated density. If hs is too small we under smooth 
   introducing spurious bumps. 
  
   Also note that HNS only gives a optimal value when the distribution of  
   the (transformed) DATA is Gaussian. If the distribution is asymmetric,  
   multimodal or have long tails the HNS may return a too large smoothing 
   parameter  i.e. KDE may oversmooth and thus give a large bias.  To 
   remedy this try: 
  
  (1) different values for HS and check by eye, i.e.  
      for 2D data count the points lying within the contours to roughly 
      check that the calculated contours approximately encloses the 
      corresponding percentage of the data.   
  (2) with alpha > 0, i.e., adaptive KDE (Good choice for skew distributions) 
  (3) with L2~=1, i.e., transformation KDE. A reasonable value of L2 is 
      found when a normal-plot of the transformed DATA is approximately 
      linear. Beaware that due to numerical problems the back 
      transformation may result in spurious spikes close to where Xi is 
      zero. These spikes should be removed!   
    
  Examples: 
   kdeoptset('kdebin') 
  
  See also  kde, kdebin

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SOURCE CODE ^

001 function options = kdeoptsetkdeoptset(varargin) 
002 %KDEOPTSET Create or alter KDE OPTIONS structure. 
003 % 
004 %  CALL:  options = kdeoptset(funcname,opts1,opts2,..,par1,val1,par2,val2,..); 
005 % 
006 %   options    = transformation options structure in which the named  
007 %                parameters have the specified values.   
008 %   funcname   = string giving the name of the function for which default 
009 %                values for the options structure should be extracted. 
010 %                Options are 'kdebin', 'kde', 'fftkde'. 
011 %   opts1, 
012 %   opts2..    = options structures 
013 %   par1,par2..= strings identifying the parameter to alter 
014 %   val1,val2..= corresponding values the parameters are altered to. 
015 %    
016 %   KDEOPTSET combines the default options for a function given by FUNCNAME 
017 %   with new options structures (OPTS1,OPTS2,...) and/or with the named 
018 %   parameters (PAR1,PAR2,...) with the corresponding values (VAL1, VAL2,...). 
019 %   The parameters are set in the same order as the input arguments. 
020 %   Any parameters with non-empty values of the options struct overwrite 
021 %   the corresponding old parameters.  
022 %   The input arguments can be given in any order with one exception: 
023 %   PARx and VALx must be given in pairs in that order. 
024 %   Any unspecified parameters for PARx are set to [].  
025 %   Parameters with value [] indicate to use the default value for that 
026 %   parameter when OPTIONS is passed to the function. It is sufficient to 
027 %   type only the 2 first characters to uniquely identify the parameter 
028 %   or function name.  Upper case letters for parameter names and values 
029 %   that are strings are ignored. If an invalid string is provided, the 
030 %   default is used. 
031 %    
032 %   KDEOPTSET with no input arguments and no output arguments displays all  
033 %   parameter names and their possible values. 
034 % 
035 %   KDEOPTSET with no input arguments creates an options structure 
036 %   OPTIONS where all the fields are set to their default values. 
037 % 
038 %    
039 % KDEOPTSET PARAMETERS 
040 %   kernel = String defining the kernel function. Options are: 
041 %            'epanechnikov'  - Epanechnikov kernel. (default) 
042 %            'biweight'      - Bi-weight kernel. 
043 %            'triweight'     - Tri-weight kernel.   
044 %            'triangular'    - Triangular kernel. 
045 %            'gaussian'      - Gaussian kernel 
046 %            'rectangular'   - Rectangular kernel.  
047 %            'laplace'       - Laplace kernel. 
048 %            'logistic'      - Logistic kernel. 
049 %   hs     = smooting parameter vector/matrix. 
050 %            (default compute from data using hsMethod) 
051 % hsMethod = string defining the method to compute the  smooting 
052 %            parameter vector/matrix, hs, if not explicitly given. 
053 %            Valid options are one of the methods: 
054 %            'hns', 'hos', 'hldpi', 'hbcv', 'hste', 'hboot', 'hlscv', 
055 %            'hscv', 'hstt' 
056 %            (default 'hns')   
057 %   alpha  = sensitivity parameter               (default 0 regular KDE) 
058 %            A good choice might be alpha = 0.5 ( or 1/D) 
059 %            alpha = 0      Regular  KDE (hs is constant) 
060 %            0 < alpha <= 1 Adaptive KDE (Make hs change)   
061 %   L2     = vector of transformation parameters (default 1 no transformation) 
062 %            or a cellarray of transformations parameters 
063 %            or non-parametric transformations. 
064 %            t(xi;L2) = xi^L2*sign(L2)   for L2(i) ~= 0 
065 %            t(xi;L2) = log(xi)          for L2(i) == 0  
066 %            If single value of L2 is given then the transformation 
067 %            is the same in all directions. 
068 %   inc    = scalar defining the dimension of kde (default 128) 
069 %            (A value below 50 is very fast to compute but may give some 
070 %            inaccuracies.  Values between 100 and 500 give very accurate  
071 %            results)  (Only used in function kdebin.) 
072 %   
073 %  Note that only the first 4 letters of the kernel name is needed.  
074 %  If L2~=1 KDE transforms the data before estimation. The final estimate 
075 %  is obtained by transforming back by a simple change of variables. 
076 %  Beaware of spurious spikes close to the edges when L2~=1. 
077 %  These spikes are due to numerical problems close to the edges. 
078 % 
079 % (1) If a single non-zero value of hs is given then smoothing is the  
080 %     same in all directions. 
081 % (2) If hs = [H1, H2] then smoothing is by H1 in the 1'st direction and H2 
082 %     in the 2'nd direction.  If hs = 0 or hs = [] is specified, automatic  
083 %     values are used computed with hsMethod.  
084 % (3) If hs = [H1, H3;H3 ,H2] then the smoothing can be in orientations 
085 %     different from those of the co-ordinate directions.   
086 %     Example: HS=(.3*eye(D))*sqrtm(cov(data)) 
087 %     Note: det(HS)>0 
088 %  
089 %  If hs is too large we over smooth introducing a large bias 
090 %  in the estimated density. If hs is too small we under smooth 
091 %  introducing spurious bumps. 
092 % 
093 %  Also note that HNS only gives a optimal value when the distribution of  
094 %  the (transformed) DATA is Gaussian. If the distribution is asymmetric,  
095 %  multimodal or have long tails the HNS may return a too large smoothing 
096 %  parameter  i.e. KDE may oversmooth and thus give a large bias.  To 
097 %  remedy this try: 
098 % 
099 % (1) different values for HS and check by eye, i.e.  
100 %     for 2D data count the points lying within the contours to roughly 
101 %     check that the calculated contours approximately encloses the 
102 %     corresponding percentage of the data.   
103 % (2) with alpha > 0, i.e., adaptive KDE (Good choice for skew distributions) 
104 % (3) with L2~=1, i.e., transformation KDE. A reasonable value of L2 is 
105 %     found when a normal-plot of the transformed DATA is approximately 
106 %     linear. Beaware that due to numerical problems the back 
107 %     transformation may result in spurious spikes close to where Xi is 
108 %     zero. These spikes should be removed!   
109 %   
110 % Examples: 
111 %  kdeoptset('kdebin') 
112 % 
113 % See also  kde, kdebin 
114  
115 % History 
116 % by pab 04.02.2005%  NEW FUNCTIONS 
117 %  ~~~~~~~~~~~~~ 
118 % based on MATLAB's optimset 
119  
120  
121 % Print out possible values of properties. 
122 if (nargin == 0) & (nargout == 0) 
123   help kdeoptset 
124   return; 
125 end 
126  
127 % Initialization 
128 % Legal functions names 
129 fnames = strvcat('kde','kdebin');  
130 % Legal parameter names 
131 names  = {'kernel','hs','hsMethod','alpha','L2','inc'};      
132 vals = {'epan',[],'hns',0,1,128}; 
133  
134 % Initialize options with default values 
135 options = cell2struct(vals,names,2); 
136 options = parseoptions(fnames,options,varargin{:}); 
137 if ~isempty(options.alpha) 
138   options.alpha=min(abs(options.alpha),1); 
139 end 
140 %if isnumeric(options.hs) 
141 %  options.hsMethod = []; 
142 %end 
143 return 
144   
145

Mathematical Statistics
Centre for Mathematical Sciences
Lund University with Lund Institute of Technology

Comments or corrections to the WAFO group


Generated on Thu 06-Oct-2005 02:21:16 for WAFO by m2html © 2003