RegionGeom#

class gammapy.maps.RegionGeom(region, axes=None, wcs=None, binsz_wcs='0.1 deg')[source]#

Bases: Geom

Map geometry representing a region on the sky.

The spatial component of the geometry is made up of a single pixel with an arbitrary shape and size. It can also have any number of non-spatial dimensions. This class represents the geometry for the RegionNDMap maps.

Parameters:
regionSkyRegion

Region object.

axeslist of MapAxis

Non-spatial data axes.

wcsWCS

Optional WCS object to project the region if needed.

binsz_wcsQuantity

Angular bin size of the underlying WcsGeom used to evaluate quantities in the region. Default is “0.1 deg”. This default value is adequate for the majority of use cases. If a WCS object is provided, the input of binsz_wcs is overridden.

Attributes Summary

as_energy_true

If the geom contains an axis named 'energy' rename it to 'energy_true'.

axes

List of non-spatial axes.

axes_names

All axes names.

binsz_wcs

Angular bin size of the underlying WcsGeom.

center_coord

Center coordinate of the region as a astropy.coordinates.SkyCoord.

center_pix

Pixel values corresponding to the center of the region.

center_skydir

Sky coordinate of the center of the region.

data_shape

Shape of the ndarray matching this geometry.

data_shape_axes

Shape of data of the non-spatial axes and unit spatial axes.

frame

Coordinate system, either Galactic ("galactic") or Equatorial ("icrs").

has_energy_axis

Whether geom has an energy axis (either 'energy' or 'energy_true').

is_all_point_sky_regions

Whether regions are all point regions.

is_allsky

is_flat

Whether the geom non-spatial axes have length 1, equivalent to an image.

is_hpx

is_image

Whether the geom is an image without extra dimensions.

is_region

is_regular

npix

Number of spatial pixels.

projection

region

The spatial component of the region geometry as a SkyRegion.

wcs

WCS projection object.

width

Width of bounding box of the region.

Methods Summary

bin_volume()

If the RegionGeom has a non-spatial axis, it returns the volume of the region.

contains(coords)

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

contains_pix(pix)

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

contains_wcs_pix(pix)

Check if a given WCS pixel coordinate is contained in the region.

coord_to_idx(coords[, clip])

Convert map coordinates to pixel indices.

coord_to_pix(coords)

Convert map coordinates to pixel coordinates.

copy(**kwargs)

Copy and overwrite given attributes.

create(region, **kwargs)

Create region geometry.

crop()

Crop the geometry at the edges.

data_nbytes([dtype])

Estimate memory usage in megabytes of the Numpy data array matching this geometry depending on the given type.

downsample(factor, axis_name)

Downsample a non-spatial dimension of the region by a given factor.

drop(axis_name)

Drop an axis from the geom.

energy_mask([energy_min, energy_max, ...])

Create a mask for a given energy range.

from_hdulist(hdulist[, format, hdu])

Read region table and convert it to region list.

from_regions(regions, **kwargs)

Create region geometry from list of regions.

get_coord([mode, frame, sparse, axis_name])

Get map coordinates from the geometry.

get_idx()

Get tuple of pixel indices for this geometry.

get_wcs_coord_and_weights([factor])

Get the array of spatial coordinates and corresponding weights.

is_allclose(other[, rtol_axes, atol_axes])

Compare two data IRFs for equivalency.

pad(pad_width, axis_name)

Pad the geometry at the edges.

pix_to_coord(pix)

Convert pixel coordinates to map coordinates.

pix_to_idx(pix[, clip])

Convert pixel coordinates to pixel indices.

plot_region([ax, kwargs_point, path_effect])

Plot region in the sky.

rename_axes(names, new_names)

Rename axes contained in the geometry.

replace_axis(axis)

Replace axis with a new one.

resample_axis(axis)

Resample geom to a new axis binning.

separation(position)

Angular distance between the center of the region and the given position.

slice_by_idx(slices)

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

solid_angle()

Get solid angle of the region.

squash(axis_name)

Squash geom axis.

to_bands_hdu([hdu_bands, format])

