products

products.base module

class xga.products.base.BaseProduct(path, obs_id='', instrument='', stdout_str='', stderr_str='', gen_cmd='', extra_info=None, force_remote=False, fsspec_kwargs=None)

Bases: object

The super class for all X-ray 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.

Parameters:

• path (str) – The path to where the product file SHOULD be located.

• obs_id (str) – The ObsID related to the product being declared.

• instrument (str) – The instrument related to the product being declared.

• stdout_str (str) – The stdout from calling the terminal command.

• stderr_str (str) – The stderr from calling the terminal command.

• gen_cmd (str) – The command used to generate the product.

• extra_info (dict) – This allows the XGA processing steps to store some temporary extra information in this object for later use by another processing step. It isn’t intended for use by a user and will only be accessible when defining a BaseProduct.

• force_remote (bool) – Used to force the product instantiation to treat the passed path string as a url to a remote dataset, and to use fsspec to read/stream the data.

• fsspec_kwargs (dict) – Optional arguments that can be passed fsspec when reading or streaming remote datasets - e.g. to pass credentials to access an S3 bucket. Default value is None, which sets the argument to {“anon”: True}, making it instantly compatible with NASA archive S3 buckets.

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

property local_file

A file is deemed remote by the presence of certain strings at the beginning of the path, or the

user passing ‘force_remote=True’ at product initialization, otherwise it is considered to be local.

Returns:

Returns a boolean flag describing if we think this product is pointed at a local file (True) or a remote file (False).

Return type:

bool

property force_remote

A property providing the value of the ‘force_remote’ argument passed to this product at instantiation - that value controls how the init treats the file path.

Returns:

The value of ‘force_remote’ argument passed to this product at instantiation.

Return type:

bool

property fsspec_kwargs

Property getter for the attribute containing the fsspec keyword arguments passed to this product at instantiation. These are for passing configuration information such as credentials for the remote access of S3 buckets

Returns:

The fsspec keyword arguments passed to this product at instantiation.

Return type:

dict

parse_stderr()

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

Method to raise the errors parsed from std_err string.

property telescope

Property getter for the name of the telescope that this product was derived from.

Returns:

The telescope name.

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

Bases: object

A base class for any XGA products that are an aggregate of an XGA SAS product, for instance this is sub-classed to make the AnnularSpectra class. Users really shouldn’t be instantiating these for themselves.

Parameters:

• file_paths (list) – The file paths of the main files for a given aggregate product.

• prod_type (str) – The product type of the individual elements.

• obs_id (str) – The ObsID related to the product.

• instrument (str) – The instrument related to the 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 AggregateProduct. 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 ObsID of this AggregateProduct.

Return type:

str

property instrument

Property getter for the instrument of this AggregateProduct. 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 ObsID of this AggregateProduct.

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.>, auto_save=False, spec_model=None, fit_conf=None)

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.

Parameters:

• radii (Quantity) – The radii at which the y values of this profile have been measured.

• values (Quantity) – The y values of this profile.

• centre (Quantity) – The central coordinate the profile was generated from.

• source_name (str) – The name of the source this profile is associated with.

• obs_id (str) – The observation which this profile was generated from.

• inst (str) – The instrument which this profile was generated from.

• radii_err (Quantity) – Uncertainties on the radii.

• values_err (Quantity) – Uncertainties on the values.

• associated_set_id (int) – The set ID of the AnnularSpectra that generated this - if applicable. If this value is supplied a set_storage_key value must also be supplied.

• set_storage_key (str) – Must be present if associated_set_id is, this is the storage key which the associated AnnularSpectra generates to place itself in XGA’s storage structure.

• deg_radii (Quantity) – A slightly unfortunate variable that is required only if radii is not in units of degrees, or if no set_storage_key is passed. It should be a quantity containing the radii values converted to degrees, and allows this object to construct a predictable storage key.

• x_norm (Quantity) – An astropy quantity to use to normalise the x-axis values, this is only used when plotting if the user tells the view method that they wish for the plot to use normalised x-axis data.

• y_norm (Quantity) – An astropy quantity to use to normalise the y-axis values, this is only used when plotting if the user tells the view method that they wish for the plot to use normalised y-axis data.

• auto_save (bool) – Whether the profile should automatically save itself to disk at any point. The default is False, but all profiles generated through XGA processes acting on XGA sources will auto-save.

• spec_model (str) – The spectral model that was fit to annular spectra to measure the results that were used to create this profile. Only relevant to profiles that are generated from annular spectra, default is None.

• fit_conf (str) – The key that describes the fit-configuration used when fitting models to annular spectra to measure the results that were then used to create this profile. Only relevant to profiles that are generated from annular spectra, default is None.

emcee_fit(model, num_steps, num_walkers, progress_bar, show_warn, num_samples)

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, you cannot pass a model name for this argument.

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

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, force_refit=False)

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

• force_refit (bool) – Controls whether the profile will re-run the fit of a model that already has a good model fit stored. The default is False.

Returns:

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

Return type:

BaseModel1D

allowed_models(table_format='fancy_grid')

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)

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)

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.

remove_model_fit(model, method)

This will remove an existing model fit for a particular fit method.

Parameters:

• model (str/BaseModel1D) – The model fit to delete.

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

get_sampler(model)

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)

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)

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

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

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, truncate_zero=False)

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.

• truncate_zero (bool) – Should the data realisations be truncated at zero, default is False. This could be used for generating realisations of profiles where negative values are not physical.

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

get_view(fig, main_ax, 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, data_colour='black', model_colour='seagreen', show_legend=True, show_residual_ax=True, draw_vals={}, auto_legend=True, joined_points=False, axis_formatters=None)

A get method for an axes (or multiple axes) showing this profile and model fits. The idea of this get method is that, whilst it is used by the view() method, it can also be called by external methods that wish to use the profile plot in concert with other views.

param Figure fig:

The figure which has been set up for this profile plot.

param Axes main_ax:

The matplotlib axes on which to show the image.

param str xscale:

The scaling to be applied to the x axis, default is log.

param str yscale:

The scaling to be applied to the y axis, default is log.

param Tuple xlim:

The limits to be applied to the x axis, upper and lower, default is to let matplotlib decide by itself.

param Tuple ylim:

The limits to be applied to the y axis, upper and lower, default is to let matplotlib decide by itself.

param str models:

Should the fitted models to this profile be plotted, default is True

param bool back_sub:

Should the plotted data be background subtracted, default is True.

param bool just_models:

Should ONLY the fitted models be plotted? Default is False

param str custom_title:

A plot title to replace the automatically generated title, default is None.

param dict draw_rads:

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

param bool x_norm:

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.

param bool y_norm:

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.

param str x_label:

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

param str y_label:

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

param str data_colour:

Used to set the colour of the data points.

param str/List[str] model_colour:

The matplotlib colour(s) that should be used for plotted model fits (if applicable). Either a single colour name, or a list of colour names, may be passed depending on the number of models that are being plotted - if there are multiple models, and a single colour is passed, the plot will revert to the default matplotlib colour cycler. If a list is passed, those colours will be cycled through instead (if there are insufficient entries for the number of models an error will be raised). The default value is ‘seagreen’.

param bool show_legend:

Whether the legend should be displayed or not. Default is True.

param bool show_residual_ax:

Controls whether a lower axis showing the residuals between data and model (if a model is fitted and being shown) is displayed. Default is True.

param dict draw_vals:

A dictionary of extra y-values (as astropy quantities) to draw onto the plot, where the dictionary key they are stored under is what they will be labelled (keys can be LaTeX formatted); e.g. {r’$T_{

m{X,500}}$’: Quantity(6, ‘keV’)}. Quantities with uncertainties may also be

passed, and the error regions will be shaded; e.g. {r’$T_{

m{X,500}}$’: Quantity([6, 0.2, 0.3], ‘keV’)},

where 0.2 is the negative error, and 0.3 is the positive error.

param bool auto_legend:

If True, and show_legend has also been set to True, then the ‘best’ legend location will be defined by matplotlib, otherwise, if False, the legend will be added to the right hand side of the plot outside the main axes.

param bool joined_points:

If True, the data in the profile will be plotted as a line, rather than points, as will any uncertainty regions.

param dict axis_formatters:

A dictionary of formatters that can be applied to the profile plot. The keys can have the following values; ‘xmajor’, ‘xminor’, ‘ymajor’, and ‘yminor’. The values associated with the keys should be instantiated matplotlib formatters.

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, data_colour='black', model_colour='seagreen', show_legend=True, show_residual_ax=True, draw_vals={}, auto_legend=True, joined_points=False, axis_formatters=None)

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.

param Tuple figsize:

The desired size of the figure, the default is (10, 7)

param str xscale:

The scaling to be applied to the x axis, default is log.

param str yscale:

The scaling to be applied to the y axis, default is log.

param Tuple xlim:

The limits to be applied to the x axis, upper and lower, default is to let matplotlib decide by itself.

param Tuple ylim:

The limits to be applied to the y axis, upper and lower, default is to let matplotlib decide by itself.

param str models:

Should the fitted models to this profile be plotted, default is True

param bool back_sub:

Should the plotted data be background subtracted, default is True.

param bool just_models:

Should ONLY the fitted models be plotted? Default is False

param str custom_title:

A plot title to replace the automatically generated title, default is None.

param dict draw_rads:

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

param bool x_norm:

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.

param bool y_norm:

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.

param str x_label:

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

param str y_label:

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

param str data_colour:

Used to set the colour of the data points.

param str/List[str] model_colour:

The matplotlib colour(s) that should be used for plotted model fits (if applicable). Either a single colour name, or a list of colour names, may be passed depending on the number of models that are being plotted - if there are multiple models, and a single colour is passed, the plot will revert to the default matplotlib colour cycler. If a list is passed, those colours will be cycled through instead (if there are insufficient entries for the number of models an error will be raised). The default value is ‘seagreen’.

param bool show_legend:

Whether the legend should be displayed or not. Default is True.

param bool show_residual_ax:

Controls whether a lower axis showing the residuals between data and model (if a model is fitted and being shown) is displayed. Default is True.

param dict draw_vals:

A dictionary of extra y-values (as astropy quantities) to draw onto the plot, where the dictionary key they are stored under is what they will be labelled (keys can be LaTeX formatted); e.g. {r’$T_{

m{X,500}}$’: Quantity(6, ‘keV’)}. Quantities with uncertainties may also be

passed, and the error regions will be shaded; e.g. {r’$T_{

m{X,500}}$’: Quantity([6, 0.2, 0.3], ‘keV’)},

where 0.2 is the negative error, and 0.3 is the positive error.

param bool auto_legend:

If True, and show_legend has also been set to True, then the ‘best’ legend location will be defined by matplotlib, otherwise, if False, the legend will be added to the right hand side of the plot outside the main axes.

param bool joined_points:

If True, the data in the profile will be plotted as a line, rather than points, as will any uncertainty regions.

param dict axis_formatters:

A dictionary of formatters that can be applied to the profile plot. The keys can have the following values; ‘xmajor’, ‘xminor’, ‘ymajor’, and ‘yminor’. The values associated with the keys should be instantiated matplotlib formatters.

save_view(save_path, 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, data_colour='black', model_colour='seagreen', show_legend=True, show_residual_ax=True, draw_vals={}, auto_legend=True, joined_points=False, axis_formatters=None)

A method that allows us to save a view of 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.

This method will not display a figure, just save it at the supplied save_path.

param str save_path:

The path (including file name) where you wish to save the profile view.

param Tuple figsize:

The desired size of the figure, the default is (10, 7)

param str xscale:

The scaling to be applied to the x axis, default is log.

param str yscale:

The scaling to be applied to the y axis, default is log.

param Tuple xlim:

The limits to be applied to the x axis, upper and lower, default is to let matplotlib decide by itself.

param Tuple ylim:

The limits to be applied to the y axis, upper and lower, default is to let matplotlib decide by itself.

param str models:

Should the fitted models to this profile be plotted, default is True

param bool back_sub:

Should the plotted data be background subtracted, default is True.

param bool just_models:

Should ONLY the fitted models be plotted? Default is False

param str custom_title:

A plot title to replace the automatically generated title, default is None.

param dict draw_rads:

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

param bool x_norm:

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.

param bool y_norm:

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.

param str x_label:

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

param str y_label:

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

param str data_colour:

Used to set the colour of the data points.

param str/List[str] model_colour:

The matplotlib colour(s) that should be used for plotted model fits (if applicable). Either a single colour name, or a list of colour names, may be passed depending on the number of models that are being plotted - if there are multiple models, and a single colour is passed, the plot will revert to the default matplotlib colour cycler. If a list is passed, those colours will be cycled through instead (if there are insufficient entries for the number of models an error will be raised). The default value is ‘seagreen’.

param bool show_legend:

Whether the legend should be displayed or not. Default is True.

param bool show_residual_ax:

Controls whether a lower axis showing the residuals between data and model (if a model is fitted and being shown) is displayed. Default is True.

param dict draw_vals:

A dictionary of extra y-values (as astropy quantities) to draw onto the plot, where the dictionary key they are stored under is what they will be labelled (keys can be LaTeX formatted); e.g. {r’$T_{

m{X,500}}$’: Quantity(6, ‘keV’)}. Quantities with uncertainties may also be

passed, and the error regions will be shaded; e.g. {r’$T_{

m{X,500}}$’: Quantity([6, 0.2, 0.3], ‘keV’)},

where 0.2 is the negative error, and 0.3 is the positive error.

param bool auto_legend:

If True, and show_legend has also been set to True, then the ‘best’ legend location will be defined by matplotlib, otherwise, if False, the legend will be added to the right hand side of the plot outside the main axes.

param bool joined_points:

If True, the data in the profile will be plotted as a line, rather than points, as will any uncertainty regions.

param dict axis_formatters:

A dictionary of formatters that can be applied to the profile plot. The keys can have the following values; ‘xmajor’, ‘xminor’, ‘ymajor’, and ‘yminor’. The values associated with the keys should be instantiated matplotlib formatters.

save(save_path=None)

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 auto_save

Whether the profile will automatically save itself at any point (such as after successful model fits).

Returns:

Boolean flag describing whether auto-save is turned on.

Return type:

bool

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, 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 equivalent of 1kpc, if they have pixel units then it will be set to one pixel, and if they are equivalent 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 spec_fit_conf

If this profile was generated from an annular spectrum, this property provides the fit-configuration key of the spectral fits that provided the properties used to build it.

Returns:

The spectral fit-configuration key. If the spectral fit configuration key was never set, the return will be None.

Return type:

str

property spec_model

If this profile was generated from an annular spectrum, this property provides the name of the model that was fit to the spectra in order to measure the properties used to build it.

Returns:

The spectral model name. If the spectral model name was never set, the return will be None.

Return type:

str

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

property custom_aggregate_label

This property is a label that should be used in place of the source name associated with this profile when plotting multiple profiles on one axis through an aggregate profile instance.

Returns:

The custom label, default is None.

Return type:

str

class xga.products.base.BaseAggregateProfile1D(profiles)

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.

Parameters:

profiles (list) – A list of profile objects (of the same type) to include in this aggregate profile.

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, show_legend=True, just_model=False, custom_title=None, draw_rads={}, x_norm=False, y_norm=False, x_label=None, y_label=None, save_path=None, draw_vals={}, auto_legend=True, axis_formatters=None, show_residual_ax=True, joined_points=False)

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

param Tuple figsize:

The desired size of the figure, the default is (10, 7)

param str xscale:

The scaling to be applied to the x axis, default is log.

param str yscale:

The scaling to be applied to the y axis, default is log.

param Tuple xlim:

The limits to be applied to the x axis, upper and lower, default is to let matplotlib decide by itself.

param Tuple ylim:

The limits to be applied to the y axis, upper and lower, default is to let matplotlib decide by itself.

param str model:

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.

param bool back_sub:

Should the plotted data be background subtracted, default is True.

param bool show_legend:

Should a legend with source names be added to the figure, default is True.

param bool just_model:

Should only the models, not the data, be plotted. Default is False.

param str custom_title:

A plot title to replace the automatically generated title, default is None.

param dict draw_rads:

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.

param bool x_norm:

Should the x-axis values be normalised with the x_norm value passed on the definition of the constituent profile objects.

param bool y_norm:

Should the y-axis values be normalised with the y_norm value passed on the definition of the constituent profile objects.

param str x_label:

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

param str y_label:

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

param str save_path:

