# 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.region_setup(sources, outer_radius, inner_radius, disable_progress, obs_id)[source]

The preparation and value checking stage for SAS spectrum generation.

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’)).

• 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.

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

• obs_id (str) – Only used if the ‘region’ radius name is passed, the ObsID to retrieve the region for.

Returns

The source objects, a list of inner radius quantities, and a list of outer radius quantities.

Return type

Tuple[Union[BaseSource, BaseSample], List[Quantity], List[Quantity]]

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 (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.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 (if running locally), 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.