[DOC] search doc(Hetero Search)

docs/workflows/search.rst

@@ -2,111 +2,97 @@
 Learnwares Search
 ============================================================
 
-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.
+``Learnware Searcher`` is a key component of ``Learnware Market`` that identifies and recommends helpful learnwares to users according to their ``UserInfo``. Based on whether the returned learnware dimensions are consistent with user tasks, the searchers can be divided into two categories: homogeneous searchers and heterogeneous searchers. 
+
+All the searchers are implemented as a subclass of ``BaseSearcher``. When initializing, you should assign a ``organizer`` to it. The introduction of ``organizer`` is shown in `COMPONENTS: Market - Framework <../components/market.html>`_. Then these searchers can be called with ``UserInfo`` and return ``SearchResults``.
+
 
 Homo 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.
+The homogeneous search of helpful learnwares can be divided into two stages: semantic specification search and statistical specification search. Both of them needs ``BaseUserInfo`` as input. The following codes shows how to use the searcher to search for helpful learnwares from a market ``easy_market`` for a user. The introduction of ``EasyMarket`` is in `COMPONENTS: Market <../components/market.html>`_.
 
 .. code-block:: python
 
-    # An example of user_semantic
+    # generate BaseUserInfo(semantic_spec + stat_info)
     user_semantic = {
-        "Data": {"Values": ["Image"], "Type": "Class"},
-        "Task": {"Values": ["Classification"], "Type": "Class"},
-        "Library": {"Values": ["Scikit-learn"], "Type": "Tag"},
-        "Scenario": {"Values": ["Education"], "Type": "Class"},
+        "Data": {"Values": ["Table"], "Type": "Class"},
+        "Task": {"Values": ["Regression"], "Type": "Class"},
+        "Library": {"Values": ["Scikit-learn"], "Type": "Class"},
+        "Scenario": {"Values": ["Business"], "Type": "Tag"},
         "Description": {"Values": "", "Type": "String"},
-        "Name": {"Values": "digits", "Type": "String"},
+        "Name": {"Values": "", "Type": "String"},
+        "Input": {"Dimension": 82, "Description": {},},
+        "Output": {"Dimension": 1, "Description": {},}, 
+        "License": {"Values": ["MIT"], "Type": "Class"},
     }
-
-
-.. image:: ../_static/img/semantic_spec.png
-   :align: center
-
-
-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 `Learnware Preparation <./submit>`_.
-
-
-
-Semantic Specification Search
--------------------------------
-To search for learnwares that fit your task purpose, 
-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 leaarnwares whose models solve tasks similar to your requirements. 
-
-.. code-block:: python
-
-    # construct user_info which includes semantic specification for searching learnware
-    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) 
-
-    # single_learnware_list is the learnware list by semantic specification searching
-    print(single_learnware_list)
-
-In semantic specification search, we go through all learnwares in the market to compare their semantic specifications with the user's one, and return all the learnwares that pass through the comparation. When comparing two learnwares' semantic specifications, we design different ways for different semantic keys:
-
-- For semantic keys with type 'Class', they are matched only if they have the same value.
-
-- For semantic keys with type 'Tag', they are matched only if they have nonempty intersections.
-
-- For the user's input in the search box, it matchs with a learnware's semantic specification only if it's a substring of its 'Name' or 'Description'. All the strings are converted to the lower case before matching.
-
-- When a key value is missing, it will not participate in the match. The user could upload no semantic specifications if he wants.
-
-Statistical Specification Search
----------------------------------
-
-If you choose to provide your own statistical specification file ``stat.json``, 
-the Learnware Market can perform a more accurate leanware selection from 
-the learnwares returned by the previous step. This second-stage search is based on statistical information and returns one or more learnwares that are most likely to be helpful for your task. 
-
-For example, the following code is designed to work with Reduced Kernel Mean Embedding (RKME) as a statistical specification:
-
-.. code-block:: python
-
-    import learnware.specification as specification
-
-    user_spec = specification.RKMETableSpecification()
-    user_spec.load(os.path.join("rkme.json"))
+    user_spec = generate_rkme_table_spec(X=x)
     user_info = BaseUserInfo(
-        semantic_spec=user_semantic, stat_info={"RKMETableSpecification": user_spec}
+        semantic_spec=user_semantic, 
+        stat_info={"RKMETableSpecification": user_spec}
     )
-    (sorted_score_list, single_learnware_list,
-        mixture_score, mixture_learnware_list) = easy_market.search_learnware(user_info)
 
-    # sorted_score_list is the learnware scores based on MMD distances, sorted in descending order
-    print(sorted_score_list) 
+    # search the market for the user
+    search_result = easy_market.search_learnware(user_info)
+
+    # search result: single_result
+    single_result = search_result.get_single_results()
+    print(f"single model num: {len(single_result)}, 
+        max_score: {single_result[0].score}, 
+        min_score: {single_result[-1].score}"
+    )
+    
+    # search result: multiple_result
+    multiple_result = search_result.get_multiple_results()
+    mixture_id = " ".join([learnware.id for learnware in multiple_result[0].learnwares])
+    print(f"mixture_score: {multiple_result[0].score}, mixture_learnwares: {mixture_id}")
 
-    # single_learnware_list is the learnwares sorted in descending order based on their scores
-    print(single_learnware_list)
 
-    # mixture_learnware_list is the learnwares whose mixture is helpful for your task
-    print(mixture_learnware_list) 
+Hetero Search
+======================
 
-    # mixture_score is the score of the mixture of learnwares
-    print(mixture_score)
+For table-based user tasks, 
+homogeneous searchers like ``EasySearcher`` fail to recommend learnwares when no table learnware matches the user task's feature dimension, returning empty results.
+To enhance functionality, ``learnware`` package includes the heterogeneous learnware search feature, whose processions is as follows: 
 
-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.
+- Learnware markets such as ``Hetero Market`` integrate different specification islands into a unified "specification world" by assigning system-level specifications to all learnwares. This allows heterogeneous searchers like ``HeteroSearcher`` to find helpful learnwares from all available table learnwares.
+- Searchers assign system-level specifications to users based on ``UserInfo``'s statistical specification, using methods provided by corresponding organizers. In ``Hetero Market``, for example, ``HeteroOrganizer.generate_hetero_map_spec`` generates system-level specifications for users.
+- Finally searchers conduct statistical specification search across the "specification world". User's system-level specification will guide the searcher in pinpointing helpful heterogeneous learnwares.
 
+To activate heterogeneous learnware search, ``UserInfo`` should contain both semantic and statistical specifications. What's more, the semantic specification should meet the following requirements: 
 
-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 task type should be ``Classification`` or ``Regression``.
+- The data type should be ``Table``.
+- It should include description for at least one feature dimension.
+- The feature dimension stated here should match with the feature dimension in the statistical specification.
 
-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 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>`_.
 
-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.
+.. code-block:: python
 
-Hetero Search
-======================
+  input_description = {
+      "Dimension": 2,
+      "Description": {
+          "0": "leaf width",
+          "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}
+  )
+
+  # search for heterogeneous learnwares in hetero_market
+  search_result = hetero_market.search_learnware(user_info)