utils - Utilities¶
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 Fermi-LAT time systems in a nutshell page 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 Fermi-LAT time systems in a nutshell.
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.utils.time.time_ref_from_dict
,
gammapy.utils.time.time_relative_to_ref
and gammapy.utils.time.absolute_time
functions
to convert MET floats to Time
objects via the reference times
stored in FITS headers.
Reference/API¶
gammapy.utils.units Module¶
Units and Quantity related helper functions
Functions¶
|
Standardise unit. |
|
Read unit from a FITS image HDU. |
gammapy.utils.coordinates Package¶
Astronomical coordinate calculation utility functions.
Functions¶
|
Convert polar coordinates to cartesian coordinates. |
|
Transform field-of-view coordinates to sky coordinates. |
|
Compute galactic coordinates lon, lat and distance. |
|
Compute motion of a object with given velocity, direction and age. |
|
Convert cartesian coordinates to polar coordinates. |
|
Transform sky coordinates to field-of-view coordinates. |
|
Compute projected angular velocity in galactic coordinates. |
gammapy.utils.integrate Module¶
Functions¶
|
Integrate using the composite trapezoidal rule in log-log space. |
gammapy.utils.interpolation Module¶
Interpolation utilities
Functions¶
|
Interpolation scaling. |
|
Helper function to interpolate one-dimensional profiles. |
Classes¶
|
Thin wrapper around |
gammapy.utils.table Module¶
Table helper utilities.
Functions¶
|
Stack the column data horizontally |
|
Standardise units for all columns in a table in a copy. |
Standardise units for all columns in a table in place. |
|
|
Make one source data dict. |
|
Helper function to create table objects from row data. |
gammapy.utils.fits Module¶
Functions¶
|
Create |
Classes¶
|
A lazy FITS data descriptor. |
|
HDU localisation, loading and Gammapy object mapper. |
gammapy.utils.random Package¶
Random probability distribution helpers.
Functions¶
|
Allows drawing of random numbers from any distribution. |
|
Get a |
|
Normalize a 1D function over a given range. |
|
One-dimensional PDF of a given radial surface density. |
|
Sample random values from a power law distribution. |
|
Sample random points on the sphere. |
|
Sample random distances if the 3-dim space density is constant. |
|
Make random times assuming a Poisson process. |
Classes¶
|
Inverse CDF sampler. |
gammapy.utils.regions Module¶
Regions helper functions.
Throughout Gammapy, we use regions
to represent and work with regions.
https://astropy-regions.readthedocs.io
The functions make_region
and make_pixel_region
should be used
throughout Gammapy in all functions that take region
objects as input.
They do conversion to a standard form, and some validation.
We might add in other conveniences and features here, e.g. sky coord contains without a WCS (see “sky and pixel regions” in PIG 10), or some HEALPix integration.
TODO: before Gammapy v1.0, discuss what to do about gammapy.utils.regions
.
Options: keep as-is, hide from the docs, or to remove it completely
(if the functionality is available in astropy-regions
directly.
Functions¶
|
Make region object ( |
|
Make pixel region object ( |
Utility returning an array of regions to make orthogonal projections |
|
|
Make a list of concentric annulus regions. |
|
Create list of regions from compound regions. |
|
Create compound region from list of regions, by creating the union. |
gammapy.utils.scripts Module¶
Utils to create scripts and command-line tools
Functions¶
|
Read YAML file. |
|
Write YAML file. |
|
Expand environment variables on |
|
Recursively merge two dictionaries. |
gammapy.utils.testing Module¶
Utilities for testing
Functions¶
|
Decorator to declare required dependencies for tests. |
|
Decorator to declare required data for tests. |
Matplotlib plotting test context manager. |
|
|
Assert all-close for |
|
Assert all-close for |
|
Assert all-close for |
gammapy.utils.nddata Module¶
Utility functions and classes for n-dimensional data and axes.
Classes¶
|
ND Data Array Base class |
gammapy.utils.time Module¶
Time related utility functions.
Functions¶
|
Calculate the time reference from metadata. |
|
TODO: document and test. |
|
Convert a time using an existing reference. |
|
Convert a MET into human readable date and time. |