HpxGeom¶

class gammapy.maps.HpxGeom(nside, nest=True, coordsys='CEL', region=None, axes=None, sparse=False)[source]¶

Bases: gammapy.maps.Geom

Geometry class for HEALPIX maps.

This class performs mapping between partial-sky indices (pixel number within a HEALPIX region) and all-sky indices (pixel number within an all-sky HEALPIX map). Multi-band HEALPIX geometries use a global indexing scheme that assigns a unique pixel number based on the all-sky index and band index. In the single-band case the global index is the same as the HEALPIX index.

By default the constructor will return an all-sky map. Partial-sky maps can be defined with the region argument.

Parameters:

nside : ndarray: HEALPIX nside parameter, the total number of pixels is 12*nside*nside. For multi-dimensional maps one can pass either a single nside value or a vector of nside values defining the pixel size for each image plane. If nside is not a scalar then its dimensionality should match that of the non-spatial axes.
nest : bool: True -> ‘NESTED’, False -> ‘RING’ indexing scheme
coordsys : str: Coordinate system, ‘CEL’ | ‘GAL’
region : str or tuple: Spatial geometry for partial-sky maps. If none the map will encompass the whole sky. String input will be parsed according to HPX_REG header keyword conventions. Tuple input can be used to define an explicit list of pixels encompassed by the geometry.
axes : list: Axes for non-spatial dimensions.
sparse : bool: If True defer allocation of partial- to all-sky index mapping arrays. This option is only compatible with partial-sky maps with an analytic geometry (e.g. DISK).

Attributes Summary

`axes`	List of non-spatial axes.
`center_coord`	Map coordinates of the center of the geometry (tuple).
`center_pix`	Pixel coordinates of the center of the geometry (tuple).
`center_skydir`	Sky coordinate of the center of the geometry.
`coordsys`
`data_shape`	Shape of the Numpy data array matching this geometry.
`ipix`	HEALPIX pixel and band indices for every pixel in the map.
`is_allsky`	Flag for all-sky maps.
`is_hpx`
`is_image`	Whether the geom is equivalent to an image without extra dimensions.
`is_regular`	Flag identifying whether this geometry is regular in non-spatial dimensions.
`ndim`	Number of dimensions (int).
`nest`	Is HEALPix order nested? (bool).
`npix`	Number of pixels in each band.
`nside`	NSIDE in each band.
`order`	ORDER in each band (`NSIDE = 2 ** ORDER`).
`ordering`	HEALPix ordering (‘NESTED’ or ‘RING’).
`projection`	Map projection.
`region`	Region string.
`shape_axes`	Shape of non-spatial axes.

Methods Summary

`contains`(self, coords)	Check if a given map coordinate is contained in the geometry.
`contains_pix`(self, pix)	Check if a given pixel coordinate is contained in the geometry.
`coord_to_idx`(self, coords[, clip])	Convert map coordinates to pixel indices.
`coord_to_pix`(self, coords)	Convert map coordinates to pixel coordinates.
`coord_to_tuple`(self, coord)	Generate a coordinate tuple compatible with this geometry.
`copy`(self, \\kwargs)	Copy and overwrite given attributes.
`create`([nside, binsz, nest, coordsys, …])	Create an HpxGeom object.
`crop`(self, crop_width)	Crop the geometry at the edges.
`downsample`(self, factor)	Downsample the spatial dimension of the geometry by a given factor.
`energy_mask`(self[, emin, emax])	Create a mask for a given energy range.
`from_hdu`(hdu[, hdu_bands])	Create an HPX object from a BinTable HDU.
`from_hdulist`(hdulist[, hdu, hdu_bands])	Load a geometry object from a FITS HDUList.
`from_header`(header[, hdu_bands, pix])	Create an HPX object from a FITS header.
`get_axis_by_name`(self, name)	Get an axis by name (case in-sensitive).
`get_axis_index_by_name`(self, name)	Get an axis index by name (case in-sensitive).
`get_coord`(self[, idx, flat])	Get the coordinate array for this geometry.
`get_idx`(self[, idx, local, flat])	Get tuple of pixel indices for this geometry.
`get_index_list`(nside, nest, region)	Get list of pixels indices for all the pixels in a region.
`get_skydirs`(self)	Get the sky coordinates of all the pixels in this geometry.
`global_to_local`(self, idx_global[, ravel])	Compute global (all-sky) index from a local (partial-sky) index.
`identify_hpx_convention`(header)	Identify the convention used to write this file.
`local_to_global`(self, idx_local)	Compute a local index (partial-sky) from a global (all-sky) index.
`make_bands_hdu`(self[, hdu, hdu_skymap, conv])
`make_header`(self[, conv])	Build and return FITS header for this HEALPIX map.
`make_wcs`(self[, proj, oversample, …])	Make a WCS projection appropriate for this HPX pixelization.
`pad`(self, pad_width)	Pad the geometry at the edges.
`pix_to_coord`(self, pix)	Convert pixel coordinates to map coordinates.
`pix_to_idx`(self, pix[, clip])	Convert pixel coordinates to pixel indices.
`slice_by_idx`(self, slices)	Create a new geometry by slicing the non-spatial axes.
`solid_angle`(self)	Solid angle array (`Quantity` in `sr`).
`to_cube`(self, axes)	Append non-spatial axes to create a higher-dimensional geometry.
`to_image`(self)	Create 2D image geometry (drop non-spatial dimensions).
`to_slice`(self, slices[, drop_axes])
`to_swapped`(self)	Geometry copy with swapped ORDERING (NEST->RING or vice versa).
`to_ud_graded`(self, order)	Upgrade or downgrade the resolution to the given order.
`upsample`(self, factor)	Upsample the spatial dimension of the geometry by a given factor.

