GiftsHealPix¶

class gdt.missions.gifts.localization.GiftsHealPix[source]¶

Bases: GbmHealPix

Class for GIFTS HEALPix localization files.

Attributes Summary

`centroid`	The RA, Dec of the centroid
`filename`	The filename
`frame`	The spacecraft frame at the time of the localization
`geo_location`	The geocenter location at `trigtime`
`geo_probability`	The amount of localization probability on the Earth
`geo_radius`	The apparent angular radius of the Earth at `trigtime`.
`hdulist`	The list of Header Data Units
`headers`	The headers
`npix`	Number of pixels in the HEALPix map
`nside`	The HEALPix resolution
`num_hdus`	The number of HDUs
`pixel_area`	The area of each pixel in square degrees
`prob`	The HEALPix array for the probability/pixel
`quaternion`	The spacecraft attitude quaternion
`scpos`	(astropy.coordinates.CartesianRepresentation): The spacecraft position in Earth inertial coordinates
`sig`	The HEALPix array for the significance of each pixel
`sun_location`	The Sun location at `trigtime`
`trigtime`	The reference time

Methods Summary

`area`(clevel)	Calculate the sky area contained within a given confidence region
`close`()	Close the file
`column`(hdu_num, col_name)	Return a column from an HDU as an array.
`columns_as_array`(hdu_num, col_names[, dtype])	Return a list of columns from an HDU as an array.
`confidence`(ra, dec)	Calculate the localization confidence level for a given point.
`confidence_region_path`(clevel[, numpts_ra, ...])	Return the bounding path for a given confidence region.
`convolve`(model, args, *kwargs)	Convolve the map with a model kernel.
`from_annulus`(center_ra, center_dec, radius, ...)	Create a HealPixLocalization object of a Gaussian-width annulus.
`from_chi2grid`(chi2grid[, nside, headers, ...])	Create a GbmHealPix object from a `Chi2Grid` object.
`from_data`(prob_arr, sig_arr[, trigtime, ...])	Create a GiftsHealPix object from a healpix array.
`from_gaussian`(center_ra, center_dec, sigma)	Create a HealPixLocalization object of a Gaussian
`from_vertices`(ra_pts, dec_pts[, nside, ...])	Create a HealPixLocalization object from a list of RA, Dec vertices.
`get_column_names`(hdu_num)	Get the column names in a HDU.
`multiply`(healpix1, healpix2[, primary, ...])	Multiply two GbmHealPix maps and return a new map.
`observable_fraction`(healpix)	The observable fraction of a healpix probability region on the sky.
`open`(file_path, **kwargs)	Open a GIFTS HEALPix FITS file and return the GiftsHealPix object
`prob_array`([numpts_ra, numpts_dec, ...])	Return the localization probability mapped to a grid on the sky
`probability`(ra, dec[, per_pixel])	Calculate the localization probability at a given point.
`region_probability`(healpix[, prior])	The probability that the localization is associated with the localization region from another map.
`remove_earth`()	Return a new GbmHealPix with the probability on the Earth masked out.
`source_probability`(ra, dec[, prior])	The probability that the GbmHealPix localization is associated with a known point location.
`write`(directory[, filename])	Write the file to disk.

Attributes Documentation

centroid¶

The RA, Dec of the centroid

Type:: (float, float)

filename¶

The filename

Type:: (str)

frame¶

The spacecraft frame at the time of the localization

Type:: (SpacecraftFrame)

geo_location¶

The geocenter location at trigtime

Type:: (astropy.coordinates.SkyCoord)

geo_probability¶

The amount of localization probability on the Earth

Type:: (float)

geo_radius¶

The apparent angular radius of the Earth at trigtime.

Note

If a scpos isn’t set, then an average 67.5 deg is returned

Type:: (astropy.units.Quantity)

hdulist¶

The list of Header Data Units

Type:: (astropy.io.fits.hdu.HDUList)

headers¶

