sas

sas.misc module

xga.sas.misc.cifbuild(sources, num_cores=1, disable_progress=False)[source]

A wrapper for the XMM cifbuild command, which will be run before many of the more complex SAS commands, to check that a CIF compatible with the local version of SAS is available. The observation date is taken from an event list for a given ObsID, and the analysis date is set to the date which this function is run.

Parameters
  • sources (BaseSource/NullSource/BaseSample) – A single source object, or a sample of sources.

  • num_cores (int) – The number of cores to use (if running locally), default is set to 90% of available.

  • disable_progress (bool) – Setting this to true will turn off the SAS generation progress bar.

sas.phot module

xga.sas.phot.evselect_image(sources, lo_en=<Quantity 0.5 keV>, hi_en=<Quantity 2. keV>, add_expr='', num_cores=1, disable_progress=False)[source]

A convenient Python wrapper for a configuration of the SAS evselect command that makes images. Images will be generated for every observation associated with every source passed to this function. If images in the requested energy band are already associated with the source, they will not be generated again.

Parameters
  • sources (BaseSource/NullSource/BaseSample) – A single source object, or a sample of sources.

  • lo_en (Quantity) – The lower energy limit for the image, in astropy energy units.

  • hi_en (Quantity) – The upper energy limit for the image, in astropy energy units.

  • add_expr (str) – A string to be added to the SAS expression keyword

  • num_cores (int) – The number of cores to use, default is set to 90% of available.

  • disable_progress (bool) – Setting this to true will turn off the SAS generation progress bar.

xga.sas.phot.eexpmap(sources, lo_en=<Quantity 0.5 keV>, hi_en=<Quantity 2. keV>, num_cores=1, disable_progress=False)[source]

A convenient Python wrapper for the SAS eexpmap command. Expmaps will be generated for every observation associated with every source passed to this function. If expmaps in the requested energy band are already associated with the source, they will not be generated again.

Parameters
  • sources (BaseSource/NullSource/BaseSample) – A single source object, or sample of sources.

  • lo_en (Quantity) – The lower energy limit for the expmap, in astropy energy units.

  • hi_en (Quantity) – The upper energy limit for the expmap, in astropy energy units.

  • num_cores (int) – The number of cores to use (if running locally), default is set to 90% of available.

  • disable_progress (bool) – Setting this to true will turn off the SAS generation progress bar.

xga.sas.phot.emosaic(sources, to_mosaic, lo_en=<Quantity 0.5 keV>, hi_en=<Quantity 2. keV>, psf_corr=False, psf_model='ELLBETA', psf_bins=4, psf_algo='rl', psf_iter=15, num_cores=1, disable_progress=False)[source]

A convenient Python wrapper for the SAS emosaic command. Every image associated with the source, that is in the energy band specified by the user, will be added together.

Parameters
  • sources (BaseSource/BaseSample) – A single source object, or a sample of sources.

  • to_mosaic (str) – The data type to produce a mosaic for, can be either image or expmap.

  • lo_en (Quantity) – The lower energy limit for the combined image, in astropy energy units.

  • hi_en (Quantity) – The upper energy limit for the combined image, in astropy energy units.

  • psf_corr (bool) – If True, PSF corrected images will be mosaiced.

  • psf_model (str) – If PSF corrected, the PSF model used.

  • psf_bins (int) – If PSF corrected, the number of bins per side.

  • psf_algo (str) – If PSF corrected, the algorithm used.

  • psf_iter (int) – If PSF corrected, the number of algorithm iterations.

  • num_cores (int) – The number of cores to use (if running locally), default is set to 90% of available.

  • disable_progress (bool) – Setting this to true will turn off the SAS generation progress bar.

xga.sas.phot.psfgen(sources, bins=4, psf_model='ELLBETA', num_cores=1, disable_progress=False)[source]

A wrapper for the psfgen SAS task. Used to generate XGA PSF objects, which in turn can be used to correct XGA images/ratemaps for optical effects. By default we use the ELLBETA model reported in Read et al. 2011 (doi:10.1051/0004-6361/201117525), and generate a grid of binsxbins PSFs that can be used to correct for the PSF over an entire image. The energy dependence of the PSF is assumed to be minimal, and the resultant PSF object will be paired up with an image that matches it’s ObsID and instrument.

Parameters
  • sources (BaseSource/BaseSample) – A single source object, or a sample of sources.

  • bins (int) – The image coordinate space will be divided into a grid of size binsxbins, PSFs will be generated at the central coordinates of the grid chunks.

  • psf_model (str) – Which model to use when generating the PSF, default is ELLBETA, the best available.

  • num_cores (int) – The number of cores to use (if running locally), default is set to 90% of available.

  • disable_progress (bool) – Setting this to true will turn off the SAS generation progress bar.

sas.run module

