HpxGeom

class gammapy.maps.HpxGeom(nside, nest=True, coordsys='CEL', region=None, axes=None, conv='gadf', sparse=False)

Bases: gammapy.maps.MapGeom

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.

conv : str

Convention for FITS serialization format.

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.
conv	Name of default FITS convention associated with this geometry.
coordsys
data_shape	Shape of the Numpy data array matching this geometry.
hpx_conv
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 MapGeom instance 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, \*\*kwargs)	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

conv

Name of default FITS convention associated with this geometry.

coordsys

data_shape

Shape of the Numpy data array matching this geometry.

hpx_conv

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)

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)

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 MapGeom instance and overwrite given attributes.

Parameters:

**kwargs : dict

Keyword arguments to overwrite in the map geometry constructor.

Returns:

copy : MapGeom

Copied map geometry.

classmethod create(nside=None, binsz=None, nest=True, coordsys='CEL', region=None, axes=None, conv='gadf', skydir=None, width=None)

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.

conv : str

Convention for FITS file format.

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)

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 : MapGeom

Cropped geometry.

downsample(self, factor)

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

Parameters:

factor : int

Downsampling factor.

axis : str

Axis to downsample.

Returns:

geom : MapGeom

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)

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 : MapGeom

Geometry object.

classmethod from_header(header, hdu_bands=None, pix=None)

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)

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)

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)

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)

Get the sky coordinates of all the pixels in this geometry.

global_to_local(self, idx_global, ravel=False)

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)

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.

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, **kwargs)

Build and return FITS header for this HEALPIX map.

make_wcs(self, proj='AIT', oversample=2, drop_axes=True, width_pix=None)

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)

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 : MapGeom

Padded geometry.

pix_to_coord(self, pix)

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)

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 : MapGeom

Sliced geometry.

solid_angle(self)

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)

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 : MapGeom

Map geometry.

to_image(self)

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

Returns:

geom : MapGeom

Image geometry.

to_slice(self, slices, drop_axes=True)

to_swapped(self)

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

Returns:

geom : HpxGeom

A HEALPix geometry object.

to_ud_graded(self, order)

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)

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

Parameters:

factor : int

Upsampling factor.

axis : str

Axis to upsample.

Returns:

geom : MapGeom

Upsampled geometry.