Merge pull request #128 from cdeil/02-up

Polish before v0.2 release

Author: cdeil

source/about.rst

@@ -9,15 +9,19 @@ In gamma-ray astronomy, a variety of data formats and proprietary software have
 been traditionally used, often developed for one specific mission or experiment.
 Especially for ground-based imaging atmospheric Cherenkov telescopes (IACTs),
 data and software are mostly private to the collaborations operating the
-telescopes. However, there is a general movement in science towards the use of
-open data and software. In addition, the next-generation IACT instrument, the
-Cherenkov Telescope Array (CTA), will be operated as an open observatory. 
+telescopes. The next-generation IACT instrument, the Cherenkov Telescope Array
+(CTA), will be the first ground-based gamma-ray telescope array operated as an
+open observatory with public observer access. This implies fundamentally
+different requirements for the data formats and software tools. Open community
+access is a novelty in this domain, putting a challenge on the implementation of
+services that make very high energy (VHE) gamma-ray astronomy as accessible as
+any other waveband.
 
 To work towards open and interoperable data formats for gamma-ray astronomy, we
 have started this open data format specification. This was started at the
 `PyGamma15 workshop`_ in November 2015, followed by a `meeting in April 2016 in
 Meudon`_ and another `meeting in March 2017 in Heidelberg`_. Version
-0.1 of the spec was release in April 2016, version 0.2 in July 2018. You can
+0.1 of the spec was release in April 2016, version 0.2 in August 2018. You can
 find more information about this effort in `Deil et al. (2017)
 <https://adsabs.harvard.edu/abs/2017AIPC.1792g0006D>`__.
 
@@ -36,8 +40,9 @@ but rather the key name and data type for each metadata or data field.
 The formats described here are partially in use by current instruments
 (Fermi-LAT, HESS, VERITAS, MAGIC, FACT) as well as in the next-generation
 Cherenkov Telescope Array CTA. Prototyping and support for many of the formats
-here is happening in the CTA science tool prototypes `Gammapy`_ and `ctools`_,
-the data formats are being used e.g. in `gamma-cat`_.
+here is happening in the CTA science tool prototypes `Gammapy`_ and `ctools`_.
+The data formats are also used e.g. in `gamma-cat`_, a collection and source
+catalog for very-high-energy gamma-ray astronomy.
 
 However, we would like to stress that this is an inofficial effort, the formats
 described here are work in progress and have not been officially adopted by any

source/conf.py

@@ -59,9 +59,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.1'
+version = '0.2'
 # The full version, including alpha/beta/rc tags.
-release = '0.1'
+release = '0.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -220,7 +220,8 @@
 
 latex_elements = {
 # The paper size ('letterpaper' or 'a4paper').
-#'papersize': 'letterpaper',
+'papersize': 'a4paper',
+'extraclassoptions': 'openany',
 
 # The font size ('10pt', '11pt' or '12pt').
 #'pointsize': '10pt',
@@ -246,7 +247,8 @@
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
-#latex_use_parts = False
+# latex_use_parts = False
+latex_toplevel_sectioning = 'chapter'
 
 # If true, show page references after internal links.
 #latex_show_pagerefs = False

source/data_storage/hdu_index/index.rst

@@ -50,6 +50,18 @@ Column Name     Description                                       Data type Requ
 ``MD5``         Checksum                                          string    no
 ==============  ================================================  ========= =========
 
+Mandatory Header keywords
+-------------------------
+
+As explained in :ref:`hduclass`, the following header keyword should be used to
+declare the type of HDU (this HDU itself, the HDU index table):
+
+* ``HDUDOC``   = 'https://github.com/open-gamma-ray-astro/gamma-astro-data-formats'
+* ``HDUVERS``  = '0.2'
+* ``HDUCLASS`` = 'GADF'
+* ``HDUCLAS1`` = 'INDEX'
+* ``HDUCLAS2`` = 'HDU'
+
 .. _hdu-type-class:
 
 HDU_TYPE and HDU_CLASS

source/data_storage/obs_index/index.rst

@@ -134,6 +134,15 @@ Mandatory Header keywords
 The standard FITS reference time header keywords should be used (see :ref:`time-formats`).
 An observatory Earth location should be given as well (see :ref:`coords-location`).
 
+As explained in :ref:`hduclass`, the following header keyword should be used to 
+declare the type of HDU:
+
+* ``HDUDOC``   = 'https://github.com/open-gamma-ray-astro/gamma-astro-data-formats'
+* ``HDUVERS``  = '0.2'
+* ``HDUCLASS`` = 'GADF'
+* ``HDUCLAS1`` = 'INDEX'
+* ``HDUCLAS2`` = 'OBS'
+
 .. _obs-index-notes:
 
 Notes

source/events/index.rst

@@ -34,8 +34,6 @@ if they want to analyse parts of observations. One option could be to absorb the
 dead-time correction into the effective areas, another option could be to add
 dead-time correction factors to GTI tables.
 
-Without further ado, here is the current spec:
-
 .. toctree::
    :maxdepth: 1
 

source/general/hduclass.rst

@@ -74,3 +74,7 @@ The current HDU class scheme used is the following:
 +-----------+------------+-----------------+--------------+
 |           |            |                 |    BKG_3D    |
 +-----------+------------+-----------------+--------------+
+|  INDEX    |   OBS      |                 |              |
++-----------+------------+-----------------+--------------+
+|           |   HDU      |                 |              |
++-----------+------------+-----------------+--------------+

source/index.rst

@@ -9,9 +9,6 @@ A place to propose and share data format descriptions for gamma-ray astronomy.
 * Docs: https://gamma-astro-data-formats.readthedocs.io/
 * Mailing list: https://lists.nasa.gov/mailman/listinfo/open-gamma-ray-astro
 
-Table of contents
------------------
-
 .. toctree::
    :maxdepth: 1
 

source/irfs/full_enclosure/aeff/index.rst

@@ -33,18 +33,24 @@ Recommended axis order: ``ENERGY``, ``THETA``
 
 Header keywords:
 
-In addition to the standard header keywords, the recommended energy range for
-the observation corresponding to the effective area file is stored in two
-additional header keywords. A hierarchical ``HDUCLASS`` keyword is used to declare the
-effective area type contained within the HDU.
+If the IRFs are only known to be "valid" or "safe" to use within a given energy
+range, that range can be given via the following two keywords. The keywords are
+optional, not all telescopes use the concept of a safe range; e.g. in CTA at
+this time this hasn't been defined. Note that a proper scheme to declare IRF
+validity range (e.g. masks or weights, or safe cuts that depend on other
+parameters such as FOV offset) is not available yet.
 
-* ``OBS_ID`` type: int
-    * Observation ID, run number
 * ``LO_THRES`` type: float, unit: TeV
     * Low energy threshold
 * ``HI_THRES`` type: float, unit: TeV
     * High energy threshold
-    
+
+If the effective area corresponds to a given observation with an ``OBS_ID``,
+that ``OBS_ID`` should be given as a header keyword. Note that this is not
+always the case, e.g. sometimes IRFs are simulated and produced for instruments
+that haven't even been built yet, and then used to simulate different kinds of
+observations.
+
 As explained in :ref:`hduclass`, the following header keyword should be used to 
 declare the type of HDU: