HpxNDMap

class gammapy.maps.HpxNDMap

Bases: HpxMap

HEALPix map with any number of non-spatial dimensions.

This class uses an N+1D numpy array to represent the sequence of HEALPix image planes. Following the convention of WCS-based maps this class uses a column-wise ordering for the data array with the spatial dimension being tied to the last index of the array.

Parameters:

geomHpxGeom

HEALPix geometry object.

datandarray, optional

HEALPix data array. If None, then an empty array will be allocated. Default is None.

dtypestr, optional

Data type. Default is ‘float32’.

metadict, optional

Dictionary to store metadata. Default is None.

unitstr or Unit

The map unit.

Notes

• For examples, see HEALPix-based maps

Methods Summary

convolve(kernel[, convolution_method])	Convolve map with a WCS kernel.
convolve_full(kernel)	Convolve map with a symmetrical WCS kernel.
convolve_wcs(kernel, **kwargs)	Convolve map with a WCS kernel.
crop(crop_width)	Crop the spatial dimensions of the map.
cutout(position, width, *args, **kwargs)	Create a cutout around a given position.
downsample(factor[, preserve_counts, axis_name])	Downsample the spatial dimension by a given factor.
fill_by_idx(idx[, weights])	Fill pixels at idx with given weights.
from_hdu(hdu[, hdu_bands, format, colname])	Make a HpxNDMap object from a FITS HDU.
from_wcs_tiles(wcs_tiles[, nest])	Create HEALPix map from WCS tiles.
get_by_idx(idx)	Return map values at the given pixel indices.
interp_by_coord(coords[, method, fill_value])	Interpolate map values at the given map coordinates.
interp_by_pix(pix[, method, fill_value])	Interpolate map values at the given pixel coordinates.
plot([method, ax, normalize, proj, ...])	Quickplot method.
plot_mask([method, ax, proj, oversample, ...])	Plot the mask as a shaded area.
sample_coord(n_events[, random_state])	Sample position and energy of events.
set_by_idx(idx, vals)	Set pixels at idx with given vals.
smooth(width[, kernel])	Smooth the map.
stack(other[, weights, nan_to_num])	Stack cutout into map.
to_nside(nside[, preserve_counts])	Upsample or downsample the map to a given nside.
to_region_nd_map(region[, func, weights, method])	Get region ND map in a given region.
to_swapped()	Return a new map with the opposite scheme (ring or nested).
to_wcs([sum_bands, normalize, proj, ...])	Make a WCS object and convert HEALPix data into WCS projection.
to_wcs_tiles([nside_tiles, margin, method, ...])	Convert HpxNDMap to a list of WCS tiles.
upsample(factor[, order, preserve_counts, ...])	Upsample the spatial dimension by a given factor.

Methods Documentation

convolve(kernel, convolution_method='wcs-tan', **kwargs)

Convolve map with a WCS kernel.

Project the map into a WCS geometry, convolve with a WCS kernel and project back into the initial HEALPix geometry.

If the kernel is two-dimensional, it is applied to all image planes likewise. If the kernel is higher dimensional it must match the map in the number of dimensions and the corresponding kernel is selected for every image plane.

Parameters:

kernelPSFKernel

Convolution kernel. The pixel size must be upsampled by a factor 2 or bigger with respect to the input map to prevent artifacts in the projection.

convolution_method{“wcs-tan”, “”}

Convolution method. If “wcs-tan”, project on WCS geometry and convolve with WCS kernel. See convolve_wcs. If “”, convolve map with a symmetrical WCS kernel. See convolve_full. Default is “wcs-tan”.

**kwargsdict

Keyword arguments passed to convolve.

Returns:

mapHpxNDMap

Convolved map.

convolve_full(kernel)

Convolve map with a symmetrical WCS kernel.

Extract the radial profile of the kernel (assuming radial symmetry) and convolve via smoothing. Since no projection is applied, this is suited for full-sky and large maps.

