Update docs

Author: antoinedemathelin

adapt/feature_based/_ccsa.py

@@ -31,7 +31,38 @@ def pairwise_X(X, Y):
 @make_insert_doc(["encoder", "task"], supervised=True)
 class CCSA(BaseAdaptDeep):
     """
-    CCSA : 
+    CCSA : Classification and Contrastive Semantic Alignment
+    
+    CCSA is a supervised feature based method for classification.
+    
+    It aims at producing an encoded space where the distances between
+    source and target pairs from the same label are minized, whereas
+    the distances between pairs from different labels are maximized.
+    
+    The optimization can be written as follows:
+    
+    .. math::
+    
+        \mathcal{L}_{CCSA} = \\gamma \mathcal{L}_{task}(h \circ g) +
+        (1-\\gamma) (\mathcal{L}_{SA}(g) + \mathcal{L}_{S}(g))
+
+    Where:
+    
+    .. math::
+    
+        \mathcal{L}_{SA}(g) = \sum_{i, j; \; y^s_i = y^t_j} || g(x^s_i) - g(x^t_j) ||^2
+        
+    .. math::
+    
+        \mathcal{L}_{S}(g) = \sum_{i, j; \; y^s_i \\neq y^t_j} \max(0, m - || g(x^s_i) - g(x^t_j) ||^2)
+    
+    With:
+    
+    - :math:`(x^s_i, y^s_i)` the labeled source data (:math:`y^s_i` gives the label)
+    - :math:`(x^t_i, y^t_i)` the labeled target data
+    - :math:`g, h` are respectively the **encoder** and the **task** networks
+    - :math:`\\gamma` is the trade-off parameter.
+    - :math:`m` is the margin parameter.
     
     Parameters
     ----------
@@ -59,6 +90,12 @@ class CCSA(BaseAdaptDeep):
         history of the losses and metrics across the epochs.
         If ``yt`` is given in ``fit`` method, target metrics
         and losses are recorded too.
+        
+    References
+    ----------
+    .. [1] `[1] <https://arxiv.org/abs/1709.10190>`_ S. Motiian, M. Piccirilli, \
+D. A Adjeroh, and G. Doretto. "Unified deep supervised domain adaptation and \
+generalization". In ICCV 2017.
     """
 
     def __init__(self,

adapt/feature_based/_fe.py

@@ -188,6 +188,19 @@ def transform(self, X, domain="tgt"):
         """
         Return augmented features for X.
         
+        In single source:
+        
+        - If ``domain="src"``, the method returns the array (X, **0**, X).
+        - If ``domain="tgt"``, the method returns the array (**0**, X, X).
+        
+        With **0** the array of same shape as X with zeros everywhere.
+        
+        In single Multi-source:
+        
+        - If ``domain="src_%i"%i``, the method returns the array
+          (X, [X]*i, **0**, [X]*(n_sources-i)).
+        - If ``domain="tgt"``, the method returns the array (**0**, [X]*(n_sources+1)).
+        
         Parameters
         ----------
         X : array

adapt/feature_based/_fmmd.py

@@ -111,6 +111,7 @@ class fMMD(BaseAdaptEstimator):
         Choose the kernel between
         ['linear', 'rbf', 'poly'].
         The kernels are computed as follows:
+        
         - kernel = linear::
         
             k(X, Y) = <X, Y>
@@ -148,6 +149,12 @@ class fMMD(BaseAdaptEstimator):
     --------
     CORAL
     FE
+    
+    References
+    ----------
+    .. [1] `[1] <https://www.cs.cmu.edu/afs/cs/Web/People/jgc/publication\
+/Feature%20Selection%20for%20Transfer%20Learning.pdf>`_ S. Uguroglu and J. Carbonell. \
+"Feature selection for transfer learning." In ECML PKDD. 2011.
     """
 
     def __init__(self,

adapt/feature_based/_mcd.py

@@ -225,7 +225,7 @@ def train_step(self, data):
     def predict_avg(self, X):
         """
         Return the average predictions between
-        task_ and discriminator_ networks.
+        ``task_`` and ``discriminator_`` networks.
         
         Parameters
         ----------

adapt/feature_based/_sa.py

@@ -22,7 +22,7 @@ class SA(BaseAdaptEstimator):
         to the input dimension of ``X``
     
     Attributes
-    ----------    
+    ----------
     estimator_ : object
         Fitted estimator.
         
@@ -34,6 +34,12 @@ class SA(BaseAdaptEstimator):
         
     M_ : numpy array
         Alignment matrix
+        
+    References
+    ----------
+    .. [1] `[1] <https://arxiv.org/abs/1409.5241>`_ B. Fernando, A. Habrard, \
+M. Sebban, and T. Tuytelaars. "Unsupervised visual domain adaptation using \
+subspace alignment". In ICCV, 2013.
     """
 
     def __init__(self,

adapt/instance_based/__init__.py

@@ -7,7 +7,7 @@
 from ._tradaboost import TrAdaBoost, TrAdaBoostR2, TwoStageTrAdaBoostR2
 from ._wann import WANN
 from ._ldm import LDM
-from ._nnw import NearestNeighborsWeighting
+from ._nearestneighborsweighting import NearestNeighborsWeighting
 
-__all__ = ["KLIEP", "KMM", "TrAdaBoost", "TrAdaBoostR2",
+__all__ = ["LDM", "KLIEP", "KMM", "TrAdaBoost", "TrAdaBoostR2",
            "TwoStageTrAdaBoostR2", "WANN", "NearestNeighborsWeighting"]

adapt/instance_based/_ldm.py

@@ -20,12 +20,13 @@ class LDM(BaseAdaptEstimator):
     
     .. math::
     
-        \min_{||w||_1 = 1, w>0} \max{||u||=1} |u^T M(w) u|
+        \min_{||w||_1 = 1, w>0} \max_{||u||=1} |u^T M(w) u|
         
     Where:
+    
     - :math:`M(w) = (1/n) X_T^T X_T - X^T_S diag(w) X_S`
     - :math:`X_S, X_T` are respectively the source dataset
-      and the target dataset of size :math:`n`
+      and the target dataset of size :math:`m` and :math:`n`
     
     Parameters
     ----------

adapt/instance_based/_nnw.py renamed to adapt/instance_based/_nearestneighborsweighting.py

@@ -25,11 +25,13 @@ class NearestNeighborsWeighting(BaseAdaptEstimator):
     
     algorithm : {'auto', 'ball_tree', 'kd_tree', 'brute'}, (default='auto')
         Algorithm used to compute the nearest neighbors:
+        
         - 'ball_tree' will use ``BallTree``
         - 'kd_tree' will use ``KDTree``
         - 'brute' will use a brute-force search.
         - 'auto' will attempt to decide the most appropriate algorithm
           based on the values passed to ``fit`` method.
+
         Note: fitting on sparse input will override the setting of
         this parameter, using brute force.
     
@@ -74,6 +76,11 @@ class NearestNeighborsWeighting(BaseAdaptEstimator):
     --------
     KMM
     KLIEP
+    
+    References
+    ----------
+    .. [1] `[1] <https://arxiv.org/pdf/2102.02291.pdf>`_ \
+M. Loog. "Nearest neighbor-based importance weighting". In MLSP 2012.
     """
 
     def __init__(self,

adapt/parameter_based/_finetuning.py

@@ -14,6 +14,12 @@ class FineTuning(BaseAdaptDeep):
     fitted first using the ``pretrain`` parameter. The layers
     to train in the encoder can be set via the parameter ``training``.
     
+    .. figure:: ../_static/images/regulartransfer.png
+        :align: center
+        
+        Transferring parameters of a CNN pretrained on Imagenet
+        (source: [1])
+    
     Parameters
     ----------        
     training : bool or list of bool, optional (default=True)
@@ -40,6 +46,13 @@ class FineTuning(BaseAdaptDeep):
     history_ : dict
         history of the losses and metrics across the epochs
         of the network training.
+    
+    References
+    ----------
+    .. [1] `[1] <https://hal.inria.fr/hal-00911179v1/document>`_ \
+Oquab M., Bottou L., Laptev I., Sivic J. "Learning and \
+transferring mid-level image representations using convolutional \
+neural networks". In CVPR, 2014.
     """
 
     def __init__(self,

src_docs/_templates/layout.html

@@ -20,18 +20,23 @@
 <li class="toctree-l1"><a class="reference internal" href="{{ pathto("contents") }}{{ contents }}{{ "adapt-feature-based" }}">Feature-based</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="{{ pathto("generated/adapt.feature_based.FE") }}">FE</a></li>
 <li class="toctree-l2"><a class="reference internal" href="{{ pathto("generated/adapt.feature_based.CORAL") }}">CORAL</a></li>
+<li class="toctree-l2"><a class="reference internal" href="{{ pathto("generated/adapt.feature_based.SA") }}">SA</a></li>
+<li class="toctree-l2"><a class="reference internal" href="{{ pathto("generated/adapt.feature_based.fMMD") }}">fMMD</a></li>
 <li class="toctree-l2"><a class="reference internal" href="{{ pathto("generated/adapt.feature_based.DeepCORAL") }}">DeepCORAL</a></li>
 <li class="toctree-l2"><a class="reference internal" href="{{ pathto("generated/adapt.feature_based.DANN") }}">DANN</a></li>
 <li class="toctree-l2"><a class="reference internal" href="{{ pathto("generated/adapt.feature_based.ADDA") }}">ADDA</a></li>
 <li class="toctree-l2"><a class="reference internal" href="{{ pathto("generated/adapt.feature_based.WDGRL") }}">WDGRL</a></li>
 <li class="toctree-l2"><a class="reference internal" href="{{ pathto("generated/adapt.feature_based.CDAN") }}">CDAN</a></li>
 <li class="toctree-l2"><a class="reference internal" href="{{ pathto("generated/adapt.feature_based.MCD") }}">MCD</a></li>
 <li class="toctree-l2"><a class="reference internal" href="{{ pathto("generated/adapt.feature_based.MDD") }}">MDD</a></li>
+<li class="toctree-l2"><a class="reference internal" href="{{ pathto("generated/adapt.feature_based.CCSA") }}">CCSA</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="{{ pathto("contents") }}{{ contents }}{{ "adapt-instance-based" }}">Instance-based</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="{{ pathto("generated/adapt.instance_based.LDM") }}">LDM</a></li>
 <li class="toctree-l2"><a class="reference internal" href="{{ pathto("generated/adapt.instance_based.KLIEP") }}">KLIEP</a></li>
 <li class="toctree-l2"><a class="reference internal" href="{{ pathto("generated/adapt.instance_based.KMM") }}">KMM</a></li>
+<li class="toctree-l2"><a class="reference internal" href="{{ pathto("generated/adapt.instance_based.NearestNeighborsWeighting") }}">NearestNeighborsWeighting</a></li>
 <li class="toctree-l2"><a class="reference internal" href="{{ pathto("generated/adapt.instance_based.TrAdaBoost") }}">TrAdaBoost</a></li>
 <li class="toctree-l2"><a class="reference internal" href="{{ pathto("generated/adapt.instance_based.TrAdaBoostR2") }}">TrAdaBoostR2</a></li>
 <li class="toctree-l2"><a class="reference internal" href="{{ pathto("generated/adapt.instance_based.TwoStageTrAdaBoostR2") }}">TwoStageTrAdaBoostR2</a></li>
@@ -42,9 +47,11 @@
 <li class="toctree-l2"><a class="reference internal" href="{{ pathto("generated/adapt.parameter_based.RegularTransferLR") }}">RegularTransferLR</a></li>
 <li class="toctree-l2"><a class="reference internal" href="{{ pathto("generated/adapt.parameter_based.RegularTransferLC") }}">RegularTransferLC</a></li>
 <li class="toctree-l2"><a class="reference internal" href="{{ pathto("generated/adapt.parameter_based.RegularTransferNN") }}">RegularTransferNN</a></li>
+<li class="toctree-l2"><a class="reference internal" href="{{ pathto("generated/adapt.parameter_based.FineTuning") }}">FineTuning</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="{{ pathto("contents") }}{{ contents }}{{ "adapt-metrics" }}">Metrics</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="{{ pathto("generated/adapt.metrics.make_uda_scorer") }}">make_uda_scorer</a></li>
 <li class="toctree-l2"><a class="reference internal" href="{{ pathto("generated/adapt.metrics.cov_distance") }}">cov_distance</a></li>
 <li class="toctree-l2"><a class="reference internal" href="{{ pathto("generated/adapt.metrics.j_score") }}">j_score</a></li>
 <li class="toctree-l2"><a class="reference internal" href="{{ pathto("generated/adapt.metrics.linear_discrepancy") }}">linear_discrepancy</a></li>