products

products.base module

class xga.products.base.BaseProduct(path, obs_id, instrument, stdout_str, stderr_str, gen_cmd)[source]

Bases: object

The super class for all SAS generated products in XGA. Stores relevant file path information, parses the std_err output of the generation process, and stores the instrument and ObsID that the product was generated for.

property usable

Returns whether this product instance should be considered usable for an analysis.

Returns

A boolean flag describing whether this product should be used.

Return type

bool

property path

Property getter for the attribute containing the path to the product.

Returns

The product path.

Return type

str

parse_stderr()[source]

This method parses the stderr associated with the generation of a product into errors confirmed to have come from SAS, and other unidentifiable errors. The SAS errors are returned with the actual error name, the error message, and the SAS routine that caused the error.

Returns

A list of dictionaries containing parsed, confirmed SAS errors, another containing SAS warnings, and another list of unidentifiable errors that occured in the stderr.

Return type

Tuple[List[Dict], List[Dict], List]

property sas_errors

Property getter for the confirmed SAS errors associated with a product.

Returns

The list of confirmed SAS errors.

Return type

List[Dict]

property sas_warnings

Property getter for the confirmed SAS warnings associated with a product.

Returns

The list of confirmed SAS warnings.

Return type

List[Dict]

raise_errors()[source]

Method to raise the errors parsed from std_err string.

property obs_id

Property getter for the ObsID of this image. Admittedly this information is implicit in the location this object is stored in a source object, but I think it worth storing directly as a property as well.

Returns

The XMM ObsID of this image.

Return type

str

property instrument

Property getter for the instrument used to take this image. Admittedly this information is implicit in the location this object is stored in a source object, but I think it worth storing directly as a property as well.

Returns

The XMM instrument used to take this image.

Return type

str

property type

Property getter for the string identifier for the type of product this object is, mostly useful for internal methods of source objects.

Returns

The string identifier for this type of object.

Return type

str

property errors

Property getter for non-SAS errors detected during the generation of a product.

Returns

A list of errors that aren’t related to SAS.

Return type

List[str]

property energy_bounds

Getter method for the energy_bounds property, which returns the rest frame energy band that this product was generated in.

Returns

Tuple containing the lower and upper energy limits as Astropy quantities.

Return type

Tuple[Quantity, Quantity]

property src_name

Method to return the name of the object a product is associated with. The product becomes aware of this once it is added to a source object.

Returns

The name of the source object this product is associated with.

Return type

str

property not_usable_reasons

Whenever the usable flag of a product is set to False (indicating you shouldn’t use the product), a string indicating the reason is added to a list, which this property returns.

Returns

A list of reasons why this product is unusable.

Return type

List

property sas_command

A property that returns the original SAS command used to generate this object.

Returns

String containing the command.

Return type

str

class xga.products.base.BaseAggregateProduct(file_paths, prod_type, obs_id, instrument)[source]

Bases: object

A base class for any XGA products that are an aggregate of an XGA SAS product.

property src_name

Method to return the name of the object a product is associated with. The product becomes aware of this once it is added to a source object. This is overridden in the AnnularSpectra class.

Returns

The name of the source object this product is associated with.

Return type

str

property obs_id

Property getter for the ObsID of this image. Admittedly this information is implicit in the location this object is stored in a source object, but I think it worth storing directly as a property as well.

Returns

The XMM ObsID of this image.

Return type

str

property instrument

Property getter for the instrument used to take this image. Admittedly this information is implicit in the location this object is stored in a source object, but I think it worth storing directly as a property as well.

Returns

The XMM instrument used to take this image.

Return type

str

property type

Property getter for the string identifier for the type of product this object is, mostly useful for internal methods of source objects.

Returns

The string identifier for this type of object.

Return type

str

property usable

Property getter for the boolean variable that tells you whether all component products have been found to be usable.

Returns

Boolean variable, are all component products usable?

Return type

bool

property energy_bounds

Getter method for the energy_bounds property, which returns the rest frame energy band that this product was generated in, if relevant.

Returns

Tuple containing the lower and upper energy limits as Astropy quantities.

Return type

Tuple[Quantity, Quantity]

property sas_errors

Equivelant to the BaseProduct sas_errors property, but reports any SAS errors stored in the component products.

Returns

A list of SAS errors related to component products.

Return type

List

property errors

Equivelant to the BaseProduct errors property, but reports any non-SAS errors stored in the component products.

Returns

A list of non-SAS errors related to component products.

Return type

List

property unprocessed_stderr

Equivelant to the BaseProduct sas_errors unprocessed_stderr, but returns a list of all the unprocessed standard error outputs.

Returns

List of stderr outputs.

Return type

List

class xga.products.base.BaseProfile1D(radii, values, centre, source_name, obs_id, inst, radii_err=None, values_err=None, associated_set_id=None, set_storage_key=None, deg_radii=None, x_norm=<Quantity 1.>, y_norm=<Quantity 1.>)[source]

Bases: object

The superclass for all 1D radial profile products, with built in fitting, viewing, and result retrieval functionality. Classes derived from BaseProfile1D can be added together to create Aggregate Profiles.

emcee_fit(model, num_steps, num_walkers, progress_bar, show_warn, num_samples)[source]

A fitting function to fit an XGA model instance to the data in this profile using the emcee affine-invariant MCMC sampler, this should be called through .fit() for full functionality. An initial run of curve_fit is used to find start parameters for the sampler, though if that fails a maximum likelihood estimate is run, and if that fails the method will revert to using the start parameters set in the model instance.

Parameters
  • model (BaseModel1D) – The model to be fit to the data.

  • num_steps (int) – The number of steps each chain should take.

  • num_walkers (int) – The number of walkers to be run for the ensemble sampler.

  • progress_bar (bool) – Whether a progress bar should be displayed.

  • show_warn (bool) – Should warnings be printed out, otherwise they are just stored in the model instance (this also happens if show_warn is True).

  • num_samples (int) – The number of random samples to take from the posterior distributions of the model parameters.

Returns

The model instance, and a boolean flag as to whether this was a successful fit or not.

Return type

Tuple[BaseModel1D, bool]

nlls_fit(model, num_samples, show_warn)[source]

A function to fit an XGA model instance to the data in this profile using the non-linear least squares curve_fit routine from scipy, this should be called through .fit() for full functionality

Parameters
  • model (BaseModel1D) – An instance of the model to be fit to this profile.

  • num_samples (int) – The number of random samples to be drawn and stored in the model parameter distribution property.

  • show_warn (bool) – Should warnings be printed out, otherwise they are just stored in the model instance (this also happens if show_warn is True).

Returns

The model (with best fit parameters stored within it), and a boolean flag as to whether the fit was successful or not.

Return type

Tuple[BaseModel1D, bool]

fit(model, method='mcmc', num_samples=10000, num_steps=30000, num_walkers=20, progress_bar=True, show_warn=True)[source]

Method to fit a model to this profile’s data, then store the resulting model parameter results. Each profile can store one instance of a type of model per fit method. So for instance you could fit both a ‘beta’ and ‘double_beta’ model to a surface brightness profile with curve_fit, and then you could fit ‘double_beta’ again with MCMC.

If any of the parameters of the passed model have a uniform prior associated, and the chosen method is curve_fit, then those priors will be used to place bounds on those parameters.

Parameters
  • model (str/BaseModel1D) – Either an instance of an XGA model to be fit to this profile, or the name of a profile (e.g. ‘beta’, or ‘simple_vikhlinin_dens’).

  • method (str) – The fit method to use, either ‘curve_fit’, ‘mcmc’, or ‘odr’.

  • num_samples (int) – The number of random samples to draw to create the parameter distributions that are saved in the model.

  • num_steps (int) – Only applicable if using MCMC fitting, the number of steps each walker should take.

  • num_walkers (int) – Only applicable if using MCMC fitting, the number of walkers to initialise for the ensemble sampler.

  • progress_bar (bool) – Only applicable if using MCMC fitting, should a progress bar be shown.

  • show_warn (bool) – Should warnings be printed out, otherwise they are just stored in the model instance (this also happens if show_warn is True).

Returns

The fitted model object. The fitted model is also stored within the profile object.

Return type

BaseModel1D

allowed_models(table_format='fancy_grid')[source]

This is a convenience function to tell the user what models can be used to fit a profile of the current type, what parameters are expected, and what the defaults are.

Parameters

