imagetools

imagetools.misc module

xga.imagetools.misc.pix_deg_scale(coord, input_wcs, small_offset=<Quantity 1. arcmin>)

Very heavily inspired by the regions module version of this function, just tweaked to work better for my use case. Perturbs the given coordinates with the small_offset value, converts the changed ra-dec coordinates to pixel, then calculates the difference between the new and original coordinates in pixel. Then small_offset is converted to degrees and divided by the pixel distance to calculate a pixel to degree factor.

Parameters

• coord (Quantity) – The starting coordinates.

• input_wcs (WCS) – The world coordinate system used to calculate the pixel to degree scale

• small_offset (Quantity) – The amount you wish to perturb the original coordinates

Returns

Factor that can be used to convert pixel distances to degree distances, returned as an astropy quantity with units of deg/pix.

Return type

Quantity

xga.imagetools.misc.sky_deg_scale(im_prod, coord, small_offset=<Quantity 1. arcmin>)

This is equivelant to pix_deg_scale, but instead calculates the conversion factor between XMM’s XY sky coordinate system and degrees.

Parameters

• im_prod (Image/Ratemap/ExpMap) – The image product to calculate the conversion factor for.

• coord (Quantity) – The starting coordinates.

• small_offset (Quantity) – The amount you wish to perturb the original coordinates

Returns

A scaling factor to convert sky distances to degree distances, returned as an astropy quantity with units of deg/xmm_sky.

Return type

Quantity

xga.imagetools.misc.pix_rad_to_physical(im_prod, pix_rad, out_unit, coord, z=None, cosmo=None)

Pure convenience function to convert a list of pixel radii to whatever unit we might want at the end. Used quite a lot in the imagetools.profile functions, which is why it was split off into its own function. Redshift and cosmology must be supplied if proper distance units (like kpc) are chosen for out_unit.

Parameters

• im_prod (Image/RateMap/ExpMap) – The image/ratemap product for which the conversion is taking place.

• pix_rad (Quantity) – The array of pixel radii to convert to out_unit.

• out_unit (UnitBase/str) – The desired output unit for the radii, either an astropy unit object or a name string.

• coord (Quantity) – The position of the object being analysed.

• z (float/int) – The redshift of the object (only required for proper distance units like kpc).

• cosmo – The chosen cosmology for the analysis (only required for proper distance units like kpc).

Returns

An astropy Quantity with the radii in units of out_unit.

Return type

Quantity

xga.imagetools.misc.physical_rad_to_pix(im_prod, physical_rad, coord, z=None, cosmo=None)

Another convenience function, this time to convert physical radii to pixels. It can deal with both angular and proper radii, so long as redshift and cosmology information is provided for the conversion from proper radii to pixels.

Parameters

• im_prod (Image/RateMap/ExpMap) –

• physical_rad (Quantity) – The physical radius to be converted to pixels.

• coord (Quantity) – The position of the object being analysed.

• z (float/int) – The redshift of the object (only required for input proper distance units like kpc).

• cosmo – The chosen cosmology for the analysis (only required for input proper distance units like kpc).

Returns

The converted radii, in an astropy Quantity with pix units.

Return type

Quantity

xga.imagetools.misc.data_limits(im_prod)

A function that finds the pixel coordinates that bound where data is present in Image or RateMap object.

Parameters

im_prod (Image/RateMap/ndarray) – An Image, RateMap, or numpy array that you wish to find boundary coordinates for.

Returns

Two lists, the first with the x lower and upper bounding coordinates, and the second with the y lower and upper bounding coordinates.

Return type

Tuple[List[int, int], List[int, int]]

xga.imagetools.misc.edge_finder(data, keep_corners=True, border=False)

A simple edge finding algorithm designed to locate ‘edges’ in binary data, or in special cases produce a detector map of an instrument using an exposure map. The algorithm takes the difference of one column from the next, over the entire array, then does the same with rows. Different difference values indicate where edges are in the array, and when added together all edges should be located.

Depending on how the ‘border’ option is set, the returned array will either represent the exact edge, or a boundary that is 1 pixel outside the actual edge.

Parameters

• data (RateMap/ExpMap/ndarray) – The 2D array or exposure map to run edge detection on. If an array is passed it must only consist of 0s and 1s.

• keep_corners (bool) – Should corner information be kept in the output array. If True then 2s in the output will indicate vertices.

• border (bool) – If True, then the returned array will represent a border running around the boundary of the true edge, rather than the outer boundary of the edge itself.

Returns

An array of 0s and 1s. 1s indicate a detected edge.

Return type

np.ndarray

imagetools.profile module

xga.imagetools.profile.annular_mask(centre, inn_rad, out_rad, shape, start_ang=<Quantity 0. deg>, stop_ang=<Quantity 360. deg>)

A handy little function to generate annular (or circular) masks in the form of numpy arrays. It produces the src_mask for a given shape of image, centered at supplied coordinates, and with inner and outer radii supplied by the user also. Angular limits can also be supplied to give the src_mask an annular dependence. This function should be properly vectorised, and accepts inner and outer radii in the form of arrays. The result will be an len_y, len_x, N dimensional array, where N is equal to the length of inn_rad.

Parameters

• centre (Quantity) – Astropy pix quantity of the form Quantity([x, y], pix).

• inn_rad (np.ndarray) – Pixel radius for the inner part of the annular src_mask.

• out_rad (np.ndarray) – Pixel radius for the outer part of the annular src_mask.

• start_ang (Quantity) – Lower angular limit for the src_mask.

• stop_ang (Quantity) – Upper angular limit for the src_mask.

• shape (tuple) – The output from the shape property of the numpy array you are generating masks for.

