som_pieplane

Purpose

 Visualizes the map prototype vectors as pie charts.

Syntax

  h = som_pieplane(topol, data)
  h = som_pieplane(lattice, msize, data)
  h = som_pieplane(..., color)
  h = som_pieplane(..., color, s)
  h = som_pieplane(..., color, s, pos)

Description

  Visualizes the map prototype vectors as pie charts.

Known bugs

 It is not possible to specify explicit coordinates for map
 consisting of just one unit as then the msize is interpreted as
 map size.

Features

  - negative values in data cause an error

  - the colors are fixed: changing colormap in the figure (see help
    colormap) will not affect the coloring of the slices.

  - if input variable s has size Nxd it gives each slice an individual
    scaling factor. This may be used to create a glyph where
    the radius of the slice, not the angle, shows the variable
    try, e.g., som_pieplane('rect',[5 4],ones(20,4),'w',rand(20,4));

Required input arguments

 lattice  The basic shape of the map units 

    (string) 'hexa' or 'rect' positions the pies according to hexagonal or 
             rectangular map lattice.

 msize    The size of the map grid     

    (vector) [n1 n2] vector defines the map size (height n1 units,
             width n2 units, total M=n1xn2 units). The units will 
             be placed to their topological locations to form a
             uniform hexagonal or rectangular grid.
    (matrix) Mx2 matrix defines arbitary coordinates for the M units. In 
             this case the argument 'lattice' has no effect.

 topol    Topology of the map grid

   (struct) map or topology struct from which the topology is taken

 data     The data to be visualized

    (matrix) Mxd matrix of data vectors. Negative values are invalid.

Optional input arguments

 If value is unspecified or empty ([] or ''), the default values
 are used for optional input arguments.

 s       The size scaling factors for the units

    (scalar) gives each unit the same size scaling: 
             0   unit disappears (edges can be seen as a dot)
             ... default size is 0.8
             >1  unit overlaps others          
    (matrix) Mx1 double: each unit gets individual size scaling 

 color   The color of the slices in each pie

    (string) ColorSpec or 'none' gives the same color for each slice
    (matrix) dx3 matrix assigns an RGB color determined by the dth row of
             the matrix to the dth slice (variable) in each pie plot

 pos    Position of origin       

    (vector) size 1x2: this is meant for drawing the plane in arbitary 
             location in a figure. Note the operation: if this argument is
             given, the axis limits setting part in the routine is skipped and 
             the limits setting will be left to be done by
             MATLAB's defaults. Default is no translation.

Output arguments

  h (scalar)  Handle to the created patch object.

Object tags

 One object handle is returned: field Tag is set to 'planePie'       

Examples

 %%% Create the data and make a map 

 data=rand(100,5); map=som_make(data);

 %%% Create a 'jet' colormap that has as many rows as the data has variables

 colors=jet(5);

 %%% Draw pies

 som_pieplane(map, map.codebook, colors);

 %%% Calculate the hits of data on the map and normalize them between [0,1]

 hit=som_hits(map,data); hit=hit./max(max(hit));

 %%% Draw the pies so that their size tells the hit count

 som_pieplane(map, map.codebook, colors, hit);

 %%% Try this! (see section FEATURES) 

 som_pieplane('rect',[5 4],ones(20,4),'w',rand(20,4));

See also