tutorials/light_curve.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Light curves\n",
    "\n",
    "## Introduction\n",
    "\n",
    "This tutorial explain how to compute a light curve with Gammapy.\n",
    "\n",
    "We will use the four Crab nebula observations from the [H.E.S.S. first public test data release](https://www.mpi-hd.mpg.de/hfm/HESS/pages/dl3-dr1/) and compute per-observation fluxes. The Crab nebula is not known to be variable at TeV energies, so we expect constant brightness within statistical and systematic errors.\n",
    "\n",
    "The main classes we will use are:\n",
    "\n",
    "* [gammapy.time.LightCurve](https://docs.gammapy.org/dev/api/gammapy.time.LightCurve.html)\n",
    "* [gammapy.time.LightCurveEstimator](https://docs.gammapy.org/dev/api/gammapy.time.LightCurveEstimator.html)\n",
    "\n",
    "## Setup\n",
    "\n",
    "As usual, we'll start with some setup..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%matplotlib inline\n",
    "import matplotlib.pyplot as plt\n",
    "import astropy.units as u\n",
    "from astropy.coordinates import SkyCoord, Angle\n",
    "from regions import CircleSkyRegion\n",
    "from gammapy.utils.energy import EnergyBounds\n",
    "from gammapy.data import DataStore\n",
    "from gammapy.spectrum import SpectrumExtraction\n",
    "from gammapy.spectrum.models import PowerLaw\n",
    "from gammapy.background import ReflectedRegionsBackgroundEstimator\n",
    "from gammapy.time import LightCurve, LightCurveEstimator"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Spectrum\n",
    "\n",
    "The `LightCurveEstimator` is based on a 1d spectral analysis within each time bin.\n",
    "So before we can make the light curve, we have to extract 1d spectra."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "data_store = DataStore.from_dir(\"$GAMMAPY_DATA/hess-dl3-dr1/\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mask = data_store.obs_table[\"TARGET_NAME\"] == \"Crab\"\n",
    "obs_ids = data_store.obs_table[\"OBS_ID\"][mask].data\n",
    "observations = data_store.get_observations(obs_ids)\n",
    "print(observations)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Target definition\n",
    "target_position = SkyCoord(ra=83.63308, dec=22.01450, unit=\"deg\")\n",
    "on_region_radius = Angle(\"0.2 deg\")\n",
    "on_region = CircleSkyRegion(center=target_position, radius=on_region_radius)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%time\n",
    "bkg_estimator = ReflectedRegionsBackgroundEstimator(\n",
    "    on_region=on_region, observations=observations\n",
    ")\n",
    "bkg_estimator.run()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%time\n",
    "ebounds = EnergyBounds.equal_log_spacing(0.7, 100, 50, unit=\"TeV\")\n",
    "extraction = SpectrumExtraction(\n",
    "    observations=observations,\n",
    "    bkg_estimate=bkg_estimator.result,\n",
    "    containment_correction=False,\n",
    "    e_reco=ebounds,\n",
    "    e_true=ebounds,\n",
    ")\n",
    "extraction.run()\n",
    "spectrum_observations = extraction.spectrum_observations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Light curve estimation\n",
    "\n",
    "OK, so now that we have prepared 1D spectra (not spectral models, just the 1D counts and exposure and 2D energy dispersion matrix), we can compute a lightcurve.\n",
    "\n",
    "To compute the light curve, a spectral model shape has to be assumed, and an energy band chosen.\n",
    "The method is then to adjust the amplitude parameter of the spectral model in each time bin to the data, resulting in a flux measurement in each time bin."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Creat list of time bin intervals\n",
    "# Here we do one time bin per observation\n",
    "def time_intervals_per_obs(observations):\n",
    "    for obs in observations:\n",
    "        yield obs.tstart, obs.tstop\n",
    "\n",
    "\n",
    "time_intervals = list(time_intervals_per_obs(observations))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Assumed spectral model\n",
    "spectral_model = PowerLaw(\n",
    "    index=2, amplitude=2.0e-11 * u.Unit(\"1 / (cm2 s TeV)\"), reference=1 * u.TeV\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "energy_range = [1, 100] * u.TeV"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%time\n",
    "lc_estimator = LightCurveEstimator(extraction)\n",
    "lc = lc_estimator.light_curve(\n",
    "    time_intervals=time_intervals,\n",
    "    spectral_model=spectral_model,\n",
    "    energy_range=energy_range,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Results\n",
    "\n",
    "The light curve measurement result is stored in a table. Let's have a look at the results:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(lc.table.colnames)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "lc.table[\"time_min\", \"time_max\", \"flux\", \"flux_err\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "lc.plot();"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Let's compare to the expected flux of this source\n",
    "from gammapy.spectrum import CrabSpectrum\n",
    "\n",
    "crab_spec = CrabSpectrum().model\n",
    "crab_flux = crab_spec.integral(*energy_range).to(\"cm-2 s-1\")\n",
    "crab_flux"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ax = lc.plot(marker=\"o\", lw=2)\n",
    "ax.hlines(\n",
    "    crab_flux.value,\n",
    "    xmin=lc.table[\"time_min\"].min(),\n",
    "    xmax=lc.table[\"time_max\"].max(),\n",
    ");"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercises\n",
    "\n",
    "* Change the assumed spectral model shape (e.g. to a steeper power-law), and see how the integral flux estimate for the lightcurve changes.\n",
    "* Try a time binning where you split the observation time for every run into two time bins.\n",
    "* Try to analyse the PKS 2155 flare data from the H.E.S.S. first public test data release.\n",
    "  Start with per-observation fluxes, and then try fluxes within 5 minute time bins for one or two of the observations where the source was very bright."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}