1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
|
.. _astroquery.mocserver:
****************************************
CDS MOC Service (`astroquery.mocserver`)
****************************************
Getting started
===============
This module provides a python interface for querying the `CDS MOCServer`_.
What's a MOC?
-------------
MOC means Multi-Order Coverage. It's an `IVOA standard`_ that allows to describe
Space-Time coverages of arbitrary sky regions, with or without an associated time of
observation.
The space component maps the sky with the `HEALPix sky tessellation
<https://arxiv.org/abs/astro-ph/9905275>`_ to represent regions on the sky
by hierarchically grouped HEALPix cells. It other words, a Spatial MOC is a set of
HEALPix cells at different orders.
The idea is the same for Time MOCs. The time axis is split into time cells.
For those wanting to know more about MOCs, please refer to `the MOC 2.0 specification
document <https://ivoa.net/documents/MOC/20220727/REC-moc-2.0-20220727.pdf>`_.
`MOCPy <https://github.com/cds-astro/mocpy>`_ is a Python library allowing to manipulate
these Space-Time Coverage objects. You're welcome to have a look at
`MOCPy's documentation <https://cds-astro.github.io/mocpy/>`_.
What's the MOC Server?
----------------------
The MOC Server is a service of astronomical resources organized by spatial and/or
temporal coverages following the Space and Time MOC specification.
In the MOC Server, there a few tens of thousands of astronomical collections.
They each have an identifier ``ID`` and a set of properties that describe their content.
This is a practical way of finding datasets with criteria on time and/or space.
The meta data properties are freely assigned by each publisher. You can get the current
list of properties with their frequency of usage and examples example with
`astroquery.mocserver.MOCServerClass.list_fields`.
This method also accepts a string to limit the number of responses. Let's try with ``MOC``:
..
We ignore output here, as occurrence is changing often
.. doctest-requires:: mocpy
>>> from astroquery.mocserver import MOCServer
>>> MOCServer.list_fields("MOC") # doctest: +IGNORE_OUTPUT +REMOTE_DATA
<Table length=7>
field_name occurrence example
str27 int64 str70
---------------- ---------- ----------------------------------------------------------------------
moc_type 34226 smoc
moc_access_url 33084 https://alasky.unistra.fr/footprints/tables/vizier/J_AJ_165_248_tab...
moc_sky_fraction 30175 4.271E-6
moc_order 30161 11
moc_time_range 5319 5491
moc_time_order 5319 35
moc_release_date 4 2015-02-25T11:51Z
Here, we learn that there are very few MOC-related field names. The most frequent is
``moc_type`` that will tell if the MOC is a spatial moc (``smoc``), a temporal moc
(``tmoc``)...
Querying with a region
======================
The MOCServer is optimized to return the datasets having at least one source lying in a
specific sky region (or time interval).
The regions can be provided either as astropy-regions from the
`regions <https://astropy-regions.readthedocs.io/en/stable/>`_ python library,
or as an accepted MOC type (`mocpy.TimeMOC`, `mocpy.MOC`, `~mocpy.STMOC`).
The frequency MOCs are not yet available.
Performing a query on a cone region
-----------------------------------
Let's get the datasets for which all the data is comprised in a cone (this is
what the ``enclosed`` option means for intersect). We also restrict our search to
datasets describing the sky (with ``coordinate_system=sky``).
.. doctest-requires:: mocpy
>>> from astropy import coordinates
>>> from regions import CircleSkyRegion
>>> from astroquery.mocserver import MOCServer
>>> center = coordinates.SkyCoord(10.8, 32.2, unit='deg')
>>> radius = coordinates.Angle(0.5, unit='deg')
>>> cone = CircleSkyRegion(center, radius)
>>> MOCServer.query_region(region=cone, intersect="enclosed", coordinate_system="sky") # doctest: +IGNORE_OUTPUT +REMOTE_DATA
<Table length=450>
ID ...
str49 ...
------------------------------ ...
CDS/C/GALFAHI/Narrow ...
CDS/C/GALFAHI/Narrow/DR2 ...
CDS/C/GALFAHI/Wide/DR2 ...
CDS/C/HI4PI/HI ...
CDS/I/220/out ...
CDS/I/243/out ...
CDS/I/252/out ...
CDS/I/254/out ...
CDS/I/255/out ...
... ...
ov-gso/P/WHAM ...
simg.de/P/NSNS/DR0_1/halpha ...
simg.de/P/NSNS/DR0_1/halpha8 ...
simg.de/P/NSNS/DR0_1/hbr8 ...
simg.de/P/NSNS/DR0_1/sn-halpha ...
simg.de/P/NSNS/DR0_1/sn-vc ...
simg.de/P/NSNS/DR0_1/tc8 ...
simg.de/P/NSNS/DR0_1/vc ...
wfau.roe.ac.uk/P/UHSDR1/J ...
wfau.roe.ac.uk/UHSDR1/J ...
You can also use this method with `regions.PolygonSkyRegion`, `mocpy.MOC`, `mocpy.TimeMOC`,
and `mocpy.STMOC`. Not providing the region parameter means that the search is done on
the whole sky (or the whole planet, if we chose a different ``coordinate_system``).
Querying by meta-data
=====================
Retrieving datasets based on their meta-data values
----------------------------------------------------
The ``criteria`` parameter of :meth:`~astroquery.mocserver.MOCServerClass.query_region`
allows to write an expression on the dataset's metadata to filter the output.
Let's add a criteria to get only images from the previous query:
.. doctest-requires:: mocpy
>>> from astropy import coordinates
>>> from regions import CircleSkyRegion
>>> from astroquery.mocserver import MOCServer
>>> center = coordinates.SkyCoord(10.8, 32.2, unit='deg')
>>> radius = coordinates.Angle(0.5, unit='deg')
>>> cone = CircleSkyRegion(center, radius)
>>> MOCServer.query_region(region=cone, intersect="enclosed",
... fields=['ID', 'dataproduct_type', 'moc_sky_fraction'],
... criteria="dataproduct_type=image") # doctest: +IGNORE_OUTPUT +REMOTE_DATA
<Table length=336>
ID dataproduct_type moc_sky_fraction
str49 str5 float64
------------------------------ ---------------- ----------------
CDS/P/2MASS/H image 1.0
CDS/P/2MASS/J image 1.0
CDS/P/2MASS/K image 1.0
CDS/P/2MASS/color image 1.0
CDS/P/AKARI/FIS/Color image 1.0
CDS/P/AKARI/FIS/N160 image 1.0
CDS/P/AKARI/FIS/N60 image 1.0
CDS/P/AKARI/FIS/WideL image 1.0
CDS/P/AKARI/FIS/WideS image 1.0
... ... ...
ov-gso/P/RASS/SoftBand image 1.0
ov-gso/P/WHAM image 1.0
simg.de/P/NSNS/DR0_1/halpha image 0.6464
simg.de/P/NSNS/DR0_1/halpha8 image 0.6464
simg.de/P/NSNS/DR0_1/hbr8 image 0.651
simg.de/P/NSNS/DR0_1/sn-halpha image 0.6466
simg.de/P/NSNS/DR0_1/sn-vc image 0.6466
simg.de/P/NSNS/DR0_1/tc8 image 0.651
simg.de/P/NSNS/DR0_1/vc image 0.6464
wfau.roe.ac.uk/P/UHSDR1/J image 0.3083
Looking at the ``dataproduct_type`` column, all the datasets are indeed images. There
are a few less results than when we did not apply this additional criteria.
Other examples for filtering expressions can be found on the `help page of the MOC Server
web interface <http://alasky.unistra.fr/MocServer/example>`_.
Let's do a search on the whole sky by omitting the region parameter.
The next example retrieves all the ``moc_access_url`` of datasets having ``HST`` in
their identifier. These correspond to the Hubble surveys:
.. doctest-requires:: mocpy
>>> MOCServer.query_region(criteria="ID=*HST*",
... fields=['ID', 'moc_access_url'],
... casesensitive=False) # doctest: +IGNORE_OUTPUT +REMOTE_DATA
<Table length=45>
ID moc_access_url
str26 str51
-------------------------- ---------------------------------------------------
CDS/P/HST-programs/3D-DASH --
CDS/P/HST/B --
CDS/P/HST/CO --
CDS/P/HST/EPO --
CDS/P/HST/GOODS/b http://alasky.unistra.fr/GOODS/GOODSb/Moc.fits
CDS/P/HST/GOODS/color http://alasky.unistra.fr/GOODS/GOODS-color/Moc.fits
CDS/P/HST/GOODS/i http://alasky.unistra.fr/GOODS/GOODSi/Moc.fits
CDS/P/HST/GOODS/v http://alasky.unistra.fr/GOODS/GOODSv/Moc.fits
CDS/P/HST/GOODS/z http://alasky.unistra.fr/GOODS/GOODSz/Moc.fits
... ...
CDS/P/HST/Y --
CDS/P/HST/other --
CDS/P/HST/wideUV --
CDS/P/HST/wideV --
ESAVO/P/HST/ACS-blue --
ESAVO/P/HST/FOC --
ESAVO/P/HST/NICMOS --
ESAVO/P/HST/WFC3 --
ESAVO/P/HST/WFPC --
ESAVO/P/HST/WFPC2 --
Query for Hierarchical Progressive Surveys (HiPS)
=================================================
The MOCServer contains an extensive list of `HiPS <https://ivoa.net/documents/HiPS/>`_,
for images and catalogs. These progressive surveys can be displayed in applications
such as `ipyaladin <https://github.com/cds-astro/ipyaladin>`_. The
`astroquery.mocserver.MOCServerClass.query_hips` method allows to find these HiPS.
It accepts the same parameters (``region`` and ``criteria`` for example) as the other
methods. The only difference is that the output will only contain HiPS data.
.. doctest-requires:: mocpy
>>> from astroquery.mocserver import MOCServer
>>> MOCServer.query_hips(coordinate_system="mars") # doctest: +IGNORE_OUTPUT +REMOTE_DATA
<Table length=25>
ID ...
str35 ...
----------------------------------- ...
CDS/P/Mars/Express286545 ...
CDS/P/Mars/MGS-MOLA-DEM ...
CDS/P/Mars/MGS-TES-Dust ...
CDS/P/Mars/MOLA-color ...
CDS/P/Mars/MRO-CTX ...
CDS/P/Mars/TES-Albedo ...
CDS/P/Mars/TES-Thermal-Inertia ...
CDS/P/Mars/THEMIS-Day-100m-v12 ...
CDS/P/Mars/THEMIS-IR-Night-100m-v14 ...
... ...
idoc/P/omega/emissivite_5-03mic ...
idoc/P/omega/emissivite_5-05mic ...
idoc/P/omega/emissivite_5-07mic ...
idoc/P/omega/emissivite_5-09mic ...
idoc/P/omega/ferric_bd530 ...
idoc/P/omega/ferric_nnphs ...
idoc/P/omega/olivine_osp1 ...
idoc/P/omega/olivine_osp2 ...
idoc/P/omega/olivine_osp3 ...
idoc/P/omega/pyroxene_bd2000 ... doi:10.1029/2012JE004117 ... omega pyroxene_bd2000
Here, we see that there are currently 25 HiPS surveys for the planet Mars available in
the MOCServer.
Personalization of the queries
==============================
Changing the default fields
---------------------------
By default, :meth:`~astroquery.mocserver.MOCServerClass.query_region` returns an
`astropy.table.Table` with information about the matching datasets. The default fields
are ``ID``, ``obs_title``, ``obs_description``, ``nb_rows``, ``obs_regime``,
``bib_reference``, and ``dataproduct_type``.
To change this default behavior, use the ``fields`` parameter.
Let's say we would like only the ``ID``, and the ``moc_sky_fraction`` for this query:
.. doctest-requires:: mocpy
>>> from astropy import coordinates
>>> from regions import CircleSkyRegion
>>> from astroquery.mocserver import MOCServer
>>> center = coordinates.SkyCoord(10.8, 32.2, unit='deg')
>>> radius = coordinates.Angle(0.5, unit='deg')
>>> cone = CircleSkyRegion(center, radius)
>>> MOCServer.query_region(region=cone,
... intersect="enclosed",
... fields=['ID', 'moc_sky_fraction']) # doctest: +IGNORE_OUTPUT +REMOTE_DATA
<Table length=450>
ID moc_sky_fraction
str49 float64
CDS/I/220/out 0.9697
CDS/I/243/out 1.0
CDS/I/252/out 0.9993
CDS/I/254/out 1.0
CDS/I/255/out 0.9696
... ...
ov-gso/P/WHAM 1.0
simg.de/P/NSNS/DR0_1/halpha 0.6464
simg.de/P/NSNS/DR0_1/halpha8 0.6464
simg.de/P/NSNS/DR0_1/hbr8 0.651
simg.de/P/NSNS/DR0_1/sn-halpha 0.6466
We now see in a single glance that the dataset ``CDS/I/220/out`` covers almost all the
sky!
Limiting the number of returned datasets
----------------------------------------
Another parameter called ``max_rec`` specifies an upper limit for the number of data-sets to be returned:
.. doctest-requires:: mocpy
>>> from astroquery.mocserver import MOCServer
>>> from mocpy import MOC
>>> MOCServer.query_region(region=MOC.from_string("5/22-24"), max_rec=3) # doctest: +IGNORE_OUTPUT +REMOTE_DATA
<Table length=3>
ID ... dataproduct_type
str24 ... str7
------------------------ ... ----------------
CDS/J/AJ/156/102/table9 ... catalog
CDS/J/ApJS/257/54/table1 ... catalog
CDS/III/39A/catalog ... catalog
This result has only 3 rows although we know that more datasets match the query.
The result will come faster than requesting all results.
Returning a ``mocpy`` object as a result
----------------------------------------
If you want the union of all the MOCs of the datasets matching the query, you can
get the result as a `mocpy.MOC`, `mocpy.TimeMOC`, or `mocpy.STMOC` object instead of an
`astropy.table.Table` by setting the parameter ``return_moc`` to ``smoc``, ``tmoc``, or
``stmoc``. An additional parameter ``max_norder`` allows to set the resolution/precision
of the returned MOC.
As an example, we would like to obtain the union of the space coverage of all the
Hubble surveys:
.. doctest-requires:: mocpy
>>> from mocpy import MOC
>>> import matplotlib.pyplot as plt
>>> from astroquery.mocserver import MOCServer
>>> moc = MOCServer.query_region(return_moc="smoc",
... max_norder=20,
... criteria="ID=*HST*") # doctest: +REMOTE_DATA
The resulting MOC looks like:
.. image:: HST_union.png
Retrieve the `~mocpy.STMOC` of a specific dataset
-------------------------------------------------
To retrieve the MOC of a specific dataset, we can use
`~astroquery.mocserver.MOCServerClass.query_region`.
This example will show you how to get the space-time MOC (i.e. a `mocpy.STMOC`
object) of the ``GALEXGR6/AIS/FUV`` survey.
.. doctest-requires:: mocpy
>>> from mocpy import MOC
>>> from astroquery.mocserver import MOCServer
>>> moc_galex = MOCServer.query_region(criteria="ID=CDS/P/GALEXGR6/AIS/FUV",
... return_moc="stmoc", max_norder="s7 t26") # doctest: +REMOTE_DATA
>>> print(f"GALEX GR6 contains data taken from {moc_galex.min_time.iso} to"
... f" {moc_galex.max_time.iso}.") # doctest: +REMOTE_DATA
GALEX GR6 contains data taken from 2010-03-31 18:02:05.602 to 2010-06-01 18:57:24.787.
.. note::
Note that for Space-Time MOCs the ``max_norder`` parameter is not an integer but a
string that contains the information about both the spatial order and the time order.
Here, we requested a spatial order of 7 (roughly 27') and a time order of 26 (roughly
9 hours).
Finding data on a specific solar system body
--------------------------------------------
The default value for ``coordinate_system`` is ``None``. It means that we're looking for
data for the sky and all other possible frames. This parameter can take all the values
listed by `astroquery.mocserver.MOCServerClass.list_coordinate_systems`:
.. doctest-requires:: mocpy
>>> from astroquery.mocserver import MOCServer
>>> MOCServer.list_coordinate_systems() # doctest: +REMOTE_DATA
['ariel', 'callisto', 'ceres', 'charon', 'dione', 'earth', 'enceladus', 'equatorial', 'europa', 'galactic', 'ganymede', 'iapetus', 'io', 'jupiter', 'mars', 'mars-pia20284', 'mars-pia24422', 'mars-stimson', 'mercury', 'mimas', 'miranda', 'moon', 'moon-pan1', 'neptune', 'oberon', 'pluto', 'rhea', 'sky', 'sun', 'tethys', 'titan', 'titania', 'triton', 'umbriel', 'venus']
Where the special value ``sky`` means any celestial frame (mainly ``equatorial`` and
``galactic``).
The ``coordinate_system`` parameter can be used in any of the query methods like so:
.. doctest-requires:: mocpy
>>> from astroquery.mocserver import MOCServer
>>> MOCServer.query_hips(coordinate_system="ariel") # doctest: +REMOTE_DATA
<Table length=1>
ID obs_title ... dataproduct_type
str19 str13 ... str5
------------------- ------------- ... ----------------
CDS/P/Ariel/Voyager Ariel Voyager ... image
Reference/API
=============
.. automodapi:: astroquery.mocserver
:no-inheritance-diagram:
.. _CDS MOCServer: http://alasky.unistra.fr/MocServer/query
.. _IVOA standard: http://ivoa.net/documents/MOC/20140602/REC-MOC-1.0-20140602.pdf
|
