Skip to content

Commit 88dd76d

Browse files
bsipoczbsipocz
authored
Merge pull request #2743 from mstcyr2/mast-docs-vr
Preserving mast docs vertical real estate
2 parents 69bcecf + b1ae163 commit 88dd76d

File tree

6 files changed

+1438
-1423
lines changed

6 files changed

+1438
-1423
lines changed

‎docs/mast/mast.rst

Lines changed: 8 additions & 1423 deletions
Large diffs are not rendered by default.

‎docs/mast/mast_catalog.rst

Lines changed: 322 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,322 @@
1+
2+
3+
***************
4+
Catalog Queries
5+
***************
6+
7+
The Catalogs class provides access to a subset of the astronomical catalogs stored at MAST.
8+
The catalogs currently available through this interface are:
9+
10+
- The Hubble Source Catalog (HSC)
11+
- The GALEX Catalog (V2 and V3)
12+
- The Gaia (DR1 and DR2) and TGAS Catalogs
13+
- The TESS Input Catalog (TIC)
14+
- The TESS Candidate Target List (CTL)
15+
- The Disk Detective Catalog
16+
- The PanSTARRS Catalog (DR1 and DR2)
17+
- The All-Sky PLATO Input Catalog (DR1)
18+
19+
Catalog Positional Queries
20+
==========================
21+
22+
Positional queries can be based on a sky position or a target name.
23+
The returned fields vary by catalog, find the field documentation for specific catalogs
24+
`here <https://mast.stsci.edu/api/v0/pages.html>`__.
25+
If no catalog is specified, the Hubble Source Catalog will be queried.
26+
27+
.. doctest-remote-data::
28+
29+
>>> from astroquery.mast import Catalogs
30+
...
31+
>>> catalog_data = Catalogs.query_object("158.47924 -7.30962", catalog="Galex")
32+
>>> print(catalog_data[:10])
33+
distance_arcmin objID survey ... fuv_flux_aper_7 fuv_artifact
34+
------------------ ------------------- ------ ... --------------- ------------
35+
0.3493802506329695 6382034098673685038 AIS ... 0.047751952 0
36+
0.7615422488595471 6382034098672634783 AIS ... -- 0
37+
0.9243329366166956 6382034098672634656 AIS ... -- 0
38+
1.162615739258038 6382034098672634662 AIS ... -- 0
39+
1.2670891287503308 6382034098672634735 AIS ... -- 0
40+
1.492173395497916 6382034098674731780 AIS ... 0.0611195639 0
41+
1.6051235757244107 6382034098672634645 AIS ... -- 0
42+
1.705418541388336 6382034098672634716 AIS ... -- 0
43+
1.7463721100195875 6382034098672634619 AIS ... -- 0
44+
1.7524423152919317 6382034098672634846 AIS ... -- 0
45+
46+
47+
Some catalogs have a maximum number of results they will return.
48+
If a query results in this maximum number of results a warning will be displayed to alert
49+
the user that they might be getting a subset of the true result set.
50+
51+
.. doctest-remote-data::
52+
53+
>>> from astroquery.mast import Catalogs
54+
...
55+
>>> catalog_data = Catalogs.query_region("322.49324 12.16683", catalog="HSC", magtype=2) # doctest: +SHOW_WARNINGS
56+
InputWarning: Coordinate string is being interpreted as an ICRS coordinate provided in degrees.
57+
MaxResultsWarning: Maximum catalog results returned, may not include all sources within radius.
58+
>>> print(catalog_data[:10])
59+
MatchID Distance MatchRA ... W3_F160W_MAD W3_F160W_N
60+
--------- -------------------- ------------------ ... ------------ ----------
61+
50180585 0.003984902849540913 322.4931746094701 ... nan 0
62+
8150896 0.006357935819940561 322.49334740450234 ... nan 0
63+
100906349 0.00808206428937523 322.4932839715549 ... nan 0
64+
105434103 0.011947078376104195 322.49324000530777 ... nan 0
65+
103116183 0.01274757103013683 322.4934207202404 ... nan 0
66+
45593349 0.013026569623011767 322.4933878707698 ... nan 0
67+
103700905 0.01306760650244682 322.4932769229944 ... nan 0
68+
102470085 0.014611879195009472 322.49311034430366 ... nan 0
69+
93722307 0.01476438046135455 322.49348351134466 ... nan 0
70+
24781941 0.015234351867433582 322.49300148743345 ... nan 0
71+
72+
Radius is an optional parameter and the default is 0.2 degrees.
73+
74+
.. doctest-remote-data::
75+
76+
>>> from astroquery.mast import Catalogs
77+
...
78+
>>> catalog_data = Catalogs.query_object("M10", radius=.02, catalog="TIC")
79+
>>> print(catalog_data[:10]) # doctest: +IGNORE_OUTPUT
80+
ID ra dec ... wdflag dstArcSec
81+
---------- ---------------- ----------------- ... ------ ------------------
82+
510188144 254.287449269816 -4.09954224264168 ... -1 0.7650443624931581
83+
510188143 254.28717785824 -4.09908635292493 ... -1 1.3400566638148848
84+
189844423 254.287799703996 -4.0994998249247 ... 0 1.3644407138867785
85+
1305764031 254.287147439535 -4.09866105132406 ... -1 2.656905409847388
86+
1305763882 254.286696117371 -4.09925522448626 ... -1 2.7561196688252894
87+
510188145 254.287431890823 -4.10017293344746 ... -1 3.036238557555728
88+
1305763844 254.286675148545 -4.09971617257086 ... 0 3.1424781549696217
89+
1305764030 254.287249718516 -4.09841883152995 ... -1 3.365991083435227
90+
1305764097 254.287599269103 -4.09837925361712 ... -1 3.4590276863989
91+
1305764215 254.28820865799 -4.09859677020253 ... -1 3.7675526728257034
92+
93+
94+
The Hubble Source Catalog, the Gaia Catalog, and the PanSTARRS Catalog have multiple versions.
95+
An optional version parameter allows you to select which version you want, the default is the highest version.
96+
97+
.. doctest-remote-data::
98+
99+
>>> catalog_data = Catalogs.query_region("158.47924 -7.30962", radius=0.1,
100+
... catalog="Gaia", version=2)
101+
>>> print("Number of results:",len(catalog_data))
102+
Number of results: 111
103+
>>> print(catalog_data[:4])
104+
solution_id designation ... distance
105+
------------------- ---------------------------- ... ------------------
106+
1635721458409799680 Gaia DR2 3774902350511581696 ... 0.6326770410972467
107+
1635721458409799680 Gaia DR2 3774901427093274112 ... 0.8440033390947586
108+
1635721458409799680 Gaia DR2 3774902148648277248 ... 0.9199206487344911
109+
1635721458409799680 Gaia DR2 3774902453590798208 ... 1.3578181104319944
110+
111+
The PanSTARRS Catalog has multiple data releases as well as multiple queryable tables.
112+
An optional data release parameter allows you to select which data release is desired, with the default being the latest version (dr2).
113+
The table to query is a required parameter.
114+
115+
.. doctest-remote-data::
116+
117+
>>> catalog_data = Catalogs.query_region("158.47924 -7.30962", radius=0.1,
118+
... catalog="Panstarrs", data_release="dr1", table="mean")
119+
>>> print("Number of results:",len(catalog_data))
120+
Number of results: 7007
121+
>>> print(catalog_data[:10]) # doctest: +IGNORE_OUTPUT
122+
ObjName objAltName1 ... yFlags distance
123+
-------------------------- ----------- ... ------ --------------------
124+
PSO J103359.653-071622.382 -999 ... 16416 0.04140441098310487
125+
PSO J103359.605-071622.873 -999 ... 0 0.04121935961328582
126+
PSO J103359.691-071640.232 -999 ... 0 0.03718729257758985
127+
PSO J103400.268-071639.192 -999 ... 0 0.03870112803784765
128+
PSO J103400.073-071637.358 -999 ... 0 0.03867536827891155
129+
PSO J103359.789-071632.606 -999 ... 0 0.03921557769883566
130+
PSO J103359.192-071654.790 -999 ... 0 0.03266232705300051
131+
PSO J103359.959-071655.155 -999 ... 0 0.034361022297827955
132+
PSO J103359.847-071655.610 -999 ... 0 0.033986082329893995
133+
PSO J103400.586-071656.646 -999 ... 0 0.035645179491121386
134+
135+
Catalog Criteria Queries
136+
========================
137+
138+
The TESS Input Catalog (TIC), Disk Detective Catalog, and PanSTARRS Catalog can also be queried based on non-positional criteria.
139+
140+
.. doctest-remote-data::
141+
142+
>>> from astroquery.mast import Catalogs
143+
...
144+
>>> catalog_data = Catalogs.query_criteria(catalog="Tic",Bmag=[30,50],objType="STAR")
145+
>>> print(catalog_data) # doctest: +IGNORE_OUTPUT
146+
ID version HIP TYC ... e_Dec_orig raddflag wdflag objID
147+
--------- -------- --- --- ... ------------------ -------- ------ ----------
148+
125413929 20190415 -- -- ... 0.293682765259495 1 0 579825059
149+
261459129 20190415 -- -- ... 0.200397148604244 1 0 1701625107
150+
64575709 20190415 -- -- ... 0.21969663115091 1 0 595775997
151+
94322581 20190415 -- -- ... 0.205286802302475 1 0 606092549
152+
125414201 20190415 -- -- ... 0.22398993783274 1 0 579825329
153+
463721073 20190415 -- -- ... 0.489828592248652 -1 1 710312391
154+
81609218 20190415 -- -- ... 0.146788572369267 1 0 630541794
155+
282024596 20190415 -- -- ... 0.548806522539047 1 0 573765450
156+
23868624 20190415 -- -- ... 355.949 -- 0 916384285
157+
282391528 20190415 -- -- ... 0.47766300834538 0 0 574723760
158+
123585000 20190415 -- -- ... 0.618316068787371 0 0 574511442
159+
260216294 20190415 -- -- ... 0.187170498094167 1 0 683390717
160+
406300991 20190415 -- -- ... 0.0518318978617112 0 0 1411465651
161+
162+
163+
.. doctest-remote-data::
164+
165+
>>> from astroquery.mast import Catalogs
166+
...
167+
>>> catalog_data = Catalogs.query_criteria(catalog="Ctl",
168+
... objectname='M101', radius=1, Tmag=[10.75,11])
169+
>>> print(catalog_data)
170+
ID version HIP TYC ... raddflag wdflag objID
171+
--------- -------- --- ------------ ... -------- ------ ---------
172+
233458861 20190415 -- 3852-01407-1 ... 1 0 150390757
173+
441662028 20190415 -- 3855-00941-1 ... 1 0 150395533
174+
441658008 20190415 -- 3852-00116-1 ... 1 0 150246361
175+
441639577 20190415 -- 3852-00429-1 ... 1 0 150070672
176+
441658179 20190415 -- 3855-00816-1 ... 1 0 150246482
177+
154258521 20190415 -- 3852-01403-1 ... 1 0 150281963
178+
441659970 20190415 -- 3852-00505-1 ... 1 0 150296707
179+
441660006 20190415 -- 3852-00341-1 ... 1 0 150296738
180+
181+
182+
.. doctest-remote-data::
183+
184+
>>> from astroquery.mast import Catalogs
185+
...
186+
>>> catalog_data = Catalogs.query_criteria(catalog="DiskDetective",
187+
... objectname="M10",radius=2,state="complete")
188+
>>> print(catalog_data) # doctest: +IGNORE_OUTPUT
189+
designation ... ZooniverseURL
190+
------------------- ... ----------------------------------------------------
191+
J165628.40-054630.8 ... https://talk.diskdetective.org/#/subjects/AWI0005cka
192+
J165748.96-054915.4 ... https://talk.diskdetective.org/#/subjects/AWI0005ckd
193+
J165427.11-022700.4 ... https://talk.diskdetective.org/#/subjects/AWI0005ck5
194+
J165749.79-040315.1 ... https://talk.diskdetective.org/#/subjects/AWI0005cke
195+
J165327.01-042546.2 ... https://talk.diskdetective.org/#/subjects/AWI0005ck3
196+
J165949.90-054300.7 ... https://talk.diskdetective.org/#/subjects/AWI0005ckk
197+
J170314.11-035210.4 ... https://talk.diskdetective.org/#/subjects/AWI0005ckv
198+
199+
200+
The `~astroquery.mast.CatalogsClass.query_criteria` function requires at least one non-positional parameter.
201+
These parameters are the column names listed in the `field descriptions <https://mast.stsci.edu/api/v0/pages.html>`__
202+
of the catalog being queried. They do not include objectname, coordinates, or radius. Running a query with only positional
203+
parameters will result in an error.
204+
205+
.. doctest-remote-data::
206+
207+
>>> from astroquery.mast import Catalogs
208+
...
209+
>>> catalog_data = Catalogs.query_criteria(catalog="Tic",
210+
... objectname='M101', radius=1)
211+
Traceback (most recent call last):
212+
...
213+
astroquery.exceptions.InvalidQueryError: At least one non-positional criterion must be supplied.
214+
215+
216+
The PanSTARRS catalog also accepts additional parameters to allow for query refinement. These options include column selection,
217+
sorting, column criteria, page size and page number. Additional information on PanSTARRS queries may be found
218+
`here <https://catalogs.mast.stsci.edu/docs/panstarrs.html>`__.
219+
220+
Columns returned from the query may be submitted with the columns parameter as a list of column names.
221+
222+
The query may be sorted with the sort_by parameter composed of either a single column name (to sort ascending),
223+
or a list of multiple column names and/or tuples of direction and column name (ASC/DESC, column name).
224+
225+
To filter the query, criteria per column name are accepted. The 'AND' operation is performed between all
226+
column name criteria, and the 'OR' operation is performed within column name criteria. Per each column name
227+
parameter, criteria may consist of either a value or a list. The list may consist of a mix of values and
228+
tuples of criteria decorator (min, gte, gt, max, lte, lt, like, contains) and value.
229+
230+
.. doctest-remote-data::
231+
232+
>>> catalog_data = Catalogs.query_criteria(coordinates="5.97754 32.53617", radius=0.01,
233+
... catalog="PANSTARRS", table="mean", data_release="dr2",
234+
... nStackDetections=[("gte", 2)],
235+
... columns=["objName", "objID", "nStackDetections", "distance"],
236+
... sort_by=[("desc", "distance")], pagesize=15)
237+
>>> print(catalog_data[:10]) # doctest: +IGNORE_OUTPUT
238+
objName objID nStackDetections distance
239+
--------------------- ------------------ ---------------- ---------------------
240+
PSO J005.9812+32.5270 147030059812483022 5 0.009651200148871086
241+
PSO J005.9726+32.5278 147030059727583992 2 0.0093857181370567
242+
PSO J005.9787+32.5453 147050059787164914 4 0.009179045509852305
243+
PSO J005.9722+32.5418 147050059721440704 4 0.007171813230776031
244+
PSO J005.9857+32.5377 147040059855825725 4 0.007058815429178634
245+
PSO J005.9810+32.5424 147050059809651427 2 0.006835678269917365
246+
PSO J005.9697+32.5368 147040059697224794 2 0.006654002479439699
247+
PSO J005.9712+32.5330 147040059711340087 4 0.006212461367287632
248+
PSO J005.9747+32.5413 147050059747400181 5 0.0056515210592035965
249+
PSO J005.9775+32.5314 147030059774678271 3 0.004739286624336443
250+
251+
252+
Hubble Source Catalog (HSC) specific queries
253+
============================================
254+
255+
Given an HSC Match ID, return all catalog results.
256+
257+
.. doctest-remote-data::
258+
259+
>>> from astroquery.mast import Catalogs
260+
...
261+
>>> catalog_data = Catalogs.query_object("M10", radius=.02, catalog="HSC")
262+
>>> matchid = catalog_data[0]["MatchID"]
263+
>>> print(matchid)
264+
63980492
265+
>>> matches = Catalogs.query_hsc_matchid(matchid)
266+
>>> print(matches)
267+
CatID MatchID ... cd_matrix
268+
--------- -------- ... ------------------------------------------------------
269+
257195287 63980492 ... -1.38889e-005 -5.26157e-010 -5.26157e-010 1.38889e-005
270+
257440119 63980492 ... -1.38889e-005 -5.26157e-010 -5.26157e-010 1.38889e-005
271+
428373428 63980492 ... -1.10056e-005 5.65193e-010 5.65193e-010 1.10056e-005
272+
428373427 63980492 ... -1.10056e-005 5.65193e-010 5.65193e-010 1.10056e-005
273+
428373429 63980492 ... -1.10056e-005 5.65193e-010 5.65193e-010 1.10056e-005
274+
410574499 63980492 ... -1.10056e-005 1.56577e-009 1.56577e-009 1.10056e-005
275+
410574498 63980492 ... -1.10056e-005 1.56577e-009 1.56577e-009 1.10056e-005
276+
410574497 63980492 ... -1.10056e-005 1.56577e-009 1.56577e-009 1.10056e-005
277+
278+
279+
HSC spectra accessed through this class as well. `~astroquery.mast.CatalogsClass.get_hsc_spectra`
280+
does not take any arguments, and simply loads all HSC spectra.
281+
282+
.. doctest-remote-data::
283+
284+
>>> from astroquery.mast import Catalogs
285+
...
286+
>>> all_spectra = Catalogs.get_hsc_spectra()
287+
>>> print(all_spectra[:10])
288+
ObjID DatasetName MatchID ... PropID HSCMatch
289+
----- -------------------------------------------- -------- ... ------ --------
290+
20010 HAG_J072655.67+691648.9_J8HPAXAEQ_V01.SPEC1D 19657846 ... 9482 Y
291+
20011 HAG_J072655.69+691648.9_J8HPAOZMQ_V01.SPEC1D 19657846 ... 9482 Y
292+
20012 HAG_J072655.76+691729.7_J8HPAOZMQ_V01.SPEC1D 19659745 ... 9482 Y
293+
20013 HAG_J072655.82+691620.0_J8HPAOZMQ_V01.SPEC1D 19659417 ... 9482 Y
294+
20014 HAG_J072656.34+691704.7_J8HPAXAEQ_V01.SPEC1D 19660230 ... 9482 Y
295+
20015 HAG_J072656.36+691704.7_J8HPAOZMQ_V01.SPEC1D 19660230 ... 9482 Y
296+
20016 HAG_J072656.36+691744.9_J8HPAOZMQ_V01.SPEC1D 19658847 ... 9482 Y
297+
20017 HAG_J072656.37+691630.2_J8HPAXAEQ_V01.SPEC1D 19660827 ... 9482 Y
298+
20018 HAG_J072656.39+691630.2_J8HPAOZMQ_V01.SPEC1D 19660827 ... 9482 Y
299+
20019 HAG_J072656.41+691734.9_J8HPAOZMQ_V01.SPEC1D 19656620 ... 9482 Y
300+
301+
302+
Individual or ranges of spectra can be downloaded using the
303+
`~astroquery.mast.CatalogsClass.download_hsc_spectra` function.
304+
305+
.. doctest-remote-data::
306+
307+
>>> from astroquery.mast import Catalogs
308+
...
309+
>>> all_spectra = Catalogs.get_hsc_spectra()
310+
>>> manifest = Catalogs.download_hsc_spectra(all_spectra[100:104]) # doctest: +IGNORE_OUTPUT
311+
Downloading URL https://hla.stsci.edu/cgi-bin/ecfproxy?file_id=HAG_J072704.61+691530.3_J8HPAOZMQ_V01.SPEC1D.fits to ./mastDownload/HSC/HAG_J072704.61+691530.3_J8HPAOZMQ_V01.SPEC1D.fits ... [Done]
312+
Downloading URL https://hla.stsci.edu/cgi-bin/ecfproxy?file_id=HAG_J072704.68+691535.9_J8HPAOZMQ_V01.SPEC1D.fits to ./mastDownload/HSC/HAG_J072704.68+691535.9_J8HPAOZMQ_V01.SPEC1D.fits ... [Done]
313+
Downloading URL https://hla.stsci.edu/cgi-bin/ecfproxy?file_id=HAG_J072704.70+691530.2_J8HPAOZMQ_V01.SPEC1D.fits to ./mastDownload/HSC/HAG_J072704.70+691530.2_J8HPAOZMQ_V01.SPEC1D.fits ... [Done]
314+
Downloading URL https://hla.stsci.edu/cgi-bin/ecfproxy?file_id=HAG_J072704.73+691808.0_J8HPAOZMQ_V01.SPEC1D.fits to ./mastDownload/HSC/HAG_J072704.73+691808.0_J8HPAOZMQ_V01.SPEC1D.fits ... [Done]
315+
...
316+
>>> print(manifest) # doctest: +IGNORE_OUTPUT
317+
Local Path ... URL
318+
-------------------------------------------------------------------- ... ----
319+
./mastDownload/HSC/HAG_J072704.61+691530.3_J8HPAOZMQ_V01.SPEC1D.fits ... None
320+
./mastDownload/HSC/HAG_J072704.68+691535.9_J8HPAOZMQ_V01.SPEC1D.fits ... None
321+
./mastDownload/HSC/HAG_J072704.70+691530.2_J8HPAOZMQ_V01.SPEC1D.fits ... None
322+
./mastDownload/HSC/HAG_J072704.73+691808.0_J8HPAOZMQ_V01.SPEC1D.fits ... None

0 commit comments

Comments
 (0)