Skip to content

Commit

Permalink
Merge pull request #1972 from tinumide/eso-doc-cleanup
Browse files Browse the repository at this point in the history 
Eso documentation cleanup
  • Loading branch information
@ceb8
ceb8 authored Apr 29, 2022
2 parents d40d316 + 4519f73 commit 5ac1834
Showing 1 changed file with 107 additions and 85 deletions.
192 changes: 107 additions & 85 deletions docs/eso/eso.rst
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
.. doctest-skip-all
.. _astroquery.eso:

******************************
Expand Down Expand Up @@ -40,12 +38,12 @@ store the password in your operating system. As such you should have to enter yo
correct password only once, and later be able to use this package for automated
interaction with the ESO archive.

.. code-block:: python
.. doctest-skip::

>>> from astroquery.eso import Eso
>>> eso = Eso()
>>> # First example: TEST is not a valid username, it will fail
>>> eso.login("TEST") # doctest: +SKIP
>>> eso.login("TEST")
TEST, enter your ESO password:

Authenticating TEST on www.eso.org...
Expand Down Expand Up @@ -85,7 +83,7 @@ needs to be edited by adding ``username = ICONDOR`` in the ``[eso]`` section.
When configured, the username in the ``login()`` method call can be omitted
as follows:

.. code-block:: python
.. doctest-skip::

>>> from astroquery.eso import Eso
>>> eso = Eso()
Expand All @@ -107,12 +105,15 @@ authentication example above. The first thing to do is to identify the instrumen
list of available instrument-specific queries can be obtained with the
:meth:`~astroquery.eso.EsoClass.list_instruments` method.

.. code-block:: python
.. doctest-remote-data::

>>> from astroquery.eso import Eso
>>> eso = Eso()
>>> eso.list_instruments()
['fors1', 'fors2', 'sphere', 'vimos', 'omegacam', 'hawki', 'isaac', 'naco', 'visir',
'vircam', 'apex', 'giraffe', 'uves', 'xshooter', 'espresso', 'muse', 'crires',
'kmos', 'sinfoni', 'amber', 'gravity', 'matisse', 'midi', 'pionier', 'wlgsu']

>>> eso.list_instruments()
['fors1', 'fors2', 'vimos', 'omegacam', 'hawki', 'isaac', 'naco', 'visir', 'vircam',
'apex', 'uves', 'giraffe', 'xshooter', 'muse, 'crires', 'kmos', 'sinfoni',
'amber', 'gravity', 'midi', 'pionier']

In the example above, 22 instruments are available, they correspond to the instruments listed on
the following web page: http://archive.eso.org/cms/eso-data/instrument-specific-query-forms.html.
Expand All @@ -124,9 +125,9 @@ Once an instrument is chosen, ``midi`` in our case, the query options for that i
inspected by setting the ``help=True`` keyword of the :meth:`~astroquery.eso.EsoClass.query_instrument`
method.

.. code-block:: python
.. doctest-remote-data::

>>> eso.query_instrument('midi', help=True)
>>> eso.query_instrument('midi', help=True) # doctest: +IGNORE_OUTPUT
List of the column_filters parameters accepted by the midi instrument query.
The presence of a column in the result table can be controlled if prefixed with a [ ] checkbox.
The default columns in the result table are shown as already ticked: [x].
Expand Down Expand Up @@ -175,39 +176,40 @@ It is now time to query the ``midi`` instrument for datasets. In the following e
target ``NGC 4151`` between ``2007-01-01`` and ``2008-01-01`` are searched, and the query is configured to
return the observation date column.

.. code-block:: python
.. doctest-remote-data::

