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

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

Use new SVG icons in the widget documentation.

Line 
1.. _Distance File:
2
3Distance File
4=============
5
6.. image:: ../../../../Orange/OrangeWidgets/Unsupervised/icons/LoadDistances.svg
7
8Computes distances between examples in the data set
9
10Signals
11-------
12
13Inputs:
14   - Examples
15      A list of examples
16
17
18Outputs:
19   - Distance Matrix
20      A matrix of example distances
21
22
23Description
24-----------
25
26Loads a distance matrix from a text file.
27
28The first line in the file has to start with the number of items - the
29dimension of the matrix. It can be followed by the word labeled or labelled
30if the file also contains the labels for the items. The rest of the file is
31the matrix, where the elements are separated by tabulators. If the items are
32labelled, the label has to be put in front of each line. The matrix can be
33given with the lower or the upper part, or both. Here are two examples.
34
35::
36
37   0.1
38   0.5    0.3
39   0.7    0.9    0.2
40   0.2    0.8    0.6    0.5
41
42::
43
44   john   0.1
45   joe    0.5    0.3
46   jack   0.7    0.9    0.2
47   jane   0.2    0.8    0.6    0.5
48
49
50.. image:: images/DistanceFile.png
51   :alt: Distance File Widget
52
53The file is selected using button :obj:`...`, which opens a file browser.
54File extension is arbitrary.
55
56Sometimes we get the labels in a separate example table. Say that we have a
57set of 15 examples in a data file, and the distance matrix represents distances
58between these examples. In this case, we would connect the widget providing
59these 15 examples (say a :ref:`File`) to the input of Distance File and
60select :obj:`Use examples as items` in Items from input data.
61Distance File would attach the examples to the distance matrix, so further
62widget can, for instance, use a user-selected attribute to label the items.
63
64In another scenario, the distance matrix would represent distances between
65attributes of some data table. We similarly connect a data providing widget
66to Distance File, but select :obj:`Use attribute names`. Distance File then
67labels the items with the names of the attributes.
68
69Examples
70--------
71
72The first schema loads the labelled distance file above and shows it with
73the :ref:`Distance Map`.
74
75.. image:: images/DistanceFile1-Schema.png
76
77.. image:: images/DistanceFile-DistanceMap1.png
78
79In the second schema the labels come from a file. The labels given in the file
80loaded by Distance File are replaced by the attribute names (since we checked
81:obj:`Use attribute names`.
82
83.. image:: images/DistanceFile2-Schema.png
84
85In the file widget we loaded the Iris data set, and the resulting distance map
86looks like this.
87
88.. image:: images/DistanceFile-DistanceMap2.png
89
90The widget can of course be connected to any other widget that can do something
91useful with the distances, such as :ref:`MDS` or
92:ref:`Hierarchical Clustering`.
Note: See TracBrowser for help on using the repository browser.