Update docs

Author: antoinedemathelin

.gitignore

@@ -17,4 +17,6 @@ var/
 *.egg-info/
 .installed.cfg
 *.egg
-docs_build/
+docs_build/
+docs/html/
+docs/doctrees/

adapt/base.py

@@ -59,8 +59,12 @@
 """
 )
 
+base_doc_Xt = """
+    Xt : numpy array (default=None)
+        Target input data.
+"""
 
-base_doc_1 = """
+base_doc_Xt_yt = """
     Xt : numpy array (default=None)
         Target input data.
             
@@ -86,8 +90,53 @@
         ``_get_legal_params(params)``.
 """
 
+base_doc_other_params="""
+    Yields
+    ------
+    optimizer : str or instance of tf.keras.optimizers (default="rmsprop")
+        Optimizer for the task. It should be an
+        instance of tf.keras.optimizers as:
+        ``tf.keras.optimizers.SGD(0.001)`` or
+        ``tf.keras.optimizers.Adam(lr=0.001, beta_1=0.5)``.
+        A string can also be given as ``"adam"``.
+        Default optimizer is ``rmsprop``.
+
+    loss : str or instance of tf.keras.losses (default="mse")
+        Loss for the task. It should be an
+        instance of tf.keras.losses as:
+        ``tf.keras.losses.MeanSquaredError()`` or
+        ``tf.keras.losses.CategoricalCrossentropy()``.
+        A string can also be given as ``"mse"`` or
+        ``categorical_crossentropy``.
+        Default loss is ``mse``.
+
+    metrics : list of str or list of tf.keras.metrics.Metric instance
+        List of metrics to be evaluated by the model during training
+        and testing. Typically you will use ``metrics=['accuracy']``.
+
+    optimizer_enc : str or instance of tf.keras.optimizers
+        If the Adapt Model has an ``encoder`` attribute,
+        a specific optimizer for the ``encoder`` network can
+        be given. Typically, this parameter can be used to
+        give a smaller learning rate to the encoder.
+        If not specified, ``optimizer_enc=optimizer``.
+
+    optimizer_disc : str or instance of tf.keras.optimizers
+        If the Adapt Model has a ``discriminator`` attribute,
+        a specific optimizer for the ``discriminator`` network can
+        be given. If not specified, ``optimizer_disc=optimizer``.
+
+    kwargs : key, value arguments
+        Any arguments of the ``fit`` method from the Tensorflow
+        Model can be given, as ``epochs`` and ``batch_size``.
+        Specific arguments from ``optimizer`` can also be given
+        as ``learning_rate`` or ``beta_1`` for ``Adam``.
+        This allows to perform ``GridSearchCV`` from scikit-learn
+        on these arguments.
+"""
+
 
-def make_insert_doc(estimators=["estimator"]):
+def make_insert_doc(estimators=["estimator"], supervised=False):
     """
     Abstract for adding common parameters
     to the docstring
@@ -101,8 +150,15 @@ def make_insert_doc(estimators=["estimator"]):
     -------
     func
     """
-
     def insert_base_doc(func):
+        # Change signature of Deep Model
+        if "BaseAdaptDeep" in func.__bases__[0].__name__:
+            sign = inspect.signature(func.__init__)
+            parameters = dict(sign.parameters)
+            parameters.pop("self", None)
+            sign = sign.replace(parameters=list(parameters.values()))
+            func.__signature__ = sign
+        
         doc = func.__doc__
         if "Parameters" in doc:
             splits = doc.split("Parameters")
@@ -129,11 +185,21 @@ def insert_base_doc(func):
             doc_est = ""
             for est in estimators:
                 doc_est += base_doc_est[est]
+                
+            if supervised:
+                doc_1 = base_doc_Xt_yt
+            else:
+                doc_1 = base_doc_Xt
+            
+            doc_2 = base_doc_2
+            if "BaseAdaptDeep" in func.__bases__[0].__name__:
+                doc_2 += base_doc_other_params
+            
             splits[1] = (
                 splits[1][:i-1]+
-                doc_est+base_doc_1+
+                doc_est+doc_1+
                 splits[1][i-1:j+1]+
-                base_doc_2+
+                doc_2+
                 splits[1][j+1:]
             )
             new_doc = splits[0]+"Parameters"+splits[1]