If the kernel is two-dimensional, it is applied to all image planes likewise. If the kernel is higher dimensional it must match the map in the number of dimensions and the corresponding kernel is selected for every image plane.

Parameters:

kernelPSFKernel

Convolution kernel. The pixel size must be upsampled by a factor 2 or bigger with respect to the input map to prevent artifacts in the projection.

Returns:

mapHpxNDMap

Convolved map.

convolve_wcs(kernel, **kwargs)

Convolve map with a WCS kernel.

Project the map into a WCS geometry, convolve with a WCS kernel and project back into the initial HEALPix geometry.

If the kernel is two-dimensional, it is applied to all image planes likewise. If the kernel is higher dimensional should either match the map in the number of dimensions or the map must be an image (no non-spatial axes). In that case, the corresponding kernel is selected and applied to every image plane or to the single input image respectively.

Parameters:

kernelPSFKernel

Convolution kernel. The pixel size must be upsampled by a factor 2 or bigger with respect to the input map to prevent artifacts in the projection.

**kwargsdict

Keyword arguments passed to convolve.

Returns:

mapHpxNDMap

Convolved map.

crop(crop_width)

Crop the spatial dimensions of the map.

Parameters:

crop_width{sequence, array_like, int}

Number of pixels cropped from the edges of each axis. Defined analogously to pad_with from numpy.pad.

Returns:

mapMap

Cropped map.

cutout(position, width, *args, **kwargs)

Create a cutout around a given position.

Parameters:

positionSkyCoord

Center position of the cutout region.

widthAngle or Quantity

Diameter of the circular cutout region.

Returns:

cutoutHpxNDMap

Cutout map.

downsample(factor, preserve_counts=True, axis_name=None)

Downsample the spatial dimension by a given factor.

Parameters:

factorint

Downsampling factor.

preserve_countsbool, optional

Preserve the integral over each bin. This should be set to True if the map is an integral quantity (e.g. counts) and False if the map is a differential quantity (e.g. intensity). Default is True.

axis_namestr, optional

Which axis to downsample. By default, spatial axes are downsampled. Default is None.

Returns:

mapMap

Downsampled map.

fill_by_idx(idx, weights=None)

Fill pixels at idx with given weights.

Parameters:

idxtuple

Tuple of pixel index arrays for each dimension of the map. Tuple should be ordered as (I_lon, I_lat, I_0, …, I_n) for WCS maps and (I_hpx, I_0, …, I_n) for HEALPix maps.

weightsndarray, optional

Weights vector. If None, weights are set to 1. Default is None.

classmethod from_hdu(hdu, hdu_bands=None, format=None, colname=None)

Make a HpxNDMap object from a FITS HDU.

Parameters:

hduBinTableHDU

The FITS HDU.

hdu_bandsBinTableHDU, optional

The BANDS table HDU. Default is None.

formatstr, optional

FITS convention. Default is None. If None the format is guessed. The following formats are supported:

• “gadf”

• “fgst-ccube”

• “fgst-ltcube”

• “fgst-bexpcube”

• “fgst-srcmap”

• “fgst-template”

• “fgst-srcmap-sparse”

• “galprop”

• “galprop2”

colnamestr, optional

Data column name to be used for the HEALPix map. Default is None.

Returns:

mapHpxMap

HEALPix map.

classmethod from_wcs_tiles(wcs_tiles, nest=True)

Create HEALPix map from WCS tiles.

Parameters:

wcs_tileslist of WcsNDMap

WCS map tiles.

nestbool, optional

Indexing scheme. If True, “NESTED” scheme. If False, “RING” scheme. Default is True.

Returns:

hpx_mapHpxNDMap

HEALPix map.

get_by_idx(idx)

Return map values at the given pixel indices.

Parameters:

idxtuple

