Add convenience function Grounder.ground_best

gilda/grounder.py

@@ -181,6 +181,55 @@ def _score_namespace(self, term) -> int:
         except ValueError:
             return 0
 
+    def ground_best(
+        self,
+        raw_str: str,
+        context: Optional[str] = None,
+        organisms: Optional[List[str]] = None,
+        namespaces: Optional[List[str]] = None,
+    ) -> Optional["ScoredMatch"]:
+        """Return the best scored grounding for a given raw string.
+
+        Parameters
+        ----------
+        raw_str : str
+            A string to be grounded with respect to the set of Terms that the
+            Grounder contains.
+        context : Optional[str]
+            Any additional text that serves as context for disambiguating the
+            given entity text, used if a model exists for disambiguating the
+            given text.
+        organisms : Optional[List[str]]
+            An optional list of organism identifiers defining a priority
+            ranking among organisms, if genes/proteins from multiple
+            organisms match the input. If not provided, the default
+            ['9606'] i.e., human is used.
+        namespaces : Optional[List[str]]
+            A list of namespaces to restrict matches to. This will apply to
+            both the primary namespace of a matched term, to any subsumed
+            matches, and to the source namespaces of terms if they were
+            created using cross-reference mappings. By default, no
+            restriction is applied.
+
+        Returns
+        -------
+        Optional[gilda.grounder.ScoredMatch]
+            The best ScoredMatch returned by :meth:`ground` if any are returned,
+            otherwise None.
+        """
+        scored_matches = self.ground(
+            raw_str=raw_str,
+            context=context,
+            organisms=organisms,
+            namespaces=namespaces,
+        )
+        if scored_matches:
+            # Because of the way the ground() function is implemented,
+            # the first element is guaranteed to have the best score
+            # (after filtering by namespace)
+            return scored_matches[0]
+        return None
+
     def ground(self, raw_str, context=None, organisms=None,
                namespaces=None):
         """Return scored groundings for a given raw string.

gilda/tests/test_grounder.py

@@ -28,6 +28,25 @@ def test_grounder():
     assert appreq(scores[0].score, 0.9936), scores
 
 
+def test_ground_best():
+    score = gr.ground_best('kras')
+    assert score is not None
+    assert appreq(score.score, 0.9845), score
+    score = gr.ground_best('k-ras')
+    assert score is not None
+    assert appreq(score.score, 0.9936), score
+    score = gr.ground_best('KRAS')
+    assert score is not None
+    assert appreq(score.score, 1.0), score
+    score = gr.ground_best('bRaf')
+    assert score is not None
+    assert appreq(score.score, 0.9936), score
+
+    # Check that when no grounding
+    # is possible, none is returned
+    assert gr.ground_best("nope nope nope") is None
+
+
 def test_grounder_bug():
     # Smoke test to make sure the 'NA' entry in grounding terms doesn't get
     # turned into a None