# kdebiv

kdebiv computes (and optionally plots) a kernel smoothing estimate for bivariate data.

## Syntax

• F=kdebiv(X)example
• F=kdebiv(X,Name,Value)example
• [F,Xi]=kdebiv(___)example
• [F,Xi,bw]=kdebiv(___)example

## Description

This function is introduced in FSDA to support MATLAB releases older than R2016a, when function ksdensity was only addressing one-dimensional data.

For R2016a and subsequent releases, kdebiv uses ksdensity. Otherwise, the function computes a nonparametric estimate of the probability density function based on a normal kernel and using a bandwidth estimated as a function of the number of points in X.

 F =kdebiv(X) Density plots for a mixture of two normal distributions.

 F =kdebiv(X, Name, Value) An example using colormap.

 [F, Xi] =kdebiv(___) Surf and mesh plots.

 [F, Xi, bw] =kdebiv(___) Test option 'method'.

## Examples

expand all

### Density plots for a mixture of two normal distributions.

      X1 = [0+.5*randn(150,1)   5+2.5*randn(150,1)];
X2 = [1.75+.25*randn(60,1) 8.75+1.25*randn(60,1)];
X = [X1 ; X2];

% A filled contour plot obtained using colormap 'cmap' = 'summer'.
[F1,Xi,bw] = kdebiv(X,'contourtype','contourf','cmap','summer');
title('A filled contour plot obtained using colormap ''summer''');
hold on
plot(X(:,1),X(:,2),'rx')



### An example using colormap.

A standard (not filled) contour plot obtained using colormap 'cmap' = 'hot'.

      figure;
F2 = kdebiv(X,'cmap','hot');
title('A standard (not filled) contour plot obtained using colormap ''hot''');

% A filled contour plot with personalized colormap: note the last
% line of cmap (1 1 1), which is added to obtain a white background
% in the low densit areas.
figure;
% Data points, with associated clickable legends.
plot(X1(:,1),X1(:,2),'xr' , X2(:,1),X2(:,2),'oc');
clickableMultiLegend('group 1','group 2');
% superimpose the contour plot
hold on;
cmap =   [0, 0, 0.3 ; 0, 0, 0.4 ;  0, 0, 0.5 ; 0, 0, 0.6 ;  0, 0, 0.8 ; 0, 0, 1.0 ; 1, 1, 1 ];
F3 = kdebiv(X,'cmap',cmap);
title('A filled contour plot with personalized colormap and data point superimposed');

% just to position the figures in "cascade".



### Surf and mesh plots.

      close all;
figure;
F4 = kdebiv(X,'contourtype','surf');
figure;
F5 = kdebiv(X,'cmap',summer,'contourtype','surf');
figure;
F6 = kdebiv(X,'contourtype','mesh');
figure;
F7 = kdebiv(X,'cmap',summer,'contourtype','mesh');



### Test option 'method'.

      [F,Xi,bw]      = kdebiv(X,'pdfmethod','fsda');
disp(['fsda: estimated bandwidth over x axis is ' num2str(bw(1))]);
disp(['fsda: estimated bandwidth over y axis is ' num2str(bw(2))]);
if ~verLessThan('matlab','9.0')
[F2,Xi2,bw2] = kdebiv(X,'pdfmethod','matlab');
disp(['matlab (ksdensity): estimated bandwidth over x axis is ' num2str(bw2(1))]);
disp(['matlab (ksdensity): estimated bandwidth over y axis is ' num2str(bw2(2))]);
end


### test option 'method', with plots.

    close all;

figure
[F2,Xi2,bw2] = kdebiv(X,'cmap','gray','pdfmethod','fsda');
hold on
plot(X(:,1),X(:,2),'rx');
title('pdfmethod = fsda');

if ~verLessThan('matlab','9.0')

figure
[F3,Xi3,bw3] = kdebiv(X,'cmap','gray','pdfmethod','matlab');
hold on
plot(X(:,1),X(:,2),'rx')
title('pdfmethod = matalb');

