Skip to content

Commit fa099a6

Browse files
mstcyr2bsipocz
mstcyr2
authored and
bsipocz
committed
Updated docs for mast_query feature; new changelong; fix syntax
1 parent 4d15ee9 commit fa099a6

File tree

4 files changed

+189
-33
lines changed

4 files changed

+189
-33
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: 33 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -909,35 +909,61 @@ 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='*', **kwargs):
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+
"""
913932
# Specific keywords related to positional and MashupRequest parameters.
914933
position_keys = ['ra', 'dec', 'radius', 'position']
915934
request_keys = ['format', 'data', 'filename', 'timeout', 'clearcache',
916935
'removecache', 'removenullcolumns', 'page', 'pagesize']
917936

918937
# Explicit formatting for Mast's filtered services
919-
if 'Filtered' in service:
938+
if 'filtered' in service.lower():
920939

921940
# Separating the filter params from the positional and service_request method params.
922941
filters = [{'paramName': k, 'values': kwargs[k]} for k in kwargs
923-
if k not in position_keys+request_keys]
924-
position_params = {k: v for k, v in kwargs.items() if k in position_keys}
925-
request_params = {k: v for k, v in kwargs.items() if k in request_keys}
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}
926945

927946
# Mast's filtered services require at least one filter
928947
if filters == []:
929948
raise InvalidQueryError("Please provide at least one filter.")
930949

931950
# Building 'params' for Mast.service_request
951+
if columns is None:
952+
columns = '*'
953+
932954
params = {'columns': columns,
933955
'filters': filters,
934956
**position_params
935957
}
936958
else:
937959

938960
# Separating service specific params from service_request method params
939-
params = {k: v for k, v in kwargs.items() if k not in request_keys}
940-
request_params = {k: v for k, v in kwargs.items() if k in request_keys}
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)
941967

942968
return self.service_request(service, params, **request_params)
943969

‎astroquery/mast/tests/test_mast.py

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -309,9 +309,17 @@ def test_mast_query(patch_post):
309309
dataproduct_type=['image'],
310310
proposal_pi=['Osten, Rachel A.'],
311311
s_dec=[{'min': 43.5, 'max': 45.5}])
312+
pp_list = result['proposal_pi']
313+
sd_list = result['s_dec']
312314
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
313318

314-
# filtered search with position
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)
315323

316324

317325
def test_resolve_object(patch_post):

‎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)