Merge pull request #76 from astrofrog/tidying-up

Various fixes ahead of release

docs/api.rst

@@ -0,0 +1,5 @@
+Reference/API
+=============
+
+.. automodapi:: wcsaxes
+   :no-inheritance-diagram:

docs/getting_started.rst

@@ -69,8 +69,8 @@ Plotting images and contours
 
 Plotting images as bitmaps or contours should be done via the usual matplotlib
 methods such as :meth:`~matplotlib.axes.Axes.imshow` or
-:meth:`~matplotlib.axes.Axes.contour`. For example, to plot the data from
-the file read in `Initialization`_, you can do:
+:meth:`~matplotlib.axes.Axes.contour`. For example, continuing from the
+example in `Initialization`_, you can do:
 
 .. plot::
    :context:

docs/index.rst

@@ -11,19 +11,17 @@ is affiliated with the `Astropy <http://www.astropy.org>`_ project and is
 intended for inclusion in the Astropy package once stable.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    installation.rst
    getting_started.rst
    ticks_labels_grid.rst
    overlays.rst
+   overlaying_coordinate_systems.rst
    slicing_datacubes.rst
    changing_axis_unit.rst
+   custom_frames.rst
+   api.rst
 
 
-Reference/API
-=============
-
-.. automodapi:: wcsaxes
-   :no-inheritance-diagram:
 

docs/installation.rst

@@ -5,7 +5,7 @@ Installation
 Requirements
 ============
 
-WCSAxes requires Python 2.6, 2.7, 3.2, or 3.3, and the following Python
+WCSAxes requires Python 2.6, 2.7, 3.2, 3.3, or 3.4 and the following Python
 packages to be installed:
 
 * `Numpy <http://www.numpy.org>`_
@@ -21,8 +21,12 @@ package, such as the `Anaconda Python Distribution
 Installation
 ============
 
-You can install the latest developer version of WCSAxes by cloning the git
-repository::
+You can install the stable version of WCSAxes with::
+
+    pip install wcsaxes
+
+Alternatively, you can install the latest developer version of WCSAxes by
+cloning the git repository::
 
     git clone http://github.com/astrofrog/wcsaxes
 
@@ -35,8 +39,9 @@ Testing
 =======
 
 If you want to check that all the tests are running correctly with your Python
-configuration, you can also run::
+configuration, start up python, and type::
 
-    python setup.py test
+    import wcsaxes
+    wcsaxes.test()
 
-in the source directory. If there are no errors, you are good to go!    
+If there are no errors, you are good to go!    

docs/overlaying_coordinate_systems.rst

@@ -0,0 +1,63 @@
+=============================
+Overlaying coordinate systems
+=============================
+
+For the example in the following page we start from the example introduced in
+:doc:`getting_started`.
+
+.. plot::
+   :context: reset
+   :nofigs:
+
+    from astropy.wcs import WCS
+    from wcsaxes import datasets
+    hdu = datasets.msx_hdu()
+    wcs = WCS(hdu.header)
+
+    import matplotlib.pyplot as plt
+    fig = plt.figure()
+
+    from wcsaxes import WCSAxes
+
+    ax = WCSAxes(fig, [0.25, 0.25, 0.6, 0.6], wcs=wcs)
+    fig.add_axes(ax)  # note that the axes have to be added to the figure
+
+    ax.imshow(hdu.data, vmin=-2.e-5, vmax=2.e-4, cmap=plt.cm.gist_heat,
+              origin='lower')
+
+The coordinates shown by default in a plot will be those derived from the WCS
+or transformation passed to the :class:`wcsaxes.wcsaxes.WCSAxes` class.
+However, it is possible to overlay different coordinate systems using the
+:meth:`wcsaxes.wcsaxes.WCSAxes.get_coords_overlay` method:
+
+.. plot::
+   :context:
+   :include-source:
+   :align: center
+
+    overlay = ax.get_coords_overlay('fk5')
+
+The object returned is a :class:`~wcsaxes.coordinates_map.CoordinatesMap`, the
+same type of object as ``ax.coord``. It can therefore be used in the same way
+as ``ax.coord`` to set the ticks, tick labels, and axis labels properties:
+
+.. plot::
+   :context:
+   :include-source:
+   :align: center
+
+    ax.coords['glon'].set_ticks(color='white')
+    ax.coords['glat'].set_ticks(color='white')
+
+    ax.coords['glon'].set_axislabel('Galactic Longitude')
+    ax.coords['glat'].set_axislabel('Galactic Latitude')
+
+    ax.coords.grid(color='yellow', linestyle='solid', alpha=0.5)
+
+    overlay['ra'].set_ticks(color='white')
+    overlay['dec'].set_ticks(color='white')
+
+    overlay['ra'].set_axislabel('Right Ascension')
+    overlay['dec'].set_axislabel('Declination')
+
+    overlay.grid(color='white', linestyle='solid', alpha=0.5)

docs/overlays.rst

@@ -1,6 +1,6 @@
-=================
-Plotting overlays
-=================
+====================
+Overplotting artists
+====================
 
 For the example in the following page we start from the example introduced in
 :doc:`getting_started`.
@@ -66,10 +66,13 @@ If the world coordinate system of the plot is a celestial coordinate system,
 the following built-in sky coordinate systems would be available from the
 ``get_transform`` method:
 
-* ``'fk4'`` or ``'b1950'``: B1950 equatorial coordinates
-* ``'fk5'`` or ``'j2000'``: J2000 equatorial coordinates
+* ``'fk4'``: B1950 FK4 equatorial coordinates
+* ``'fk5'``: J2000 FK5 equatorial coordinates
+* ``'icrs'``: ICRS equatorial coordinates
+* ``'galactic'``: Galactic coordinates
 
-and more coordinate systems will be added in future.
+It is also possible to directly pass a frame object from
+:mod:`astropy.coordinates`.
 
 Patches/shapes/lines
 ====================
@@ -100,8 +103,45 @@ to plot for example in FK5 equatorial coordinates:
 
 Many Matplotlib methods accept the ``transform=`` option, so
 :meth:`~wcsaxes.wcsaxes.WCSAxes.get_transform` can be used in many cases to
-plot overlays in various coordinate systems.
+plot overlays in various coordinate systems. A few examples are shown below.
+
+Contours
+========
+
+Overplotting contours is also simple using the
+:meth:`~wcsaxes.wcsaxes.WCSAxes.get_transform` method. For contours,
+:meth:`~wcsaxes.wcsaxes.WCSAxes.get_transform` should be given the WCS of the
+image to plot the contours for:
+
+.. plot::
+   :context:
+   :include-source:
+   :align: center
+
+    hdu = datasets.bolocam_hdu()
+    ax.contour(hdu.data, transform=ax.get_transform(WCS(hdu.header)),
+               levels=[1,2,3,4,5,6], colors='white')
+
+    ax.set_xlim(-0.5, 148.5)
+    ax.set_ylim(-0.5, 148.5)
+
+The calls to ``set_xlim`` and ``set_ylim`` are included here as the contours
+cover a larger region than the image, so we want to make sure we focus just on
+the image.
+
+Scatter plots
+=============
+
+Since the ``ax.scatter`` Matplotlib routine can take the ``transform`` option,
+it can also be used to plot objects in various coordinate systems:
+
+.. plot::
+   :context:
+   :include-source:
+   :align: center
+
+    l = [0.25, 0.20, 0.30, 0.27]
+    b = [0.20, 0.23, 0.27, 0.30]
 
-..     ax.add_collection(c, transform=ax.get_transform('gal'))
-..     ax.add_line(l, transform=ax.get_transform('fk4'))
-..     ax.scatter(l, b, transform=ax.get_transform('gal'))
+    ax.scatter(l, b, transform=ax.get_transform('galactic'), s=100,
+               edgecolor='white', facecolor='yellow', alpha=0.5)

docs/slicing_datacubes.rst

@@ -18,9 +18,9 @@ information. The original FITS file can be downloaded from `here
 
 .. plot::
    :context: reset