xga.sas.run.execute_cmd(cmd, p_type, p_path, extra_info, src)[source]

This function is called for the local compute option, and runs the passed command in a Popen shell. It then creates an appropriate product object, and passes it back to the callback function of the Pool it was called from.

Parameters
  • cmd (str) – SAS command to be executed on the command line.

  • p_type (str) – The product type that will be produced by this command.

  • p_path (str) – The final output path of the product.

  • extra_info (dict) – Any extra information required to define the product object.

  • src (str) – A string representation of the source object that this product is associated with.

Returns

The product object, and the string representation of the associated source object.

Return type

Tuple[BaseProduct, str]

xga.sas.run.sas_call(sas_func)[source]

This is used as a decorator for functions that produce SAS command strings. Depending on the system that XGA is running on (and whether the user requests parallel execution), the method of executing the SAS command will change. This supports both simple multi-threading and submission with the Sun Grid Engine. :return:

sas.spec module

xga.sas.spec.evselect_spectrum(sources, outer_radius, inner_radius=<Quantity 0. arcsec>, group_spec=True, min_counts=5, min_sn=None, over_sample=None, one_rmf=True, num_cores=1, disable_progress=False)[source]

A wrapper for all of the SAS processes necessary to generate an XMM spectrum that can be analysed in XSPEC. Every observation associated with this source, and every instrument associated with that observation, will have a spectrum generated using the specified outer and inner radii as a boundary. The default inner radius is zero, so by default this function will produce circular spectra out to the outer_radius. It is possible to generate both grouped and ungrouped spectra using this function, with the degree of grouping set by the min_counts, min_sn, and oversample parameters.

Parameters
  • sources (BaseSource/BaseSample) – A single source object, or a sample of sources.

  • outer_radius (str/Quantity) – The name or value of the outer radius to use for the generation of the spectrum (for instance ‘r200’ would be acceptable for a GalaxyCluster, or Quantity(1000, ‘kpc’)). If ‘region’ is chosen (to use the regions in region files), then any inner radius will be ignored. If you are generating for multiple sources then you can also pass a Quantity with one entry per source.

  • inner_radius (str/Quantity) – The name or value of the inner radius to use for the generation of the spectrum (for instance ‘r500’ would be acceptable for a GalaxyCluster, or Quantity(300, ‘kpc’)). By default this is zero arcseconds, resulting in a circular spectrum. If you are generating for multiple sources then you can also pass a Quantity with one entry per source.

  • group_spec (bool) – A boolean flag that sets whether generated spectra are grouped or not.

  • min_counts (float) – If generating a grouped spectrum, this is the minimum number of counts per channel. To disable minimum counts set this parameter to None.

  • min_sn (float) – If generating a grouped spectrum, this is the minimum signal to noise in each channel. To disable minimum signal to noise set this parameter to None.

  • over_sample (float) – The minimum energy resolution for each group, set to None to disable. e.g. if over_sample=3 then the minimum width of a group is 1/3 of the resolution FWHM at that energy.

  • one_rmf (bool) – This flag tells the method whether it should only generate one RMF for a particular ObsID-instrument combination - this is much faster in some circumstances, however the RMF does depend slightly on position on the detector.

  • num_cores (int) – The number of cores to use, default is set to 90% of available.

  • disable_progress (bool) – Setting this to true will turn off the SAS generation progress bar.

xga.sas.spec.spectrum_set(sources, radii, group_spec=True, min_counts=5, min_sn=None, over_sample=None, one_rmf=True, num_cores=1, force_regen=False, disable_progress=False)[source]

This function can be used to produce ‘sets’ of XGA Spectrum objects, generated in concentric circular annuli. Such spectrum sets can be used to measure projected spectroscopic quantities, or even be de-projected to attempt to measure spectroscopic quantities in a three dimensional space.

Parameters
  • sources (BaseSource/BaseSample) – A single source object, or a sample of sources.

  • radii (List[Quantity]/Quantity) – A list of non-scalar quantities containing the boundary radii of the annuli for the sources. A single quantity containing at least three radii may be passed if one source is being analysed, but for multiple sources there should be a quantity (with at least three radii), PER source.

  • group_spec (bool) – A boolean flag that sets whether generated spectra are grouped or not.

  • min_counts (float) – If generating a grouped spectrum, this is the minimum number of counts per channel. To disable minimum counts set this parameter to None.

  • min_sn (float) – If generating a grouped spectrum, this is the minimum signal to noise in each channel. To disable minimum signal to noise set this parameter to None.

  • over_sample (float) – The minimum energy resolution for each group, set to None to disable. e.g. if over_sample=3 then the minimum width of a group is 1/3 of the resolution FWHM at that energy.

  • one_rmf (bool) – This flag tells the method whether it should only generate one RMF for a particular ObsID-instrument combination - this is much faster in some circumstances, however the RMF does depend slightly on position on the detector.

  • num_cores (int) – The number of cores to use, default is set to 90% of available.

  • force_regen (bool) – This will force all the constituent spectra of the set to be regenerated, use this if your call to this function was interrupted and an incomplete AnnularSpectrum is being read in.

  • disable_progress (bool) – Setting this to true will turn off the SAS generation progress bar.