The path where the figure produced by this method should be saved. Default is None, in which case the figure will not be saved.

param dict draw_vals:

A dictionary of extra y-values (as astropy quantities) to draw onto the plot, where the dictionary key they are stored under is what they will be labelled (keys can be LaTeX formatted); e.g. {r’$T_{

m{X,500}}$’: Quantity(6, ‘keV’)}. Quantities with uncertainties may also be

passed, and the error regions will be shaded; e.g. {r’$T_{

m{X,500}}$’:

Quantity([6, 0.2, 0.3], ‘keV’)}, where 0.2 is the negative error, and 0.3 is the positive error. Finally, plotting colour may be specified by setting the value to a list, with the first entry being the quantity, and the second being a colour; e.g. {r’$T_{

m{X,500}}$’: [Quantity([6, 0.2, 0.3], ‘keV’), ‘tab:blue’]}.

param bool auto_legend:

If True, and show_legend has also been set to True, then the ‘best’ legend location will be defined by matplotlib, otherwise, if False, the legend will be added to the right hand side of the plot outside the main axes.

param dict axis_formatters:

A dictionary of formatters that can be applied to the profile plot. The keys can have the following values; ‘xmajor’, ‘xminor’, ‘ymajor’, and ‘yminor’. The values associated with the keys should be instantiated matplotlib formatters.

param bool show_residual_ax:

Controls whether a lower axis showing the residuals between data and model (if a model is fitted and being shown) is displayed. Default is True.

param bool joined_points:

If True, the data in the profiles will be plotted as a line, rather than points, as will any uncertainty regions.

products.misc module

class xga.products.misc.EventList(path, obs_id=None, instrument=None, stdout_str=None, stderr_str=None, gen_cmd=None, telescope=None, obs_ids=None, force_remote=False, fsspec_kwargs=None)

Bases: BaseProduct

A product class for event lists, it stores information about the event list.

Parameters:

• path (str) – The path to the event list file, OR an S3-bucket (or S3-bucket-like) path/url to stream the event list data from.

• obs_id (str) – The ObsID related to the event list being declared.

• instrument (str) – The instrument related to the event list being declared.

• stdout_str (str) – The stdout from calling the terminal command.

• stderr_str (str) – The stderr from calling the terminal command.

• gen_cmd (str) – The command used to generate the event list.

• telescope (str) – The telescope that is the source of this event list. The default is None.

• obs_ids (List[str]) – The obs ids that were combined to make this event list. The default is None.

• force_remote (bool) – Used to force the product instantiation to treat the passed path string as a url to a remote dataset, and to use fsspec to read/stream the data.

• fsspec_kwargs (dict) – Optional arguments that can be passed fsspec when reading or streaming remote datasets - e.g. to pass credentials to access an S3 bucket. Default value is None, which sets the argument to {“anon”: True}, making it instantly compatible with NASA archive S3 buckets.

property obs_ids

Property getter for the ObsIDs that are involved in this Eventlist, if combined. Otherwise will return a list with one element, the single relevant ObsID.

Returns:

List of ObsIDs involved in this EventList.

Return type:

list

property header

The primary header object of this event list.

Returns:

The primary header of the event list.

Return type:

fits.Header

property event_header

The header object of the events table in this event list.

Returns:

The event table header of the event list.

Return type:

fits.Header

property data

Property getter allowing access to the astropy fits header object of this event list.

Returns:

The header of the primary data table of the event list.

Return type:

pd.DataFrame

property radec_sky_wcs

WCS information that relates this event list’s ‘sky’ coordinate system (or the system that is primary and used for imaging positions) to RA-Dec coordinates.

Returns:

The WCS information that relates this event list’s ‘sky’ coordinate system to RA-Dec coordinates.

Return type:

astropy.wcs.WCS

property deg_per_sky

Uses the Sky-RA/Dec WCS (accessible through the radec_sky_wcs property) to provide the angular size of a pixel in the sky coordinate system - both x and y directions are returned, though they are often the same.

Returns:

A two-entry non-scalar property, with the first entry being the x-direction sky pixel scale and the second being the y-direction sky pixel scale.

Return type:

Quantity

property sky_pix_lims

The X and Y pixel limits of the sky coordinate system (or the system that is primary and used for imaging positions).

Returns:

Two non-scalar quantities, with the first representing the lower and upper allowed values for the primary coordinate (usually sky) coordinate system x-axis, and the second being for the y-axis.

Return type:

Tuple[Quantity, Quantity]

get_columns_from_data(col_names)

This method allows you to retrieve specific columns from the event list table, without loading the whole table into memory.

Parameters:

col_names (List[str]) – A list of column names to retrieve.

Returns:

A pandas DataFrame containing the specified columns.

Return type:

pd.DataFrame

unload(unload_data=True, unload_header=True)

This method allows you to safely remove the header and/or data information stored in memory.

Parameters:

• unload_data (bool) – Specifies whether the data should be unloaded from memory. Default is True, as the event list data is liable to take up far more memory than the header, meaning it is more likely to need to be removed.

• unload_header (bool) – Specifies whether the header should be unloaded from memory. Default is True.

generate_image(bin_size=None, x_lims=None, y_lims=None, lo_en=None, hi_en=None, donor_image=None, save_path=None)

Returns:

Return type:

products.phot module

class xga.products.phot.Image(path, obs_id, instrument, stdout_str, stderr_str, gen_cmd, lo_en, hi_en, regs='', matched_regs=None, smoothed=False, smoothed_info=None, obs_inst_combs=None)

Bases: 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).

Parameters:

• path (str) – The path to where the product file SHOULD be located.

• obs_id (str) – The ObsID related to the Image being declared.

• instrument (str) – The instrument related to the Image being declared.

• stdout_str (str) – The stdout from calling the terminal command.

• stderr_str (str) – The stderr from calling the terminal command.

• gen_cmd (str) – The command used to generate the product.

• lo_en (Quantity) – The lower energy bound used to generate this product.

• hi_en (Quantity) – The upper energy bound used to generate this product.

• regs (str/List[SkyRegion/PixelRegion]/dict) – A region list file path, a list of region objects, or a dictionary of region lists with ObsIDs as dictionary keys.

• matched_regs (dict/SkyRegion/PixelRegion) – Similar to the regs argument, but in this case for a region that has been designated as ‘matched’, i.e. is the subject of a current analysis. This should either be supplied as a single region object, or as a dictionary of region objects with ObsIDs as keys, or None values if there is no match. Such a dictionary can be retrieved from a source using the ‘matched_regions’ property. Default is None.

• smoothed (bool) – Has this image been smoothed, default is False. This information can also be set after the instantiation of an image.

• smoothed_info (dict/Kernel) – Information on how the image was smoothed, given either by the Astropy kernel used or a dictionary of information (required structure detailed in parse_smoothing). Default is None

• obs_inst_combs (List[List]) – Supply a list of lists of ObsID-Instrument combinations if the image is combined and wasn’t made by emosaic (e.g. [[‘0404910601’, ‘pn’], [‘0404910601’, ‘mos1’], [‘0404910601’, ‘mos2’], [‘0201901401’, ‘pn’], [‘0201901401’, ‘mos1’], [‘0201901401’, ‘mos2’]].

static parse_smoothing(info)

Parses smoothing information that has been passed into the Image object, either on init or afterwards. If an Astropy kernel is provided then the name, and kernel parameter, will be extracted. If a dictionary is provided then it must have a) ‘method’ key with the name of the smoothing method, and b) a ‘pars’ key with another dictionary of all the parameters involved in smoothing; e.g. {‘method’: ‘Gaussian2DKernel’, ‘pars’: {‘amplitude’: 0.63, ‘x_mean’: 0.0, ‘y_mean’: 0.0, ‘x_stddev’: 0.5,

‘y_stddev’: 0.5, ‘theta’: 0.0}}

Parameters:

info (dict/Kernel) – The information dictionary or astropy kernel used for the smoothing.

Returns:

The name of the kernel/method and parameter information

Return type:

Tuple[str, dict]

property smoothing_info

If the image has been smoothed, then this property getter will return information on the smoothing done.

Returns:

A dictionary of information on the smoothing applied (if any). Default is None if no smoothing applied.

Return type:

dict

property smoothed_method

The name of the smoothing method (or kernel) that has been applied.

Returns:

Name of method/kernel, default is None if no smoothing has been applied.

Return type:

str

property smoothed

Property describing whether an image product has been smoothed or not.

Returns:

Has the product been smoothed.

Return type:

bool

property storage_key

The key under which this object should be stored in a source’s product structure. Contains information about various aspects of the Image/RateMap/ExpMap.

Returns:

The storage key.

Return type:

str

property obs_inst_combos

This property getter will provide ObsID-Instrument information on the constituent images that make up this total image (if it is combined), otherwise it will just provide the single ObsID-Instrument combo.

Returns:

A list of lists of ObsID-Instrument combinations, or a list containing one ObsID and one instrument.

Return type:

list

property obs_ids

Property getter for the ObsIDs that are involved in this image, if combined. Otherwise will return a list with one element, the single relevant ObsID.

Returns:

List of ObsIDs involved in this image.

Return type:

list

property instruments

Equivelant to the BaseSource instruments property, this will return a dictionary of ObsIDs with lists of instruments that are associated with them in a combined image. If the image is not combined then an equivelant dictionary with one key (the ObsID), with the associated value being a list with one entry (the instrument).

Returns:

A dictionary of ObsIDs and their associated instruments

Return type:

dict

property inventory_entry

This allows an Image product to generate its own entry for the XGA file generation inventory.

Returns:

The new line entry for the inventory.

Return type:

pd.Series

property regions

Property getter for regions associated with this image.

Returns:

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

Return type:

Dict[PixelRegion]

property matched_regions

Property getter for any regions which have been designated a ‘match’ in the current analysis, if they have been set.

Returns:

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

Return type:

Dict[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 data_unit

The unit of the data associated with this photometric product.

Returns:

An astropy unit object describing the units of this objects’ data.

Return type:

Unit

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)

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_count(at_coord)

A simple method that converts the given coordinates to pixels, then finds the number of counts at those coordinates.

Parameters:

at_coord (Quantity) – Coordinate at which to find the number of counts.

Returns:

The counts at the supplied coordinates.

Return type:

Quantity

simple_peak(mask, out_unit=Unit('deg'))

Simplest possible way to find the position of the peak of X-ray emission in an Image. 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).

Results from this can be less valid than the RateMap implementation (especially if the object you care about is off-axis), as that takes into account vignetting corrected exposure times.

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/str) – 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. A null value is also returned in place of the boolean flag describing whether the coordinates are near an edge or not that RateMap returns.

Return type:

Tuple[Quantity, 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, low_val_lim=None, upp_val_lim=None, custom_title=None)

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, as this acts as the central coordinate of the annuli. If two cross-hair coordinates are specified, the first will be used as the centre.

• 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, as this acts as the central coordinate of the annuli. If two cross-hair coordinates are specified, the first will be used as the centre.

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

• low_val_lim (float) – This can be used to set a lower limit for the value range across which an image is scaled and normalised (i.e. a ManualInterval from Astropy). The default is None, and if low_val_lim is not None, upp_val_lim must be as well.

• upp_val_lim (float) – This can be used to set an upper limit for the value range across which an image is scaled and normalised (i.e. a ManualInterval from Astropy). The default is None, and if upp_val_lim is not None, low_val_lim must be as well.

• custom_title (str) – If set, this will overwrite the automatically generated title for this visualisation. Default is None.

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, low_val_lim=None, upp_val_lim=None, custom_title=None)

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.

• low_val_lim (float) – This can be used to set a lower limit for the value range across which an image is scaled and normalised (i.e. a ManualInterval from Astropy). The default is None, and if low_val_lim is not None, upp_val_lim must be as well.

• upp_val_lim (float) – This can be used to set an upper limit for the value range across which an image is scaled and normalised (i.e. a ManualInterval from Astropy). The default is None, and if upp_val_lim is not None, low_val_lim must be as well.

• custom_title (str) – If set, this will overwrite the automatically generated title for this visualisation. Default is None.

save_view(save_path, 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, low_val_lim=None, upp_val_lim=None, custom_title=None)

This is entirely equivalent to the view() method, but instead of displaying the view it will save it to a path of your choosing.

Parameters:

• save_path (str) – The path (including file name) where you wish to save the view.

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

• low_val_lim (float) – This can be used to set a lower limit for the value range across which an image is scaled and normalised (i.e. a ManualInterval from Astropy). The default is None, and if low_val_lim is not None, upp_val_lim must be as well.

• upp_val_lim (float) – This can be used to set an upper limit for the value range across which an image is scaled and normalised (i.e. a ManualInterval from Astropy). The default is None, and if upp_val_lim is not None, low_val_lim must be as well.

• custom_title (str) – If set, this will overwrite the automatically generated title for this visualisation. Default is None.

edit_regions(figsize=(7, 7), cmap='gnuplot2', reg_save_path=None, cross_hair=None, radial_bins_pix=<Quantity [] pix>, back_bin_pix=None)

This allows for displaying, interacting with, editing, and adding new regions to an image. These can then be saved as a new region file. It also allows for the dynamic adjustment of which regions are displayed, the scaling of the image, and smoothing, in order to make placing new regions as simple as possible. If a save path for region files is passed, then it will be possible to save new region files in RA-Dec coordinates.

Parameters:

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

• cmap (str) – The colour map to use for displaying the image. Default is gnuplot2.

• reg_save_path (str) – A string that will have ObsID values added before ‘.reg’ to construct save paths for the output region lists (if that feature is activated by the user). Default is None, in which case saving will be disabled.

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

• radial_bins_pix (Quantity) – 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 (Quantity) – 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.

dynamic_view(figsize=(7, 7), cmap='gnuplot2', cross_hair=None, radial_bins_pix=<Quantity [] pix>, back_bin_pix=None)

This allows for displaying regions on an image. It also allows for the dynamic adjustment of which regions are displayed, the scaling of the image, and smoothing.

Parameters:

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

• cmap (str) – The colour map to use for displaying the image. Default is gnuplot2.

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

• radial_bins_pix (Quantity) – 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 (Quantity) – 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.

class xga.products.phot.ExpMap(path, obs_id, instrument, stdout_str, stderr_str, gen_cmd, lo_en, hi_en, obs_inst_combs=None)

Bases: Image

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

Parameters:

• path (str) – The path to where the product file SHOULD be located.

• obs_id (str) – The ObsID related to the ExpMap being declared.

• instrument (str) – The instrument related to the ExpMap being declared.

• stdout_str (str) – The stdout from calling the terminal command.

• stderr_str (str) – The stderr from calling the terminal command.

• gen_cmd (str) – The command used to generate the product.

• lo_en (Quantity) – The lower energy bound used to generate this product.

• hi_en (Quantity) – The upper energy bound used to generate this product.

• obs_inst_combs (List[List]) – Supply a list of lists of ObsID-Instrument combinations if the image is combined and wasn’t made by emosaic (e.g. [[‘0404910601’, ‘pn’], [‘0404910601’, ‘mos1’], [‘0404910601’, ‘mos2’], [‘0201901401’, ‘pn’], [‘0201901401’, ‘mos1’], [‘0201901401’, ‘mos2’]].

get_exp(at_coord)

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

get_count(*args, **kwargs)

Inherited method from Image superclass, disabled as does not make sense in an exposure map.

property smoothing_info

As exposure maps cannot be smoothed, this property overrides the Image smoothing_info getter, and returns None.

Returns:

None, as exposure maps cannot be smoothed.

Return type:

None

class xga.products.phot.RateMap(xga_image, xga_expmap, regs='', matched_regs=None)

Bases: 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.

Parameters:

• xga_image (Image) – The image component of the RateMap.

• xga_expmap (ExpMap) – The exposure map component of the RateMap.

• regs (str/List[SkyRegion/PixelRegion]/dict) – A region list file path, a list of region objects, or a dictionary of region lists with ObsIDs as dictionary keys.

• matched_regs (dict/SkyRegion/PixelRegion) – Similar to the regs argument, but in this case for a region that has been designated as ‘matched’, i.e. is the subject of a current analysis. This should either be supplied as a single region object, or as a dictionary of region objects with ObsIDs as keys, or None values if there is no match. Such a dictionary can be retrieved from a source using the ‘matched_regions’ property. Default is None.

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)

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

get_count(at_coord)

A simple method that converts the given coordinates to pixels, then finds the number of counts at those coordinates.