-   :nofigs:
    :include-source:
    :align: center
+   :nofigs:
 
     from astropy.wcs import WCS
     from wcsaxes import datasets
@@ -48,6 +48,7 @@ We then instantiate the :class:`~wcsaxes.wcsaxes.WCSAxes` using the
    :context:
    :include-source:
    :align: center
+   :nofigs:
 
     import matplotlib.pyplot as plt
     fig = plt.figure()
@@ -92,7 +93,7 @@ If we don't want to reverse the dimensions plotted, we can simply do:
    :include-source:
    :align: center
 
-    fig = plt.figure()
+    fig = plt.figure(figsize=(6,3))
     ax = WCSAxes(fig, [0.1, 0.1, 0.8, 0.8], wcs=wcs, slices=(50, 'x', 'y'))
     fig.add_axes(ax)
     ax.imshow(image_data[:, :, 50], cmap=plt.cm.gist_heat)

docs/ticks_labels_grid.rst

@@ -133,11 +133,18 @@ The syntax for the format string is the following:
 ``'d.d'``             ``'15.4'``
 ``'d.dd'``            ``'15.39'``
 ``'d.ddd'``           ``'15.392'``
+``'m'``               ``'924'``
+``'m.m'``             ``'923.5'``
+``'m.mm'``            ``'923.53'``
+``'s'``               ``'55412'``
+``'s.s'``             ``'55412.0'``
+``'s.ss'``            ``'55412.03'``
 ``'x.xxxx'``          ``'15.3922'``
 ==================== ====================
 
-All the ``d...`` and ``h...`` formats can be used for angular coordinate axes,
-while the ``x...`` formats should be used for non-angular coordinate axes.
+All the ``h...``, ``d...``, ``m...``, and ``s...`` formats can be used for
+angular coordinate axes, while the ``x...`` formats should be used for
+non-angular coordinate axes.
 
 Tick/label spacing and properties
 =================================
