Commits

Aleš Erjavec  committed fc11507

Fixed/added some docstrings.

  • Participants
  • Parent commits 4d52aba

Comments (0)

Files changed (3)

+orangekit.earth
+===============
+

File orangekit/earth/earth.py

 """
 Earth Orange interface
+
+Example::
+
+    >>> import Orange, orangekit.earth
+    >>> data = Orange.data.Table("housing")
+    >>> c = orangekit.earth.EarthLearner(data, degree=2, terms=10)
+    >>> print c.to_string(precision=2)
+    MEDV =
+       23.59
+       -0.61 * max(0, LSTAT - 6.12)
+       +11.90 * max(0, RM - 6.43)
+       +1.14 * max(0, 6.43 - RM)
+       -228.80 * max(0, NOX - 0.65) * max(0, RM - 6.43)
+       +0.02 * max(0, TAX - 307.00) * max(0, 6.12 - LSTAT)
+       +0.03 * max(0, 307.00 - TAX) * max(0, 6.12 - LSTAT)
+
 """
 
 from __future__ import division
     :param float penalty:
         Penalty for hinges in the GCV computation (used in the pruning pass).
         Default is 3.0 if ``degree`` is above 1, and 2.0 otherwise.
-    :param flaot thresh:
+    :param float thresh:
         Threshold for RSS decrease in the forward pass (default: 0.001).
     :param int min_span: TODO.
     :param float new_var_penalty:
     :param bool store_instances:
         Store training instances in the model (default: ``True``).
 
-    .. todo::
-        min_span, prunning_method (need Leaps like functionality,
-        currently only eval_subsets_using_xtx is implemented).
-
-
     """
 
     def __new__(cls, instances=None, weight_id=None, **kwargs):
             Orange.data.preprocess.DomainContinuizer.Ignore
 
     def __call__(self, instances, weight_id=None):
+        """
+        Train an :class:`EarthClassifier` instance on the `instances`.
+
+        :param Orange.data.Table instances: Training instances.
+
+        .. note:: `weight_id` is ignored.
+
+        """
         expanded_class = None
         multitarget = False
 
         self.__dict__.update(kwargs)
 
     def __call__(self, instance, result_type=Orange.core.GetValue):
+        """
+        Predict the response value on `instance`.
+
+        :param Orange.data.Instance instance:
+            Input data instance.
+
+        """
         if self.multitarget and self.domain.class_vars:
             resp_vars = list(self.domain.class_vars)
         elif is_discrete(self.class_var):
         If table is not supplied, the base matrix of the training instances
         is returned.
 
-        :param instances: Input instances for the base matrix.
-        :type instances: :class:`Orange.data.Table`
+        :param Orange.data.Table instances:
+            Input instances for the base matrix.
 
         """
         if instances is None:
         """
         Return a list of constructed features of Earth terms.
 
-        The attributes can be used in Orange's domain translation
-        (i.e. they define the proper ``get_value_from`` functions).
+        The features can be used in Orange's domain translation
+        (i.e. they define the proper :func:`get_value_from` functions).
+
+        :rtype: list of :class:`Orange.feature.Descriptor`
 
         """
         terms = []
         """
         Predict the response values.
 
-        :param instance: Data instance
-        :type instance: :class:`Orange.data.Instance`
+        :param Orange.data.Instance instance:
+            Data instance
 
         """
         data = Orange.data.Table(self.domain, [instance])
 
         If no term is given, return all features used in the model.
 
-        :param term: term index
-        :type term: int
+        :param int term: Term index
 
         """
         if term is None:
         """
         Return the estimated variable importances.
 
-        :param used_only: if True return only used attributes
+        :param bool used_only: If True return only used attributes.
 
         """
         return evimp(self, used_only)
                             self.cuts, self.betas),
                 dict(self.__dict__))
 
-    def to_string(self, percision=3, indent=3):
+    def to_string(self, precision=3, indent=3):
         """
         Return a string representation of the model.
+
+        This is also the default string representation of the model
+        (as returned by :func:`str`)
+
         """
         if self.multitarget:
             r_vars = list(self.domain.class_vars)
             resp.append(
                 _format_response(name, betas, self.cuts[self.best_set],
                                  self.dirs[self.best_set], feature_names,
-                                 percision, indent))
+                                 precision, indent))
 
         return "\n\n".join(resp)
 

File orangekit/earth/evimp.py

     imp_min = numpy.min(importances[:, [2, 3]], axis=0)
     imp_max = numpy.max(importances[:, [2, 3]], axis=0)
 
-    #Normalize importances.
+    # Normalize importances.
     importances[:, [2, 3]] = 100.0 * (importances[:, [2, 3]] \
                             - [imp_min]) / ([imp_max - imp_min])
 
 
 def bagged_evimp(classifier, used_only=True):
     """
-    Extract combined (average) `evimp` from an instance of BaggedClassifier.
+    Extract combined (average) :func:`evimp` from an instance of
+    :class:`~Orange.ensemble.bagging.BaggedClassifier` using
+    :class:`EarthLearner` as a `base_learner`.
 
     Example::
 
         bc = BaggedLearner(EarthLearner(degree=3, terms=10), data)
         bagged_evimp(bc)
 
+    .. seealso:: :class:`ScoreEarthImportance`
+
     """
     def assert_type(obj, class_):
         if not isinstance(obj, class_):
 
         import Orange
         data = Orange.data.Table("housing")
-        c = Orange.regression.earth.EarthLearner(data, degree=3)
-        Orange.regression.earth.plot_evimp(c.evimp())
+        c = orangekit.earth.EarthLearner(data, degree=3)
+        orangekit.earth.plot_evimp(c.evimp())
 
     .. image:: files/earth-evimp.png
 
     features based on their importance in the Earth model using
     ``bagged_evimp``.
 
+    :param int t:
+        Number of earth models to train on the data.
+
+    :param int degree:
+        The maximum degree of the induced models.
+
+    :param int terms:
+        Maximum number of terms induced in the forward pass.
+
+    :param int score_what:
+        What to return as a score. Can be one of:
+
+        * ``"nsubsets"``
+        * ``"rss"``
+        * ``"gcv"``
+
+        string or or class constants:
+
+        * ``NSUBSETS``
+        * ``RSS``
+        * ``GCV``
+
     """
     # Return types
+
+    #: The number of subsets the feature is included during the
+    #: pruning pass.
     NSUBSETS = 0
+
+    #: Residual squared error increase when the feature was removed
+    #: during the pruning pass (averaged over all `t` models)
     RSS = 1
+
+    #: GCV increase when the feature was removed during the pruning pass
+    #: (averaged over all `t` models)
     GCV = 2
 
     handles_discrete = True
 
     def __init__(self, t=10, degree=2, terms=10, score_what="nsubsets",
                  cached=True):
-        """
-        :param t: Number of earth models to train on the data
-            (using BaggedLearner).
-
-        :param score_what: What to return as a score.
-            Can be one of: "nsubsets", "rss", "gcv" or class constants
-            NSUBSETS, RSS, GCV.
-
-        """
         self.t = t
         self.degree = degree
         self.terms = terms
         self._cached_evimp = None
 
     def __call__(self, attr, data, weight_id=None):
+        """
+        Return the score for `attr` as evaluated on `data`.
+
+        :param Orange.feature.Descriptor attr:
+            A feature descriptor present in ``data.domain.features``.
+
+        :param Orange.data.Table data:
+            Model training data.
+
+        .. note:: `weight_id` is ignored.
+
+        """
         ref = self._cache_ref
         if ref is not None and ref is data:
             evimp = self._cached_evimp