Index: Orange/distance/__init__.py
===================================================================
 Orange/distance/__init__.py (revision 9759)
+++ Orange/distance/__init__.py (revision 9805)
@@ 27,5 +27,4 @@
class PearsonR(DistanceConstructor):
 """Constructs an instance of :obj:`PearsonRDistance`. Not all the data needs to be given."""
def __new__(cls, data=None, **argkw):
@@ 46,5 +45,5 @@
`Pearson correlation coefficient
`_
+ _correlation_coefficient>`_.
"""
@@ 58,5 +57,5 @@
Returns Pearson's disimilarity between e1 and e2,
 i.e. (1r)/2 where r is Sprearman's rank coefficient.
+ i.e. (1r)/2 where r is Pearson's rank coefficient.
"""
X1 = []
@@ 74,5 +73,4 @@
class SpearmanR(DistanceConstructor):
 """Constructs an instance of SpearmanR. Not all the data needs to be given."""
def __new__(cls, data=None, **argkw):
@@ 93,5 +91,5 @@
"""`Spearman's rank correlation coefficient
`_"""
+ correlation_coefficient>`_."""
def __init__(self, **argkw):
@@ 119,5 +117,4 @@
class Mahalanobis(DistanceConstructor):
 """ Construct instance of Mahalanobis. """
def __new__(cls, data=None, **argkw):
Index: docs/reference/rst/Orange.distance.rst
===================================================================
 docs/reference/rst/Orange.distance.rst (revision 9752)
+++ docs/reference/rst/Orange.distance.rst (revision 9805)
@@ 5,4 +5,22 @@
##########################################
+The following example demonstrates how to compute distances between two instances:
+
+.. literalinclude:: code/distancesimple.py
+ :lines: 17
+
+A matrix with all pairwise distances can be computed with :obj:`distance_matrix`:
+
+.. literalinclude:: code/distancesimple.py
+ :lines: 911
+
+Unknown values are treated correctly only by Euclidean and Relief
+distance. For other measures, a distance between unknown and known or
+between two unknown values is always 0.5.
+
+===================
+Computing distances
+===================
+
Distance measures typically have to be adjusted to the data. For instance,
when the data set contains continuous features, the distances between
@@ 10,23 +28,11 @@
similar impats, e.g. by dividing the distance with the range.
Distance measures thus appear in pairs  a class that measures
the distance (:obj:`Distance`) and a class that constructs it based on the
data (:obj:`DistanceConstructor`).
+Distance measures thus appear in pairs:
Since most measures work on normalized distances between corresponding
features, an abstract class `DistanceNormalized` takes care of
normalizing.

Unknown values are treated correctly only by Euclidean and Relief
distance. For other measures, a distance between unknown and known or
between two unknown values is always 0.5.

.. autofunction:: distance_matrix

.. class:: Distance

 .. method:: __call__(instance1, instance2)

 Return a distance between the given instances (as a floating point number).
+ a class that constructs the distance measure based on the
+ data (subclass of :obj:`DistanceConstructor`, for
+ example :obj:`Euclidean`), and returns is as
+ a class that measures the distance between two instances
+ (subclass of :obj:`Distance`, for example :obj:`EuclideanDistance`).
.. class:: DistanceConstructor
@@ 38,35 +44,21 @@
not given, instances or distributions can be used.
.. class:: DistanceNormalized
+.. class:: Distance
 An abstract class that provides normalization.
+ .. method:: __call__(instance1, instance2)
 .. attribute:: normalizers
+ Return a distance between the given instances (as a floating point number).
 A precomputed list of normalizing factors for feature values. They are:
+Pairwise distances
+==================
  1/(max_valuemin_value) for continuous and 1/number_of_values
 for ordinal features.
 If either feature is unknown, the distance is 0.5. Such factors
 are used to multiply differences in feature's values.
  ``1`` for nominal features; the distance
 between two values is 0 if they are same (or at least one is
 unknown) and 1 if they are different.
  ``0`` for ignored features.
+.. autofunction:: distance_matrix
 .. attribute:: bases, averages, variances
+=========
+Measures
+=========
 The minimal values, averages and variances
 (continuous features only).

 .. attribute:: domain_version

 The domain version changes each time a domain description is
 changed (i.e. features are added or removed).

 .. method:: feature_distances(instance1, instance2)

 Return a list of floats representing normalized distances between
 pairs of feature values of the two instances.
+Distance measures are defined with two classes: a subclass of obj:`DistanceConstructor`
+and a subclass of :obj:`Distance`.
.. class:: Hamming
@@ 81,5 +73,5 @@
The maximal distance
between two feature values. If dist is the result of
 ~:obj:`DistanceNormalized.feature_distances`,
+ :obj:`~DistanceNormalized.feature_distances`,
then :class:`Maximal` returns ``max(dist)``.
@@ 89,5 +81,5 @@
The sum of absolute values
of distances between pairs of features, e.g. ``sum(abs(x) for x in dist)``
 where dist is the result of ~:obj:`DistanceNormalized.feature_distances`.
+ where dist is the result of :obj:`~DistanceNormalized.feature_distances`.
.. class:: Euclidean
@@ 96,5 +88,5 @@
The square root of sum of squared perfeature distances,
i.e. ``sqrt(sum(x*x for x in dist))``, where dist is the result of
 ~:obj:`DistanceNormalized.feature_distances`.
+ :obj:`~DistanceNormalized.feature_distances`.
.. method:: distributions
@@ 137,5 +129,4 @@
This class is derived directly from :obj:`Distance`.

.. autoclass:: PearsonR
:members:
@@ 147,6 +138,48 @@
:members:
.. autoclass:: SpearmanRConstructor
+.. autoclass:: SpearmanRDistance
:members:
+.. autoclass:: Mahalanobis
+ :members:
+.. autoclass:: MahalanobisDistance
+ :members:
+
+=========
+Utilities
+=========
+
+.. class:: DistanceNormalized
+
+ An abstract class that provides normalization.
+
+ .. attribute:: normalizers
+
+ A precomputed list of normalizing factors for feature values. They are:
+
+  1/(max_valuemin_value) for continuous and 1/number_of_values
+ for ordinal features.
+ If either feature is unknown, the distance is 0.5. Such factors
+ are used to multiply differences in feature's values.
+  ``1`` for nominal features; the distance
+ between two values is 0 if they are same (or at least one is
+ unknown) and 1 if they are different.
+  ``0`` for ignored features.
+
+ .. attribute:: bases, averages, variances
+
+ The minimal values, averages and variances
+ (continuous features only).
+
+ .. attribute:: domain_version
+
+ The domain version changes each time a domain description is
+ changed (i.e. features are added or removed).
+
+ .. method:: feature_distances(instance1, instance2)
+
+ Return a list of floats representing normalized distances between
+ pairs of feature values of the two instances.
+
+