Merge branch 'doc' of ssh://git.nju.edu.cn/learnware/learnware-market into doc

docs/workflow/Identify helpful learnwares.rst

@@ -2,17 +2,51 @@
 Identify Helpful Learnwares
 ============================================================
 
+When a user comes with her requirements, the market should identify helpful learnwares and recommend them to the user.
+The search of helpful learnwares is based on the user information, and can be divided into two stages: semantic specification search and statistical specification search.
+
+User information
+-------------------------------
+The user should provide her requirements in ``BaseUserInfo``. The class ``BaseUserInfo`` consists of user's semantic specification ``user_semantic`` and statistical information ``stat_info``. 
+
+The semantic specification ``user_semantic`` is stored in a ``dict``, with keywords 'Data', 'Task', 'Library', 'Scenario', 'Description' and 'Name'. An example is shown below, and you could choose their values according to the figure. For the keys of type 'Class, you should choose one ilegal value; for the keys of type 'Tag', you can choose one or more values; for the keys of type 'String', you should provide a string; the key 'Description' is used in learnwares' semantic specifications and is ignored in user semantic specification; the values of all these keys can be empty if the user have no idea of them.
+
+.. code-block:: python
+
+    # An example of user_semantic
+    user_semantic = {
+        "Data": {"Values": ["Image"], "Type": "Class"},
+        "Task": {"Values": ["Classification"], "Type": "Class"},
+        "Library": {"Values": ["Scikit-learn"], "Type": "Tag"},
+        "Scenario": {"Values": ["Education"], "Type": "Class"},
+        "Description": {"Values": "", "Type": "String"},
+        "Name": {"Values": "digits", "Type": "String"},
+    }
+
+.. _semantic_specification:
+
+.. figure: ..\_static\img\semantic_spec.png
+   :alt: Semantic Specification
+   :align: center
+
+引用方式 :ref:`semantic_specification` 。
+
+
+The user's statistical information ``stat_info`` is stored in a ``json`` file, e.g., ``stat.json``. The generation of this file is seen in `这是一个语义规约生成的链接`_.
+
+
+
 Semantic Specification Search
 -------------------------------
 To search for learnwares that fit your task purpose, 
-you should first provide a semantic specification ``user_semantic`` that describes the characteristics of your task.
+the user should first provide a semantic specification ``user_semantic`` that describes the characteristics of your task.
 The Learnware Market will perform a first-stage search based on ``user_semantic``,
 identifying potentially helpful leranwares whose models solve tasks similar to your requirements. 
 
 .. code-block:: python
 
     # construct user_info which includes semantic specification for searching learnware
-    user_info = BaseUserInfo(id="user", semantic_spec=semantic_spec)
+    user_info = BaseUserInfo(semantic_spec=semantic_spec)
 
     # search_learnware performs semantic specification search if user_info doesn't include a statistical specification
     _, single_learnware_list, _ = easy_market.search_learnware(user_info) 
@@ -44,9 +78,9 @@ For example, the following code is designed to work with Reduced Kernel Mean Emb
     import learnware.specification as specification
 
     user_spec = specification.rkme.RKMEStatSpecification()
-    user_spec.load(os.path.join(unzip_path, "rkme.json"))
+    user_spec.load(os.path.join("rkme.json"))
     user_info = BaseUserInfo(
-        id="user", semantic_spec=user_semantic, stat_info={"RKMEStatSpecification": user_spec}
+        semantic_spec=user_semantic, stat_info={"RKMEStatSpecification": user_spec}
     )
     (sorted_score_list, single_learnware_list,
         mixture_score, mixture_learnware_list) = easy_market.search_learnware(user_info)
@@ -63,9 +97,14 @@ For example, the following code is designed to work with Reduced Kernel Mean Emb
     # mixture_score is the score of the mixture of learnwares
     print(mixture_score)
 
