From fa8aaa76cfd2a7bad97ee9f13698fe0bfb1a2b1a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Brigitta=20Sip=C5=91cz?= Date: Wed, 5 Mar 2025 23:56:55 -0800 Subject: [PATCH 1/3] DOC: updating IRSA documentation Co-authored-by: Vandana Desai --- docs/ipac/irsa/irsa.rst | 119 ++++++++++++++++++++++++---------------- 1 file changed, 71 insertions(+), 48 deletions(-) diff --git a/docs/ipac/irsa/irsa.rst b/docs/ipac/irsa/irsa.rst index b4fb3dcdd3..316c46581a 100644 --- a/docs/ipac/irsa/irsa.rst +++ b/docs/ipac/irsa/irsa.rst @@ -7,21 +7,27 @@ IRSA Queries (`astroquery.ipac.irsa`) Getting started =============== -This module can has methods to perform different types of queries on the -catalogs present in the IRSA general catalog service. All queries can be -performed by calling :meth:`~astroquery.ipac.irsa.IrsaClass.query_region`, with -different keyword arguments. There are 4 different region queries that are -supported: ``Cone``, ``Box``, ``Polygon`` and ``All-Sky``. All successful -queries return the results in a `~astropy.table.Table`. We now look at some -examples. +This module provides access to the public astrophysics catalogs, +images, and spectra curated by the NASA/IPAC Infrared Science Archive +(IRSA) at Caltech. IRSA hosts data from many missions, including +Euclid, Spitzer, WISE/NEOWISE, SOFIA, IRTF, 2MASS, Herschel, IRAS, and +ZTF. +Below we provide examples of common searches. -Available catalogs ------------------- -All region queries require a ``catalog`` keyword argument, which is the name of -the catalog in the IRSA database, on which the query must be performed. To take -a look at all the available catalogs: +Catalog search +-------------- + +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 +specific catalog, the first field can be entered as the value of the +``catalog parameter`` in the `~.astroquery.ipac.irsa.IrsaClass.query_region` method. .. doctest-remote-data:: @@ -37,7 +43,10 @@ a look at all the available catalogs: ... 'xmm_cat_s05': "SWIRE XMM_LSS Region Spring '05 Spitzer Catalog"} -To access the full VOTable of the catalog information, use the ``full`` keyword argument. +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. +The ``table_name`` column holds values that can be entered as the catalog parameter in +the `~astroquery.ipac.irsa.IrsaClass.query_region` method. .. doctest-remote-data:: @@ -53,22 +62,36 @@ To access the full VOTable of the catalog information, use the ``full`` keyword ... -Performing a cone search ------------------------- +Spatial search types +^^^^^^^^^^^^^^^^^^^^ + +Cone search +""""""""""" + +A cone search is performed by using `~astroquery.ipac.irsa.IrsaClass.query_region` with the +``spatial`` parameter set to ``'Cone'``. The center (target name or coordinates) +of the cone search must also be specified, and the radius can be +changed from the default value of 10 arcsec using the radius +parameter. + +Target names may be passed as strings without a parameter. -A cone search query is performed by setting the ``spatial`` keyword to -``Cone``. The target name or the coordinates of the search center must also be -specified. The radius for the cone search may also be specified - if this is -missing, it defaults to a value of 10 arcsec. The radius may be specified in -any appropriate unit using a `~astropy.units.Quantity` object. It may also be -entered as a string that is parsable by `~astropy.coordinates.Angle`. +The coordinates of the center of the cone search can be passed using +the coordinates parameter and specified using a `~astropy.coordinates.SkyCoord` object or a +string resolvable by the ``SkyCoord`` constructor. + +The radius of the cone search can be passed using the ``radius`` +parameter and specified in any appropriate unit using a `~astropy.units.Quantity` +object or entered as a string that is parsable by `~astropy.coordinates.Angle`. .. doctest-remote-data:: >>> from astroquery.ipac.irsa import Irsa + >>> from astropy.coordinates import SkyCoord >>> import astropy.units as u - >>> table = Irsa.query_region("m31", catalog="fp_psc", spatial="Cone", - ... radius=2 * u.arcmin) + >>> coord = SkyCoord(121.1743, -21.5733, unit='deg', frame='galactic') + >>> table = Irsa.query_region(coordinates=coord, spatial='Cone', + ... catalog='fp_psc', radius=2 * u.arcmin) >>> print(table) ra dec err_maj err_min ... coadd_key coadd htm20 deg deg arcsec arcsec ... @@ -82,42 +105,34 @@ entered as a string that is parsable by `~astropy.coordinates.Angle`. 10.663245 41.240646 0.24 0.21 ... 1590591 33 4805203679649555456 Length = 774 rows -The coordinates of the center may be specified rather than using the target -name. The coordinates can be specified using a `~astropy.coordinates.SkyCoord` -object or a string resolvable by the `~astropy.coordinates.SkyCoord` constructor. +Box search +"""""""""" + +A box search is performed by using the `~astroquery.ipac.irsa.IrsaClass.query_region` with the +``spatial`` parameter set to ``'Box'``. The center (target name or coordinates) +and width parameter of the box search must also be specified. .. doctest-remote-data:: >>> from astroquery.ipac.irsa import Irsa >>> from astropy.coordinates import SkyCoord + >>> import astropy.units as u >>> coord = SkyCoord(121.1743, -21.5733, unit='deg', frame='galactic') - >>> table = Irsa.query_region(coordinates=coord, - ... catalog='fp_psc', radius='0d2m0s') + >>> table = Irsa.query_region(coordinates=coord, spatial='Box', + ... catalog='fp_psc', width=2 * u.arcmin) >>> print(table) - ra dec err_maj err_min ... coadd_key coadd htm20 - deg deg arcsec arcsec ... - --------- --------- ------- ------- ... --------- ----- ------------------- - 10.692216 41.260162 0.10 0.09 ... 1590591 33 4805203678124326400 - 10.700059 41.263481 0.31 0.30 ... 1590591 33 4805203678125364736 - 10.699131 41.263248 0.28 0.20 ... 1590591 33 4805203678125474304 - ... ... ... ... ... ... ... ... - 10.661414 41.242363 0.21 0.20 ... 1590591 33 4805203679644192256 - 10.665184 41.240238 0.14 0.13 ... 1590591 33 4805203679647824896 - 10.663245 41.240646 0.24 0.21 ... 1590591 33 4805203679649555456 - Length = 774 rows -Queries over a polygon ----------------------- +Polygon search +"""""""""""""" -Polygon queries can be performed by setting ``spatial='Polygon'``. The search -center is optional in this case. One additional parameter that must be set for +A polygon search is performed by using the `~astroquery.ipac.irsa.IrsaClass.query_region` with +the ``spatial`` parameter set to ``'Polygon'``. One additional parameter that must be set for these queries is ``polygon``. This is a list of coordinate pairs that define a convex polygon. The coordinates may be specified as usual by using the appropriate `~astropy.coordinates.SkyCoord` object. In addition to using a list of `~astropy.coordinates.SkyCoord` objects, one additional convenient means of specifying the coordinates is also available - Coordinates may also be entered as a list of -tuples, each tuple containing the ra and dec values in degrees. Each of these -options is illustrated below: +tuples, each tuple containing the ra and dec values in degrees. .. doctest-remote-data:: @@ -160,6 +175,15 @@ is an ra, dec pair expressed in degrees: 10.059964 10.085445 0.23 0.20 ... 1443005 91 4805087710674674176 10.005549 10.018401 0.16 0.14 ... 1443005 91 4805087784811171840 +All-sky search +"""""""""""""" + +An all-sky search is performed by using the `~astroquery.ipac.irsa.IrsaClass.query_region` method +with the ``spatial`` parameter set to ``"All-Sky"``. + +.. TODO: add example, that is runnable, but still potentially useful. + + Selecting Columns ----------------- @@ -194,8 +218,8 @@ the query is send in asynchronous mode. >>> from astroquery.ipac.irsa import Irsa >>> table = Irsa.query_region("HIP 12", catalog="allwise_p3as_psd", spatial="Cone", async_job=True) >>> print(table) - designation ra dec sigra ... y z spt_ind htm20 - deg deg arcsec ... + designation ra dec sigra ... y z spt_ind htm20 + deg deg arcsec ... ------------------- --------- ----------- ------ ... ------------------ ------------------- --------- ------------- J000009.78-355736.9 0.0407905 -35.9602605 0.0454 ... 0.0005762523295116 -0.5872239888098030 100102010 8873706189183 @@ -316,7 +340,6 @@ Now plot the cutout. plt.show() - Simple spectral access queries ------------------------------ From 86d400d13023023afb398ccbee082b7a68270855 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Brigitta=20Sip=C5=91cz?= Date: Thu, 6 Mar 2025 00:01:31 -0800 Subject: [PATCH 2/3] DOC: making doctests pass --- docs/ipac/irsa/irsa.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/ipac/irsa/irsa.rst b/docs/ipac/irsa/irsa.rst index 316c46581a..ed3f0b8592 100644 --- a/docs/ipac/irsa/irsa.rst +++ b/docs/ipac/irsa/irsa.rst @@ -121,6 +121,17 @@ and width parameter of the box search must also be specified. >>> table = Irsa.query_region(coordinates=coord, spatial='Box', ... catalog='fp_psc', width=2 * u.arcmin) >>> print(table) + ra dec err_maj err_min err_ang designation ... ext_key scan_key coadd_key coadd htm20 + deg deg arcsec arcsec deg ... + --------- --------- ------- ------- ------- ---------------- ... ------- -------- --------- ----- ------------------- + 10.692216 41.260162 0.10 0.09 87 00424613+4115365 ... -- 69157 1590591 33 4805203678124326400 + 10.700059 41.263481 0.31 0.30 155 00424801+4115485 ... -- 69157 1590591 33 4805203678125364736 + 10.699131 41.263248 0.28 0.20 82 00424779+4115476 ... -- 69157 1590591 33 4805203678125474304 + ... ... ... ... ... ... ... ... ... ... ... ... + 10.672209 41.252857 0.22 0.21 8 00424133+4115102 ... -- 69157 1590591 33 4805203679613328896 + 10.672878 41.252518 0.18 0.17 38 00424149+4115090 ... -- 69157 1590591 33 4805203679613393408 + 10.671090 41.252468 0.14 0.13 69 00424106+4115088 ... -- 69157 1590591 33 4805203679613500928 + Length = 265 rows Polygon search """""""""""""" From 282d59f020e018a6fa0a00fac70702b697ee1a34 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Brigitta=20Sip=C5=91cz?= Date: Thu, 6 Mar 2025 00:09:50 -0800 Subject: [PATCH 3/3] Fixes for rendering issues --- docs/ipac/irsa/irsa.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ipac/irsa/irsa.rst b/docs/ipac/irsa/irsa.rst index ed3f0b8592..04ebc65191 100644 --- a/docs/ipac/irsa/irsa.rst +++ b/docs/ipac/irsa/irsa.rst @@ -27,7 +27,7 @@ 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 specific catalog, the first field can be entered as the value of the -``catalog parameter`` in the `~.astroquery.ipac.irsa.IrsaClass.query_region` method. +``catalog`` parameter in the `~.astroquery.ipac.irsa.IrsaClass.query_region` method. .. doctest-remote-data::