Skip to content

Commit 223838d

Browse files
committed
docs! and update API to match the way I used it in the docs
1 parent 48a6c88 commit 223838d

File tree

6 files changed

+152
-14
lines changed

6 files changed

+152
-14
lines changed

README.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,7 @@ List of Modules
9191
* `Splatalogue <http://astroquery.readthedocs.org/en/latest/splatalogue/splatalogue.html>`_: National Radio Astronomy Observatory (NRAO)-maintained (mostly) molecular radio and millimeter line list service.
9292
* `CosmoSim <http://astroquery.readthedocs.org/en/latest/cosmosim/cosmosim.html>`_: The CosmoSim database provides results from cosmological simulations performed within different projects: the MultiDark project, the BolshoiP project, and the CLUES project.
9393
* `ESO Archive <http://astroquery.readthedocs.org/en/latest/eso/eso.html>`_
94+
* `ALMA Archive <http://astroquery.readthedocs.org/en/latest/alma/alma.html>`_
9495
* `GAMA database <http://astroquery.readthedocs.org/en/latest/gama/gama.html>`_
9596
* `NVAS archive <http://astroquery.readthedocs.org/en/latest/nvas/nvas.html>`_
9697
* `Open Expolanet Catalog (OEC) <http://astroquery.readthedocs.org/en/latest/open_exoplanet_catalogue/open_exoplanet_catalogue.html>`_

astroquery/alma/core.py