Parameters:

at_coord (Quantity) – Coordinate at which to find the number of counts.

Returns:

The counts at the supplied coordinates.

Return type:

Quantity

get_exp(at_coord)

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

simple_peak(mask, out_unit=Unit('deg'))

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/str) – 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)

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/str) – 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'))

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 peak 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)

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)

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

background_subtracted_counts(source_mask, back_mask)

This method uses a user-supplied source and background mask (alongside knowledge of the sensor layout drawn from the exposure map) to calculate the number of background-subtracted counts within the source region of the image used to construct this RateMap.

The exposure map is used to construct a sensor mask, so that we know where the chip gaps are and take them into account when calculating the ratio of areas of the source region to the background region. This is why this method is built into the RateMap rather than Image class.

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.

Returns:

The background subtracted counts in the source region.

Return type:

Quantity

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

property regions

Property getter for regions associated with this ratemap.

Returns:

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

Return type:

Dict[PixelRegion]

property matched_regions

Property getter for any regions which have been designated a ‘match’ in the current analysis, if they have been set.

Returns:

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

Return type:

Dict[PixelRegion]

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

Bases: Image

A subclass of image that is a wrapper for 2D images of PSFs that can be generated by SAS. This can be used to view the PSF and is used in other analyses to correct images.

Parameters:

• path (str) – The path to where the product file SHOULD be located.

• psf_model (str) – The model used for the generation of the PSF.

• obs_id (str) – The ObsID related to the PSF being declared.

• instrument (str) – The instrument related to the PSF being declared.

• stdout_str (str) – The stdout from calling the terminal command.

• stderr_str (str) – The stderr from calling the terminal command.

• gen_cmd (str) – The command used to generate the product.

get_val(at_coord)

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

Parameters:

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

Returns:

The PSF value at the supplied coordinates.

Return type:

Quantity

resample(im_prod, half_side_length)

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)

Bases: BaseAggregateProduct

Parameters:

• file_paths (list) – The file paths of the individual PSF files for this grid.

• bins (int) – The number of bins per side of the grid.

• psf_model (str) – The model used to generate PSFs.

• x_bounds (np.ndarray) – The upper and lower x boundaries of the bins in image pixel coordinates.

• y_bounds (np.ndarray) – The upper and lower y boundaries of the bins in image pixel coordinates.

• obs_id (str) – The ObsID for which this PSFGrid was generated.

• instrument (str) – The instrument for which this PSFGrid was generated.

• stdout_str (str) – The stdout from calling the terminal command.

• stderr_str (str) – The stderr from calling the terminal command.

• gen_cmd (str) – The commands used to generate the products.

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

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, auto_save=False)

Bases: BaseProfile1D

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

Parameters:

• rt (RateMap) – The RateMap from which this SB profile was generated.

• radii (Quantity) – The radii at which surface brightness has been measured.

• values (Quantity) – The surface brightnesses that have been measured.

• centre (Quantity) – The central coordinate the profile was generated from.

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

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

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

• radii_err (Quantity) – Uncertainties on the radii.

• values_err (Quantity) – Uncertainties on the values.

• background (Quantity) – The background brightness value.

• pixel_bins (np.ndarray) – An optional argument that provides the pixel bins used to create the profile.

• back_pixel_bin (np.ndarray) – An optional argument that provides the pixel bin used for the background calculation of this profile.

• ann_areas (Quantity) – The area of the annuli.

• deg_radii (Quantity) – A slightly unfortunate variable that is required only if radii is not in units of degrees, or if no set_storage_key is passed. It should be a quantity containing the radii values converted to degrees, and allows this object to construct a predictable storage key.

• min_snr_succeeded (bool) – A boolean flag describing whether re-binning was successful or not.

• auto_save (bool) – Whether the profile should automatically save itself to disk at any point. The default is False, but all profiles generated through XGA processes acting on XGA sources will auto-save.

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)

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, auto_save=False, spec_model=None, fit_conf=None)

Bases: BaseProfile1D

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

Parameters:

• radii (Quantity) – The radii at which gas mass has been measured.

• values (Quantity) – The gas mass that have been measured.

• centre (Quantity) – The central coordinate the profile was generated from.

• source_name (str) – The name of the source this profile is associated with.

• obs_id (str) – The observation which this profile was generated from.

• inst (str) – The instrument which this profile was generated from.

• dens_method (str) – A keyword describing the method used to generate the density profile that was used to measure this gas mass profile.

• associated_prof (SurfaceBrightness1D/APECNormalisation1D) – The profile that the gas density profile was measured from.

• radii_err (Quantity) – Uncertainties on the radii.

• values_err (Quantity) – Uncertainties on the values.

• deg_radii (Quantity) – A slightly unfortunate variable that is required only if radii is not in units of degrees, or if no set_storage_key is passed. It should be a quantity containing the radii values converted to degrees, and allows this object to construct a predictable storage key.

• auto_save (bool) – Whether the profile should automatically save itself to disk at any point. The default is False, but all profiles generated through XGA processes acting on XGA sources will auto-save.

• spec_model (str) – The spectral model that was fit to annular spectra to measure the results that were used to create this profile. Only relevant to profiles that are generated from annular spectra, default is None.

• fit_conf (str) – The key that describes the fit-configuration used when fitting models to annular spectra to measure the results that were then used to create this profile. Only relevant to profiles that are generated from annular spectra, default is None.

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, auto_save=False, spec_model=None, fit_conf=None)

Bases: BaseProfile1D

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

Parameters:

• radii (Quantity) – The radii at which gas density has been measured.

• values (Quantity) – The gas densities that have been measured.

• centre (Quantity) – The central coordinate the profile was generated from.

• source_name (str) – The name of the source this profile is associated with.

• obs_id (str) – The observation which this profile was generated from.

• inst (str) – The instrument which this profile was generated from.

• dens_method (str) – A keyword describing the method used to generate this density profile.

• associated_prof (SurfaceBrightness1D/APECNormalisation1D) – The profile that this gas density profile was measured from.

• radii_err (Quantity) – Uncertainties on the radii.

• values_err (Quantity) – Uncertainties on the values.

• associated_set_id (int) – The set ID of the AnnularSpectra that generated this - if applicable. It is possible for a Gas Density profile to be generated from spectral or photometric information.

• set_storage_key (str) – Must be present if associated_set_id is, this is the storage key which the associated AnnularSpectra generates to place itself in XGA’s store structure.

• deg_radii (Quantity) – A slightly unfortunate variable that is required only if radii is not in units of degrees, or if no set_storage_key is passed. It should be a quantity containing the radii values converted to degrees, and allows this object to construct a predictable storage key.

• auto_save (bool) – Whether the profile should automatically save itself to disk at any point. The default is False, but all profiles generated through XGA processes acting on XGA sources will auto-save.

• spec_model (str) – The spectral model that was fit to annular spectra to measure the results that were used to create this profile. Only relevant to profiles that are generated from annular spectra, default is None.

• fit_conf (str) – The key that describes the fit-configuration used when fitting models to annular spectra to measure the results that were then used to create this profile. Only relevant to profiles that are generated from annular spectra, default is None.

gas_mass(model, outer_rad, inner_rad=None, conf_level=68.2, fit_method='mcmc', radius_err=None)

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.

Passing uncertainties on the outer (and inner) radii for the gas mass calculation is supported, with such uncertainties assumed to be representing a Gaussian distribution. Radii distributions will be drawn from a Gaussian, though any radii that are negative will be set to zero, so it could be a truncated Gaussian.

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. Only one radius may be passed at a time.

