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')

CROSS-REFERENCE INFORMATION

This function calls:
 kdeoptset Create or alter KDE OPTIONS structure. parseoptions Create or alter a OPTIONS structure. cell2struct Convert cell array to structure array. help Display help text in Command Window. strvcat Vertically concatenate strings.
This function is called by:
 Chapter3 % CHAPTER3 Demonstrates distributions of wave characteristics hlscv Least Squares Cross-Validation estimate of smoothing parameter hstt Scott-Tapia-Thompson estimate of smoothing parameter. kde Kernel Density Estimator. kde1dgui GUI to Kernel Density Estimator. kde2dgui GUI to Kernel Density Estimator in two dimensions. kdebin Binned Kernel Density Estimator. kdedemo1 Demonstrate the smoothing parameter impact on KDE kdedemo2 Demonstrate the difference between transformation- and ordinary-KDE kdefun Kernel Density Estimator. kdeoptset Create or alter KDE OPTIONS structure. recinit setup all global variables of the RECDEMO ssample Random sampling from a smoothed empirical distribution wafofig3 Probability density distributions (pdf) of wave period, Tt, wafofig5 Joint distribution (pdf) of crest front velocity and wave height: wafofig6 Joint distribution (pdf) of crest front period, Tcf, and crest amplitude, Ac

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 %
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