Serialization: Add docstrings

GPy/core/gp.py

@@ -110,7 +110,14 @@ class GP(Model):
         self.posterior = None
 
     def to_dict(self, save_data=True):
-        input_dict = super(GP, self)._to_dict()
+        """
+        Convert the object into a json serializable dictionary.
+        Note: It uses the private method _save_to_input_dict of the parent.
+
+        :param boolean save_data: if true, it adds the training data self.X and self.Y to the dictionary
+        :return dict: json serializable dictionary containing the needed information to instantiate the object
+        """
+        input_dict = super(GP, self)._save_to_input_dict()
         input_dict["class"] = "GPy.core.GP"
         if not save_data:
             input_dict["X"] = None
@@ -137,7 +144,7 @@ class GP(Model):
         return input_dict
 
     @staticmethod
-    def _from_dict(input_dict, data=None):
+    def _build_from_input_dict(input_dict, data=None):
         import GPy
         import numpy as np
         if (input_dict['X'] is None) or (input_dict['Y'] is None):
@@ -282,7 +289,7 @@ class GP(Model):
             mu += self.mean_function.f(Xnew)
         return mu, var
 
-    def predict(self, Xnew, full_cov=False, Y_metadata=None, kern=None, 
+    def predict(self, Xnew, full_cov=False, Y_metadata=None, kern=None,
                 likelihood=None, include_likelihood=True):
         """
         Predict the function(s) at the new point(s) Xnew. This includes the

GPy/core/mapping.py

@@ -28,7 +28,7 @@ class Mapping(Parameterized):
     def to_dict(self):
         raise NotImplementedError
 
-    def _to_dict(self):
+    def _save_to_input_dict(self):
         input_dict = {}
         input_dict["input_dim"] = self.input_dim
         input_dict["output_dim"] = self.output_dim
@@ -37,16 +37,27 @@ class Mapping(Parameterized):
 
     @staticmethod
     def from_dict(input_dict):
+        """
+        Instantiate an object of a derived class using the information
+        in input_dict (built by the to_dict method of the derived class).
+        More specifically, after reading the derived class from input_dict,
+        it calls the method _build_from_input_dict of the derived class.
+        Note: This method should not be overrided in the derived class. In case
+        it is needed, please override _build_from_input_dict instate.
+
+        :param dict input_dict: Dictionary with all the information needed to
+           instantiate the object.
+        """
         import copy
         input_dict = copy.deepcopy(input_dict)
         mapping_class = input_dict.pop('class')
         input_dict["name"] = str(input_dict["name"])
         import GPy
         mapping_class = eval(mapping_class)
-        return mapping_class._from_dict(mapping_class, input_dict)
+        return mapping_class._build_from_input_dict(mapping_class, input_dict)
 
     @staticmethod
-    def _from_dict(mapping_class, input_dict):
+    def _build_from_input_dict(mapping_class, input_dict):
         return mapping_class(**input_dict)
 
 

GPy/core/model.py

@@ -8,7 +8,10 @@ class Model(ParamzModel, Priorizable):
     def __init__(self, name):
         super(Model, self).__init__(name)  # Parameterized.__init__(self)
 
-    def _to_dict(self):
+    def _save_to_input_dict(self):
+        """
+        It is used by the public method to_dict to create json serializable dictionary.
+        """
         input_dict = {}
         input_dict["name"] = self.name
         return input_dict
@@ -18,16 +21,37 @@ class Model(ParamzModel, Priorizable):
 
     @staticmethod
     def from_dict(input_dict, data=None):
+        """
+        Instantiate an object of a derived class using the information
+        in input_dict (built by the to_dict method of the derived class).
+        More specifically, after reading the derived class from input_dict,
+        it calls the method _build_from_input_dict of the derived class.
+        Note: This method should not be overrided in the derived class. In case
+        it is needed, please override _build_from_input_dict instate.
+
+        :param dict input_dict: Dictionary with all the information needed to
+           instantiate the object.
+        """
         import copy
         input_dict = copy.deepcopy(input_dict)
         model_class = input_dict.pop('class')
         input_dict["name"] = str(input_dict["name"])
         import GPy
         model_class = eval(model_class)
-        return model_class._from_dict(input_dict, data)
+        return model_class._build_from_input_dict(input_dict, data)
 
     @staticmethod
-    def _from_dict(model_class, input_dict, data=None):
+    def _build_from_input_dict(model_class, input_dict, data=None):
+        """
+        This method is used by the public method from_dict to build an object
+        of class model_class using the information contained in input_dict.
+        Note: This method is often overrided in the derived class to deal with
+        any pre-processing of the parameters in input_dict before calling the
+        constructor of the object.
+
+        :param str model_class: Class of the object to build.
+        :param dict input_dict: Extra information needed by the constructor of model_class.
+        """
         return model_class(**input_dict)
 
     def save_model(self, output_filename, compress=True, save_data=True):

GPy/core/sparse_gp.py

@@ -119,16 +119,24 @@ class SparseGP(GP):
         self._Zgrad = self.Z.gradient.copy()
 
     def to_dict(self, save_data=True):
+        """
+        Convert the object into a json serializable dictionary.
+
+        :param boolean save_data: if true, it adds the training data self.X and self.Y to the dictionary
+        :return dict: json serializable dictionary containing the needed information to instantiate the object
+        """
         input_dict = super(SparseGP, self).to_dict(save_data)
         input_dict["class"] = "GPy.core.SparseGP"
         input_dict["Z"] = self.Z.tolist()
         return input_dict
 
     @staticmethod
-    def _from_dict(input_dict, data=None):
+    def _build_from_input_dict(input_dict, data=None):
+        # Called from the from_dict method.
         import GPy
         if (input_dict['X'] is None) or (input_dict['Y'] is None):
-            assert(data is not None)
+            if data is None:
+                raise ValueError("The model was serialized whithout the training data. 'data' must be not None!")
             input_dict["X"], input_dict["Y"] = np.array(data[0]), np.array(data[1])
         elif data is not None:
             print("WARNING: The model has been saved with X,Y! The original values are being overriden!")