Utility functions and classes (gammapy.utils)

Introduction

gammapy.utils is a collection of utility functions that are used in many places or don’t fit in one of the other packages.

Since the various sub-modules of gammapy.utils are mostly unrelated, they are not imported into the top-level namespace. Here are some examples of how to import functionality from the gammapy.utils sub-modules:

from gammapy.utils.random import sample_sphere
sample_sphere(size=10)

from gammapy.utils import random
random.sample_sphere(size=10)

Time handling in Gammapy

See gammapy.utils.time.

Time format and scale

In Gammapy, astropy.time.Time objects are used to represent times:

>>> from astropy.time import Time
>>> Time(['1999-01-01T00:00:00.123456789', '2010-01-01T00:00:00'])
<Time object: scale='utc' format='isot' value=['1999-01-01T00:00:00.123' '2010-01-01T00:00:00.000']>

Note that Astropy chose format='isot' and scale='utc' as default and in Gammapy these are also the recommended format and time scale.

Warning

Actually what’s written here is not true. In CTA it hasn’t been decided if times will be in utc or tt (terrestial time) format.

Here’s a reminder that this needs to be settled / updated: https://github.com/gammapy/gammapy/issues/284

When other time formats are needed it’s easy to convert, see the time format section and table in the Astropy docs.

E.g. sometimes in astronomy the modified Julian date mjd is used and for passing times to matplotlib for plotting the plot_date format should be used:

>>> from astropy.time import Time
>>> time = Time(['1999-01-01T00:00:00.123456789', '2010-01-01T00:00:00'])
>>> time.mjd
array([ 51179.00000143,  55197.        ])
>>> time.plot_date
array([ 729755.00000143,  733773.        ])

Converting to other time scales is also easy, see the time scale section, diagram and table in the Astropy docs.

E.g. when converting celestial (RA/DEC) to horizontal (ALT/AZ) coordinates, the sidereal time is needed. This is done automatically by astropy.coordinates.AltAz when the astropy.coordinates.AltAz.obstime is set with a Time object in any scale, no need for explicit time scale transformations in Gammapy (although if you do want to explicitly compute it, it’s easy, see here).

The “Time Systems in a nutshell” section here gives a good, brief explanation of the differences between the relevant time scales UT1, UTC and TT.

Mission elapsed times (MET)

[MET] time references are times representing UTC seconds after a specific origin. Each experiment may have a different MET origin that should be included in the header of the corresponding data files. For more details see Cicerone: Data - Time in Fermi Data Analysis.

It’s not clear yet how to best implement METs in Gammapy, it’s one of the tasks here: https://github.com/gammapy/gammapy/issues/284

For now, we use the gammapy.time.time_ref_from_dict, gammapy.time.time_relative_to_ref and gammapy.time.absolute_time functions to convert MET floats to Time objects via the reference times stored in FITS headers.

Time differences

TODO: discuss when to use TimeDelta or Quantity or [MET] floats and where one needs to convert between those and what to watch out for.

Energy handling in Gammapy

Basics

Most objects in Astronomy require an energy axis, e.g. counts spectra or effective area tables. In general, this axis can be defined in two ways.

  • As an array of energy values. E.g. the Fermi-LAT diffuse flux is given at certain energies and those are stored in an ENERGY FITS table extension. In Gammalib this is represented by GEnergy.
  • As an array of energy bin edges. This is usually stored in EBOUNDS tables, e.g. for Fermi-LAT counts cubes. In Gammalib this is represented by GEbounds.

In Gammapy both the use cases are handled by two seperate classes: gammapy.utils.energy.Energy for energy values and gammapy.utils.energy.EnergyBounds for energy bin edges

Energy

The Energy class is a subclass of Quantity and thus has the same functionality plus some convenience functions for fits I/O

>>> from gammapy.utils.energy import Energy
>>> energy = Energy([1,2,3], 'TeV')
>>> hdu = energy.to_fits()
>>> type(hdu)
<class 'astropy.io.fits.hdu.table.BinTableHDU'>

EnergyBounds