table_format (str) – The desired format of the allowed models table. This is passed to the tabulate module (allowed formats can be found here - https://pypi.org/project/tabulate/), and alters the way the printed table looks.

get_model_fit(model, method)[source]

A get method for fitted model objects associated with this profile. Models for which the fit failed will also be returned, but a warning will be shown to inform the user that the fit failed.

Parameters
  • model (str) – The name of the model to retrieve.

  • method (str) – The method which was used to fit the model.

Returns

An instance of an XGA model object that was fitted to this profile and updated with the parameter values.

Return type

BaseModel1D

add_model_fit(model, method)[source]

There are rare circumstances where XGA processes might wish to add a model to a profile from the outside, which is what this method allows you to do.

Parameters
  • model (BaseModel1D) – The XGA model object to add to the profile.

  • method (str) – The method used to fit the model.

get_sampler(model)[source]

A get method meant to retrieve the MCMC ensemble sampler used to fit a particular model (supplied by the user). Checks are applied to the supplied model, to make sure that it is valid for the type of profile, that a good fit has actually been performed, and that the fit was performed with Emcee and not another method.

Parameters

model (str) – The name of the model for which to retrieve the sampler.

Returns

The Emcee sampler used to fit the user supplied model.

Return type

em.EnsembleSampler

get_chains(model, discard=True, flatten=True, thin=1)[source]

Get method for the sampler chains of an MCMC fit to the user supplied model. get_sampler is called to retrieve the sampler object, as well as perform validity checks on the model name.

Parameters
  • model (str) – The name of the model for which to retrieve the chains.

  • discard (bool/int) – Whether steps should be discarded for burn-in. If True then the cut off decided using the auto-correlation time will be used. If an integer is passed then this will be used as the number of steps to discard, and if False then no steps will be discarded.

  • flatten (bool) – Should the chains of the multiple walkers be flattened into one chain per parameter.

  • thin (int) – The thinning that should be applied to the chains. The default is 1, which means no thinning is applied.

Returns

The requested chains.

Return type

np.ndarray

view_chains(model, discard=True, thin=1, figsize=None)[source]

Simple view method to quickly look at the MCMC chains for a given model fit.

Parameters
  • model (str) – The name of the model for which to view the MCMC chains.

  • discard (bool/int) – Whether steps should be discarded for burn-in. If True then the cut off decided using the auto-correlation time will be used. If an integer is passed then this will be used as the number of steps to discard, and if False then no steps will be discarded.

  • thin (int) – The thinning that should be applied to the chains. The default is 1, which means no thinning is applied.

  • figsize (Tuple) – Desired size of the figure, if None will be set automatically.

view_corner(model, figsize=8, 8)[source]

A convenient view method to examine the corner plot of the parameter posterior distributions.

Parameters
  • model (str) – The name of the model for which to view the corner plot.

  • figsize (Tuple) – The desired figure size.

view_getdist_corner(model, settings={}, figsize=10, 10)[source]

A view method to see a corner plot generated with the getdist module, using flattened chains with burn-in removed (whatever the getdist message might say).

Parameters
  • model (str) – The name of the model for which to view the corner plot.

  • settings (dict) – The settings dictionary for a getdist MCSample.

  • figsize (tuple) – A tuple to set the size of the figure.

generate_data_realisations(num_real)[source]

A method to generate random realisations of the data points in this profile, using their y-axis values and uncertainties. This can be useful for error propagation for instance, and does not require a model fit to work. This method assumes that the y-errors are 1-sigma, which isn’t necessarily the case.

Parameters

num_real (int) – The number of random realisations to generate.

Returns

An N x R astropy quantity, where N is the number of realisations and R is the number of radii at which there are data points in this profile.

Return type

Quantity

view(figsize=10, 7, xscale='log', yscale='log', xlim=None, ylim=None, models=True, back_sub=True, just_models=False, custom_title=None, draw_rads={}, x_norm=False, y_norm=False, x_label=None, y_label=None)[source]

A method that allows us to view the current profile, as well as any models that have been fitted to it, and their residuals. The models are plotted by generating random model realisations from the parameter distributions, then plotting the median values, with 1sigma confidence limits.

Parameters
  • figsize (Tuple) – The desired size of the figure, the default is (10, 7)

  • xscale (str) – The scaling to be applied to the x axis, default is log.

  • yscale (str) – The scaling to be applied to the y axis, default is log.

  • xlim (Tuple) – The limits to be applied to the x axis, upper and lower, default is to let matplotlib decide by itself.

  • ylim (Tuple) – The limits to be applied to the y axis, upper and lower, default is to let matplotlib decide by itself.

  • models (str) – Should the fitted models to this profile be plotted, default is True

  • back_sub (bool) – Should the plotted data be background subtracted, default is True.

  • just_models (bool) – Should ONLY the fitted models be plotted? Default is False

  • custom_title (str) – A plot title to replace the automatically generated title, default is None.

  • draw_rads (dict) – A dictionary of extra radii (as astropy Quantities) to draw onto the plot, where the dictionary key they are stored under is what they will be labelled. e.g. ({‘r500’: Quantity(), ‘r200’: Quantity()}

  • x_norm (bool) – Controls whether the x-axis of the profile is normalised by another value, the default is False, in which case no normalisation is applied. If it is set to True then it will attempt to use the internal normalisation value (which can be set with the x_norm property), and if a quantity is passed it will attempt to normalise using that.

  • y_norm (bool) – Controls whether the y-axis of the profile is normalised by another value, the default is False, in which case no normalisation is applied. If it is set to True then it will attempt to use the internal normalisation value (which can be set with the y_norm property), and if a quantity is passed it will attempt to normalise using that.

  • x_label (str) – Custom label for the x-axis (excluding units, which will be added automatically).

  • y_label (str) – Custom label for the y-axis (excluding units, which will be added automatically).

save(save_path=None)[source]

This method pickles and saves the profile object. This will be called automatically when the profile is initialised, and when changes are made to the profile (such as when a model is fitted). The save file is a pickled version of this object.

Parameters

save_path (str) – The path where this profile should be saved. By default this is None, which means this method will use the save_path attribute of the profile.

property save_path

Property getter that assembles the default XGA save path of this profile. The file name contains limited information; the type of profile, the source name, and a random integer.

Returns

The default XGA save path for this profile.

Return type

str

property good_model_fits

A list of the names of models that have been successfully fitted to the profile.

Returns

A list of model names.

Return type

Dict

property radii

Getter for the radii passed in at init. These radii correspond to radii where the values were measured.

Returns

Astropy quantity array of radii.

Return type

Quantity

property radii_err

Getter for the uncertainties on the profile radii.

Returns

Astropy quantity array of radii uncertainties, or a None value if no radii_err where passed.

Return type

Quantity

property fit_radii

This property gives the user a sanitised set of radii that is safe to use for fitting to XGA models, by which I mean if the first element is zero (true for many of XGA’s profiles), then it will be replaced by a value slightly above zero that won’t cause divide by zeros in the fit process.

If the radius units are convertible to kpc then the zero value will be set to the equivelant of 1kpc, if they have pixel units then it will be set to one pixel, and if they are equivelant to degrees then it will be set to 1e−5 degrees. The value for degrees is loosely based on the value of 1kpc at a redshift of 1.

Returns

A Quantity with a set of radii that are ‘safe’ for fitting

Return type

Quantity

property radii_unit

Getter for the unit of the radii passed by the user at init.

Returns

An astropy unit object.

Return type

Unit

property annulus_bounds

Getter for the original boundary radii of the annuli this profile may have been generated from. Only available if radii errors were passed on init.

Returns

An astropy quantity containing the boundary radii of the annuli, or None if not available.

Return type

Quantity

property values

Getter for the values passed by user at init.

Returns

Astropy quantity array of values.

Return type

Quantity

property values_err

Getter for uncertainties on the profile values.

Returns

Astropy quantity array of values uncertainties, or a None value if no values_err where passed.

Return type

Quantity

property values_unit

Getter for the unit of the values passed by the user at init.

Returns

An astropy unit object.

Return type

Unit

property background

Getter for the background associated with the profile values. If no background is set this will be zero.

Returns

Astropy scalar quantity.

Return type

Quantity

property centre

Property that returns the central coordinate that the profile was generated from.

Returns

An astropy quantity of the central coordinate

Return type

Quantity

property type

Getter for a string representing the type of profile stored in this object.

Returns

String description of profile.

Return type

str

property src_name

Getter for the name attribute of this profile, what source object it was derived from.

Returns

Return type

object

property obs_id

Property getter for the ObsID this profile was made from. Admittedly this information is implicit in the location this object is stored in a source object, but I think it worth storing directly as a property as well.

Returns

XMM ObsID string.

Return type

str

property instrument

Property getter for the instrument this profile was made from. Admittedly this information is implicit in the location this object is stored in a source object, but I think it worth storing directly as a property as well.

directly as a property as well. :return: XMM instrument name string. :rtype: str

property energy_bounds

Getter method for the energy_bounds property, which returns the rest frame energy band that this profile was generated from

Returns

Tuple containing the lower and upper energy limits as Astropy quantities.

Return type

Union[Tuple[Quantity, Quantity], Tuple[None, None]]

property set_ident

If this profile was generated from an annular spectrum, this will contain the set_id of that annular spectrum.

Returns

The integer set ID of the annular spectrum that generated this, or None if it wasn’t generated from an AnnularSpectra object.

Return type

int

property y_axis_label

Property to return the name used for labelling the y-axis in any plot generated by a profile object.

Returns

The y_axis label.

Return type

str

property associated_set_storage_key

This property provides the storage key of the associated AnnularSpectra object, if the profile was generated from an AnnularSpectra. If it was not then a None value is returned.

Returns

The storage key of the associated AnnularSpectra, or None if not applicable.

Return type

str

property deg_radii

The radii in degrees if available.

Returns

An astropy quantity containing the radii in degrees, or None.

Return type

Quantity

property storage_key

This property returns the storage key which this object assembles to place the profile in an XGA source’s storage structure. If the profile was generated from an AnnularSpectra then the key is based on the properties of the AnnularSpectra, otherwise it is based upon the properties of the specific profile.

Returns

String storage key.

Return type

str

property usable

Whether the profile object can be considered usable or not, reasons for this decision will vary for different profile types.

Returns

A boolean variable.

Return type

bool

property x_norm

The normalisation value for x-axis data passed on the definition of the this profile object.

Returns

An astropy quantity containing the normalisation value.

Return type

Quantity

property y_norm

The normalisation value for y-axis data passed on the definition of the this profile object.

Returns

An astropy quantity containing the normalisation value.

Return type

Quantity

property fit_options

Returns the supported fit options for XGA profiles.

Returns

List of supported fit options.

Return type

List[str]

property nice_fit_names

Returns nicer looking names for the supported fit options of XGA profiles.

Returns

List of nice fit options.

Return type

List[str]

property outer_radius

Property that returns the outer radius used for the generation of this profile.

Returns

The outer radius used in the generation of the profile.

Return type

Quantity

class xga.products.base.BaseAggregateProfile1D(profiles)[source]

Bases: object

Quite a simple class that is generated when multiple 1D radial profile objects are added together. The purpose of instances of this class is simply to make it easy to view 1D radial profiles on the same axes.

property radii_unit

Getter for the unit of the radii passed by the user at init.

Returns

An astropy unit object.

Return type

Unit

property values_unit

Getter for the unit of the values passed by the user at init.

Returns

An astropy unit object.

Return type

Unit

property type

Getter for a string representing the type of profile stored in this object.

Returns

String description of profile.

Return type

str

property profiles

This property is for the constituent profiles that makes up this aggregate profile.

Returns

A list of the profiles that make up this object.

Return type

List[BaseProfile1D]

property energy_bounds

Getter method for the energy_bounds property, which returns the rest frame energy band that the component profiles of this object were generated from.

Returns

Tuple containing the lower and upper energy limits as Astropy quantities.

Return type

Union[Tuple[Quantity, Quantity], Tuple[None, None]]

property x_norms

The collated x normalisation values for the constituent profiles of this aggregate profile.

Returns

A list of astropy quantities which represent the x-normalisations of the different profiles.

Return type

List[Quantity]

property y_norms

The collated y normalisation values for the constituent profiles of this aggregate profile.

Returns

A list of astropy quantities which represent the y-normalisations of the different profiles.

Return type

List[Quantity]

view(figsize=10, 7, xscale='log', yscale='log', xlim=None, ylim=None, model=None, back_sub=True, legend=True, just_model=False, custom_title=None, draw_rads={}, normalise_x=False, normalise_y=False, x_label=None, y_label=None)[source]

A method that allows us to see all the profiles that make up this aggregate profile, plotted on the same figure.

Parameters
  • figsize (Tuple) – The desired size of the figure, the default is (10, 7)

  • xscale (str) – The scaling to be applied to the x axis, default is log.

  • yscale (str) – The scaling to be applied to the y axis, default is log.

  • xlim (Tuple) – The limits to be applied to the x axis, upper and lower, default is to let matplotlib decide by itself.

  • ylim (Tuple) – The limits to be applied to the y axis, upper and lower, default is to let matplotlib decide by itself.

  • model (str) – The name of the model fit to display, default is None. If the model hasn’t been fitted, or it failed, then it won’t be displayed.

  • back_sub (bool) – Should the plotted data be background subtracted, default is True.

  • legend (bool) – Should a legend with source names be added to the figure, default is True.

  • just_model (bool) – Should only the models, not the data, be plotted. Default is False.

  • custom_title (str) – A plot title to replace the automatically generated title, default is None.

  • draw_rads (dict) – A dictionary of extra radii (as astropy Quantities) to draw onto the plot, where the dictionary key they are stored under is what they will be labelled. e.g. ({‘r500’: Quantity(), ‘r200’: Quantity()}. If normalise_x option is also used, and the x-norm values are not the same for each profile, then draw_rads will be disabled.

  • normalise_x (bool) – Should the x-axis values be normalised with the x_norm value passed on the definition of the constituent profile objects.

  • normalise_y (bool) – Should the y-axis values be normalised with the y_norm value passed on the definition of the constituent profile objects.

  • x_label (str) – Custom label for the x-axis (excluding units, which will be added automatically).

  • y_label (str) – Custom label for the y-axis (excluding units, which will be added automatically).

products.misc module

class xga.products.misc.EventList(path, obs_id, instrument, stdout_str, stderr_str, gen_cmd)[source]

Bases: xga.products.base.BaseProduct

products.phot module

class xga.products.phot.Image(path, obs_id, instrument, stdout_str, stderr_str, gen_cmd, lo_en, hi_en, reg_file_path='')[source]

Bases: xga.products.base.BaseProduct

This class stores image data from X-ray observations. It also allows easy, direct, access to that data, and implements many helpful methods with extra functionality (including coordinate transforms, peak finders, and a powerful view method).

property regions

Property getter for regions associated with this image.

Returns

Returns a list of regions, if they have been associated with this object.

Return type

List[PixelRegion]

property shape

Property getter for the resolution of the image. Standard XGA settings will make this 512x512.

Returns

The shape of the numpy array describing the image.

Return type

Tuple[int, int]

property data

Property getter for the actual image data, in the form of a numpy array. Doesn’t include any of the other stuff you get in a fits image, thats found in the hdulist property.

Returns

A numpy array of shape self.shape containing the image data.

Return type

np.ndarray

property radec_wcs

Property getter for the WCS that converts back and forth between pixel values and RA-DEC coordinates. This one is the only WCS guaranteed to not-None.

Returns

The WCS object for RA and DEC.

Return type

wcs.WCS

property skyxy_wcs

Property getter for the WCS that converts back and forth between pixel values and XMM XY Sky coordinates.

Returns

The WCS object for XMM X and Y sky coordinates.

Return type

wcs.WCS

property detxy_wcs

Property getter for the WCS that converts back and forth between pixel values and XMM DETXY detector coordinates.

Returns

The WCS object for XMM DETX and DETY detector coordinates.

Return type

wcs.WCS

property header

Property getter allowing access to the astropy fits header object created when the image was read in.

Returns

The header of the primary data table of the image that was read in.

Return type

FITSHDR

coord_conv(coords, output_unit)[source]

This will use the loaded WCSes, and astropy coordinates (including custom ones defined for this module), to perform common coordinate conversions for this product object.

Parameters
  • coords (Quantity) – The input coordinates quantity to convert, in units of either deg, pix, xmm_sky, or xmm_det (xmm_sky and xmm_det are defined for this module).

  • output_unit (Unit/str) – The astropy unit to convert to, can be either deg, pix, xmm_sky, or xmm_det (xmm_sky and xmm_det are defined for this module).

Returns

The converted coordinates.

Return type

Quantity

property psf_corrected

Tells the user (and XGA), whether an Image based object has been PSF corrected or not.

Returns

Boolean flag, True means this object has been PSF corrected, False means it hasn’t

Return type

bool

property psf_algorithm

If this object has been PSF corrected, this property gives the name of the algorithm used.

Returns

The name of the algorithm used to correct for PSF effects, or None if the object hasn’t been PSF corrected.

Return type

Union[str, None]

property psf_bins

If this object has been PSF corrected, this property gives the number of bins that the X and Y axes were divided into to generate the PSFGrid.

Returns

The number of bins in X and Y for which PSFs were generated, or None if the object hasn’t been PSF corrected.

Return type

Union[int, None]

property psf_iterations

If this object has been PSF corrected, this property gives the number of iterations that the algorithm went through to create this image.

Returns

The number of iterations the PSF correction algorithm went through, or None if the object hasn’t been PSF corrected.

Return type

Union[int, None]

property psf_model

If this object has been PSF corrected, this property gives the name of the PSF model used.

Returns

The name of the PSF model used to correct for PSF effects, or None if the object hasn’t been PSF corrected.

Return type

Union[str, None]

get_view(ax, cross_hair=None, mask=None, chosen_points=None, other_points=None, zoom_in=False, manual_zoom_xlims=None, manual_zoom_ylims=None, radial_bins_pix=array([], dtype=float64), back_bin_pix=None, stretch=<astropy.visualization.stretch.LogStretch object>, mask_edges=True, view_regions=False, ch_thickness=0.8)[source]

The method that creates and populates the view axes, separate from actual view so outside methods can add a view to other matplotlib axes.

Parameters
  • ax (Axes) – The matplotlib axes on which to show the image.

  • cross_hair (Quantity) – An optional parameter that can be used to plot a cross hair at the coordinates. Up to two cross-hairs can be plotted, as any more can be visually confusing. If passing two, each row of a quantity is considered to be a separate coordinate pair.

  • mask (np.ndarray) – Allows the user to pass a numpy mask and view the masked data if they so choose.

  • chosen_points (np.ndarray) – A numpy array of a chosen point cluster from a hierarchical peak finder.

  • other_points (list) – A list of numpy arrays of point clusters that weren’t chosen by the hierarchical peak finder.

  • zoom_in (bool) – Sets whether the figure limits should be set automatically so that borders with no data are reduced.

  • manual_zoom_xlims (tuple) – If set, this will override the automatic zoom in and manually set a part of the x-axis to limit the image to, default is None. Pass a tuple with two elements, first being the lower limit, second the upper limit. Variable zoom_in must still be true for these limits to be applied.

  • manual_zoom_ylims (tuple) – If set, this will override the automatic zoom in and manually set a part of the y-axis to limit the image to, default is None. Pass a tuple with two elements, first being the lower limit, second the upper limit. Variable zoom_in must still be true for these limits to be applied.

  • radial_bins_pix (np.ndarray) – Radii (in units of pixels) of annuli to plot on top of the image, will only be triggered if a cross_hair coordinate is also specified and contains only one coordinate.

  • back_bin_pix (np.ndarray) – The inner and outer radii (in pixel units) of the annulus used to measure the background value for a given profile, will only be triggered if a cross_hair coordinate is also specified and contains only one coordinate.

  • stretch (BaseStretch) – The astropy scaling to use for the image data, default is log.

  • mask_edges (bool) – If viewing a RateMap, this variable will control whether the chip edges are masked to remove artificially bright pixels, default is True.

  • view_regions (bool) – If regions have been associated with this object (either on init or using the ‘regions’ property setter, should they be displayed. Default is False.

  • ch_thickness (float) – The desired linewidth of the crosshair(s), can be useful to increase this in certain circumstances. Default is 0.8.

Returns

A populated figure displaying the view of the data.

Return type

Axes

view(cross_hair=None, mask=None, chosen_points=None, other_points=None, figsize=(10, 8), zoom_in=False, manual_zoom_xlims=None, manual_zoom_ylims=None, radial_bins_pix=array([], dtype=float64), back_bin_pix=None, stretch=<astropy.visualization.stretch.LogStretch object>, mask_edges=True, view_regions=False, ch_thickness=0.8)[source]

Powerful method to view this Image/RateMap/Expmap, with different options that can be used for eyeballing and producing figures for publication.

Parameters
  • cross_hair (Quantity) – An optional parameter that can be used to plot a cross hair at the coordinates. Up to two cross-hairs can be plotted, as any more can be visually confusing. If passing two, each row of a quantity is considered to be a separate coordinate pair.

  • mask (np.ndarray) – Allows the user to pass a numpy mask and view the masked data if they so choose.

  • chosen_points (np.ndarray) – A numpy array of a chosen point cluster from a hierarchical peak finder.

  • other_points (list) – A list of numpy arrays of point clusters that weren’t chosen by the hierarchical peak finder.

  • figsize (Tuple) – Allows the user to pass a custom size for the figure produced by this method.

  • zoom_in (bool) – Sets whether the figure limits should be set automatically so that borders with no data are reduced.

  • manual_zoom_xlims (tuple) – If set, this will override the automatic zoom in and manually set a part of the x-axis to limit the image to, default is None. Pass a tuple with two elements, first being the lower limit, second the upper limit. Variable zoom_in must still be true for these limits to be applied.

  • manual_zoom_ylims (tuple) – If set, this will override the automatic zoom in and manually set a part of the y-axis to limit the image to, default is None. Pass a tuple with two elements, first being the lower limit, second the upper limit. Variable zoom_in must still be true for these limits to be applied.

  • radial_bins_pix (np.ndarray) – Radii (in units of pixels) of annuli to plot on top of the image, will only be triggered if a cross_hair coordinate is also specified and contains only one coordinate.

  • back_bin_pix (np.ndarray) – The inner and outer radii (in pixel units) of the annulus used to measure the background value for a given profile, will only be triggered if a cross_hair coordinate is also specified and contains only one coordinate.

  • stretch (BaseStretch) – The astropy scaling to use for the image data, default is log.

  • mask_edges (bool) – If viewing a RateMap, this variable will control whether the chip edges are masked to remove artificially bright pixels, default is True.

  • view_regions (bool) – If regions have been associated with this object (either on init or using the ‘regions’ property setter, should they be displayed. Default is False.

  • ch_thickness (float) – The desired linewidth of the crosshair(s), can be useful to increase this in certain circumstances. Default is 0.8.

class xga.products.phot.ExpMap(path, obs_id, instrument, stdout_str, stderr_str, gen_cmd, lo_en, hi_en)[source]

Bases: xga.products.phot.Image

A very simple subclass of the Image product class - designed to allow for easy interaction with exposure maps.

get_exp(at_coord)[source]

A simple method that converts the given coordinates to pixels, then finds the exposure time at those coordinates.

Parameters

at_coord (Quantity) – A pair of coordinates to find the exposure time for.

Returns

The exposure time at the supplied coordinates.

Return type

Quantity

class xga.products.phot.RateMap(xga_image, xga_expmap, reg_file_path='')[source]

Bases: xga.products.phot.Image

A very powerful class which allows interactions with ‘RateMaps’, though these are not directly generated by SAS, they are images divided by matching exposure maps, to provide a count rate image.

property shape

Property getter for the resolution of the ratemap. Standard XGA settings will make this 512x512.

Returns

The shape of the numpy array describing the ratemap.

Return type

Tuple[int, int]

property data

Property getter for ratemap data, overrides the method in the base Image class. This is because the ratemap class has a _construct_on_demand method that creates the ratemap data, which needs to be called instead of _read_on_demand.

Returns

A numpy array of shape self.shape containing the ratemap data.

Return type

np.ndarray

get_rate(at_coord)[source]

A simple method that converts the given coordinates to pixels, then finds the rate (in photons per second) and returns it.

Parameters

at_coord (Quantity) – A pair of coordinates to find the photon rate for.

Returns

The photon rate at the supplied coordinates.

Return type

Quantity

simple_peak(mask, out_unit=Unit('deg'))[source]

Simplest possible way to find the position of the peak of X-ray emission in a ratemap. This method takes a mask in the form of a numpy array, which allows the user to mask out parts of the ratemap that shouldn’t be searched (outside of a certain region, or within point sources for instance).

Parameters
  • mask (np.ndarray) – A numpy array used to weight the data. It should be 0 for pixels that aren’t to be searched, and 1 for those that are.

  • out_unit (UnitBase) – The desired output unit of the peak coordinates, the default is degrees.

Returns

An astropy quantity containing the coordinate of the X-ray peak of this ratemap (given the user’s mask), in units of out_unit, as specified by the user. Also returned is a boolean flag that tells the caller if the peak is near a chip edge.

Return type

Tuple[Quantity, bool]

clustering_peak(mask, out_unit=Unit('deg'), top_frac=0.05, max_dist=5, clean_point_clusters=False)[source]

An experimental peak finding function that cuts out the top 5% (by default) of array elements (by value), and runs a hierarchical clustering algorithm on their positions. The motivation for this is that the cluster peak will likely be contained in that top 5%, and the only other pixels that might be involved are remnants of poorly removed point sources. So when clusters have been formed, we can take the one with the most entries, and find the maximal pixel of that cluster. Should be consistent with simple_peak under ideal circumstances.

Parameters
  • mask (np.ndarray) – A numpy array used to weight the data. It should be 0 for pixels that aren’t to be searched, and 1 for those that are.

  • out_unit (UnitBase) – The desired output unit of the peak coordinates, the default is degrees.

  • top_frac (float) – The fraction of the elements (ordered in descending value) that should be used to generate clusters, and thus be considered for the cluster centre.

  • max_dist (float) – The maximum distance criterion for the hierarchical clustering algorithm, in pixels.

  • clean_point_clusters (bool) – If this is set to true then the point clusters which are not believed to host the peak pixel will be cleaned, meaning that if they have less than 4 pixels associated with them then they will be removed.

Returns

An astropy quantity containing the coordinate of the X-ray peak of this ratemap (given the user’s mask), in units of out_unit, as specified by the user. Finally, the coordinates of the points in the chosen cluster are returned, as is a list of all the coordinates of all the other clusters.

Return type

Tuple[Quantity, bool]

convolved_peak(mask, redshift, cosmology, out_unit=Unit('deg'))[source]

A very experimental peak finding algorithm, credit for the idea and a lot of the code in this function go to Lucas Porth. A radial profile (for instance a project king profile for clusters) is convolved with the ratemap, using a suitable radius for the object type (so for a cluster r might be ~1000kpc). As such objects that are similar to this profile will be boosted preferentially over objects that aren’t, making it less likely that we accidentally select the peak brightness pixel from a point source remnant or something similar. The convolved image is then masked to only look at the area of interest, and the peak brightness pixel is found.

Parameters
  • mask (np.ndarray) – A numpy array used to weight the data. It should be 0 for pixels that aren’t to be searched, and 1 for those that are.

  • redshift (float) – The redshift of the source that we wish to find the X-ray centroid of.

  • cosmology – An astropy cosmology object.

  • out_unit (UnitBase) – The desired output unit of the peak coordinates, the default is degrees.

Returns

An astropy quantity containing the coordinate of the X-ray peak of this ratemap (given the user’s mask), in units of out_unit, as specified by the user.

Return type

Tuple[Quantity, bool]

near_edge(coord)[source]

Uses the edge mask generated for RateMap objects to determine if the passed coordinates are near an edge/chip gap. If the coordinates are within +- 2 pixels of an edge the result will be true.

Parameters

coord (Quantity) – The coordinates to check.

Returns

A boolean flag as to whether the coordinates are near an edge.

Return type

bool

signal_to_noise(source_mask, back_mask, exp_corr=True, allow_negative=False)[source]

A signal to noise calculation method which takes information on source and background regions, then uses that to calculate a signal to noise for the source. This was primarily motivated by the desire to produce valid SNR values for combined data, where uneven exposure times across the combined field of view could cause issues with the usual approach of just summing the counts in the region images and scaling by area. This method can also measure signal to noises without exposure time correction.

Parameters
  • source_mask (np.ndarray) – The mask which defines the source region, ideally with interlopers removed.

  • back_mask (np.ndarray) – The mask which defines the background region, ideally with interlopers removed.

  • exp_corr (bool) – Should signal to noises be measured with exposure time correction, default is True. I recommend that this be true for combined observations, as exposure time could change quite dramatically across the combined product.

  • allow_negative (bool) – Should pixels in the background subtracted count map be allowed to go below zero, which results in a lower signal to noise (and can result in a negative signal to noise).

Returns

A signal to noise value for the source region.

Return type

float

property edge_mask

Returns the edge mask calculated for this RateMap in the form of a numpy array

Returns

A boolean numpy array in the same shape as the RateMap.

Return type

ndarray

property sensor_mask

Returns the detector map calculated for this RateMap. Values of 1 mean on chip, values of 0 mean off chip.

Returns

A boolean numpy array in the same shape as the RateMap.

Return type

ndarray

property expmap_path

Similar to the path property, but for the exposure map that went into this ratemap.

Returns

The exposure map path.

Return type

str

property image

This property allows the user to access the input Image object for this ratemap.

Returns

The input XGA Image object used to create this ratemap.

Return type

Image

property expmap

This property allows the user to access the input ExpMap object for this ratemap.

Returns

The input XGA ExpMap object used to create this ratemap.

Return type

ExpMap

class xga.products.phot.PSF(path, psf_model, obs_id, instrument, stdout_str, stderr_str, gen_cmd)[source]

Bases: xga.products.phot.Image

get_val(at_coord)[source]

A simple method that converts the given coordinates to pixels, then finds the exposure time at those coordinates.

Parameters

at_coord (Quantity) – A pair of coordinates to find the exposure time for.

Returns

The exposure time at the supplied coordinates.

Return type

Quantity

resample(im_prod, half_side_length)[source]

This method resamples a psfgen created PSF image to the same scale as the passed Image object. This is very important because psfgen makes these PSF images with a standard pixel size of 1 arcsec x 1 arcsec, and it can’t be changed when calling the routine. Thankfully, due to the wonders of WCS, it is possible to construct a new array with the same pixel size as a given image. Very important for when we want to deconvolve with an image and correct for the PSF.

Parameters
  • im_prod (Image) –

  • half_side_length (Quantity) –

Returns

The resampled PSF.

Return type

np.ndarray

property ra_dec

A property that fetches the RA-DEC that the PSF was generated at.

Returns

An astropy quantity of the ra and dec that the PSF was generated at.

Return type

Quantity

property model

This is the model that was used to generate this PSF.

Returns

XMM SAS psfgen model name.

Return type

str

class xga.products.phot.PSFGrid(file_paths, bins, psf_model, x_bounds, y_bounds, obs_id, instrument, stdout_str, stderr_str, gen_cmd)[source]

Bases: xga.products.base.BaseAggregateProduct

property num_bins

Getter for the number of bins in X and Y that this PSFGrid has PSF objects for.

Returns

The number of bins per side used to generate this PSFGrid

Return type

int

property model

This is the model that was used to generate the component PSFs in this PSFGrid.

Returns

XMM SAS psfgen model name.

Return type

str

property x_bounds

The x lower (column 0) and x upper (column 1) bounds of the PSFGrid bins. :return: N x 2 numpy array, where N is the total number of PSFGrid bins. :rtype: np.ndarray

property y_bounds

The y lower (column 0) and y upper (column 1) bounds of the PSFGrid bins.

Returns

N x 2 numpy array, where N is the total number of PSFGrid bins.

Return type

np.ndarray

property grid_locs

A 3D quantity containing the central position of each PSF in the grid.

Returns

A 3D Quantity

Return type

unload_data()[source]

A convenience method that will iterate through the component PSFs of this object and remove their data from memory using the data property deleter. This ensures that, if the data needs to be accessed again, the call to .data will read in the PSFs and all will be well, hopefully.

products.profile module

class xga.products.profile.SurfaceBrightness1D(rt, radii, values, centre, pix_step, min_snr, outer_rad, radii_err=None, values_err=None, background=None, pixel_bins=None, back_pixel_bin=None, ann_areas=None, deg_radii=None, min_snr_succeeded=True)[source]

Bases: xga.products.base.BaseProfile1D

This class provides an interface to radially symmetric X-ray surface brightness profiles of extended objects.

property pix_step

Property that returns the integer pixel step size used to generate the annuli that make up this profile.

Returns

The pixel step used to generate the surface brightness profile.

Return type

int

property min_snr

Property that returns minimum signal to noise value that was imposed upon this profile during generation.

Returns

The minimum signal to noise value used to generate this profile.

Return type

float

property psf_corrected

Tells the user (and XGA), whether the RateMap this brightness profile was generated from has been PSF corrected or not.

Returns

Boolean flag, True means this object has been PSF corrected, False means it hasn’t

Return type

bool

property psf_algorithm

If the RateMap this brightness profile was generated from has been PSF corrected, this property gives the name of the algorithm used.

Returns

The name of the algorithm used to correct for PSF effects, or None if there was no PSF correction.

Return type

Union[str, None]

property psf_bins

If the RateMap this brightness profile was generated from has been PSF corrected, this property gives the number of bins that the X and Y axes were divided into to generate the PSFGrid.

Returns

The number of bins in X and Y for which PSFs were generated, or None if the object

hasn’t been PSF corrected. :rtype: Union[int, None]

property psf_iterations

If the RateMap this brightness profile was generated from has been PSF corrected, this property gives the number of iterations that the algorithm went through.

Returns

The number of iterations the PSF correction algorithm went through, or None if there has been

no PSF correction. :rtype: Union[int, None]

property psf_model

If the RateMap this brightness profile was generated from has been PSF corrected, this property gives the name of the PSF model used.

Returns

The name of the PSF model used to correct for PSF effects, or None if there has been no

PSF correction. :rtype: Union[str, None]

property min_snr_succeeded

If True then the minimum signal to noise re-binning that can be applied to surface brightness profiles by some functions was successful, if False then it failed and the profile with no re-binning is stored here.

Returns

A boolean flag describing whether re-binning was successful or not.

Return type

bool

property pixel_bins

The annuli radii used to generate this profile, assuming they were passed on initialisation, otherwise None.

Returns

Numpy array containing the pixel bins used to measure this radial brightness profile.

Return type

np.ndarray

property back_pixel_bin

The annulus used to measure the background for this profile, assuming they were passed on initialisation, otherwise None.

Returns

Numpy array containing the pixel bin used to measure the background.

Return type

np.ndarray

property areas

Returns the areas of the annuli used to make this profile as an astropy Quantity.

Returns

Astropy non-scalar quantity containing the areas.

Return type

Quantity

check_match(rt, centre, pix_step, min_snr, outer_rad)[source]

A method for external use to check whether this profile matches the requested configuration of surface brightness profile, put here just because I imagine it’ll be used in quite a few places.

Parameters
  • rt (RateMap) – The RateMap to compare to this profile.

  • centre (Quantity) – The central coordinate to compare to this profile.

  • pix_step (int) – The width of each annulus in pixels to compare to this profile.

  • min_snr (float) – The minimum signal to noise to compare to this profile.

  • outer_rad (Quantity) – The outer radius to compare to this profile.

Returns

Whether this profile matches the passed parameters or not.

Return type

bool

class xga.products.profile.GasMass1D(radii, values, centre, source_name, obs_id, inst, dens_method, associated_prof, radii_err=None, values_err=None, deg_radii=None)[source]

Bases: xga.products.base.BaseProfile1D

This class provides an interface to a cumulative gas mass profile of a Galaxy Cluster.

property density_method

Gives the user the method used to generate the density profile used to make this gas mass profile.

Returns

The string describing the method

Return type

str

property generation_profile

Provides the profile from which the density profile used to make this gas mass profile was measured. Either a surface brightness profile if measured using SB methods, or an APEC normalisation profile if inferred from annular spectra.

Returns

The profile from which the density profile that made this profile was measured.

Return type

Union[SurfaceBrightness1D, APECNormalisation1D]

class xga.products.profile.GasDensity3D(radii, values, centre, source_name, obs_id, inst, dens_method, associated_prof, radii_err=None, values_err=None, associated_set_id=None, set_storage_key=None, deg_radii=None)[source]

Bases: xga.products.base.BaseProfile1D

This class provides an interface to a gas density profile of a galaxy cluster.

gas_mass(model, outer_rad, conf_level=68.2, fit_method='mcmc')[source]

A method to calculate and return the gas mass (with uncertainties). This method uses the model to generate a gas mass distribution (using the fit parameter distributions from the fit performed using the model), then measures the median mass, along with lower and upper uncertainties.

Parameters
  • model (str) – The name of the model from which to derive the gas mass.

  • outer_rad (Quantity) – The radius to measure the gas mass out to.

  • conf_level (float) – The confidence level to use to calculate the mass errors

  • fit_method (str) – The method that was used to fit the model, default is ‘mcmc’.

Returns

A Quantity containing three values (mass, -err, +err), and another Quantity containing the entire mass distribution from the whole realisation.

Return type

Tuple[Quantity, Quantity]

property density_method

Gives the user the method used to generate this density profile.

Returns

The string describing the method

Return type

str

property generation_profile

Provides the profile from which this density profile was measured. Either a surface brightness profile if measured using SB methods, or an APEC normalisation profile if inferred from annular spectra.

Returns

The profile from which the densities were measured.

Return type

Union[SurfaceBrightness1D, APECNormalisation1D]

view_gas_mass_dist(model, outer_rad, conf_level=68.2, figsize=8, 8, bins='auto', colour='lightslategrey', fit_method='mcmc')[source]

A method which will generate a histogram of the gas mass distribution that resulted from the gas mass calculation at the supplied radius. If the mass for the passed radius has already been measured it, and the mass distribution, will be retrieved from the storage of this product rather than re-calculated.

Parameters
  • model (str) – The name of the model from which to derive the gas mass.

  • outer_rad (Quantity) – The radius within which to calculate the gas mass.

  • conf_level (float) – The confidence level for the mass uncertainties, this doesn’t affect the distribution, only the vertical lines indicating the measured value of gas mass.

  • colour (str) – The desired colour of the histogram.

  • figsize (tuple) – The desired size of the histogram figure.

  • bins (int/str) – The argument to be passed to plt.hist, either a number of bins or a binning algorithm name.

  • fit_method (str) – The method that was used to fit the model, default is ‘mcmc’.

gas_mass_profile(model, radii=None, deg_radii=None, fit_method='mcmc')[source]

A method to calculate and return a gas mass profile.

Parameters
  • model (str) – The name of the model from which to derive the gas mass.

  • radii (Quantity) – The radii at which to measure gas masses. The default is None, in which case the radii at which this density profile has data points will be used.

  • deg_radii (Quantity) – The equivelant radii to radii but in degrees, required for defining a profile. The default is None, but if custom radii are passed then this variable must be passed too.

  • fit_method (str) – The method that was used to fit the model, default is ‘mcmc’.

Returns

A cumulative gas mass distribution.

Return type

GasMass1D

class xga.products.profile.ProjectedGasTemperature1D(radii, values, centre, source_name, obs_id, inst, radii_err=None, values_err=None, associated_set_id=None, set_storage_key=None, deg_radii=None)[source]

Bases: xga.products.base.BaseProfile1D

A profile product meant to hold a radial profile of projected X-ray temperature, as measured from a set of annular spectra by XSPEC. These are typically only defined by XGA methods.

class xga.products.profile.APECNormalisation1D(radii, values, centre, source_name, obs_id, inst, radii_err=None, values_err=None, associated_set_id=None, set_storage_key=None, deg_radii=None)[source]

Bases: xga.products.base.BaseProfile1D

A profile product meant to hold a radial profile of XSPEC normalisation, as measured from a set of annular spectra by XSPEC. These are typically only defined by XGA methods. This is a useful profile because it allows to not only infer 3D profiles of temperature and metallicity, but can also allow us to infer the 3D density profile.

gas_density_profile(redshift, cosmo, abund_table='angr', num_real=10000, sigma=1, num_dens=True)[source]

A method to calculate the gas density profile from the APEC normalisation profile, which in turn was measured from XSPEC fits of an AnnularSpectra. This method supports the generation of both number density and mass density profiles through the use of the num_dens keyword.

Parameters
  • redshift (float) – The redshift of the source that this profile was generated from.

  • cosmo – The chosen cosmology.

  • abund_table (str) – The abundance table to used for the conversion from n_e x n_H to n_e^2 during density calculation. Default is the famous Anders & Grevesse table.

  • num_real (int) – The number of data realisations which should be generated to infer density errors.

  • sigma (int) – What sigma of error should the density profile be created with, the default is 1σ.

  • num_dens (bool) – If True then a number density profile will be generated, otherwise a mass density profile

will be generated. :return: The gas density profile which has been calculated from the APEC normalisation profile. :rtype: GasDensity3D

emission_measure_profile(redshift, cosmo, abund_table='angr', num_real=100, sigma=2)[source]

A method to calculate the emission measure profile from the APEC normalisation profile, which in turn was measured from XSPEC fits of an AnnularSpectra.

Parameters
  • redshift (float) – The redshift of the source that this profile was generated from.

  • cosmo – The chosen cosmology.

  • abund_table (str) – The abundance table to used for the conversion from n_e x n_H to n_e^2 during density calculation. Default is the famous Anders & Grevesse table.

  • num_real (int) – The number of data realisations which should be generated to infer emission measure errors.

  • sigma (int) – What sigma of error should the density profile be created with, the default is 2σ.

Returns

Return type

class xga.products.profile.EmissionMeasure1D(radii, values, centre, source_name, obs_id, inst, radii_err=None, values_err=None, associated_set_id=None, set_storage_key=None, deg_radii=None)[source]

Bases: xga.products.base.BaseProfile1D

A profile product meant to hold a radial profile of X-ray emission measure.

class xga.products.profile.ProjectedGasMetallicity1D(radii, values, centre, source_name, obs_id, inst, radii_err=None, values_err=None, associated_set_id=None, set_storage_key=None, deg_radii=None)[source]

Bases: xga.products.base.BaseProfile1D

A profile product meant to hold a radial profile of projected X-ray metallicities/abundances, as measured from a set of annular spectra by XSPEC. These are typically only defined by XGA methods.

class xga.products.profile.GasTemperature3D(radii, values, centre, source_name, obs_id, inst, radii_err=None, values_err=None, associated_set_id=None, set_storage_key=None, deg_radii=None)[source]

Bases: xga.products.base.BaseProfile1D

A profile product meant to hold a 3D radial profile of X-ray temperature, as measured by some form of de-projection applied to a projected temperature profile

class xga.products.profile.BaryonFraction(radii, values, centre, source_name, obs_id, inst, radii_err=None, values_err=None, associated_set_id=None, set_storage_key=None, deg_radii=None)[source]

Bases: xga.products.base.BaseProfile1D

A profile product which will hold a profile showing how the baryon fraction of a galaxy cluster changes with radius. These profiles are typically generated from a HydrostaticMass profile product instance.

class xga.products.profile.HydrostaticMass(temperature_profile, temperature_model, density_profile, density_model, radii, radii_err, deg_radii, fit_method='mcmc', num_walkers=20, num_steps=20000, num_samples=10000, show_warn=True, progress=True)[source]

Bases: xga.products.base.BaseProfile1D

A profile product which uses input GasTemperature3D and GasDensity3D profiles to generate a hydrostatic mass profile, which in turn can be used to measure the hydrostatic mass at a particular radius. In contrast to other profile objects, this one calculates the y values itself, as such any radii may be passed.

mass(radius, conf_level=68.2)[source]

A method which will measure a hydrostatic mass and hydrostatic mass uncertainty within the given radius/radii. No corrections are applied to the values calculated by this method, it is just the vanilla hydrostatic mass.

If the models for temperature and density have analytical solutions to their derivative wrt to radius then those will be used to calculate the gradients at radius, but if not then a numerical method will be used for which dx will be set to radius/1e+6.

Parameters
  • radius (Quantity) – An astropy quantity containing the radius/radii that you wish to calculate the mass within.

  • conf_level (float) – The confidence level for the mass uncertainties, the default is 68.2% (~1σ).

Returns

An astropy quantity containing the mass/masses, lower and upper uncertainties, and another containing the mass realisation distribution.

Return type

Union[Quantity, Quantity]

view_mass_dist(radius, conf_level=68.2, figsize=8, 8, bins='auto', colour='lightslategrey')[source]

A method which will generate a histogram of the mass distribution that resulted from the mass calculation at the supplied radius. If the mass for the passed radius has already been measured it, and the mass distribution, will be retrieved from the storage of this product rather than re-calculated.

Parameters
  • radius (Quantity) – An astropy quantity containing the radius/radii that you wish to calculate the mass within.

  • conf_level (float) – The confidence level for the mass uncertainties, the default is 68.2% (~1σ).

  • bins (int/str) – The argument to be passed to plt.hist, either a number of bins or a binning algorithm name.

  • colour (str) – The desired colour of the histogram.

  • figsize (tuple) – The desired size of the histogram figure.

baryon_fraction(radius, conf_level=68.2)[source]

A method to use the hydrostatic mass information of this profile, and the gas density information of the input gas density profile, to calculate a baryon fraction within the given radius.

Parameters
  • radius (Quantity) – An astropy quantity containing the radius/radii that you wish to calculate the baryon fraction within.

  • conf_level (float) – The confidence level for the mass uncertainties, the default is 68.2% (~1σ).

Returns

An astropy quantity containing the baryon fraction, -ve error, and +ve error, and another quantity containing the baryon fraction distribution.

Return type

Tuple[Quantity, Quantity]

view_baryon_fraction_dist(radius, conf_level=68.2, figsize=8, 8, bins='auto', colour='lightslategrey')[source]

A method which will generate a histogram of the baryon fraction distribution that resulted from the mass calculation at the supplied radius. If the baryon fraction for the passed radius has already been measured it, and the baryon fraction distribution, will be retrieved from the storage of this product rather than re-calculated.

Parameters
  • radius (Quantity) – An astropy quantity containing the radius/radii that you wish to calculate the baryon fraction within.

  • conf_level (float) – The confidence level for the mass uncertainties, the default is 68.2% (~1σ).

  • bins (int/str) – The argument to be passed to plt.hist, either a number of bins or a binning algorithm name.

  • figsize (tuple) – The desired size of the histogram figure.

  • colour (str) – The desired colour of the histogram.

baryon_fraction_profile()[source]

A method which uses the baryon_fraction method to construct a baryon fraction profile at the radii of this HydrostaticMass profile. The uncertainties on the baryon fraction are calculated at the 1σ level.

Returns

An XGA BaryonFraction object.

Return type

BaryonFraction

property temperature_profile

A method to provide access to the 3D temperature profile used to generate this hydrostatic mass profile.

Returns

The input temperature profile.

Return type

GasTemperature3D

property density_profile

A method to provide access to the 3D density profile used to generate this hydrostatic mass profile.

Returns

The input density profile.

Return type

GasDensity3D

property temperature_model

A method to provide access to the model that was fit to the temperature profile.

Returns

The fit temperature model.

Return type

BaseModel1D

property density_model

A method to provide access to the model that was fit to the density profile.

Returns

The fit density profile.

Return type

BaseModel1D

rad_check(rad)[source]

Very simple method that prints a warning if the radius is outside the range of data covered by the density or temperature profiles.

Parameters

rad (Quantity) – The radius to check.

class xga.products.profile.Generic1D(radii, values, centre, source_name, obs_id, inst, y_axis_label, prof_type, radii_err=None, values_err=None, associated_set_id=None, set_storage_key=None, deg_radii=None)[source]

Bases: xga.products.base.BaseProfile1D

A 1D profile product meant to hold profiles which have been dynamically generated by XSPEC profile fitting of models that I didn’t build into XGA. It can also be used to make arbitrary profiles using external data.

products.relation module

class xga.products.relation.ScalingRelation(fit_pars, fit_par_errs, model_func, x_norm, y_norm, x_name, y_name, fit_method='unknown', x_data=None, y_data=None, x_err=None, y_err=None, x_lims=None, odr_output=None, chains=None, relation_name=None, relation_author='XGA', relation_year='2021', relation_doi='', scatter_par=None, scatter_chain=None)[source]

Bases: object

This class is designed to store all information pertaining to a scaling relation fit, either performed by XGA or from literature. It also aims to make creating publication quality plots simple and easy.

property pars

The parameters that describe this scaling relation, along with their uncertainties. They are in the order in which they are expected to be passed into the model function.

Returns

A numpy array of the fit parameters and their uncertainties, first column are parameters, second column are uncertainties.

Return type

np.ndarray

property model_func

Provides the model function used to fit this relation.

Returns

The Python function of this relation’s model.

property x_name

A string containing the name of the x-axis of this relation.

Returns

A Python string containing the name.

Return type

str

property y_name

A string containing the name of the x-axis of this relation.

Returns

A Python string containing the name.

Return type

str

property x_norm

The astropy quantity containing the x-axis normalisation used during fitting.

Returns

An astropy quantity object.

Return type

Quantity

property y_norm

The astropy quantity containing the y-axis normalisation used during fitting.

Returns

An astropy quantity object.

Return type

Quantity

property x_unit

The astropy unit object relevant to the x-axis of this relation.

Returns

An Astropy Unit object.

Return type

Unit

property y_unit

The astropy unit object relevant to the y-axis of this relation.

Returns

An Astropy Unit object.

Return type

Unit

property x_data

An astropy Quantity of the x-data used to fit this relation, or an empty quantity if that data is not available. The first column is the data, the second is the uncertainties.

Returns

An Astropy Quantity object, containing the data and uncertainties.

Return type

Quantity

property y_data

An astropy Quantity of the y-data used to fit this relation, or an empty quantity if that data is not available. The first column is the data, the second is the uncertainties.

Returns

An Astropy Quantity object, containing the data and uncertainties.

Return type

Quantity

property x_lims

If the user passed an x range in which the relation is valid on initialisation, then this will return those limits in the same units as the x-axis.

Returns

A quantity containing upper and lower x limits, or None.

Return type

Quantity

property fit_method

A descriptor for the fit method used to generate this scaling relation.

Returns

A string containing the name of the fit method.

Return type

str

property name

A property getter for the name of the relation, this may not be unique in cases where no name was passed on declaration.

Returns

String containing the name of the relation.

Return type

str

property author

A property getter for the author of the relation, if not from literature it will be XGA.

Returns

String containing the name of the author.

Return type

str

property year

A property getter for the year that the relation was created/published, if not from literature it will be the current year.

Returns

String containing the year of publication/creation.

Return type

str

property doi

A property getter for the doi of the original paper of the relation, if not from literature it will an empty string.

Returns

String containing the doi.

Return type

str

property scatter_par

A getter for the scatter information.

Returns

The scatter parameter and its uncertainty. If no scatter information was passed on definition then this will return None.

Return type

np.ndarray

property scatter_chain

A getter for the scatter information chain.

Returns

The scatter chain. If no scatter information was passed on definition then this will return None.

Return type

np.ndarray

property chains

Property getter for the parameter chains.

Returns

The MCMC chains of the fit for this scaling relation, if they were passed. Otherwise None.

Return type

np.ndarray

property par_names

Getter for the parameter names.

Returns

The names of the model parameters.

Return type

List

view_chains(figsize=None)[source]

Simple view method to quickly look at the MCMC chains for a scaling relation fit.

Parameters

figsize (tuple) – Desired size of the figure, if None will be set automatically.

view_corner(figsize=10, 10, cust_par_names=None, colour='tab:gray', save_path=None)[source]

A convenient view method to examine the corner plot of the parameter posterior distributions.

Parameters
  • figsize (tuple) – The size of the figure.

  • cust_par_names (List[str]) – A list of custom parameter names. If the names include LaTeX code do not include $$ math environment symbols - you may also need to pass a string literal (e.g. r”sigma”). Do not include an entry for a scatter parameter.

  • colour (List[str]) – Colour for the contours, the default is tab:gray.

  • save_path (str) – The path where the figure produced by this method should be saved. Default is None, in which case the figure will not be saved.

predict(x_values)[source]

This method allows for the prediction of y values from this scaling relation, you just need to pass in an appropriate set of x values.

Parameters

x_values (Quantity) – The x values to predict y values for.

Returns

The predicted y values

Return type

Quantity

view(x_lims=None, log_scale=True, plot_title=None, figsize=10, 8, data_colour='black', model_colour='grey', grid_on=False, conf_level=90, custom_x_label=None, custom_y_label=None, fontsize=15, legend_fontsize=13, x_ticks=None, x_minor_ticks=None, y_ticks=None, y_minor_ticks=None, save_path=None)[source]

A method that produces a high quality plot of this scaling relation (including the data it is based upon, if available).

Parameters
  • x_lims (Quantity) – If not set, this method will attempt to take appropriate limits from the x-data this relation is based upon, if that data is not available an error will be thrown.

  • log_scale (bool) – If true then the x and y axes of the plot will be log-scaled.

  • plot_title (str) – A custom title to be used for the plot, otherwise one will be generated automatically.

  • figsize (tuple) – A custom figure size for the plot, default is (8, 8).

  • data_colour (str) – The colour to use for the data points in the plot, default is black.

  • model_colour (str) – The colour to use for the model in the plot, default is grey.

  • grid_on (bool) – If True then a grid will be included on the plot. Default is True.

  • conf_level (int) – The confidence level to use when plotting the model.

  • custom_x_label (str) – Passing a string to this variable will override the x axis label of this plot, including the unit string.

  • custom_y_label (str) – Passing a string to this variable will override the y axis label of this plot, including the unit string.

  • fontsize (float) – The fontsize for axis labels.

  • legend_fontsize (float) – The fontsize for text in the legend.

  • x_ticks (list) – Customise which major x-axis ticks and labels are on the figure, default is None in which case they are determined automatically.

  • x_minor_ticks (list) – Customise which minor x-axis ticks and labels are on the figure, default is None in which case they are determined automatically.

  • y_ticks (list) – Customise which major y-axis ticks and labels are on the figure, default is None in which case they are determined automatically.

  • y_minor_ticks (list) – Customise which minor y-axis ticks and labels are on the figure, default is None in which case they are determined automatically.

  • save_path (str) – The path where the figure produced by this method should be saved. Default is None, in which case the figure will not be saved.

class xga.products.relation.AggregateScalingRelation(relations)[source]

Bases: object

This class is akin to the BaseAggregateProfile class, in that it is the result of a sum of ScalingRelation objects. References to the component objects will be stored within the structure of this class, and it primarily exists to allow plots with multiple relations to be generated.

property relations

This returns the list of ScalingRelation instances that make up this aggregate scaling relation.

Returns

A list of ScalingRelation instances.

Return type

List[ScalingRelation]

property x_unit

The astropy unit object relevant to the x-axis of this relation.

Returns

An Astropy Unit object.

Return type

Unit

property y_unit

The astropy unit object relevant to the y-axis of this relation.

Returns

An Astropy Unit object.

Return type

Unit

view_corner(figsize=10, 10, cust_par_names=None, contour_colours=None, save_path=None)[source]

A corner plot viewing method that will combine chains from all the relations that make up this aggregate scaling relation and display them using getdist.

Parameters
  • figsize (tuple) – The size of the figure.

  • cust_par_names (List[str]) – A list of custom parameter names. If the names include LaTeX code do not include $$ math environment symbols - you may also need to pass a string literal (e.g. r”sigma”). Do not include an entry for a scatter parameter.

  • contour_colours (List[str]) – Custom colours for the contours, there should be one colour per scaling relation.

  • save_path (str) – The path where the figure produced by this method should be saved. Default is None, in which case the figure will not be saved.

view(x_lims=None, log_scale=True, plot_title=None, figsize=10, 8, colour_list=None, grid_on=False, conf_level=90, show_data=True, fontsize=15, legend_fontsize=13, x_ticks=None, x_minor_ticks=None, y_ticks=None, y_minor_ticks=None, save_path=None)[source]

A method that produces a high quality plot of the component scaling relations in this AggregateScalingRelation.

Parameters
  • x_lims (Quantity) – If not set, this method will attempt to take appropriate limits from the x-data this relation is based upon, if that data is not available an error will be thrown.

  • log_scale (bool) – If true then the x and y axes of the plot will be log-scaled.

  • plot_title (str) – A custom title to be used for the plot, otherwise one will be generated automatically.

  • figsize (tuple) – A custom figure size for the plot, default is (8, 8).

  • colour_list (list) – A list of matplotlib colours to use as a custom colour cycle.

  • grid_on (bool) – If True then a grid will be included on the plot. Default is True.

  • conf_level (int) – The confidence level to use when plotting the model.

  • show_data (bool) – Controls whether data points are shown on the view, as it can quickly become confusing with multiple relations on one axis.

  • fontsize (float) – The fontsize for axis labels.

  • legend_fontsize (float) – The fontsize for text in the legend.

  • x_ticks (list) – Customise which major x-axis ticks and labels are on the figure, default is None in which case they are determined automatically.

  • x_minor_ticks (list) – Customise which minor x-axis ticks and labels are on the figure, default is None in which case they are determined automatically.

  • y_ticks (list) – Customise which major y-axis ticks and labels are on the figure, default is None in which case they are determined automatically.

  • y_minor_ticks (list) – Customise which minor y-axis ticks and labels are on the figure, default is None in which case they are determined automatically.

  • save_path (str) – The path where the figure produced by this method should be saved. Default is None, in which case the figure will not be saved.

products.spec module

class xga.products.spec.Spectrum(path, rmf_path, arf_path, b_path, central_coord, inn_rad, out_rad, obs_id, instrument, grouped, min_counts, min_sn, over_sample, stdout_str, stderr_str, gen_cmd, region=False, b_rmf_path='', b_arf_path='')[source]

Bases: xga.products.base.BaseProduct

This class is the XGA product responsible for storing an individual spectrum. Various qualities that can be measured from it (X-ray luminosity for example) can be associated with an instance of this object, as well as conversion factors that can be calculated from XSPEC. If a model has been fitted then the data and model can be viewed.

property path

This method returns the path to the spectrum file of this object.

Returns

The path to the spectrum file associated with this object.

Return type

str

property rmf

This method returns the path to the RMF file of the main spectrum of this object.

Returns

The path to the RMF file associated with the main spectrum of this object.

Return type

str

property arf

This method returns the path to the ARF file of the main spectrum of this object.

Returns

The path to the ARF file associated with the main spectrum of this object.

Return type

str

property background

This method returns the path to the background spectrum.

Returns

Path of the background spectrum.

Return type

str

property background_rmf

This method returns the path to the background spectrum’s RMF file.

Returns

The path the the background spectrum’s RMF.

Return type

str

property background_arf

This method returns the path to the background spectrum’s ARF file.

Returns

The path the the background spectrum’s ARF.

Return type

str

property storage_key

This property returns the storage key which this object assembles to place the Spectrum in an XGA source’s storage structure. The key is based on the properties of the spectrum, and some of the configuration options, and is basically human readable.

Returns

String storage key.

Return type

str

property central_coord

This property provides the central coordinates (RA-Dec) of the region that this spectrum was generated from.

Returns

Astropy quantity object containing the central coordinate in degrees.

Return type

Quantity

property shape

Returns the shape of the outer edge of the region this spectrum was generated from.

Returns

The shape (either circular or elliptical).

Return type

str

property inner_rad

Gives the inner radius (if circular) or radii (if elliptical - semi-major, semi-minor) of the region in which this spectrum was generated.

Returns

The inner radius(ii) of the region.

Return type

Quantity

property outer_rad

Gives the outer radius (if circular) or radii (if elliptical - semi-major, semi-minor) of the region in which this spectrum was generated.

Returns

The outer radius(ii) of the region.

Return type

Quantity

property grouped

A property stating whether SAS was told to group this spectrum during generation or not.

Returns

Boolean variable describing whether the spectrum is grouped or not

Return type

bool

property grouped_on

A property stating what metric this spectrum was grouped on.

Returns

String representation of the metric this spectrum was grouped on (None if not grouped).

Return type

str

property min_counts

A property stating the minimum number of counts allowed in a grouped channel.

Returns

The integer minimum number of counts per grouped channel (if this spectrum was grouped on minimum numbers of counts).

Return type

int

property min_sn

A property stating the minimum signal to noise allowed in a grouped channel.

Returns

The minimum signal to noise per grouped channel (if this spectrum was grouped on minimum signal to noise).

Return type

Union[float, int]

property over_sample

A property string stating the amount of oversampling applied by evselect during the spectrum generation process.

Returns

Oversampling applied during generation

Return type

float

property region

This property states whether this spectrum was generated directly from a region file region or not. If true then this isn’t from any arbitrary radii or an overdensity radius, but instead directly from a source finder.

Returns

A boolean flag describing if this is a region spectrum or not.

Return type

bool

property annulus_ident

This property returns the integer identifier of which annulus in a set this Spectrum is, if it is part of a set.

Returns

Integer annulus identifier, None if not part of a set.

Return type

object

property set_ident

This property returns the random id of the spectrum set this is a part of.

Returns

Set identifier, None if not part of a set.

Return type

int

property exposure

Property that returns the spectrum exposure time used by XSPEC.

Returns

Spectrum exposure time.

Return type

Quantity

add_fit_data(model, tab_line, plot_data)[source]

Method that adds information specific to a spectrum from an XSPEC fit to this object. This includes individual spectrum exposure and count rate, as well as calculated luminosities, and plotting information for data and model.

Parameters
  • model (str) – String representation of the XSPEC model fitted to the data.

  • tab_line – The line of the SPEC_INFO table produced by xga_extract.tcl that is relevant to this spectrum object.

  • plot_data (hdu.table.TableHDU) – The PLOT{N} table in the file produced by xga_extract.tcl that is relevant to this spectrum object.

get_luminosities(model, lo_en=None, hi_en=None)[source]

Returns the luminosities measured for this spectrum from a given model.

Parameters
  • model – Name of model to fetch luminosities for.

  • lo_en (Quantity) – The lower energy limit for the desired luminosity measurement.

  • hi_en (Quantity) – The upper energy limit for the desired luminosity measurement.

Returns

Luminosity measurement, either for all energy bands, or the one requested with the energy limit parameters. Luminosity measurements are presented as three column numpy arrays, with column 0 being the value, column 1 being err-, and column 2 being err+.

get_rate(model)[source]

Fetches the count rate for a particular model fitted to this spectrum.

Parameters

model – The model to fetch count rate for.

Returns

Count rate in counts per second.

Return type

Quantity

add_conv_factors(lo_ens, hi_ens, rates, lums, model)[source]

Method used to store countrate to luminosity conversion factors derived from fakeit spectra, as well as the actual countrate and luminosity measured in case the user wants to create a combined factor for multiple observations.

Parameters
  • lo_ens (np.ndarray) – A numpy array of string representations of the lower energy bounds for the cntrate and luminosity measurements.

  • hi_ens (np.ndarray) – A numpy array of string representations of the upper energy bounds for the cntrate and luminosity measurements.

  • rates (np.ndarray) – A numpy array of the rates measured for this arf/rmf combination for the energy ranges specified in lo_ens and hi_end.

  • lums (np.ndarray) – A numpy array of the luminosities measured for this arf/rmf combination for the energy ranges specified in lo_ens and hi_end.

  • model (str) – The name of the model used to calculate this factor.

get_conv_factor(lo_en, hi_en, model)[source]

Retrieves a conversion factor between count rate and luminosity for a given energy range, if one has been calculated.

Parameters
  • lo_en (Quantity) – The lower energy bound for the desired conversion factor.

  • hi_en (Quantity) – The upper energy bound for the desired conversion factor.

  • model (str) – The model used to generate the desired conversion factor.

Returns

The conversion factor, luminosity, and rate for the supplied model-energy combination.

Return type

Tuple[Quantity, Quantity, Quantity]

get_plot_data(model)[source]

Simply grabs the plot data dictionary for a given model, if the spectrum has had a fit performed on it.

Parameters

model (str) –

Returns

All information required to plot the data and model.

Return type

dict

get_arf_data()[source]

Reads in and returns the ARF effective areas for this spectrum.

Returns

The mid point of the energy bins and their corresponding effective areas.

Return type

Tuple[Quantity, Quantity]

view_arf(figsize=(8, 6), xscale='linear', yscale='linear', lo_en=<Quantity 0. keV>, hi_en=<Quantity 16. keV>)[source]

Plots the response curve for this spectrum.

Parameters
  • figsize (tuple) – The desired size of the output figure.

  • xscale (str) – The xscale to use for the plot.

  • yscale (str) – The yscale to use for the plot.

  • lo_en (Quantity) – The lower energy limit for the x-axis.

  • hi_en (Quantity) – The upper energy limit for the y-axis.

view(lo_en=<Quantity 0. keV>, hi_en=<Quantity 30. keV>, figsize=(8, 6))[source]

Very simple method to plot the data/models associated with this Spectrum object, between certain energy limits.

Parameters
  • lo_en (Quantity) – The lower energy limit from which to plot the spectrum.

  • hi_en (Quantity) – The upper energy limit to plot the spectrum to.

  • figsize (Tuple) – The desired size of the output figure.

class xga.products.spec.AnnularSpectra(spectra)[source]

Bases: xga.products.base.BaseAggregateProduct

A class designed to hold a set of XGA spectra generated in concentric, circular annuli.

property src_name

Method to return the name of the object a product is associated with. The product becomes aware of this once it is added to a source object.

Returns

The name of the source object this product is associated with.

Return type

str

property central_coord

This property provides the central coordinates (RA-Dec) that this set of spectra was generated around.

Returns

Astropy quantity object containing the central coordinate in degrees.

Return type

Quantity

property num_annuli

A property getter for the number of annular spectra.

Returns

The number of annular spectra associated with this product.

Return type

int

background(obs_id, inst)[source]

This method returns the path to the background spectrum for a particular ObsID and instrument. It is the background associated with the outermost annulus of this object.

Parameters
  • obs_id (str) – The ObsID to get the background spectrum for.

  • inst (str) – The instrument to get the background spectrum for.

Returns

Path of the background spectrum.

Return type

str

background_rmf(obs_id, inst)[source]

This method returns the path to the background spectrum’s RMF for a particular ObsID and instrument. It is the RMF of the background associated with the outermost annulus of this object.

Parameters
  • obs_id (str) – The ObsID to get the background spectrum’s RMF for.

  • inst (str) – The instrument to get the background spectrum’ RMF for.

Returns

Path of the background spectrum RMF.

Return type

str

background_arf(obs_id, inst)[source]

This method returns the path to the background spectrum’s ARF for a particular ObsID and instrument. It is the ARF of the background associated with the outermost annulus of this object.

Parameters
  • obs_id (str) – The ObsID to get the background spectrum’s ARF for.

  • inst (str) – The instrument to get the background spectrum’ ARF for.

Returns

Path of the background spectrum ARF.

Return type

str

property obs_ids

A property of this spectrum set that details which ObsIDs have contributed spectra to this object.

Returns

A list of ObsIDs.

containing instruments associated with those ObsIDs. :rtype: dict

property instruments

A property of this spectrum set that details which ObsIDs and instruments have contributed spectra to this object.

Returns

A dictionary of lists, with the top level keys being ObsIDs, and the lists

containing instruments associated with those ObsIDs. :rtype: dict

get_spectra(annulus_ident, obs_id=None, inst=None)[source]

This is the getter for the spectra stored in the AnnularSpectra data storage structure. They can be retrieved based on annulus identifier, ObsID, and instrument.

Parameters
  • annulus_ident (int) – The annulus identifier to retrieve spectra for.

  • obs_id (str) – Optionally, a specific obs_id to search for can be supplied.

  • inst (str) – Optionally, a specific instrument to search for can be supplied.

Returns

List of matching spectra, or just a Spectrum object if one match is found.

Return type

Union[List[Spectrum], Spectrum]

property all_spectra

Simple extra wrapper for get_spectra that allows the user to retrieve every single spectrum associated with this AnnularSpectra instance, for all annulus IDs.

Returns

A list of every single spectrum associated with this object.

Return type

List[Spectrum]

property radii

A property to return all the boundary radii of the constituent annuli.

Returns

Astropy quantity of the radii.

Return type

Quantity

property annulus_centres

Returns the centres of all the annuli, in the original units the radii were passed in with.

Returns

An astropy quantity containing radii.

Return type

Quantity

property proper_radii

A property to return the boundary radii of the constituent annuli in kpc. This has to be set using the setter first, otherwise the value is None.

Returns

Astropy quantity of the proper radii.

Return type

Quantity

property proper_annulus_centres

Returns the centres of all the annuli, in the units of proper radii which the user has to have set through the property setter.

Returns

An astropy quantity containing radii, or None if no proper radii exist

Return type

Quantity

property set_ident

This property returns the ID of this set of spectra.

Returns

The integer ID of this set.

Return type

int

property storage_key

This property returns the storage key which this object assembles to place the AnnularSpectra in an XGA source’s storage structure. The key is based on the properties of the AnnularSpectra, and some of the configuration options, and is basically human readable.

Returns

String storage key.

Return type

str

property grouped

A property stating whether SAS was told to group the spectra in this set during generation or not.

Returns

Boolean variable describing whether the spectra are grouped or not

Return type

bool

property grouped_on

A property stating what metric the spectra in this set were grouped on.

Returns

String representation of the metric the spectra were grouped on (None if not grouped).

Return type

str

property min_counts

A property stating the minimum number of counts allowed in a grouped channel for the spectra in this set.

Returns

The integer minimum number of counts per grouped channel (if these spectra were grouped on minimum numbers of counts).

Return type

int

property min_sn

A property stating the minimum signal to noise allowed in a grouped channel for the spectra in this set.

Returns

The minimum signal to noise per grouped channel (if these spectra were grouped on minimum signal to noise).

Return type

Union[float, int]

property over_sample

A property string stating the amount of oversampling applied by evselect during the generation of the spectra in this set. e.g. if over_sample=3 then the minimum width of a group is 1/3 of the resolution FWHM at that energy.

Returns

Oversampling applied during generation.

Return type

float

add_fit_data(model, tab_line, lums, obs_order)[source]

An equivelant to the add_fit_data method built into all source objects. The final fit results and luminosities are housed in a storage structure within the AnnularSpectra, which makes sense because this is an aggregate product of all the relevant spectra, storing them just as source objects store spectra that don’t exist in a spectrum set.

Parameters
  • model (str) – The XSPEC definition of the model used to perform the fit. e.g. constant*tbabs*apec

  • tab_line – A dictionary of table lines with fit data, the keys of the dictionary being the relevant annulus ID for the fit.

  • lums (dict) – A dictionary of the luminosities measured during the fits, the keys of the outermost dictionary being annulus IDs, and the luminosity dictionaries being energy based.

  • obs_order (dict) – A dictionary (with keys being annuli idents) of lists of lists describing the order the data is being passed, so that specific results can be related back to specific observations later (if applicable). The lists should be structured like [[obsid1, inst1], [obsid1, inst2], [obsid1, inst3]] for instance.

get_results(annulus_ident, model, par=None)[source]

Important method that will retrieve fit results from the AnnularSpectra object. Either for a specific parameter of the supplied model combination, or for all of them. If a specific parameter is requested, all matching values from the fit will be returned in an N row, 3 column numpy array (column 0 is the value, column 1 is err-, and column 2 is err+). If no parameter is specified, the return will be a dictionary of such numpy arrays, with the keys corresponding to parameter names.

Parameters
  • annulus_ident (int) – The annulus for which you wish to retrieve the fit results.

  • model (str) – The name of the fitted model that you’re requesting the results from (e.g. constant*tbabs*apec).

  • par (str) – The name of the parameter you want a result for.

Returns

The requested result value, and uncertainties.

get_luminosities(annulus_ident, model, lo_en=None, hi_en=None)[source]

This will retrieve luminosities of specific annuli from fits performed on this AnnularSpectra object. A model name must be supplied, and if a luminosity from a specific energy range is desired then lower and upper energy bounds may be passed.

Parameters
  • annulus_ident (int) – The annulus for which you wish to retrieve the luminosities.

  • model (str) – The name of the fitted model that you’re requesting the results from (e.g. constant*tbabs*apec).

  • lo_en (Quantity) – The lower energy limit for the desired luminosity measurement.

  • hi_en (Quantity) – The upper energy limit for the desired luminosity measurement.

Returns

The requested luminosity value, and uncertainties. If a specific energy range has been supplied then a quantity containing the value (col 1), -err (col 2), and +err (col 3), will be returned. If no energy range is supplied then a dictionary of all available luminosity quantities will be returned.

Return type

Union[Quantity, Dict[str, Quantity]]

generate_profile(model, par, par_unit, upper_limit=None)[source]

This generates a radial profile of the requested fit parameter using the stored results from an XSPEC model fit run on this AnnularSpectra. The profile is added to AnnularSpectra internal storage, and also returned to the user.

Parameters
  • model (str) – The name of the fitted model you wish to generate a profile from.

  • par (str) – The name of the free model parameter that you wish to generate a profile for.

  • par_unit (Unit/str) – The unit of the free model parameter as an astropy unit object, or a string representation (e.g. keV).

  • upper_limit (Quantity) – Allows an allowed upper limit for the y values in the profile to be passed.

Returns

The requested profile object.

Return type

Union[BaseProfile1D, ProjectedGasTemperature1D, ProjectedGasMetallicity1D]

view_annulus(ann_ident, model, figsize=12, 8)[source]

An equivelant to the Spectrum view method, but allows all spectra from the same annulus to be displayed on the same axis.

Parameters
  • ann_ident (int) – The integer identifier of the annulus you wish to see spectra for.

  • model (str) – The fitted model to display on the data.

  • figsize (tuple) – The size of the plot.

view_annuli(obs_id, inst, model, figsize=12, 8, elevation_angle=30, azimuthal_angle=- 60)[source]

This view method is one of several in the AnnularSpectra class, and will display data and associated model fits for a single ObsID-Instrument combination for all annuli in this AnnularSpectra, in a 3D plot. The output of this can be quite visually confusing, so you may wish to use view_annulus to see the spectrum of a particular annulus for a particular ObsID-Instrument in a more traditional way, or just view to see all model fits at all annuli.

Parameters
  • obs_id (str) – The ObsID of the spectra to display.

  • inst (str) – The instrument of the spectra to display.

  • model (str) – The model fit to display

  • figsize (tuple) – The size of the figure.

  • elevation_angle (int) – The elevation angle in the z plane, in degrees.

  • azimuthal_angle (int) – The azimuth angle in the x,y plane, in degrees.

view(model, figsize=12, 8, elevation_angle=30, azimuthal_angle=- 60)[source]

This view method is one of several in the AnnularSpectra class, and will display model fits to all spectra for each annuli in a 3D plot. No data is displayed in this viewing method, primarily because its so visually confusing. If you wish to see model fits displayed over actual data in this style, please use view_annuli.

Parameters
  • model (str) – The model fit to display

  • figsize (tuple) – The size of the figure.

  • elevation_angle (int) – The elevation angle in the z plane, in degrees.

  • azimuthal_angle (int) – The azimuth angle in the x,y plane, in degrees.