>>> table = eso.query_instrument('midi', column_filters={'target':'NGC 4151', 'stime':'2007-01-01', 'etime':'2008-01-01'}, columns=['night'])
>>> table = eso.query_instrument('midi', column_filters={'target':'NGC 4151',
... 'stime':'2007-01-01',
... 'etime':'2008-01-01'},
... columns=['night'])
>>> print(len(table))
38
>>> print(table.columns)
<TableColumns names=('Object','RA', 'DEC','Target l b','DATE OBS','ProgId','DP.ID','OB.ID','OBS.TARG.NAME','DPR.CATG','DPR.TYPE','DPR.TECH','INS.MODE','DIMM S-avg')>
<TableColumns names=('Release Date','Object','RA','DEC','Target Ra Dec','Target l b','DATE OBS','ProgId','DP.ID','OB.ID','OBS.TARG.NAME','DPR.CATG','DPR.TYPE','DPR.TECH','INS.MODE','DIMM Seeing-avg')>
>>> table.pprint(max_width=100)
Object Target Ra Dec Target l b ... INS.MODE DIMM S-avg
----------------------- ----------------------- -------------------- ... -------- -----------
NGC4151 12:10:32.63 +39:24:20.7 155.076719 75.063247 ... STARINTF 0.69 [0.01]
NGC4151 12:10:32.63 +39:24:20.7 155.076719 75.063247 ... STARINTF 0.68 [0.01]
NGC4151 12:10:32.63 +39:24:20.7 155.076719 75.063247 ... STARINTF 0.68 [0.01]
NGC4151 12:10:32.63 +39:24:20.7 155.076719 75.063247 ... STARINTF 0.69 [0.01]
NGC4151 12:10:32.63 +39:24:20.7 155.076719 75.063247 ... STARINTF 0.69 [0.01]
NGC4151 12:10:32.63 +39:24:20.7 155.076719 75.063247 ... STARINTF 0.74 [0.01]
NGC4151 12:10:32.63 +39:24:20.7 155.076719 75.063247 ... STARINTF 0.69 [0.01]
NGC4151 12:10:32.63 +39:24:20.7 155.076719 75.063247 ... STARINTF 0.66 [0.01]
NGC4151 12:10:32.63 +39:24:20.7 155.076719 75.063247 ... STARINTF 0.64 [0.01]
NGC4151 12:10:32.63 +39:24:20.7 155.076719 75.063247 ... STARINTF 0.60 [0.01]
NGC4151 12:10:32.63 +39:24:20.7 155.076719 75.063247 ... STARINTF 0.59 [0.01]
... ... ... ... ... ...
TRACK,OBJECT,DISPERSED 12:10:32.63 +39:24:20.7 155.076719 75.063247 ... STARINTF 0.70 [0.01]
TRACK,OBJECT,DISPERSED 12:10:32.63 +39:24:20.7 155.076719 75.063247 ... STARINTF 0.72 [0.01]
SEARCH,OBJECT,DISPERSED 12:10:32.63 +39:24:20.7 155.076719 75.063247 ... STARINTF 0.62 [0.01]
SEARCH,OBJECT,DISPERSED 12:10:32.63 +39:24:20.7 155.076719 75.063247 ... STARINTF 0.61 [0.01]
SEARCH,OBJECT,DISPERSED 12:10:32.63 +39:24:20.7 155.076719 75.063247 ... STARINTF 0.54 [0.01]
SEARCH,OBJECT,DISPERSED 12:10:32.63 +39:24:20.7 155.076719 75.063247 ... STARINTF 0.53 [0.01]
TRACK,OBJECT,DISPERSED 12:10:32.63 +39:24:20.7 155.076719 75.063247 ... STARINTF 0.51 [0.01]
TRACK,OBJECT,DISPERSED 12:10:32.63 +39:24:20.7 155.076719 75.063247 ... STARINTF 0.51 [0.01]
TRACK,OBJECT,DISPERSED 12:10:32.63 +39:24:20.7 155.076719 75.063247 ... STARINTF 0.51 [0.01]
PHOTOMETRY,OBJECT 12:10:32.63 +39:24:20.7 155.076719 75.063247 ... STARINTF 0.54 [0.01]
PHOTOMETRY,OBJECT 12:10:32.63 +39:24:20.7 155.076719 75.063247 ... STARINTF 0.54 [0.01]
Release Date Object RA ... DPR.TECH INS.MODE DIMM Seeing-avg
------------ ----------------------- ---------- ... -------------------- -------- ---------------
2008-02-07 NGC4151 182.635969 ... IMAGE,WINDOW STARINTF 0.69 [0.01]
2008-02-07 NGC4151 182.635969 ... IMAGE,WINDOW STARINTF 0.68 [0.01]
2008-02-07 NGC4151 182.635969 ... IMAGE,WINDOW STARINTF 0.68 [0.01]
2008-02-07 NGC4151 182.635969 ... IMAGE,WINDOW STARINTF 0.69 [0.01]
2008-02-07 NGC4151 182.635969 ... IMAGE,WINDOW STARINTF 0.69 [0.01]
2008-02-07 NGC4151 182.635969 ... IMAGE,WINDOW STARINTF 0.74 [0.01]
2008-02-07 NGC4151 182.635969 ... IMAGE,WINDOW STARINTF 0.69 [0.01]
2008-02-07 NGC4151 182.635969 ... IMAGE,WINDOW STARINTF 0.66 [0.01]
2008-02-07 NGC4151 182.635969 ... IMAGE,WINDOW STARINTF 0.64 [0.01]
2008-02-07 NGC4151 182.635969 ... IMAGE,WINDOW STARINTF 0.60 [0.01]
... ... ... ... ... ... ...
2007-02-07 TRACK,OBJECT,DISPERSED 182.635969 ... INTERFEROMETRY STARINTF 0.72 [0.01]
2007-02-07 SEARCH,OBJECT,DISPERSED 182.635969 ... INTERFEROMETRY STARINTF 0.62 [0.01]
2007-02-07 SEARCH,OBJECT,DISPERSED 182.635969 ... INTERFEROMETRY STARINTF 0.61 [0.01]
2007-02-07 SEARCH,OBJECT,DISPERSED 182.635969 ... INTERFEROMETRY STARINTF 0.54 [0.01]
2007-02-07 SEARCH,OBJECT,DISPERSED 182.635969 ... INTERFEROMETRY STARINTF 0.53 [0.01]
2007-02-07 TRACK,OBJECT,DISPERSED 182.635969 ... INTERFEROMETRY STARINTF 0.51 [0.01]
2007-02-07 TRACK,OBJECT,DISPERSED 182.635969 ... INTERFEROMETRY STARINTF 0.51 [0.01]
2007-02-07 TRACK,OBJECT,DISPERSED 182.635969 ... INTERFEROMETRY STARINTF 0.51 [0.01]
2007-02-07 PHOTOMETRY,OBJECT 182.635969 ... IMAGE,WINDOW,CHOPNOD STARINTF 0.54 [0.01]
2007-02-07 PHOTOMETRY,OBJECT 182.635969 ... IMAGE,WINDOW,CHOPNOD STARINTF 0.54 [0.01]
Length = 38 rows