+The return values of statistical specification search are ``sorted_score_list``, ``single_learnware_list``, ``mixture_score`` and ``mixture_learnware_list``.
+``sorted_score_list`` and ``single_learnware_list`` are the ranking of each single learnware and the corresponding scores. We return at least 15 learnwares unless there're no enough ones. If there are more than 15 matched learnwares, the ones with scores less than 50 will be ignored.
+``mixture_score`` and ``mixture_learnware_list`` are the chosen mixture learnwares and the corresponding score. At most 5 learnwares will be chosen, whose mixture may have a relatively good performance on the user's task.
+
+
 The statistical specification search is done in the following way.
 We first filter by the dimension of RKME specifications; only those with the same dimension with the user's will enter the subsequent stage.
 
-The single_learnware_list is calculated using the distances between two RKMEs. The greater the distance from the user's RKME, the lower the score is. The learnwares with very low scores will not be returned, unless the number of matching leanwares is smaller than a set threshold.
+The single_learnware_list is calculated using the distances between two RKMEs. The greater the distance from the user's RKME, the lower the score is. 
 
 The mixture_learnware_list is calculated in a greedy way. Each time we choose a learnware to make their mixture closer to the user's RKME. Specifically, each time we go through all the left learnwares to find the one whose combination with chosen learnwares could minimize the distance between their mixture's RKME and the user's RKME. The mixture weight is calculated by minimizing the RKME distance, which is solved by quadratic programming. If the distance become larger or the number of chosen learnwares reaches a threshold, the process will end and the chosen learnware and weight list will return.

docs/workflow/reuse.rst

@@ -3,17 +3,26 @@ Getting Started-Workflow-Reuse learnware
 ==========================================
 
 This part introduces two baseline methods for reusing a given list of learnwares, namely ``JobSelectorReuser`` and ``AveragingReuser``.
-Instead of training a model from scratch, you can easily reuse a list of learnwares ``learnware_list (List[Learnware])`` to make predictions on your own data ``test_data (numpy.ndarray or torch.Tensor)`` in the following way:
+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``).
+
+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.
 
 .. code-block:: python
 
+    from sklearn.datasets import load_digits
     from learnware.learnware import JobSelectorReuser, AveragingReuser
 
-    # using jobselector reuser to reuse the searched learnwares to make prediction
+    # Load user data
+    X, y = load_digits(return_X_y=True)
+    test_data = X
+
+    # 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
     reuse_job_selector = JobSelectorReuser(learnware_list=learnware_list)
     job_selector_predict_y = reuse_job_selector.predict(user_data=test_data)
 
-    # using averaging ensemble reuser to reuse the searched learnwares to make prediction
+    # 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)
 
@@ -29,7 +38,7 @@ There are three parameters required to initialize the class:
 - ``herding_num``: An optional integer that specifies the number of items to herd, which defaults to 1000 if not provided.
 - ``use_herding``: A boolean flag indicating whether to use kernel herding.
 
-The job selector is essentially a multi-class classifier :math:`g(\boldsymbol{x}\rightarrow \mathcal{I})` with :math:`\mathcal{I}=\{1,\ldots, C\}`.
+The job selector is essentially a multi-class classifier :math:`g(\boldsymbol{x}):\mathcal{X}\rightarrow \mathcal{I}` with :math:`\mathcal{I}=\{1,\ldots, C\}`, where :math:`C` is the size of ``learnware_list``.
 Given a testing sample :math:`\boldsymbol{x}`, the ``JobSelectorReuser`` predicts it by using the :math:`g(\boldsymbol{x})`-th learnware in ``learnware_list``.
 If ``use_herding`` is set to false, the ``JobSelectorReuser`` uses data points in each learware's RKME spefication with the corresponding learnware index to train a job selector.
 If ``use_herding`` is true, the algorithm estimates the mixture weight based on RKME specifications and raw user data, uses the weight to generate ``herding_num`` auxiliary data points mimicking the user distribution through the kernel herding method, and learns a job selector on these data.