Merge pull request #439 from keflavich/alma/docs

Add 'help' to ALMA docs

Author: keflavich

docs/alma/alma.rst

@@ -12,6 +12,44 @@ Getting started
 `astroquery.alma` provides the astroquery interface to the ALMA archive.  It
 supports object and region based querying and data staging and retrieval.
 
+You can get interactive help to find out what keywords to query for:
+
+.. code-block:: python
+
+   >>> from astroquery.alma import Alma
+   >>> Alma.help()
+   Valid ALMA keywords:
+
+   Position
+     Source name (Sesame)             : source_name_sesame
+     Source name (ALMA)               : source_name-asu
+     RA Dec                           : raDecCoordinates
+
+   Energy
+     Frequency                        : energy.frequency-asu
+     Bandwidth                        : energy.bandwidth-asu
+     Spectral resolution              : energy.resolution-asu
+     Band                             : band-asu
+
+   Time
+     Observation date                 : start_date-asu
+     Integration time                 : int_time-asu
+
+   Polarisation
+     Polarisation type                : energy.pol_num-asu
+
+   Observation
+     Water vapour                     : pwv-asu
+
+   Project
+     Project code                     : project_code-asu
+     Project title                    : project.title-substr
+     PI name                          : project.pi_name-substr
+
+   Options
+     View:                            : viewFormat
+     [x] public data only             : publicFilterFlag     = public
+     [x] science observations only    : scan_intent-asu      = =%TARGET%
 
 Authentication
 ==============
@@ -111,7 +149,7 @@ UIDs):
 
 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
+directory is ``~/.astropy/cache/astroquery/Alma/``, but this can be changed by
 changing the ``cache_location`` variable:
 
 .. code-block:: python

docs/gallery.rst

@@ -107,3 +107,53 @@ Finding the mass of a specific planet:
         >>> print findvalue( kepler68b, 'mass')
         0.02105109
 
+Example 6
++++++++++
+
+Grab some data from ALMA, then analyze it using the Spectral Cube package after
+identifying some spectral lines in the data.
+
+.. code-block:: python
+
+   from astroquery.alma import Alma
+   from astroquery.splatalogue import Splatalogue
+   from astroquery.simbad import Simbad
+   from astropy import units as u
+   from astropy import constants
+   from spectral_cube import SpectralCube
+
+   m83table = Alma.query_object('M83', public=True)
+   m83urls = Alma.stage_data(m83table['Asdm_uid'])
+   m83files = Alma.download_and_extract_files(m83urls['URL'])
+   # Sometimes there can be duplicates
+   m83files = list(set(m83files))
+   
+   Simbad.add_votable_fields('rvel')
+   m83simbad = Simbad.query_object('M83')
+   rvel = m83simbad['RVel_Rvel'][0]*u.Unit(m83simbad['RVel_Rvel'].unit)
+
+   for fn in m83files:
+       if 'line' in fn:
+           cube = SpectralCube.read(fn)
+           # Convert frequencies to their rest frequencies
+           frange = u.Quantity([cube.spectral_axis.min(),
+                                cube.spectral_axis.max()]) * (1+rvel/constants.c)
+
+           # Query the top 20 most common species in the frequency range of the
+           # cube with an upper energy state <= 50K
+           lines = Splatalogue.query_lines(frange[0], frange[1], top20='top20',
+                                           energy_max=50, energy_type='eu_k',
+                                           only_NRAO_recommended=True)
+           lines.pprint()
+
+           # Change the cube coordinate system to be in velocity with respect
+           # to the rest frequency (in the M83 rest frame)
+           rests_frequency = lines['Freq-GHz'][0]*u.GHz / (1+rvel/constants.c)
+           vcube = cube.with_spectral_unit(u.km/u.s,
+                                           rest_value=rest_frequency,
+                                           velocity_convention='radio')
+
+           # Write the cube with the specified line name
+           fmt = "{Species}{Resolved QNs}"
+           linename = fmt.format(**dict(zip(row.colnames,row.data)))
+           vcube.write('M83_ALMA_{linename}.fits'.format(linename=linename))