xga.sas.spec.cross_arf(sources, radii, group_spec=True, min_counts=5, min_sn=None, over_sample=None, set_id=None, detmap_bin=200, num_cores=1, disable_progress=False)[source]

This function will generate cross-arfs for annular spectra, which describe the contribution of each annulus to each other annulus due to XMM’s relatively sizeable PSF. The cross-arfs are generated for each instrument of each observation, and automatically stored in their parent AnnularSpectra instance, both for retrieval by fitting processes and so that the user can examine them with a plotting method and by retrieving effective area values from them.

Parameters
  • sources (BaseSource/BaseSample) – A single source object, or a sample of sources.

  • radii (List[Quantity]/Quantity) – A list of non-scalar quantities containing the boundary radii of the annuli for the sources. A single quantity containing at least three radii may be passed if one source is being analysed, but for multiple sources there should be a quantity (with at least three radii), PER source. This is used to help retrieve the correct annular spectrum.

  • group_spec (bool) – A boolean flag that sets whether the spectra are grouped or not. This is used to help retrieve the correct annular spectrum.

  • min_counts (float) – If retrieving a grouped spectrum, this is the minimum number of counts per channel. To disable minimum counts set this parameter to None. This is used to help retrieve the correct annular spectrum.

  • min_sn (float) – If retrieving a grouped spectrum, this is the minimum signal to noise in each channel. To disable minimum signal to noise set this parameter to None. This is used to help retrieve the correct annular spectrum.

  • over_sample (float) – The minimum energy resolution for each group, set to None to disable. e.g. if over_sample=3 then the minimum width of a group is 1/3 of the resolution FWHM at that energy. This is used to help retrieve the correct annular spectrum.

  • set_id (str/List[str]) – The unique annular spectrum identifier (or a list of them if analysing multiple sources) that specifies which annular spectrum to use.

  • detmap_bin (int) – The spatial binning applied to event lists to create the detector maps used in the calculations of effective areas. The default is 200, smaller values will increase the resolution but will cause dramatically slower calculations.

  • num_cores (int) – The number of cores to use, default is set to 90% of available.

  • disable_progress (bool) – Setting this to true will turn off the SAS generation progress bar.

Returns

sas.lightcurve module

xga.sas.lightcurve.evselect_lightcurve(sources, outer_radius, inner_radius=<Quantity 0. arcsec>, lo_en=<Quantity 0.5 keV>, hi_en=<Quantity 2. keV>, time_bin_size=<Quantity 100. s>, pn_patt='<= 4', mos_patt='<= 12', num_cores=1, disable_progress=False)[source]
A wrapper for all the SAS processes necessary to generate XMM light curves for a specified region.

Every observation associated with this source, and every instrument associated with that

observation, will have a light curve generated using the specified outer and inner radii as a boundary. The default inner radius is zero, so by default this function will produce light curves in a circular region out to the outer_radius. The light curves are corrected for background, vignetting, and PSF concerns using the SAS ‘epiclccorr’ tool.

Parameters
  • sources (BaseSource/BaseSample) – A single source object, or a sample of sources.

  • outer_radius (str/Quantity) – The name or value of the outer radius to use for the generation of the light curve (for instance ‘point’ would be acceptable for a Star or PointSource). If ‘region’ is chosen (to use the regions in region files), then any inner radius will be ignored. If you are generating for multiple sources then you can also pass a Quantity with one entry per source.

  • inner_radius (str/Quantity) – The name or value of the inner radius to use for the generation of the light curve. By default this is zero arcseconds, resulting in a light curve from a circular region. If you are generating for multiple sources then you can also pass a Quantity with one entry per source.

  • lo_en (Quantity) – The lower energy boundary for the light curve, in units of keV. The default is 0.5 keV.

  • hi_en (Quantity) – The upper energy boundary for the light curve, in units of keV. The default is 2.0 keV.

  • time_bin_size (Quantity) – The bin size to be used for the creation of the light curve, in seconds. The default is 100 s.

  • pn_patt (str) – The event selection pattern that should be applied for PN data. This should be a string containing the selection expression of a valid XMM SAS pattern definition. For instance, the default for PN is <= 4.

  • mos_patt (str) – The event selection pattern that should be applied for MOS data. This should be a string containing the selection expression of a valid XMM SAS pattern definition. For instance, the default for MOS is <= 12.

  • num_cores (int) – The number of cores to use (if running locally), default is set to 90% of available.

  • disable_progress (bool) – Setting this to true will turn off the SAS generation progress bar.