• inner_rad (Quantity) – The inner radius within which to measure the gas mass, this enables measuring core-excised gas masses. Default is None, which equates to zero. If passing separate uncertainties for inner and outer radii using `radius_err’, the inner radius error must be the second entry.

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

• radius_err (Quantity) – A standard deviation on radius, which will be taken into account during the calculation of gas mass. If both an inner and outer radius have been passed, then you may pass either a single standard deviation value for both, or a Quantity with two entries. THE FIRST being the outer radius error, THE SECOND being inner radius error.

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='lightseagreen', fit_method='mcmc')

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')

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, auto_save=False, spec_model=None, fit_conf=None)

Bases: 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.

Parameters:

• radii (Quantity) – The radii at which the projected gas temperatures have been measured, this should be in a proper radius unit, such as kpc.

• values (Quantity) – The projected gas temperatures that have been measured.

• centre (Quantity) – The central coordinate the profile was generated from.

• source_name (str) – The name of the source this profile is associated with.

• obs_id (str) – The observation which this profile was generated from.

• inst (str) – The instrument which this profile was generated from.

• radii_err (Quantity) – Uncertainties on the radii.

• values_err (Quantity) – Uncertainties on the values.

• associated_set_id (int) – The set ID of the AnnularSpectra that generated this - if applicable.

• set_storage_key (str) – Must be present if associated_set_id is, this is the storage key which the associated AnnularSpectra generates to place itself in XGA’s store structure.

• deg_radii (Quantity) – A slightly unfortunate variable that is required only if radii is not in units of degrees, or if no set_storage_key is passed. It should be a quantity containing the radii values converted to degrees, and allows this object to construct a predictable storage key.

• auto_save (bool) – Whether the profile should automatically save itself to disk at any point. The default is False, but all profiles generated through XGA processes acting on XGA sources will auto-save.

• spec_model (str) – The spectral model that was fit to annular spectra to measure the results that were used to create this profile. Only relevant to profiles that are generated from annular spectra, default is None.

• fit_conf (str) – The key that describes the fit-configuration used when fitting models to annular spectra to measure the results that were then used to create this profile. Only relevant to profiles that are generated from annular spectra, default is None.

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, auto_save=False, spec_model=None, fit_conf=None)

Bases: 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.

Parameters:

• radii (Quantity) – The radii at which the APEC normalisations have been measured, this should be in a proper radius unit, such as kpc.

• values (Quantity) – The APEC normalisations that have been measured.

• centre (Quantity) – The central coordinate the profile was generated from.

• source_name (str) – The name of the source this profile is associated with.

• obs_id (str) – The observation which this profile was generated from.

• inst (str) – The instrument which this profile was generated from.

• radii_err (Quantity) – Uncertainties on the radii.

• values_err (Quantity) – Uncertainties on the values.

• associated_set_id (int) – The set ID of the AnnularSpectra that generated this - if applicable.

• set_storage_key (str) – Must be present if associated_set_id is, this is the storage key which the associated AnnularSpectra generates to place itself in XGA’s store structure.

• deg_radii (Quantity) – A slightly unfortunate variable that is required only if radii is not in units of degrees, or if no set_storage_key is passed. It should be a quantity containing the radii values converted to degrees, and allows this object to construct a predictable storage key.

• auto_save (bool) – Whether the profile should automatically save itself to disk at any point. The default is False, but all profiles generated through XGA processes acting on XGA sources will auto-save.

• spec_model (str) – The spectral model that was fit to annular spectra to measure the results that were used to create this profile. Only relevant to profiles that are generated from annular spectra, default is None.

• fit_conf (str) – The key that describes the fit-configuration used when fitting models to annular spectra to measure the results that were then used to create this profile. Only relevant to profiles that are generated from annular spectra, default is None.

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

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)

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, auto_save=False, spec_model=None, fit_conf=None)

Bases: BaseProfile1D

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

Parameters:

• radii (Quantity) – The radii at which the emission measures have been measured, this should be in a proper radius unit, such as kpc.

• values (Quantity) – The emission measures that have been measured.

• centre (Quantity) – The central coordinate the profile was generated from.

• source_name (str) – The name of the source this profile is associated with.

• obs_id (str) – The observation which this profile was generated from.

• inst (str) – The instrument which this profile was generated from.

• radii_err (Quantity) – Uncertainties on the radii.

• values_err (Quantity) – Uncertainties on the values.

• associated_set_id (int) – The set ID of the AnnularSpectra that generated this - if applicable.

• set_storage_key (str) – Must be present if associated_set_id is, this is the storage key which the associated AnnularSpectra generates to place itself in XGA’s store structure.

• deg_radii (Quantity) – A slightly unfortunate variable that is required only if radii is not in units of degrees, or if no set_storage_key is passed. It should be a quantity containing the radii values converted to degrees, and allows this object to construct a predictable storage key.

• auto_save (bool) – Whether the profile should automatically save itself to disk at any point. The default is False, but all profiles generated through XGA processes acting on XGA sources will auto-save.

• spec_model (str) – The spectral model that was fit to annular spectra to measure the results that were used to create this profile. Only relevant to profiles that are generated from annular spectra, default is None.

• fit_conf (str) – The key that describes the fit-configuration used when fitting models to annular spectra to measure the results that were then used to create this profile. Only relevant to profiles that are generated from annular spectra, default is None.

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, auto_save=False, spec_model=None, fit_conf=None)

Bases: 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.

Parameters:

• radii (Quantity) – The radii at which the projected gas metallicity have been measured, this should be in a proper radius unit, such as kpc.

• values (Quantity) – The projected gas metallicity that have been measured.

• centre (Quantity) – The central coordinate the profile was generated from.

• source_name (str) – The name of the source this profile is associated with.

• obs_id (str) – The observation which this profile was generated from.

• inst (str) – The instrument which this profile was generated from.

• radii_err (Quantity) – Uncertainties on the radii.

• values_err (Quantity) – Uncertainties on the values.

• associated_set_id (int) – The set ID of the AnnularSpectra that generated this - if applicable.

• set_storage_key (str) – Must be present if associated_set_id is, this is the storage key which the associated AnnularSpectra generates to place itself in XGA’s store structure.

• deg_radii (Quantity) – A slightly unfortunate variable that is required only if radii is not in units of degrees, or if no set_storage_key is passed. It should be a quantity containing the radii values converted to degrees, and allows this object to construct a predictable storage key.

• auto_save (bool) – Whether the profile should automatically save itself to disk at any point. The default is False, but all profiles generated through XGA processes acting on XGA sources will auto-save.

• spec_model (str) – The spectral model that was fit to annular spectra to measure the results that were used to create this profile. Only relevant to profiles that are generated from annular spectra, default is None.

• fit_conf (str) – The key that describes the fit-configuration used when fitting models to annular spectra to measure the results that were then used to create this profile. Only relevant to profiles that are generated from annular spectra, default is None.

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, auto_save=False, spec_model=None, fit_conf=None)

Bases: 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.

Parameters:

• radii (Quantity) – The radii at which the gas temperatures have been measured, this should be in a proper radius unit, such as kpc.

• values (Quantity) – The gas temperatures that have been measured.

• centre (Quantity) – The central coordinate the profile was generated from.

• source_name (str) – The name of the source this profile is associated with.

• obs_id (str) – The observation which this profile was generated from.

• inst (str) – The instrument which this profile was generated from.

• radii_err (Quantity) – Uncertainties on the radii.

• values_err (Quantity) – Uncertainties on the values.

• associated_set_id (int) – The set ID of the AnnularSpectra that generated this - if applicable.

• set_storage_key (str) – Must be present if associated_set_id is, this is the storage key which the associated AnnularSpectra generates to place itself in XGA’s store structure.

• deg_radii (Quantity) – A slightly unfortunate variable that is required only if radii is not in units of degrees, or if no set_storage_key is passed. It should be a quantity containing the radii values converted to degrees, and allows this object to construct a predictable storage key.

• auto_save (bool) – Whether the profile should automatically save itself to disk at any point. The default is False, but all profiles generated through XGA processes acting on XGA sources will auto-save.

• spec_model (str) – The spectral model that was fit to annular spectra to measure the results that were used to create this profile. Only relevant to profiles that are generated from annular spectra, default is None.

• fit_conf (str) – The key that describes the fit-configuration used when fitting models to annular spectra to measure the results that were then used to create this profile. Only relevant to profiles that are generated from annular spectra, default is None.

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, auto_save=False, spec_model=None, fit_conf=None)

Bases: 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.

Parameters:

• radii (Quantity) – The radii at which the baryon fracion have been measured, this should be in a proper radius unit, such as kpc.

• values (Quantity) – The baryon fracions that have been measured.

• centre (Quantity) – The central coordinate the profile was generated from.

• source_name (str) – The name of the source this profile is associated with.

• obs_id (str) – The observation which this profile was generated from.

• inst (str) – The instrument which this profile was generated from.

• radii_err (Quantity) – Uncertainties on the radii.

• values_err (Quantity) – Uncertainties on the values.

• associated_set_id (int) – The set ID of the AnnularSpectra that generated this - if applicable.

• set_storage_key (str) – Must be present if associated_set_id is, this is the storage key which the associated AnnularSpectra generates to place itself in XGA’s store structure.

• deg_radii (Quantity) – A slightly unfortunate variable that is required only if radii is not in units of degrees, or if no set_storage_key is passed. It should be a quantity containing the radii values converted to degrees, and allows this object to construct a predictable storage key.

• auto_save (bool) – Whether the profile should automatically save itself to disk at any point. The default is False, but all profiles generated through XGA processes acting on XGA sources will auto-save.

• spec_model (str) – The spectral model that was fit to annular spectra to measure the results that were used to create this profile. Only relevant to profiles that are generated from annular spectra, default is None.

• fit_conf (str) – The key that describes the fit-configuration used when fitting models to annular spectra to measure the results that were then used to create this profile. Only relevant to profiles that are generated from annular spectra, default is None.

class xga.products.profile.HydrostaticMass(temperature_profile, density_profile, temperature_model=None, density_model=None, radii=None, radii_err=None, deg_radii=None, fit_method='mcmc', num_walkers=20, num_steps=20000, num_samples=1000, show_warn=True, progress=True, interp_data=False, allow_unphysical=False, auto_save=False, spec_model=None, fit_conf=None)

Bases: BaseProfile1D

A profile product which uses input temperature and density profiles to calculate a cumulative hydrostatic mass profile - used in galaxy cluster analyses (https://ui.adsabs.harvard.edu/abs/2024arXiv240307982T/abstract for instance). Similar in function to the SpecificEntropy profile class, in that hydrostatic mass values are calculated during the declaration of this class from multiple other profiles, rather than being passed in directly.

The hydrostatic mass profile can be used with several different kinds of input profiles, reflecting some of the different ways that they are calculated in the literature, and the practical limitations of generating ‘de-projected’ profiles. In short, this profile can be used in the following different ways:

• Either projected, or de-projected (inferred 3D profiles) can be passed to this profile; the temperature and density profiles also do not need to both be projected or both be de-projected. Clearly, from a purely physical point of view, it would be better to pass 3D profiles, but practically de-projection processes often cause a lot of problems, so the choice is left to the user.

• The hydrostatic mass values can be calculated either from models fit to the input profiles, or from the data points of the input profiles. This means that the user can choose between a ‘cleaner’ profile from generated from smooth models, or a data-driven profile that might better represent the intricacies of the particular galaxy cluster.

• If data points are being used rather than models, and the radial binning is different between the temperature and density profiles, then the data points on the profile with wider bins can either be interpolated, or matched to the data points of the other profile that they cover.

Parameters:

• temperature_profile (GasTemperature3D/ProjectedGasTemperature1D) – The XGA 3D or projected temperature profile to take temperature information from.

• temperature_model (str/BaseModel1D) – The model to fit to the temperature profile (if smooth models are to be used to calculate the hydrostatic mass profile), either a name or an instance of an XGA temperature model class. Default is None, in which case this class will use profile data points to calculate hydrostatic mass.

• density_profile (GasDensity3D) – The XGA 3D density profile to take density information from.

• density_model (str/BaseModel1D) – The model to fit to the density profile (if smooth models are to be used to calculate the hydrostatic mass profile), either a name or an instance of an XGA density model class. Default is None, in which case this class will use profile data points to calculate hydrostatic mass.

• radii (Quantity) – The radii at which to measure the hydrostatic mass - this is only necessary if model fits are being used to calculate hydrostatic mass, otherwise profile radii will be used.

• radii_err (Quantity) – The uncertainties on the radii - this is only necessary if model fits are being used to calculate hydrostatic mass, otherwise profile radii errors will be used.

• deg_radii (Quantity) – The radii values, but in units of degrees - this is only necessary if model fits are being used to calculate hydrostatic mass, otherwise profile radii will be used.

• fit_method (str) – The name of the fit method to use for the fitting of the profiles, default is ‘mcmc’.

• num_walkers (int) – If the fit method is ‘mcmc’ then this will set the number of walkers for the emcee sampler to set up.

• num_steps (list/int) – If the fit method is ‘mcmc’ this will set the number of steps for each sampler to take. If a single number is passed then that number of steps is used for both profiles, otherwise if a list is passed the first entry is used for the temperature fit, and the second for the density fit.

• num_samples (int) – The number of random samples to be drawn from the posteriors of the fit results.

• show_warn (bool) – Controls whether warnings produced the fitting processes are displayed.

• progress (bool) – Controls whether fit progress bars are displayed.

• interp_data (bool) – If the hydrostatic mass profile is to be derived from data points rather than fitted models, this controls whether the data profile with the coarser bins is interpolated, or whether the other profile’s data points are matched with the value that was measured for the radial region they are in (the default).

• allow_unphysical (bool) – This controls whether unphysical mass results are ‘allowed’ without an exception being raised (e.g. if a calculated mass value is negative). Default is False.

• auto_save (bool) – Whether the profile should automatically save itself to disk at any point. The default is False, but all profiles generated through XGA processes acting on XGA sources will auto-save.

• spec_model (str) – The spectral model that was fit to annular spectra to measure the results that were used to create this profile. Only relevant to profiles that are generated from annular spectra, default is None.

• fit_conf (str) – The key that describes the fit-configuration used when fitting models to annular spectra to measure the results that were then used to create this profile. Only relevant to profiles that are generated from annular spectra, default is None.

mass(radius, conf_level=68.2, radius_err=None)

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

• radius_err (Quantity) – A standard deviation on radius, which will be taken into account during the calculation of hydrostatic mass.

Returns:

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

Return type:

Union[Quantity, Quantity]

annular_mass(outer_radius, inner_radius, conf_level=68.2)

Calculate the hydrostatic mass contained within a specific 3D annulus, bounded by the outer and inner radius supplied to this method. Annular mass is calculated by measuring the mass within the inner and outer radii, and then subtracting the inner from the outer. Also supports calculating multiple annular masses when inner_radius and outer_radius are non-scalar.

WARNING - THIS METHOD INVOLVES SUBTRACTING TWO MASS DISTRIBUTIONS, WHICH CAN’T NECESSARILY BE APPROXIMATED AS GAUSSIAN DISTRIBUTIONS, AS SUCH RESULTS FROM THIS METHOD SHOULD BE TREATED WITH SOME SUSPICION.

Parameters:

• outer_radius (Quantity) – Astropy containing outer radius (or radii) for the annulus (annuli) within which you wish to measure the mass. If calculating multiple annular masses, the length of outer_radius must be the same as inner_radius.

• inner_radius (Quantity) – Astropy containing inner radius (or radii) for the annulus (annuli) within which you wish to measure the mass. If calculating multiple annular masses, the length of inner_radius must be the same as outer_radius.

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

Returns:

An astropy quantity containing a mass distribution(s). Quantity will become two-dimensional when multiple sets of inner and outer radii are passed by the user.

Return type:

Quantity

view_mass_dist(radius, conf_level=68.2, figsize=(8, 8), bins='auto', colour='lightseagreen')

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[float, float]) – The desired size of the histogram figure.

baryon_fraction(radius, conf_level=68.2)

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='lightseagreen')

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[float, float]) – The desired size of the histogram figure.

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

baryon_fraction_profile(radii=None, deg_radii=None)

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

Parameters:

• radii (Quantity) – Custom radii to generate the points of the profile at, default is None in which case the radii of this hydrostatic mass profile are used.

• deg_radii (Quantity) – The equivalent values to ‘radii’, but in degrees.

Returns:

An XGA BaryonFraction object.

Return type:

BaryonFraction

overdensity_radius(delta, redshift, cosmo, init_lo_rad=<Quantity 100. kpc>, init_hi_rad=<Quantity 3500. kpc>, init_step=<Quantity 100. kpc>, out_unit=Unit("kpc"))

This method uses the mass profile to find the radius that corresponds to the user-supplied overdensity - common choices for cluster analysis are Δ=2500, 500, and 200. Overdensity radii are defined as the radius at which the density is Δ times the critical density of the Universe at the cluster redshift.

This method takes a numerical approach to the location of the requested radius. Though we have calculated analytical hydrostatic mass models for common choices of temperature and density profile models, there are no analytical solutions for R.

When an overdensity radius is being calculated, we initially measure masses for a range of radii between init_lo_rad - init_hi_rad in steps of init_step. From this we find the two radii that bracket the radius where average density - Delta*critical density = 0. Between those two radii we perform the same test with another range of radii (in steps of 1 kpc this time), finding the radius that corresponds to the minimum density difference value.

Parameters:

• delta (int) – The overdensity factor for which a radius is to be calculated.

• redshift (float) – The redshift of the cluster.

• cosmo – The cosmology in which to calculate the overdensity. Should be an astropy cosmology instance.

• init_lo_rad (Quantity) – The lower radius bound for the first radii array generated to find the wide brackets around the requested overdensity radius. Default value is 100 kpc.

• init_hi_rad (Quantity) – The upper radius bound for the first radii array generated to find the wide brackets around the requested overdensity radius. Default value is 3500 kpc.

• init_step (Quantity) – The step size for the first radii array generated to find the wide brackets around the requested overdensity radius. Default value is 100 kpc, recommend that you don’t set it smaller than 10 kpc.

• out_unit (Unit/str) – The unit that this method should output the radius with.

Returns:

The calculated overdensity radius.

Return type:

Quantity

diagnostic_view(src=None, figsize=None)

This method produces a figure with the most important products that went into the creation of this HydrostaticMass profile, for the purposes of quickly checking that everything looks sensible. The maximum number of plots included is five; mass profile, temperature profile, density profile, surface brightness profile, and ratemap. The RateMap will only be included if the source that this profile was generated from is passed.

Parameters:

• src (GalaxyCluster) – The GalaxyCluster source that this HydrostaticMass profile was generated from.

• figsize (Tuple[float, float]) – A tuple that sets the size of the diagnostic plot, default is None in which case it is set automatically.

save_diagnostic_view(save_path, src=None, figsize=None)

This method saves a figure (without displaying) with the most important products that went into the creation of this HydrostaticMass profile, for the purposes of quickly checking that everything looks sensible. The maximum number of plots included is five; mass profile, temperature profile, density profile, surface brightness profile, and ratemap. The RateMap will only be included if the source that this profile was generated from is passed.

Parameters:

• save_path (str) – The path and filename where the diagnostic figure should be saved.

• src (GalaxyCluster) – The GalaxyCluster source that this HydrostaticMass profile was generated from.

• figsize (Tuple[float, float]) – A tuple that sets the size of the diagnostic plot, default is None in which case it is set automatically.

property temperature_profile

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

Returns:

The input temperature profile.

Return type:

GasTemperature3D/ProjectedGasTemperature1D

property density_profile

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

Returns:

The input density profile.

Return type:

GasDensity3D

property temperature_model

A method to provide access to the model that may have been 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 may have been fit to the density profile.

Returns:

The fit density profile.

Return type:

BaseModel1D

rad_check(rad)

Very simple method that prints a warning if the radius is outside the range of data covered by the density or temperature profiles - will actually throw an error if the hydrostatic mass profile was set up in a data-driven mode, because we aren’t going to let anyone extrapolate the data points.

Parameters:

rad (Quantity) – The radius to check.

class xga.products.profile.SpecificEntropy(temperature_profile, density_profile, temperature_model=None, density_model=None, radii=None, radii_err=None, deg_radii=None, fit_method='mcmc', num_walkers=20, num_steps=20000, num_samples=1000, show_warn=True, progress=True, interp_data=False, allow_unphysical=False, auto_save=False, spec_model=None, fit_conf=None)

Bases: BaseProfile1D

A profile product which uses input temperature and density profiles to calculate a specific entropy profile of the kind often used in galaxy cluster analyses (https://ui.adsabs.harvard.edu/abs/2009ApJS..182…12C/abstract for instance). Somewhat similar in function to the HydrostaticMass profile class, in that entropy values are calculated during the declaration of this class, rather than being passed in.

The entropy profile can be used with several different kinds of input profiles, reflecting some of the different ways that they are calculated in the literature, and the practical limitations of generating ‘de-projected’ profiles. In short, this profile can be used in the following different ways:

• Either projected, or de-projected (inferred 3D profiles) can be passed to this profile; the temperature and density profiles also do not need to both be projected or both be de-projected. Clearly, from a purely physical point of view, it would be better to pass 3D profiles, but practically de-projection processes often cause a lot of problems, so the choice is left to the user.

• The entropy values can be calculated either from models fit to the input profiles, or from the data points of the input profiles. This means that the user can choose between a ‘cleaner’ profile from generated from smooth models, or a data-driven profile that might better represent the intricacies of the particular galaxy cluster.

• If data points are being used rather than models, and the radial binning is different between the temperature and density profiles, then the data points on the profile with wider bins can either be interpolated, or matched to the data points of the other profile that they cover.

Parameters:

• temperature_profile (GasTemperature3D / ProjectedGasTemperature1D) – The XGA 3D or projected temperature profile to take temperature information from.

• temperature_model (str/BaseModel1D) – The model to fit to the temperature profile (if smooth models are to be used to calculate the entropy profile), either a name or an instance of an XGA temperature model class. Default is None, in which case this class will use profile data points to calculate entropy.

• density_profile (GasDensity3D) – The XGA 3D density profile to take density information from.

• density_model (str/BaseModel1D) – The model to fit to the density profile (if smooth models are to be used to calculate the entropy profile), either a name or an instance of an XGA density model class. Default is None, in which case this class will use profile data points to calculate entropy.

• radii (Quantity) – The radii at which to measure the entropy - this is only necessary if model fits are being used to calculate entropy, otherwise profile radii will be used.

• radii_err (Quantity) – The uncertainties on the radii - this is only necessary if model fits are being used to calculate entropy, otherwise profile radii errors will be used.

• deg_radii (Quantity) – The radii values, but in units of degrees - this is only necessary if model fits are being used to calculate entropy, otherwise profile radii will be used.

• fit_method (str) – The name of the fit method to use for the fitting of the profiles, default is ‘mcmc’.

• num_walkers (int) – If the fit method is ‘mcmc’ then this will set the number of walkers for the emcee sampler to set up.

• num_steps (list/int) – If the fit method is ‘mcmc’ this will set the number of steps for each sampler to take. If a single number is passed then that number of steps is used for both profiles, otherwise if a list is passed the first entry is used for the temperature fit, and the second for the density fit.

• num_samples (int) – The number of random samples to be drawn from the posteriors of the fit results.

• show_warn (bool) – Controls whether warnings produced the fitting processes are displayed.

• progress (bool) – Controls whether fit progress bars are displayed.

• interp_data (bool) – If the entropy profile is to be derived from data points rather than fitted models, this controls whether the data profile with the coarser bins is interpolated, or whether the other profile’s data points are matched with the value that was measured for the radial region they are in (the default).

• allow_unphysical (bool) – This controls whether unphysical entropy results are ‘allowed’ without an exception being raised (e.g. if a calculated entropy value is negative). Default is False.

• auto_save (bool) – Whether the profile should automatically save itself to disk at any point. The default is False, but all profiles generated through XGA processes acting on XGA sources will auto-save.

• spec_model (str) – The spectral model that was fit to annular spectra to measure the results that were used to create this profile. Only relevant to profiles that are generated from annular spectra, default is None.

• fit_conf (str) – The key that describes the fit-configuration used when fitting models to annular spectra to measure the results that were then used to create this profile. Only relevant to profiles that are generated from annular spectra, default is None.

entropy(radius, conf_level=68.2)

A method which will measure a specific entropy and specific entropy uncertainty within the given radius/radii.

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 entropy uncertainties, the default is 68.2% (~1σ).

Returns:

An astropy quantity containing the entropy/entropies, lower and upper uncertainties, and another containing the entropy realization distribution.

Return type:

Union[Quantity, Quantity]

view_entropy_dist(radius, conf_level=68.2, figsize=(8, 8), bins='auto', colour='lightseagreen')

A method which will generate a histogram of the entropy distribution that resulted from the entropy calculation at the supplied radius. If the entropy for the passed radius has already been measured it, and the entropy 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 entropy at.

• conf_level (float) – The confidence level for the entropy 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.

property temperature_profile

A method to provide access to the 3D or projected temperature profile used to generate this entropy 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 entropy profile.

Returns:

The input density profile.

Return type:

GasDensity3D

property temperature_model

A method to provide access to the model that may have been 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 may have been fit to the density profile.

Returns:

The fit density profile.

Return type:

BaseModel1D

rad_check(rad)

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.ThermalPressure(temperature_profile, density_profile, temperature_model=None, density_model=None, radii=None, radii_err=None, deg_radii=None, fit_method='mcmc', num_walkers=20, num_steps=20000, num_samples=1000, show_warn=True, progress=True, interp_data=False, allow_unphysical=False, auto_save=False)

Bases: BaseProfile1D

A profile product which uses input temperature and density profiles to calculate a thermal pressure profile of the kind often used in galaxy cluster analyses. Very similar in function to the SpecificEntropy profile class, in that pressure values are calculated during the declaration of this class, rather than being passed in.

The thermal pressure profile can be used with several different kinds of input profiles, reflecting some of the different ways that they are calculated in the literature, and the practical limitations of generating ‘de-projected’ profiles. In short, this profile can be used in the following different ways:

• Either projected, or de-projected (inferred 3D profiles) can be passed to this profile; the temperature and density profiles also do not need to both be projected or both be de-projected. Clearly, from a purely physical point of view, it would be better to pass 3D profiles, but practically de-projection processes often cause a lot of problems, so the choice is left to the user.

• The thermal pressure values can be calculated either from models fit to the input profiles, or from the data points of the input profiles. This means that the user can choose between a ‘cleaner’ profile from generated from smooth models, or a data-driven profile that might better represent the intricacies of the particular galaxy cluster.

• If data points are being used rather than models, and the radial binning is different between the temperature and density profiles, then the data points on the profile with wider bins can either be interpolated, or matched to the data points of the other profile that they cover.

Parameters:

• temperature_profile (GasTemperature3D / ProjectedGasTemperature1D) – The XGA 3D or projected temperature profile to take temperature information from.

• temperature_model (str/BaseModel1D) – The model to fit to the temperature profile (if smooth models are to be used to calculate the thermal pressure profile), either a name or an instance of an XGA temperature model class. Default is None, in which case this class will use profile data points to calculate thermal pressure.

• density_profile (GasDensity3D) – The XGA 3D density profile to take density information from.

• density_model (str/BaseModel1D) – The model to fit to the density profile (if smooth models are to be used to calculate the thermal pressure profile), either a name or an instance of an XGA density model class. Default is None, in which case this class will use profile data points to calculate thermal pressure.

• radii (Quantity) – The radii at which to measure the thermal pressure - this is only necessary if model fits are being used to calculate thermal pressure, otherwise profile radii will be used.

• radii_err (Quantity) – The uncertainties on the radii - this is only necessary if model fits are being used to calculate thermal pressure, otherwise profile radii errors will be used.

• deg_radii (Quantity) – The radii values, but in units of degrees - this is only necessary if model fits are being used to calculate thermal pressure, otherwise profile radii will be used.

• fit_method (str) – The name of the fit method to use for the fitting of the profiles, default is ‘mcmc’.

• num_walkers (int) – If the fit method is ‘mcmc’ then this will set the number of walkers for the emcee sampler to set up.

• num_steps (list/int) – If the fit method is ‘mcmc’ this will set the number of steps for each sampler to take. If a single number is passed then that number of steps is used for both profiles, otherwise if a list is passed the first entry is used for the temperature fit, and the second for the density fit.

• num_samples (int) – The number of random samples to be drawn from the posteriors of the fit results.

• show_warn (bool) – Controls whether warnings produced the fitting processes are displayed.

• progress (bool) – Controls whether fit progress bars are displayed.

• interp_data (bool) – If the thermal pressure profile is to be derived from data points rather than fitted models, this controls whether the data profile with the coarser bins is interpolated, or whether the other profile’s data points are matched with the value that was measured for the radial region they are in (the default).

• allow_unphysical (bool) – This controls whether unphysical thermal pressure results are ‘allowed’ without an exception being raised (e.g. if a calculated thermal pressure value is negative). Default is False.

• auto_save (bool) – Whether the profile should automatically save itself to disk at any point. The default is False, but all profiles generated through XGA processes acting on XGA sources will auto-save.

pressure(radius, conf_level=68.2)

A method which will measure a thermal pressure and thermal pressure uncertainty within the given radius/radii.

Parameters:

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

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

Returns:

An astropy quantity containing the thermal pressure(s), lower and upper uncertainties, and another containing the thermal pressure realization distribution.

Return type:

Union[Quantity, Quantity]

view_pressure_dist(radius, conf_level=68.2, figsize=(8, 8), bins='auto', colour='lightseagreen')

A method which will generate a histogram of the thermal pressure distribution that resulted from the pressure calculation at the supplied radius. If the entropy for the passed radius has already been measured it, and the pressure 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 pressure at.

• conf_level (float) – The confidence level for the pressure 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.

property temperature_profile

A method to provide access to the 3D or projected temperature profile used to generate this pressure 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 pressure profile.

Returns:

The input density profile.

Return type:

GasDensity3D

property temperature_model

A method to provide access to the model that may have been 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 may have been fit to the density profile.

Returns:

The fit density profile.

Return type:

BaseModel1D

rad_check(rad)

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, auto_save=False, spec_model=None, fit_conf=None)

Bases: 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.

Parameters:

• centre (Quantity) – The central coordinate the profile was generated from.

• source_name (str) – The name of the source this profile is associated with.

• obs_id (str) – The observation which this profile was generated from.

• inst (str) – The instrument which this profile was generated from.

• y_axis_label (str) – The label to apply to the y-axis of any plots generated from this profile.

• prof_type (str) – This is a string description of the profile, used to store it in an XGA source (with _profile appended). For instance the prof_type of a ProjectedGasTemperature1D instance is 1d_proj_temperature, and it would be stored under 1d_proj_temperature_profile.

• radii_err (Quantity) – Uncertainties on the radii.

• values_err (Quantity) – Uncertainties on the values.

• associated_set_id (int) – The set ID of the AnnularSpectra that generated this - if applicable.

• set_storage_key (str) – Must be present if associated_set_id is, this is the storage key which the associated AnnularSpectra generates to place itself in XGA’s store structure.

• deg_radii (Quantity) – A slightly unfortunate variable that is required only if radii is not in units of degrees, or if no set_storage_key is passed. It should be a quantity containing the radii values converted to degrees, and allows this object to construct a predictable storage key.

• auto_save (bool) – Whether the profile should automatically save itself to disk at any point. The default is False, but all profiles generated through XGA processes acting on XGA sources will auto-save.

• spec_model (str) – The spectral model that was fit to annular spectra to measure the results that were used to create this profile. Only relevant to profiles that are generated from annular spectra, default is None.

• fit_conf (str) – The key that describes the fit-configuration used when fitting models to annular spectra to measure the results that were then used to create this profile. Only relevant to profiles that are generated from annular spectra, default is None.

products.relation module

class xga.products.relation.ScalingRelation(fit_pars, fit_par_errs, model_func, x_norm, y_norm, x_name, y_name, dim_hubb_ind=None, 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='2025', relation_doi='', scatter_par=None, scatter_chain=None, model_colour=None, point_names=None, third_dim_info=None, third_dim_name=None, x_en_bounds=None, y_en_bounds=None)

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.

Parameters:

• fit_pars (np.ndarray) – The results of the fit to a model that describes this scaling relation.

• fit_par_errs (np.ndarray) – The uncertainties on the fit results for this scalin relation.

• model_func – A Python function of the model which this scaling relation is described by. PLEASE NOTE, the function must be defined in the style used in xga.models.misc; i.e. powerlaw(x: np.ndarray, k: float, a: float), where the first argument is for x values, and the following arguments are all fit parameters.

• x_norm (Quantity) – Quantity to normalise the x data by.

• y_norm (Quantity) – Quantity to normalise the y data by.

• x_name (str) – The name to be used for the x-axis of the plot (DON’T include the unit, that will be inferred from an astropy Quantity.

• y_name (str) – The name to be used for the y-axis of the plot (DON’T include the unit, that will be inferred from an astropy Quantity.

• dim_hubb_ind (float/int) – This is used to tell the ScalingRelation which power of E(z) has been applied to the y-axis data, this can then be used by the predict method to remove the E(z) contribution from predictions. The default is None.

• fit_method (str) – The method used to fit this data, if known.

• x_data (Quantity) – The x-data used to fit this scaling relation, if available. This should be the raw, un-normalised data.

• y_data (Quantity) – The y-data used to fit this scaling relation, if available. This should be the raw, un-normalised data.

• x_err (Quantity) – The x-errors used to fit this scaling relation, if available. This should be the raw, un-normalised data.

• y_err (Quantity) – The y-errors used to fit this scaling relation, if available. This should be the raw, un-normalised data.

• x_lims (Quantity) – The range of x values in which this relation is valid, default is None. If this information is supplied, please pass it as a Quantity array, with the first element being the lower bound and the second element being the upper bound.

• odr_output (odr.Output) – The orthogonal distance regression output object associated with this relation’s fit, if available and applicable.

• chains (np.ndarray) – The parameter chains associated with this relation’s fit, if available and applicable. They should be of shape N_stepxN_par, where N_steps is the number of steps (after burn-in is removed), and N_par is the number of parameters in the fit.

• relation_name (str) – A suitable name for this relation.

• relation_author (str) – The author who deserves credit for this relation.

• relation_year (str) – The year this relation was produced, default is the current year.

• relation_doi (str) – The DOI of the original paper this relation appeared in.

• scatter_par (np.ndarray) – A parameter describing the intrinsic scatter of y|x. Optional as many fits don’t include this.

• scatter_chain (np.ndarray) – A corresponding MCMC chain for the scatter parameter. Optional.

• model_colour (str) – This variable can be used to set the colour that the fit should be displayed in when plotting. Setting it at definition or setting the property means that the colour doesn’t have to be set for every view method, and it will be remembered when multiple relations are viewed together.

• point_names (np.ndarray/list) – The source names associated with the data points passed in to this scaling relation, can be used for diagnostic purposes (i.e. identifying which source an outlier belongs to).

• third_dim_info (np.ndarray/Quantity) – A set of data points which represent a faux third dimension. They should not have been involved in the fitting process, and the relation should not be in three dimensions, but these can be used to colour the data points in a view method.

• third_dim_name (str) – The name of the third dimension data.

• x_en_bounds (Tuple[Quantity]) – If the value on the x-axis of this relation is ‘energy bound’, those bounds can be specified here (e.g. if the value is 0.5-2.0 keV luminosity you would pass a non-scalar quantity with the first entry being 0.5 and the second 2.0; Quantity([0.5, 2.0], ‘keV’). The default is None.

• y_en_bounds (Tuple[Quantity]) – If the value on the y-axis of this relation is ‘energy bound’, those bounds can be specified here (e.g. if the value is 0.5-2.0 keV luminosity you would pass a non-scalar quantity with the first entry being 0.5 and the second 2.0; Quantity([0.5, 2.0], ‘keV’). The default is None.

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 dimensionless_hubble_parameter

This property should be set on the declaration of a scaling relation, and exists to tell the relation what power of E(z) has been applied to the y-axis data before fitting. This also helps the predict method remove the E(z) contribution (if any) from predictions.

Returns:

The power of E(z) applied to the y-axis data before fitting. Default is None.

Return type:

float/int

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

property model_colour

Property getter for the model colour assigned to this relation. If it wasn’t set at definition or set via the property setter then it defaults to ‘tab:gray’.

Returns:

The currently set model colour. If one wasn’t set on definition then we default to tab:gray.

Return type:

str

property point_names

Returns an array of point names, with one entry per data point, and in the same order (unless the user passes a differently ordered name array than data array, there is no way we can detect that).

Returns:

The names associated with the data points, if supplied on initialization. The default is None.

Return type:

np.ndarray/None

property third_dimension_data

Returns a Quantity containing a third dimension of data associated with the data points (this can be used to colour the points in the view method), with one entry per data point, and in the same order (unless the user passes a differently ordered name array than data array, there is no way we can detect that).

Returns:

The third dimension data associated with the data points, if supplied on initialization. The default is None.

Return type:

Quantity/None

property third_dimension_name

Returns the name of the third data dimension passed to this relation on initialization.

Returns:

The name of the third dimension, if supplied on initialization. The default is None.

Return type:

Quantity/None

property x_energy_bounds

The energy bounds within which the x-axis data have been measured (e.g. a 0.5-2.0 keV luminosity).

Returns:

A non-scalar Astropy Quantity with two entries if the x-data energy bounds have been set, and None if they have not.

Return type:

Quantity

property y_energy_bounds

The energy bounds within which the y-axis data have been measured (e.g. a 0.5-2.0 keV luminosity).

Returns:

A non-scalar Astropy Quantity with two entries if the y-data energy bounds have been set, and None if they have not.

Return type:

Quantity

view_chains(figsize=None, colour=None)

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.

• colour (str) – The colour that the chains should be in the plot. Default is None in which case the value of the model_colour property of the relation is used.

view_corner(figsize=(10, 10), cust_par_names=None, colour=None, save_path=None)

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. Default is None in which case the value of the model_colour property of the relation is used.

• 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, redshift=None, cosmo=None, x_errors=None)

This method allows for the prediction of y values from this scaling relation, you just need to pass in an appropriate set of x value(s). If a power of E(z) was applied to the y-axis data before fitting, and that information was passed on declaration (using ‘dim_hubb_ind’), then a redshift and cosmology are required to remove out the E(z) contribution.

Parameters:

• x_values (Quantity) – The x value(s) to predict y value(s) for.

• redshift (float/np.ndarray) – The redshift(s) of the objects for which we wish to predict values. This is only necessary if the ‘dim_hubb_ind’ argument was set on declaration. Default is None.

• cosmo (Cosmology) – The cosmology in which we wish to predict values. This is only necessary if the ‘dim_hubb_ind’ argument was set on declaration. Default is None.

• x_errors (Quantity) – The uncertainties for passed x-values. Default is None. If this argument is not None then uncertainties in x-value and the model fit will be propagated to a final prediction uncertainty. If minus and plus uncertainties are passed then they will be averaged before propagation.

Returns:

The predicted y values (and predicted uncertainties if x-errors were passed).

Return type:

Quantity

get_view(ax, x_lims=None, log_scale=True, plot_title=None, data_colour='black', model_colour=None, grid_on=False, conf_level=90, custom_x_label=None, custom_y_label=None, fontsize=15, x_ticks=None, x_minor_ticks=None, y_ticks=None, y_minor_ticks=None, label_points=False, point_label_colour='black', point_label_size=10, point_label_offset=(0.01, 0.01), show_third_dim=None, third_dim_cmap='plasma', third_dim_norm_cmap=<class 'matplotlib.colors.Normalize'>, third_dim_axis_formatters=None, y_lims=None, one_to_one=False)

A get method that will populate a matplotlib axes with a high quality plot of this scaling relation (including the data it is based upon, if available), and then return it.

Parameters:

• ax (Axes) – The axes on which to draw the plot.

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

• 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 None in which case the value of the model_colour property of the relation is used.

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

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

• label_points (bool) – If True, and source name information for each point was passed on the declaration of this scaling relation, then points will be accompanied by an index that can be used with the ‘point_names’ property to retrieve the source name for a point. Default is False.

• point_label_colour (str) – The colour of the label text.

• point_label_size (int) – The fontsize of the label text.

• show_third_dim (bool) – Colour the data points by the third dimension data passed in on creation of this scaling relation, with a colour bar to communicate values. Only possible if data were passed to ‘third_dim_info’ on initialization. Default is None, which automatically gets converted to True if there is a third data dimension, and converted to False if there is not.

• third_dim_cmap (str/Colormap) – The colour map which should be used for the third dimension data points. A matplotlib colour map name or a colour map object may be passed. Default is ‘plasma’. This essentially overwrites the ‘data_colour’ argument if show_third_dim is True.

• third_dim_norm_cmap (Normalize) – A matplotlib ‘Normalize’ class/subclass (e.g. LogNorm, SymLogNorm, etc.) that will be used to scale the colouring of the data points by the third data dimension. Note that a class, NOT A CLASS INSTANCE (e.g. LogNorm()) must be passed, as the normalisation will be set up in this method. Default is Normalization (linear scaling).

• third_dim_axis_formatters (dict) – A dictionary of formatters that can be applied to the colorbar axis. Allowed keys are; ‘major’ and ‘minor’. The values associated with the keys should be instantiated matplotlib formatters.

• point_label_offset (Tuple[float, float]) – A fractional offset (in display coordinates) applied to the data point coordinates to determine the location a label should be added. You can use this to fine-tune the label positions relative to their data point.

• y_lims (Quantity) – If not set, this method will attempt to take appropriate limits from the y-data and/or relation line - setting any value other than None will override that.

• one_to_one (bool) – If True, a one-to-one line will be plotted on the scaling relation view. Default is False.

view(x_lims=None, log_scale=True, plot_title=None, figsize=(10, 8), data_colour='black', model_colour=None, 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, label_points=False, point_label_colour='black', point_label_size=10, point_label_offset=(0.01, 0.01), show_third_dim=None, third_dim_cmap='plasma', third_dim_norm_cmap=<class 'matplotlib.colors.Normalize'>, third_dim_axis_formatters=None, y_lims=None, one_to_one=False)

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 None in which case the value of the model_colour property of the relation is used.

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

• label_points (bool) – If True, and source name information for each point was passed on the declaration of this scaling relation, then points will be accompanied by an index that can be used with the ‘point_names’ property to retrieve the source name for a point. Default is False.

• point_label_colour (str) – The colour of the label text.

• point_label_size (int) – The fontsize of the label text.

• show_third_dim (bool) – Colour the data points by the third dimension data passed in on creation of this scaling relation, with a colour bar to communicate values. Only possible if data were passed to ‘third_dim_info’ on initialization. Default is None, which automatically gets converted to True if there is a third data dimension, and converted to False if there is not.

• third_dim_cmap (str/Colormap) – The colour map which should be used for the third dimension data points. A matplotlib colour map name or a colour map object may be passed. Default is ‘plasma’. This essentially overwrites the ‘data_colour’ argument if show_third_dim is True.

• third_dim_norm_cmap (Normalize) – A matplotlib ‘Normalize’ class/subclass (e.g. LogNorm, SymLogNorm, etc.) that will be used to scale the colouring of the data points by the third data dimension. Note that a class, NOT A CLASS INSTANCE (e.g. LogNorm()) must be passed, as the normalisation will be set up in this method. Default is Normalization (linear scaling).

• third_dim_axis_formatters (dict) – A dictionary of formatters that can be applied to the colorbar axis. Allowed keys are; ‘xmajor’, ‘xminor’, ‘ymajor’, and ‘yminor’. The values associated with the keys should be instantiated matplotlib formatters.

• point_label_offset (Tuple[float, float]) – A fractional offset (in display coordinates) applied to the data point coordinates to determine the location a label should be added. You can use this to fine-tune the label positions relative to their data point.

• y_lims (Quantity) – If not set, this method will attempt to take appropriate limits from the y-data and/or relation line - setting any value other than None will override that.

• one_to_one (bool) – If True, a one-to-one line will be plotted on the scaling relation view. Default is False.

save(save_path)

This method pickles and saves the scaling relation object. The save file is a pickled version of this object.

Parameters:

save_path (str) – The path where this relation should be saved.

class xga.products.relation.AggregateScalingRelation(relations)

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.

Parameters:

relations (List[ScalingRelation]) – A list of scaling relations objects to be combined in this object.

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)

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.

get_view(ax, x_lims=None, log_scale=True, plot_title=None, colour_list=None, grid_on=False, conf_level=90, show_data=True, fontsize=15, x_ticks=None, x_minor_ticks=None, y_ticks=None, y_minor_ticks=None, data_colour_list=None, data_shape_list=None, custom_x_label=None, custom_y_label=None, y_lims=None, one_to_one=False)

A method that populates a passed matplotlib axis with a high quality plot of the component scaling relations in this AggregateScalingRelation, and then returns it.

Parameters:

• ax (Axes) – The matplotlib Axes object to draw on.

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

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

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

• data_colour_list (list) – A list of matplotlib colours to use as a colour cycle specifically for data points. This should be used when you want data points to be a different colour to their model.

• data_shape_list (list) – A list of matplotlib format shapes, to manually set the shapes of plotted data points.

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

• y_lims (Quantity) – If not set, this method will attempt to take appropriate limits from the y-data and/or relation line - setting any value other than None will override that.

• one_to_one (bool) – If True, a one-to-one line will be plotted on the scaling relation view. Default is False.

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, data_colour_list=None, data_shape_list=None, custom_x_label=None, custom_y_label=None, y_lims=None, one_to_one=False)

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.

• data_colour_list (list) – A list of matplotlib colours to use as a colour cycle specifically for data points. This should be used when you want data points to be a different colour to their model.

• data_shape_list (list) – A list of matplotlib format shapes, to manually set the shapes of plotted data points.

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

• y_lims (Quantity) – If not set, this method will attempt to take appropriate limits from the y-data and/or relation line - setting any value other than None will override that.

• one_to_one (bool) – If True, a one-to-one line will be plotted on the scaling relation view. Default is False.

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='')

Bases: 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.

Parameters:

• path (str) – The path to the spectrum file.

• rmf_path (str) – The path to the RMF generated for the spectrum file.

• arf_path (str) – The path to the ARF generated for the spectrum file.

• b_path (str) – The path to the background spectrum generated for the spectrum file.

• central_coord (Quantity) – The central coordinate of the spectrum region.

• inn_rad (Quantity) – The inner radius of the spectrum region.

• out_rad (Quantity) – The outer radius of the spectrum region.

• obs_id (str) – The ObsID from which this spectrum was generated.

• instrument (str) – The instrument which this spectrum was generated.

• grouped (bool) – Was this spectrum grouped?

• min_counts (int) – The minimum counts applied for the grouping.

• min_sn (float) – The minimum signal to noise applied for the grouping.

• over_sample (int) – Level of oversampling applied to spectrum grouping.

• stdout_str (str) – The stdout from the generation process.

• stderr_str (str) – The stderr for the generation process.

• gen_cmd (str) – The generation command for the spectrum stack.

• region (bool) – Was this spectrum generated from a region in a region file?

• b_rmf_path (str) – The path to the RMF generated for the background spectrum (if applicable, XGA no longer generates these by default, as XSPEC does not make use of them).

• b_arf_path (str) – The path to the ARF generated for the background spectrum (if applicable, XGA no longer generates these by default, as XSPEC does not make use of them).

property header

The SPECTRUM table header of the source spectrum. This property was called header because I suspect this will be more the more useful of the two headers that a Spectrum instance allows you to access.

Return type:

FITSHDR

Returns:

The SPECTRUM fits table header.

property primary_header

The PRIMARY (overall) header of the source spectrum file.

Return type:

FITSHDR

Returns:

The PRIMARY (overall) fits file header.

property counts

The array of counts associated with each channel of the spectrum, with a second column containing the Poisson error.

Return type:

Quantity

Returns:

The counts quantity in units of ‘ct’.

property exposure

The weighted (from individual exposure times of different CCD chips) exposure time of the source spectrum, as used by XSPEC.

Return type:

Quantity

Returns:

The exposure time for the source spectrum, in units of seconds.

property count_rates

The array of counts/second associated with each channel of the spectrum. This takes the counts property and divides it by the EXPOSURE entry in the spectrum header. A second column containing uncertainty is included.

Return type:

Quantity

Returns:

The counts/second quantity in units of ‘ct/s’.

property channels

The array of instrument channels in the spectrum.

Return type:

Quantity

Returns:

An array of channels.

property energies

The array of instrument channels, converted to energy using information from the RMF.

Return type:

Quantity

Returns:

An array of channel energy midpoints, in keV.

property grouping

The grouping information from the spectrum. A 1 entry indicates the first channel in a group and -1 indicates a member of the current group.

Return type:

np.ndarray

Returns:

An array of group IDs.

property quality

The quality information from the spectrum. 0 = good quality, 1 is bad quality and 2 means dubious.

Return type:

np.ndarray

Returns:

An array of quality flags.

property back_header

The SPECTRUM table header of the background spectrum. This property was called header because I suspect this will be more the more useful of the two headers that a Spectrum instance allows you to access.

Return type:

FITSHDR

Returns:

The SPECTRUM fits table header.

property back_primary_header

The PRIMARY (overall) header of the background spectrum file.

Return type:

FITSHDR

Returns:

The PRIMARY (overall) fits file header.

property back_counts

The array of counts associated with each channel of the background spectrum, with a second column containing the Poisson error.

Return type:

Quantity

Returns:

The counts quantity in units of ‘ct’.

property back_exposure

The weighted (from individual exposure times of different CCD chips) exposure time of the background spectrum, as used by XSPEC.

Return type:

Quantity

Returns:

The exposure time for the background spectrum, in units of seconds.

property back_count_rates

The array of counts/second associated with each channel of the background spectrum. This takes the back_counts property and divides it by the EXPOSURE entry in the background spectrum header. A second column containing uncertainty is included.

Return type:

Quantity

Returns:

The counts/second quantity in units of ‘ct/s’.

property back_channels

The array of instrument channels in the background spectrum.

Return type:

Quantity

Returns:

An array of channels.

property back_grouping

The grouping information from the background spectrum

Return type:

np.ndarray

Returns:

An array of group IDs.

property back_quality

The quality information from the background spectrum. A 0 flag value means good quality, 1 means not good quality.

Return type:

np.ndarray

Returns:

An array of quality flags.

property eff_area

The discrete effective area curve of the telescope. These area values correspond to upper and lower energy bounds that can be accessed using the eff_area_lo_en and eff_area_hi_en properties

Return type:

Quantity

Returns:

A quantity containing the effective area values in units of cm^-2.

property eff_area_lo_en

The lower energy bounds for the effective area curve.

Return type:

Quantity

Returns:

A quantity containing the lower energy bounds for effective area values in units keV.

property eff_area_hi_en

The upper energy bounds for the effective area curve.

Return type:

Quantity

Returns:

A quantity containing the upper energy bounds for effective area values in units keV.

property rmf_channels

The channels present in the RMF EBOUND table, used for converting between channel and energy when used in conjunction with rmf_channels_lo_en and rmf_channels_hi_en.

Return type:

np.ndarray

Returns:

A numpy array containing the channels in the EBOUND table.

property rmf_channels_lo_en

The lower energy bounds for the RMF EBOUND channels.

Return type:

Quantity

Returns:

A quantity containing the lower energy bounds for RMF channels, in units keV.

property rmf_channels_hi_en

The upper energy bounds for the RMF EBOUND channels.

Return type:

Quantity

Returns:

A quantity containing the upper energy bounds for RMF channels, in units keV.

property rmf_redist_matrix

The contents of the RMF MATRIX table.

Return type:

np.ndarray

Returns:

A numpy array with names columns.

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 fitted_models

A property that gets the list of spectral models that have been fit to this spectrum instance.

Returns:

A list of models fit to this spectrum.

Return type:

list

property fitted_model_configurations

Property that returns a dictionary with model names as keys and lists of fit configuration identifiers as values, for the models that have been fit to this spectrum.

Returns:

Dictionary with model names as keys, and lists of model configuration identifiers as values.

Return type:

dict

property fitted_model_configuration_diffs

Property that returns the difference of each fitted model configuration from the default for that particular model - making it easier to identify only those parameters that were altered.

Returns:

Dictionary with model names as keys, fit configuration identifiers as lower level keys, and dictionaries of parameters-changed-from-default as values.

Return type:

dict

add_fit_data(model, tab_line, plot_data, fit_conf)

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.

• fit_conf (str) – In order to be able to store results for different fit configurations (e.g. different starting pars, abundance tables, all that), we need to have a key that identifies the configuration. We do not expect the user to be adding fit data, so this will be a key generated by the fit function

get_luminosities(model=None, lo_en=None, hi_en=None, fit_conf=None)

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

If no model name is supplied, but only one model has been fit to this spectrum, then that model will be automatically selected - this behavior also applies to the fit configuration (fit_conf) parameter; if a model was only fit with one fit configuration then that will be automatically selected.

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.

• fit_conf (str/dict) – Either a dictionary with keys being the names of parameters passed to the fit method and values being the changed values (only values changed-from-default need be included) or a full string representation of the fit configuration that is being requested.

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=None, fit_conf=None)

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

If no model name is supplied, but only one model has been fit to this spectrum, then that model will be automatically selected - this behavior also applies to the fit configuration (fit_conf) parameter; if a model was only fit with one fit configuration then that will be automatically selected.

Parameters:

• model – The model to fetch count rate for.

• fit_conf (str/dict) – Either a dictionary with keys being the names of parameters passed to the fit method and values being the changed values (only values changed-from-default need be included) or a full string representation of the fit configuration that is being requested.

Returns:

Count rate in counts per second.

Return type:

Quantity

add_conv_factors(lo_ens, hi_ens, rates, lums, model)

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)

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=None, fit_conf=None)

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

If no model name is supplied, but only one model has been fit to this spectrum, then that model will be automatically selected - this behavior also applies to the fit configuration (fit_conf) parameter; if a model was only fit with one fit configuration then that will be automatically selected.

Parameters:

• model (str) – The model for which the plotting data is to be retrieved. Default is None, which will automatically be set to the model name IF only one model has been fit.

• fit_conf (str/dict) – Either a dictionary with keys being the names of parameters passed to the fit method and values being the changed values (only values changed-from-default need be included) or a full string representation of the fit configuration that is being requested.

Returns:

All information required to plot the data and model.

Return type:

dict

conv_channel_energy(to_convert)

This method will use RMF information to convert between channels and energy, and vice versa. If converting from channel to energy, the return will be the midpoint of the energy bin associated with that channel.

Parameters:

to_convert (Quantity) – The input Quantity, either with units of energy, or no units (which will be taken to mean channels). Any channel input will be converted to an integer, floats are not valid.

Return type:

Quantity

Returns:

The converted value, either as a channel (for energy input) or an energy (for channel input).

get_grouped_data(count_rate=True)

In many cases a spectrum is ‘grouped’ after generation, which involves combining sequential channels to increase the signal-to-noise. This method reads any grouping information in the spectrum associated with this object and returns the grouped data, along with everything necessary to use it. The properties that return counts, energy bins etc all give the raw data, unlike this method.

The spectrum quality information is used to filter the spectrum before grouping is applied, only channels with a quality flag of 0 are accepted.

Parameters:

count_rate (bool) – Should the grouped spectrum data be returned as a count-rate, default is True. If set to False then grouped data will be returned as counts.

Return type:

Tuple[Quantity, Quantity, Quantity, Quantity, Quantity, Quantity]

Returns:

The source count-rates (or counts) with uncertainties, the background count-rates (or counts) with uncertainties, the lower energy bounds of the groups, the upper energy bounds of the groups, the channel midpoints of the groups (with width in a second column), the energy midpoints of the groups (with width in a second column).

view_arf(figsize=(8, 6), xscale='log', yscale='linear', lo_en=<Quantity 0.01 keV>, hi_en=<Quantity 16. keV>)

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. The default is 0.01 keV. This will be altered to reflect the minimum value of the energy scale for this curve if lo_en is smaller than the lowest energy bin.

• hi_en (Quantity) – The upper energy limit for the x-axis. The default is 16.0 keV. This will be altered to reflect the maximum value of the energy scale for this curve if hi_en is greater than the highest energy bin.

get_view(ax, lo_lim=<Quantity 0.3 keV>, hi_lim=<Quantity 7.9 keV>, back_sub=True, energy=True, src_colour='black', bck_colour='firebrick', grouped=True, xscale='log', yscale='linear', fontsize=14, show_model_fits=True, model=None, fit_conf=None)

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

A spectrum can be viewed prior to fitting, and this method will produce plots that should be the same as the XSPEC count/s/keV (or channel) spectrum views. If a model has been fit, and the user wishes to display it, then the ‘normalised count/s/keV’ that are plotted are extracted from the XSPEC data, rather than assembled in this method.

Parameters:

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

• lo_lim (Quantity) – The lower limit applied to the plot, either a unitless Quantity (representing channels) or an energy Quantity. Limits will be automatically converted to the units of the x-axis. Default is 0.3 keV, matching the default lower limit of the XGA implementation of XSPEC fitting.

• hi_lim (Quantity) – The upper limit applied to the plot, either a unitless Quantity (representing channels) or an energy Quantity. Limits will be automatically converted to the units of the x-axis. Default is 7.9 keV, matching the default lower limit of the XGA implementation of XSPEC fitting.

• back_sub (bool) – Whether the plotted data should have their background subtracted, default is True.

• energy (bool) – Controls whether the x-axis is in units of energy, default is True. If False then channels are plotted instead.

• src_colour (str) – The colour in which to plot the source spectrum. Default is ‘black’.

• bck_colour (str) – The colour in which to plot the background spectrum. Default is ‘firebrick’ red.

• grouped (bool) – Whether the grouped spectrum should be plotted, default is True. If the spectrum has not been grouped then this be automatically set to False.

• 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 ‘linear’.

• fontsize (int/float) – The fontsize for axis labels. The legend fontsize will be fontsize - 1. The title fontsize will be fontsize + 1. Default is 14.

• show_model_fits (bool) – Whether any models fit to the spectrum by XSPEC should be shown. Default is True, but will be set to False if no fits have been performed.

• model (str) – This parameter allows you to specify a particular model to plot (if show_model_fits is True). Default is None, in which case all models will be shown (if available).

• fit_conf (str/dict) – This parameter allows you to specify a particular fit configuration of a model to plot (if ‘show_model_fits’ is True and ‘model’ is set). Pass either a dictionary with keys being the names of parameters passed to the XGA XSPEC fit function that were changed from default, and values being the changed values, or a full string representation of the fit configuration that is being requested. Default is None, in which case all fit configurations of a model will be plotted.

view(figsize=(10, 7), lo_lim=<Quantity 0.3 keV>, hi_lim=<Quantity 7.9 keV>, back_sub=True, energy=True, src_colour='black', bck_colour='firebrick', grouped=True, xscale='log', yscale='linear', fontsize=14, show_model_fits=True, save_path=None, model=None, fit_conf=None)

A method for viewing the data associated with this Spectrum instance.

A spectrum can be viewed prior to fitting, and this method will produce plots that should be the same as the XSPEC count/s/keV (or channel) spectrum views. If a model has been fit, and the user wishes to display it, then the ‘normalised count/s/keV’ that are plotted are extracted from the XSPEC data, rather than assembled in this method.

Parameters:

• figsize (tuple) – The desired size of the output figure, default is (10, 7).

• lo_lim (Quantity) – The lower limit applied to the plot, either a unitless Quantity (representing channels) or an energy Quantity. Limits will be automatically converted to the units of the x-axis. Default is 0.3 keV, matching the default lower limit of the XGA implementation of XSPEC fitting.

• hi_lim (Quantity) – The upper limit applied to the plot, either a unitless Quantity (representing channels) or an energy Quantity. Limits will be automatically converted to the units of the x-axis. Default is 7.9 keV, matching the default lower limit of the XGA implementation of XSPEC fitting.

• back_sub (bool) – Whether the plotted data should have their background subtracted, default is True.

• energy (bool) – Controls whether the x-axis is in units of energy, default is True. If False then channels are plotted instead.

• src_colour (str) – The colour in which to plot the source spectrum. Default is ‘black’.

• bck_colour (str) – The colour in which to plot the background spectrum. Default is ‘firebrick’ red.

• grouped (bool) – Whether the grouped spectrum should be plotted, default is True. If the spectrum has not been grouped then this be automatically set to False.

• 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 ‘linear’.

• fontsize (int/float) – The fontsize for axis labels. The legend fontsize will be fontsize - 1. The title fontsize will be fontsize + 1. Default is 14.

• show_model_fits (bool) – Whether any models fit to the spectrum by XSPEC should be shown. Default is True, but will be set to False if no fits have been performed.

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

• model (str) – This parameter allows you to specify a particular model to plot (if show_model_fits is True). Default is None, in which case all models will be shown (if available).

• fit_conf (str/dict) – This parameter allows you to specify a particular fit configuration of a model to plot (if ‘show_model_fits’ is True and ‘model’ is set). Pass either a dictionary with keys being the names of parameters passed to the XGA XSPEC fit function that were changed from default, and values being the changed values, or a full string representation of the fit configuration that is being requested. Default is None, in which case all fit configurations of a model will be plotted.

class xga.products.spec.AnnularSpectra(spectra)

Bases: BaseAggregateProduct

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

Parameters:

spectra (List[Spectrum]) – A list of XGA spectrum objects which make up this set.

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

property annulus_ids

The set of annulus IDs for this AnnularSpectra; i.e. for an AnnularSpectra with 4 annuli, this will return an array of 0, 1, 2, and 3.

Returns:

The array of annulus IDs.

Return type:

np.ndarray

background(obs_id, inst)

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)

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)

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.

Return type:

list

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.

Return type:

dict

get_spectra(annulus_ident, obs_id=None, inst=None)

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

property fitted_models

A property that gets the list of spectral models that have been fit to this AnnularSpectra instance.

Returns:

A list of models fit to this annular spectrum.

Return type:

list

property fitted_model_configurations

Property that returns a dictionary with model names as keys and lists of fit configuration identifiers as values, for the models that have been fit to this annular spectrum.

Returns:

Dictionary with model names as keys, and lists of model configuration identifiers as values.

Return type:

dict

add_cross_arf(arf, obs_id, inst, src_ann_id, cross_ann_id, set_ident)

This method allows you to add cross-arfs generated for this annular spectrum to a storage structure in the object. That means that other processes that make use of them, such as spectral fitting, will be able to retrieve them from this object easily.

Parameters:

• arf (BaseProduct/str) – Either an XGA BaseProduct instance (which is what is produced by the generation process) or a string path to the cross-arf file. This should represent the ‘cross_ann_id’ contribution to the ‘src_ann_id’ spectrum.

• obs_id (str) – The ObsID of the cross-arf - if ‘arf’ is a BaseProduct instance this argument will be compared the ObsID of the ‘arf’ object. It will also be checked to ensure that it is associated with this object.

• inst (str) – The instrument of the cross-arf - if ‘arf’ is a BaseProduct instance this argument will be compared the instrument of the ‘arf’ object. It will also be checked to ensure that it is associated with the ObsID in this object.

• src_ann_id (int) – The identifying number of the source annulus for this cross-arf.

• cross_ann_id (int) – The identifying number of the ‘cross’ annulus for this cross-arf.

• set_ident (int) – The set_ident that the cross-arf was generated for, it is checked against the set identifier of this object.

get_cross_arf_paths(obs_id, inst, src_ann_id, cross_ann_id=None)

This method allows the user to retrieve cross-arf paths for a specific ObsID-instrument spectrum of an annulus. For instance, passing an ObsID and Instrument, along with a src_ann_id of 1, to an annular spectrum with four annuli, will return the paths to cross-arfs between annulus 1 and 0, annulus 1 and 2, and annulus 1 and 3 (labelling starts at zero). If a cross_ann_id is passed in addition to a src_ann_id, then that specific path will be retrieved (but still returned in a dictionary).

Parameters:

• obs_id (str) – The ObsID of the spectrum for which you wish to retrieve cross-arf paths.

• inst (str) – The instrument of the spectrum for which you wish to retrieve cross-arf paths.

• src_ann_id (int) – The annulus ID (e.g. 1) of the spectrum you wish to retrieve cross-arf paths for.

• cross_ann_id (int) – Optionally you can specify the cross-arf annulus ID. The default is None, in which case all cross-arf paths for the given source annulus will be returned.

Returns:

A dictionary with annulus IDs as keys, and cross-arf paths as values.

Return type:

dict

get_cross_arf_lo_ens(obs_id, inst, src_ann_id, cross_ann_id=None)

A method that will retrieve the lower energy bound data from cross-arfs associated with this annular spectrum. A set of cross-arf lower energy bounds can be retrieved for a particular source annulus, or an individual cross-arf for a particular source annulus, depending on user input. It is extremely likely that all lower energy bounds will be the same for a given instrument, but this is not assumed.

Parameters:

• obs_id (str) – The ObsID of the spectrum for which you wish to retrieve cross-arf lower energy bounds.

• inst (str) – The instrument of the spectrum for which you wish to retrieve cross-arf lower energy bounds.

• src_ann_id (int) – The annulus ID (e.g. 1) of the spectrum you wish to retrieve cross-arf lower energy bounds for.

• cross_ann_id (int) – Optionally you can specify the cross-arf annulus ID. The default is None, in which case all lower energy bounds of cross-arfs for the given source annulus will be returned.

Returns:

A dictionary with annulus IDs as keys, and astropy array quantities of lower energy bounds as values.

Return type:

dict

get_cross_arf_hi_ens(obs_id, inst, src_ann_id, cross_ann_id=None)

A method that will retrieve the upper energy bound data from cross-arfs associated with this annular spectrum. A set of cross-arf upper energy bounds can be retrieved for a particular source annulus, or an individual cross-arf for a particular source annulus, depending on user input. It is extremely likely that all upper energy bounds will be the same for a given instrument, but this is not assumed.

Parameters:

• obs_id (str) – The ObsID of the spectrum for which you wish to retrieve cross-arf upper energy bounds.

• inst (str) – The instrument of the spectrum for which you wish to retrieve cross-arf upper energy bounds.

• src_ann_id (int) – The annulus ID (e.g. 1) of the spectrum you wish to retrieve cross-arf upper energy bounds for.

• cross_ann_id (int) – Optionally you can specify the cross-arf annulus ID. The default is None, in which case all upper energy bounds of cross-arfs for the given source annulus will be returned.

Returns:

A dictionary with annulus IDs as keys, and astropy array quantities of upper energy bounds as values.

Return type:

dict

get_cross_arf_eff_areas(obs_id, inst, src_ann_id, cross_ann_id=None)

A method that will retrieve the effective area data from cross-arfs associated with this annular spectrum. A set of cross-arf effective areas can be retrieved for a particular source annulus, or an individual cross-arf for a particular source annulus, depending on user input.

Parameters:

• obs_id (str) – The ObsID of the spectrum for which you wish to retrieve cross-arf effective areas.

• inst (str) – The instrument of the spectrum for which you wish to retrieve cross-arf effective areas.

• src_ann_id (int) – The annulus ID (e.g. 1) of the spectrum you wish to retrieve cross-arf effective areas for.

• cross_ann_id (int) – Optionally you can specify the cross-arf annulus ID. The default is None, in which case all effective areas of cross-arfs for the given source annulus will be returned.

Returns:

A dictionary with annulus IDs as keys, and astropy array quantities of effective areas as values.

Return type:

dict

add_fit_data(model, tab_line, lums, obs_order, fit_conf)

An equivalent 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.

• fit_conf (str) – In order to be able to store results for different fit configurations (e.g. different starting pars, abundance tables, all that), we need to have a key that identifies the configuration. We do not expect the user to be adding fit data, so this will be a key generated by the fit function.

get_results(annulus_ident, model=None, par=None, fit_conf=None)

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.

If no model name is supplied, but only one model has been fit to this annular spectrum, then that model will be automatically selected - this behavior also applies to the fit configuration (fit_conf) parameter; if a model was only fit with one fit configuration then that will be automatically selected.

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.

• fit_conf (str/dict) – Either a dictionary with keys being the names of parameters passed to the fit method and values being the changed values (only values changed-from-default need be included) or a full string representation of the fit configuration that is being requested.

Returns:

The requested result value, and uncertainties.

get_fit_statistic(annulus_ident, model=None, fit_conf=None)

Method that will retrieve fit statistic from the AnnularSpectra object. If no model name is supplied, but only one model has been fit to this annular spectrum, then that model will be automatically selected - this behavior also applies to the fit configuration (fit_conf) parameter; if a model was only fit with one fit configuration then that will be automatically selected.

Parameters:

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

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

• fit_conf (str/dict) – Either a dictionary with keys being the names of parameters passed to the fit method and values being the changed values (only values changed-from-default need be included) or a full string representation of the fit configuration that is being requested.

Returns:

The requested fit statistic.

get_test_statistic(annulus_ident, model=None, fit_conf=None)

Method that will retrieve test statistic from the AnnularSpectra object. If no model name is supplied, but only one model has been fit to this annular spectrum, then that model will be automatically selected - this behavior also applies to the fit configuration (fit_conf) parameter; if a model was only fit with one fit configuration then that will be automatically selected.

Parameters:

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

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

• fit_conf (str/dict) – Either a dictionary with keys being the names of parameters passed to the fit method and values being the changed values (only values changed-from-default need be included) or a full string representation of the fit configuration that is being requested.

Returns:

The requested test statistic.

get_luminosities(annulus_ident, model=None, lo_en=None, hi_en=None, fit_conf=None)

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.

If no model name is supplied, but only one model has been fit to this annular spectrum, then that model will be automatically selected - this behavior also applies to the fit configuration (fit_conf) parameter; if a model was only fit with one fit configuration then that will be automatically selected.

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 luminosity of (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.

• fit_conf (str/dict) – Either a dictionary with keys being the names of parameters passed to the fit method and values being the changed values (only values changed-from-default need be included) or a full string representation of the fit configuration that is being requested.

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, fit_conf=None)

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.

• fit_conf (str/dict) – Either a dictionary with keys being the names of parameters passed to the fit method and values being the changed values (only values changed-from-default need be included) or a full string representation of the fit configuration that is being requested.

Returns:

The requested profile object.

Return type:

Union[BaseProfile1D, ProjectedGasTemperature1D, ProjectedGasMetallicity1D]

view_cross_arfs(src_ann_id, obs_id, inst, src_arf_norm=False, figsize=(8, 6), xscale='log', yscale='linear', lo_en=<Quantity 0.01 keV>, hi_en=<Quantity 16. keV>)

A method that produces a plot of the cross-arf curves for a specified source annulus spectrum, for a specified ObsID and instrument. The original source spectrum will also be plotted as a reference. This method can also be used to create ‘normalized’ curves were the cross-arf effective area values are divided by the source arf effective areas.

Parameters:

• src_ann_id (int) – The annulus ID of the source annulus for which you wish to plot cross-arf curves.

• obs_id (str) – The ObsID of the spectrum for which you wish to plot cross-arf curves.

• inst (str) – The instrument of the spectrum for which you wish to plot cross-arf curves.

• src_arf_norm (bool)

• figsize (tuple) – The size of the figure, the default is (8, 6).

• 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. The default is 0.01 keV. This will be altered to reflect the minimum value of the energy scale for this curve if lo_en is smaller than the lowest energy bin.

• hi_en (Quantity) – The upper energy limit for the x-axis. The default is 16.0 keV. This will be altered to reflect the maximum value of the energy scale for this curve if hi_en is greater than the highest energy bin.

view_annulus(ann_ident, figsize=(10, 7), lo_lim=<Quantity 0.3 keV>, hi_lim=<Quantity 7.9 keV>, back_sub=True, energy=True, src_colour='black', bck_colour='firebrick', grouped=True, xscale='log', yscale='linear', fontsize=14, show_model_fits=True, save_path=None, model=None, fit_conf=None)

A view method that allows all spectra from a particular annulus to be displayed on the same axis.

A spectrum can be viewed prior to fitting, and this method will produce plots that should be the same as the XSPEC count/s/keV (or channel) spectrum views. If a model has been fit, and the user wishes to display it, then the ‘normalised count/s/keV’ that are plotted are extracted from the XSPEC data, rather than assembled in this method.

Parameters:

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

• figsize (tuple) – The desired size of the output figure, default is (10, 7).

• lo_lim (Quantity) – The lower limit applied to the plot, either a unitless Quantity (representing channels) or an energy Quantity. Limits will be automatically converted to the units of the x-axis. Default is 0.3 keV, matching the default lower limit of the XGA implementation of XSPEC fitting.

• hi_lim (Quantity) – The upper limit applied to the plot, either a unitless Quantity (representing channels) or an energy Quantity. Limits will be automatically converted to the units of the x-axis. Default is 7.9 keV, matching the default lower limit of the XGA implementation of XSPEC fitting.

• back_sub (bool) – Whether the plotted data should have their background subtracted, default is True.

• energy (bool) – Controls whether the x-axis is in units of energy, default is True. If False then channels are plotted instead.

• src_colour (str) – The colour in which to plot the source spectrum. Default is ‘black’.

• bck_colour (str) – The colour in which to plot the background spectrum. Default is ‘firebrick’ red.

• grouped (bool) – Whether the grouped spectrum should be plotted, default is True. If the spectrum has not been grouped then this be automatically set to False.

• 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 ‘linear’.

• fontsize (int/float) – The fontsize for axis labels. The legend fontsize will be fontsize - 1. The title fontsize will be fontsize + 1. Default is 14.

• show_model_fits (bool) – Whether any models fit to the spectrum by XSPEC should be shown. Default is True, but will be set to False if no fits have been performed.

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

• model (str) – This parameter allows you to specify a particular model to plot (if show_model_fits is True). Default is None, in which case all models will be shown (if available).

• fit_conf (str/dict) – This parameter allows you to specify a particular fit configuration of a model to plot (if ‘show_model_fits’ is True and ‘model’ is set). Pass either a dictionary with keys being the names of parameters passed to the XGA XSPEC fit function that were changed from default, and values being the changed values, or a full string representation of the fit configuration that is being requested. Default is None, in which case all fit configurations of a model will be plotted.

view_annuli(obs_id, inst, model=None, fit_conf=None, elevation_angle=30, azimuthal_angle=-60, figsize=(12, 8), lo_lim=<Quantity 0.3 keV>, hi_lim=<Quantity 7.9 keV>, back_sub=True, energy=True, src_colour='black', bck_colour='firebrick', grouped=True, fontsize=14)

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) – This parameter allows you to specify a particular model to plot. Default is None, in which case a model will be automatically selected if only one has been fit, or no model will be shown if one has not.

• fit_conf (str/dict) – This parameter allows you to specify a particular fit configuration of a model to plot (if ‘show_model_fits’ is True and ‘model’ is set). Pass either a dictionary with keys being the names of parameters passed to the XGA XSPEC fit function that were changed from default, and values being the changed values, or a full string representation of the fit configuration that is being requested. The default is None - if only one fit configuration has been run for the model, then that will be automatically selected.

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

• lo_lim (Quantity) – The lower limit applied to the plot, either a unitless Quantity (representing channels) or an energy Quantity. Limits will be automatically converted to the units of the x-axis. Default is 0.3 keV, matching the default lower limit of the XGA implementation of XSPEC fitting.

• hi_lim (Quantity) – The upper limit applied to the plot, either a unitless Quantity (representing channels) or an energy Quantity. Limits will be automatically converted to the units of the x-axis. Default is 7.9 keV, matching the default lower limit of the XGA implementation of XSPEC fitting.

• back_sub (bool) – Whether the plotted data should have their background subtracted, default is True.

• energy (bool) – Controls whether the x-axis is in units of energy, default is True. If False then channels are plotted instead.

• src_colour (str) – The colour in which to plot the source spectrum. Default is ‘black’.

• bck_colour (str) – The colour in which to plot the background spectrum. Default is ‘firebrick’ red.

• grouped (bool) – Whether the grouped spectrum should be plotted, default is True. If the spectrum has not been grouped then this be automatically set to False.

• 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 ‘linear’.

• fontsize (int/float) – The fontsize for axis labels. The legend fontsize will be fontsize - 1. The title fontsize will be fontsize + 1. Default is 14.

view(model=None, fit_conf=None, figsize=(12, 8), elevation_angle=30, azimuthal_angle=-60)

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 it’s 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. The default is None, in which case if one model has been fit then it will be automatically selected. If multiple models have been fit then a model name must be supplied.

• fit_conf (str/dict) – Either a dictionary with keys being the names of parameters passed to the fit method and values being the changed values (only values changed-from-default need be included) or a full string representation of the fit configuration that is being requested. Default is None, and if only one fit configuration has been run for the model then it will be automatically selected, otherwise it will need to be specified.

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

products.lightcurve module

class xga.products.lightcurve.LightCurve(path, obs_id, instrument, stdout_str, stderr_str, gen_cmd, central_coord, inn_rad, out_rad, lo_en, hi_en, time_bin_size, pattern_expr, region=False, is_back_sub=True)

Bases: BaseProduct

This is the XGA LightCurve product class, which is used to interface with X-ray lightcurves generated for a variety of sources. It provides simple access to data and information about the lightcurve, fitting capabilities, and the ability to easily create lightcurve visualisations.

Parameters:

• path (str) – The path to the lightcurve.

• obs_id (str) – The ObsID from which this lightcurve was generated.

• instrument (str) – The instrument from which this lightcurve.

• stdout_str (str) – The stdout from the generation process.

• stderr_str (str) – The stderr for the generation process.

• gen_cmd (str) – The generation command for the lightcurve.

• central_coord (Quantity) – The central coordinate of the region from which this lightcurve was extracted.

• inn_rad (Quantity) – The inner radius of the lightcurve region.

• out_rad (Quantity) – The outer radius of the lightcurve region.

• lo_en (Quantity) – The lower energy bound for this lightcurve.

• hi_en (Quantity) – The upper energy bound for this lightcurve.

• time_bin_size (Quantity) – The time bin size used to generate the lightcurve.

• pattern_expr (str) – The event selection pattern used to generate the lightcurve.

• region (bool) – Whether this was generated from a region in a region file

• is_back_sub (bool) – Whether this lightcurve is background subtracted or not.

property storage_key

This property returns the storage key which this object assembles to place the LightCurve in an XGA source’s storage structure. The key is based on the properties of the LightCurve, and some 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 light curve 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 light curve 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 light curve 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 light curve was generated.

Returns:

The outer radius(ii) of the region.

Return type:

Quantity

property time_bin_size

Gives the time bin size used to generate the lightcurve.

Returns:

The time bin size used to generate the lightcurve.

Return type:

Quantity

property count_rate

Returns the background-subtracted instrumental-effect-corrected count-rates for this light curve.

Returns:

Background-subtracted instrumental-effect-corrected count-rates, in units of ct/s.

Return type:

Quantity

property count_rate_err

Returns the background-subtracted instrumental-effect-corrected count-rate uncertainties for this light curve.

Returns:

Background-subtracted instrumental-effect-corrected count-rate uncertainties, in units of ct/s.

Return type:

Quantity

property src_count_rate

Returns the source instrumental-effect-corrected count-rates for this light curve.

Returns:

Source instrumental-effect-corrected count-rates, in units of ct/s.

Return type:

Quantity

property src_count_rate_err

Returns the source instrumental-effect-corrected count-rate uncertainties for this light curve.

Returns:

Source instrumental-effect-corrected count-rate uncertainties, in units of ct/s.

Return type:

Quantity

property ref_time

Returns the reference time for this lightcurve, which is what the ‘time’ values are calculated from.

Returns:

An Astropy Time object that defines the reference time for this lightcurve.

Return type:

Time

property time_system

Returns the time system for this lightcurve; e.g. TT or terrestrial time.

Returns:

The time system.

Return type:

str

property time

Returns the time steps that correspond to the count-rates measured for this light curve

Returns:

Background-subtracted and instrumental-effect-corrected count-rate uncertainties, in units of seconds.

Return type:

Quantity

property datetime

Returns the time steps for this light curve, but in a datetime format, and no longer relative to a reference time.

Returns:

The absolute datetimes that the time steps correspond to.

Return type:

np.ndarray(datetime)

property bck_count_rate

Returns the background count-rates for this light curve.

Returns:

Background count-rates, in units of ct/s.

Return type:

Quantity

property bck_count_rate_err

Returns the background count-rate uncertainties for this light curve.

Returns:

Background count-rate uncertainties, in units of ct/s.

Return type:

Quantity

property frac_exp

The fractional exposure time for each entry in this light curve.

Returns:

Fractional exposure.

Return type:

Quantity

property src_gti

Returns a 2D quantity with start (column 0) and end (column 1) times for the good-time-intervals of the source light curve.

Returns:

A 2D astropy quantity with start (column 0) and end (column 1) times for the source good-time-intervals (in seconds).

Return type:

Quantity

property bck_gti

Returns a 2D quantity with start (column 0) and end (column 1) times for the good-time-intervals of the background light curve.

Returns:

A 2D astropy quantity with start (column 0) and end (column 1) times for the background good-time-intervals (in seconds).

Return type:

Quantity

property start_time

A property getter to access the recorded start time for this light curve.

Returns:

Light curve start time, in seconds.

Return type:

Quantity

property stop_time

A property getter to access the recorded stop time for this light curve.

Returns:

Light curve stop time, in seconds.

Return type:

Quantity

property start_datetime

A property getter to access the recorded start datetime for this light curve.

Returns:

Light curve start datetime.

Return type:

datetime

property stop_datetime

A property getter to access the recorded stop datetime for this light curve.

Returns:

Light curve stop datetime.

Return type:

datetime

property time_assign

A property getter to access the physical location that the assigned times are based on.

Returns:

The TASSIGN entry of the light curve file.

Return type:

str

property header

Property getter allowing access to the main fits header of the light curve.

Returns:

The header of the primary data table (RATE) of the light curve that was read in.

Return type:

FITSHDR

overlap_check(lightcurves)

A simple method which checks whether a passed LightCurve (or list of lightcurves) overlap temporally with this lightcurve.

Parameters:

lightcurves (LightCurve/List[LightCurve]) – A LightCurve, or a list of LightCurves, to check for overlap with this LightCurve.

Return type:

np.ndarray/bool

Returns:

A boolean value (or an array of boolean values if multiple LightCurve instances were passed) which is True if the passed LightCurve temporally overlaps with this one, and False if it does not.

get_view(ax, time_unit=Unit('s'), lo_time_lim=None, hi_time_lim=None, colour='black', plot_sep=False, src_colour='tab:cyan', bck_colour='firebrick', custom_title=None, label_font_size=15, title_font_size=18, highlight_bad_times=True)

view(figsize=(14, 6), time_unit=Unit('s'), lo_time_lim=None, hi_time_lim=None, colour='black', plot_sep=False, src_colour='tab:cyan', bck_colour='firebrick', custom_title=None, label_font_size=15, title_font_size=18, highlight_bad_times=True)

class xga.products.lightcurve.AggregateLightCurve(lightcurves)

Bases: BaseAggregateProduct

The init method for the AggregateLightCurve class, performs checks and organises the light-curves which have been passed in, for easy retrieval. It also allows for analysis to be performed on the combined data, and for visualisations to be created.

This class is designed to package light-curves generated for the same source, with the same settings, and for the same energy bounds - if interested in the time varying behaviours of multiple energy bands then the HardnessCurve and AggregateHardnessCurve products should be used. It can take light-curves from different instruments, and will deal with them simultaneously rather than stacking them.

Light curves that are part of an AggregateLightCurve will be separated into ‘time chunks’, where a time chunk is a period that has uninterrupted coverage. For instance, three XMM observations separated by a year each would be in three different time chunks, but if there were a fourth observation that was taken by another telescope and happened concurrently (even if it didn’t start and end at the same time) with the first XMM observation, then it would be in the same time chunk.

Parameters:

lightcurves (Union[List[LightCurve], np.ndarray]) – A list or array of LightCurve objects that are to be collated in an AggregateLightCurve. These must be for the same source, and generated with the same settings.

property obs_ids

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

Returns:

A list of ObsIDs.

Return type:

list

property instruments

A property of this spectrum set that details which ObsIDs and instruments have contributed lightcurves to this object. The top level keys are ObsIDs, and the values are lists of instruments.

Returns:

A dictionary of lists, with the top level keys being ObsIDs, and the lists containing instruments associated with those ObsIDs.

Return type:

dict

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 all_lightcurves

Simple extra wrapper for get_lightcurve that allows the user to retrieve every single lightcurve associated with this AggregateLightCurve instance, for all time chunk IDs, ObsIDs, and Instruments.

Returns:

A list of every single lightcurve associated with this object.

Return type:

List[LightCurve]

property central_coord

This property provides the central coordinates (RA-Dec) of the region that this set of light curves 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 set of light curves 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 set of light curves 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 set of light curves was generated.

Returns:

The outer radius(ii) of the region.

Return type:

Quantity

property time_bin_size

Gives the time bin size used to generate this set of light curves.

Returns:

The time bin size used to generate this set of light curves.

Return type:

Quantity

property time_chunk_ids

Getter for the time chunk IDs associated with this AggregateLightCurve. Light curves that are part of an AggregateLightCurve will be separated into ‘time chunks’, where a time chunk is a period that has uninterrupted coverage. For instance, three XMM observations separated by a year each would be in three different time chunks, but if there were a fourth observation that was taken by another telescope and happened concurrently (even if it didn’t start and end at the same time) with the first XMM observation, then it would be in the same time chunk.

Returns:

np.ndarray

Return type:

An array of integer time chunk identifiers, ordered from earlier to later times.

property num_time_chunks

Getter for the number of time chunks associated with this AggregateLightCurve. Light curves that are part of an AggregateLightCurve will be separated into ‘time chunks’, where a time chunk is a period that has uninterrupted coverage. For instance, three XMM observations separated by a year each would be in three different time chunks, but if there were a fourth observation that was taken by another telescope and happened concurrently (even if it didn’t start and end at the same time) with the first XMM observation, then it would be in the same time chunk.

Returns:

np.ndarray

Return type:

An array of integer time chunk identifiers, ordered from earlier to later times.

property time_chunks

A getter for the start and stop times of the time chunks associated with this AggregateLightCurve. The left hand column are start times, and the right hand column are stop times. These are the earliest and latest times of coverage for all the observations in the particular time chunk.

Returns:

A Nx2 non-scalar Astropy Quantity, where the left hand column are chunk start times, and the right hand column are chunk stop times.

Return type:

Quantity

property datetime_chunks

A getter for the start and stop datetimes of the time chunks associated with this AggregateLightCurve. The left hand column are start datetimes, and the right hand column are stop datetimes. These are the earliest and latest times of coverage for all the observations in the particular time chunk.

Returns:

A Nx2 array of datetime objects, where the left hand column are chunk start datetimes, and the right hand column are chunk stop datetimes.

Return type:

np.ndarray(datetime)

property storage_key

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

Returns:

String storage key.

Return type:

str

property event_selection_patterns

The event selection patterns used for different instruments that are associated with this AggregateLightCurve.

Returns:

A dictionary where keys are instrument names and values are event selection patterns.

Return type:

dict

get_lightcurves(time_chunk_id, obs_id=None, inst=None)

This is the getter for the lightcurves stored in the AggregateLightCurve data storage structure. They can be retrieved based on ObsID and instrument.

Parameters:

• time_chunk_id (int) – The time chunk identifier to retrieve lightcurves 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 lightcurves, or just a LightCurve object if one match is found.

Return type:

Union[List[LightCurve], LightCurve]

get_data(inst, date_time=False)

A get method to retrieve all count-rate and timing data for a particular instrument from this AggregateLightCurve. The data are in the correct temporal order.

Parameters:

• inst (str) – The instrument for which to retrieve the overall count-rate and time data.

• date_time (bool) – Whether the time data should be returned as an array of datetimes (not the default), or an Astropy TimeDelta object with the time as a different from MJD 50814.0 in seconds (the default).

Returns:

The count rate data, count rate uncertainty data, and time data for the selected instrument. These are in the correct temporal order.

Return type:

Tuple[Quantity, Quantity, Union[TimeDelta, np.ndarray]]

get_view(fig, inst=None, custom_title=None, label_font_size=18, title_font_size=20)

A get method for a populated visualisation of the light curves present in this AggregateLightCurve.

Parameters:

• fig (Figure) – The matplotlib Figure object to create axes on, and thus make the plot.

• inst (str) – A specific instrument to display data for. Default is None, in which case all instruments are plotted.

• custom_title (str) – A custom title to add to the visualisation - the default is None, in which case a title containing the source name and energy band will be generated.

• label_font_size (int) – The font size for axes labels, default is 18.

• title_font_size (int) – The font size for the title, default is 20.

Returns:

A dictionary of axes objects that have been added, and the figure object that was passed in.

Return type:

Tuple[dict, Figure]

view(figsize=(14, 6), inst=None, custom_title=None, label_font_size=15, title_font_size=18)

This method creates a combined visualisation of all the light curves associated with this object (apart from when you specify a single instrument, then it uses all the light curves from that instrument). The data are displayed in the correct temporal order, with the x-axis labels indicating the date and time rather than the mission specific internal time.

Parameters:

• figsize (tuple) – The size of the visualisation figure, default is (14, 6). Adjusting this value is the best way to achieve nice looking plots when labels are overlapping, particularly when there are many observations and time chunks to plot in the x-direction.

• inst (str) – A specific instrument to display data for. Default is None, in which case all instruments are plotted.

• custom_title (str) – A custom title to add to the visualisation - the default is None, in which case a title containing the source name and energy band will be generated.

• label_font_size (int) – The font size for axes labels, default is 18.

• title_font_size (int) – The font size for the title, default is 20.