Merge pull request neuroquery#1 from jeromedockes/update_urls

misc updates

Author: jeromedockes

README.md

@@ -13,7 +13,7 @@ projection on the [DiFuMo atlas](https://parietal-inria.github.io/DiFuMo/).
 Unlike NeuroQuery, NeuroQuery Image Search isn't hosted anywhere online. However
 we provide a [Voilà](https://github.com/voila-dashboards/voila) dashboard that
 can be run for example on `mybinder` by following [this
-link](https://mybinder.org/v2/gh/neuroquery/neuroquery_apps/master?urlpath=%2Fvoila%2Frender%2Fimage_search.py),
+link](https://mybinder.org/v2/gh/neuroquery/neuroquery_apps/main?urlpath=%2Fvoila%2Frender%2Fimage_search.py),
 or locally by cloning [this
 repository](https://github.com/neuroquery/neuroquery_apps).
 
@@ -58,6 +58,8 @@ optional arguments:
   --transform {absolute_value,identity,positive_part}
                         Transform to apply to the image. As NeuroQuery ignores the direction of activations by default the absolute value of the
                         input map is compared to activation patterns in the literature. (default: absolute_value)
+  --no_rescaling        Disable rescaling the similarities. By default they
+                        are mapped to the [0, 1] range. (default: False)
 ```
 
 ## As a Python package

src/neuroquery_image_search/_searching.py

@@ -119,6 +119,14 @@ def default(self, obj):
         return json.JSONEncoder.default(self, obj)
 
 
+def _rescale_similarities(similarities):
+    if (similarities == 0).all():
+        return similarities
+    similarities = similarities - similarities.min()
+    similarities = similarities / similarities.max()
+    return similarities
+
+
 class NeuroQueryImageSearch:
     """Search for studies and terms with activation maps similar to an image.
 
@@ -133,11 +141,17 @@ class NeuroQueryImageSearch:
     "image" (`nibabel.Nifti1Image` containing the input image).
 
     """
+
     def __init__(self):
         self.data = fetch_data()
 
     def __call__(
-        self, query_img, n_studies=50, n_terms=20, transform="absolute_value"
+        self,
+        query_img,
+        n_studies=50,
+        n_terms=20,
+        transform="absolute_value",
+        rescale_similarities=True,
     ):
         """Search for studies and terms with activation maps similar to an image
 
@@ -156,6 +170,9 @@ def __call__(
             helpful when comparing to the absolute value of the input image.
             "absolute_value" is the default.
 
+        rescale_similarities : if `True` (the default), similarities are
+            rescaled to span the range [0, 1]
+
         Returns
         -------
         results : dictionary with keys "image", "studies", "terms".
@@ -189,8 +206,9 @@ def __call__(
 
         similarities = self.data["studies_loadings"].dot(query)
         most_similar = np.argsort(similarities)[::-1][:n_studies]
-        if (similarities > 0).any():
-            similarities /= similarities.max()
+
+        if rescale_similarities:
+            similarities = _rescale_similarities(similarities)
         study_results = (
             self.data["studies_info"]
             .iloc[most_similar]
@@ -204,8 +222,8 @@ def __call__(
             1 + self.data["document_frequencies"]["document_frequency"].values
         )
         most_similar = np.argsort(similarities)[::-1][:n_terms]
-        if (similarities > 0).any():
-            similarities /= similarities.max()
+        if rescale_similarities:
+            similarities = _rescale_similarities(similarities)
         term_results = (
             self.data["document_frequencies"]
             .iloc[most_similar]
@@ -262,6 +280,12 @@ def _get_parser():
         "direction of activations by default the absolute value of the "
         "input map is compared to activation patterns in the literature.",
     )
+    parser.add_argument(
+        "--no_rescaling",
+        action="store_true",
+        help="Disable rescaling the similarities. "
+        "By default they are mapped to the [0, 1] range.",
+    )
     return parser
 
 
@@ -281,6 +305,7 @@ def image_search(args=None):
         n_studies=args.n_studies,
         n_terms=args.n_terms,
         transform=args.transform,
+        rescale_similarities=(not args.no_rescaling)
     )
     if args.output is None:
         results_to_html(results, image_name).open_in_browser()

tests/test_searching.py

@@ -47,7 +47,14 @@ def test_json_encoder():
 
 def test_neuroquery_image_search(fake_img):
     search = _searching.NeuroQueryImageSearch()
-    results = search(fake_img, 20, transform="identity")["studies"]
+
+    results = search(fake_img, 20, transform="identity", rescale_similarities=False)
+    assert results["studies"]["similarity"].max() != pytest.approx(1.)
+
+    results = search(fake_img, 20, transform="identity")
+    assert results["terms"]["similarity"].min() == pytest.approx(0.)
+    assert results["studies"]["similarity"].max() == pytest.approx(1.)
+    results = results["studies"]
     neg_img = image.new_img_like(fake_img, image.get_data(fake_img) * -1.0)
     neg_results = search(neg_img, 20, transform="identity")["studies"]
     assert (neg_results["pmid"].values == results["pmid"].values[::-1]).all()