XMM-Newton

ESA XMM-Newton Science Archive.

Module name: xmm_newton
Python class: astroquery.esa.xmm_newton.XMMNewton
Functions: 11

Call any function below with the astroquery_execute MCP tool. Descriptions are taken from the upstream astroquery/astropy docstrings.

Function	Summary
`clear_cache`	Removes all cache files.
`download_data`	Download data from XMM-Newton
`get_columns`	Get the available columns for a table in XSA TAP service
`get_epic_images`	Extracts the EPIC images from a given TAR file
`get_epic_lightcurve`	Extracts the EPIC sources light curve products from a given TAR file
`get_epic_metadata`	Downloads the European Photon Imaging Camera (EPIC)
`get_epic_spectra`	Extracts in path (when set) the EPIC sources spectral products from a
`get_postcard`	Download postcards from XSA
`get_tables`	Get the available table in XSA TAP service
`query_xsa_tap`	Launches a synchronous job to query the XSA tap
`reset_cache_location`	Resets the cache location to the default astropy cache

Functions

`clear_cache`

Call via MCP

astroquery_execute(
    module_name="xmm_newton",
    function_name="clear_cache",
    params={},
)

XMMNewtonClass.clear_cache(): Removes all cache files.

`download_data`

Call via MCP

astroquery_execute(
    module_name="xmm_newton",
    function_name="download_data",
    params={"observation_id": "<observation_id>"},
)

XMMNewtonClass.download_data(observation_id, *, filename=None, verbose=False, cache=True, prop=False, credentials_file=None, **kwargs)

Download data from XMM-Newton

Parameters:

observation_id (string) – id of the observation to be downloaded, mandatory The identifier of the observation we want to retrieve, 10 digits example: 0144090201
filename (string) – file name to be used to store the file
verbose (bool) – optional, default ‘False’ flag to display information about the process
prop (boolean) – optional, default ‘False’ flag to download proprietary data, the method will then ask the user to input their username and password either manually or using the credentials_file
credentials_file (string) – optional, default None path to where the users config.ini file is stored with their username and password
level (string) – level to download, optional, by default everything is downloaded values: ODF, PPS
instname (string) – instrument name, optional, two characters, by default everything values: OM, R1, R2, M1, M2, PN
instmode (string) – instrument mode, optional examples: Fast, FlatFieldLow, Image, PrimeFullWindow
filter (string) – filter, optional examples: Closed, Open, Thick, UVM2, UVW1, UVW2, V
expflag (string) – exposure flag, optional, by default everything values: S, U, X(not applicable)
expno (integer) – exposure number with 3 digits, by default all exposures examples: 001, 003
name (string) – product type, optional, 6 characters, by default all product types examples: 3COLIM, ATTTSR, EVENLI, SBSPEC, EXPMAP, SRCARF
datasubsetno (character) – data subset number, optional, by default all examples: 0, 1
sourceno (hex value) – source number, optional, by default all sources example: 00A, 021, 001
extension (string) – file format, optional, by default all formats values: ASC, ASZ, FTZ, HTM, IND, PDF, PNG
cache (bool) – Defaults to True. If set overrides global caching behavior. See caching documentation.

Returns:

None if not verbose. It downloads the observation indicated
If verbose returns the filename

`get_columns`

Call via MCP

astroquery_execute(
    module_name="xmm_newton",
    function_name="get_columns",
    params={"table_name": "<table_name>"},
)

XMMNewtonClass.get_columns(table_name, *, only_names=True, verbose=False)

Get the available columns for a table in XSA TAP service

Parameters:

table_name (string, mandatory, default None) – table name of which, columns will be returned
only_names (bool, TAP+ only, optional, default 'True') – True to load table names only
verbose (bool, optional, default 'False') – flag to display information about the process

Return type:

A list of columns

`get_epic_images`

Call via MCP

astroquery_execute(
    module_name="xmm_newton",
    function_name="get_epic_images",
    params={"filename": "<filename>"},
)

XMMNewtonClass.get_epic_images(filename, band=[], instrument=[], get_detmask=False, get_exposure_map=False, path='', **kwargs)

Extracts the EPIC images from a given TAR file

This function extracts the EPIC images in a given band (or bands) and instrument (or instruments) from it

