WcsGeom

class gammapy.maps.WcsGeom(wcs, npix, cdelt=None, crpix=None, axes=None)[source]

Bases: gammapy.maps.Geom

Geometry class for WCS maps.

This class encapsulates both the WCS transformation object and the the image extent (number of pixels in each dimension). Provides methods for accessing the properties of the WCS object and performing transformations between pixel and world coordinates.

Parameters:
wcs : WCS

WCS projection object

npix : tuple

Number of pixels in each spatial dimension

cdelt : tuple

Pixel size in each image plane. If none then a constant pixel size will be used.

crpix : tuple

Reference pixel coordinate in each image plane.

axes : list

Axes for non-spatial dimensions

Attributes Summary

axes List of non-spatial axes.
bin_volume(self) Bin volume (Quantity)
center_coord Map coordinate of the center of the geometry.
center_pix Pixel coordinate of the center of the geometry.
center_skydir Sky coordinate of the center of the geometry.
coordsys Coordinate system of the projection.
data_shape Shape of the Numpy data array matching this geometry.
get_coord(self[, idx, flat, mode, coordsys]) Get map coordinates from the geometry.
get_idx(self[, idx, flat])
get_pix(self[, idx, mode]) Get map pix coordinates from the geometry.
is_allsky Flag for all-sky maps.
is_hpx
is_image Whether the geom is equivalent to an image without extra dimensions.
is_regular Is this geometry is regular in non-spatial dimensions (bool)?
ndim
npix Tuple with image dimension in pixels in longitude and latitude.
pixel_area Pixel area in deg^2.
pixel_scales Pixel scale.
projection Map projection.
shape_axes Shape of non-spatial axes.
solid_angle(self) Solid angle array (Quantity in sr).
to_image(self)
wcs WCS projection object.
width Tuple with image dimension in deg in longitude and latitude.

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([npix, binsz, proj, coordsys, …]) Create a WCS geometry object.
crop(self, crop_width) Crop the geometry at the edges.
cutout(self, position, width[, mode]) Create a cutout around a given position.
downsample(self, factor[, axis]) 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_hdulist(hdulist[, hdu, hdu_bands]) Load a geometry object from a FITS HDUList.
from_header(header[, hdu_bands]) Create a WCS geometry 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_image_shape(self, idx) Get the shape of the image plane at index idx.
make_bands_hdu(self[, hdu, hdu_skymap, conv])
make_header(self)
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.
region_mask(self, regions[, inside]) Create a mask from a given list of regions
separation(self, center) Compute sky separation wrt a given center.
slice_by_idx(self, slices) Create a new geometry by slicing the non-spatial axes.
to_binsz(self, binsz) Change pixel size of the geometry
to_cube(self, axes) Append non-spatial axes to create a higher-dimensional geometry.
upsample(self, factor[, axis]) Upsample the spatial dimension of the geometry by a given factor.

Attributes Documentation

axes

List of non-spatial axes.

bin_volume(self)[source]

Bin volume (Quantity)

center_coord

Map coordinate of the center of the geometry.

Returns:
coord : tuple
center_pix

Pixel coordinate of the center of the geometry.

Returns:
pix : tuple
center_skydir

Sky coordinate of the center of the geometry.

Returns:
pix : SkyCoord
coordsys

Coordinate system of the projection.

Galactic (‘GAL’) or Equatorial (‘CEL’).

data_shape

Shape of the Numpy data array matching this geometry.

get_coord(self, idx=None, flat=False, mode='center', coordsys=None)[source]

Get map coordinates from the geometry.

Parameters:
mode : {‘center’, ‘edges’}

Get center or edge coordinates for the spatial axes.

Returns:
coord : MapCoord

Map coordinate object.

get_idx(self, idx=None, flat=False)[source]
get_pix(self, idx=None, mode='center')[source]

Get map pix coordinates from the geometry.

Parameters:
mode : {‘center’, ‘edges’}

Get center or edge pix coordinates for the spatial axes.

Returns:
coord : tuple

Map pix coordinate tuple.

is_allsky

Flag for all-sky maps.

is_hpx = False
is_image

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

is_regular

Is this geometry is regular in non-spatial dimensions (bool)?

  • False for multi-resolution or irregular geometries.
  • True if all image planes have the same pixel geometry.
ndim
npix

Tuple with image dimension in pixels in longitude and latitude.

pixel_area

Pixel area in deg^2.

pixel_scales

Pixel scale.

Returns angles along each axis of the image at the CRPIX location once it is projected onto the plane of intermediate world coordinates.

Returns:
angle: Angle
projection

Map projection.

shape_axes

Shape of non-spatial axes.

solid_angle(self)[source]

Solid angle array (Quantity in sr).

The array has the same dimension as the WcsGeom object.

