source: orange/docs/widgets/rst/unsupervized/distancemap.rst @ 11778:ecd4beec2099

Revision 11778:ecd4beec2099, 5.8 KB checked in by Ales Erjavec <ales.erjavec@…>, 5 months ago (diff)

Use new SVG icons in the widget documentation.

Line 
1.. _Distance Map:
2
3Distance Map
4============
5
6.. image:: ../../../../Orange/OrangeWidgets/Unsupervised/icons/DistanceMatrix.svg
7
8Visualizes distances between items
9
10Signals
11-------
12
13Inputs:
14   - Distance Matrix (SymMatrix)
15      A distance matrix
16
17
18Outputs:
19   - Examples (ExampleTable)
20      Examples corresponding to selected elements of the matrix
21   - Attribute List (orange.VarList)
22      Attributes corresponding to selected elements of the matrix
23
24
25Description
26-----------
27
28Distance Map is a visualization of distances between objects. The visualization
29is rather simple: it is the same as is we printed out a table of numbers,
30except that the numbers are replaced by spots colored by colors from the
31specified palette.
32
33The distances are most often distances between examples (for instance from
34:ref:`Example Distance` or attributes (for instance from
35:ref:`Attribute Distance`. The widget does not require that (another option
36can be loading the distances from a file using :ref:`Distance File`, although
37when one of these is the case, the user can select a region of the map and the
38widget will output the corresponding examples or attributes through the
39appropriate signal.
40
41.. image:: images/DistanceMap.png
42
43The snapshot shows distances between attributes in the heart disease data,
44using the preset Black - Red palette, where smaller numbers are represented
45with black and larger with red. The matrix is symmetric and the diagonal is
46black - no attribute is different from itself. The former (symmetricity) is
47always assumed, while the diagonal may also be non-zero.
48
49.. image:: images/DistanceMap-Settings.png
50
51The widget's settings are divided into three tabs. The first one defines the
52size and order of cells. :obj:`Width` and :obj:`Height` in the :obj:`Cell Size`
53box set the size of the cells. The cells can be restricted to squares
54(:obj:`Cells as squares`) and drawn with or without gridlines in between
55(:obj:`Show grid`). When cells are too small (8 pixels or less), the grid
56disappears in any case.
57
58:obj:`Merge` merges multiple cells into a single cell, which can be useful
59when the matrix is too large. For this option to yield meaningful results,
60items need to be sorted so similar items are merged. The widget has three
61options; it can leave the items as they are (:obj:`No sorting`) it can put
62similar items together (:obj:`Adjacent distance`) or randomly shuffle the
63items (:obj:`Random order`). Of these, adjacent distance is unfortunately not
64implemented yet.
65
66
67.. image:: images/DistanceMap-Colors.png
68
69The second tab defines the colors that represent the numeric values.
70:obj:`Gamma` defines how numbers are mapped onto the palette colors.
71When set to 1 (default), the mapping is linear. When it decreases, the numeric
72values at the lower end get similar colors, the curve get steeper in the
73middle, and higher values are again represented with colors which are more
74similar than if gamma was higher. The graph below shows the mapping function
75at gamma=0.25.
76
77.. image:: images/DistanceMap-gamma.png
78
79Setting gamma is useful when the distribution of distances has long tails which
80are not very interested. The widget also offers controls for cutting of the
81outliers. Normally, the color palette is used to visualize the entire range
82of distances appearing in the matrix. This can be changed be checking
83:obj:`Enable thresholds` and setting the low and high threshold. Distances
84outside this interval are then shown using special colors, so the color
85spectrum can be used for visualizing the interesting part of the distribution.
86
87The widget supports different color schemes. The built-in schemes are named
88:obj:`Blue - Yellow`, :obj:`Black - Red` and :obj:`Green - Black - Red`. The
89schema is defined, first, by the two colors representing the lowest and
90highest distances. The two colors are set by clicking the rectangles to the
91left and right of the color strip below the schema name. The transition can go
92either from one color to another (in the RGB space) or
93:obj:`Pass through black`, that is, from one color to black and then to
94another. Colors can also be set for undefined values (:obj:`N/A`), values
95below and above the low and high thresholds (:obj:`Underflow` and
96:obj:`Overflow`), the background (:obj:`Background`), the outline of the cell
97under the mouse cursor (:obj:`Cell outline`) and the marker around the selected
98region (:obj:`Selected cells`).
99
100User can modify the existing schemata and also create new, customized schemata
101(:obj:`New`). The built-in schemata are shown below.
102
103.. image:: images/DistanceMap-Green-Black-Red.png
104
105.. image:: images/DistanceMap-Info.png
106
107The last tab defines the shown information and controls selection of cells.
108:obj:`Show legend` determines whether the widget shows the colored strip at
109the top which shows the mapping of numbers into colors. :obj:`Show labels`
110shows and hides the item names (e.g. age, gender etc) besides the map. Labels
111can only be shown it they exist; they do when the data represents distances
112between attributes or when the data is loaded from a labeled distance file.
113
114If :obj:`Show balloon` is checked, a ballon appears when the mouse is hovering
115over a cell, which shows the numerical distances and, if
116:obj:`Display item names` is checked, also the names of the corresponding
117items.
118
119The user can select a region in the map by the usual click-and-drag with the
120mouse. When a part of the map is selected, the widget output all items
121corresponding to the selected cells. The three buttons in the :obj:`Select`
122can undo the last selection, remove all selections and send the selected
123data. If :obj:`Send after mouse release` is checked, the data is set
124automatically, without needing to press the button above.
125
126Examples
127--------
128
129The above snapshots were obtained by the following schema:
130
131.. image:: images/DistanceMap-Schema.png
132
133The file widget loads the iris data set; we then compute the attribute
134distances and visualize them.
Note: See TracBrowser for help on using the repository browser.