Skip to content

Commit 2f990b4

Browse files
snbiancosnbianco
committed
Update MastMissions documentation
1 parent 1be9420 commit 2f990b4

File tree

1 file changed

+71
-64
lines changed

1 file changed

+71
-64
lines changed

‎docs/mast/mast_missions.rst

Lines changed: 71 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -7,17 +7,17 @@ Mission-Specific Search Queries
77
===============================
88

99
These queries allow for searches based on mission-specific metadata for a given
10-
data collection. Currently it provides access to a broad set of Hubble Space
11-
Telescope (HST) metadata, including header keywords, proposal information, and
12-
observational parameters. The available metadata includes all information that
13-
was previously available in the original HST web search form, and are present in
14-
the current `Mission Search interface <https://mast.stsci.edu/search/ui/#/hst>`__.
10+
data collection. Currently, it provides access to a broad set of Hubble Space
11+
Telescope (HST) and James Webb Space Telescope (JWST) metadata, including header keywords,
12+
proposal information, and observational parameters.
1513

16-
**Note:** this API interface does not yet support data product download, only
17-
metadata earch access.
14+
**Note:** This API interface does not yet support data product downloads, only
15+
metadata search access.
1816

19-
An object of MastMissions class is instantiated with a default mission of 'hst' and
20-
default service set to 'search'.
17+
An object of the ``MastMissions`` class is instantiated with a default mission of ``'hst'`` and
18+
default service set to ``'search'``. The searchable metadata for Hubble encompasses all information that
19+
was previously accessible through the original HST web search form and is now available in
20+
the current `MAST HST Search Form <https://mast.stsci.edu/search/ui/#/hst>`__.
2121

2222
.. doctest-remote-data::
2323

@@ -28,89 +28,96 @@ default service set to 'search'.
2828
>>> missions.service
2929
'search'
3030

31-
The missions object can be used to search metadata using by sky position, or other criteria.
32-
The keyword arguments can be used to specify output characteristics like selec_cols and
33-
sort_by and conditions that filter on values like proposal id, pi last name etc.
34-
The available column names for a mission are returned by the
35-
`~astroquery.mast.MastMissionsClass.get_column_list` function.
31+
To search for JWST metadata, a ``MastMissions`` object is instantiated with a value of ``'jwst'`` for ``mission``.
32+
The searchable metadata for Webb encompasses all information that is available in
33+
the current `MAST JWST Search Form <https://mast.stsci.edu/search/ui/#/jwst>`__.
34+
35+
.. doctest-remote-data::
36+
37+
>>> from astroquery.mast import MastMissions
38+
>>> missions = MastMissions(mission='jwst')
39+
>>> missions.mission
40+
'jwst'
41+
42+
The ``missions`` object can be used to search metadata by object name, sky position, or other criteria.
43+
When writing queries, keyword arguments can be used to specify output characteristics and filter on
44+
values like instrument, exposure type, and principal investigator. The available column names for a
45+
mission are returned by the `~astroquery.mast.MastMissionsClass.get_column_list` function.
3646

3747
.. doctest-remote-data::
3848

3949
>>> from astroquery.mast import MastMissions
4050
>>> missions = MastMissions(mission='hst')
4151
>>> columns = missions.get_column_list()
4252

43-
For positional searches, the columns "ang_sep", "sci_data_set_name", "search_key" and "search_position"
44-
will always be included, in addition to any columns specified using "select_cols". For non-positional
45-
searches, "search_key" and "sci_data_set_name" will always be included, in addition to any columns
46-
specified using "select_cols".
53+
Metadata queries can be performed on a particular region in the sky. Passing in a set of coordinates to the
54+
`~astroquery.mast.MastMissionsClass.query_region` function returns datasets that fall within a
55+
certain radius value of that point. This type of search is also known as a cone search.
4756

48-
For a non positional search, ``select_cols`` would always include ``'search_key'`` and ``'sci_data_set_name'``.
57+
The ``select_cols`` keyword argument specifies a list of columns to be included in the response.
58+
The ``sort_by`` keyword argument specifies a column (or columns) to sort the results by.
4959

5060
.. doctest-remote-data::
5161

