feat: new parameter 'criteria' in query_region and query_hips

ManonMarchand · bsipocz · commit 0bed33f3e730 · 2025-01-22T15:00:15.000-08:00
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -31,12 +31,12 @@ mocserver
 - ``return_moc`` now allows to ask for a Time-MOC or a Space-Time MOC rather than only
   Space-MOCs [#3139]
 
-- Fix query by MOC that would write a file ``moc.fits`` where the method was executed
-  in overwriting mode (potentially deleting data if there was a conflicting file) [#3139]
+- Fix query by MOC that would write a file ``moc.fits`` where the method was executed in
+  overwriting mode (potentially deleting data if there was a conflicting file) [#3139]
 
-- Returned tables now have a default list of fields instead of the > 130 columns returned
-  previously. The full list of fields can be displayed with the new method
-  ``MOCServer.list_fields`` [#3139]
+- [:warning: BREAKING] Returned tables now have a default list of fields instead of the
+  > 130 columns returned previously. The full list of fields can be displayed with the
+  new method ``MOCServer.list_fields`` [#3139]
 
 - Add ``casesensitive`` parameter in the queries (previously, this was hardcoded
   to ``True``) [#3139]
@@ -48,6 +48,9 @@ mocserver
 - Add ``query_hips`` method, which is convenient to filter only Hierarchical progressive
   surveys [#3139]
 
+- New parameter ``criteria`` in ``query_region`` and ``query_hips`` that has the same
+  use than ``meta_data`` in the deprecated method ``find_datasets`` [#3139]
+
 simbad
 ^^^^^^
 
@@ -61,6 +64,7 @@ simbad
 
 - Fixed non existing flux filters as votable fields would fail silently [#3186]
 
+
 Infrastructure, Utility and Other Changes and Additions
 -------------------------------------------------------
 
diff --git a/astroquery/mocserver/core.py b/astroquery/mocserver/core.py
@@ -42,7 +42,7 @@ def __init__(self):
     def query_region(
         self, region=None,
         *,
-        meta_data=None,
+        criteria=None,
         intersect="overlaps",
         return_moc=None,
         max_norder=None,
@@ -63,8 +63,8 @@ def query_region(
             The region to query the MOCServer with. Note that this can also be a
             space-time region with the Time-MOCs and Space-Time-MOCs.
             Defaults to None, which means that the search will be on the whole sky.
-        meta_data : str
-            Algebraic expression to select the datasets.
+        criteria : str
+            Expression to select the datasets.
             Examples of expressions can be found `on the mocserver's examples page
             <http://alasky.unistra.fr/MocServer/example>`_.
             Example: "ID=*HST*" will return datasets with HST in their ID column. The
@@ -114,7 +114,7 @@ def query_region(
 
         """
         response = self.query_async(
-            meta_data=meta_data,
+            criteria=criteria,
             region=region,
             intersect=intersect,
             return_moc=return_moc,
@@ -133,7 +133,7 @@ def query_region(
     def query_hips(
         self,
         *,
-        meta_data=None,
+        criteria=None,
         region=None,
         intersect="overlaps",
         return_moc=None,
@@ -150,8 +150,8 @@ def query_hips(
 
         Parameters
         ----------
-        meta_data : str
-            Algebraic expression to select the datasets.
+        criteria : str
+            Expression to select the datasets.
             Examples of expressions can be found `on the mocserver's examples page
             <http://alasky.unistra.fr/MocServer/example>`_.
             Example: "ID=*HST*" will return datasets with HST in their ID column. The
@@ -204,12 +204,12 @@ def query_hips(
             union of the MOCs from all the retrieved data-sets.
 
         """
-        if meta_data:
-            meta_data = f"({meta_data})&&hips_frame=*"
+        if criteria:
+            criteria = f"({criteria})&&hips_frame=*"
         else:
-            meta_data = "hips_frame=*"
+            criteria = "hips_frame=*"
         return self.query_region(
-            meta_data=meta_data,
+            criteria=criteria,
             region=region,
             intersect=intersect,
             return_moc=return_moc,
@@ -224,7 +224,9 @@ def query_hips(
         )
 
     @deprecated(since="v0.4.9",
-                alternative="query_region")
+                message="'find_datasets' is replaced by 'query_region' which has a new "
+                        "parameter 'criteria' that accepts the expressions that "
+                        "'meta_data' was accepting.")
     def find_datasets(
         self, meta_data,
         *,
@@ -245,7 +247,7 @@ def find_datasets(
         Parameters
         ----------
         meta_data : str
-            Algebraic expression to select the datasets.
+            Expression to select the datasets.
             Examples of expressions can be found `on the mocserver's examples page
             <http://alasky.unistra.fr/MocServer/example>`_.
             Example: "ID=*HST*" will return datasets with HST in their ID column. The
@@ -299,7 +301,7 @@ def find_datasets(
 
         """
         return self.query_region(
-            meta_data=meta_data,
+            criteria=meta_data,
             region=region,
             intersect=intersect,
             return_moc=return_moc,
@@ -317,7 +319,7 @@ def query_async(
         self,
         *,
         region=None,
-        meta_data=None,
+        criteria=None,
         return_moc=None,
         max_norder=None,
         fields=None,
@@ -332,8 +334,8 @@ def query_async(
 
         Parameters
         ----------
-        meta_data : str
-            Algebraic expression to select the datasets.
+        criteria : str
+            Expression to select the datasets.
             Examples of expressions can be found `on the mocserver's examples page
             <http://alasky.unistra.fr/MocServer/example>`_.
             Example: "ID=*HST*" will return datasets with HST in their ID column. The
@@ -385,7 +387,7 @@ def query_async(
 
         """
         request_payload = _args_to_payload(
-            meta_data=meta_data,
+            criteria=criteria,
             return_moc=return_moc,
             max_norder=max_norder,
             fields=fields,
@@ -491,7 +493,7 @@ def list_coordinate_systems(self):
             The list of coordinate systems currently available in the MOC Server
 
         """
-        frames = list(set(self.query_region(meta_data="hips_frame=*",
+        frames = list(set(self.query_region(criteria="hips_frame=*",
                                             fields=["ID", "hips_frame"],
                                             coordinate_system=None)["hips_frame"]))
         # `C` is a special case that corresponds to both equatorial and galactic frames
@@ -502,7 +504,7 @@ def list_coordinate_systems(self):
 
 def _args_to_payload(
     *,
-    meta_data=None,
+    criteria=None,
     return_moc=None,
     max_norder=None,
     fields=None,
@@ -566,8 +568,8 @@ def _args_to_payload(
                 f" or 'mocpy.STMOC', but is of type '{type(region)}'."
             )
 
-    if meta_data:
-        request_payload.update({"expr": meta_data})
+    if criteria:
+        request_payload.update({"expr": criteria})
 
     if max_rec:
         request_payload.update({"MAXREC": str(max_rec)})
diff --git a/astroquery/mocserver/tests/test_mocserver.py b/astroquery/mocserver/tests/test_mocserver.py
@@ -92,7 +92,7 @@ def test_query_hips():
     payload = MOCServer.query_hips(get_query_payload=True)
     assert payload["expr"] == "hips_frame=*"
     # with meta
-    payload = MOCServer.query_hips(meta_data="TEST", get_query_payload=True)
+    payload = MOCServer.query_hips(criteria="TEST", get_query_payload=True)
     assert payload["expr"] == "(TEST)&&hips_frame=*"
 
 
@@ -138,7 +138,7 @@ def test_list_fields():
 def _mock_list_coordinate_systems(monkeypatch):
     # This list changes upstream. To regenerate it, do:
     # >>> from astroquery.mocserver import MOCServer
-    # >>> hips_frames = MOCServer.query_region(meta_data="hips_frame=*",
+    # >>> hips_frames = MOCServer.query_region(criteria="hips_frame=*",
     # ...                                       fields=["hips_frame"],
     # ...                                       coordinate_system=None, max_rec=100)
     # >>> hips_frames.remove_column("ID")
@@ -180,54 +180,54 @@ def test_intersect_param(intersect):
 
 def test_fields():
     # check that it works for a single field
-    payload = MOCServer.query_region(meta_data="", fields="ID", get_query_payload=True)
+    payload = MOCServer.query_region(criteria="", fields="ID", get_query_payload=True)
     assert payload["fields"] == "ID"
     # as well as more fields
     payload = MOCServer.query_region(
-        meta_data="", fields=["ID", "hips_properties"], get_query_payload=True
+        criteria="", fields=["ID", "hips_properties"], get_query_payload=True
     )
     # cannot test the order, due to the use of set
     assert "hips_properties" in payload["fields"] and "ID" in payload["fields"]
     # ID has to be in fields
     payload = MOCServer.query_region(
-        meta_data="", fields="hips_body", get_query_payload=True
+        criteria="", fields="hips_body", get_query_payload=True
     )
     assert "ID" in payload["fields"]
 
 
 def test_caseinsensitive():
     # casesensitive was hardcoded to true until astroquery 0.4.8. It is now an option
-    payload = MOCServer.query_region(meta_data="", fields="ID", get_query_payload=True)
+    payload = MOCServer.query_region(criteria="", fields="ID", get_query_payload=True)
     assert payload["casesensitive"] == "false"
     payload = MOCServer.query_region(
-        meta_data="", fields="ID", get_query_payload=True, casesensitive=True
+        criteria="", fields="ID", get_query_payload=True, casesensitive=True
     )
     assert payload["casesensitive"] == "true"
 
 
 def test_maxrec():
-    payload = MOCServer.query_region(meta_data="", max_rec=100, get_query_payload=True)
+    payload = MOCServer.query_region(criteria="", max_rec=100, get_query_payload=True)
     assert payload["MAXREC"] == "100"
 
 
 def test_return_moc():
     # legacy compatibility, return_moc=True means a space-MOC
     payload = MOCServer.query_region(
-        meta_data="", return_moc=True, max_norder=5, get_query_payload=True
+        criteria="", return_moc=True, max_norder=5, get_query_payload=True
     )
     assert payload["get"] == "moc"
     assert payload["fmt"] == "ascii"
     assert payload["order"] == 5
     # no max_norder means maximum order available
     payload = MOCServer.query_region(
-        meta_data="", return_moc=True, get_query_payload=True
+        criteria="", return_moc=True, get_query_payload=True
     )
     assert payload["order"] == "max"
 
 
 def test_coordinate_system():
     payload = MOCServer.query_region(
-        coordinate_system="sky", meta_data="", return_moc=True,
+        coordinate_system="sky", criteria="", return_moc=True,
         max_norder=5, get_query_payload=True
     )
     assert payload["spacesys"] == "C"
@@ -271,6 +271,8 @@ def test_cast_to_float():
 
 def test_find_datasets():
     # find datasets is useless as it does the same than query region
-    with pytest.warns(AstropyDeprecationWarning, match="The find_datasets function *"):
+    # and 'meta_data' is replaced byt the new argument 'criteria' in query_region
+    with pytest.warns(AstropyDeprecationWarning, match="'find_datasets' is replaced "
+                                                       "by 'query_region' *"):
         old = MOCServer.find_datasets(meta_data="ID=*Euclid*", get_query_payload=True)
-    assert old == MOCServer.query_region(meta_data="ID=*Euclid*", get_query_payload=True)
+    assert old == MOCServer.query_region(criteria="ID=*Euclid*", get_query_payload=True)
diff --git a/astroquery/mocserver/tests/test_mocserver_remote.py b/astroquery/mocserver/tests/test_mocserver_remote.py
@@ -59,7 +59,7 @@ def test_moc_order_param(self, moc_order):
     def test_stmoc_as_outputs(self):
         # chose a dataset with a MOC with few cells
         stmoc = MOCServer.query_region(
-            meta_data="ID=CDS/J/AJ/157/109/table1", return_moc="stmoc"
+            criteria="ID=CDS/J/AJ/157/109/table1", return_moc="stmoc"
         )
         assert isinstance(stmoc, STMOC)
 
@@ -69,7 +69,7 @@ def test_temporal_mocs_as_inputs(self):
             region=tmoc,
             fields=["t_min"],
             max_rec=100,
-            meta_data="dataproduct_type='image'&&t_min=*",
+            criteria="dataproduct_type='image'&&t_min=*",
         )
         min_time_result = Time(result["t_min"].value, format="mjd")
         # the resulting datasets should only have starting times after the
@@ -78,7 +78,7 @@ def test_temporal_mocs_as_inputs(self):
 
     def test_no_region(self):
         result = MOCServer.query_region(
-            meta_data="moc_sky_fraction>0.5&&moc_sky_fraction=*",
+            criteria="moc_sky_fraction>0.5&&moc_sky_fraction=*",
             fields=["ID", "moc_sky_fraction"],
             max_rec=100,
         )
diff --git a/docs/mocserver/mocserver.rst b/docs/mocserver/mocserver.rst
@@ -127,8 +127,8 @@ Querying by meta-data
 Retrieving datasets based on their meta-data values
 ----------------------------------------------------
 
-The ``meta_data`` parameter of :meth:`~astroquery.mocserver.MOCServerClass.query_region`
-allows to write an algebraic expression on the metadata.
+The ``criteria`` parameter of :meth:`~astroquery.mocserver.MOCServerClass.query_region`
+allows to write an expression on the dataset's metadata to filter the output.
 Let's add a criteria to get only images from the previous query:
 
 .. doctest-requires:: mocpy
@@ -141,7 +141,7 @@ Let's add a criteria to get only images from the previous query:
     >>> cone = CircleSkyRegion(center, radius)
     >>> MOCServer.query_region(region=cone, intersect="enclosed",
     ...                 fields=['ID', 'dataproduct_type', 'moc_sky_fraction'],
-    ...                 meta_data="dataproduct_type=image")  # doctest: +IGNORE_OUTPUT +REMOTE_DATA
+    ...                 criteria="dataproduct_type=image")  # doctest: +IGNORE_OUTPUT +REMOTE_DATA
     <Table length=336>
                   ID               dataproduct_type moc_sky_fraction
                 str49                    str5           float64     
@@ -180,7 +180,7 @@ their identifier. These correspond to the Hubble surveys:
 
 .. doctest-requires:: mocpy
 
-    >>> MOCServer.query_region(meta_data="ID=*HST*",
+    >>> MOCServer.query_region(criteria="ID=*HST*",
     ...                        fields=['ID', 'moc_access_url'],
     ...                        casesensitive=False)  # doctest: +IGNORE_OUTPUT +REMOTE_DATA
     <Table length=45>
@@ -215,7 +215,7 @@ The MOCServer contains an extensive list of `HiPS <https://ivoa.net/documents/Hi
 for images and catalogs. These progressive surveys can be displayed in applications
 such as `ipyaladin <https://github.com/cds-astro/ipyaladin>`_. The
 `astroquery.mocserver.MOCServerClass.query_hips` method allows to find these HiPS.
-It accepts the same parameters (``region`` and ``meta_data`` for example) as the other
+It accepts the same parameters (``region`` and ``criteria`` for example) as the other
 methods. The only difference is that the output will only contain HiPS data.
 
 .. doctest-requires:: mocpy
@@ -332,7 +332,7 @@ Hubble surveys:
     >>> from astroquery.mocserver import MOCServer
     >>> moc = MOCServer.query_region(return_moc="smoc", 
     ...                              max_norder=20, 
-    ...                              meta_data="ID=*HST*") # doctest: +REMOTE_DATA
+    ...                              criteria="ID=*HST*") # doctest: +REMOTE_DATA
 
 The resulting MOC looks like:
 
@@ -350,7 +350,7 @@ object) of the ``GALEXGR6/AIS/FUV`` survey.
 
     >>> from mocpy import MOC
     >>> from astroquery.mocserver import MOCServer
-    >>> moc_galex = MOCServer.query_region(meta_data="ID=CDS/P/GALEXGR6/AIS/FUV", 
+    >>> moc_galex = MOCServer.query_region(criteria="ID=CDS/P/GALEXGR6/AIS/FUV", 
     ...                                    return_moc="stmoc", max_norder="s7 t26")  # doctest: +REMOTE_DATA
     >>> print(f"GALEX GR6 contains data taken from {moc_galex.min_time.iso} to"
     ...       f" {moc_galex.max_time.iso}.")  # doctest: +REMOTE_DATA
