MapAxis#

class gammapy.maps.MapAxis(nodes, interp='lin', name='', node_type='edges', unit='')[source]#

Bases: object

Class representing an axis of a map.

Provides methods for transforming to/from axis and pixel coordinates. An axis is defined by a sequence of node values that lie at the center of each bin. The pixel coordinate at each node is equal to its index in the node array (0, 1, ..). Bin edges are offset by 0.5 in pixel coordinates from the nodes such that the lower/upper edge of the first bin is (-0.5,0.5).

Parameters
nodesndarray or Quantity

Array of node values. These will be interpreted as either bin edges or centers according to node_type.

interpstr

Interpolation method used to transform between axis and pixel coordinates. Valid options are ‘log’, ‘lin’, and ‘sqrt’.

namestr

Axis name

node_typestr

Flag indicating whether coordinate nodes correspond to pixel edges (node_type = ‘edges’) or pixel centers (node_type = ‘center’). ‘center’ should be used where the map values are defined at a specific coordinate (e.g. differential quantities). ‘edges’ should be used where map values are defined by an integral over coordinate intervals (e.g. a counts histogram).

unitstr

String specifying the data units.

Attributes Summary

append

Deprecated since version 1.1.

as_plot_center

Plot center

as_plot_edges

Plot edges

as_plot_labels

Return list of axis plot labels

as_plot_scale

Plot axis scale

as_plot_xerr

Return tuple of xerr to be used with plt.errorbar()

bin_width

Array of bin widths.

bounds

Bounds of the axis (~astropy.units.Quantity)

center

Return array of bin centers.

edges

Return array of bin edges.

edges_max

Return array of bin edges min values.

edges_min

Return array of bin edges max values.

interp

Interpolation scale of the axis.

is_energy_axis

iter_by_edges

Iterate by intervals defined by the edges

name

Name of the axis.

nbin

Return number of bins.

nbin_per_decade

Return number of bins.

node_type

Return node type ('center' or 'edges').

unit

Return coordinate axis unit.

use_center_as_plot_labels

Use center as plot labels

Methods Summary

assert_name(required_name)

Assert axis name if a specific one is required.

concatenate(axis)

Concatenate another MapAxis to this MapAxis into a new MapAxis object.

coord_to_idx(coord[, clip])

Transform from axis coordinate to bin index.

coord_to_pix(coord)

Transform from axis to pixel coordinates.

copy(**kwargs)

Copy MapAxis instance and overwrite given attributes.

downsample(factor)

Downsample map axis by a given factor.

format_plot_xaxis(ax)

Format plot axis

format_plot_yaxis(ax)

Format plot axis

from_bounds(lo_bnd, hi_bnd, nbin, **kwargs)

Generate an axis object from a lower/upper bound and number of bins.

from_edges(edges, **kwargs)

Generate an axis object from a sequence of bin edges.

from_energy_bounds(energy_min, energy_max, nbin)

Make an energy axis.

from_energy_edges(energy_edges[, unit, ...])

Make an energy axis from adjacent edges.

from_nodes(nodes, **kwargs)

Generate an axis object from a sequence of nodes (bin centers).

from_stack(axes)

Create a map axis by merging a list of other map axes.

from_table(table[, format, idx, column_prefix])

Instantiate MapAxis from table HDU

from_table_hdu(hdu[, format, idx])

Instantiate MapAxis from table HDU

group_table(edges)

Compute bin groups table for the map axis, given coarser bin edges.

is_aligned(other[, atol])

Check if other map axis is aligned.

is_allclose(other, **kwargs)

Check if other map axis is all close.

pad(pad_width)

Pad axis by a given number of pixels

pix_to_coord(pix)

Transform from pixel to axis coordinates.

pix_to_idx(pix[, clip])

Convert pix to idx

rename(new_name)

Rename the axis.

round(coord[, clip])

Round coord to nearest axis edge.

slice(idx)

Create a new axis object by extracting a slice from this axis.

squash()

Create a new axis object by squashing the axis into one bin.

to_header([format, idx])

Create FITS header

to_node_type(node_type)

Return MapAxis copy changing its node type to node_type.

to_table([format])

Convert Quantity to OGIP EBOUNDS extension.

to_table_hdu([format])

Convert Quantity to OGIP EBOUNDS extension.

upsample(factor)

Upsample map axis by a given factor.

Attributes Documentation

append#

Deprecated since version 1.1: The append attribute is deprecated and may be removed in a future version. Use concatenate instead.

as_plot_center#

Plot center

as_plot_edges#

Plot edges

as_plot_labels#

Return list of axis plot labels

as_plot_scale#

Plot axis scale

as_plot_xerr#

Return tuple of xerr to be used with plt.errorbar()

bin_width#

Array of bin widths.

bounds#

Bounds of the axis (~astropy.units.Quantity)

center#

Return array of bin centers.

edges#

Return array of bin edges.

edges_max#

Return array of bin edges min values.

edges_min#