to_binsz(binsz)

Return self.

to_binsz_wcs(binsz)

Change the bin size of the underlying WCS geometry.

to_cube(axes)

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

to_hdulist([format, hdu_bands, hdu_region])

Convert geometry to HDU list.

to_image()

Remove non-spatial axes to create a 2D region.

to_wcs_geom([width_min])

Get the minimal equivalent geometry which contains the region.

union(other)

Stack a RegionGeom by making the union.

upsample(factor[, axis_name])

Upsample a non-spatial dimension of the region by a given factor.

Attributes Documentation

as_energy_true#

If the geom contains an axis named ‘energy’ rename it to ‘energy_true’.

axes#

List of non-spatial axes.

axes_names#

All axes names.

binsz_wcs#

Angular bin size of the underlying WcsGeom.

Returns:
binsz_wcs: Angle

Angular bin size.

center_coord#

Center coordinate of the region as a astropy.coordinates.SkyCoord.

center_pix#

Pixel values corresponding to the center of the region.

center_skydir#

Sky coordinate of the center of the region.

data_shape#

Shape of the ndarray matching this geometry.

data_shape_axes#

Shape of data of the non-spatial axes and unit spatial axes.

frame#

Coordinate system, either Galactic (“galactic”) or Equatorial (“icrs”).

has_energy_axis#

Whether geom has an energy axis (either ‘energy’ or ‘energy_true’).

is_all_point_sky_regions#

Whether regions are all point regions.

is_allsky = False#
is_flat#

Whether the geom non-spatial axes have length 1, equivalent to an image.

is_hpx = False#
is_image#

Whether the geom is an image without extra dimensions.

is_region = True#
is_regular = True#
npix#

Number of spatial pixels.

projection = 'TAN'#
region#

The spatial component of the region geometry as a SkyRegion.

wcs#

WCS projection object.

width#

Width of bounding box of the region.

Returns:
widthQuantity

Dimensions of the region in both spatial dimensions. Units: deg

Methods Documentation

bin_volume()[source]#

If the RegionGeom has a non-spatial axis, it returns the volume of the region. If not, it returns the solid angle size.

Returns:
volumeQuantity

Volume of the region.

contains(coords)[source]#

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

Requires the region attribute to be set. For PointSkyRegion the method always returns True.

Parameters:
coordstuple, dict, MapCoord or SkyCoord

Object containing coordinate arrays we wish to check for inclusion in the region.

Returns:
maskndarray

Boolean array with the same shape as the input that indicates which coordinates are inside the region.

contains_pix(pix)#

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

Parameters:
pixtuple

Tuple of pixel coordinates.

Returns:
containmentndarray

Bool array.

contains_wcs_pix(pix)[source]#

Check if a given WCS pixel coordinate is contained in the region.

For PointSkyRegion the method always returns True.

Parameters:
pixtuple

Tuple of pixel coordinates.

Returns:
containmentndarray

Boolean array.

coord_to_idx(coords, clip=False)#

Convert map coordinates to pixel indices.

Parameters:
coordstuple 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.

clipbool

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

Returns:
pixtuple

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

coord_to_pix(coords)[source]#

Convert map coordinates to pixel coordinates.

Parameters:
coordstuple

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

Tuple of pixel coordinates in image and band dimensions.

copy(**kwargs)#

Copy and overwrite given attributes.

Parameters:
**kwargsdict

Keyword arguments to overwrite in the map geometry constructor.

Returns:
copyGeom

Copied map geometry.

classmethod create(region, **kwargs)[source]#

Create region geometry.

The input region can be passed in the form of a ds9 string and will be parsed internally by parse. See:

Parameters:
regionstr or SkyRegion

Region definition.

**kwargsdict

Keyword arguments passed to RegionGeom.__init__.

Returns:
geomRegionGeom

Region geometry.