The headers

Type:: (FileHeaders)

npix¶

Number of pixels in the HEALPix map

Type:: (int)

nside¶

The HEALPix resolution

Type:: (int)

num_hdus¶

The number of HDUs

Type:: (int)

pixel_area¶

The area of each pixel in square degrees

Type:: (float)

prob¶

The HEALPix array for the probability/pixel

Type:: (np.array)

quaternion¶

The spacecraft attitude quaternion

Type:: (Quaternion)

scpos¶: (astropy.coordinates.CartesianRepresentation): The spacecraft position in Earth inertial coordinates

sig¶

The HEALPix array for the significance of each pixel

Type:: (np.array)

sun_location¶

The Sun location at trigtime

Type:: (astropy.coordinates.SkyCoord)

trigtime¶

The reference time

Type:: (float)

Methods Documentation

area(clevel)¶

Calculate the sky area contained within a given confidence region

Parameters:: clevel (float) – The localization confidence level (valid range 0-1)
Returns:: (float)

close()¶: Close the file

column(hdu_num: int, col_name: str) → array¶

Return a column from an HDU as an array.

Parameters:

hdu_num (int) – The HDU number
col_name (str) – The name of the column

Returns:

(np.array)

columns_as_array(hdu_num: int, col_names: List[str], dtype: dtype = None) → array¶

Return a list of columns from an HDU as an array.

Parameters:

hdu_num (int) – The HDU number
col_names (list of str) – The names of the columns
dtype (np.dtype, optional) – The custom dtype of the output array

Returns:

(np.array)

confidence(ra, dec)¶

Calculate the localization confidence level for a given point. This function interpolates the map at the requested point rather than providing the value at the nearest pixel center.

Parameters:

ra (float) – The RA
dec (float) – The Dec

Returns:

(float)

confidence_region_path(clevel, numpts_ra=360, numpts_dec=180)¶

Return the bounding path for a given confidence region.

Parameters:

clevel (float) – The localization confidence level (valid range 0-1)
numpts_ra (int, optional) – The number of grid points along the RA axis. Default is 360.
numpts_dec (int, optional) – The number of grid points along the Dec axis. Default is 180.

Returns:

([(np.array, np.array), …]) –

A list of RA, Dec points, where each: item in the list is a continuous closed path.

convolve(model, *args, **kwargs)¶

Convolve the map with a model kernel. The model can be a Gaussian kernel or any mixture of Gaussian kernels. Uses healpy.smoothing.

An example of a model kernel with a 50%/50% mixture of two Gaussians, one with a 1-deg width, and the other with a 3-deg width:

def gauss_mix_example():
    sigma1 = np.deg2rad(1.0)
    sigma2 = np.deg2rad(3.0)
    frac1 = 0.50
    return ([sigma1, sigma2], [frac1])

Parameters:

model (<function>) – The function representing the model kernel
*args – Arguments to be passed to the model kernel function

Returns:

(GbmHealPix)

classmethod from_annulus(center_ra, center_dec, radius, sigma, nside=None, trigtime=None, filename=None, **kwargs)¶

Create a HealPixLocalization object of a Gaussian-width annulus.

Parameters:

center_ra (float) – The RA of the center of the annulus
center_dec (float) – The Dec of the center of the annulus
radius (float) – The radius of the annulus, in degrees, measured to the center of the of the annulus
sigma (float) – The Gaussian standard deviation width of the annulus, in degrees
nside (int, optional) – The nside of the HEALPix to make. By default, the nside is automatically determined by the sigma width. Set this argument to override the default.
trigtime (float, optional) – The reference time for the map
filename (str, optional) – The filename

Returns:

(HealPixLocalization)

classmethod from_chi2grid(chi2grid, nside=128, headers=None, filename=None, exact_nearest=False, grid_nearest=False)¶

Create a GbmHealPix object from a Chi2Grid object.

Parameters:

chi2grid (Chi2Grid) – The chi2grid object containing the chi-squared/log-likelihood info.
nside (int, optional) – The nside resolution to use. Default is 128.
headers (FileHeaders, optional) – The file headers
filename (str, optional) – The filename
exact_nearest (bool) – Use exact nearest pixel interpolation when True. This method is slow O(minute) due to angular difference calculation.
grid_nearest (bool) – Use approximate nearest pixel interpolation when True. This method is fast O(second) by using 2D grid.

Returns:

(GbmHealPix)

classmethod from_data(prob_arr, sig_arr, trigtime=None, headers=None, filename=None, quaternion=None, scpos=None)[source]¶

Create a GiftsHealPix object from a healpix array.

Parameters:

prob_arr (np.array) – The HEALPix array containing the probability/pixel
sig_arr (np.array) – The HEALPix array containing the significance/pixel
trigtime (float, optional) – The time corresponding to the localization
headers (FileHeaders, optional) – The file headers
filename (str, optional) – The filename
quaternion (Quaternion, optional) – The associated spacecraft quaternion used to determine the detector pointings in equatorial coordinates
scpos (astropy.coordinates.representation.CartesianRepresentation, optional) – The associated spacecraft position in Earth inertial coordinates used to determine the geocenter location in equatorial coordinates

Returns:

(GiftsHealPix)

classmethod from_gaussian(center_ra, center_dec, sigma, nside=None, trigtime=None, filename=None, **kwargs)¶

Create a HealPixLocalization object of a Gaussian

Parameters:

center_ra (float) – The RA of the center of the Gaussian
center_dec (float) – The Dec of the center of the Gaussian
sigma (float) – The Gaussian standard deviation, in degrees
nside (int, optional) – The nside of the HEALPix to make. By default, the nside is automatically determined by the sigma of the Gaussian. Set this argument to override the default.
trigtime (float, optional) – The reference time for the map
filename (str, optional) – The filename

Returns:

(HealPixLocalization)

classmethod from_vertices(ra_pts, dec_pts, nside=64, trigtime=None, filename=None, **kwargs)¶

Create a HealPixLocalization object from a list of RA, Dec vertices. The probability within the vertices will be distributed uniformly and zero probability outside the vertices.

Parameters:

ra_pts (np.array) – The array of RA coordinates
dec_pts (np.array) – The array of Dec coordinates
nside (int, optional) – The nside of the HEALPix to make. Default is 64.
trigtime (float, optional) – The reference time for the map
filename (str, optional) – The filename

Returns:

(HealPixLocalization)

get_column_names(hdu_num: int)¶

Get the column names in a HDU. Returns empty if there is no data extension in the HDU.

Parameters:: hdu_num (int) – The HDU number
Returns:: (tuple)

classmethod multiply(healpix1, healpix2, primary=0, output_nside=128)¶

Multiply two GbmHealPix maps and return a new map.

Note

Either healpix1 or healpix2 can be a non-GbmHealPix object, however at least one of them must be a GbmHealPix object and the primary argument must be set to the appropriate GbmHealPix object otherwise a TypeError will be raised.

Parameters:

healpix1 (HealPix or GbmHealPix) – One of the HEALPix maps to multiply
healpix2 (HealPix or GbmHealPix) – The other HEALPix map to multiply
primary (int, optional) – If 0, use the first map header information, or if 1, use the second map header information. Default is 1.
output_nside (int, optional) – The nside of the multiplied map. Default is 128.

Returns: GbmHealPix: The multiplied map

observable_fraction(healpix)¶

The observable fraction of a healpix probability region on the sky. Non-observable regions are ones that are behind the Earth.

Parameters:: healpix (HealPix) – The healpix region for which to calculate the observable fraction.
Returns:: (float)

classmethod open(file_path, **kwargs)[source]¶

Open a GIFTS HEALPix FITS file and return the GiftsHealPix object

Parameters:: file_path (str) – The file path of the FITS file
Returns:: (GiftsHealPix)

prob_array(numpts_ra=360, numpts_dec=180, sqdegrees=True, sig=False)¶

Return the localization probability mapped to a grid on the sky

Parameters:

numpts_ra (int, optional) – The number of grid points along the RA axis. Default is 360.
numpts_dec (int, optional) – The number of grid points along the Dec axis. Default is 180.
sqdegrees (bool, optional) – If True, the prob_array is in units of probability per square degrees, otherwise in units of probability per pixel. Default is True
sig (bool, optional) – Set True to retun the significance map on a grid instead of the probability. Default is False.

Returns:

3-tuple containing –

np.array: The probability (or significance) array with shape (numpts_dec, numpts_ra)
np.array: The RA grid points
np.array: The Dec grid points

probability(ra, dec, per_pixel=False)¶

Calculate the localization probability at a given point. This function interpolates the map at the requested point rather than providing the vale at the nearest pixel center.

Parameters:

ra (float) – The RA
dec (float) – The Dec
per_pixel (bool, optional) – If True, return probability per pixel, otherwise return probability per square degree. Default is False.

Returns:

(float)

region_probability(healpix, prior=0.5)¶

The probability that the localization is associated with the localization region from another map. This is calculated against the null hypothesis that the two maps represent unassociated sources:

\(P(A | \mathcal{I}) = \frac{P(\mathcal{I} | A) \ P(A)} {P(\mathcal{I} | A) \ P(A) + P(\mathcal{I} | \neg A) \ P(\neg A)}\)

where

\(P(\mathcal{I} | A)\) is the integral over the overlap of the two maps once the Earth occultation has been removed for this map.
\(P(\mathcal{I} | \neg A)\) is the integral over the overlap of this map with a uniform distribution on the sky (i.e. the probability the localization is associated with a random point on the sky)
\(P(A)\) is the prior probability that this localization is associated with the other HEALPix map.

Note

The localization region of this map overlapping the Earth will be removed and the remaining unocculted region is used for the calculation. The other map is assumed to have no exclusionary region.

Parameters:

healpix (HealPixLocalization) – The healpix map for which to calculate the spatial association.
prior (float, optional) – The prior probability that the localization is associated with the source. Default is 0.5.

Returns:

(float)

remove_earth()¶

Return a new GbmHealPix with the probability on the Earth masked out. The remaining probability on the sky is renormalized.

Note

The geo_location attribute must be available to use this function.

Returns:: (GbmHealPix)

source_probability(ra, dec, prior=0.5)¶

The probability that the GbmHealPix localization is associated with a known point location. This is calculated against the null hypothesis that the localization originates from an unassociated random source that has equal probability of origination anywhere in the sky:

\(P(A | \mathcal{I}) = \frac{P(\mathcal{I} | A) \ P(A)} {P(\mathcal{I} | A) \ P(A) + P(\mathcal{I} | \neg A) \ P(\neg A)}\)

where

\(P(\mathcal{I} | A)\) is the probability of the localization at the point source once the Earth occultation has been removed
\(P(\mathcal{I} | \neg A)\) is the probability per pixel assuming a uniform distribution on the sky (i.e. the probability the localization is associated with a random point on the sky)
\(P(A)\) is the prior probability that the localization is associated with the point source

Note

If the point source is behind the Earth, then it is assumed that GBM could not observe it, therefore the probability will be zero.

Parameters:

ra (float) – The RA of the known source location
dec (float) – The Dec of the known source location
prior (float, optional) – The prior probability that the localization is associated with the source. Default is 0.5.

Returns:

(float)

write(directory: str | Path, filename: str = None, **kwargs)¶

Write the file to disk.

Parameters:

directory (str) – The directory to write the file.
filename (str, optional) – The filename. If omitted, attempts to use the filename if set.

GiftsHealPix¶

Page Contents

Previous topic

Next topic

This Page

Navigation

GiftsHealPix¶