[DOC] reuse doc(All Reuse Methods)

docs/components/learnware.rst

@@ -16,20 +16,10 @@ In our implementation, the class ``Learnware`` has 3 important member variables:
 - ``model``: The model in the learnware, can be a ``BaseModel`` or a dict including model name and path. When it is a dict, the function ``Learnware.instantiate_model`` is used to transform it to a ``BaseModel``. The function ``Learnware.predict`` use the model to predict for an input ``X``. See more in `COMPONENTS: Model <./model.html>`_.
 - ``specification``: The specification including the semantic specification and the statistic specification.
 
-In the learnware paradigm, a learnware is a well-performed trained machine learning model with a specification which enables it to be adequately identified to reuse according to the requirement of future users who know nothing about the learnware in advance. The introduction of specifications are shown in `COMPONENTS: Specification <./spec.html>`_.
-
-In our implementation, the class ``Learnware`` has 3 important member variables:
-
-- ``id``: The learnware id is generated by ``market``.
-- ``model``: The model in the learnware, can be a ``BaseModel`` or a dict including model name and path. When it is a dict, the function ``Learnware.instantiate_model`` is used to transform it to a ``BaseModel``. The function ``Learnware.predict`` use the model to predict for an input ``X``. See more in `COMPONENTS: Model <./model.html>`_.
-- ``specification``: The specification including the semantic specification and the statistic specification.
-
-
-Learnware for Hetero Reuse (Feature Align + Hetero Map Learnware)
 Learnware for Hetero Reuse (Feature Align + Hetero Map Learnware)
 =======================================================================
 
-In the Hetero Market(see `COMPONENTS:Market  <./market.html>`_ for details), ``HeteroSearcher`` identifies and recommends helpful learnwares among all learnwares in the market, 
+In the Hetero Market(see `COMPONENTS: Hetero Market  <./market.html#hetero-market>`_ for details), ``HeteroSearcher`` identifies and recommends helpful learnwares among all learnwares in the market, 
 including learnwares with feature/label spaces different from the user's task requirements(heterogeneous learnwares). ``FeatureAlignLearnware`` and ``HeteroMapLearnware``
 are designed to enable the reuse of heterogeneous learnwares, which extends ``Learnware`` with the ability to align the feature space and label space of the learnware to the user's task requirements, 
 and provide basic interfaces for heterogeneous learnwares to be applied to tasks beyond their original purposes.
@@ -71,7 +61,7 @@ helpful beyond their original purposes, and eliminating the need for users to bu
 There are two main categories of ``Reuse Methods``: (1) direct reuse and (2) reuse based on a small amount of labeled data.
 
 .. note:: 
-    Combine ``HeteroMapAlignLearnware`` with the following reuse methods to enable the reuse of heterogeneous learnwares. See `WORKFLOW:Reuse <../workflows/reuse.html>`_ for details.
+    Combine ``HeteroMapAlignLearnware`` with the following reuse methods to enable the reuse of heterogeneous learnwares. See `WORKFLOW: Reuse <../workflows/reuse.html>`_ for details.
 
 Direct Reuse of Learnware
 --------------------------

docs/components/market.rst

@@ -164,4 +164,4 @@ The semantic specification search and statistical specification search have been
   - If the ``stat_info`` is provided in ``user_info``, it conducts one of the following two types of statistical specification search using ``EasySearcher``, depending on whether heterogeneous learnware search is enabled. If enabled, ``stat_info`` will be updated with a ``HeteroMapTableSpecification`` generated for the user, and the Hetero Market performs heterogeneous learnware selection based on the updated ``stat_info``. If not enabled, the Hetero Market performs homogeneous learnware selection based on the original ``stat_info``.
   
 .. note:: 
-  The heterogeneous learnware search is enabled when ``user_info`` contains valid heterogeneous search information. Please refer to `WORKFLOWS:Search  <../workflows/search.html>`_ for details.
+  The heterogeneous learnware search is enabled when ``user_info`` contains valid heterogeneous search information. Please refer to `WORKFLOWS: Hetero Search  <../workflows/search.html#hetero-search>`_ for details.

docs/workflows/reuse.rst

@@ -2,36 +2,135 @@
 Learnwares Reuse
 ==========================================
 
-This part introduces two baseline methods for reusing a given list of learnwares, namely ``JobSelectorReuser`` and ``AveragingReuser``.
-Instead of training a model from scratch, the user can easily reuse a list of learnwares (``List[Learnware]``) to predict the labels of their own data (``numpy.ndarray`` or ``torch.Tensor``).
+``Learnware Reuser`` is a ``Python API`` that offers a variety of convenient tools for learnware reuse. Users can reuse a single learnware, combination of multiple learnwares,
+and heterogeneous learnwares using these tools efficiently, thereby saving the laborious time and effort of building models from scratch. There are mainly two types of 
+reuse tools, based on whether user has gathered a small amount of labeled data beforehand: (1) direct reuse and (2) customized reuse based on labeled data.
 