Tuple of pixel index arrays for each dimension of the map. Tuple should be ordered as (I_lon, I_lat, I_0, …, I_n) for WCS maps and (I_hpx, I_0, …, I_n) for HEALPix maps.

Returns:

valsndarray

Array of pixel values. numpy.nan is used to flag coordinates outside the map.

interp_by_coord(coords, method='linear', fill_value=None)

Interpolate map values at the given map coordinates.

Parameters:

coordstuple or MapCoord

Coordinate arrays for each dimension of the map. Tuple should be ordered as (lon, lat, x_0, …, x_n) where x_i are coordinates for non-spatial dimensions of the map.

method{“linear”, “nearest”}

Method to interpolate data values. Default is “linear”.

fill_valuefloat, optional

The value to use for points outside the interpolation domain. If None, values outside the domain are extrapolated. Default is None.

Returns:

valsndarray

Interpolated pixel values.

interp_by_pix(pix, method=None, fill_value=None)

Interpolate map values at the given pixel coordinates.

plot(method='raster', ax=None, normalize=False, proj='AIT', oversample=2, width_pix=1000, **kwargs)

Quickplot method.

This will generate a visualization of the map by converting to a rasterized WCS image (method=’raster’) or drawing polygons for each pixel (method=’poly’).

Parameters:

method{‘raster’,’poly’}

Method for mapping HEALPix pixels to a two-dimensional image. Can be set to ‘raster’ (rasterization to cartesian image plane) or ‘poly’ (explicit polygons for each pixel). WARNING: The ‘poly’ method is much slower than ‘raster’ and only suitable for maps with less than ~10k pixels. Default is “raster”.

projstring, optional

Any valid WCS projection type. Default is “AIT”.

oversamplefloat, optional

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. Default is 2.

width_pixint, optional

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. Default is 1000.

**kwargsdict

Keyword arguments passed to imshow.

Returns:

axWCSAxes

WCS axes object.

plot_mask(method='raster', ax=None, proj='AIT', oversample=2, width_pix=1000, **kwargs)

Plot the mask as a shaded area.

Parameters:

method{‘raster’,’poly’}

Method for mapping HEALPix pixels to a two-dimensional image. Can be set to ‘raster’ (rasterization to cartesian image plane) or ‘poly’ (explicit polygons for each pixel). WARNING: The ‘poly’ method is much slower than ‘raster’ and only suitable for maps with less than ~10k pixels. Default is “raster”.

projstring, optional

Any valid WCS projection type. Default is “AIT”.

oversamplefloat, optional

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. Default is 2.

width_pixint, optional

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. Default is 1000.

**kwargsdict

Keyword arguments passed to imshow.

Returns:

axWCSAxes

WCS axis object.

sample_coord(n_events, random_state=0)

Sample position and energy of events.

Parameters:

n_eventsint

Number of events to sample.

random_state{int, ‘random-seed’, ‘global-rng’, RandomState}

Defines random number generator initialisation. Passed to get_random_state. Default is 0.

Returns:

coordsMapCoord object.

Sequence of coordinates and energies of the sampled events.

set_by_idx(idx, vals)

Set pixels at idx with given vals.

Parameters:

idxtuple

Tuple of pixel index arrays for each dimension of the map. Tuple should be ordered as (I_lon, I_lat, I_0, …, I_n) for WCS maps and (I_hpx, I_0, …, I_n) for HEALPix maps.

valsndarray

Values vector.

smooth(width, kernel='gauss')

Smooth the map.

Iterates over 2D image planes, processing one at a time.

Parameters:

widthQuantity, str or float

Smoothing width given as quantity or float. If a float is given it is interpreted as smoothing width in pixels. If an (angular) quantity is given it is converted to pixels using nside2resol. It corresponds to the standard deviation in case of a Gaussian kernel, and the radius in case of a disk kernel.

kernel{‘gauss’, ‘disk’}, optional

Kernel shape. Default is “gauss”.

Returns:

imageHpxNDMap