figure
[F4,Xi4,bw4] = kdebiv(X,'cmap','gray','pdfmethod','histsmooth');
hold on
plot(X(:,1),X(:,2),'rx')
title('pdfmethod = histogram smoothing (remark: to be fixed)');

figure
[F5,Xi5,bw5] = kdebiv(X,'cmap','gray','pdfmethod','independence');
hold on
plot(X(:,1),X(:,2),'rx')
title('pdfmethod = independence');

else

disp('For this MATLAB release, only ''fsda'' option can be used' );

end



### Speed test.

     if ~verLessThan('matlab','9.0')
tt = 0; tt2=0;
for i = 1 : 100
X1 = [0+.5*randn(150,1)   5+2.5*randn(150,1)];
X2 = [1.75+.25*randn(60,1) 8.75+1.25*randn(60,1)];
X = [X1 ; X2];

t = tic;
[F,Xi,bw] = kdebiv(X,'pdfmethod','fsda');
tt = tt+toc(t);

t2 = tic;
[F,Xi,bw] = ksdensity(X);
tt2 = tt2+toc(t2);
end
disp(['kdebiv    time = ' num2str(tt)] );
disp(['ksdensity time = ' num2str(tt2)] );
end


## Input Arguments

### X — Input matrix. Matrix.

Two-column matrix with the bivariate data sample on which a probability density estimate is computed. The density is estimated on a grid of points covering the range of the data, created using MATLAB function meshgrid.

Data Types: single | double.

### Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as  Name1,Value1,...,NameN,ValueN.

Example:  'XI',X , 'Xlim', [Xlim, Ylim] , 'contourtype','contourf' , 'cmap',[0, 0, 0.3 ; 0, 0, 0.4 ; 0, 0, 0.5 ] , 'pdfmethod','fsda' 

### XI —Evaluation points of the estimated density.matrix.

In this case the density is estimated using X and evaluated on XI.

Example:  'XI',X 

Data Types: single | double.

### Xlim —Limits of the estimated density.matrix.

Two-columns matrix with the bivariate data sample on which the limits of the probability density estimate is computed. The default value is [] (i.e. automatic scale).

Example:  'Xlim', [Xlim, Ylim] 

Data Types: single | double.

### contourtype —Plot on the screen.string.

Takes one of these strings:

- contourtype = 'contour' generates a contour plot.

- contourtype = 'contourf' generates a filled contour plot.

- contourtype = 'surf' generates a surf plot.

- contourtype = 'mesh' generates a mesh plot.

Unless specified otherwise, the colormap of the plots is based on grey levels.

Example:  'contourtype','contourf' 

Data Types: char

### cmap —Three-column matrix with colormap values in the range [0,1].matrix | character.

A personalized colormap is used to plot the contour. Each row of 'plots' is an RGB triplet that defines one color or a string which identifies the color (i.e. 'gray').

Example:  'cmap',[0, 0, 0.3 ; 0, 0, 0.4 ; 0, 0, 0.5 ] 

Data Types: single | double | char

### pdfmethod —Density estimation method.character.

Supported options are 'matlab' and 'fsda'.

- 'matlab' (default) uses the default approach implemented in the MATLAB ksdensity function, using a normal kernel.

- 'fsda' computes a nonparametric estimate of the probability density function based on a normal kernel and using a bandwidth estimated as a function of the number of points in X.

Independently from the choice of the user, the function switches automatically to 'fsda' in case the user is using releases older than R2016a, when function ksdensity was only addressing one-dimensional data.

Example:  'pdfmethod','fsda' 

Data Types: char

## Output Arguments

### F —Density values.  Vector

The estimate of F is based on the normal kernel function, using the window parameter (bandwidth) that is a function of the number of points and dimension in X.

### Xi —Grid of evaluation points.  Matrix

2d matrix of equally-spaced points where the normal kernel function has been evaluated.

### bw —Bandwidth value.  Vector

The bandwidth used for the density estimation.

## References

A.W. Bowman and A. Azzalini (1997), "Applied Smoothing Techniques for Data Analysis," Oxford University Press.