5262
>>> from astroquery.mast import MastMissions
5363
>>> from astropy.coordinates import SkyCoord
5464
>>> missions = MastMissions(mission='hst')
5565
>>> regionCoords = SkyCoord(210.80227, 54.34895, unit=('deg', 'deg'))
56-
>>> results = missions.query_region(regionCoords, radius=3, sci_pep_id=12556,
66+
>>> results = missions.query_region(regionCoords,
67+
... radius=3,
68+
... sci_pep_id=12556,
5769
... select_cols=["sci_stop_time", "sci_targname", "sci_start_time", "sci_status"],
5870
... sort_by=['sci_targname'])
5971
>>> results[:5] # doctest: +IGNORE_OUTPUT
6072
<Table masked=True length=5>
61-
sci_status sci_targname sci_data_set_name ang_sep sci_pep_id search_pos sci_pi_last_name search_key
62-
str6 str16 str9 str20 int64 str18 str6 str27
63-
---------- ---------------- ----------------- -------------------- ---------- ------------------ ---------------- ---------------------------
64-
PUBLIC NUCLEUS+HODGE602 OBQU010H0 0.017460048037303017 12556 210.80227 54.34895 GORDON 210.80227 54.34895OBQU010H0
65-
PUBLIC NUCLEUS+HODGE602 OBQU01050 0.017460048037303017 12556 210.80227 54.34895 GORDON 210.80227 54.34895OBQU01050
66-
PUBLIC NUCLEUS+HODGE602 OBQU01030 0.022143836477276503 12556 210.80227 54.34895 GORDON 210.80227 54.34895OBQU01030
67-
PUBLIC NUCLEUS+HODGE602 OBQU010F0 0.022143836477276503 12556 210.80227 54.34895 GORDON 210.80227 54.34895OBQU010F0
68-
PUBLIC NUCLEUS+HODGE602 OBQU010J0 0.04381046755938432 12556 210.80227 54.34895 GORDON 210.80227 54.34895OBQU010J0
69-
70-
for paging through the results, offset and limit can be used to specify the starting record and the number
71-
of returned records. the default values for offset and limit is 0 and 5000 respectively.
73+
search_pos sci_data_set_name sci_targname sci_start_time sci_stop_time ang_sep sci_status
74+
------------------ ----------------- ---------------- -------------------------- -------------------------- -------------------- ----------
75+
210.80227 54.34895 OBQU01050 NUCLEUS+HODGE602 2012-05-24T07:51:40.553000 2012-05-24T07:54:46.553000 0.017460048037303017 PUBLIC
76+
210.80227 54.34895 OBQU010H0 NUCLEUS+HODGE602 2012-05-24T09:17:38.570000 2012-05-24T09:20:44.570000 0.017460048037303017 PUBLIC
77+
210.80227 54.34895 OBQU01030 NUCLEUS+HODGE602 2012-05-24T07:43:20.553000 2012-05-24T07:46:26.553000 0.022143836477276503 PUBLIC
78+
210.80227 54.34895 OBQU010F0 NUCLEUS+HODGE602 2012-05-24T09:09:18.570000 2012-05-24T09:12:24.570000 0.022143836477276503 PUBLIC
79+
210.80227 54.34895 OBQU01070 NUCLEUS+HODGE602 2012-05-24T08:00:00.553000 2012-05-24T08:03:06.553000 0.04381046755938432 PUBLIC
7280

73-
.. doctest-remote-data::
81+
You may notice that the above query returned more columns than were specified in the ``select_cols``
82+
argument. For each mission, certain columns are automatically returned.
7483

75-
>>> from astroquery.mast import MastMissions
76-
>>> from astropy.coordinates import SkyCoord
77-
>>> missions = MastMissions()
78-
>>> results = missions.query_criteria(sci_start_time=">=2021-01-01 00:00:00",
79-
... select_cols=["sci_stop_time", "sci_targname", "sci_start_time", "sci_status", "sci_pep_id"],
80-
... sort_by=['sci_pep_id'], limit=1000, offset=1000) # doctest: +IGNORE_WARNINGS
81-
... # MaxResultsWarning('Maximum results returned, may not include all sources within radius.')
82-
>>> len(results)
83-
1000
84+
* *HST*: For positional searches, the columns ``ang_sep``, ``sci_data_set_name``, and ``search_pos``
85+
are always included in the query results. For non-positional searches, ``sci_data_set_name`` is always
86+
present.
8487

85-
Metadata queries can also be performed using object names with the
86-
~astroquery.mast.MastMissionsClass.query_object function.
88+
* *JWST*: For every query, the ``ArchiveFileID`` column is always returned.
89+
90+
Searches can also be run on target names with the `~astroquery.mast.MastMissionsClass.query_object`
91+
function.
8792

8893
.. doctest-remote-data::
8994

90-
>>> results = missions.query_object('M101', radius=3, select_cols=["sci_stop_time", "sci_targname", "sci_start_time", "sci_status"],
95+
>>> results = missions.query_object('M101',
96+
... radius=3,
97+
... select_cols=["sci_stop_time", "sci_targname", "sci_start_time", "sci_status"],
9198
... sort_by=['sci_targname'])
9299
>>> results[:5] # doctest: +IGNORE_OUTPUT
93100
<Table masked=True length=5>
94-
ang_sep search_pos sci_status search_key sci_stop_time sci_targname sci_start_time sci_data_set_name
95-
str20 str18 str6 str27 str26 str16 str26 str9
96-
------------------ ------------------ ---------- --------------------------- -------------------------- ------------ -------------------------- -----------------
97-
2.751140575012458 210.80227 54.34895 PUBLIC 210.80227 54.34895LDJI01010 2019-02-19T05:52:40.020000 +164.6+9.9 2019-02-19T00:49:58.010000 LDJI01010
98-
0.8000626246647815 210.80227 54.34895 PUBLIC 210.80227 54.34895J8OB02011 2003-08-27T08:27:34.513000 ANY 2003-08-27T07:44:47.417000 J8OB02011
99-
1.1261718338567348 210.80227 54.34895 PUBLIC 210.80227 54.34895J8D711J1Q 2003-01-17T00:50:22.250000 ANY 2003-01-17T00:42:06.993000 J8D711J1Q
100-
1.1454431087675097 210.80227 54.34895 PUBLIC 210.80227 54.34895JD6V01012 2017-06-15T18:33:25.983000 ANY 2017-06-15T18:10:12.037000 JD6V01012
101-
1.1457795862361977 210.80227 54.34895 PUBLIC 210.80227 54.34895JD6V01013 2017-06-15T20:08:44.063000 ANY 2017-06-15T19:45:30.023000 JD6V01013
102-
103-
Metadata queries can also be performed using non-positional parameters with the
104-
`~astroquery.mast.MastMissionsClass.query_criteria` function.
101+
search_pos sci_data_set_name sci_targname sci_start_time sci_stop_time ang_sep sci_status
102+
------------------ ----------------- ------------ -------------------------- -------------------------- ------------------ ----------
103+
210.80243 54.34875 LDJI01010 +164.6+9.9 2019-02-19T00:49:58.010000 2019-02-19T05:52:40.020000 2.7469653000840397 PUBLIC
104+
210.80243 54.34875 J8OB02011 ANY 2003-08-27T07:44:47.417000 2003-08-27T08:27:34.513000 0.8111299061221189 PUBLIC
105+
210.80243 54.34875 J8D711J1Q ANY 2003-01-17T00:42:06.993000 2003-01-17T00:50:22.250000 1.1297984178946574 PUBLIC
106+
210.80243 54.34875 JD6V01012 ANY 2017-06-15T18:10:12.037000 2017-06-15T18:33:25.983000 1.1541053362381077 PUBLIC
107+
210.80243 54.34875 JD6V01013 ANY 2017-06-15T19:45:30.023000 2017-06-15T20:08:44.063000 1.15442580192948 PUBLIC
108+
109+
For non-positional metadata queries, use the `~astroquery.mast.MastMissionsClass.query_criteria`
110+
function. For paging through results, the ``offset`` and ``limit`` keyword arguments can be used
111+
to specify the starting record and the number of returned records. The default values for ``offset``
112+
and ``limit`` are 0 and 5000, respectively.
105113

106114
.. doctest-remote-data::
107115

108-
>>> results = missions.query_criteria(sci_data_set_name="Z06G0101T", sci_pep_id="1455",
109-
... select_cols=["sci_stop_time", "sci_targname", "sci_start_time", "sci_status"],
110-
... sort_by=['sci_targname'])
111-
>>> results[:5] # doctest: +IGNORE_OUTPUT
112-
<Table masked=True length=5>
113-
search_key sci_stop_time sci_data_set_name sci_start_time sci_targname sci_status
114-
str9 str26 str9 str26 str19 str6
115-
---------- -------------------------- ----------------- -------------------------- ------------ ----------
116-
Z06G0101T 1990-05-13T11:02:34.567000 Z06G0101T 1990-05-13T10:38:09.193000 -- PUBLIC
116+
>>> results = missions.query_criteria(sci_start_time=">=2021-01-01 00:00:00",
117+
... select_cols=["sci_stop_time", "sci_targname", "sci_start_time", "sci_status", "sci_pep_id"],
118+
... sort_by=['sci_pep_id'],
119+
... limit=1000,
120+
... offset=1000) # doctest: +IGNORE_WARNINGS
121+
... # MaxResultsWarning('Maximum results returned, may not include all sources within radius.')
122+
>>> len(results)
123+
1000

0 commit comments

Comments
 (0)