Note

You are not reading the most up to date version of Gammapy documentation.
Access the latest stable version v1.3 or the list of Gammapy releases.

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.