@@ -362,11 +428,11 @@ def fit(self, X, y, Xt=None, yt=None, domains=None, **fit_params):
         
         For feature-based models, the transformation of the
         input features ``Xs`` and ``Xt`` is first fitted. In a second
-        stage, the ``estimator`` is fitted on the transformed features.
+        stage, the ``estimator_`` is fitted on the transformed features.
         
         For instance-based models, source importance weights are
         first learned based on ``Xs, ys`` and ``Xt``. In a second
-        stage, the ``estimator`` is fitted on ``Xs, ys`` with the learned
+        stage, the ``estimator_`` is fitted on ``Xs, ys`` with the learned
         importance weights.
 
         Parameters
@@ -382,8 +448,9 @@ def fit(self, X, y, Xt=None, yt=None, domains=None, **fit_params):
             given in `init` is used.
 
         yt : array (default=None)
-            Target input data. If None, the `Xt` argument
-            given in `init` is used.
+            Target input data. Only needed for supervised
+            and semi-supervised Adapt model.
+            If None, the `yt` argument given in `init` is used.
             
         domains : array (default=None)
             Vector giving the domain for each source
@@ -851,6 +918,9 @@ def fit(self, X, y=None, Xt=None, yt=None, domains=None, **fit_params):
         """
         Fit Model. Note that ``fit`` does not reset
         the model but extend the training.
+        
+        Notice also that the compile method will be called 
+        if the model has not been compiled yet.
 
         Parameters
         ----------
@@ -865,8 +935,9 @@ def fit(self, X, y=None, Xt=None, yt=None, domains=None, **fit_params):
             given in `init` is used.
 
         yt : array (default=None)
-            Target input data. If None, the `Xt` argument
-            given in `init` is used.
+            Target input data. Only needed for supervised
+            and semi-supervised Adapt model.
+            If None, the `yt` argument given in `init` is used.
             
         domains : array (default=None)
             Vector giving the domain for each source

adapt/feature_based/_adda.py

@@ -145,7 +145,6 @@ def __init__(self,
                  task=None,
                  discriminator=None,
                  Xt=None,
-                 yt=None,
                  pretrain=True,
                  tol=0.001,
                  copy=True,

adapt/feature_based/_ccsa.py

@@ -8,25 +8,27 @@
 EPS = np.finfo(np.float32).eps
 
 def pairwise_y(X, Y):
-    batch_size = tf.shape(X)[0]
+    batch_size_x = tf.shape(X)[0]
+    batch_size_y = tf.shape(Y)[0]
     dim = tf.reduce_prod(tf.shape(X)[1:])
-    X = tf.reshape(X, (batch_size, dim))
-    Y = tf.reshape(Y, (batch_size, dim))
-    X = tf.tile(tf.expand_dims(X, -1), [1, 1, batch_size])
-    Y = tf.tile(tf.expand_dims(Y, -1), [1, 1, batch_size])
+    X = tf.reshape(X, (batch_size_x, dim))
+    Y = tf.reshape(Y, (batch_size_y, dim))
+    X = tf.tile(tf.expand_dims(X, -1), [1, 1, batch_size_y])
+    Y = tf.tile(tf.expand_dims(Y, -1), [1, 1, batch_size_x])
     return tf.reduce_sum(tf.abs(X-tf.transpose(Y)), 1)/2
 
 def pairwise_X(X, Y):
-    batch_size = tf.shape(X)[0]
+    batch_size_x = tf.shape(X)[0]
+    batch_size_y = tf.shape(Y)[0]
     dim = tf.reduce_prod(tf.shape(X)[1:])
-    X = tf.reshape(X, (batch_size, dim))
-    Y = tf.reshape(Y, (batch_size, dim))
-    X = tf.tile(tf.expand_dims(X, -1), [1, 1, batch_size])
-    Y = tf.tile(tf.expand_dims(Y, -1), [1, 1, batch_size])
+    X = tf.reshape(X, (batch_size_x, dim))
+    Y = tf.reshape(Y, (batch_size_y, dim))
+    X = tf.tile(tf.expand_dims(X, -1), [1, 1, batch_size_y])
+    Y = tf.tile(tf.expand_dims(Y, -1), [1, 1, batch_size_x])
     return tf.reduce_sum(tf.square(X-tf.transpose(Y)), 1)
 
 
-@make_insert_doc(["encoder", "task"])
+@make_insert_doc(["encoder", "task"], supervised=True)
 class CCSA(BaseAdaptDeep):
     """
     CCSA : 