Returns

The generated src_mask array.

Return type

np.ndarray

xga.imagetools.profile.ann_radii(im_prod, centre, rad, z=None, pix_step=1, rad_units=Unit("arcsec"), cosmo=LambdaCDM(name=None, H0=<Quantity 70. km / (Mpc s)>, Om0=0.3, Ode0=0.7, Tcmb0=<Quantity 0. K>, Neff=3.04, m_nu=None, Ob0=None), min_central_pix_rad=3, start_pix_rad=0)

Will probably only ever be called by an internal brightness calculation, but two different methods need it so it gets its own method.

Parameters

• im_prod (Image) – An Image or RateMap product object that you wish to calculate annuli for.

• centre (Quantity) – The coordinates of the centre of the set of annuli.

• rad (Quantity) – The outer radius of the set of annuli.

• z (float) – The redshift of the source of interest, required if the output radius units are a proper radius.

• pix_step (int) – The width (in pixels) of each annular bin, default is 1.

• rad_units (UnitBase) – The output units for the centres of the annulli returned by this function. The inner and outer radii will always be in pixels.

• cosmo (Cosmology) – An instance of an astropy cosmology, the default is a concordance flat LambdaCDM model.

• start_pix_rad (int) – The pixel radius at which the innermost annulus starts, default is zero.

• min_central_pix_rad (int) – The minimum radius of the innermost circular annulus (will only be used if start_pix_rad is 0, otherwise the innermost annulus is not a circle), default is three.

Returns

Returns the inner and outer radii of the annuli (in pixels), and the centres of the annuli in cen_rad_units.

Return type

Tuple[np.ndarray, np.ndarray, Quantity]

xga.imagetools.profile.radial_brightness(rt, centre, outer_rad, back_inn_rad_factor=1.05, back_out_rad_factor=1.5, interloper_mask=None, z=None, pix_step=1, rad_units=Unit("arcsec"), cosmo=LambdaCDM(name=None, H0=<Quantity 70. km / (Mpc s)>, Om0=0.3, Ode0=0.7, Tcmb0=<Quantity 0. K>, Neff=3.04, m_nu=None, Ob0=None), min_snr=0.0, min_central_pix_rad=3, start_pix_rad=0)

A simple method to calculate the average brightness in circular annuli upto the radius of the chosen region. The annuli are one pixel in width, and as this uses the masks that were generated earlier, interloper sources should be removed.

Parameters

• rt (RateMap) – A RateMap object to construct a brightness profile from.

• centre (Quantity) – The coordinates for the centre of the brightness profile.

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

• back_inn_rad_factor (float) – This factor is multiplied by the outer pixel radius, which gives the inner radius for the background mask.

• back_out_rad_factor (float) – This factor is multiplied by the outer pixel radius, which gives the outer radius for the background mask.

• interloper_mask (np.ndarray) – A numpy array that masks out any interloper sources.

• z (float) – The redshift of the source of interest.

• pix_step (int) – The width (in pixels) of each annular bin, default is 1.

• rad_units (BaseUnit) – The desired output units for the central radii of the annuli.

• cosmo (Cosmology) – An astropy cosmology object for source coordinate conversions.

• min_snr (float) – The minimum signal to noise allowed for each bin in the profile. If any point is below this threshold the profile will be rebinned. Default is 0.0

• start_pix_rad (int) – The pixel radius at which the innermost annulus starts, default is zero.

• min_central_pix_rad (int) – The minimum radius of the innermost circular annulus (will only be used if start_pix_rad is 0, otherwise the innermost annulus is not a circle), default is three.

Returns

The brightness is returned in a flat numpy array, then the radii at the centre of the bins are returned in units of kpc, the width of the bins, and finally the average brightness in the background region is returned.

Return type

Tuple[SurfaceBrightness1D, bool]

xga.imagetools.profile.pizza_brightness(im_prod, src_mask, back_mask, centre, rad, num_slices=4, z=None, pix_step=1, cen_rad_units=Unit("arcsec"), cosmo=LambdaCDM(name=None, H0=<Quantity 70. km / (Mpc s)>, Om0=0.3, Ode0=0.7, Tcmb0=<Quantity 0. K>, Neff=3.04, m_nu=None, Ob0=None))

imagetools.psf module

xga.imagetools.psf.rl_psf(sources, iterations=15, psf_model='ELLBETA', lo_en=<Quantity 0.5 keV>, hi_en=<Quantity 2. keV>, bins=4, num_cores=1)

An implementation of the Richardson-Lucy (doi:10.1364/JOSA.62.000055) PSF deconvolution algorithm that also takes into account the spatial variance of the XMM Newton PSF. The sources passed into this function will have all images matching the passed energy range deconvolved, the image objects will have the result stored in them alongside the original data, and a combined image will be generated. I view this method as quite crude, but it does seem to work, and I may implement a more intelligent way of doing PSF deconvolutions later. I initially tried convolving the PSFs generated at different spatial points with the chunks of data relevant to them in isolation, but the edge effects were very obvious. So I settled on convolving the whole original image with each PSF, and after it was finished taking the relevant chunks and patchworking them into a new array.

Parameters

• sources (BaseSource/BaseSample) – A single source object, or list of source objects.

• iterations (int) – The number of deconvolution iterations performed by the Richardson-Lucy algorithm.

• psf_model (str) – Which model of PSF should be used for this deconvolution. The default is ELLBETA, the best available.

• lo_en (Quantity) – The lower energy bound of the images to be deconvolved.

• hi_en (Quantity) – The upper energy bound of the images to be deconvolved.

• bins (int) – Number of bins that the X and Y axes will be divided into when generating a PSFGrid.

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