The result is a dictionary containing the paths to the extracted EPIC images with keys being the band and the instrument

If the band or the instrument are not specified this function will return all the available bands and instruments

Additionally, get_detmask and get_exposure_map can be set to True. If so, this function will also extract the exposure maps and detector masks within the specified bands and instruments

Parameters:

filename (string, mandatory) – The name of the tarfile to be proccessed
band (array of integers, optional, default []) – An array of intergers indicating the desired bands
instruments (array of strings, optional, default []) – An array of strings indicating the desired instruments
get_detmask (bool, optional) – If True, also extracts the detector masks
get_exposure_map (bool, optional) – If True, also extracts the exposure maps
path (string, optional) – If set, extracts the EPIC images in the indicated path

Returns:

A dictionary of dictionaries with the full paths of the extracted
EPIC images. The keys of each dictionary are the band for the first
level dictionary and the instrument for the second level dictionaries

Notes

The structure and the content of the extracted compressed FITS files are described in details in the Pipeline Products Description [XMM-SOC-GEN-ICD-0024](https://xmm-tools.cosmos.esa.int/external/xmm_obs_info/odf/data/docs/XMM-SOC-GEN-ICD-0024.pdf).

`get_epic_lightcurve`

Call via MCP

astroquery_execute(
    module_name="xmm_newton",
    function_name="get_epic_lightcurve",
    params={"filename": "<filename>", "source_number": "<source_number>"},
)

XMMNewtonClass.get_epic_lightcurve(filename, source_number, *, instrument=[], path='')

Extracts the EPIC sources light curve products from a given TAR file

For a given TAR file obtained with XMMNewton.download_data.

This function extracts the EPIC sources light curve products in a given instrument (or instruments) from said TAR file

The result is a dictionary containing the paths to the extracted EPIC sources light curve products with the key being the instrument

If the instrument is not specified, this function will return all available instruments

Parameters:

filename (string, mandatory) – The name of the tarfile to be proccessed
source_number (integer, mandatory) – The source number, in decimal, in the observation
instruments (array of strings, optional, default []) – An array of strings indicating the desired instruments
path (string, optional) – If set, extracts the EPIC images in the indicated path

Returns:

A dictionary with the full paths of the extracted EPIC sources
light curve products. The key is the instrument

Notes

The filenames will contain the source number in hexadecimal, as this is the convention used by the pipeline.

The structure and the content of the extracted compressed FITS files are described in details in the Pipeline Products Description [XMM-SOC-GEN-ICD-0024](https://xmm-tools.cosmos.esa.int/external/xmm_obs_info/odf/data/docs/XMM-SOC-GEN-ICD-0024.pdf).

`get_epic_metadata`

Call via MCP

astroquery_execute(
    module_name="xmm_newton",
    function_name="get_epic_metadata",
    params={},
)

XMMNewtonClass.get_epic_metadata(*, target_name=None, coordinates=None, radius=None)

Downloads the European Photon Imaging Camera (EPIC) metadata from a given target

Parameters:

target_name (string, optional, default None) – The name of the target
coordinates (SkyCoord, optinal, default None) – The coordinates of the target in a SkyCoord object
radius (float, optional, default None) – The radius to query the target in degrees

Returns:

epic_source, cat_4xmm, stack_4xmm, slew_source – Tables containing the metadata of the target

Return type:

Table objects

`get_epic_spectra`

Call via MCP

astroquery_execute(
    module_name="xmm_newton",
    function_name="get_epic_spectra",
    params={"filename": "<filename>", "source_number": "<source_number>"},
)

XMMNewtonClass.get_epic_spectra(filename, source_number, *, instrument=[], path='', verbose=False)

Extracts in path (when set) the EPIC sources spectral products from a given TAR file.

This function extracts the EPIC sources spectral products in a given instrument (or instruments) from it The result is a dictionary containing the paths to the extracted EPIC sources spectral products with key being the instrument If the instrument is not specified this function will return all the available instruments

Parameters:

filename (string, mandatory) – The name of the tarfile to be processed
source_number (integer, mandatory) – The source number, in decimal, in the observation
instruments (array of strings, optional, default []) – An array of strings indicating the desired instruments
path (string, optional) – If set, extracts the EPIC images in the indicated path
verbose (bool) – optional, default ‘False’ flag to display information about the process

Returns:

A dictionary with the full paths of the extracted EPIC sources
spectral products. The key is the instrument

Notes

The filenames will contain the source number in hexadecimal, as this is the convention used by the pipeline. The structure and the content of the extracted compressed FITS files are described in details in the Pipeline Products Description [XMM-SOC-GEN-ICD-0024] (https://xmm-tools.cosmos.esa.int/external/xmm_obs_info/odf/data/docs/XMM-SOC-GEN-ICD-0024.pdf).

The RMF to be used for the spectral analysis should be generated with the same PPS version as the spectrum, background and ARF. The PPS version can be found in SASVERS keyword in the SPECTRUM file, characters [-6:-3]. Once the sas version is determined, the code should look for the proper version of RMF in the FTP tree. However, for the current PPS versions available in the archive, i.e v18.0, v19.0, v20.0 and v21.0, all RMF matrices are equal among the versions and for all instruments, so it is possible to download the last one, v21.0, available in the root FTP stored in ‘rmf_ftp’. In the future, the FTP tree and/or PPS keywords will be modified to make it easier to download the appropriate RMF file for each spectrum.

`get_postcard`

Call via MCP

astroquery_execute(
    module_name="xmm_newton",
    function_name="get_postcard",
    params={"observation_id": "<observation_id>"},
)

XMMNewtonClass.get_postcard(observation_id, *, image_type='OBS_EPIC', filename=None, verbose=False)

Download postcards from XSA

Parameters:

observation_id (string) – id of the observation for which download the postcard, mandatory The identifier of the observation we want to retrieve, regardless of whether it is simple or composite.
image_type (string) – image type, optional, default ‘OBS_EPIC’ The image_type to be returned. It can be: OBS_EPIC, OBS_RGS_FLUXED, OBS_RGS_FLUXED_2, OBS_RGS_FLUXED_3, OBS_EPIC_MT, OBS_RGS_FLUXED_MT, OBS_OM_V, OBS_OM_B, OBS_OM_U, OBS_OM_L, OBS_OM_M, OBS_OM_S, OBS_OM_W
filename (string) – file name to be used to store the postcard, optional, default None
verbose (bool) – optional, default ‘False’ Flag to display information about the process

Return type:

None. It downloads the observation postcard indicated

`get_tables`

Call via MCP

astroquery_execute(
    module_name="xmm_newton",
    function_name="get_tables",
    params={},
)

XMMNewtonClass.get_tables(*, only_names=True, verbose=False)

Get the available table in XSA TAP service

Parameters:

only_names (bool, TAP+ only, optional, default 'True') – True to load table names only
verbose (bool, optional, default 'False') – flag to display information about the process

Return type:

A list of tables

`query_xsa_tap`

Call via MCP

astroquery_execute(
    module_name="xmm_newton",
    function_name="query_xsa_tap",
    params={"query": "<query>"},
)

XMMNewtonClass.query_xsa_tap(query, *, output_file=None, output_format='votable', verbose=False)

Launches a synchronous job to query the XSA tap

Parameters:

query (str, mandatory) – query (adql) to be executed
output_file (str, optional, default None) – file name where the results are saved if dumpToFile is True. If this parameter is not provided, the jobid is used instead
output_format (str, optional, default 'votable') – possible values ‘votable’ or ‘csv’
verbose (bool, optional, default 'False') – flag to display information about the process

Return type:

A table object

`reset_cache_location`

Call via MCP

astroquery_execute(
    module_name="xmm_newton",
    function_name="reset_cache_location",
    params={},
)

XMMNewtonClass.reset_cache_location(): Resets the cache location to the default astropy cache

XMM-Newton

Functions

clear_cache

download_data

get_columns

get_epic_images

get_epic_lightcurve

get_epic_metadata

get_epic_spectra

get_postcard

get_tables

query_xsa_tap

reset_cache_location

`clear_cache`

`download_data`

`get_columns`

`get_epic_images`

`get_epic_lightcurve`

`get_epic_metadata`

`get_epic_spectra`

`get_postcard`

`get_tables`

`query_xsa_tap`

`reset_cache_location`