Quickstart Guide

The following tutorial will take you, step by step, through the main features of APLpy. You will need to download the following file.

First, unpack the example files and go to the tutorial directory:

tar -xvzf tutorial.tar.gz
cd tutorial

Now, start up ipython and import the aplpy module as follows:

ipython -pylab
import aplpy
import numpy # For the numpy.loadtxt() function

Displaying a FITS image

To start off, use the aplpy.FITSfigure class to create a canvas to where your data will be plotted:

gc = aplpy.FITSFigure('fits/2MASS_k.fits')

and display the image using a grayscale stretch:

gc.show_grayscale()

Check out the buttons at the top or bottom of the canvas (depending on the version of matplotlib). You will see seven buttons:

The first five are of interest to us here. The button with the magnifying glass will allow you to select an area on the plot and zoom in. To zoom out you can click on the home button (first one on the left). When you’re zoomed in you can pan around by clicking on the button with the arrows (fourth button from the left).

The size of the canvas can be controlled through the figsize argument. Close the current canvas and create a new figure using:

gc = aplpy.FITSFigure('fits/2MASS_k.fits',figsize=(10,9))
gc.show_grayscale()

This will create a figure that is 10 by 10 inches and will show the image as a grayscale. Use the following command to show a colorscale image instead:

gc.show_colorscale()

The colormap used for the colorscale image can be changed. Try the following:

gc.show_colorscale(cmap='gist_heat')

to show the image showing a ‘heat’ map. For more information on show_grayscale and show_colorscale, see the documentation For example, you can control the minimum and maximum pixel values to show and the stretch function to use.

Displaying a 3-color image

It is possible to use APLpy to show 3-color images. To do this, you need a FITS file with the image - this is used for the information relating to the coordinates - and a PNG file containing the 3-color image. Both files need to have exactly the same dimensions and the pixels from the PNG file have to match those from the FITS file. An example is provided in the tutorial files. Try the following:

gc.show_rgb('graphics/2MASS_arcsinh_color.png')

Modifying fonts

It is very easy to modify the font properties of the various labels. For example, in this case, we can change the font size of the tick labels to be smaller than the default:

gc.set_tick_labels_font(size='small')

Contours

APLpy can be used to overlay contours onto a grayscale/colorscale/3-color image. Try typing the following command:

gc.show_contour('fits/mips_24micron.fits',colors='white')

There are a number of arguments that can be passed to show_contour to control the appearance of the contours as well as the number of levels to show. For more information, see the see the contour documentation.

Coordinate grid

Display a coordinate grid using:

gc.show_grid()

and hide it again using:

gc.hide_grid()

Markers

Let’s overplot positions from a source list. Here we will use loadtxt to read in the coordinates from a file, but in general you can pass any pair of lists or numpy arrays that are already defined:

# If the numpy.loadtxt() command does not work
# then do "import numpy", without the quotes.
data = numpy.loadtxt('data/yso_wcs_only.txt')
ra,dec = data[:,0],data[:,1]
gc.show_markers(ra,dec,edgecolor='green',facecolor='none',
   marker='o',s=10,alpha=0.5)

For more information about show_markers, see the see the markers documentation.

Layers

It’s often the case that you might want to change the look of a contour or markers, but if you run show_contour or show_markers a second time, it will overplot rather than replacing. To solve this problem APLpy has ‘layers’ which can be manipulated in a basic way. Type:

gc.list_layers()

which will print out something like this:

There are 2 layers in this figure:

-> contour_set_1
-> marker_set_1

You can use remove_layer, hide_layer, and show_layer to manipulate the layers, and you can also specify the layer=name argument to show_contour or show_markers. Using the latter forces APLpy to name the layer you are creating with the name provided, and can also be used to replace an existing layer. For example, let’s change the color of the markers from green to red:

gc.show_markers(ra,dec,layer='marker_set_1',edgecolor='green',
       facecolor='none',marker='o',s=10,alpha=0.5)

Note the presence of the layer='marker_set_1' which means that the current markers plot will be replaced. For more information about layers, see the see the layers documentation.

Saving

To wrap up this tutorial, we will save the plot to a file. Type the following:

gc.save('myfirstplot.png')

This will produce the following file:

You can of course save it as a PS/EPS, PDF, or SVG file instead. The EPS output is suitable for publication.

Summary

To summarize, the above plot was made using the following commands:

import aplpy
import numpy

gc = aplpy.FITSFigure('fits/2MASS_k.fits',figsize=(10,9))
gc.show_rgb('graphics/2MASS_arcsinh_color.png')

gc.set_tick_labels_font(size='small')

gc.show_contour('fits/mips_24micron.fits',colors='white')

data = numpy.loadtxt('data/yso_wcs_only.txt')
ra,dec = data[:,0],data[:,1]

gc.show_markers(ra,dec,layer='marker_set_1',edgecolor='red',
facecolor='none',marker='o',s=10,alpha=0.5)

gc.save('myfirstplot.png')

There are many more methods and options, from setting the tick spacing and format to controling the label fonts. For more information, see the full api.