adapt/feature_based/_coral.py

@@ -111,7 +111,6 @@ class CORAL(BaseAdaptEstimator):
     def __init__(self,
                  estimator=None,
                  Xt=None,
-                 yt=None,
                  lambda_=1e-5,
                  copy=True,
                  verbose=1,

adapt/feature_based/_dann.py

@@ -58,13 +58,8 @@ class DANN(BaseAdaptDeep):
     
     Parameters
     ----------        
-    lambda_ : float (default=0.1)
+    lambda_ : float or tensorflow Variable (default=0.1)
         Trade-off parameter.
-        
-    gamma : float (default=10.0)
-        Increase rate parameter.
-        Give the increase rate of the trade-off parameter if
-        ``lambda_`` is set to ``None``.
     
     Attributes
     ----------

adapt/feature_based/_deepcoral.py

@@ -57,7 +57,7 @@ class DeepCORAL(BaseAdaptDeep):
     
     Parameters
     ----------
-    lambda_ : float (default=1.)
+    lambda_ : float or tensorflow Variable (default=1.)
         Trade-off parameter.
         
     match_mean : bool (default=False)
@@ -116,7 +116,6 @@ def __init__(self,
                  encoder=None,
                  task=None,
                  Xt=None,
-                 yt=None,
                  lambda_=1.,
                  match_mean=False,
                  copy=True,

adapt/feature_based/_fe.py

@@ -11,7 +11,7 @@
 from adapt.utils import check_arrays
 
 
-@make_insert_doc()
+@make_insert_doc(supervised=True)
 class FE(BaseAdaptEstimator):
     """
     FE: Frustratingly Easy Domain Adaptation.

adapt/feature_based/_fmmd.py

@@ -8,12 +8,13 @@
 
 
 def pairwise_X(X, Y):
-    batch_size = tf.shape(X)[0]
+    batch_size_x = tf.shape(X)[0]
+    batch_size_y = tf.shape(Y)[0]
     dim = tf.reduce_prod(tf.shape(X)[1:])
-    X = tf.reshape(X, (batch_size, dim))
-    Y = tf.reshape(Y, (batch_size, dim))
-    X = tf.tile(tf.expand_dims(X, -1), [1, 1, batch_size])
-    Y = tf.tile(tf.expand_dims(Y, -1), [1, 1, batch_size])
+    X = tf.reshape(X, (batch_size_x, dim))
+    Y = tf.reshape(Y, (batch_size_y, dim))
+    X = tf.tile(tf.expand_dims(X, -1), [1, 1, batch_size_y])
+    Y = tf.tile(tf.expand_dims(Y, -1), [1, 1, batch_size_x])
     return tf.reduce_sum(tf.square(X-tf.transpose(Y)), 1)
 
 
@@ -110,8 +111,17 @@ class fMMD(BaseAdaptEstimator):
         Choose the kernel between
         ['linear', 'rbf', 'poly'].
         The kernels are computed as follows:
-        ``rbf(X, Y) = exp(gamma * ||X-Y||^2)``
-        ``poly(X, Y) = (gamma * <X, Y> + coef)^degree``
+        - kernel = linear::
+        
+            k(X, Y) = <X, Y>
+            
+        - kernel = rbf::
+        
+            k(X, Y) = exp(gamma * ||X-Y||^2)
+            
+        - kernel = poly::
+        
+            poly(X, Y) = (gamma * <X, Y> + coef)^degree
         
     gamma : float (default=1.)
         Gamma multiplier for the 'rbf' and 
@@ -143,7 +153,6 @@ class fMMD(BaseAdaptEstimator):
     def __init__(self,
                  estimator=None,
                  Xt=None,
-                 yt=None,
                  threshold="auto",
                  kernel="linear",
                  gamma=1.,

adapt/feature_based/_mcd.py

@@ -76,7 +76,6 @@ def __init__(self,
                  encoder=None,
                  task=None,
                  Xt=None,
-                 yt=None,
                  pretrain=True,
                  n_steps=1,
                  copy=True,