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
|
.. _astroquery.esa.xmm_newton:
****************************************************
ESA XMM-Newton Archive (`astroquery.esa.xmm_newton`)
****************************************************
The X-ray Multi-Mirror Mission, XMM-Newton, is an ESA X-ray observatory launched on 10 December 1999.
It carries 3 high-throughput X-ray telescopes with unprecedented effective area and an Optical Monitor,
the first flown on an X-ray observatory.
This package allows the access to the `XMM-Newton Science Archive <https://nxsa.esac.esa.int/nxsa-web/>`__.
It has been developed by the ESAC Science Data Centre (ESDC) with requirements provided by the
XMM-Newton Science Operations Centre.
========
Examples
========
--------------------------
1. Getting XMM-Newton data
--------------------------
.. Skipping becuase the download takes too long
.. doctest-skip::
>>> from astroquery.esa.xmm_newton import XMMNewton
>>>
>>> XMMNewton.download_data('0505720401', level="PPS" ,extension="PDF", instname="M1",
... filename="result0505720401") # doctest: +IGNORE_OUTPUT
Downloading URL https://nxsa.esac.esa.int/nxsa-sl/servlet/data-action-aio?obsno=0505720401&level=PPS&extension=PDF&instname=M1 to result0505720401.tar ...
|==============================================================| 7.4M/7.4M (100.00%) 9s
This will download all PPS files for the observation '0505720401' and instrument MOS1, with 'PDF' extension and
it will store them in a tar called 'result0505720401.tar'. The parameters available are detailed in the API.
For more details of the parameters check the section 3.4 at:
'https://nxsa.esac.esa.int/nxsa-web/#aio'
--------------------------------------
2. Getting XMM-Newton proprietary data
--------------------------------------
To access proprietary data an extra variable is needed in the XMMNewton.download_data method. This variabe is prop which
can be True or False. If True a username and password is needed. A username and password can be passed by adding another
variable to the XMMNewton.download_data method called credentials_file. This variable is a string with the path to
~/.astropy/config/astroquery.cfg file. Inside this file add your desired username and password, e.g.
.. code-block::
[xmm_newton]
username = your_username
password = your_password
If the credentials_file variable is not provided the method will ask for the username and password to be added manually
from the commandline
.. Skipping proprietary example
.. doctest-skip::
>>> from astroquery.esa.xmm_newton import XMMNewton
>>>
>>> XMMNewton.download_data('0505720401', level="PPS", extension="PDF", instname="M1",
... filename="result0505720401.tar", prop=True)
INFO: File result0505720401.tar downloaded to current directory [astroquery.esa.xmm_newton.core]
This will download all PPS files for the observation '0505720401' and instrument MOS1, with 'PDF' extension and any
proprietary data. It will store them in a tar called 'result0505720401.tar'.
-------------------------------
3. Getting XMM-Newton postcards
-------------------------------
.. doctest-remote-data::
>>> from astroquery.esa.xmm_newton import XMMNewton
>>>
>>> XMMNewton.get_postcard('0505720401') # doctest: +IGNORE_OUTPUT
INFO: File P0505720401EPX000OIMAGE8000.PNG downloaded to current directory [astroquery.esa.xmm_newton.core]
'P0505720401EPX000OIMAGE8000.PNG'
This will download the EPIC postcard for the observation '0505720401' and it will stored in a PNG called
'P0505720401EPX000OIMAGE8000.PNG'.
------------------------------------------
4. Getting XMM-Newton metadata through TAP
------------------------------------------
This function provides access to the XMM-Newton Science Archive database using the Table Access Protocol (TAP) and via the Astronomical Data
Query Language (ADQL).
.. doctest-remote-data::
>>> from astroquery.esa.xmm_newton import XMMNewton
>>>
>>> result = XMMNewton.query_xsa_tap("select top 10 * from v_public_observations",
... output_format='csv', output_file='results10.csv')
>>> print(result) # doctest: +IGNORE_OUTPUT
bii dec duration ... target with_science
-------------------- --------- -------- ... ---------------- ------------
4.1331178178373715 55.99944 32913 ... XTE J0421+560 true
0.05069186370709437 -32.58167 17083 ... HD159176 true
0.05069186370709437 -32.58167 9362 ... HD159176 true
0.05069186370709437 -32.58167 10859 ... HD159176 true
-0.31119608673831345 6.135278 21939 ... HD47129 true
-0.31119608673831345 6.135278 21863 ... HD47129 true
-51.687075256085755 10.68917 26609 ... IRAS F00235+1024 true
73.04737400339847 10.18639 25192 ... IRAS F12514+1027 true
46.71747372703565 -15.78639 12101 ... Denis-J1228 true
-15.881772371450268 -77.61555 33986 ... Cha-Ha-3 true
This will execute an ADQL query to download the first 10 observations in the XMM-Newton Science Archive. The result of the query will be
stored in the file 'results10.csv'. The result of this query can be printed by doing print(result).
-----------------------------------
5. Getting table details of XSA TAP
-----------------------------------
.. doctest-remote-data::
>>> from astroquery.esa.xmm_newton import XMMNewton
>>> XMMNewton.get_tables()
INFO: Retrieving tables... [astroquery.utils.tap.core]
INFO: Parsing tables... [astroquery.utils.tap.core]
INFO: Done. [astroquery.utils.tap.core]
['public.dual', 'tap_config.coord_sys', 'tap_config.properties', 'tap_schema.columns',
'tap_schema.key_columns', 'tap_schema.keys', 'tap_schema.schemas',
'tap_schema.tables', 'xsa.v_all_observations', 'xsa.v_epic_source',
'xsa.v_epic_source_cat', 'xsa.v_epic_xmm_stack_cat', 'xsa.v_exposure',
'xsa.v_instrument_mode', 'xsa.v_om_source', 'xsa.v_om_source_cat',
'xsa.v_proposal', 'xsa.v_proposal_observation_info', 'xsa.v_publication',
'xsa.v_publication_observation', 'xsa.v_publication_slew_observation',
'xsa.v_public_observations', 'xsa.v_public_observations_new_odf_ingestion',
'xsa.v_public_observations_new_pps_ingestion', 'xsa.v_rgs_source',
'xsa.v_slew_exposure', 'xsa.v_slew_observation', 'xsa.v_slew_source',
'xsa.v_slew_source_cat', 'xsa.v_target_type', 'xsa.v_uls_exposure_image',
'xsa.v_uls_slew_exposure_image']
This will show the available tables in XSA TAP service in the XMM-Newton Science Archive.
-------------------------------------
6. Getting columns details of XSA TAP
-------------------------------------
.. doctest-remote-data::
>>> from astroquery.esa.xmm_newton import XMMNewton
>>> XMMNewton.get_columns('xsa.v_all_observations')
INFO: Retrieving tables... [astroquery.utils.tap.core]
INFO: Parsing tables... [astroquery.utils.tap.core]
INFO: Done. [astroquery.utils.tap.core]
['bii', 'citext', 'dec', 'duration', 'end_utc', 'footprint_fov', 'heasarc_code', 'lii', 'moving_target',
'observation_equatorial_spoint', 'observation_fov_scircle', 'observation_galactic_spoint', 'observation_id',
'observation_oid', 'odf_proc_date', 'odf_version', 'position_angle', 'pps_proc_date', 'pps_version', 'proposal_id',
'proposal_oid', 'proprietary_end_date', 'ra', 'ra_nom', 'revolution', 'sas_version', 'seq_id', 'start_utc', 'stc_s', 'with_science']
This will show the column details of the table 'v_all_observations' in XSA TAP service in the XMM-Newton Science Archive.
--------------------------------------------
7. Getting EPIC images from a given TAR file
--------------------------------------------
.. Skipping becuase the download takes too long
.. doctest-skip::
>>> from astroquery.esa.xmm_newton import XMMNewton
>>>
>>> XMMNewton.download_data('0405320501') # doctest: +IGNORE_OUTPUT
Downloading URL http://nxsa.esac.esa.int/nxsa-sl/servlet/data-action-aio?obsno=0405320501 to 0405320501.tar ...
|===================================================================================================================================================| 540M/540M (100.00%) 57s
>>> XMMNewton.get_epic_images('0405320501.tar', band=[1,2], instrument=['M1'])
{1: {'M1': '/home/esa/0405320501/pps/P0405320501M1S002IMAGE_1000.FTZ'}, 2: {'M1': '/home/esa/0405320501/pps/P0405320501M1S002IMAGE_2000.FTZ'}}
This will extract the European Photon Imaging Camera (EPIC) images within the specified TAR file, bands, and instruments. It will also return a dictionary containing the paths to the extracted files.
------------------------------------------------------------------------------
8. Getting the European Photon Imaging Camera (EPIC) metadata from the XSA TAP
------------------------------------------------------------------------------
This function retrieves the EPIC metadata from a given target.
The target must be defined with either a source name or a `~astropy.coordinates.SkyCoord` object.
The EPIC metadata can be found in four tables in the XSA TAP:
- xsa.v_epic_source
- xsa.v_epic_source_cat
- xsa.v_epic_xmm_stack_cat
- xsa.v_slew_source_cat
.. doctest-remote-data::
>>> from astroquery.esa.xmm_newton import XMMNewton
>>> epic_source, cat_4xmm, stack_4xmm, slew_source = XMMNewton.get_epic_metadata(target_name="4XMM J122934.7+015657")
This will return the metadata within the four TAP tables in four `~astropy.table.Table` for the given target.
Troubleshooting
===============
If you are repeatedly getting failed queries, or bad/out-of-date results, try clearing your cache:
.. code-block:: python
>>> from astroquery.esa.xmm_newton import XMMNewton
>>> XMMNewton.clear_cache()
If this function is unavailable, upgrade your version of astroquery.
The ``clear_cache`` function was introduced in version 0.4.7.dev8479.
Reference/API
=============
.. automodapi:: astroquery.esa.xmm_newton
:no-inheritance-diagram:
|
