Access datasets (gammapy.datasets)

Introduction

gammapy.datasets contains function to easily access datasets that are relevant for gamma-ray astronomy.

The functions have a naming pattern (following the sklearn.datasets lead):

  • load_* functions load datasets that are distributed with Gammapy (bundled in the repo)
  • fetch_* functions fetch datasets from the web (either from gammapy-extra or other sites)
  • make_* functions create datasets programatically (sometimes involving a random number generator)

Note

The gammapy.datasets sub-package shouldn’t be confused with the gammapy.data sub-package, which contains classes representing gamma-ray data. And there is a separate section describing the Data Formats that are commonly used in gamma-ray astronomy.

gammapy-extra

To keep the Gammapy code repository at https://github.com/gammapy/gammapy small and clean, we are putting sample data files and IPython notebooks in an extra repository at https://github.com/gammapy/gammapy-extra/ .

To get the repository, git clone it to a location of your choosing using a git protocol of your choosing (try HTTPS or see the Github clone URL help article if you’re not sure which you want).

git clone https://github.com/gammapy/gammapy-extra.git
git clone git@github.com:gammapy/gammapy-extra.git

If you don’t have git, you can also fetch the latest version as a zip file:

wget https://github.com/gammapy/gammapy-extra/archive/master.zip
unzip master.zip # will result in a `gammapy-extra-master` folder

The Gammapy tests, docs generator, examples and tutorials will access files from the gammapy-extra repo using the gammapy.datasets.gammapy_extra object.

For this to work, you have to set the GAMMAPY_EXTRA shell environment variable to point to that folder. We suggest you put this in you .bashrc or .profile

export GAMMAPY_EXTRA=/path/on/your/machine/to/gammapy-extra

After you’ve done this, open up a new terminal (or source .profile) and check if gammapy-extra is found:

# TODO: make this print some info about gammapy-extra (including a version!!!)
gammapy info

Example usage:

>>> from gammapy.datasets import gammapy_extra
>>> gammapy_extra.filename('logo/gammapy_banner.png')
'/Users/deil/code/gammapy-extra/logo/gammapy_banner.png'

Gamma-cat

Gamma-cat is an open catalog for TeV gamma-ray sources. It is maintained as an open git repository and hosted on github. To get the data you can use the git clone command:

git clone https://github.com/gammapy/gamma-cat.git
git clone git@github.com:gammapy/gamma-cat.git

If you don’t have git, you can also fetch the latest version as a zip file as well:

wget https://github.com/gammapy/gamma-cat/archive/master.zip
unzip master.zip # will result in a `gamma-cat-master` folder

The SourceCatalogGammaCat and SourceCatalogObjectGammaCat classes need to know where the gamma-cat repository is located on your machine. For this reason the GAMMA_CAT shell environment variable has to be set using:

export GAMMAPY_CAT=/path/on/your/machine/to/gamma-cat

Getting Started

Example how to load a dataset that is distributed with the code in the gammapy repo (i.e. will be available even if you’re offline)

>>> from gammapy.datasets import load_crab_flux_points
>>> flux_points = load_crab_flux_points()

Example how to fetch a dataset from the web (i.e. will download to the Astropy cache and need internet access on first call):

>>> from gammapy.datasets import fetch_fermi_diffuse_background_model
>>> catalog = fetch_fermi_diffuse_background_model()

TODO: explain how the Astropy cache works and make it configurable for Gammapy.

Example how to make a dataset (from scratch, no file is loaded):

>>> from gammapy.datasets import make_test_psf
>>> psf = make_test_psf(energy_bins=20)

Reference/API

gammapy.datasets Package

Access datasets.

Functions

fetch_fermi_diffuse_background_model([filename]) Fetch Fermi diffuse background model.
load_crab_flux_points([component]) Load published Crab pulsar and nebula flux points.
load_diffuse_gamma_spectrum(reference) Load published diffuse gamma-ray spectrum.
load_electron_spectrum(reference) Load published electron spectrum.
load_lat_psf_performance(performance_file) Loads Fermi-LAT TOTAL PSF performance data.
load_poisson_stats_image([extra_info, …]) Load Poisson statistics counts image of a Gaussian source on flat background.
load_tev_spectrum(source_name) Load published TeV flux point measurements.
make_test_bg_cube_model([detx_range, …]) Make a test bg cube model.
make_test_dataset(outdir[, overwrite, …]) Make a test dataset and save it to disk.
make_test_eventlist(observation_table, obs_id) Make a test event list for a specified observation.
make_test_observation_table([…]) Make a test observation table.
make_test_psf([energy_bins, theta_bins]) Create a test FITS PSF file.

Classes

Datasets([config]) Download and access for all built-in datasets.
FermiGalacticCenter Fermi high-energy data for the Galactic center region.
FermiLATDataset(filename) Fermi dataset container class, with lazy data access.
FermiVelaRegion Fermi high-energy data for the Vela region.

Variables

gammapy_extra Module-level variable to access gammapy-extra.