The EnergyBounds class is a subclass of Energy. Additional functions are available e.g. to compute the bin centers

>>> from gammapy.utils.energy import EnergyBounds
>>> ebounds = EnergyBounds.equal_log_spacing(1, 10, 8, 'GeV')
>>> ebounds.size
9
>>> ebounds.nbins
8
>>> center = ebounds.log_centers
>>> center
<Energy [ 1.15478198, 1.53992653, 2.05352503, 2.73841963, 3.65174127,
          4.86967525, 6.49381632, 8.65964323] GeV>

Reference/API

gammapy.utils.energy Module

Classes

Energy Energy quantity scalar or array.
EnergyBounds EnergyBounds array.

gammapy.utils.units Module

Units and Quantity related helper functions

Functions

standardise_unit(unit) Standardise unit.

gammapy.utils.mpl_style Module

Define the Gammapy matplotlib plotting style.

gammapy.utils.coordinates Package

Astronomical coordinate calculation utility functions.

Functions

angle_to_radius(angle, distance) Radius (pc), distance(kpc), angle(deg)
cartesian(r, theta) Convert polar coordinates to cartesian coordinates.
flux_to_luminosity(flux, distance) Distance is assumed to be in kpc
galactic(x, y, z[, obs_pos]) Compute galactic coordinates lon, lat (deg) and distance (kpc)
luminosity_to_flux(luminosity, distance) Distance is assumed to be in kpc
minimum_separation(lon1, lat1, lon2, lat2) Compute minimum distance of each (lon1, lat1) to any (lon2, lat2).
motion_since_birth(v, age, theta, phi) Compute motion of a object with given velocity, direction and age.
pair_correlation(lon, lat, theta_bins) Compute pair correlation function for points on the sphere.
polar(x, y) Convert cartesian coordinates to polar coordinates.
radius_to_angle(radius, distance) Radius (pc), distance(kpc), angle(deg)
velocity_glon_glat(x, y, z, vx, vy, vz) Compute projected angular velocity in galactic coordinates.

gammapy.utils.table Module

Table helper utilities.

Functions

table_standardise(table) TODO

gammapy.utils.fits Module

FITS utility functions.

Functions

table_from_row_data(rows[, type]) Helper function to create table objects from row data.
table_to_fits_table(table) Convert Table to astropy.io.fits.BinTableHDU.
fits_table_to_table(tbhdu) Convert astropy table to binary table FITS format.
energy_axis_to_ebounds(energy) Convert EnergyBounds to OGIP EBOUNDS extension

Classes

SmartHDUList(hdu_list) A FITS HDU list wrapper with some sugar.

gammapy.utils.root Package

Utility functions to work with ROOT and rootpy.

Functions

TH2_to_FITS(hist[, flipx]) Convert ROOT 2D histogram to FITS format.
TH2_to_FITS_data(hist[, flipx]) Convert TH2 bin values into a numpy array.
TH2_to_FITS_header(hist[, flipx]) Create FITS header for a given ROOT histogram.
graph1d_to_table(graph) Convert ROOT TGraph to an astropy Table.
hist1d_to_table(hist) Convert 1D ROOT histogram into astropy table.

gammapy.utils.random Module

Random sampling for some common distributions

Functions

get_random_state(init) Get a numpy.random.RandomState instance.
sample_sphere(size[, lon_range, lat_range, ...]) Sample random points on the sphere.
sample_sphere_distance([distance_min, ...]) Sample random distances if the 3-dim space density is constant.
sample_powerlaw(x_min, x_max, gamma[, size, ...]) Sample random values from a power law distribution.

gammapy.utils.distributions Package

Utility functions / classes for working with distributions (e.g. probability density functions)

Functions

density(func) Returns the radial surface density of a given one dimensional PDF.
draw(low, high, size, dist[, random_state]) Allows drawing of random numbers from any distribution.
normalize(func, x_min, x_max) Normalize a 1D function over a given range.
pdf(func) Returns the one dimensional PDF of a given radial surface density.

Classes