Smoothed image (a copy, the original object is unchanged).

stack(other, weights=None, nan_to_num=True)

Stack cutout into map.

Parameters:

otherHpxNDMap

Other map to stack.

weightsHpxNDMap, optional

Array to be used as weights. The spatial geometry must be equivalent to other and additional axes must be broadcastable. Default is None.

nan_to_num: bool, optional

Non-finite values are replaced by zero if True. Default is True.

to_nside(nside, preserve_counts=True)

Upsample or downsample the map to a given nside.

Parameters:

nsideint

HEALPix NSIDE parameter.

preserve_countsbool, optional

Preserve the integral over each bin. This should be true if the map is an integral quantity (e.g. counts) and false if the map is a differential quantity (e.g. intensity). Default is True.

Returns:

geomHpxNDMap

HEALPix map with new NSIDE.

to_region_nd_map(region, func=<function nansum>, weights=None, method='nearest')

Get region ND map in a given region.

By default, the whole map region is considered.

Parameters:

region: `~regions.Region` or `~astropy.coordinates.SkyCoord`

Region.

funcnumpy.func, optional

Function to reduce the data. Default is np.nansum. For boolean Map, use np.any or np.all.

weightsWcsNDMap, optional

Array to be used as weights. The geometry must be equivalent. Default is None.

method{“nearest”, “linear”}

How to interpolate if a position is given. Default is “neraest”.

Returns:

spectrumRegionNDMap

Spectrum in the given region.

to_swapped()

Return a new map with the opposite scheme (ring or nested).

Returns:

mapHpxMap

Map object.

to_wcs(sum_bands=False, normalize=True, proj='AIT', oversample=2, width_pix=None, hpx2wcs=None, fill_nan=True)

Make a WCS object and convert HEALPix data into WCS projection.

Parameters:

sum_bandsbool, optional

Sum over non-spatial axes before reprojecting. If False then the WCS map will have the same dimensionality as the HEALPix one. Default is False.

normalizebool, optional

Preserve integral by splitting HEALPix values between bins. Default is True.

projstr, optional

WCS-projection. Default is “AIT”.

oversamplefloat, optional

Oversampling factor for WCS map. This will be the approximate ratio of the width of a HEALPix pixel to a WCS pixel. If this parameter is None then the width will be set from width_pix. Default is 2.

width_pixint, optional

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. Default is None.

hpx2wcsHpxToWcsMapping, optional

Set the HEALPix to WCS mapping object that will be used to generate the WCS map. If None then a new mapping will be generated based on proj and oversample arguments. Default is None.

Returns:

map_outWcsMap

WCS map object.

to_wcs_tiles(nside_tiles=4, margin='0 deg', method='nearest', oversampling_factor=1)

Convert HpxNDMap to a list of WCS tiles.

Parameters:

nside_tilesint, optional

HEALPix NSIDE parameter for super pixel tiles. Default is 4.

marginAngle, optional

Width margin of the WCS tile. Default is “0 deg”.

method{‘nearest’, ‘linear’}

Interpolation method. Default is “nearest”.

oversampling_factorint, optional

Oversampling factor. Default is 1.

Returns:

wcs_tileslist of WcsNDMap

WCS tiles.

upsample(factor, order=0, preserve_counts=True, axis_name=None)

Upsample the spatial dimension by a given factor.

Parameters:

factorint

Upsampling factor.

orderint, optional

Order of the interpolation used for upsampling. Default is 0.

preserve_countsbool, optional

Preserve the integral over each bin. This should be true if the map is an integral quantity (e.g. counts) and false if the map is a differential quantity (e.g. intensity). Default is True.

axis_namestr, optional

Which axis to upsample. By default, spatial axes are upsampled. Default is None.

Returns:

mapMap

Upsampled map.

__init__(geom, data=None, dtype='float32', meta=None, unit='')

classmethod __new__(*args, **kwargs)