-To illustrate, we provide a code demonstration that obtains the user dataset using ``sklearn.datasets.load_digits``, where ``test_data`` represents the data that requires prediction.
-Assuming that ``learnware_list`` is the list of learnwares searched by the learnware market based on user specifications, the user can reuse each learnware in the ``learnware_list`` through ``JobSelectorReuser`` or ``AveragingReuser`` to predict the label of ``test_data``, thereby avoiding training a model from scratch.
+.. note:: 
+
+    For detailed explanations of the learnware reusers mentioned below, please refer to `COMPONENTS: Learnware & Reuser  <../components/learnware.html#all-reuse-methods>`_ .
 
 Homo Reuse
 ====================
 
-.. code-block:: python
+This part introduces baseline methods for reusing homogeneous learnwares to make predictions on unlabeled data.
+
+Direct reuse of Learnware
+--------------------------
 
-    from sklearn.datasets import load_digits
-    from learnware.learnware import JobSelectorReuser, AveragingReuser
+- ``JobSelector`` selects different learnwares for different data by training a ``job selector`` classifier. The following code shows how to use it:
 
-    # Load user data
-    X, y = load_digits(return_X_y=True)
-    test_data = X
+.. code:: python
 
-    # Based on user information, the learnware market returns a list of learnwares (learnware_list)
-    # Use jobselector reuser to reuse the searched learnwares to make prediction
+    from learnware.reuse import JobSelectorReuser
+
+    # learnware_list is the list of searched learnware
     reuse_job_selector = JobSelectorReuser(learnware_list=learnware_list)
-    job_selector_predict_y = reuse_job_selector.predict(user_data=test_data)
 
-    # Use averaging ensemble reuser to reuse the searched learnwares to make prediction
-    reuse_ensemble = AveragingReuser(learnware_list=learnware_list)
-    ensemble_predict_y = reuse_ensemble.predict(user_data=test_data)
+    # test_x is the user's data for prediction
+    # predict_y is the prediction result of the reused learnwares
+    predict_y = reuse_job_selector.predict(user_data=test_x)
+
+- ``AveragingReuser`` uses an ensemble method to make predictions. The ``mode`` parameter specifies the specific ensemble method:
+
+.. code:: python
+
+    from learnware.reuse import AveragingReuser
+
+    # Regression tasks:
+    #   - mode="mean": average the learnware outputs.
+    # Classification tasks:
+    #   - mode="vote_by_label": majority vote for learnware output labels.
+    #   - mode="vote_by_prob": majority vote for learnware output label probabilities.
+    
+    reuse_ensemble = AveragingReuser(
+        learnware_list=learnware_list, mode="vote_by_label"
+    )
+    ensemble_predict_y = reuse_ensemble.predict(user_data=test_x)
+
+
+Reusing Learnware with Labeled Data
+------------------------------------
+
+When users have a small amount of labeled data, they can also adapt/polish the received learnware(s) by reusing them with the labeled data, gaining even better performance. 
+
+- ``EnsemblePruningReuser`` selectively ensembles a subset of learnwares to choose the ones that are most suitable for the user's task:
+
+.. code:: python
+
+    from learnware.reuse import EnsemblePruningReuser
+
+    # mode="regression": Suitable for regression tasks
+    # mode="classification": Suitable for classification tasks
+    reuse_ensemble_pruning = EnsemblePruningReuser(
+        learnware_list=learnware_list, mode="regression"
+    )
+
+    # (val_X, val_y) is the small amount of labeled data
+    reuse_ensemble_pruning.fit(val_X, val_y)
+    predict_y = reuse_job_selector.predict(user_data=test_x)
+
+- ``FeatureAugmentReuser`` helps users reuse learnwares by augmenting features. This reuser regards each received learnware as a feature augmentor, taking its output as a new feature and then build a simple model on the augmented feature set(``logistic regression`` for classification tasks and ``ridge regression`` for regression tasks):
+
+.. code:: python
+
+    from learnware.reuse import FeatureAugmentReuser
+
+    # mode="regression": Suitable for regression tasks
+    # mode="classification": Suitable for classification tasks
+    reuse_feature_augment = FeatureAugmentReuser(
+        learnware_list=learnware_list, mode="regression"
+    )
+
+    # (val_X, val_y) is the small amount of labeled data
+    reuse_feature_augment.fit(val_X, val_y)
+    predict_y = reuse_feature_augment.predict(user_data=test_x)
+
 
 Hetero Reuse
 ====================
 
