gammapy · mapazarr · Aug 4, 2015 · Jun 29, 2015 · Jun 29, 2015 · Jun 29, 2015
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -95,6 +95,7 @@ Pull requests
 - Add Feldman Cousins algorithm [#311] (Dirk Lennarz)
 - Simplified attribute docstrings [#301] (Manuel Paz Arribas)
 - Add a simple Makefile for Gammapy. [#289] (Manuel Paz Arribas)
+- Observation table subset selection [#295] (Manuel Paz Arribas)
 
 .. _gammapy_0p2_release:
 

diff --git a/docs/dataformats/observation_lists.rst b/docs/dataformats/observation_lists.rst
@@ -28,7 +28,8 @@ DEC               pointing position declination in equatorial (ICRS) coordinates
 AZ                average azimuth angle during the observation                                 no
 ALT               average altitude angle during the observation                                no
 MUON_EFFICIENCY   average muon efficiency of the telescopes                                    yes?
-TIME_START        start time of the observation stored as number of seconds after [MET]_       yes?
+TIME_START        start time of the observation stored as number of seconds after [MET]_ or    yes?
+                  as absolute times in UTC (see description of header keyword `TIME FORMAT`)
 TIME_STOP         end time of the observation in the same format as TIME_START                 no
 TIME_OBSERVATION  duration of the observation                                                  no
 TIME_LIVE         duration of the observation without dead time                                no
@@ -51,11 +52,13 @@ keyword           description
 ================  ===========================================================================  =========
 OBSERVATORY_NAME  name of the observatory where the observations were taken. This is           no
                   important for instance for coordinate transformations between celestial
-                  (i.e. RA/dec) and terrestrial (i.e. az/alt) coordinate systems.
+                  (i.e. RA/dec) and terrestrial (i.e. az/alt) coordinate systems
 MJDREFI           reference time: integer value in mean julian days; details in                yes?
-                  :ref:`time_handling`.
+                  :ref:`time_handling`
 MJDREFF           reference time: fraction of integer value defined in MJDREFI; details in     yes?
-                  :ref:`time_handling`.
+                  :ref:`time_handling`
+TIME_FORMAT       format in which times are stored: `absolute` (UTC) or `relative` ([MET]_);   yes?
+                  see details for both formats in :ref:`time_handling`
 ================  ===========================================================================  =========
 
 Extra user-defined header entries are allowed; Gammapy will ignore them.
@@ -97,3 +100,7 @@ Table:
 +------+----------------+---------+-------------+-------------+-------------+-------------+-------------+--------------+------+---------------+
 |    10|          1800.0|   1500.0|144207430.361|144209230.361|323.562657045|45.4005803262|324.596045439| 13.6761217326|     3| 0.694201696626|
 +------+----------------+---------+-------------+-------------+-------------+-------------+-------------+--------------+------+---------------+
+
+A test observation list file in fits format is located in the
+`~gammapy-extra` repository
+(`test_observation_table.fits <https://github.com/gammapy/gammapy-extra/blob/master/test_datasets/obs/test_observation_table.fits>`_).
diff --git a/docs/obs/find_observations.rst b/docs/obs/find_observations.rst
@@ -0,0 +1,73 @@
+.. _obs_find_observations:
+
+Find observations
+=================
+
+The ``gammapy-find-obs`` command line tool can be used to select a
+subset of observations from a given observation list. The format for
+observation lists is described in :ref:`dataformats_observation_lists`.
+
+This tool works with `fits` files as input/output for now.
+
+For more details, please refer to `~gammapy.scripts.find_obs`.
+
+.. note:: Noel Dawe's ``goodruns`` tool for `ATLAS <http://atlas.ch>`__ run selection
+      (`docs <http://ndawe.github.io/goodruns/>`__, `code <https://github.com/ndawe/goodruns>`__)
+      is a nice example for a run selection tool.
+
+Examples
+--------
+
+The ``gammapy-find-obs`` tool has many options. Only a few examples
+are shown here. For a full list of options, please use:
+
+  .. code-block:: bash
+
+      $ gammapy-find-obs --help
+
+at the command line.
+
+In order to test the examples below, the test observation list
+file located in the `~gammapy-extra` repository
+(`test_observation_table.fits <https://github.com/gammapy/gammapy-extra/blob/master/test_datasets/obs/test_observation_table.fits>`_)
+can be used as input observation list.
+
+* Find all observations within 5 deg of the Galactic center:
+
+  .. code-block:: bash
+
+      $ gammapy-find-obs all_obs.fits galactic_center_obs.fits \
+                         --x 0 --y 0 --r 50 --system 'galactic'
+
+* Select all observations in a box along the Galactic plane
+  (GLON = -20 .. +20 deg, GLAT = -3 .. +3 deg) (can of course be
+  combined with other selections shown above):
+
+  .. code-block:: bash
+
+      $ gammapy-find-obs all_obs.fits galactic_plane_obs.fits \
+                         --x 0 --y 0 --dx 20 --dy 3 --system 'galactic'
+
+* Select all observations in a given date range (can of course be
+  combined with other selections shown above):
+
+  .. code-block:: bash
+
+      $ gammapy-find-obs all_obs.fits obs_2010-04-26_to_2010-04-29-12h42.fits \
+                         --t_start '2012-04-20' --t_stop '2012-04-30T12:42'
+
+* Select all observations in a given observation ID range (can of
+  course be combined with other selections shown above):
+
+  .. code-block:: bash
+
+      $ gammapy-find-obs all_obs.fits obs_042_to_100.fits \
+                         --par_name 'OBS_ID' --par_min 42 --par_max 101
+
+* Select all observations in a given altitude range (can of course
+  be combined with other selections shown above):
+
+  .. code-block:: bash
+
+      $ gammapy-find-obs all_obs.fits alt_70_to_90_deg_obs.fits \
+                         --par_name 'ALT' --par_min 70 --par_max 90
diff --git a/docs/obs/findruns.rst b/docs/obs/findruns.rst
diff --git a/docs/obs/index.rst b/docs/obs/index.rst
@@ -35,7 +35,7 @@ Using `gammapy.obs`
 .. toctree::
    :maxdepth: 1
 
-   findruns
+   find_observations
 
 Reference/API
 =============

diff --git a/docs/references.rst b/docs/references.rst
@@ -71,6 +71,6 @@ Glossary
 --------
 
 .. [CSV] comma-separated values; see also :ref:`CSV_files`.
-.. [MET] mission elapsed time; see also :ref:`time_handling`.
+.. [MET] mission elapsed time; see also :ref:`MET` in :ref:`time_handling`.
 .. [RST] restructured text; the markup format used for documentation and docstrings.
-         See `here <http://en.wikipedia.org/wiki/ReStructuredText>`__ and `here <http://sphinx-doc.org/rest.html>`__.
+         See `here <http://en.wikipedia.org/wiki/ReStructuredText>`__ and `here <http://sphinx-doc.org/rest.html>`__.
diff --git a/docs/time/index.rst b/docs/time/index.rst
@@ -100,23 +100,30 @@ no need for explicit time scale transformations in Gammapy
 The "Time Systems in a nutshell" section `here <http://fermi.gsfc.nasa.gov/ssc/data/analysis/documentation/Cicerone/Cicerone_Data/Time_in_ScienceTools.html>`__
 gives a good, brief explanation of the differences between the relevant time scales `UT1`, `UTC` and `TT`.
 
+.. _MET:
+
 Mission elapsed times (MET)
 ---------------------------
 
-It's not clear yet how to best implement METs, it's one of the tasks here:
-https://github.com/gammapy/gammapy/issues/284
-
-For now, we use the `gammapy.time.time_ref_from_dict` and `gammapy.time.time_relative_to_ref` functions
-to convert MET floats to `~astropy.time.Time` objects via the reference times stored in FITS headers.
-
-See `Cicerone: Data - Time in Fermi Data Analysis
+[MET]_ time references are times representing UTC seconds after a
+specific origin. Each experiment may have a different MET origin
+that should be included in the header of the corresponding data
+files. For more details see `Cicerone: Data - Time in Fermi Data Analysis
 <http://fermi.gsfc.nasa.gov/ssc/data/analysis/documentation/Cicerone/Cicerone_Data/
 Time_in_ScienceTools.html>`_.
 
+It's not clear yet how to best implement METs in Gammapy, it's one
+of the tasks here:
+https://github.com/gammapy/gammapy/issues/284
+
+For now, we use the `gammapy.time.time_ref_from_dict`, `gammapy.time.time_relative_to_ref`
+and `gammapy.time.absolute_time` functions to convert MET floats to `~astropy.time.Time`
+objects via the reference times stored in FITS headers.
+
 Time differences
 ----------------
 
-TODO: discuss when to use `astropy.time.TimeDelta` or `astropy.units.Quantity` or MET floats and
+TODO: discuss when to use `astropy.time.TimeDelta` or `astropy.units.Quantity` or [MET]_ floats and
 where one needs to convert between those and what to watch out for.
 
 Reference/API