astro query:docs

- Index
- Modules

### Navigation

- next »
- « previous |
- astroquery v0.4.11 »
- ESA XMM-Newton Archive (`astroquery.esa.xmm_newton`) »
- XMMNewtonClass

# XMMNewtonClass

class astroquery.esa.xmm_newton.XMMNewtonClass(tap_handler=None)

  Bases: `BaseQuery`

  Attributes Summary

  `TIMEOUT` |
  `data_aio_url` |
  `data_url` |
  `metadata_url` |

  Methods Summary

  `download_data`(observation_id, *[, filename, ...]) | Download data from XMM-Newton
  `get_columns`(table_name, *[, only_names, verbose]) | Get the available columns for a table in XSA TAP service
  `get_epic_images`(filename[, band, ...]) | Extracts the EPIC images from a given TAR file
  `get_epic_lightcurve`(filename, source_number, *) | Extracts the EPIC sources light curve products from a given TAR file
  `get_epic_metadata`(*[, target_name, ...]) | Downloads the European Photon Imaging Camera (EPIC) metadata from a given target
  `get_epic_spectra`(filename, source_number, *) | Extracts in path (when set) the EPIC sources spectral products from a given TAR file.
  `get_postcard`(observation_id, *[, ...]) | Download postcards from XSA
  `get_tables`(*[, only_names, verbose]) | Get the available table in XSA TAP service
  `query_xsa_tap`(query, *[, output_file, ...]) | Launches a synchronous job to query the XSA tap

  Attributes Documentation

  TIMEOUT = 60
  data_aio_url = 'https://nxsa.esac.esa.int/nxsa-sl/servlet/data-action-aio?'
  data_url = 'https://nxsa.esac.esa.int/nxsa-sl/servlet/data-action?'
  metadata_url = 'https://nxsa.esac.esa.int/nxsa-sl/servlet/metadata-action?'

  Methods Documentation

  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(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

    Returns:
      A list of columns
  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(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(*, 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 `Table` objects

        Tables containing the metadata of the target

  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(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

    Returns:
      None. It downloads the observation postcard indicated
  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

    Returns:
      A list of tables
  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

    Returns:
      A table object