GeneralRandom(pdf, min_range, max_range[, ...]) Fast random number generation with an arbitrary pdf of a continuous variable x.
GeneralRandomArray(pdf) Draw random indices from a discrete probability distribution given by a numpy array.

gammapy.utils.scripts Module

Utils to create scripts and command-line tools

Functions

get_parser([function, description]) Make an ArgumentParser how we like it.
get_installed_scripts() Get list of installed scripts via pkg-resources.
get_all_main_functions() Get a dict with all scripts (used for testing).
set_up_logging_from_args(args) Set up logging from command line arguments.
read_yaml(filename[, logger]) Read YAML file
write_yaml(dictionary, filename[, logger]) Write YAML file.
make_path(path) Expand environment variables on Path construction.
recursive_merge_dicts(a, b) Recursively merge two dictionaries.

Classes

GammapyFormatter(prog[, indent_increment, ...]) ArgumentParser formatter_class argument.

gammapy.utils.testing Module

Utilities for testing

Functions

requires_dependency(name) Decorator to declare required dependencies for tests.
requires_data(name) Decorator to declare required data for tests.
assert_wcs_allclose(wcs1, wcs2) Assert all-close for WCS
assert_skycoord_allclose(skycoord1, skycoord2) Assert all-close for SkyCoord.

gammapy.utils.wcs Module

WCS related utility functions.

Functions

linear_wcs_to_arrays(wcs, nbins_x, nbins_y) Make a 2D linear binning from a WCS object.
linear_arrays_to_wcs(name_x, name_y, ...) Make a 2D linear WCS object from arrays of bin edges.
get_wcs_ctype(wcs) Get celestial coordinate type of WCS instance.
get_resampled_wcs(wcs, factor, downsampled) Get resampled WCS object.

gammapy.utils.nddata Module

Utility functions and classes for n-dimensional data and axes.

Functions

sqrt_space(start, stop, num) Return numbers spaced evenly on a square root scale.

Classes

NDDataArray(axes[, data, meta, interp_kwargs]) ND Data Array Base class
DataAxis(nodes[, name, interpolation_mode]) Data axis to be used with NDDataArray
BinnedDataAxis(lo, hi, **kwargs) Data axis for binned data

gammapy.utils.time Module

Time related utility functions.

Functions

time_ref_from_dict(meta) Calculate the time reference from metadata.
time_relative_to_ref(time, meta) Convert a time using an existing reference.
absolute_time(time_delta, meta) Convert a MET into human readable date and time.

gammapy.utils.modeling Module

Model classes to generate XML.

This is prototype code.

The goal was to be able to save gamma-cat in XML format for the CTA data challenge GPS sky model.

TODO (needs a bit of experimentation / discussion / thought and a few days of coding):

  • add repr to all classes
  • integrate this the existing Gammapy model classes to make analysis possible.
  • don’t couple this to gamma-cat. Gamma-cat should change to create model classes that support XML I/O.
  • sub-class Astropy Parameter and ParameterSet classes instead of starting from scratch?
  • implement spatial and spectral mode registries instead of if-elif set on type to make SourceLibrary extensible.
  • write test and docs
  • Once modeling setup OK, ask new people to add missing models (see Gammalib, Fermi ST, naima, Sherpa, HESS) (it’s one of the simplest and nicest things to get started with)

For XML model format definitions, see here:

Classes

Parameter(name, value[, unit, parmin, ...]) Class representing model parameters.
ParameterList(parameters[, covariance]) List of Parameters
SourceLibrary(source_list)
SourceModel(source_name, source_type, ...) TODO: having “source_type” separate, but often inferred from the spatial model is weird.
SpectralModel(parameters) Spectral model abstract base class.
SpectralModelPowerLaw(parameters)
SpectralModelPowerLaw2(parameters)
SpectralModelExpCutoff(parameters)
SpatialModel(parameters) Spatial model abstract base class
SpatialModelPoint(parameters)
SpatialModelGauss(parameters)
SpatialModelShell(parameters)
UnknownModelError Error when encountering unknown model types.