Skip to content

Commit 23d3471

Browse files
bsipoczbsipocz
authored
Merge pull request #3170 from cds-astro/doc-vizier-notes
docs: reformulate the section on downloading a whole catalog
2 parents 49103b7 + 93adae7 commit 23d3471

File tree

1 file changed

+79
-56
lines changed

1 file changed

+79
-56
lines changed

‎docs/vizier/vizier.rst

Lines changed: 79 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,8 @@ individual columns before retrieving the results.
2121
In astroquery >=0.4.8, the column names are the same in VizieR's webpages and in
2222
the tables received (for the two examples: you'll see ``r'mag`` and ``2MASS``).
2323

24-
Table Discover
25-
--------------
24+
Catalogs exploration
25+
--------------------
2626

2727
If you want to search for a set of tables, e.g. based on author name or other keywords,
2828
the :meth:`~astroquery.vizier.VizierClass.find_catalogs` tool can be used:
@@ -40,55 +40,97 @@ the :meth:`~astroquery.vizier.VizierClass.find_catalogs` tool can be used:
4040
J/AJ/157/217 : Transit times of five hot Jupiter WASP exoplanets (Bouma+, 2019)
4141
J/A+A/635/A122 : CoRoT-30b and CoRoT-31b radial velocity curves (Border+, 2020)
4242

43-
From this result, you could either get any of these as a complete catalog or
44-
query them for individual objects or regions.
43+
From this list, you can either get any catalog completely (all the lines) or make
44+
sub-selections with :meth:`~astroquery.vizier.VizierClass.query_region`,
45+
or with additional criteria.
4546

4647
Get a whole catalog
4748
-------------------
4849

50+
From the result of the precedent example, let's select ``J/ApJ/788/39``.
51+
We call :meth:`~astroquery.vizier.VizierClass.get_catalogs`. Let's fix the number of
52+
returned rows to 1 for now, to minimize the amount of data we download and speed up
53+
exploration, while we inspect the result:
54+
55+
.. doctest-remote-data::
56+
57+
>>> vizier.ROW_LIMIT = 1
58+
>>> exoplanets = vizier.get_catalogs("J/ApJ/788/39")
59+
>>> exoplanets
60+
TableList with 2 tables:
61+
'0:J/ApJ/788/39/stars' with 7 column(s) and 1 row(s)
62+
'1:J/ApJ/788/39/table4' with 48 column(s) and 1 row(s)
63+
64+
.. note::
65+
66+
``ROW_LIMIT`` is set to 50 per default.
67+
68+
We see that this catalog has two tables. One named ``J/ApJ/788/39/stars`` and the
69+
other one is ``J/ApJ/788/39/table4``.
4970

50-
If you know the name of the catalog you wish to retrieve, e.g. from doing a
51-
:meth:`~astroquery.vizier.VizierClass.find_catalogs` search as above, you can then grab
52-
the complete contents of those catalogs:
71+
Let's look at the columns of ``J/ApJ/788/39/stars`` from the single row that we just
72+
downloaded:
5373

5474
.. doctest-remote-data::
5575

56-
>>> catalogs = vizier.get_catalogs(catalog_list.keys())
57-
>>> print(catalogs) # doctest: +IGNORE_OUTPUT
58-
TableList with 10 tables:
59-
'0:J/A+A/635/A205/20140119' with 7 column(s) and 50 row(s)
60-
'1:J/A+A/635/A205/20140123' with 7 column(s) and 50 row(s)
61-
'2:J/A+A/635/A205/20171231' with 7 column(s) and 50 row(s)
62-
'3:J/A+A/635/A205/20180114' with 7 column(s) and 50 row(s)
63-
'4:J/A+A/635/A205/ccf-mask' with 3 column(s) and 50 row(s)
64-
'5:J/ApJ/788/39/stars' with 7 column(s) and 17 row(s)
65-
'6:J/ApJ/788/39/table4' with 48 column(s) and 50 row(s)
66-
'7:J/AJ/157/217/transits' with 8 column(s) and 50 row(s)
67-
'8:J/A+A/635/A122/table2' with 4 column(s) and 18 row(s)
68-
'9:J/A+A/635/A122/table3' with 4 column(s) and 17 row(s)
76+
>>> exoplanets[0]
77+
<Table length=1>
78+
Name RAJ2000 DEJ2000 Vmag Name1 lines Simbad
79+
mag
80+
str9 str11 str11 float32 str8 str5 str6
81+
------- ----------- ----------- ------- ------ ----- ------
82+
CoRoT-2 19 27 06.50 +01 23 01.4 12.57 COROT2 lines Simbad
83+
84+
.. note::
6985

70-
Similarly, the ``Resource`` objects (the values of the dictionary resulting from
71-
:meth:`~astroquery.vizier.VizierClass.find_catalogs`) can be used in the same
72-
way:
86+
The coordinates columns often have the information about the frame and epoch in
87+
their descriptions:
7388

7489
.. doctest-remote-data::
7590