@@ -230,8 +237,8 @@ for declination with:
    :include-source:
    :align: center
 
-    lon.grid(color='yellow', alpha=0.5)
-    lat.grid(color='orange', alpha=0.5)
+    lon.grid(color='yellow', alpha=0.5, linestyle='solid')
+    lat.grid(color='orange', alpha=0.5, linestyle='solid')
 
 For convenience, you can also simply draw a grid for all the coordinates in
 one command:
@@ -241,4 +248,4 @@ one command:
    :include-source:
    :align: center
 
-    ax.coords.grid(color='white', alpha=0.3)
+    ax.coords.grid(color='white', alpha=0.5, linestyle='solid')

setup.cfg

@@ -16,7 +16,7 @@ auto_use = True
 
 [metadata]
 package_name = wcsaxes
-description = WCSAxes implementation
+description = WCSAxes: a framework for plotting astronomical and geospatial data
 long_description =
 author = Thomas Robitaille
 author_email = thomas.robitaille@gmail.com

wcsaxes/__init__.py

@@ -13,3 +13,4 @@
 if not _ASTROPY_SETUP_:
     from .wcsaxes import *
     from .coordinate_helpers import CoordinateHelper
+    from .coordinates_map import CoordinatesMap

wcsaxes/datasets/__init__.py

@@ -25,3 +25,8 @@ def twoMASS_k_hdu(cache=True):
 def l1448_co_hdu(cache=True):
     filename = download_file("http://astrofrog.github.io/wcsaxes-datasets/L1448_13CO_subset.fits", cache=cache)
     return fits.open(filename)[0]
+
+
+def bolocam_hdu(cache=True):
+    filename = download_file("http://astrofrog.github.io/wcsaxes-datasets/bolocam_v2.0.fits", cache=cache)
+    return fits.open(filename)[0]

wcsaxes/tests/test_transform_coord_meta.py

@@ -96,6 +96,27 @@ def test_coords_overlay(self, generate):
 
         self.generate_or_test(generate, fig, 'coords_overlay.png')
 
+    def test_coords_overlay_auto_coord_meta(self, generate):
+
+        fig = plt.figure(figsize=(4,4))
+
+        ax = WCSAxes(fig, [0.15, 0.15, 0.7, 0.7], wcs=WCS(self.msx_header))
+        fig.add_axes(ax)
+
+        ax.grid(color='red', alpha=0.5, linestyle='solid')
+
+        overlay = ax.get_coords_overlay('fk5')  # automatically sets coord_meta
+
+        overlay.grid(color='black', alpha=0.5, linestyle='solid')
+
+        overlay['ra'].set_ticks(color='black')
+        overlay['dec'].set_ticks(color='black')
+
+        ax.set_xlim(-0.5, 148.5)
+        ax.set_ylim(-0.5, 148.5)
+
+        self.generate_or_test(generate, fig, 'coords_overlay_auto_coord_meta.png')
+
     def test_direct_init(self, generate):
 
         s = DistanceToLonLat(R=6378.273)
@@ -109,7 +130,7 @@ def test_direct_init(self, generate):
 
         ax = WCSAxes(fig, [0.15, 0.15, 0.7, 0.7], transform=s, coord_meta=coord_meta)
         fig.add_axes(ax)
-        
+
         ax.coords['lon'].grid(color='red', linestyle='solid', alpha=0.3)
         ax.coords['lat'].grid(color='blue', linestyle='solid', alpha=0.3)
 

wcsaxes/utils.py

@@ -1,6 +1,9 @@
 import numpy as np
+
 from astropy import units as u
 
+from . import six
+
 # Modified from axis_artist, supports astropy.units
 
 
@@ -138,6 +141,36 @@ def get_coordinate_frame(wcs):
     return coordinate_class
 
 
+def get_coord_meta(frame):
+
+    coord_meta = {}
+    coord_meta['type'] = ('longitude', 'latitude')
+    coord_meta['wrap'] = (None, None)
+    coord_meta['unit'] = (u.deg, u.deg)
+
+    try:
+
+        from astropy.coordinates import frame_transform_graph
+
+        if isinstance(frame, six.string_types):
+            frame = frame_transform_graph.lookup_name(frame)
+
+        names = frame().representation_component_names.keys()
+        coord_meta['name'] = names[:2]
+
+    except ImportError:
+
+        if isinstance(frame, six.string_types):
+            if frame in ('fk4', 'fk5', 'icrs'):
+                coord_meta['name'] = ('ra', 'dec')
+            elif frame == 'galactic':
+                coord_meta['name'] = ('l', 'b')
+            else:
+                raise ValueError("Unknown frame: {0}".format(frame))
+
+    return coord_meta
+
+
 def coord_type_from_ctype(ctype):
     """
     Determine whether a particular WCS ctype corresponds to an angle or scalar