Utility functions#
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'])
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
(terrestrial 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'])
print(time.mjd)
print(time.plot_date)
[51179.00000143 55197. ]
[10592.00000143 14610. ]
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.
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.