76-
>>> catalogs = vizier.get_catalogs(catalog_list.values())
77-
>>> print(catalogs) # doctest: +IGNORE_OUTPUT
78-
TableList with 10 tables:
79-
'0:J/A+A/635/A205/20140119' with 7 column(s) and 50 row(s)
80-
'1:J/A+A/635/A205/20140123' with 7 column(s) and 50 row(s)
81-
'2:J/A+A/635/A205/20171231' with 7 column(s) and 50 row(s)
82-
'3:J/A+A/635/A205/20180114' with 7 column(s) and 50 row(s)
83-
'4:J/A+A/635/A205/ccf-mask' with 3 column(s) and 50 row(s)
84-
'5:J/ApJ/788/39/stars' with 7 column(s) and 17 row(s)
85-
'6:J/ApJ/788/39/table4' with 48 column(s) and 50 row(s)
86-
'7:J/AJ/157/217/transits' with 8 column(s) and 50 row(s)
87-
'8:J/A+A/635/A122/table2' with 4 column(s) and 18 row(s)
88-
'9:J/A+A/635/A122/table3' with 4 column(s) and 17 row(s)
91+
>>> exoplanets[0]["RAJ2000"].description
92+
'Simbad Hour of Right Ascension (J2000)'
93+
94+
When we're ready to download the complete table, we can set the row limit to -1 (for
95+
infinity).
96+
97+
.. doctest-remote-data::
98+
99+
>>> vizier.ROW_LIMIT = -1
100+
>>> stars = vizier.get_catalogs("J/ApJ/788/39/stars")
101+
>>> # stars is a TableList with only one table. Here is its first and only element
102+
>>> stars[0]
103+
<Table length=17>
104+
Name RAJ2000 DEJ2000 Vmag Name1 lines Simbad
105+
mag
106+
str9 str11 str11 float32 str8 str5 str6
107+
--------- ----------- ----------- ------- -------- ----- ------
108+
CoRoT-2 19 27 06.50 +01 23 01.4 12.57 COROT2 lines Simbad
109+
TrES-4 17 53 13.06 +37 12 42.4 11.59 TRES4 lines Simbad
110+
TrES-2 19 07 14.04 +49 18 59.1 11.25 TRES2 lines Simbad
111+
WASP-2 20 30 54.13 +06 25 46.4 11.98 WASP2 lines Simbad
112+
WASP-12 06 30 32.79 +29 40 20.3 11.57 WASP12 lines Simbad
113+
HD 149026 16 30 29.62 +38 20 50.3 8.14 HD149026 lines Simbad
114+
HAT-P-1 22 57 46.84 +38 40 30.3 10.40 HATP1 lines Simbad
115+
XO-2S 07 48 07.48 +50 13 03.3 11.25 XO2S lines Simbad
116+
XO-2N 07 48 06.47 +50 13 33.0 11.25 XO2N lines Simbad
117+
XO-1 16 02 11.85 +28 10 10.4 11.25 XO1 lines Simbad
118+
TRES-3 17 52 07.02 +37 32 46.2 12.40 TRES3 lines Simbad
119+
HD 189733 20 00 43.71 +22 42 39.1 7.68 HD189733 lines Simbad
120+
HD 80606 09 22 37.58 +50 36 13.4 9.00 HD80606 lines Simbad
121+
HAT-P-7 19 28 59.35 +47 58 10.2 10.48 HATP7 lines Simbad
122+
HAT-P-13 08 39 31.81 +47 21 07.3 10.42 HATP13 lines Simbad
123+
HAT-P-16 00 38 17.56 +42 27 47.2 10.91 HATP16 lines Simbad
124+
WASP-32 00 15 50.81 +01 12 01.6 11.26 WASP32 lines Simbad
125+
126+
127+
Alternatively, we could have downloaded all the catalogs from the results of
128+
:meth:`~astroquery.vizier.VizierClass.find_catalogs`.
129+
Be careful when doing so, as this might be huge.
89130

90131
.. doctest-remote-data::
91132

133+
>>> vizier.ROW_LIMIT = 50 # we reset to the default value
92134
>>> catalogs = vizier.get_catalogs(catalog_list.keys())
93135
>>> print(catalogs) # doctest: +IGNORE_OUTPUT
94136
TableList with 10 tables:
@@ -103,26 +145,7 @@ way:
103145
'8:J/A+A/635/A122/table2' with 4 column(s) and 18 row(s)
104146
'9:J/A+A/635/A122/table3' with 4 column(s) and 17 row(s)
105147

106-
Note that the row limit is set to 50 by default, so if you want to get a truly
107-
complete catalog, you need to change that:
108-
109-
.. doctest-remote-data::
110-
111-
>>> vizier.ROW_LIMIT = -1
112-
>>> catalogs = vizier.get_catalogs(catalog_list.keys())
113-
>>> print(catalogs) # doctest: +IGNORE_OUTPUT
114-
TableList with 10 tables:
115-
'0:J/A+A/635/A205/20140119' with 7 column(s) and 235 row(s)
116-
'1:J/A+A/635/A205/20140123' with 7 column(s) and 195 row(s)
117-
'2:J/A+A/635/A205/20171231' with 7 column(s) and 248 row(s)
118-
'3:J/A+A/635/A205/20180114' with 7 column(s) and 307 row(s)
119-
'4:J/A+A/635/A205/ccf-mask' with 3 column(s) and 1828 row(s)
120-
'5:J/ApJ/788/39/stars' with 7 column(s) and 17 row(s)
121-
'6:J/ApJ/788/39/table4' with 48 column(s) and 106 row(s)
122-
'7:J/AJ/157/217/transits' with 8 column(s) and 236 row(s)
123-
'8:J/A+A/635/A122/table2' with 4 column(s) and 18 row(s)
124-
'9:J/A+A/635/A122/table3' with 4 column(s) and 17 row(s)
125-
>>> vizier.ROW_LIMIT = 50
148+
We downloaded the 50 first rows of these 10 tables.
126149

127150
Get a catalog's associated metadata
128151
-----------------------------------

0 commit comments

Comments
 (0)