GAIASWRQ-25 Rename method to cross_match_basic

Author: Jorge Fernandez Hernandez

CHANGES.rst

@@ -27,7 +27,7 @@ alma
 gaia
 ^^^^
 
-- New method cross_match_stream that simplifies the positional x-match method [#3320]
+- New method cross_match_basic that simplifies the positional x-match method [#3320]
 
 linelists.cdms
 ^^^^^^^^^^^^^^

astroquery/gaia/core.py

@@ -848,10 +848,10 @@ def load_user(self, user_id, *, verbose=False):
 
         return self.is_valid_user(user_id=user_id, verbose=verbose)
 
-    def cross_match_stream(self, *, table_a_full_qualified_name, table_a_column_ra, table_a_column_dec,
-                           table_b_full_qualified_name=MAIN_GAIA_TABLE, table_b_column_ra=MAIN_GAIA_TABLE_RA,
-                           table_b_column_dec=MAIN_GAIA_TABLE_DEC, results_name=None,
-                           radius=1.0, background=False, verbose=False):
+    def cross_match_basic(self, *, table_a_full_qualified_name, table_a_column_ra, table_a_column_dec,
+                          table_b_full_qualified_name=MAIN_GAIA_TABLE, table_b_column_ra=MAIN_GAIA_TABLE_RA,
+                          table_b_column_dec=MAIN_GAIA_TABLE_DEC, results_name=None,
+                          radius=1.0, background=False, verbose=False):
         """Performs a positional cross-match between the specified tables.
 
         This methods simples the execution of the method `cross_match` since it carries out the following steps in one
@@ -861,8 +861,10 @@ def cross_match_stream(self, *, table_a_full_qualified_name, table_a_column_ra,
             #. launches a positional cross-match as an asynchronous query;
             #. returns all the columns from both tables plus the angular distance (deg) for the cross-matched sources.
 
-        The result is a join table with the identifies of both tables and the distance. To speed up the cross-match,
-        pass the biggest table to the ``table_b_full_qualified_name`` parameter.
+        The result is a join table with the identifies of both tables and the distance (degrees), that is returned
+        without metadata units. If desired, units can be added using the Units package of Astropy as follows:
+        results[‘separation’].unit = u.degree. To speed up the cross-match, pass the biggest table to the
+        ``table_b_full_qualified_name`` parameter.
         TAP+ only
 
         Parameters

astroquery/gaia/tests/test_gaiatap.py

@@ -441,7 +441,7 @@ def cross_match_kwargs():
 
 
 @pytest.fixture
-def cross_match_stream_kwargs():
+def cross_match_basic_kwargs():
     return {"table_a_full_qualified_name": "schemaA.tableA",
             "table_a_column_ra": "ra",
             "table_a_column_dec": "dec",
@@ -451,7 +451,7 @@ def cross_match_stream_kwargs():
 
 
 @pytest.fixture
-def cross_match_stream_2_kwargs():
+def cross_match_basic_2_kwargs():
     return {"table_a_full_qualified_name": "user_hola.tableA",
             "table_a_column_ra": "ra",
             "table_a_column_dec": "dec",
@@ -1384,7 +1384,7 @@ def make_table_metadata(table_name):
 
 
 @pytest.mark.parametrize("background", [False, True])
-def test_cross_match_stream(monkeypatch, background, cross_match_stream_kwargs, mock_querier_async):
+def test_cross_match_basic(monkeypatch, background, cross_match_basic_kwargs, mock_querier_async):
     def load_table_monkeypatched(self, table, verbose):
         tap_table_a = make_table_metadata("schemaA.tableA")
         tap_table_b = make_table_metadata("schemaB.tableB")
@@ -1394,14 +1394,14 @@ def load_table_monkeypatched(self, table, verbose):
 
     monkeypatch.setattr(Tap, "load_table", load_table_monkeypatched)
 
-    job = mock_querier_async.cross_match_stream(**cross_match_stream_kwargs, background=background)
+    job = mock_querier_async.cross_match_basic(**cross_match_basic_kwargs, background=background)
     assert job.async_ is True
     assert job.get_phase() == "EXECUTING" if background else "COMPLETED"
     assert job.failed is False
 
 
 @pytest.mark.parametrize("background", [False, True])
-def test_cross_match_stream_2(monkeypatch, background, cross_match_stream_2_kwargs, mock_querier_async):
+def test_cross_match_basic_2(monkeypatch, background, cross_match_basic_2_kwargs, mock_querier_async):
     def load_table_monkeypatched(self, table, verbose):
         tap_table_a = make_table_metadata("user_hola.tableA")
         tap_table_b = make_table_metadata("user_hola.tableB")
@@ -1415,14 +1415,14 @@ def update_user_table(self, table_name, list_of_changes, verbose):
     monkeypatch.setattr(Tap, "load_table", load_table_monkeypatched)
     monkeypatch.setattr(TapPlus, "update_user_table", update_user_table)
 
-    job = mock_querier_async.cross_match_stream(**cross_match_stream_2_kwargs, background=background)
+    job = mock_querier_async.cross_match_basic(**cross_match_basic_2_kwargs, background=background)
     assert job.async_ is True
     assert job.get_phase() == "EXECUTING" if background else "COMPLETED"
     assert job.failed is False
 
 
 @pytest.mark.parametrize("background", [False, True])
-def test_cross_match_stream_3(monkeypatch, background, mock_querier_async):
+def test_cross_match_basic_3(monkeypatch, background, mock_querier_async):
     mock_querier_async.MAIN_GAIA_TABLE = None
 
     def load_table_monkeypatched_2(self, table, verbose):
@@ -1438,15 +1438,15 @@ def update_user_table(self, table_name, list_of_changes, verbose):
     monkeypatch.setattr(Tap, "load_table", load_table_monkeypatched_2)
     monkeypatch.setattr(TapPlus, "update_user_table", update_user_table)
 
-    job = mock_querier_async.cross_match_stream(table_a_full_qualified_name="user_hola.tableA", table_a_column_ra="ra",
-                                                table_a_column_dec="dec", background=background)
+    job = mock_querier_async.cross_match_basic(table_a_full_qualified_name="user_hola.tableA", table_a_column_ra="ra",
+                                               table_a_column_dec="dec", background=background)
     assert job.async_ is True
     assert job.get_phase() == "EXECUTING" if background else "COMPLETED"
     assert job.failed is False
 
 
 @pytest.mark.parametrize("background", [False, True])
-def test_cross_match_stream_wrong_column(monkeypatch, background, mock_querier_async):
+def test_cross_match_basic_wrong_column(monkeypatch, background, mock_querier_async):
     mock_querier_async.MAIN_GAIA_TABLE = None
 
     def load_table_monkeypatched(self, table, verbose):
@@ -1464,18 +1464,18 @@ def update_user_table(self, table_name, list_of_changes, verbose):
 
     error_message = "Please check: columns Wrong_ra or dec not available in the table 'user_hola.tableA'"
     with pytest.raises(ValueError, match=error_message):
-        mock_querier_async.cross_match_stream(table_a_full_qualified_name="user_hola.tableA",
-                                              table_a_column_ra="Wrong_ra", table_a_column_dec="dec",
-                                              background=background)
+        mock_querier_async.cross_match_basic(table_a_full_qualified_name="user_hola.tableA",
+                                             table_a_column_ra="Wrong_ra", table_a_column_dec="dec",
+                                             background=background)
 
     error_message = "Please check: columns ra or Wrong_dec not available in the table 'user_hola.tableA'"
     with pytest.raises(ValueError, match=error_message):
-        mock_querier_async.cross_match_stream(table_a_full_qualified_name="user_hola.tableA",
-                                              table_a_column_ra="ra", table_a_column_dec="Wrong_dec",
-                                              background=background)
+        mock_querier_async.cross_match_basic(table_a_full_qualified_name="user_hola.tableA",
+                                             table_a_column_ra="ra", table_a_column_dec="Wrong_dec",
+                                             background=background)
 
 
-def test_cross_match_stream_exceptions(monkeypatch):
+def test_cross_match_basic_exceptions(monkeypatch):
     def load_table_monkeypatched(self, table, verbose):
         raise ValueError(f"Not found schema name in full qualified table: '{table}'")
 
@@ -1487,41 +1487,41 @@ def update_user_table(self, table_name, list_of_changes, verbose):
 
     error_message = "Not found table 'user_hola.tableA' in the archive"
     with pytest.raises(ValueError, match=error_message):
-        GAIA_QUERIER.cross_match_stream(table_a_full_qualified_name="user_hola.tableA", table_a_column_ra="ra",
-                                        table_a_column_dec="dec", background=True)
+        GAIA_QUERIER.cross_match_basic(table_a_full_qualified_name="user_hola.tableA", table_a_column_ra="ra",
+                                       table_a_column_dec="dec", background=True)
 
     # Check invalid input values
     error_message = "Not found schema name in full qualified table: 'hola'"
     with pytest.raises(ValueError, match=error_message):
-        GAIA_QUERIER.cross_match_stream(table_a_full_qualified_name="hola", table_a_column_ra="ra",
-                                        table_a_column_dec="dec")
+        GAIA_QUERIER.cross_match_basic(table_a_full_qualified_name="hola", table_a_column_ra="ra",
+                                       table_a_column_dec="dec")
 
     error_message = "Schema name is empty in full qualified table: '.table_name'"
     with pytest.raises(ValueError, match=error_message):
-        GAIA_QUERIER.cross_match_stream(table_a_full_qualified_name=".table_name", table_a_column_ra="ra",
-                                        table_a_column_dec="dec")
+        GAIA_QUERIER.cross_match_basic(table_a_full_qualified_name=".table_name", table_a_column_ra="ra",
+                                       table_a_column_dec="dec")
 
     error_message = "Not found schema name in full qualified table: 'hola'"
     with pytest.raises(ValueError, match=error_message):
-        GAIA_QUERIER.cross_match_stream(table_a_full_qualified_name="schema.table_name", table_a_column_ra="ra",
-                                        table_a_column_dec="dec", table_b_full_qualified_name="hola")
+        GAIA_QUERIER.cross_match_basic(table_a_full_qualified_name="schema.table_name", table_a_column_ra="ra",
+                                       table_a_column_dec="dec", table_b_full_qualified_name="hola")
 
     error_message = "Schema name is empty in full qualified table: '.table_name'"
     with pytest.raises(ValueError, match=error_message):
-        GAIA_QUERIER.cross_match_stream(table_a_full_qualified_name="schema.table_name", table_a_column_ra="ra",
-                                        table_a_column_dec="dec", table_b_full_qualified_name=".table_name")
+        GAIA_QUERIER.cross_match_basic(table_a_full_qualified_name="schema.table_name", table_a_column_ra="ra",
+                                       table_a_column_dec="dec", table_b_full_qualified_name=".table_name")
 
     error_message = "Invalid radius value. Found 50.0, valid range is: 0.1 to 10.0"
     with pytest.raises(ValueError, match=error_message):
-        GAIA_QUERIER.cross_match_stream(table_a_full_qualified_name="schema.table_name", table_a_column_ra="ra",
-                                        table_a_column_dec="dec", table_b_full_qualified_name="schema.table_name",
-                                        radius=50.0)
+        GAIA_QUERIER.cross_match_basic(table_a_full_qualified_name="schema.table_name", table_a_column_ra="ra",
+                                       table_a_column_dec="dec", table_b_full_qualified_name="schema.table_name",
+                                       radius=50.0)
 
     error_message = "Invalid radius value. Found 0.01, valid range is: 0.1 to 10.0"
     with pytest.raises(ValueError, match=error_message):
-        GAIA_QUERIER.cross_match_stream(table_a_full_qualified_name="schema.table_name", table_a_column_ra="ra",
-                                        table_a_column_dec="dec", table_b_full_qualified_name="schema.table_name",
-                                        radius=0.01)
+        GAIA_QUERIER.cross_match_basic(table_a_full_qualified_name="schema.table_name", table_a_column_ra="ra",
+                                       table_a_column_dec="dec", table_b_full_qualified_name="schema.table_name",
+                                       radius=0.01)
 
 
 @patch.object(TapPlus, 'login')

docs/gaia/gaia.rst

@@ -787,7 +787,7 @@ The previous 3-step cross-match can be executed in one step by the following met
 
   >>> from astroquery.gaia import Gaia
   >>> Gaia.login()
-  >>> job = Gaia.cross_match_stream(table_a_full_qualified_name=full_qualified_table_name, table_a_column_ra='raj2000',
+  >>> job = Gaia.cross_match_basic(table_a_full_qualified_name=full_qualified_table_name, table_a_column_ra='raj2000',
                        table_a_column_dec='dej2000', table_b_full_qualified_name='gaiadr3.gaia_source',
                        table_b_column_ra='ra', table_b_column_dec='dec, radius=1.0, background=True):
   >>> print(job)