+When heterogeneous learnware search is activated(see `WORKFLOWS: Hetero Search <../workflows/search.html#hetero-search>`_), users would receive heterogeneous learnwares which are identified from the whole "specification world". 
+Though these recommended learnwares are trained from tasks with different feature/label spaces from the user's task, they can still be helpful and perform well beyond their original purpose.
+Normally these learnwares are hard to be used, leave alone polished by users, due to the feature/label space heterogeneity. However with the help of ``HeteroMapAlignLearnware`` class which align heterogeneous learnware
+with the user's task, users can easily reuse them with the same set of reuse methods mentioned above.
+
+During the alignment process of heterogeneous learnware, the statistical specifications of the learnware and the user's task ``(user_spec)`` are used for input space alignment, 
+and a small amount of labeled data `(val_x, val_y)`` is mandatory to be used for output space alignment. This can be done by the following code:
+
+.. code:: python
+
+    from learnware.reuse import HeteroMapAlignLearnware
+
+    # mode="regression": For user tasks of regression
+    # mode="classification": For user tasks of classification
+    hetero_learnware = HeteroMapAlignLearnware(learnware=leanrware, mode="regression")
+    hetero_learnware.align(user_spec, val_x, val_y)
+
+    # Make predictions using the aligned heterogeneous learnware
+    predict_y = hetero_learnware.predict(user_data=test_x)
+
+If you want to reuse multiple heterogeneous learnwares, 
+combine ``HeteroMapAlignLearnware`` with the homogeneous reuse methods ``AveragingReuser`` and ``EnsemblePruningReuser`` mentioned above will do the trick:
+
+.. code:: python
+
+    hetero_learnware_list = []
+    for learnware in learnware_list:
+        hetero_learnware = HeteroMapAlignLearnware(learnware, mode="regression")
+        hetero_learnware.align(user_spec, val_x, val_y)
+        hetero_learnware_list.append(hetero_learnware)
+                
+    # Reuse multiple heterogeneous learnwares using AveragingReuser
+    reuse_ensemble = AveragingReuser(learnware_list=hetero_learnware_list, mode="mean")
+    ensemble_predict_y = reuse_ensemble.predict(user_data=test_x)
+
+    # Reuse multiple heterogeneous learnwares using EnsemblePruningReuser
+    reuse_ensemble = EnsemblePruningReuser(
+        learnware_list=hetero_learnware_list, mode="regression"
+    )
+    reuse_ensemble.fit(val_x, val_y)
+    ensemble_pruning_predict_y = reuse_ensemble.predict(user_data=test_x)
 
 Reuse with Container
 =====================

docs/workflows/search.rst

@@ -13,7 +13,6 @@ The homogeneous search of helpful learnwares can be divided into two stages: sem
 
 .. code-block:: python
 
-    # generate BaseUserInfo(semantic_spec + stat_info)
     # generate BaseUserInfo(semantic_spec + stat_info)
     user_semantic = {
         "Data": {"Values": ["Table"], "Type": "Class"},
@@ -66,10 +65,14 @@ To activate heterogeneous learnware search, ``UserInfo`` should contain both sem
 - The feature dimension stated here should match with the feature dimension in the statistical specification.
 
 The following codes shows how to search for helpful heterogeneous learnwares from a market 
-``hetero_market`` for a user. The introduction of ``HeteroMarket`` is in `COMPONENTS: Hetero Market <../components/market.html>`_.
+``hetero_market`` for a user. The introduction of ``HeteroMarket`` is in `COMPONENTS: Hetero Market <../components/market.html#hetero-market>`_.
 
 .. code-block:: python
 
+  # initiate a Hetero Market
+  hetero_market = initiate_learnware_market(market_id="test_hetero", name="hetero")
+  
+  # user_semantic should meet the above requirements
   input_description = {
       "Dimension": 2,
       "Description": {
@@ -77,17 +80,13 @@ The following codes shows how to search for helpful heterogeneous learnwares fro
           "1": "leaf length",
       },
   }
-  
-  # user_semantic should meet the above requirements
   user_semantic = generate_semantic_spec(
       data_type="table",
       task_type="Classification",
       scenarios=["Business"],
       input_description=input_description,
   )
-  
   user_spec = generate_stat_spec(type="table", X=train_x)
-  
   user_info = BaseUserInfo(
       semantic_spec=user_semantic,
       stat_info={user_spec.type: user_spec}