crop()[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:
geomGeom

Cropped geometry.

data_nbytes(dtype='float32')#

Estimate memory usage in megabytes of the Numpy data array matching this geometry depending on the given type.

Parameters:
dtypestr, optional

The desired data-type for the array. Default is “float32”.

Returns:
memoryQuantity

Estimated memory usage in megabytes (MB).

downsample(factor, axis_name)[source]#

Downsample a non-spatial dimension of the region by a given factor.

Returns:
regionRegionGeom

Region geometry with the downsampled axis.

drop(axis_name)#

Drop an axis from the geom.

Parameters:
axis_namestr

Name of the axis to remove.

Returns:
geomGeom

New geom with the axis removed.

energy_mask(energy_min=None, energy_max=None, round_to_edge=False)#

Create a mask for a given energy range.

The energy bin must be fully contained to be included in the mask.

Parameters:
energy_min, energy_maxQuantity

Energy range.

Returns:
maskMap

Map containing the energy mask. The geometry of the map is the same as the geometry of the instance which called this method.

classmethod from_hdulist(hdulist, format='ogip', hdu=None)[source]#

Read region table and convert it to region list.

Parameters:
hdulistHDUList

HDU list.

format{“ogip”, “ogip-arf”, “gadf”}

HDU format. Default is “ogip”.

hdustr, optional

Name of the HDU. Default is None.

Returns:
geomRegionGeom

Region map geometry.

classmethod from_regions(regions, **kwargs)[source]#

Create region geometry from list of regions.

The regions are combined with union to a compound region.

Parameters:
regionslist of SkyRegion or str

Regions.

**kwargs: dict

Keyword arguments forwarded to RegionGeom.

Returns:
geomRegionGeom

Region map geometry.

get_coord(mode='center', frame=None, sparse=False, axis_name=None)[source]#

Get map coordinates from the geometry.

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

Get center or edge coordinates for the non-spatial axes. Default is “center”.

framestr or Frame, optional

Coordinate frame. Default is None.

sparsebool, optional

Compute sparse coordinates. Default is False.

axis_namestr, optional

If mode = “edges”, the edges will be returned for this axis only. Default is None.

Returns:
coordMapCoord

Map coordinate object.

get_idx()[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:
idxtuple, 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. Default is None.

localbool, optional

Flag to return local or global pixel indices. Local indices run from 0 to the number of pixels in a given image plane. Default is False.

flatbool, optional

Return a flattened array containing only indices for pixels contained in the geometry. Default is False.

Returns:
idxtuple

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

get_wcs_coord_and_weights(factor=10)[source]#

Get the array of spatial coordinates and corresponding weights.

The coordinates are the center of a pixel that intersects the region and the weights that represent which fraction of the pixel is contained in the region.

Parameters:
factorint, optional

Oversampling factor to compute the weights. Default is 10.

Returns:
region_coordMapCoord

MapCoord object with the coordinates inside the region.

weightsndarray

Weights representing the fraction of each pixel contained in the region.

is_allclose(other, rtol_axes=1e-06, atol_axes=1e-06)[source]#

Compare two data IRFs for equivalency.

Parameters:
otherRegionGeom

Region geometry to compare against.

rtol_axesfloat, optional

Relative tolerance for the axes comparison. Default is 1e-6.

atol_axesfloat, optional

Relative tolerance for the axes comparison. Default is 1e-6.

Returns:
is_allclosebool

Whether the geometry is all close.

pad(pad_width, axis_name)#

Pad the geometry at the edges.

Parameters:
pad_width{sequence, array_like, int}

Number of values padded to the edges of each axis.

axis_namestr

Name of the axis to pad.

Returns:
geomGeom

Padded geometry.

pix_to_coord(pix)[source]#

Convert pixel coordinates to map coordinates.

Parameters:
pixtuple

Tuple of pixel coordinates.

Returns:
coordstuple

Tuple of map coordinates.

pix_to_idx(pix, clip=False)[source]#

Convert pixel coordinates to pixel indices.

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

Parameters:
pixtuple

Tuple of pixel coordinates.

clipbool

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

Returns:
idxtuple

Tuple of pixel indices.

plot_region(ax=None, kwargs_point=None, path_effect=None, **kwargs)[source]#

Plot region in the sky.

Parameters:
axWCSAxes, optional

Axes to plot on. If no axes are given, the region is shown using the minimal equivalent WCS geometry. Default is None.

kwargs_pointdict, optional

Keyword arguments passed to Line2D for plotting of point sources. Default is None.

path_effectPathEffect, optional

Path effect applied to artists and lines. Default is None.

**kwargsdict

Keyword arguments forwarded to as_artist.

Returns:
axWCSAxes

Axes to plot on.

rename_axes(names, new_names)#

Rename axes contained in the geometry.

Parameters:
nameslist or str

Names of the axes.

new_nameslist or str

New names of the axes. The list must be of same length than names.

Returns:
geomGeom

Renamed geometry.

replace_axis(axis)#

Replace axis with a new one.

Parameters:
axisMapAxis

New map axis.

Returns:
mapGeom

Geom with replaced axis.

resample_axis(axis)#

Resample geom to a new axis binning.

This method groups the existing bins into a new binning.

Parameters:
axisMapAxis

New map axis.

Returns:
mapGeom

Geom with resampled axis.

separation(position)[source]#

Angular distance between the center of the region and the given position.

Parameters:
positionastropy.coordinates.SkyCoord

Sky coordinate we want the angular distance to.

Returns:
sepAngle

The on-sky separation between the given coordinate and the region center.

slice_by_idx(slices)#

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

Parameters:
slicesdict

Dictionary of axes names and integers or slice object pairs. Contains one element for each non-spatial dimension. For integer indexing the corresponding axes is dropped from the map. Axes not specified in the dict are kept unchanged.

Returns:
geomGeom

Sliced geometry.

Examples

>>> from gammapy.maps import MapAxis, WcsGeom
>>> import astropy.units as u
>>> energy_axis = MapAxis.from_energy_bounds(1*u.TeV, 3*u.TeV, 6)
>>> geom = WcsGeom.create(skydir=(83.63, 22.01), axes=[energy_axis], width=5, binsz=0.02)
>>> slices = {"energy": slice(0, 2)}
>>> sliced_geom = geom.slice_by_idx(slices)
solid_angle()[source]#

Get solid angle of the region.

Returns:
angleQuantity

Solid angle of the region in steradians. Units: sr

squash(axis_name)#

Squash geom axis.

Parameters:
axis_namestr

Axis to squash.

Returns:
geomGeom

Geom with squashed axis.

to_bands_hdu(hdu_bands=None, format='gadf')#
to_binsz(binsz)[source]#

Return self.

to_binsz_wcs(binsz)[source]#

Change the bin size of the underlying WCS geometry.

Parameters:
binszfloat, str or Quantity

Bin size.

Returns:
regionRegionGeom

Region geometry with the same axes and region as the input, but different WCS pixelization.

to_cube(axes)[source]#

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

Returns:
regionRegionGeom

Region geometry with the added axes.

to_hdulist(format='ogip', hdu_bands=None, hdu_region=None)[source]#

Convert geometry to HDU list.

Parameters:
format{“ogip”, “gadf”, “ogip-sherpa”}

HDU format. Default is “ogip”.

hdu_bandsstr, optional

Name or index of the HDU with the BANDS table. Default is None.

hdu_regionstr, optional

Name or index of the HDU with the region table. Not used for the “gadf” format. Default is None.

Returns:
hdulistHDUList

HDU list.

to_image()[source]#

Remove non-spatial axes to create a 2D region.

Returns:
regionRegionGeom

Region geometry without any non-spatial axes.

to_wcs_geom(width_min=None)[source]#

Get the minimal equivalent geometry which contains the region.

Parameters:
width_minQuantity, optional

Minimum width for the resulting geometry. Can be a single number or two, for different minimum widths in each spatial dimension. Default is None.

Returns:
wcs_geomWcsGeom

A WCS geometry object.

union(other)[source]#

Stack a RegionGeom by making the union.

upsample(factor, axis_name=None)[source]#

Upsample a non-spatial dimension of the region by a given factor.

Returns:
regionRegionGeom

Region geometry with the upsampled axis.