Added default_prediction() method

CHANGELOG.md

@@ -1,7 +1,16 @@
 Latest version, in development
 ==============================
 
-* A lot to do here!
+Enhancements
+------------
+
+* When PredictionImpossible is raised, the prediction is now deferred to
+  default_prediction() method, which can be overridden is child classes. This
+  allows to not always set the default prediction to the average rating, which
+  can be useful for some algorithms (e.g. thos working with implicit positive
+  feedback).
+* LeaveOneOut() now accepts a min_n_ratings parameter to make sure users in the
+  trainset have at least min_n_ratings ratings.
 
 VERSION 1.0.5
 =============

doc/source/building_custom_algo.rst

@@ -95,15 +95,18 @@ It's up to your algorithm to decide if it can or cannot yield a prediction. If
 the prediction is impossible, then you can raise the
 :class:`PredictionImpossible
 <surprise.prediction_algorithms.predictions.PredictionImpossible>` exception.
-You'll need to import it first): ::
+You'll need to import it first: ::
 
-  from surprise import PredictionImpossible
+    from surprise import PredictionImpossible
 
 
 This exception will be caught by the :meth:`predict()
 <surprise.prediction_algorithms.algo_base.AlgoBase.predict>` method, and the
-estimation :math:`\hat{r}_{ui}` will be set to the global mean of all ratings
-:math:`\mu`.
+estimation :math:`\hat{r}_{ui}` will be set according to
+the :meth:`default_prediction()
+<surprise.prediction_algorithms.algo_base.AlgoBase.default_prediction>` method,
+which can be overridden. By default, it returns the average of all ratings in
+the trainset.
 
 Using similarities and baselines
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

surprise/prediction_algorithms/algo_base.py

@@ -102,7 +102,8 @@ def predict(self, uid, iid, r_ui=None, clip=True, verbose=False):
         The ``predict`` method converts raw ids to inner ids and then calls the
         ``estimate`` method which is defined in every derived class. If the
         prediction is impossible (e.g. because the user and/or the item is
-        unkown), the prediction is set to the global mean of all ratings.
+        unkown), the prediction is set according to :meth:`default_prediction()
+        <surprise.prediction_algorithms.algo_base.AlgoBase.default_prediction>`.
 
         Args:
             uid: (Raw) id of the user. See :ref:`this note<raw_inner_note>`.
@@ -151,7 +152,7 @@ def predict(self, uid, iid, r_ui=None, clip=True, verbose=False):
             details['was_impossible'] = False
 
         except PredictionImpossible as e:
-            est = self.trainset.global_mean
+            est = self.default_prediction()
             details['was_impossible'] = True
             details['reason'] = str(e)
 
@@ -172,6 +173,19 @@ def predict(self, uid, iid, r_ui=None, clip=True, verbose=False):
 
         return pred
 
+    def default_prediction(self):
+        '''Used when the ``PredictionImpossible`` exception is raised during a
+        call to :meth:`predict()
+        <surprise.prediction_algorithms.algo_base.AlgoBase.predict>`. By
+        default, return the global mean of all ratings (can be overridden in
+        child classes).
+
+        Returns:
+            (float): The mean of all ratings in the trainset.
+        '''
+
+        return self.trainset.global_mean
+
     def test(self, testset, verbose=False):
         """Test the algorithm on given testset, i.e. estimate all the ratings
         in the given testset.