Merge pull request #1564 from janezd/cn2-documentation

CN2: simplify documentation

Author: BlazZupan

Orange/classification/rules.py

@@ -1,3 +1,12 @@
+"""
+Induction of rules works by finding a rule that covers some learning instances,
+removing these instances, and repeating this until all instances are covered.
+Rules are scored by heuristics such as impurity of class distribution of
+covered instances. The module includes common rule-learning algorithms,
+and allows for replacing rule search strategies, scoring and other
+components.
+"""
+
 import operator
 from copy import copy
 from hashlib import sha1
@@ -1287,16 +1296,16 @@ def predict(self, X):
 
 class CN2UnorderedLearner(_RuleLearner):
     """
-    Unordered CN2 inducer that constructs a set of unordered rules. To
-    evaluate found hypotheses, Laplace accuracy measure is used. Returns
-    a CN2UnorderedClassifier if called with data.
+    Construct a set of unordered rules.
 
-    Notes
-    -----
-    Rules are learnt for each class (target class) individually, in
-    regard to the original learning data. When a rule has been found,
-    only covered examples of that class are removed. This is because now
-    each rule must independently stand against all negatives.
+    Rules are learnt for each class individually and scored
+    by the relative frequency of the class corrected by the Laplace correction.
+    After adding a rule, only the covered examples of that class are removed.
+
+    The code below loads the *iris* data set (four continuous attributes
+    and a discrete class) and fits the learner.
+
+    .. literalinclude:: code/classification-cn2ruleinduction1.py
 
     References
     ----------

doc/data-mining-library/source/reference/classification.rst

@@ -176,6 +176,8 @@ Elliptic Envelope
 CN2 Rule Induction
 ------------------
 
+.. automodule:: Orange.classification.rules
+
 .. autoclass:: CN2Learner
    :members:
 

…code/classification-cn2ruleinduction1.py …code/classification-cn2ruleinduction1.pydoc/data-mining-library/source/tutorial/code/classification-cn2ruleinduction1.py renamed to doc/data-mining-library/source/reference/code/classification-cn2ruleinduction1.py doc/data-mining-library/source/tutorial/code/classification-cn2ruleinduction1.py renamed to doc/data-mining-library/source/reference/code/classification-cn2ruleinduction1.py

@@ -136,57 +136,3 @@ Logistic regression wins in area under ROC curve::
              tree knn  logreg
     Accuracy 0.79 0.47 0.78
     AUC      0.68 0.56 0.70
-
-
-Rule induction
---------------
-
-To induce rules from examples, separate and conquer strategy is applied.
-In essence, learning instances are covered and removed following a
-chosen rule. The process is repeated while learning instances remain. To
-evaluate found hypotheses and to choose the best rule in each iteration,
-search heuristics are used (primarily, rule class distribution is the
-decisive determinant). The over-fitting of noisy data is avoided by
-preferring simpler, shorter rules even if the accuracy of more complex
-rules is higher.
-
-The use of the created module is straightforward. New rule induction
-algorithms can be easily introduced, by either utilising predefined
-components or developing new ones (these include various search
-algorithms, search strategies, evaluators, and others). Several
-well-known rule induction algorithms have already been included.
-
-Unordered CN2
-+++++++++++++
-
-Unordered CN2 inducer (:any:`CN2UnorderedLearner`) constructs a set of
-unordered rules. Rules are learnt for each class individually, in regard
-to the original learning data. To evaluate found hypotheses, Laplace
-accuracy measure is used. Returns a CN2UnorderedClassifier if called
-with data.
-
-The code below loads the *iris* data set (four continuous attributes
-and a discrete class) and fits the learner.
-
-.. literalinclude:: code/classification-cn2ruleinduction1.py
-
-Having first initialised the learner, we then control the algorithm by
-modifying its parameters. The underlying components are available to us
-by accessing the rule finder. The search algorithm can additionally be
-constrained by forwarding base rules upon learner initialization (see
-code reference).
-
-The classifier is used to predict data instances.
-
-    >>> classifier(data.X[50:55])
-    [1 1 0 1 1]
-
-Induced rules can be quickly reviewed and interpreted. They are each of
-the form "if cond then predict class". That is, a conjunction of
-selectors followed by the predicted class.
-
-    >>> for rule in classifier.rule_list[:3]:
-    >>>     print(rule, rule.curr_class_dist.tolist())
-    IF petal length<=3.0 AND sepal width>=2.9 THEN iris=Iris-setosa  [49, 0, 0]
-    IF petal length>=3.0 AND petal length<=4.8 THEN iris=Iris-versicolor  [0, 46, 3]
-    IF petal width>=1.8 AND petal length>=4.9 THEN iris=Iris-virginica  [0, 0, 43]

doc/data-mining-library/source/tutorial/classification.rst

@@ -61,6 +61,7 @@ Visualize
    widgets/visualize/sievediagram
    widgets/visualize/pythagoreantree
    widgets/visualize/pythagoreanforest
+   widgets/classify/cn2ruleviewer
 
 
 Classify
@@ -80,7 +81,6 @@ Classify
    widgets/classify/saveclassifier
    widgets/classify/svm
    widgets/classify/cn2ruleinduction
-   widgets/classify/cn2ruleviewer
 
 
 Regression