Attributes Documentation

axes¶: List of non-spatial axes.

center_coord¶: Map coordinates of the center of the geometry (tuple).

center_pix¶: Pixel coordinates of the center of the geometry (tuple).

center_skydir¶

Sky coordinate of the center of the geometry.

Returns:	pix : `SkyCoord`

coordsys¶

data_shape¶: Shape of the Numpy data array matching this geometry.

ipix¶: HEALPIX pixel and band indices for every pixel in the map.

is_allsky¶: Flag for all-sky maps.

is_hpx = True¶

is_image¶: Whether the geom is equivalent to an image without extra dimensions.

is_regular¶

Flag identifying whether this geometry is regular in non-spatial dimensions.

False for multi-resolution or irregular geometries. If true all image planes have the same pixel geometry.

ndim¶: Number of dimensions (int).

nest¶: Is HEALPix order nested? (bool).

npix¶

Number of pixels in each band.

For partial-sky geometries this can be less than the number of pixels for the band NSIDE.

nside¶: NSIDE in each band.

order¶

ORDER in each band (NSIDE = 2 ** ORDER).

Set to -1 for bands with NSIDE that is not a power of 2.

ordering¶: HEALPix ordering (‘NESTED’ or ‘RING’).

projection¶: Map projection.

region¶: Region string.

shape_axes¶: Shape of non-spatial axes.

Methods Documentation

contains(self, coords)[source]¶

Check if a given map coordinate is contained in the geometry.

Parameters:	coords : tuple or `MapCoord` Tuple of map coordinates.
Returns:	containment : `ndarray` Bool array.

contains_pix(self, pix)¶

Check if a given pixel coordinate is contained in the geometry.

Parameters:	pix : tuple Tuple of pixel coordinates.
Returns:	containment : `ndarray` Bool array.

coord_to_idx(self, coords, clip=False)¶

Convert map coordinates to pixel indices.

Parameters:

coords : tuple or MapCoord: Coordinate values in each dimension of the map. This can either be a tuple of numpy arrays or a MapCoord object. If passed as a tuple then the ordering should be (longitude, latitude, c_0, …, c_N) where c_i is the coordinate vector for axis i.
clip : bool: Choose whether to clip indices to the valid range of the geometry. If false then indices for coordinates outside the geometry range will be set -1.

Returns:

pix : tuple: Tuple of pixel indices in image and band dimensions. Elements set to -1 correspond to coordinates outside the map.

coord_to_pix(self, coords)[source]¶

Convert map coordinates to pixel coordinates.

Parameters:	coords : tuple Coordinate values in each dimension of the map. This can either be a tuple of numpy arrays or a MapCoord object. If passed as a tuple then the ordering should be (longitude, latitude, c_0, …, c_N) where c_i is the coordinate vector for axis i.
Returns:	pix : tuple Tuple of pixel coordinates in image and band dimensions.

coord_to_tuple(self, coord)¶

Generate a coordinate tuple compatible with this geometry.

Parameters:	coord : `MapCoord`

copy(self, **kwargs)¶

Copy and overwrite given attributes.

Parameters:	**kwargs : dict Keyword arguments to overwrite in the map geometry constructor.
Returns:	copy : `Geom` Copied map geometry.

classmethod create(nside=None, binsz=None, nest=True, coordsys='CEL', region=None, axes=None, skydir=None, width=None)[source]¶

Create an HpxGeom object.

Parameters:

nside : int or ndarray: HEALPix NSIDE parameter. This parameter sets the size of the spatial pixels in the map.
binsz : float or ndarray: Approximate pixel size in degrees. An NSIDE will be chosen that correponds to a pixel size closest to this value. This option is superseded by nside.
nest : bool: True for HEALPIX “NESTED” indexing scheme, False for “RING” scheme
coordsys : {‘CEL’, ‘GAL’}, optional: Coordinate system, either Galactic (‘GAL’) or Equatorial (‘CEL’).
skydir : tuple or SkyCoord: Sky position of map center. Can be either a SkyCoord object or a tuple of longitude and latitude in deg in the coordinate system of the map.
region : str: HPX region string. Allows for partial-sky maps.
width : float: Diameter of the map in degrees. If set the map will encompass all pixels within a circular region centered on skydir.
axes : list: List of axes for non-spatial dimensions.

Returns:

geom : HpxGeom: A HEALPix geometry object.

Examples

>>> from gammapy.maps import HpxGeom, MapAxis
>>> axis = MapAxis.from_bounds(0,1,2)
>>> geom = HpxGeom.create(nside=16)
>>> geom = HpxGeom.create(binsz=0.1, width=10.0)
>>> geom = HpxGeom.create(nside=64, width=10.0, axes=[axis])
>>> geom = HpxGeom.create(nside=[32,64], width=10.0, axes=[axis])

crop(self, crop_width)[source]¶

Crop the geometry at the edges.

Parameters:	crop_width : {sequence, array_like, int} Number of values cropped from the edges of each axis.
Returns:	geom : `Geom` Cropped geometry.

downsample(self, factor)[source]¶

Downsample the spatial dimension of the geometry by a given factor.

Parameters:	factor : int Downsampling factor. axis : str Axis to downsample.
Returns:	geom : `Geom` Downsampled geometry.

energy_mask(self, emin=None, emax=None)¶

Create a mask for a given energy range.

Parameters:	emin, emax : `Quantity` Energy range

classmethod from_hdu(hdu, hdu_bands=None)[source]¶

Create an HPX object from a BinTable HDU.

Parameters:	hdu : `BinTableHDU` The FITS HDU hdu_bands : `BinTableHDU` The BANDS table HDU
Returns:	hpx : `HpxGeom` HEALPix geometry.

classmethod from_hdulist(hdulist, hdu=None, hdu_bands=None)¶

Load a geometry object from a FITS HDUList.

Parameters:	hdulist : `HDUList` HDU list containing HDUs for map data and bands. hdu : str Name or index of the HDU with the map data. hdu_bands : str Name or index of the HDU with the BANDS table. If not defined this will be inferred from the FITS header of the map HDU.
Returns:	geom : `Geom` Geometry object.

classmethod from_header(header, hdu_bands=None, pix=None)[source]¶

Create an HPX object from a FITS header.

Parameters:	header : `Header` The FITS header hdu_bands : `BinTableHDU` The BANDS table HDU. pix : tuple List of pixel index vectors defining the pixels encompassed by the geometry. For EXPLICIT geometries with HPX_REG undefined this tuple defines the geometry.
Returns:	hpx : `HpxGeom` HEALPix geometry.

get_axis_by_name(self, name)¶

Get an axis by name (case in-sensitive).

Parameters:	name : str Name of the requested axis
Returns:	axis : `MapAxis` Axis

get_axis_index_by_name(self, name)¶

Get an axis index by name (case in-sensitive).

Parameters:	name : str Axis name
Returns:	index : int Axis index

get_coord(self, idx=None, flat=False)[source]¶

Get the coordinate array for this geometry.

Returns a coordinate array with the same shape as the data array. Pixels outside the geometry are set to NaN. Coordinates for a single image plane can be accessed by setting idx to the index tuple of a plane.

Parameters:	idx : tuple, optional A tuple of indices with one index for each non-spatial dimension. If defined only coordinates for the image plane with this index will be returned. If none then coordinates for all pixels will be returned. flat : bool, optional Return a flattened array containing only coordinates for pixels contained in the geometry.
Returns:	coords : tuple Tuple of coordinate vectors with one vector for each dimension.

get_idx(self, idx=None, local=False, flat=False)[source]¶

Get tuple of pixel indices for this geometry.

Returns all pixels in the geometry by default. Pixel indices for a single image plane can be accessed by setting idx to the index tuple of a plane.

Parameters:

idx : tuple, optional: A tuple of indices with one index for each non-spatial dimension. If defined only pixels for the image plane with this index will be returned. If none then all pixels will be returned.
local : bool: Flag to return local or global pixel indices. Local indices run from 0 to the number of pixels in a given image plane.
flat : bool, optional: Return a flattened array containing only indices for pixels contained in the geometry.