Return array of bin edges max values.

interp#

Interpolation scale of the axis.

is_energy_axis#
iter_by_edges#

Iterate by intervals defined by the edges

name#

Name of the axis.

nbin#

Return number of bins.

nbin_per_decade#

Return number of bins.

node_type#

Return node type (‘center’ or ‘edges’).

unit#

Return coordinate axis unit.

use_center_as_plot_labels#

Use center as plot labels

Methods Documentation

assert_name(required_name)[source]#

Assert axis name if a specific one is required.

Parameters
required_namestr

Required

concatenate(axis)[source]#

Concatenate another MapAxis to this MapAxis into a new MapAxis object.

Name, interp type and node type must agree between the axes. If the node type is “edges”, the edges must be contiguous and non-overlapping.

Parameters
axisMapAxis

Axis to concatenate with.

Returns
axisMapAxis

Concatenation of the two axis.

coord_to_idx(coord, clip=False)[source]#

Transform from axis coordinate to bin index.

Parameters
coordndarray

Array of axis coordinate values.

clipbool

Choose whether to clip the index to the valid range of the axis. If false then indices for values outside the axis range will be set -1.

Returns
idxndarray

Array of bin indices.

coord_to_pix(coord)[source]#

Transform from axis to pixel coordinates.

Parameters
coordndarray

Array of axis coordinate values.

Returns
pixndarray

Array of pixel coordinate values.

copy(**kwargs)[source]#

Copy MapAxis instance and overwrite given attributes.

Parameters
**kwargsdict

Keyword arguments to overwrite in the map axis constructor.

Returns
copyMapAxis

Copied map axis.

downsample(factor)[source]#

Downsample map axis by a given factor.

When down-sampling each n-th (given by the factor) bin is selected from the axis while preserving the axis limits. For node type “edges” this requires nbin to be dividable by the factor, for node type “center” this requires nbin - 1 to be dividable by the factor.

Parameters
factorint

Downsampling factor.

Returns
axisMapAxis

Downsampled map axis.

format_plot_xaxis(ax)[source]#

Format plot axis

Parameters
axAxis

Plot axis to format

Returns
axAxis

Formatted plot axis

format_plot_yaxis(ax)[source]#

Format plot axis

Parameters
axAxis

Plot axis to format

Returns
axAxis

Formatted plot axis

classmethod from_bounds(lo_bnd, hi_bnd, nbin, **kwargs)[source]#

Generate an axis object from a lower/upper bound and number of bins.

If node_type = ‘edges’ then bounds correspond to the lower and upper bound of the first and last bin. If node_type = ‘center’ then bounds correspond to the centers of the first and last bin.

Parameters
lo_bndfloat

Lower bound of first axis bin.

hi_bndfloat

Upper bound of last axis bin.

nbinint

Number of bins.

interp{‘lin’, ‘log’, ‘sqrt’}

Interpolation method used to transform between axis and pixel coordinates. Default: ‘lin’.

classmethod from_edges(edges, **kwargs)[source]#

Generate an axis object from a sequence of bin edges.

This method should be used to construct an axis where the bin edges should lie at specific values (e.g. a histogram). The number of bins will be one less than the number of edges.

Parameters
edgesndarray

Axis bin edges.

interp{‘lin’, ‘log’, ‘sqrt’}

Interpolation method used to transform between axis and pixel coordinates. Default: ‘lin’.

classmethod from_energy_bounds(energy_min, energy_max, nbin, unit=None, per_decade=False, name=None, node_type='edges')[source]#

Make an energy axis.

Used frequently also to make energy grids, by making the axis, and then using axis.center or axis.edges.

Parameters
energy_min, energy_maxQuantity, float

Energy range

nbinint

Number of bins

unitUnit

Energy unit

per_decadebool

Whether nbin is given per decade.

namestr

Name of the energy axis, either ‘energy’ or ‘energy_true’

Returns
axisMapAxis

Axis with name “energy” and interp “log”.

classmethod from_energy_edges(energy_edges, unit=None, name=None, interp='log')[source]#

Make an energy axis from adjacent edges.

Parameters
energy_edgesQuantity, float

Energy edges

unitUnit

Energy unit

namestr

Name of the energy axis, either ‘energy’ or ‘energy_true’

interp: str

interpolation mode. Default is ‘log’.

Returns
axisMapAxis

Axis with name “energy” and interp “log”.

classmethod from_nodes(nodes, **kwargs)[source]#

Generate an axis object from a sequence of nodes (bin centers).

This will create a sequence of bins with edges half-way between the node values. This method should be used to construct an axis where the bin center should lie at a specific value (e.g. a map of a continuous function).

Parameters
nodesndarray

Axis nodes (bin center).

interp{‘lin’, ‘log’, ‘sqrt’}

Interpolation method used to transform between axis and pixel coordinates. Default: ‘lin’.

classmethod from_stack(axes)[source]#

Create a map axis by merging a list of other map axes.