To return solid angles for the spatial dimensions only use:

WcsGeom.to_image().solid_angle()
to_image(self)[source]
wcs

WCS projection object.

width

Tuple with image dimension in deg in longitude and latitude.

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(npix=None, binsz=0.5, proj='CAR', coordsys='CEL', refpix=None, axes=None, skydir=None, width=None)[source]

Create a WCS geometry object.

Pixelization of the map is set with binsz and one of either npix or width arguments. For maps with non-spatial dimensions a different pixelization can be used for each image plane by passing a list or array argument for any of the pixelization parameters. If both npix and width are None then an all-sky geometry will be created.

Parameters:
npix : int or tuple or list

Width of the map in pixels. A tuple will be interpreted as parameters for longitude and latitude axes. For maps with non-spatial dimensions, list input can be used to define a different map width in each image plane. This option supersedes width.

width : float or tuple or list

Width of the map in degrees. A tuple will be interpreted as parameters for longitude and latitude axes. For maps with non-spatial dimensions, list input can be used to define a different map width in each image plane.

binsz : float or tuple or list

Map pixel size in degrees. A tuple will be interpreted as parameters for longitude and latitude axes. For maps with non-spatial dimensions, list input can be used to define a different bin size in each image plane.

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.

coordsys : {‘CEL’, ‘GAL’}, optional

Coordinate system, either Galactic (‘GAL’) or Equatorial (‘CEL’).

axes : list

List of non-spatial axes.

proj : string, optional

Any valid WCS projection type. Default is ‘CAR’ (cartesian).

refpix : tuple

Reference pixel of the projection. If None this will be set to the center of the map.

Returns:
geom : WcsGeom

A WCS geometry object.

Examples

>>> from gammapy.maps import WcsGeom
>>> from gammapy.maps import MapAxis
>>> axis = MapAxis.from_bounds(0,1,2)
>>> geom = WcsGeom.create(npix=(100,100), binsz=0.1)
>>> geom = WcsGeom.create(npix=[100,200], binsz=[0.1,0.05], axes=[axis])
>>> geom = WcsGeom.create(width=[5.0,8.0], binsz=[0.1,0.05], axes=[axis])
>>> geom = WcsGeom.create(npix=([100,200],[100,200]), binsz=0.1, 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.

cutout(self, position, width, mode='trim')[source]

Create a cutout around a given position.

Parameters:
position : SkyCoord

Center position of the cutout region.

width : tuple of Angle

Angular sizes of the region in (lon, lat) in that specific order. If only one value is passed, a square region is extracted.

mode : {‘trim’, ‘partial’, ‘strict’}

Mode option for Cutout2D, for details see Cutout2D.

Returns:
cutout : WcsNDMap

Cutout map

downsample(self, factor, axis=None)[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_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)[source]

Create a WCS geometry object from a FITS header.

Parameters:
header : Header

The FITS header

hdu_bands : BinTableHDU

The BANDS table HDU.

Returns:
wcs : WcsGeom

WCS geometry object.

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_image_shape(self, idx)[source]

Get the shape of the image plane at index idx.

make_bands_hdu(self, hdu=None, hdu_skymap=None, conv=None)
make_header(self)[source]
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.

region_mask(self, regions, inside=True)[source]

Create a mask from a given list of regions

Parameters:
regions : list of Region

Python list of regions (pixel or sky regions accepted)

inside : bool

For inside=True, pixels in the region to True (the default). For inside=False, pixels in the region are False.

Returns:
mask_map : ndarray of boolean type

Boolean region mask

Examples

Make an exclusion mask for a circular region:

from regions import CircleSkyRegion
from astropy.coordinates import SkyCoord, Angle
from gammapy.maps import WcsNDMap, WcsGeom

pos = SkyCoord(0, 0, unit='deg')
geom = WcsGeom.create(skydir=pos, npix=100, binsz=0.1)

region = CircleSkyRegion(
    SkyCoord(3, 2, unit='deg'),
    Angle(1, 'deg'),
)
mask = geom.region_mask([region], inside=False)

Note how we made a list with a single region, since this method expects a list of regions.

The return mask is a boolean Numpy array. If you want a map object (e.g. for storing in FITS or plotting), this is how you can make the map:

mask_map = WcsNDMap(geom=geom, data=mask)
mask_map.plot()
separation(self, center)[source]

Compute sky separation wrt a given center.

Parameters:
center : SkyCoord

Center position

Returns:
separation : Angle

Separation angle array (2D)

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.

to_binsz(self, binsz)[source]

Change pixel size of the geometry

Parameters:
binsz : float or tuple or list

New pixel size in degree.

Returns:
geom : WcsGeom

Geometry with new pixel size.

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.

upsample(self, factor, axis=None)[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.