Returns:

idx : tuple: Tuple of pixel index vectors with one vector for each dimension.

static get_index_list(nside, nest, region)[source]¶

Get list of pixels indices for all the pixels in a region.

Parameters:	nside : int HEALPIX nside parameter nest : bool True for ‘NESTED’, False = ‘RING’ region : str HEALPIX region string
Returns:	ilist : `ndarray` List of pixel indices.

get_skydirs(self)[source]¶: Get the sky coordinates of all the pixels in this geometry.

global_to_local(self, idx_global, ravel=False)[source]¶

Compute global (all-sky) index from a local (partial-sky) index.

Parameters:	idx_global : tuple A tuple of pixel indices with global HEALPix pixel indices. ravel : bool Return a raveled index.
Returns:	idx_local : tuple A tuple of pixel indices with local HEALPIX pixel indices.

static identify_hpx_convention(header)[source]¶: Identify the convention used to write this file.

local_to_global(self, idx_local)[source]¶

Compute a local index (partial-sky) from a global (all-sky) index.

Returns:	idx_global : tuple A tuple of pixel index vectors with global HEALPIX pixel indices

make_bands_hdu(self, hdu=None, hdu_skymap=None, conv=None)¶

make_header(self, conv='gadf', **kwargs)[source]¶: Build and return FITS header for this HEALPIX map.

make_wcs(self, proj='AIT', oversample=2, drop_axes=True, width_pix=None)[source]¶

Make a WCS projection appropriate for this HPX pixelization.

Parameters:

drop_axes : bool: Drop non-spatial axes from the HEALPIX geometry. If False then all dimensions of the HEALPIX geometry will be copied to the WCS geometry.
proj : str: Projection type of WCS geometry.
oversample : float: Oversampling factor for WCS map. This will be the approximate ratio of the width of a HPX pixel to a WCS pixel. If this parameter is None then the width will be set from width_pix.
width_pix : int: Width of the WCS geometry in pixels. The pixel size will be set to the number of pixels satisfying oversample or width_pix whichever is smaller. If this parameter is None then the width will be set from oversample.

Returns:

wcs : WcsGeom: WCS geometry

pad(self, pad_width)[source]¶

Pad the geometry at the edges.

Parameters:	pad_width : {sequence, array_like, int} Number of values padded to the edges of each axis.
Returns:	geom : `Geom` Padded geometry.

pix_to_coord(self, pix)[source]¶

Convert pixel coordinates to map coordinates.

Parameters:	pix : tuple Tuple of pixel coordinates.
Returns:	coords : tuple Tuple of map coordinates.

pix_to_idx(self, pix, clip=False)[source]¶

Convert pixel coordinates to pixel indices.

Returns -1 for pixel coordinates that lie outside of the map.

Parameters:	pix : tuple Tuple of pixel coordinates. clip : bool Choose whether to clip indices to the valid range of the geometry. If false then indices for coordinates outside the geometry range will be set -1.
Returns:	idx : tuple Tuple of pixel indices.

slice_by_idx(self, slices)¶

Create a new geometry by slicing the non-spatial axes.

Parameters:	slices : dict Dict of axes names and integers or `slice` object pairs. Contains one element for each non-spatial dimension. For integer indexing the correspoding axes is dropped from the map. Axes not specified in the dict are kept unchanged.
Returns:	geom : `Geom` Sliced geometry.

solid_angle(self)[source]¶

Solid angle array (Quantity in sr).

The array has the same dimensionality as map.nside since all pixels have the same solid angle.

to_cube(self, axes)[source]¶

Append non-spatial axes to create a higher-dimensional geometry.

This will result in a new geometry with N+M dimensions where N is the number of current dimensions and M is the number of axes in the list.

Parameters:	axes : list Axes that will be appended to this geometry.
Returns:	geom : `Geom` Map geometry.

to_image(self)[source]¶

Create 2D image geometry (drop non-spatial dimensions).

Returns:	geom : `Geom` Image geometry.

to_slice(self, slices, drop_axes=True)[source]¶

to_swapped(self)[source]¶

Geometry copy with swapped ORDERING (NEST->RING or vice versa).

Returns:	geom : `HpxGeom` A HEALPix geometry object.

to_ud_graded(self, order)[source]¶

Upgrade or downgrade the resolution to the given order.

This method does not preserve the geometry footprint.

Returns:	geom : `HpxGeom` A HEALPix geometry object.

upsample(self, factor)[source]¶

Upsample the spatial dimension of the geometry by a given factor.

Parameters:	factor : int Upsampling factor. axis : str Axis to upsample.
Returns:	geom : `Geom` Upsampled geometry.