Lines changed: 35 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,7 @@ def query_region_async(self, coordinate, radius, cache=True, public=True,
5454
"""
5555
5656
"""
57+
coordinate = commons.parse_coordinates(coordinate)
5758
cstr = coordinate.fk5.to_string(style='hmsdms', sep=':')
5859
rdc = "{cstr}, {rad}".format(cstr=cstr, rad=radius.to(u.deg).value)
5960

@@ -141,7 +142,33 @@ def stage_data(self, uids, cache=False):
141142

142143
return data_file_urls
143144

144-
def download_data(self, uids, cache=True):
145+
def data_size(self, files):
146+
"""
147+
Given a list of file URLs, return the data size. This is useful for
148+
assessing how much data you might be downloading!
149+
"""
150+
totalsize = 0
151+
pb = ProgressBar(len(files))
152+
for ii,fileLink in enumerate(files):
153+
response = self._request('HEAD', fileLink, stream=True,
154+
cache=False, timeout=self.TIMEOUT)
155+
totalsize += int(response.headers['content-length'])
156+
pb.update(ii+1)
157+
158+
return (totalsize*u.B).to(u.GB)
159+
160+
def download_files(self, files, cache=True):
161+
"""
162+
Given a list of file URLs, download them
163+
"""
164+
downloaded_files = []
165+
for fileLink in files:
166+
filename = self._request("GET", fileLink, save=True,
167+
timeout=self.TIMEOUT)
168+
downloaded_files.append(filename)
169+
return downloaded_files
170+
171+
def retrieve_data_from_uid(self, uids, cache=True):
145172
"""
146173
Stage & Download ALMA data. Will print out the expected file size
147174
before attempting the download.
@@ -160,24 +187,18 @@ def download_data(self, uids, cache=True):
160187
downloaded_files : list
161188
A list of the downloaded file paths
162189
"""
190+
if isinstance(uids, six.string_types):
191+
uids = [uids]
192+
if not isinstance(uids, (list, tuple, np.ndarray)):
193+
raise TypeError("Datasets must be given as a list of strings.")
163194

164195
files = self.stage_data(uids, cache=cache)
165196

166197
log.info("Determining download size for {0} files...".format(len(files)))
167-
totalsize = 0
168-
pb = ProgressBar(len(files))
169-
for ii,fileLink in enumerate(files):
170-
response = self._request('GET', fileLink, stream=True,
171-
timeout=self.TIMEOUT)
172-
totalsize += int(response.headers['content-length'])
173-
pb.update(ii+1)
198+
totalsize = self.data_size(files)
174199

175-
log.info("Downloading files of size {0}...".format((totalsize*u.B).to(u.GB)))
176-
downloaded_files = []
177-
for fileLink in files:
178-
filename = self._request("GET", fileLink, save=True,
179-
timeout=self.TIMEOUT)
180-
downloaded_files.append(filename)
200+
log.info("Downloading files of size {0}...".format(totalsize.to(u.GB)))
201+
downloaded_files = self.download_files(files, cache=cache)
181202

182203
return downloaded_files
183204

astroquery/alma/tests/test_alma_remote.py

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,3 +40,32 @@ def test_stage_data(self, temp_dir):
4040
uid = result_s['Asdm_uid'][0]
4141

4242
alma.stage_data([uid])
43+
44+
def test_doc_example(self, temp_dir):
45+
alma = Alma()
46+
alma.cache_location = temp_dir
47+
48+
from astroquery.alma import Alma
49+
from astropy import units as u
50+
from astropy import coordinates
51+
import numpy as np
52+
alma = Alma()
53+
m83_data = alma.query_object('M83')
54+
assert m83_data.colnames == ['Project_code', 'Source_name', 'RA',
55+
'Dec', 'Band', 'Frequency_resolution',
56+
'Integration', 'Release_date',
57+
'Frequency_support',
58+
'Velocity_resolution', 'Pol_products',
59+
'Observation_date', 'PI_name', 'PWV',
60+
'Member_ous_id', 'Asdm_uid',
61+
'Project_title', 'Project_type',
62+
'Scan_intent']
63+
galactic_center = coordinates.SkyCoord(0*u.deg, 0*u.deg,
64+
frame='galactic')
65+
gc_data = alma.query_region(galactic_center, 1*u.deg)
66+
67+
uids = np.unique(m83_data['Asdm_uid'])
68+
assert 'uid://A002/X3b3400/X90f' in uids
69+
70+
link_list = alma.stage_data(uids[0:2])
71+
alma.data_size(link_list)

astroquery/query.py

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,8 @@ def __init__(self, response=None, url=None, encoding=None, content=None,
3333
if stream:
3434
self.iter_content = response.iter_content
3535
self.content = response.content
36+
# Needed for assessing file size:
37+
self.headers = response.headers
3638
elif not hasattr(response, 'content'):
3739
raise TypeError("{0} is not a requests.Response".format(response))
3840
elif not isinstance(response, requests.Response):

docs/alma/alma.rst

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,4 +37,87 @@ via the ALMA CAS (central authentication server).
3737
Authenticating ICONDOR on asa.alma.cl...
3838
Authentication successful!
3939
40+
Querying Targets and Regions
41+
============================
4042

43+
You can query by object name or by circular region:
44+
45+
.. code-block:: python
46+
47+
>>> from astroquery.alma import Alma
48+
>>> m83_data = Alma.query_object('M83')
49+
>>> print(len(m83_data))
50+
225
51+
>>> m83_data.colnames
52+
['Project_code', 'Source_name', 'RA', 'Dec', 'Band',
53+
'Frequency_resolution', 'Integration', 'Release_date', 'Frequency_support',
54+
'Velocity_resolution', 'Pol_products', 'Observation_date', 'PI_name',
55+
'PWV', 'Member_ous_id', 'Asdm_uid', 'Project_title', 'Project_type',
56+
'Scan_intent']
57+
58+
59+
Region queries are just like any other in astroquery:
60+
61+
.. code-block:: python
62+
63+
>>> from astropy import coordinates
64+
>>> from astropy import units as u
65+
>>> galactic_center = coordinates.SkyCoord(0*u.deg, 0*u.deg,
66+
... frame='galactic')
67+
>>> gc_data = Alma.query_region(galactic_center, 1*u.deg)
68+
>>> print(len(gc_data))
69+
82
70+
71+
Downloading Data
72+
================
73+
74+
You can download ALMA data with astroquery, but be forewarned, cycle 0 and
75+
cycle 1 data sets tend to be >100 GB!
76+
77+
78+
.. code-block:: python
79+
80+
>>> import numpy as np
81+
>>> uids = np.unique(m83_data['Asdm_uid'])
82+
>>> print(uids)
83+
Asdm_uid
84+
-----------------------
85+
uid://A002/X3b3400/X90f
86+
uid://A002/X3b3400/Xaf3
87+
uid://A002/X3fbe56/X607
88+
uid://A002/X4b29af/X24c
89+
uid://A002/X4b29af/X5c
90+
91+
You can then stage the data and see how big it is (you can ask for one or more
92+
UIDs):
93+
94+
95+
.. code-block:: python
96+
97+
>>> link_list = Alma.stage_data(uids[0:2])
98+
>>> Alma.data_size(link_list)
99+
INFO: Staging files... [astroquery.alma.core]
100+
<Quantity 146.51379712000002 Gbyte>
101+
102+
You can then go on to download that data. The download will be cached so that repeat
103+
queries of the same file will not re-download the data. The default cache
104+
directory is `~/.astropy/cache/astroquery/Alma/`, but this can be changed by
105+
changing the ``cache_location`` variable:
106+
107+
.. code-block:: python
108+
109+
>>> myAlma = Alma()
110+
>>> myAlma.cache_location = '/big/external/drive/'
111+
>>> myAlma.download_files(link_list, cache=True)
112+
113+
You can also do the downloading all in one step:
114+
115+
.. code-block:: python
116+
117+
>>> myAlma.retrieve_data_from_uid(uids[0])
118+
119+
Reference/API
120+
=============
121+
122+
.. automodapi:: astroquery.alma
123+
:no-inheritance-diagram:

docs/index.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,7 @@ The following modules have been completed using a common API:
120120
eso/eso.rst
121121
xmatch/xmatch.rst
122122
atomic/atomic.rst
123+
alma/alma.rst
123124

124125
These others are functional, but do not follow a common & consistent API:
125126

@@ -175,6 +176,7 @@ generally return a table listing the available data first.
175176
:maxdepth: 1
176177

177178
alfalfa/alfalfa.rst
179+
alma/alma.rst
178180
eso/eso.rst
179181
fermi/fermi.rst
180182
irsa/irsa.rst

0 commit comments

Comments
 (0)