first draft

README.md

@@ -1,11 +1,10 @@
 ---
 title: map
-datasets:
--  
 tags:
 - evaluate
 - metric
-description: "TODO: add a description here"
+description: "This is the mean average precision (map) metric for retrieval systems.
+It is the average of the precision scores computer after each relevant document is got. You can refer to [here](https://amenra.github.io/ranx/metrics/#mean-average-precision)"
 sdk: gradio
 sdk_version: 3.19.1
 app_file: app.py
@@ -14,37 +13,43 @@ pinned: false
 
 # Metric Card for map
 
-***Module Card Instructions:*** *Fill out the following subsections. Feel free to take a look at existing metric cards if you'd like examples.*
-
 ## Metric Description
-*Give a brief overview of this metric, including what task(s) it is usually used for, if any.*
+This is the mean average precision (map) metric for retrieval systems.
+It is the average of the precision scores computer after each relevant document is got. You can refer to [here](https://amenra.github.io/ranx/metrics/#mean-average-precision)
 
 ## How to Use
-*Give general statement of how to use the metric*
-
-*Provide simplest possible example for using the metric*
-
+```python
+>>> my_new_module = evaluate.load("map")
+>>> references= [json.dumps({"q_1":{"d_1":1, "d_2":2} }), 
+             json.dumps({"q_2":{"d_2":1, "d_3":2, "d_5":3}})] 
+>>> predictions = [json.dumps({"q_1": { "d_1": 0.9, "d_2": 0.8}}),
+         json.dumps({"q_2": {"d_2": 0.9, "d_1": 0.8, "d_5": 0.7, "d_3": 0.3}})]
+>>> results = my_new_module.compute(references=references, predictions=predictions)
+>>> print(results)
+{'map': 0.902777}
+```
 ### Inputs
-*List all input arguments in the format below*
-- **input_field** *(type): Definition of input, with explanation if necessary. State any default value(s).*
+- **predictions:** a list of dictionaries where each dictionary consists of document relevancy scores produced by the model for a given query. One dictionary per query. The dictionaries should be converted to string. 
+- **references:** a lift of list of dictionaries where each dictionary consists of the relevant order for the documents for a given query in a sorted relevancy order. The dictionaries should be converted to string.
 
 ### Output Values
+- **map (`float`):** mean average precision score. Minimum possible value is 0. Maximum possible value is 1.0
 
-*Explain what this metric outputs and provide an example of what the metric output looks like. Modules should return a dictionary with one or multiple key-value pairs, e.g. {"bleu" : 6.02}*
-
-*State the range of possible values that the metric's output can take, as well as what in that range is considered good. For example: "This metric can take on any value between 0 and 100, inclusive. Higher scores are better."*
-
-#### Values from Popular Papers
-*Give examples, preferrably with links to leaderboards or publications, to papers that have reported this metric, along with the values they have reported.*
-
-### Examples
-*Give code examples of the metric being used. Try to include examples that clear up any potential ambiguity left from the metric description above. If possible, provide a range of examples that show both typical and atypical results, as well as examples where a variety of input parameters are passed.*
 
 ## Limitations and Bias
 *Note any known limitations or biases that the metric has, with links and references if possible.*
 
 ## Citation
-*Cite the source where this metric was introduced.*
-
-## Further References
-*Add any useful further references.*
+```bibtex
+@inproceedings{ranx,
+  author       = {Elias Bassani},
+  title        = {ranx: {A} Blazing-Fast Python Library for Ranking Evaluation and Comparison},
+  booktitle    = {{ECIR} {(2)}},
+  series       = {Lecture Notes in Computer Science},
+  volume       = {13186},
+  pages        = {259--264},
+  publisher    = {Springer},
+  year         = {2022},
+  doi          = {10.1007/978-3-030-99739-7\_30}
+}
+```

map.py

@@ -11,58 +11,62 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-"""TODO: Add a description here."""
+"""Mean average precision metric"""
 
 import evaluate
 import datasets
+import json
+from ranx import Qrels, Run
+from ranx import evaluate as ran_evaluate
 
 
-# TODO: Add BibTeX citation
 _CITATION = """\
-@InProceedings{huggingface:module,
-title = {A great new module},
-authors={huggingface, Inc.},
-year={2020}
+@inproceedings{ranx,
+  author       = {Elias Bassani},
+  title        = {ranx: {A} Blazing-Fast Python Library for Ranking Evaluation and Comparison},
+  booktitle    = {{ECIR} {(2)}},
+  series       = {Lecture Notes in Computer Science},
+  volume       = {13186},
+  pages        = {259--264},
+  publisher    = {Springer},
+  year         = {2022},
+  doi          = {10.1007/978-3-030-99739-7\_30}
 }
 """
 
-# TODO: Add description of the module here
 _DESCRIPTION = """\
-This new module is designed to solve this great ML task and is crafted with a lot of care.
+This is the mean average precision (map) metric for retrieval systems.
+It is the average of the precision scores computer after each relevant document is got. You can refer to [here](https://amenra.github.io/ranx/metrics/#mean-average-precision)
 """
 
 
-# TODO: Add description of the arguments of the module here
 _KWARGS_DESCRIPTION = """
-Calculates how good are predictions given some references, using certain scores
 Args:
-    predictions: list of predictions to score. Each predictions
-        should be a string with tokens separated by spaces.
-    references: list of reference for each prediction. Each
-        reference should be a string with tokens separated by spaces.
+    predictions: dictionary of dictionaries where each dictionary consists of document relevancy scores produced by the model for a given query 
+        One dictionary per query.  
+    references: List of list of strings where each lists consists of the relevant document names for a given query in a sorted relevancy order.
+        The outer list is sorted from query one to n.
 Returns:
-    accuracy: description of the first score,
-    another_score: description of the second score,
+    map (`float`): mean average precision score. Minimum possible value is 0. Maximum possible value is 1.0
 Examples:
-    Examples should be written in doctest format, and should illustrate how
-    to use the function.
-
-    >>> my_new_module = evaluate.load("my_new_module")
-    >>> results = my_new_module.compute(references=[0, 1], predictions=[0, 1])
+   
+    >>> my_new_module = evaluate.load("map")
+    >>> results = my_new_module.compute(
+        references=[
+            ["d_1", "d_2"],
+            ["d_2", "d_3", "d_5"]
+        ]
+    predictions={ 
+        "q_1": { "d_1": 0.9, "d_2": 0.8, },
+        "q_2": { "d_2": 0.9, "d_1": 0.8, "d_5": 0.7, "d_3": 0.3} }
+)
     >>> print(results)
-    {'accuracy': 1.0}
+    {'map': 0.902777}
 """
 
-# TODO: Define external resources urls if needed
-BAD_WORDS_URL = "http://url/to/external/resource/bad_words.txt"
-
-
 @evaluate.utils.file_utils.add_start_docstrings(_DESCRIPTION, _KWARGS_DESCRIPTION)
 class map(evaluate.Metric):
-    """TODO: Short description of my evaluation module."""
-
     def _info(self):
-        # TODO: Specifies the evaluate.EvaluationModuleInfo object
         return evaluate.MetricInfo(
             # This is the description that will appear on the modules page.
             module_type="metric",
@@ -71,25 +75,31 @@ class map(evaluate.Metric):
             inputs_description=_KWARGS_DESCRIPTION,
             # This defines the format of each prediction and reference
             features=datasets.Features({
-                'predictions': datasets.Value('int64'),
-                'references': datasets.Value('int64'),
+                'predictions':  datasets.Value("string"), #list[dict],
+                'references':  datasets.Value("string")#datasets.Sequence(datasets.Sequence(datasets.Value("string"))), #list[list[str]],
             }),
             # Homepage of the module for documentation
-            homepage="http://module.homepage",
-            # Additional links to the codebase or references
-            codebase_urls=["http://github.com/path/to/codebase/of/new_module"],
-            reference_urls=["http://path.to.reference.url/new_module"]
+            reference_urls=["https://amenra.github.io/ranx/"]
         )
 
-    def _download_and_prepare(self, dl_manager):
-        """Optional: download external resources useful to compute the scores"""
-        # TODO: Download external resources if needed
-        pass
-
     def _compute(self, predictions, references):
         """Returns the scores"""
-        # TODO: Compute the different scores of the module
-        accuracy = sum(i == j for i, j in zip(predictions, references)) / len(predictions)
+        preds = {}
+        refs = {}
+        for pred in predictions:
+            preds = preds | json.loads(pred)
+        for ref in references:
+            refs = refs | json.loads(ref)
+        
+        run = Run(preds)
+        """gt_dict = {}
+        for i in range(len(references)):
+            per_query_gt = {}
+            for rank in range(len(references[i])):
+                per_query_gt[references[i][rank]] = rank+1
+            gt_dict[f"q_{i+1}"] = per_query_gt"""
+        qrels = Qrels(refs)
+        map_score = ran_evaluate(qrels, run, "map")
         return {
-            "accuracy": accuracy,
+            "map": map_score,
         }

requirements.txt

@@ -1 +1,2 @@
-git+https://github.com/huggingface/evaluate@main
+git+https://github.com/huggingface/evaluate@main
+ranx==0.3.19