.. _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 <http://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:
		'http://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]
  ['tap_config.coord_sys', 'tap_config.properties', 'tap_schema.columns',
   'tap_schema.key_columns', 'tap_schema.keys', 'tap_schema.schemas',
   'tap_schema.tables', 'xsa.dual', '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:
