Skip to content

Commit 815fce3

Browse files
juanmcloaizajuanmcloaiza
committed
Update documentation and docstrings
1 parent c4cc1f1 commit 815fce3

File tree

2 files changed

+118
-67
lines changed

2 files changed

+118
-67
lines changed

‎astroquery/eso/core.py‎

Lines changed: 17 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -277,6 +277,7 @@ def _tap_service(self, authenticated: bool = False) -> TAPService:
277277
"<eso_class_instance>.login(username=<your_username>"
278278
)
279279

280+
log.debug(f"Querying from {self._tap_url()}")
280281
if authenticated:
281282
h = self._get_auth_header()
282283
self._session.headers = {**self._session.headers, **h}
@@ -469,7 +470,10 @@ def query_surveys(
469470
Note that authenticated queries are slower. Default is `False`.
470471
:type authenticated: bool
471472
472-
:param column_filters: Constraints applied to the query. Default is `None`.
473+
:param column_filters: Constraints applied to the query in ADQL syntax,
474+
``{"column_name": "<adql_operator> <value>"}``. For example:
475+
``{"exp_start": "between '2024-12-31' and '2025-12-31'"}``
476+
Default is `None`.
473477
:type column_filters: dict, `None`
474478
475479
:param open_form: **Deprecated** - unused.
@@ -565,7 +569,10 @@ def query_main(
565569
Note that authenticated queries are slower. Default is `False`.
566570
:type authenticated: bool
567571
568-
:param column_filters: Constraints applied to the query. Default is `None`.
572+
:param column_filters: Constraints applied to the query in ADQL syntax,
573+
``{"column_name": "<adql_operator> <value>"}``. For example:
574+
``{"exp_start": "between '2024-12-31' and '2025-12-31'"}``
575+
Default is `None`.
569576
:type column_filters: dict, `None`
570577
571578
:param open_form: **Deprecated** - unused.
@@ -660,7 +667,10 @@ def query_instrument(
660667
Note that authenticated queries are slower. Default is `False`.
661668
:type authenticated: bool
662669
663-
:param column_filters: Constraints applied to the query. Default is `None`.
670+
:param column_filters: Constraints applied to the query in ADQL syntax,
671+
``{"column_name": "<adql_operator> <value>"}``. For example:
672+
``{"exp_start": "between '2024-12-31' and '2025-12-31'"}``
673+
Default is `None`.
664674
:type column_filters: dict, `None`
665675
666676
:param open_form: **Deprecated** - unused.
@@ -1047,7 +1057,10 @@ def query_apex_quicklooks(self,
10471057
Note that authenticated queries are slower. Default is `False`.
10481058
:type authenticated: bool
10491059
1050-
:param column_filters: Constraints applied to the query. Default is `None`.
1060+
:param column_filters: Constraints applied to the query in ADQL syntax,
1061+
``{"column_name": "<adql_operator> <value>"}``. For example:
1062+
``{"exp_start": "between '2024-12-31' and '2025-12-31'"}``
1063+
Default is `None`.
10511064
:type column_filters: dict, `None`
10521065
10531066
:param open_form: **Deprecated** - unused.

‎docs/eso/eso.rst‎

Lines changed: 101 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,34 @@
44
ESO Queries (`astroquery.eso`)
55
******************************
66

7+
.. warning::
8+
9+
Backward Compatibility Notice
10+
==============================
11+
12+
On replacing the backend WDB by TAP
13+
The WDB (Web DataBase) API is being deprecated and replaced by TAP (Table Access Protocol),
14+
a standardized interface for querying astronomical datasets using ADQL (Astronomical Data Query Language).
15+
While the Python interface remains the same, the ``columns`` and ``column_filters``
16+
parameters have been updated to reflect TAP's field names and ADQL syntax. This means that
17+
although the structure of your code won't need to change,
18+
the values passed to these arguments must be revised to comply with the new format.
19+
20+
In TAP, column_filters accepts SQL-like ADQL expressions. For example:
21+
22+
.. doctest-skip::
23+
24+
column_filters = {
25+
'some_int_column': "< 5",
26+
'some_float_column_2': ">= 1.23",
27+
'some_char_column': "like '%John%'",
28+
'some_generic_column': "in ('mango', 'apple', 'kiwi')",
29+
'other_generic_column': "between '2024-01-01' and '2024-12-31'"
30+
}
31+
32+
Please review your queries carefully and update them accordingly to ensure compatibility with the new astroquery versions.
33+
34+
735
Getting started
836
===============
937

@@ -14,10 +42,10 @@ For now, it supports the following:
1442
- listing available surveys (phase 3)
1543
- searching INSTRUMENT SPECIFIC raw data (table ``ist.<instrument_name>``) via the ESO TAP service*
1644
- searching data products (phase 3; table ``ivoa.ObsCore``) via the ESO TAP service*
17-
- searching raw data (table ``dbo.raw``)via the ESO TAP service*
45+
- searching raw data (table ``dbo.raw``) via the ESO TAP service*
1846
- downloading data by dataset identifiers: http://archive.eso.org/cms/eso-data/eso-data-direct-retrieval.html
1947

20-
\* ESO TAP website: https://archive.eso.org/programmatic/#TAP
48+
\* ESO TAP web interface: https://archive.eso.org/programmatic/#TAP
2149

2250
Requirements
2351
============
@@ -149,35 +177,35 @@ as certain columns with datatype ``char`` actually define timestamps or regions
149177
.. doctest-remote-data::
150178

151179
>>> eso.query_instrument('midi', help=True) # doctest: +IGNORE_OUTPUT
152-
INFO:
180+
INFO:
153181
Columns present in the table ist.midi:
154-
column_name datatype xtype unit
182+
column_name datatype xtype unit
155183
------------------- -------- ----------- ------
156184
access_estsize long kbyte
157-
access_url char
158-
datalink_url char
159-
date_obs char
185+
access_url char
186+
datalink_url char
187+
date_obs char
160188
dec double deg
161-
del_ft_sensor char
162-
del_ft_status char
189+
del_ft_sensor char
190+
del_ft_status char
163191
det_dit float s
164-
det_ndit int
192+
det_ndit int
165193
dimm_fwhm_avg float arcsec
166194
dimm_fwhm_rms float arcsec
167-
dp_cat char
168-
dp_id char
195+
dp_cat char
196+
dp_id char
169197
... ...
170-
release_date char timestamp
171-
s_region char adql:REGION
198+
release_date char timestamp
199+
s_region char adql:REGION
172200
... ...
173-
telescope char
174-
tpl_expno int
175-
tpl_id char
176-
tpl_name char
177-
tpl_nexp int
178-
tpl_start char
201+
telescope char
202+
tpl_expno int
203+
tpl_id char
204+
tpl_name char
205+
tpl_nexp int
206+
tpl_start char
179207
utc float s
180-
208+
181209
Number of records present in the table ist.midi:
182210
421764
183211
[astroquery.eso.core]
@@ -195,12 +223,16 @@ target ``NGC 4151`` between ``2008-01-01`` and ``2009-05-12`` are searched, and
195223
return two columns: the date of observation and the name of the object.
196224

197225
.. doctest-remote-data::
198-
>>> table = eso.query_instrument('midi', column_filters={'object':'NGC4151'}, columns=['object', 'date_obs'])
199-
>>> t_2008 = table[table["date_obs"] >= "2008-01-01"]
200-
>>> t_2008_2009 = t_2008[t_2008["date_obs"] <= "2009-05-12"]
201-
>>> t_2008_2009
226+
>>> table = eso.query_instrument(
227+
'midi',
228+
column_filters={
229+
'object':'NGC4151',
230+
'exp_start': "between '2008-01-01' and '2009-05-12'"
231+
},
232+
columns=['object', 'date_obs'])
233+
>>> table
202234
<Table length=196>
203-
object date_obs
235+
object date_obs
204236
------- -----------------------
205237
NGC4151 2008-04-22T02:07:50.154
206238
NGC4151 2008-04-22T02:08:20.345
@@ -231,14 +263,18 @@ query all-sky images from APICAM with ``luminance`` filter.
231263
.. doctest-remote-data::
232264

233265
>>> eso.maxrec = -1 # Return all results
234-
#(i.e. do not truncate the query even if it is slow)
266+
# (i.e. do not truncate the query even if it is slow)
235267
>>> table = eso.query_main(column_filters={'instrument': 'APICAM',
236268
'filter_path': 'LUMINANCE'})
269+
270+
>>> table = eso.query_main(
271+
column_filters={
272+
'instrument': 'APICAM',
273+
'filter_path': 'LUMINANCE',
274+
'exp_start': "between '2019-04-26' and '2019-04-27'"
275+
}
276+
)
237277
>>> print(len(table))
238-
102147
239-
>>> table_filtered = table[table['date_obs']>='2019-04-26']
240-
>>> table_filtered = table_filtered[table_filtered['date_obs']<='2019-04-27']
241-
>>> len(table_filtered)
242278
215
243279
>>> print(table.columns)
244280
<TableColumns names=('access_estsize','access_url','datalink_url','date_obs',
@@ -251,9 +287,9 @@ query all-sky images from APICAM with ``luminance`` filter.
251287
'tel_airm_start','tel_alt','tel_ambi_fwhm_end','tel_ambi_fwhm_start',
252288
'tel_ambi_pres_end','tel_ambi_pres_start','tel_ambi_rhum','tel_az','telescope',
253289
'tpl_expno','tpl_id','tpl_name','tpl_nexp','tpl_seqno','tpl_start')>
254-
>>> table_filtered[["object", "ra", "dec", "date_obs", "prog_id"]].pprint(max_width=200)
255-
object ra dec date_obs prog_id
256-
deg deg
290+
>>> table[["object", "ra", "dec", "date_obs", "prog_id"]].pprint(max_width=200)
291+
object ra dec date_obs prog_id
292+
deg deg
257293
------- ------------ ------------ ----------------------- ------------
258294
ALL SKY 145.29212694 -24.53624194 2019-04-26T00:08:49.000 60.A-9008(A)
259295
ALL SKY 145.92251305 -24.53560305 2019-04-26T00:11:20.000 60.A-9008(A)
@@ -316,7 +352,7 @@ More details about this method in the next section.
316352
Obtaining extended information on data products
317353
===============================================
318354

319-
Only a small subset of the keywords presents in the data products can be obtained
355+
Only a small subset of the keywords present in the data products can be obtained
320356
with :meth:`~astroquery.eso.EsoClass.query_instrument` or :meth:`~astroquery.eso.EsoClass.query_main`.
321357
There is however a way to get the full primary header of the FITS data products,
322358
using :meth:`~astroquery.eso.EsoClass.get_headers`.
@@ -325,39 +361,38 @@ This method is detailed in the example below.
325361

326362
.. doctest-remote-data::
327363

328-
>>> table = eso.query_instrument('midi', column_filters={'object':'NGC4151'},
329-
... columns=['object', 'date_obs', 'dp_id'])
330-
>>> table_filtered = table[table['date_obs']<='2008-01-01']
331-
>>> table_headers = eso.get_headers(table_filtered["dp_id"])
364+
>>> table = eso.query_instrument('midi',
365+
column_filters={
366+
'object': 'NGC4151',
367+
'date_obs': "<='2008-01-01'"
368+
},
369+
columns=['object', 'date_obs', 'dp_id'])
370+
371+
>>> table_headers = eso.get_headers(table["dp_id"])
372+
>>> len(table_headers.columns)
373+
336
332374
>>> table_headers.pprint()
333-
DP.ID SIMPLE BITPIX ... HIERARCH ESO OCS EXPO7 FNAME2 HIERARCH ESO OCS EXPO8 FNAME1 HIERARCH ESO OCS EXPO8 FNAME2
375+
DP.ID SIMPLE BITPIX ... HIERARCH ESO OCS EXPO7 FNAME2 HIERARCH ESO OCS EXPO8 FNAME1 HIERARCH ESO OCS EXPO8 FNAME2
334376
---------------------------- ------ ------ ... --------------------------------- --------------------------------- ---------------------------------
335-
MIDI.2007-02-07T07:01:51.000 True 16 ...
336-
MIDI.2007-02-07T07:02:49.000 True 16 ...
337-
MIDI.2007-02-07T07:03:30.695 True 16 ...
338-
MIDI.2007-02-07T07:05:47.000 True 16 ...
339-
MIDI.2007-02-07T07:06:28.695 True 16 ...
340-
MIDI.2007-02-07T07:09:03.000 True 16 ...
341-
MIDI.2007-02-07T07:09:44.695 True 16 ...
342-
MIDI.2007-02-07T07:13:09.000 True 16 ...
343-
MIDI.2007-02-07T07:13:50.695 True 16 ...
344-
MIDI.2007-02-07T07:15:55.000 True 16 ...
345-
MIDI.2007-02-07T07:16:36.694 True 16 ...
346-
MIDI.2007-02-07T07:19:25.000 True 16 ...
347-
MIDI.2007-02-07T07:20:06.695 True 16 ... MIDI.2007-02-07T07:20:06.695.fits
348-
MIDI.2007-02-07T07:22:57.000 True 16 ... MIDI.2007-02-07T07:20:06.695.fits MIDI.2007-02-07T07:22:57.000.fits
377+
MIDI.2007-02-07T07:01:51.000 True 16 ...
378+
MIDI.2007-02-07T07:02:49.000 True 16 ...
379+
MIDI.2007-02-07T07:03:30.695 True 16 ...
380+
MIDI.2007-02-07T07:05:47.000 True 16 ...
381+
MIDI.2007-02-07T07:06:28.695 True 16 ...
382+
MIDI.2007-02-07T07:09:03.000 True 16 ...
383+
MIDI.2007-02-07T07:09:44.695 True 16 ...
384+
MIDI.2007-02-07T07:13:09.000 True 16 ...
385+
MIDI.2007-02-07T07:13:50.695 True 16 ...
386+
MIDI.2007-02-07T07:15:55.000 True 16 ...
387+
MIDI.2007-02-07T07:16:36.694 True 16 ...
388+
MIDI.2007-02-07T07:19:25.000 True 16 ...
389+
MIDI.2007-02-07T07:20:06.695 True 16 ... MIDI.2007-02-07T07:20:06.695.fits
390+
MIDI.2007-02-07T07:22:57.000 True 16 ... MIDI.2007-02-07T07:20:06.695.fits MIDI.2007-02-07T07:22:57.000.fits
349391
MIDI.2007-02-07T07:23:38.695 True 16 ... MIDI.2007-02-07T07:20:06.695.fits MIDI.2007-02-07T07:22:57.000.fits MIDI.2007-02-07T07:23:38.695.fits
350-
>>> len(table_headers.columns)
351-
336
352392

353393

354-
..
355-
## TODO ... Is this paragraph true?? What does it actually mean? To me it does not make sense.
356-
## As shown above, for each data product ID (``DP.ID``), the full header (336 columns in our case) of the archive
357-
## FITS file is collected. In the above table ``table_headers``, there are as many rows as in the column ``table['DP.ID']``.
358-
## The original paragraph reads:
359-
## As shown above, for each data product ID (``DP.ID``), the full header (570 columns in our case) of the archive
360-
## FITS file is collected. In the above table ``table_headers``, there are as many rows as in the column ``table['DP.ID']``.
394+
As shown above, for each data product ID (``DP.ID``), the full header (336 columns in our case) of the archive
395+
FITS file is collected. In the above table ``table_headers``, there are as many rows as in the column ``table['DP.ID']``.
361396

362397

363398
Downloading datasets from the archive
@@ -378,6 +413,9 @@ using their data product IDs ``dp_id``, and retrieved from the ESO archive.
378413
INFO: Uncompressing file /Users/foobar/.astropy/cache/astroquery/Eso/MIDI.2007-02-07T07:01:51.000.fits.Z [astroquery.eso.core]
379414
INFO: Uncompressing file /Users/foobar/.astropy/cache/astroquery/Eso/MIDI.2007-02-07T07:02:49.000.fits.Z [astroquery.eso.core]
380415
INFO: Done! [astroquery.eso.core]
416+
>>> data_files
417+
['/Users/foobar/.astropy/cache/astroquery/Eso/MIDI.2007-02-07T07:01:51.000.fits',
418+
'/Users/foobar/.astropy/cache/astroquery/Eso/MIDI.2007-02-07T07:02:49.000.fits']
381419

382420
The file names, returned in data_files, points to the decompressed datasets
383421
(without the .Z extension) that have been locally downloaded.

0 commit comments

Comments
 (0)