Skip to content

Commit 8efac7b

Browse files
bsipoczbsipocz
authored
Merge pull request #2785 from mstcyr2/mastclass-query-helper
MastClass query helper function
2 parents 70762dc + fa099a6 commit 8efac7b

File tree

5 files changed

+243
-25
lines changed

5 files changed

+243
-25
lines changed

‎CHANGES.rst‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -248,6 +248,9 @@ mast
248248

249249
- Bug fix in ``Observations.query_criteria()`` to use ``page`` and ``pagesize`` parameters [#2915]
250250

251+
- Added ``Mast.mast_query`` to ``MastClass`` to handle the creation of parameter dictionaries for
252+
MAST Service queries. [#2785]
253+
251254
nist
252255
^^^^
253256

‎astroquery/mast/observations.py‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -909,6 +909,64 @@ def service_request_async(self, service, params, *, pagesize=None, page=None, **
909909

910910
return self._portal_api_connection.service_request_async(service, params, pagesize, page, **kwargs)
911911

912+
def mast_query(self, service, columns=None, **kwargs):
913+
"""
914+
Given a Mashup service and parameters as keyword arguments, builds and excecutes a Mashup query.
915+
916+
Parameters
917+
----------
918+
service : str
919+
The Mashup service to query.
920+
columns : str, optional
921+
Specifies the columns to be returned as a comma-separated list, e.g. "ID, ra, dec".
922+
**kwargs :
923+
Service-specific parameters and MashupRequest properties. See the
924+
`service documentation <https://mast.stsci.edu/api/v0/_services.html>`__ and the
925+
`MashupRequest Class Reference <https://mast.stsci.edu/api/v0/class_mashup_1_1_mashup_request.html>`__
926+
for valid keyword arguments.
927+
928+
Returns
929+
-------
930+
response : `~astropy.table.Table`
931+
"""
932+
# Specific keywords related to positional and MashupRequest parameters.
933+
position_keys = ['ra', 'dec', 'radius', 'position']
934+
request_keys = ['format', 'data', 'filename', 'timeout', 'clearcache',
935+
'removecache', 'removenullcolumns', 'page', 'pagesize']
936+
937+
# Explicit formatting for Mast's filtered services
938+
if 'filtered' in service.lower():
939+
940+
# Separating the filter params from the positional and service_request method params.
941+
filters = [{'paramName': k, 'values': kwargs[k]} for k in kwargs
942+
if k.lower() not in position_keys+request_keys]
943+
position_params = {k: v for k, v in kwargs.items() if k.lower() in position_keys}
944+
request_params = {k: v for k, v in kwargs.items() if k.lower() in request_keys}
945+
946+
# Mast's filtered services require at least one filter
947+
if filters == []:
948+
raise InvalidQueryError("Please provide at least one filter.")
949+
950+
# Building 'params' for Mast.service_request
951+
if columns is None:
952+
columns = '*'
953+
954+
params = {'columns': columns,
955+
'filters': filters,
956+
**position_params
957+
}
958+
else:
959+
960+
# Separating service specific params from service_request method params
961+
params = {k: v for k, v in kwargs.items() if k.lower() not in request_keys}
962+
request_params = {k: v for k, v in kwargs.items() if k.lower() in request_keys}
963+
964+
# Warning for wrong input
965+
if columns is not None:
966+
warnings.warn("'columns' parameter will not mask non-filtered services", InputWarning)
967+
968+
return self.service_request(service, params, **request_params)
969+
912970

913971
Observations = ObservationsClass()
914972
Mast = MastClass()

‎astroquery/mast/tests/test_mast.py‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -299,6 +299,29 @@ def test_mast_service_request(patch_post):
299299
assert isinstance(result, Table)
300300

301301

302+
def test_mast_query(patch_post):
303+
# cone search
304+
result = mast.Mast.mast_query('Mast.Caom.Cone', ra=23.34086, dec=60.658, radius=0.2)
305+
assert isinstance(result, Table)
306+
307+
# filtered search
308+
result = mast.Mast.mast_query('Mast.Caom.Filtered',
309+
dataproduct_type=['image'],
310+
proposal_pi=['Osten, Rachel A.'],
311+
s_dec=[{'min': 43.5, 'max': 45.5}])
312+
pp_list = result['proposal_pi']
313+
sd_list = result['s_dec']
314+
assert isinstance(result, Table)
315+
assert len(set(pp_list)) == 1
316+
assert max(sd_list) < 45.5
317+
assert min(sd_list) > 43.5
318+
319+
# error handling
320+
with pytest.raises(InvalidQueryError) as invalid_query:
321+
mast.Mast.mast_query('Mast.Caom.Filtered')
322+
assert "Please provide at least one filter." in str(invalid_query.value)
323+
324+
302325
def test_resolve_object(patch_post):
303326
m103_loc = mast.Mast.resolve_object("M103")
304327
print(m103_loc)

‎astroquery/mast/tests/test_mast_remote.py‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,21 @@ def test_mast_service_request(self):
8383
# Are the two GALEX observations with obs_id 6374399093149532160 in the results table
8484
assert len(result[np.where(result["obs_id"] == "6374399093149532160")]) == 2
8585

86+
def test_mast_query(self):
87+
# clear columns config
88+
mast.Mast._column_configs = dict()
89+
90+
result = mast.Mast.mast_query('Mast.Caom.Cone', ra=184.3, dec=54.5, radius=0.2)
91+
92+
# Is result in the right format
93+
assert isinstance(result, Table)
94+
95+
# Are the GALEX observations in the results table
96+
assert "GALEX" in result['obs_collection']
97+
98+
# Are the two GALEX observations with obs_id 6374399093149532160 in the results table
99+
assert len(result[np.where(result["obs_id"] == "6374399093149532160")]) == 2
100+
86101
def test_mast_session_info(self):
87102
sessionInfo = mast.Mast.session_info(verbose=False)
88103
assert sessionInfo['ezid'] == 'anonymous'

‎docs/mast/mast_mastquery.rst‎

Lines changed: 144 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -3,26 +3,127 @@
33
MAST Queries
44
************
55

6-
Direct Mast Queries
7-
===================
8-
96
The Mast class provides more direct access to the MAST interface. It requires
107
more knowledge of the inner workings of the MAST API, and should be rarely
118
needed. However in the case of new functionality not yet implemented in
12-
astroquery, this class does allow access. See the `MAST api documentation
13-
<https://mast.stsci.edu/api>`_ for more information.
9+
astroquery, this class does allow access. See the
10+
`MAST api documentation <https://mast.stsci.edu/api>`__ for more
11+
information.
12+
13+
The basic MAST query function allows users to query through the following
14+
`MAST Services <https://mast.stsci.edu/api/v0/_services.html>`__ using
15+
their corresponding parameters and returns query results as an
16+
`~astropy.table.Table`.
17+
18+
Filtered Mast Queries
19+
=====================
20+
21+
MAST's Filtered services use the parameters 'columns' and 'filters'. The 'columns'
22+
parameter is a required string that specifies the columns to be returned as a
23+
comma-separated list. The 'filters' parameter is a required list of filters to be
24+
applied. The `~astroquery.mast.MastClass.mast_query` method accepts that list of
25+
filters as keyword arguments paired with a list of values, similar to
26+
`~astroquery.mast.ObservationsClass.query_criteria`.
27+
28+
The following example uses a JWST service with column names and filters specific to
29+
JWST services. For the full list of valid parameters view the
30+
`JWST Field Documentation <https://mast.stsci.edu/api/v0/_jwst_inst_keywd.html>`__.
31+
32+
.. doctest-remote-data::
33+
34+
>>> from astroquery.mast import Mast
35+
...
36+
>>> observations = Mast.mast_query('Mast.Jwst.Filtered.Nirspec',
37+
... columns='title, instrume, targname',
38+
... targoopp=['T'])
39+
>>> print(observations) # doctest: +IGNORE_OUTPUT
40+
title instrume targname
41+
------------------------------- -------- ----------------
42+
ToO Comet NIRSPEC ZTF (C/2022 E3)
43+
ToO Comet NIRSPEC ZTF (C/2022 E3)
44+
ToO Comet NIRSPEC ZTF (C/2022 E3)
45+
ToO Comet NIRSPEC ZTF (C/2022 E3)
46+
De-Mystifying SPRITEs with JWST NIRSPEC SPIRITS18nu
47+
ToO Comet NIRSPEC ZTF (C/2022 E3)
48+
... ... ...
49+
ToO Comet NIRSPEC ZTF (C/2022 E3)
50+
ToO Comet NIRSPEC ZTF (C/2022 E3)
51+
ToO Comet NIRSPEC ZTF (C/2022 E3)
52+
Length = 319 rows
53+
54+
55+
TESS Queries
56+
------------
1457

15-
The basic MAST query function returns query results as an `~astropy.table.Table`.
58+
TESS queries have 2 types of filtered services. To output a table and specify
59+
columns for a TESS query, use TIC or CTL services with '.Rows' on the end
60+
(e.g. `Mast.Catalogs.Filtered.Tic.Rows
61+
<https://mast.stsci.edu/api/v0/_services.html#MastCatalogsFilteredTicRows>`__).
62+
Valid parameters for TIC and CTL services are detailed in the
63+
`TIC Field Documentation <https://mast.stsci.edu/api/v0/_t_i_cfields.html>`__.
1664

1765
.. doctest-remote-data::
1866

1967
>>> from astroquery.mast import Mast
2068
...
21-
>>> service = 'Mast.Caom.Cone'
22-
>>> params = {'ra':184.3,
23-
... 'dec':54.5,
24-
... 'radius':0.2}
25-
>>> observations = Mast.service_request(service, params)
69+
>>> observations = Mast.mast_query('Mast.Catalogs.Filtered.Tic.Rows',
70+
... columns='id',
71+
... dec=[{'min': -90, 'max': -30}],
72+
... Teff=[{'min': 4250, 'max': 4500}],
73+
... logg=[{'min': 4.5, 'max': 5.0}],
74+
... Tmag=[{'min': 8, 'max': 10}])
75+
>>> print(observations) # doctest: +IGNORE_OUTPUT
76+
ID
77+
---------
78+
320274328
79+
408290683
80+
186485314
81+
395586623
82+
82007673
83+
299550797
84+
...
85+
333372236
86+
394008846
87+
261525246
88+
240766734
89+
240849919
90+
219338557
91+
92131304
92+
Length = 814 rows
93+
94+
TESS services without '.Rows' in the title are used for count queries and will
95+
not mask the output tables using the columns parameter. Additionally, using a
96+
'.Rows' service for a count query will result in an error.
97+
98+
.. doctest-skip::
99+
100+
>>> from astroquery.mast import Mast
101+
...
102+
>>> observations = Mast.mast_query('Mast.Catalogs.Filtered.Tic.Rows',
103+
... columns = 'COUNT_BIG(*)',
104+
... dec=[{'min': -90, 'max': -30}],
105+
... Teff=[{'min': 4250, 'max': 4500}],
106+
... logg=[{'min': 4.5, 'max': 5.0}],
107+
... Tmag=[{'min': 8, 'max': 10}])
108+
Traceback (most recent call last):
109+
...
110+
astroquery.exceptions.RemoteServiceError: Incorrect syntax near '*'.
111+
112+
113+
Cone Searches
114+
=============
115+
116+
MAST's cone search services use the parameters 'ra', 'dec', and 'radius' and return
117+
a table of observations with all columns present.
118+
119+
.. doctest-remote-data::
120+
121+
>>> from astroquery.mast import Mast
122+
...
123+
>>> observations = Mast.mast_query('Mast.Caom.Cone',
124+
... ra=184.3,
125+
... dec=54.5,
126+
... radius=0.2)
26127
>>> print(observations) # doctest: +IGNORE_OUTPUT
27128
intentType obs_collection provenance_name ... obsid distance
28129
---------- -------------- --------------- ... ----------- ------------------
@@ -51,28 +152,46 @@ The basic MAST query function returns query results as an `~astropy.table.Table`
51152
Length = 77 rows
52153

53154

54-
Many mast services, specifically JWST and Catalog services, require the two principal keywords, 'columns' and 'filters',
55-
to list parameters. Positional services will also require right ascension and declination parameters, either in
56-
addition to columns and filters or on their own. For example, the cone search service only requires the 'ra' and
57-
'dec' parameters. Using the wrong service parameters will result in an error. Read the
58-
`MAST API services documentation <https://mast.stsci.edu/api/v0/_services.html>`__ for more information on valid
59-
service parameters.
155+
Cone search services only require positional parameters. Using the wrong service
156+
parameters will result in an error. Read the
157+
`MAST API services documentation <https://mast.stsci.edu/api/v0/_services.html>`__
158+
for more information on valid service parameters.
60159

61-
.. doctest-remote-data::
160+
.. doctest-skip::
62161

63162
>>> from astroquery.mast import Mast
64163
...
65-
>>> service = 'Mast.Caom.Cone'
66-
>>> params = {'columns': "*",
67-
... 'filters': {}}
68-
>>> observations = Mast.service_request(service, params)
164+
>>> observations = Mast.mast_query('Mast.Caom.Cone',
165+
... columns='ra',
166+
... Teff=[{'min': 4250, 'max': 4500}],
167+
... logg=[{'min': 4.5, 'max': 5.0}])
69168
Traceback (most recent call last):
70169
...
71170
astroquery.exceptions.RemoteServiceError: Request Object is Missing Required Parameter : RA
72171

172+
Using the 'columns' parameter in addition to the required cone search parameters will
173+
result in a warning.
174+
175+
.. doctest-remote-data::
176+
177+
>>> from astroquery.mast import Mast
178+
...
179+
>>> observations = Mast.mast_query('Mast.Catalogs.GaiaDR1.Cone',
180+
... columns="ra",
181+
... ra=254.287,
182+
... dec=-4.09933,
183+
... radius=0.02) # doctest: +SHOW_WARNINGS
184+
InputWarning: 'columns' parameter will not mask non-filtered services
185+
186+
Advanced Service Request
187+
========================
73188

74-
If the output is not the MAST json result type it cannot be properly parsed into a `~astropy.table.Table`.
75-
In this case, the async method should be used to get the raw http response, which can then be manually parsed.
189+
Certain MAST Services, such as `Mast.Name.Lookup
190+
<https://mast.stsci.edu/api/v0/_services.html#MastNameLookup>`__ will not work with
191+
`astroquery.mast.MastClass.mast_query` due to it's return type. If the output of a query
192+
is not the MAST json result type it cannot be properly parsed into a `~astropy.table.Table`.
193+
In this case, the `~astroquery.mast.MastClass.service_request_async` method should be used
194+
to get the raw http response, which can then be manually parsed.
76195

77196
.. doctest-remote-data::
78197

@@ -82,7 +201,7 @@ In this case, the async method should be used to get the raw http response, whic
82201
>>> params ={'input':"M8",
83202
... 'format':'json'}
84203
...
85-
>>> response = Mast.service_request_async(service,params)
204+
>>> response = Mast.service_request_async(service, params)
86205
>>> result = response[0].json()
87206
>>> print(result) # doctest: +IGNORE_OUTPUT
88207
{'resolvedCoordinate': [{'cacheDate': 'Apr 12, 2017 9:28:24 PM',

0 commit comments

Comments
 (0)