docs! and update API to match the way I used it in the docs

keflavich · keflavich · commit 223838d1e7ae · 2014-09-10T09:58:15.000+02:00
diff --git a/README.rst b/README.rst
@@ -91,6 +91,7 @@ List of Modules
   * `Splatalogue <http://astroquery.readthedocs.org/en/latest/splatalogue/splatalogue.html>`_: National Radio Astronomy Observatory (NRAO)-maintained (mostly) molecular radio and millimeter line list service.
   * `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. 
   * `ESO Archive <http://astroquery.readthedocs.org/en/latest/eso/eso.html>`_
+  * `ALMA Archive <http://astroquery.readthedocs.org/en/latest/alma/alma.html>`_
   * `GAMA database <http://astroquery.readthedocs.org/en/latest/gama/gama.html>`_
   * `NVAS archive <http://astroquery.readthedocs.org/en/latest/nvas/nvas.html>`_
   * `Open Expolanet Catalog (OEC) <http://astroquery.readthedocs.org/en/latest/open_exoplanet_catalogue/open_exoplanet_catalogue.html>`_
diff --git a/astroquery/alma/core.py b/astroquery/alma/core.py
@@ -54,6 +54,7 @@ def query_region_async(self, coordinate, radius, cache=True, public=True,
         """
 
         """
+        coordinate = commons.parse_coordinates(coordinate)
         cstr = coordinate.fk5.to_string(style='hmsdms', sep=':')
         rdc = "{cstr}, {rad}".format(cstr=cstr, rad=radius.to(u.deg).value)
 
@@ -141,7 +142,33 @@ def stage_data(self, uids, cache=False):
 
         return data_file_urls
 
-    def download_data(self, uids, cache=True):
+    def data_size(self, files):
+        """
+        Given a list of file URLs, return the data size.  This is useful for
+        assessing how much data you might be downloading!
+        """
+        totalsize = 0
+        pb = ProgressBar(len(files))
+        for ii,fileLink in enumerate(files):
+            response = self._request('HEAD', fileLink, stream=True,
+                                     cache=False, timeout=self.TIMEOUT)
+            totalsize += int(response.headers['content-length'])
+            pb.update(ii+1)
+
+        return (totalsize*u.B).to(u.GB)
+
+    def download_files(self, files, cache=True):
+        """
+        Given a list of file URLs, download them
+        """
+        downloaded_files = []
+        for fileLink in files:
+            filename = self._request("GET", fileLink, save=True,
+                                     timeout=self.TIMEOUT)
+            downloaded_files.append(filename)
+        return downloaded_files
+
+    def retrieve_data_from_uid(self, uids, cache=True):
         """
         Stage & Download ALMA data.  Will print out the expected file size
         before attempting the download.
@@ -160,24 +187,18 @@ def download_data(self, uids, cache=True):
         downloaded_files : list
             A list of the downloaded file paths
         """
+        if isinstance(uids, six.string_types):
+            uids = [uids]
+        if not isinstance(uids, (list, tuple, np.ndarray)):
+            raise TypeError("Datasets must be given as a list of strings.")
 
         files = self.stage_data(uids, cache=cache)
 
         log.info("Determining download size for {0} files...".format(len(files)))
-        totalsize = 0
-        pb = ProgressBar(len(files))
-        for ii,fileLink in enumerate(files):
-            response = self._request('GET', fileLink, stream=True,
-                                     timeout=self.TIMEOUT)
-            totalsize += int(response.headers['content-length'])
-            pb.update(ii+1)
+        totalsize = self.data_size(files)
 
-        log.info("Downloading files of size {0}...".format((totalsize*u.B).to(u.GB)))
-        downloaded_files = []
-        for fileLink in files:
-            filename = self._request("GET", fileLink, save=True,
-                                     timeout=self.TIMEOUT)
-            downloaded_files.append(filename)
+        log.info("Downloading files of size {0}...".format(totalsize.to(u.GB)))
+        downloaded_files = self.download_files(files, cache=cache)
 
         return downloaded_files
 
diff --git a/astroquery/alma/tests/test_alma_remote.py b/astroquery/alma/tests/test_alma_remote.py
@@ -40,3 +40,32 @@ def test_stage_data(self, temp_dir):
         uid = result_s['Asdm_uid'][0]
 
         alma.stage_data([uid])
+
+    def test_doc_example(self, temp_dir):
+        alma = Alma()
+        alma.cache_location = temp_dir
+
+        from astroquery.alma import Alma
+        from astropy import units as u
+        from astropy import coordinates
+        import numpy as np
+        alma = Alma()
+        m83_data = alma.query_object('M83')
+        assert m83_data.colnames == ['Project_code', 'Source_name', 'RA',
+                                     'Dec', 'Band', 'Frequency_resolution',
+                                     'Integration', 'Release_date',
+                                     'Frequency_support',
+                                     'Velocity_resolution', 'Pol_products',
+                                     'Observation_date', 'PI_name', 'PWV',
+                                     'Member_ous_id', 'Asdm_uid',
+                                     'Project_title', 'Project_type',
+                                     'Scan_intent']
+        galactic_center = coordinates.SkyCoord(0*u.deg, 0*u.deg,
+                                               frame='galactic')
+        gc_data = alma.query_region(galactic_center, 1*u.deg)
+
+        uids = np.unique(m83_data['Asdm_uid'])
+        assert 'uid://A002/X3b3400/X90f' in uids
+
+        link_list = alma.stage_data(uids[0:2])
+        alma.data_size(link_list)
diff --git a/astroquery/query.py b/astroquery/query.py
@@ -33,6 +33,8 @@ def __init__(self, response=None, url=None, encoding=None, content=None,
             if stream:
                 self.iter_content = response.iter_content
             self.content = response.content
+            # Needed for assessing file size:
+            self.headers = response.headers
         elif not hasattr(response, 'content'):
             raise TypeError("{0} is not a requests.Response".format(response))
         elif not isinstance(response, requests.Response):
diff --git a/docs/alma/alma.rst b/docs/alma/alma.rst
@@ -37,4 +37,87 @@ via the ALMA CAS (central authentication server).
     Authenticating ICONDOR on asa.alma.cl...
     Authentication successful!
 
+Querying Targets and Regions
+============================
 
+You can query by object name or by circular region:
+
+.. code-block:: python
+
+    >>> from astroquery.alma import Alma
+    >>> m83_data = Alma.query_object('M83')
+    >>> print(len(m83_data))
+    225
+    >>> m83_data.colnames
+    ['Project_code', 'Source_name', 'RA', 'Dec', 'Band',
+    'Frequency_resolution', 'Integration', 'Release_date', 'Frequency_support',
+    'Velocity_resolution', 'Pol_products', 'Observation_date', 'PI_name',
+    'PWV', 'Member_ous_id', 'Asdm_uid', 'Project_title', 'Project_type',
+    'Scan_intent']
+
+
+Region queries are just like any other in astroquery:
+
+.. code-block:: python
+
+    >>> from astropy import coordinates
+    >>> from astropy import units as u
+    >>> galactic_center = coordinates.SkyCoord(0*u.deg, 0*u.deg,
+    ...                                        frame='galactic')
+    >>> gc_data = Alma.query_region(galactic_center, 1*u.deg)
+    >>> print(len(gc_data))
+    82
+
+Downloading Data
+================
+
+You can download ALMA data with astroquery, but be forewarned, cycle 0 and
+cycle 1 data sets tend to be >100 GB!
+
+
+.. code-block:: python
+
+   >>> import numpy as np
+   >>> uids = np.unique(m83_data['Asdm_uid'])
+   >>> print(uids)
+           Asdm_uid
+    -----------------------
+    uid://A002/X3b3400/X90f
+    uid://A002/X3b3400/Xaf3
+    uid://A002/X3fbe56/X607
+    uid://A002/X4b29af/X24c
+     uid://A002/X4b29af/X5c
+
+You can then stage the data and see how big it is (you can ask for one or more
+UIDs):
+
+
+.. code-block:: python
+
+   >>> link_list = Alma.stage_data(uids[0:2])
+   >>> Alma.data_size(link_list)
+   INFO: Staging files... [astroquery.alma.core]
+   <Quantity 146.51379712000002 Gbyte>
+
+You can then go on to download that data.  The download will be cached so that repeat
+queries of the same file will not re-download the data.  The default cache
+directory is `~/.astropy/cache/astroquery/Alma/`, but this can be changed by
+changing the ``cache_location`` variable:
+
+.. code-block:: python
+
+   >>> myAlma = Alma()
+   >>> myAlma.cache_location = '/big/external/drive/'
+   >>> myAlma.download_files(link_list, cache=True)
+
+You can also do the downloading all in one step:
+
+.. code-block:: python
+
+   >>> myAlma.retrieve_data_from_uid(uids[0])
+
+Reference/API
+=============
+
+.. automodapi:: astroquery.alma
+    :no-inheritance-diagram:
diff --git a/docs/index.rst b/docs/index.rst
@@ -120,6 +120,7 @@ The following modules have been completed using a common API:
   eso/eso.rst
   xmatch/xmatch.rst
   atomic/atomic.rst
+  alma/alma.rst
 
 These others are functional, but do not follow a common & consistent API:
 
@@ -175,6 +176,7 @@ generally return a table listing the available data first.
   :maxdepth: 1
 
   alfalfa/alfalfa.rst
+  alma/alma.rst
   eso/eso.rst
   fermi/fermi.rst
   irsa/irsa.rst