And indeed, 38 datasets are found, and the ``DATE OBS`` column is in the result table.
Expand All @@ -224,27 +226,42 @@ is identical to :meth:`~astroquery.eso.EsoClass.query_instrument`.
ESO instruments without a specific query interface can be queried with
:meth:`~astroquery.eso.EsoClass.query_main`, specifying the ``instrument`` constraint.
This is the case of e.g. ``harps``, ``feros`` or the all sky cameras APICAM and MASCOT. Here is an example to
query all-sky images from APICAM with ``luminance`` filter.
query all-sky images from APICAM with ``luminance`` filter.

.. code-block:: python
.. doctest-remote-data::

>>> eso.ROW_LIMIT = -1 # Return all results
>>> table = eso.query_main(column_filters={'instrument': 'APICAM', 'filter_path': 'LUMINANCE',
... 'stime':'2019-04-26', 'etime':'2019-04-27'}, cache=False)
>>> print(len(table))
207
>>> print(table.columns)
<TableColumns names=('OBJECT','RA','DEC','Program_ID','Instrument','Category','Type','Mode','Dataset ID','Release_Date','TPL ID','TPL START','Exptime','Exposure','Filter','MJD-OBS','Airmass','DIMM Seeing at Start')>
<TableColumns names=('OBJECT','RA','DEC','Program_ID','Instrument','Category','Type','Mode','Dataset ID','Release_Date','TPL ID','TPL START','Exptime','Exposure','filter_lambda_min','filter_lambda_max','MJD-OBS','Airmass','DIMM Seeing at Start')>
>>> table.pprint(max_width=100)
OBJECT RA DEC Program_ID ... Filter MJD-OBS Airmass DIMM Seeing at Start
------- ----------- ----------- ------------ ... --------- ------------ ------- --------------------
ALL SKY 09:18:37.39 -24:32:32.7 60.A-9008(A) ... LUMINANCE 58599.987766 1.0 N/A
ALL SKY 09:21:07.68 -24:32:30.1 60.A-9008(A) ... LUMINANCE 58599.989502 1.0 N/A
ALL SKY 09:23:38.98 -24:32:27.5 60.A-9008(A) ... LUMINANCE 58599.99125 1.0 N/A
... ... ... ... ... ... ... ... ...
ALL SKY 11:47:35.12 -24:31:07.7 60.A-9008(A) ... LUMINANCE 58600.091019 1.0 N/A
ALL SKY 11:50:07.40 -24:31:07.6 60.A-9008(A) ... LUMINANCE 58600.092778 1.0 N/A
Length = 50 rows
OBJECT RA DEC Program_ID ... MJD-OBS Airmass DIMM Seeing at Start
------- ----------- ----------- ------------ ... ------------ ------- --------------------
ALL SKY 09:18:37.39 -24:32:32.7 60.A-9008(A) ... 58599.987766 1.0 N/A
ALL SKY 09:21:07.68 -24:32:30.1 60.A-9008(A) ... 58599.989502 1.0 N/A
ALL SKY 09:23:38.98 -24:32:27.5 60.A-9008(A) ... 58599.99125 1.0 N/A
ALL SKY 09:26:10.28 -24:32:24.9 60.A-9008(A) ... 58599.992998 1.0 N/A
ALL SKY 09:28:40.58 -24:32:22.4 60.A-9008(A) ... 58599.994734 1.0 N/A
ALL SKY 09:31:43.93 -24:32:19.4 60.A-9008(A) ... 58599.996852 1.0 N/A
ALL SKY 09:34:15.23 -24:32:17.0 60.A-9008(A) ... 58599.9986 1.0 N/A
ALL SKY 09:36:47.53 -24:32:14.5 60.A-9008(A) ... 58600.000359 1.0 N/A
ALL SKY 09:39:18.82 -24:32:12.2 60.A-9008(A) ... 58600.002106 1.0 N/A
ALL SKY 09:41:49.11 -24:32:09.9 60.A-9008(A) ... 58600.003843 1.0 N/A
... ... ... ... ... ... ... ...
ALL SKY 19:07:39.21 -24:39:35.1 60.A-9008(A) ... 58600.395914 1.0 N/A
ALL SKY 19:10:11.68 -24:39:39.1 60.A-9008(A) ... 58600.397674 1.0 N/A
ALL SKY 19:12:44.15 -24:39:43.2 60.A-9008(A) ... 58600.399433 1.0 N/A
ALL SKY 19:15:15.62 -24:39:47.1 60.A-9008(A) ... 58600.401181 1.0 N/A
ALL SKY 19:17:46.09 -24:39:51.1 60.A-9008(A) ... 58600.402917 1.0 N/A
ALL SKY 19:20:46.65 -24:39:55.8 60.A-9008(A) ... 58600.405 1.0 N/A
ALL SKY 19:23:18.12 -24:39:59.7 60.A-9008(A) ... 58600.406748 1.0 N/A
ALL SKY 19:25:51.60 -24:40:03.7 60.A-9008(A) ... 58600.408519 1.0 N/A
ALL SKY 19:28:22.08 -24:40:07.6 60.A-9008(A) ... 58600.410255 1.0 N/A
ALL SKY 19:30:52.55 -24:40:11.4 60.A-9008(A) ... 58600.411991 1.0 N/A
Length = 207 rows


Query the ESO archive for reduced data
Expand All @@ -258,7 +275,7 @@ Identify available surveys

The list of available surveys can be obtained with :meth:`astroquery.eso.EsoClass.list_surveys` as follows:

.. code-block:: python
.. doctest-remote-data::

>>> surveys = eso.list_surveys()

Expand All @@ -269,7 +286,8 @@ Let's assume that we work with the ``HARPS`` survey, and that we are interested
target ``HD203608``.
The archive can be queried as follows:

.. code-block:: python

.. doctest-remote-data::

>>> table = eso.query_surveys('HARPS', cache=False, target="HD203608")

Expand All @@ -284,37 +302,40 @@ Only a small subset of the keywords presents in the data products can be obtaine
with :meth:`~astroquery.eso.EsoClass.query_instrument` or :meth:`~astroquery.eso.EsoClass.query_main`.
There is however a way to get the full primary header of the FITS data products,
using :meth:`~astroquery.eso.EsoClass.get_headers`.
This method is detailed in the example below, continuing with the previously obtained table.
This method is detailed in the example below.


.. code-block:: python
.. doctest-remote-data::

>>> table = eso.query_instrument('midi', column_filters={'target':'NGC 4151',
... 'stime':'2007-01-01',
... 'etime':'2008-01-01'},
... columns=['night'])
>>> table_headers = eso.get_headers(table['DP.ID'])
>>> table_headers.pprint()
ARCFILE BITPIX ... TELESCOP UTC
--------------------------------- ------ ... ------------ -------
MIDI.2007-02-07T07:01:51.000.fits 16 ... ESO-VLTI-U23 25300.5
MIDI.2007-02-07T07:02:49.000.fits 16 ... ESO-VLTI-U23 25358.5
MIDI.2007-02-07T07:03:30.695.fits 16 ... ESO-VLTI-U23 25358.5
MIDI.2007-02-07T07:05:47.000.fits 16 ... ESO-VLTI-U23 25538.5
MIDI.2007-02-07T07:06:28.695.fits 16 ... ESO-VLTI-U23 25538.5
MIDI.2007-02-07T07:09:03.000.fits 16 ... ESO-VLTI-U23 25732.5
MIDI.2007-02-07T07:09:44.695.fits 16 ... ESO-VLTI-U23 25732.5
MIDI.2007-02-07T07:13:09.000.fits 16 ... ESO-VLTI-U23 25978.5
MIDI.2007-02-07T07:13:50.695.fits 16 ... ESO-VLTI-U23 25978.5
MIDI.2007-02-07T07:15:55.000.fits 16 ... ESO-VLTI-U23 26144.5
MIDI.2007-02-07T07:16:36.694.fits 16 ... ESO-VLTI-U23 26144.5
... ... ... ... ...
MIDI.2007-02-07T07:51:13.485.fits 16 ... ESO-VLTI-U23 28190.5
MIDI.2007-02-07T07:52:27.992.fits 16 ... ESO-VLTI-U23 28190.5
MIDI.2007-02-07T07:56:21.000.fits 16 ... ESO-VLTI-U23 28572.5
MIDI.2007-02-07T07:57:35.485.fits 16 ... ESO-VLTI-U23 28572.5
MIDI.2007-02-07T07:59:46.000.fits 16 ... ESO-VLTI-U23 28778.5
MIDI.2007-02-07T08:01:00.486.fits 16 ... ESO-VLTI-U23 28778.5
MIDI.2007-02-07T08:03:42.000.fits 16 ... ESO-VLTI-U23 29014.5
MIDI.2007-02-07T08:04:56.506.fits 16 ... ESO-VLTI-U23 29014.5
MIDI.2007-02-07T08:06:11.013.fits 16 ... ESO-VLTI-U23 29014.5
MIDI.2007-02-07T08:08:19.000.fits 16 ... ESO-VLTI-U23 29288.5
MIDI.2007-02-07T08:09:33.506.fits 16 ... ESO-VLTI-U23 29288.5
>>> table_headers.pprint() # doctest: +IGNORE_OUTPUT
DP.ID SIMPLE BITPIX ... HIERARCH ESO OCS TPL NFILE HIERARCH ESO OCS EXPO1 FNAME3
---------------------------- ------ ------ ... -------------------------- ---------------------------------
MIDI.2007-02-07T07:01:51.000 True 16 ... 0
MIDI.2007-02-07T07:02:49.000 True 16 ... 0
MIDI.2007-02-07T07:03:30.695 True 16 ... 0
MIDI.2007-02-07T07:05:47.000 True 16 ... 0
MIDI.2007-02-07T07:06:28.695 True 16 ... 0
MIDI.2007-02-07T07:09:03.000 True 16 ... 0
MIDI.2007-02-07T07:09:44.695 True 16 ... 0
MIDI.2007-02-07T07:13:09.000 True 16 ... 0
MIDI.2007-02-07T07:13:50.695 True 16 ... 0
MIDI.2007-02-07T07:15:55.000 True 16 ... 0
... ... ... ... ... ...
MIDI.2007-02-07T07:52:27.992 True 16 ... 8 MIDI.2007-02-07T07:52:27.992.fits
MIDI.2007-02-07T07:56:21.000 True 16 ... 0
MIDI.2007-02-07T07:57:35.485 True 16 ... 0
MIDI.2007-02-07T07:59:46.000 True 16 ... 0
MIDI.2007-02-07T08:01:00.486 True 16 ... 0
MIDI.2007-02-07T08:03:42.000 True 16 ... 8
MIDI.2007-02-07T08:04:56.506 True 16 ... 8
MIDI.2007-02-07T08:06:11.013 True 16 ... 8 MIDI.2007-02-07T08:06:11.013.fits
MIDI.2007-02-07T08:08:19.000 True 16 ... 8 MIDI.2007-02-07T08:06:11.013.fits
MIDI.2007-02-07T08:09:33.506 True 16 ... 8 MIDI.2007-02-07T08:06:11.013.fits
Length = 38 rows
>>> len(table_headers.columns)
340
Expand All @@ -329,7 +350,7 @@ Downloading datasets from the archive
Continuing from the query with constraints example, the first two datasets are selected,
using their data product IDs ``DP.ID`` (or ``ARCFILE`` for surveys), and retrieved from the ESO archive.

.. code-block:: python
.. doctest-skip::

>>> data_files = eso.retrieve_data(table['DP.ID'][:2])
Staging request...
Expand All @@ -354,12 +375,13 @@ would like to download datasets from an existing request, either submitted
through the functions here or externally, call ``retrieve_data`` with the
``request_id`` option:

.. code-block:: python
.. doctest-skip::

>>> data_files = eso.retrieve_data(table['DP.ID'][:2], request_id=999999)

The ``request_id`` can be found in the automatic email sent by the archive after
staging the initial request, i.e., https://dataportal.eso.org/rh/requests/[USERNAME]/{request_id}. A summary of your available requests is shown at https://dataportal.eso.org/rh/requests/[USERNAME]/recentRequests.
staging the initial request, i.e., https://dataportal.eso.org/rh/requests/[USERNAME]/{request_id}.
A summary of your available requests is shown at https://dataportal.eso.org/rh/requests/[USERNAME]/recentRequests.

Note: The function does check that the specified retrieval URL based on
``request_id`` is valid and then that the datasets indicated there are
Expand Down

0 comments on commit 5ac1834

Please sign in to comment.