time - Time analysis

Introduction

gammapy.time contains classes and methods for time-based analysis, e.g. for AGN, binaries or pulsars studies. The main classes are LightCurve, which is a container for light curves, and LightCurveEstimator, which extracts a light curve from a list of datasets. A number of functions to test for variability and periodicity are available in variability and periodicity. Finally, gammapy.utils.time contains low-level helper functions for time conversions.

Lightcurve

Gammapy uses a simple container for light curves: the LightCurve class. It stores the light curve in the form of a Table and provides a few convenience methods, to create time objects and plots.

The table structure follows the approach proposed in the gamma-ray-astro-formats webpage.

The following example shows how to read a table that contains a lightcurve and then create a LightCurve object. The latter gives access to a number of utilities such as plots and access to times as Time objects:

>>> from astropy.table import Table
>>> url = 'https://github.com/gammapy/gamma-cat/raw/master/input/data/2006/2006A%2526A...460..743A/tev-000119-lc.ecsv'
>>> table = Table.read(url, format='ascii.ecsv')
>>> from gammapy.time import LightCurve
>>> lc = LightCurve(table)
>>> lc.time[:2].iso
['2004-05-23 01:47:08.160' '2004-05-23 02:17:31.200']
>>> lc.plot()

Light Curve Extraction

The extraction of a light curve from gamma-ray data follows the general approach of data reduction and modeling/fitting. Observations are first reduced to dataset objects (e.g. MapDataset or SpectrumDatasetOnOff). Then, after setting the appropriate model the flux is extracted in each time bin with the LightCurveEstimator.

To extract the light curve of a source, the LightCurveEstimator fits a scale factor on the model component representing the source in each time bin and returns a LightCurve. It can work with spectral (1D) datasets as well as with map (3D) datasets.

Once a Datasets object is build with a model set, one can call the estimator to compute the light curve in the datasets time intervals:

>>> lc_estimator = LightCurveEstimator(datasets, source="source")
>>> lc = lc_estimator.run(e_min=1*u.TeV, emax=10*u.TeV, e_ref=1*u.TeV)

where source is the model component describing the source of interest and datasets the Datasets object produced by data reduction. The light curve notebook shows an example of observation based light curve extraction

Similarly, LightCurveEstimator can be used to extract the light curve in user defined time intervals. This can be useful to combine datasets to produce light curve by night, week or month:

>>> lc_estimator = LightCurveEstimator(datasets, source="source", time_intervals=time_intervals)
>>> lc = lc_estimator.run(e_min=1*u.TeV, emax=10*u.TeV, e_ref=1*u.TeV)

where time_intervals is a list of time intervals as Time objects. The light curve notebook shows an example of night-wise light curve extraction

Variability and periodicity tests

A few utility functions to perform timing tests are available in time.

compute_chisq performs a chisquare test for variable source flux:

>>> from gammapy.time import chisquare
>>> print(compute_chisq(lc['FLUX']))

compute_fvar calculates the fractional variance excess:

>>> from gammapy.time import fvar
>>> print(compute_fvar(lc['FLUX'], lc['FLUX_ERR']))

time also provides methods for period detection in time series, i.e. light curves of \(\gamma\)-ray sources. robust_periodogram performs a periodogram analysis where the unevenly sampled time series is contaminated by outliers, i.e. due to the source’s high states. This is demonstrated on the Period detection and plotting page.

Tutorials

The main tutorial demonstrates how to extract light curves from 1D and 3D datasets:

Light curve extraction on small time bins (i.e. smaller than the observation scale) for flares is demonstrated in the following tutorial:

Reference/API

gammapy.time Package

Time analysis.

Functions

compute_chisq(flux)

Calculate the chi-square test for LightCurve.

compute_fvar(flux, flux_err)

Calculate the fractional excess variance.

plot_periodogram(time, flux, periods, power)

Plot a light curve and its periodogram.

random_times(size, rate[, dead_time, …])

Make random times assuming a Poisson process.

robust_periodogram(time, flux[, flux_err, …])

Compute a light curve’s period.

Classes

LightCurve(table)

Lightcurve container.

LightCurveEstimator(datasets[, …])

Compute light curve.