From 737d93fbb750e1a2dc3313d723b19ad367161914 Mon Sep 17 00:00:00 2001
From: Diego Ceccarelli <diego@Mac-3.broadband>
Date: Sun, 15 Jun 2025 10:33:48 +0100
Subject: [PATCH 1/2] Add documentation to Run contructor and fix typing

---
 ranx/data_structures/run.py | 35 +++++++++++++++++++++++++++++++++--
 1 file changed, 33 insertions(+), 2 deletions(-)

diff --git a/ranx/data_structures/run.py b/ranx/data_structures/run.py
index 381ea81..f5342a8 100644
--- a/ranx/data_structures/run.py
+++ b/ranx/data_structures/run.py
@@ -1,7 +1,7 @@
 import gzip
 import os
 from collections import defaultdict
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Optional, Union
 
 import numpy as np
 import pandas as pd
@@ -43,8 +43,39 @@ class Run(object):
     run = Run()  # Creates an empty Run with no name
     ```
     """
+    metadata: Dict[str, Any]
+    scores: Dict[str, Dict[str, float]]
+    mean_scores: Dict[str, float]
+    std_scores: Dict[str, float]
 
-    def __init__(self, run: Dict[str, Dict[str, float]] = None, name: str = None):
+    def __init__(self, run: Union[None, Dict[str, Dict[str, float]]] = None, name: Union[None, str] = None):
+        """Initialize a Run object.
+
+        Args:
+            run (Dict[str, Dict[str, float]], optional): A dictionary mapping query IDs to dictionaries of document scores.
+                The inner dictionaries map document IDs to their relevance scores.
+                Example:
+                ```python
+                {
+                    "q_1": {
+                        "d_1": 1.5,
+                        "d_2": 2.6,
+                    },
+                    "q_2": {
+                        "d_3": 2.8,
+                        "d_2": 1.2,
+                        "d_5": 3.1,
+                    },
+                }
+                ```
+                If None, creates an empty Run. Defaults to None.
+            name (str, optional): A name for the run (e.g., "bm25", "t5", etc.). Defaults to None.
+
+        Note:
+            - Query IDs and document IDs can be any string
+            - Scores must be numeric values
+            - The run will be automatically sorted by score in descending order
+        """
         if run is None:
             self.run = TypedDict.empty(
                 key_type=types.unicode_type,

From 0e89a05d7830641d44efe261316cf556324b90f9 Mon Sep 17 00:00:00 2001
From: Diego Ceccarelli <diego.ceccarelli@gmail.com>
Date: Sun, 15 Jun 2025 10:35:42 +0100
Subject: [PATCH 2/2] Remove unused import

---
 ranx/data_structures/run.py | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/ranx/data_structures/run.py b/ranx/data_structures/run.py
index f5342a8..bc3bb4d 100644
--- a/ranx/data_structures/run.py
+++ b/ranx/data_structures/run.py
@@ -1,7 +1,7 @@
 import gzip
 import os
 from collections import defaultdict
-from typing import Any, Dict, List, Optional, Union
+from typing import Any, Dict, List, Union
 
 import numpy as np
 import pandas as pd
@@ -43,12 +43,17 @@ class Run(object):
     run = Run()  # Creates an empty Run with no name
     ```
     """
+
     metadata: Dict[str, Any]
     scores: Dict[str, Dict[str, float]]
     mean_scores: Dict[str, float]
     std_scores: Dict[str, float]
 
-    def __init__(self, run: Union[None, Dict[str, Dict[str, float]]] = None, name: Union[None, str] = None):
+    def __init__(
+        self,
+        run: Union[None, Dict[str, Dict[str, float]]] = None,
+        name: Union[None, str] = None,
+    ):
         """Initialize a Run object.
 
         Args: