HealPixLocalization¶

class gdt.core.healpix.HealPixLocalization[source]¶

Bases: HealPix

Class for localization HEALPix files

Attributes Summary

`centroid`	The RA, Dec of the centroid
`npix`	Number of pixels in the HEALPix map
`nside`	The HEALPix resolution
`pixel_area`	The area of each pixel in square degrees
`prob`	The HEALPix array for the probability/pixel
`sig`	The HEALPix array for the significance of each pixel
`trigtime`	The reference time

Methods Summary

`area`(clevel)	Calculate the sky area contained within a given confidence region
`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_data`(prob_arr[, trigtime, filename])	Create a HealPixLocalization object from a HEALPix probability 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.
`multiply`(healpix1, healpix2[, primary, ...])	Multiply two HealPix maps and return a new HealPix 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 HealPix localization is associated with another HealPixLocalization map.
`source_probability`(ra, dec[, prior])	The probability that the HealPix localization is associated with a known point location.

Attributes Documentation

centroid¶

The RA, Dec of the centroid

Type:: (float, float)

npix¶

Number of pixels in the HEALPix map

Type:: (int)

nside¶

The HEALPix resolution

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)

sig¶

The HEALPix array for the significance of each pixel

Type:: (np.array)

trigtime¶

The reference time

Type:: (float)

Methods Documentation

area(clevel)[source]¶

Calculate the sky area contained within a given confidence region

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

confidence(ra, dec)[source]¶

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)[source]¶

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:

(HealPix)

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

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 or list of floats) – The Gaussian standard deviation width/s 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_data(prob_arr, trigtime=None, filename=None, **kwargs)[source]¶

Create a HealPixLocalization object from a HEALPix probability array.

Parameters:

prob_arr (np.array) – The HEALPix array
trigtime (float, optional) – The reference time for the map
filename (str, optional) – The filename

Returns:

(HealPixLocalization)

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

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)[source]¶

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)

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

Multiply two HealPix maps and return a new HealPix object

Parameters:

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

Returns: (HealPix)

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

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)[source]¶

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)[source]¶

The probability that the HealPix localization is associated with another HealPixLocalization map. This is calculated against the null hypothesis that the two HealPix maps are unassociated:

\(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.

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)

source_probability(ra, dec, prior=0.5)[source]¶

The probability that the HealPix localization is associated with a known point location. This is calculated against the null hypothesis that the HealPix 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
\(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

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)

HealPixLocalization¶

Page Contents

Previous topic

Next topic

This Page

Navigation

HealPixLocalization¶