SkyCube

class gammapy.cube.SkyCube(name=None, data=None, wcs=None, energy_axis=None, meta=None)[source]

Bases: gammapy.image.core.MapBase

Sky cube with dimensions lon, lat and energy.

Note

There is a very nice SkyCube implementation here: http://spectral-cube.readthedocs.io/en/latest/index.html

Here is some discussion if / how it could be used: https://github.com/radio-astro-tools/spectral-cube/issues/110

For now we re-implement what we need here.

The order of the sky cube axes is defined as following:

  • The data array axis order is (energy, lat, lon).
  • The wcs object is a two dimensional celestial WCS with axis order (lon, lat).
Parameters:

name : str

Name of the cube.

data : ndarray

Data array.

wcs : WCS

WCS transformation object.

energy_axis : LogEnergyAxis

Energy axis object, defining the energy transformation.

meta : OrderedDict

Dictionary to store meta data.

Attributes Summary

sky_image_ref Empty reference SkyImage.

Methods Summary

assert_allclose(cube1, cube2)
convolve(kernels, **kwargs) Convolve cube with a given set of kernels.
cutout(position, size) Cut out rectangular piece of a cube.
empty([emin, emax, enumbins, eunit, mode]) Create empty sky cube with log equal energy binning from the scratch.
empty_like(reference[, energies, unit, fill]) Create an empty sky cube with a given WCS and energy specification.
energies([mode]) Energy coordinate vector.
fill_events(events[, weights]) Fill events (modifies data attribute).
info() Print summary info about the cube.
lookup(position, energy[, interpolation]) Lookup value in the cube at given sky position and energy.
plot_rgb([ax, fig]) Plot sky cube as RGB image.
read(filename[, format]) Read sky cube from FITS file.
read_hdu(hdu_list) Read sky cube from HDU list.
region_mask(region) Create a boolean cube mask for a region.
reproject(reference[, mode]) Reproject spatial dimensions onto a reference image.
show([viewer, ds9options]) Show sky cube in image viewer.
sky_image(energy[, interpolation]) Slice a 2-dim SkyImage from the cube at a given energy.
sky_image_idx(idx) Slice a 2-dim SkyImage from the cube at a given index.
sky_image_integral(emin, emax[, nbins, ...]) Integrate cube along the energy axes using the log-log trapezoidal rule.
spectrum(region) Extract spectrum in a given sky region.
to_fits(format) Write to FITS HDU list.
to_images() Convert to SkyCubeImages.
to_sherpa_data3d([dstype]) Convert sky cube to sherpa Data3D or Data3DInt object.
wcs_pixel_to_skycoord(x, y, z) Convert pixel to world coordinates.
wcs_skycoord_to_pixel(position, energy) Convert world to pixel coordinates.
write(filename[, format]) Write to FITS file.

Attributes Documentation

sky_image_ref

Empty reference SkyImage.

Examples

Can be used to access the spatial information of the cube:

>>> from gammapy.cube import SkyCube
>>> cube = SkyCube.empty()
>>> coords = cube.sky_image_ref.coordinates()
>>> solid_angle = cube.sky_image_ref.solid_angle()

Methods Documentation

static assert_allclose(cube1, cube2)[source]
convolve(kernels, **kwargs)[source]

Convolve cube with a given set of kernels.

Parameters:

kernels : list or ndarray

List of 2D convolution kernels or 3D array. The energy axis must correspond to array axis=0.

Returns:

convolved : SkyCube

Convolved cube.

cutout(position, size)[source]

Cut out rectangular piece of a cube.

See cutout() for details.

classmethod empty(emin=0.5, emax=100, enumbins=10, eunit='TeV', mode='edges', **kwargs)[source]

Create empty sky cube with log equal energy binning from the scratch.

Parameters:

emin : float

Minimum energy.

emax : float

Maximum energy.

enumbins : int

Number of energy bins.

eunit : str

Energy unit.

mode : {‘edges’, ‘center’}

Whether emin and emax denote the bin centers or edges.

kwargs : dict

Keyword arguments passed to empty to create the spatial part of the cube.

Returns:

empty_cube : SkyCube

Empty sky cube object.

Examples

Create an empty sky cube:

from gammapy.cube import SkyCube
cube = SkyCube.empty(nxpix=11, nypix=7, enumbins=3, mode='center',
                emin=1, emax=100, eunit='TeV')
classmethod empty_like(reference, energies=None, unit='', fill=0)[source]

Create an empty sky cube with a given WCS and energy specification.

Parameters:

reference : SkyCube or SkyImage

Reference sky cube or image.

energies : Energy or EnergyBounds (optional)

Reference energies, mandatory when a SkyImage is passed.

unit : str

String specifying the data units.

fill : float

Value to fill the data array with.

Returns:

empty_cube : SkyCube

Empty sky cube object.

Examples

Create an empty sky cube from an image and energy center specification:

from astropy import units as u
from gammapy.image import SkyImage
from gammapy.cube import SkyCube
from gammapy.utils.energy import Energy, EnergyBounds

# define reference image
image = SkyImage.empty(nxpix=11, nypix=7)

# define energy binning centers
energies = Energy.equal_log_spacing(1 * u.TeV, 100 * u.TeV, 3)
cube = SkyCube.empty_like(reference=image, energies=energies)

# define energy binning bounds
energies = EnergyBounds.equal_log_spacing(1 * u.TeV, 100 * u.TeV, 3)
cube = SkyCube.empty_like(reference=image, energies=energies)
energies(mode='center')[source]

Energy coordinate vector.

Parameters:

mode : {‘center’, ‘edges’}

Return coordinate values at the pixels edges or pixel centers.

Returns:

coordinates : Quantity

Energy

fill_events(events, weights=None)[source]

Fill events (modifies data attribute).

Parameters:

events : EventList

Event list

weights : str, optional

Column to use as weights (none by default)

info()[source]

Print summary info about the cube.

lookup(position, energy, interpolation=None)[source]

Lookup value in the cube at given sky position and energy.

Parameters:

position : SkyCoord

Position on the sky.

energy : Quantity

Energy

interpolation : {None, ‘linear’, ‘nearest’}

Interpolate data values between energies.

Returns:

value : Quantity

Value at the given sky position and energy.

plot_rgb(ax=None, fig=None, **kwargs)[source]

Plot sky cube as RGB image.

Parameters:

ax : WCSAxes, optional

WCS axis object to plot on.

fig : Figure, optional

Figure

Returns:

ax : WCSAxes

WCS axis object

classmethod read(filename, format='fermi-counts')[source]

Read sky cube from FITS file.

Parameters:

filename : str

File name

format : {‘fermi-counts’, ‘fermi-background’, ‘fermi-exposure’}

Fits file format.

Returns:

sky_cube : SkyCube

Sky cube

classmethod read_hdu(hdu_list)[source]

Read sky cube from HDU list.

Parameters:

object_hdu : ImageHDU

Image HDU object to be read

energy_table_hdu : TableHDU

Table HDU object giving energies of each slice of the Image HDU object_hdu

Returns:

sky_cube : SkyCube

Sky cube

region_mask(region)[source]

Create a boolean cube mask for a region.

The mask is:

  • True for pixels inside the region
  • False for pixels outside the region
Parameters:

region : PixelRegion or SkyRegion

Region in pixel or sky coordinates.

Returns:

mask : SkyCube

A boolean sky cube mask.

reproject(reference, mode='interp', *args, **kwargs)[source]

Reproject spatial dimensions onto a reference image.

Parameters:

reference : Header, SkyImage or SkyCube

Reference wcs specification to reproject the data on.

mode : {‘interp’, ‘exact’}

Interpolation mode.

*args : list

Arguments passed to reproject_interp or reproject_exact.

**kwargs : dict

Keyword arguments passed to reproject_interp or reproject_exact.

Returns:

reprojected_cube : SkyCube

Cube spatially reprojected to the reference.

show(viewer='mpl', ds9options=None, **kwargs)[source]

Show sky cube in image viewer.

Parameters:

viewer : {‘mpl’, ‘ds9’}

Which image viewer to use. Option ‘ds9’ requires ds9 to be installed.

ds9options : list, optional

List of options passed to ds9. E.g. [‘-cmap’, ‘heat’, ‘-scale’, ‘log’]. Any valid ds9 command line option can be passed. See http://ds9.si.edu/doc/ref/command.html for details.

**kwargs : dict

Keyword arguments passed to matplotlib.pyplot.imshow.

sky_image(energy, interpolation=None)[source]

Slice a 2-dim SkyImage from the cube at a given energy.

Parameters:

energy : Quantity

Energy value

interpolation : {None, ‘linear’, ‘nearest’}

Interpolate data values between energies. None corresponds to ‘nearest’, but might have advantages in performance, because no interpolator is set up.

Returns:

image : SkyImage

2-dim sky image

sky_image_idx(idx)[source]

Slice a 2-dim SkyImage from the cube at a given index.

Parameters:

idx : int

Index of the sky image.

Returns:

image : SkyImage

2-dim sky image

sky_image_integral(emin, emax, nbins=10, per_decade=False, interpolation='linear')[source]

Integrate cube along the energy axes using the log-log trapezoidal rule.

Parameters:

emin : Quantity

Integration range minimum.

emax : Quantity

Integration range maximum.

nbins : int, optional

Number of grid points used for the integration.

per_decade : bool

Whether nbins is per decade.

interpolation : {None, ‘linear’, ‘nearest’}

Interpolate data values between energies.

Returns:

image : SkyImage

Integral image.

spectrum(region)[source]

Extract spectrum in a given sky region.

Parameters:

region : SkyRegion

Sky region to extract the spectrum from.

Returns:

spectrum : Table

Summed spectrum of pixels in the mask.

to_fits(format)[source]

Write to FITS HDU list.

Parameters:

format : {‘fermi-counts’, ‘fermi-background’, ‘fermi-exposure’}

Fits file format.

Returns:

hdu_list : HDUList

to_images()[source]

Convert to SkyCubeImages.

to_sherpa_data3d(dstype='Data3D')[source]

Convert sky cube to sherpa Data3D or Data3DInt object.

Parameters:

dstype : {‘Data3D’, ‘Data3DInt’}

Sherpa data type.

wcs_pixel_to_skycoord(x, y, z)[source]

Convert pixel to world coordinates.

Parameters:

x : ndarry

x coordinate array

y : ndarry

y coordinate array

z : ndarry

z coordinate array

Returns:

(position, energy) : tuple

Tuple of (SkyCoord, Quantity).

wcs_skycoord_to_pixel(position, energy)[source]

Convert world to pixel coordinates.

Parameters:

position : SkyCoord

Position on the sky.

energy : Quantity

Energy

Returns:

(x, y, z) : tuple

Tuple of x, y, z coordinates.

write(filename, format='fermi-counts', **kwargs)[source]

Write to FITS file.

Parameters:

filename : str

Filename

format : {‘fermi-counts’, ‘fermi-background’, ‘fermi-exposure’}

Fits file format.