If the node type is “edges” the bin edges in the provided axes must be contiguous and non-overlapping.

Parameters
axeslist of MapAxis

List of map axis to merge.

Returns
axisMapAxis

Merged axis

classmethod from_table(table, format='ogip', idx=0, column_prefix='')[source]#

Instantiate MapAxis from table HDU

Parameters
tableTable

Table

format{“ogip”, “ogip-arf”, “fgst-ccube”, “fgst-template”, “gadf”, “gadf-dl3”}

Format specification

idxint

Column index of the axis.

column_prefixstr

Column name prefix of the axis, used for creating the axis.

Returns
axisMapAxis

Map Axis

classmethod from_table_hdu(hdu, format='ogip', idx=0)[source]#

Instantiate MapAxis from table HDU

Parameters
hduBinTableHDU

Table HDU

format{“ogip”, “ogip-arf”, “fgst-ccube”, “fgst-template”}

Format specification

idxint

Column index of the axis.

Returns
axisMapAxis

Map Axis

group_table(edges)[source]#

Compute bin groups table for the map axis, given coarser bin edges.

Parameters
edgesQuantity

Group bin edges.

Returns
groupsTable

Map axis group table.

is_aligned(other, atol=0.02)[source]#

Check if other map axis is aligned.

Two axes are aligned if their center coordinate values map to integers on the other axes as well and if the interpolation modes are equivalent.

Parameters
otherMapAxis

Other map axis.

atolfloat

Absolute numerical tolerance for the comparison measured in bins.

Returns
alignedbool

Whether the axes are aligned

is_allclose(other, **kwargs)[source]#

Check if other map axis is all close.

Parameters
otherMapAxis

Other map axis

**kwargsdict

Keyword arguments forwarded to allclose

Returns
is_allclosebool

Whether other axis is allclose

pad(pad_width)[source]#

Pad axis by a given number of pixels

Parameters
pad_widthint or tuple of int

A single int pads in both direction of the axis, a tuple specifies, which number of bins to pad at the low and high edge of the axis.

Returns
axisMapAxis

Padded axis

pix_to_coord(pix)[source]#

Transform from pixel to axis coordinates.

Parameters
pixndarray

Array of pixel coordinate values.

Returns
coordndarray

Array of axis coordinate values.

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

Convert pix to idx

Parameters
pixndarray

Pixel coordinates.

clipbool

Choose whether to clip indices to the valid range of the axis. If false then indices for coordinates outside the axi range will be set -1.

Returns
idxndarray

Pixel indices.

rename(new_name)[source]#

Rename the axis.

Parameters
new_namestr

The new name for the axis.

Returns
axisMapAxis

Renamed MapAxis

round(coord, clip=False)[source]#

Round coord to nearest axis edge.

Parameters
coordQuantity

Coordinates

clipbool

Choose whether to clip indices to the valid range of the axis.

Returns
coordQuantity

Rounded coordinates

slice(idx)[source]#

Create a new axis object by extracting a slice from this axis.

Parameters
idxslice

Slice object selecting a subselection of the axis.

Returns
axisMapAxis

Sliced axis object.

squash()[source]#

Create a new axis object by squashing the axis into one bin.

Returns
axisMapAxis

Sliced axis object.

to_header(format='ogip', idx=0)[source]#

Create FITS header

Parameters
format{“ogip”}

Format specification

idxint

Column index of the axis.

Returns
headerHeader

Header to extend.

to_node_type(node_type)[source]#

Return MapAxis copy changing its node type to node_type.

Parameters
node_typestr ‘edges’ or ‘center’

the target node type

Returns
axisMapAxis

the new MapAxis

to_table(format='ogip')[source]#

Convert Quantity to OGIP EBOUNDS extension.

See https://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/docs/memos/cal_gen_92_002/cal_gen_92_002.html#tth_sEc3.2 # noqa: E501

The ‘ogip-sherpa’ format is equivalent to ‘ogip’ but uses keV energy units.

Parameters
format{“ogip”, “ogip-sherpa”, “gadf-dl3”, “gtpsf”}

Format specification

Returns
tableTable

Table HDU

to_table_hdu(format='ogip')[source]#

Convert Quantity to OGIP EBOUNDS extension.

See https://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/docs/memos/cal_gen_92_002/cal_gen_92_002.html#tth_sEc3.2 # noqa: E501

The ‘ogip-sherpa’ format is equivalent to ‘ogip’ but uses keV energy units.

Parameters
format{“ogip”, “ogip-sherpa”, “gtpsf”}

Format specification

Returns
hduBinTableHDU

Table HDU

upsample(factor)[source]#

Upsample map axis by a given factor.

When up-sampling for each node specified in the axis, the corresponding number of sub-nodes are introduced and preserving the initial nodes. For node type “edges” this results in nbin * factor new bins. For node type “center” this results in (nbin - 1) * factor + 1 new bins.

Parameters
factorint

Upsampling factor.

Returns
axisMapAxis

Usampled map axis.