Source catalogs and objects (gammapy.catalog)

Introduction

gammapy.catalog provides utilities to work with source catalogs in general, and catalogs relevant for gamma-ray astronomy specifically.

A tutorial introduction is available here: source_catalogs.ipynb.

Available catalogs

Support for the following catalogs is available:

   Name                       Description                      Sources
--------- ---------------------------------------------------- -------
     3fgl                      LAT 4-year point source catalog    3034
     1fhl      First Fermi-LAT Catalog of Sources above 10 GeV     514
     2fhl                LAT second high-energy source catalog     360
     3fhl                 LAT third high-energy source catalog    1558
     hgps H.E.S.S. Galactic plane survey (HGPS) source catalog      78
gamma-cat                 An open catalog of gamma-ray sources     162

More catalogs can be added to gammapy.catalog, and users can also add support for their favourite catalog in their Python script or package, by following the examples how the built-in catalogs are implemented.

How it works

This section provides some information how gammapy.catalog works. In principle, to use it, you don’t have to know how it’s implemented, and just follow the examples in the sections below. In practice, if you want to work with catalogs via gammapy.catalog or directly, it really helps if you spend a little time and learn about Astropy tables.

Catalog data is stored as an astropy.table.Table object, with the information for each source in a astropy.table.Row. In gammapy.catalog we have implemented a base class gammapy.catalog.SourceCatalog that stores the astropy.table.Table in the table attribute, and a base gammapy.catalog.SourceCatalogObject class that can extract the astropy.table.Row data into a Python dictionary in the data attribute and then provides conveniences to work with the data for a given source.

For every given concrete catalog, two classes (“catalog” and “source/object”) are needed. E.g. for the Fermi-LAT 3FGL catalog, there are the gammapy.catalog.SourceCatalog3FGL and the gammapy.catalog.SourceCatalogObject3FGL classes.

The SourceCatalog class mostly handles data file loading, as well as source access by integer row index or source name. The SourceCatalogObject class implements in __str__ a pretty-printed version of source.data, so that you can print(source), as well as factory methods to create Gammapy objects such as gammapy.spectrum.models.SpectralModel or gammapy.image.models.SpatialModel or gammapy.spectrum.FluxPoints representing spatial and spectral models, or spectral points, which you can then print or plot or use for simulation and analysis.

Getting Started

Let’s start by checking which catalogs are available:

>>> from gammapy.catalog import source_catalogs
>>> source_catalogs.info()
Source catalog registry:
Name Description Loaded
---- ----------- ------
3fgl description     no
2fhl description     no

You can access source_catalogs like a dict, i.e. load catalogs by name:

>>> catalog = source_catalogs['3fgl']
>>> catalog.table # To access the underlying astropy.table.Table

Note that importing source_catalogs did not load catalogs from disk, they are lazy-loaded on access via [name] and then cached for the duration of your Python session.

You can get an object representing one source of interest by source name or by row index:

>>> source = catalog['3FGL J0004.7-4740']  # access by source name
>>> source = catalog[15]  # access by row index

The source object contains all of the information in the data attribute:

>>> source.data['RAJ2000']
1.1806999
>>> source.data['CLASS1']
'fsrq '
>>> source.pprint()
# print all info on this source in a readable format

TODO: continue here describing how to access spectra, finder charts, ... once that’s implemented.

Catalog analysis

TODO: explain about the catalog “analysis” classes and functions (see API docs below)

TODO: give one example, e.g. how to reproduce a log(N)-log(S) plot from a Fermi catalog paper.

Command line tool

Sometimes you just want to look up the information for a give source, and it’s a little inconvenient to have to start python and type the imports to access the info via gammapy.catalog.

In this case we recommend you go to http://gamma-sky.net/cat , a website we are building for this use case (still very preliminary and incomplete).

Another option is to use the command line tool gammapy-catalog-query:

$ gammapy-catalog-query --help
Usage: gammapy-catalog-query [OPTIONS] COMMAND [ARGS]...

  Gammapy catalog query command line tool.

  Examples
  --------

  gammapy-catalog-query -h
  gammapy-catalog-query catalogs
  gammapy-catalog-query sources 2fhl
  gammapy-catalog-query info 2fhl "2FHL J0534.5+2201"
  gammapy-catalog-query info 3fgl "3FGL J0534.5+2201"
  gammapy-catalog-query info hgps "HESS J1825-137"

  gammapy-catalog-query table-info 2fhl
  gammapy-catalog-query table-web 2fhl

Options:
  -h, --help  Show this message and exit.

Commands:
  catalogs         List available catalogs
  info             Print info for CATALOG and SOURCE
  plot-lightcurve  Plot lightcurve for CATALOG and SOURCE
  plot-spectrum    Plot spectrum for CATALOG and SOURCE
  sources          List sources for CATALOG
  table-info       Summarise table info for CATALOG
  table-web        Open table in web browser for CATALOG

We also started to implement a local web app: gammapy-catalog-browse. It isn’t working well at the moment, and probably now that we started http://gamma-sky.net we’ll probably remove it. But if anyone is interested to fix and improve gammapy-catalog-browse, we could also keep it.

Reference/API

gammapy.catalog Package

Source catalogs and objects.

Functions

catalog_xmatch_circle(catalog, other_catalog) Find associations within a circle around each source.
catalog_xmatch_combine(associations) Combine (vertical stack) association tables.
coordinate_iau_format(coordinate, ra_digits) Coordinate format as an IAU source designation.
dec_iau_format(dec, digits) Declination part of an IAU source designation.
fetch_fermi_catalog(catalog[, extension]) Fetch Fermi catalog data.
fetch_fermi_extended_sources(catalog) Fetch Fermi catalog extended source images.
load_catalog_green() Load Green’s supernova remnant catalog.
ra_iau_format(ra, digits) Right Ascension part of an IAU source designation.
select_sky_box(table, lon_lim, lat_lim[, ...]) Select sky positions in a box.
select_sky_circle(table, lon_cen, lat_cen, ...) Select sky positions in a circle.
skycoord_from_table(table) Make SkyCoord from lon, lat columns in Table.
table_xmatch(table1, table2, xmatch_criterion) Cross-match rows from two tables with a cross-match criterion callback.
table_xmatch_circle_criterion(max_separation) An example cross-match criterion for table_xmatch that reproduces catalog_xmatch_circle.
to_ds9_region(catalog[, radius, color, ...]) Write ds9 region file from catalog.

Classes

SourceCatalog(table[, source_name_key, ...]) Generic source catalog.
SourceCatalog1FHL([filename]) Fermi-LAT 1FHL source catalog.
SourceCatalog2FHL([filename]) Fermi-LAT 2FHL source catalog.
SourceCatalog3FGL([filename]) Fermi-LAT 3FGL source catalog.
SourceCatalog3FHL([filename]) Fermi-LAT 3FHL source catalog.
SourceCatalogATNF([filename]) ATNF pulsar catalog.
SourceCatalogGammaCat([filename]) Gammacat open TeV source catalog.
SourceCatalogHGPS([filename, hdu]) HESS Galactic plane survey (HGPS) source catalog.
SourceCatalogObject(data) Source catalog object.
SourceCatalogObject1FHL(data) One source from the Fermi-LAT 1FHL catalog.
SourceCatalogObject2FHL(data) One source from the Fermi-LAT 2FHL catalog.
SourceCatalogObject3FGL(data) One source from the Fermi-LAT 3FGL catalog.
SourceCatalogObject3FHL(data) One source from the Fermi-LAT 3FHL catalog.
SourceCatalogObjectATNF(data) One source from the ATNF pulsar catalog.
SourceCatalogObjectGammaCat(data) One object from the gamma-cat source catalog.
SourceCatalogObjectHGPS(data) One object from the HGPS catalog.
SourceCatalogObjectSNRcat(data) One source from the SNRcat catalog.
SourceCatalogRegistry() Source catalog registry.
SourceCatalogSNRcat([cache]) SNRcat supernova remnant catalog.