Merge pull request #3264 from bsipocz/ENH_irsa_filter_lists

ENH: adding ``filter`` to IRSA's list_collections and list_catalogs

Author: bsipocz

CHANGES.rst

@@ -48,6 +48,9 @@ ipac.irsa
 - Adding the "servicetype" kwarg to ``list_collections`` to be able to list SIA
   and SSA collections separately. [#3200]
 
+- Addding "filter" kwarg to ``list_collections`` and ``list_catalogs`` to
+  filter out collections/catalogs with names containing the filter string. [#3264]
+
 - Adding support for asynchronous queries using the new ``async_job``
   keyword. [#3201]
 

astroquery/ipac/irsa/core.py

@@ -165,7 +165,7 @@ def query_ssa(self, *, pos=None, radius=None, band=None, time=None, collection=N
                                   format='all', collection=collection)
         return results.to_table()
 
-    def list_collections(self, servicetype=None):
+    def list_collections(self, *, servicetype=None, filter=None):
         """
         Return information of available IRSA SIAv2 collections to be used in ``query_sia`` queries.
 
@@ -174,6 +174,9 @@ def list_collections(self, servicetype=None):
         servicetype : str or None
             Service type to list collections for. Returns all collections when not provided.
             Currently supported service types are: 'SIA', 'SSA'.
+        filter : str or None
+            If specified we only return collections then their collection_name
+            contains the filter string.
 
         Returns
         -------
@@ -198,8 +201,12 @@ def list_collections(self, servicetype=None):
             else:
                 raise ValueError("if specified, servicetype should be 'SIA' or 'SSA'")
 
-        collections = self.query_tap(query=query)
-        return collections.to_table()
+        collections = self.query_tap(query=query).to_table()
+
+        if filter:
+            mask = [filter in collection for collection in collections['collection']]
+            collections = collections[mask]
+        return collections
 
     @deprecated_renamed_argument(("selcols", "cache", "verbose"), ("columns", None, None), since="0.4.7")
     def query_region(self, coordinates=None, *, catalog=None, spatial='Cone',
@@ -297,7 +304,7 @@ def query_region(self, coordinates=None, *, catalog=None, spatial='Cone',
         return response.to_table()
 
     @deprecated_renamed_argument("cache", None, since="0.4.7")
-    def list_catalogs(self, full=False, cache=False):
+    def list_catalogs(self, *, full=False, filter=None, cache=False):
         """
         Return information of available IRSA catalogs.
 
@@ -306,8 +313,15 @@ def list_catalogs(self, full=False, cache=False):
         full : bool
             If True returns the full schema as a `~astropy.table.Table`.
             If False returns a dictionary of the table names and their description.
+        filter : str or None
+            If specified we only return catalogs when their catalog_name
+            contains the filter string.
         """
-        tap_tables = Irsa.query_tap("SELECT * FROM TAP_SCHEMA.tables").to_table()
+        tap_tables = self.query_tap("SELECT * FROM TAP_SCHEMA.tables").to_table()
+
+        if filter:
+            mask = [filter in name for name in tap_tables['table_name']]
+            tap_tables = tap_tables[mask]
 
         if full:
             return tap_tables

astroquery/ipac/irsa/tests/test_irsa_remote.py

@@ -66,12 +66,19 @@ def test_list_catalogs(self):
         # Number of available catalogs may change over time, test only for significant drop.
         # (at the time of writing there are 933 tables in the list).
         assert len(catalogs) > 900
+        assert isinstance(catalogs, dict)
+
+    def test_list_catalogs_filter(self):
+        spitzer_catalogs = Irsa.list_catalogs(filter='spitzer')
+
+        assert len(spitzer_catalogs) == 142
 
     @pytest.mark.parametrize('servicetype', (None, 'sia', 'ssa'))
     def test_list_collections(self, servicetype):
         collections = Irsa.list_collections(servicetype=servicetype)
         # Number of available collections may change over time, test only for significant drop.
         # (at the time of writing there are 104 SIA and 35 SSA collections in the list).
+        assert isinstance(collections, Table)
         if servicetype == 'ssa':
             assert len(collections) > 30
             assert 'sofia_exes' in collections['collection']
@@ -80,6 +87,11 @@ def test_list_collections(self, servicetype):
             assert 'spitzer_seip' in collections['collection']
             assert 'wise_allwise' in collections['collection']
 
+    def test_list_collections_filter(self):
+        spitzer_collections = Irsa.list_collections(filter='spitzer')
+
+        assert len(spitzer_collections) == 47
+
     def test_tap(self):
         query = "SELECT TOP 5 ra,dec FROM cosmos2015"
         with pytest.warns(expected_warning=DALOverflowWarning,

docs/ipac/irsa/irsa.rst

@@ -25,23 +25,27 @@ Available IRSA catalogs
 
 To get a concise list of IRSA catalogs available to query, use the
 `~.astroquery.ipac.irsa.IrsaClass.list_catalogs` method.
-The output consists of two fields for each catalog. To query a
+The output consists of two fields for each catalog, the name of the catalog
+and a very short description. To query a
 specific catalog, the first field can be entered as the value of the
 ``catalog`` parameter in the `~.astroquery.ipac.irsa.IrsaClass.query_region` method.
+You can also use the ``filter`` argument to return only the catalogs with
+name matches to the specified string.
+
 
 .. doctest-remote-data::
 
     >>> from astroquery.ipac.irsa import Irsa
-    >>> Irsa.list_catalogs()   # doctest: +IGNORE_OUTPUT
-    {'a1763t2': 'Abell 1763 Source Catalog',
-     'a1763t3': 'Abell 1763 MIPS 70 micron Catalog',
-     'acs_iphot_sep07': 'COSMOS ACS I-band photometry catalog September 2007',
-     'akari_fis': 'Akari/FIS Bright Source Catalogue',
-     'akari_irc': 'Akari/IRC Point Source Catalogue',
-     'astsight': 'IRAS Minor Planet Survey',
-     ...
+    >>> Irsa.list_catalogs(filter='spitzer')   # doctest: +IGNORE_OUTPUT
+    {'spitzer.safires_images': 'Spitzer Archival FIR Extragalactic Survey (SAFIRES) Images',
+     'spitzer.safires_science': 'Spitzer SAFIRES Science Image Metadata',
+     'spitzer.safires_ancillary': 'Spitzer SAFIRES Ancillary Image Metadata',
+     'spitzer.sage_images': 'SAGE Images',
+     'spitzer.sage_mips_mos': 'Spitzer SAGE MIPS Mosaic Image Metadata',
      ...
-     'xmm_cat_s05': "SWIRE XMM_LSS Region Spring '05 Spitzer Catalog"}
+     'spitzer.ssgss_irs_sl_ll': 'SSGSS IRS SL LL Spectra',
+     'spitzer.swire_images': 'Spitzer Wide-area InfraRed Extragalactic Survey (SWIRE) Images',
+     'herschel.hops_spitzer': 'HOPS Spitzer Metadata'}
 
 To get a full list of information available for each available
 catalog, use the ``full`` keyword argument. The output consists of many columns for each catalog.
@@ -52,14 +56,16 @@ the `~astroquery.ipac.irsa.IrsaClass.query_region` method.
 
     >>> from astroquery.ipac.irsa import Irsa
     >>> Irsa.list_catalogs(full=True)  # doctest: +IGNORE_OUTPUT
-    <DALResultsTable length=934>
-    table_index schema_name             table_name                              description                  ... irsa_access_flag irsa_nrows irsa_odbc_datasource irsa_spatial_idx_name
-       int32       object                 object                                   object                    ...      int32         int64           object                object
-    ----------- ----------- ---------------------------------- --------------------------------------------- ... ---------------- ---------- -------------------- ---------------------
-            303     spitzer              spitzer.m31irac_image                                M31IRAC Images ...               30          4             postgres
-            304     spitzer                             mipslg                   MIPS Local Galaxies Catalog ...               30        240              spitzer        SPT_IND_MIPSLG
-            305     spitzer             spitzer.mips_lg_images                    MIPS Local Galaxies Images ...               30        606             postgres
-    ...
+    <Table length=951>
+    table_index schema_name          table_name          ... irsa_nrows irsa_odbc_datasource irsa_spatial_idx_name
+       int32       object              object            ...   int64           object                object
+    ----------- ----------- ---------------------------- ... ---------- -------------------- ---------------------
+            101         wax                      cf_info ...     456480                  wax                SPTC01
+            102         wax                      cf_link ...  204143440                  wax
+            103     twomass                    ext_src_c ...     403811              twomass        EXT_SRC_CIX413
+            104         wax                     ecf_info ...       2146                  wax              SPTETC01
+            105         wax                     ecf_link ...     473971                  wax
+            ...
 
 
 Spatial search types
@@ -286,29 +292,28 @@ To list available collections for SIA queries, the
 `~astroquery.ipac.irsa.IrsaClass.list_collections` method is provided, and
 will return a `~astropy.table.Table`. You can use the ``servicetype``
 argument to filter for image or spectral collections using ``'SIA'`` or
-``'SSA'`` respectively:
+``'SSA'`` respectively. You can also use the ``filter`` argument to show
+only the collections with the given filter strings in the collection names.
 
 .. doctest-remote-data::
 
    >>> from astroquery.ipac.irsa import Irsa
-   >>> Irsa.list_collections(servicetype='SIA')
-   <Table length=104>
-         collection
-           object
-   ---------------------
-        akari_allskymaps
-                   blast
-             bolocam_gps
-              bolocam_lh
-       bolocam_planck_sz
-                     ...
-             wise_allsky
-            wise_allwise
-              wise_fdepa
-             wise_prelim
-   wise_prelim_2bandcryo
-             wise_unwise
-              wise_z0mgs
+   >>> Irsa.list_collections(servicetype='SIA', filter='spitzer')
+   <Table length=38>
+        collection
+          object
+   -------------------
+     spitzer_abell1763
+         spitzer_clash
+   spitzer_cosmic_dawn
+          spitzer_cygx
+     spitzer_deepdrill
+                   ...
+         spitzer_spuds
+       spitzer_srelics
+          spitzer_ssdf
+         spitzer_swire
+        spitzer_taurus
 
 Now open a cutout image for one of the science images. You could either use
 the the IRSA on-premise data or the cloud version of it using the