Debian Codegraph @

docs/fitsfigure/quickstart.rst

raw
1 Beginner Tutorial
2 -----------------
3
4 .. toctree::
5 :maxdepth: 1
6
7 The following tutorial will take you, step by step, through the main features
8 of APLpy. You will need to download the following `file <http://aplpy.github.io/downloads/tutorial.tar.gz>`_.
9
10 First, unpack the example files and go to the ``tutorial`` directory::
11
12 tar -xvzf tutorial.tar.gz
13 cd tutorial
14
15 Now, start up ``ipython``::
16
17 ipython --pylab
18
19 and import the ``aplpy`` module as follows::
20
21 import aplpy
22
23 To start off, use the :class:`~aplpy.FITSFigure` class to create a
24 canvas to where your data will be plotted::
25
26 gc = aplpy.FITSFigure('fits/2MASS_k.fits')
27
28 and display the image using a grayscale stretch::
29
30 gc.show_grayscale()
31
32 Check out the buttons at the top or bottom of the canvas (depending on the
33 version of matplotlib). You will see seven buttons:
34
35 .. image:: buttons.png
36
37 The first five are of interest to us here. The button with the magnifying
38 glass will allow you to select an area on the plot and zoom in. To zoom out
39 you can click on the home button (first one on the left). When you're zoomed
40 in you can pan around by clicking on the button with the arrows (fourth button
41 from the left).
42
43 Use the following command to show a colorscale image instead::
44
45 gc.show_colorscale()
46
47 The colormap used for the colorscale image can be changed. Try the following::
48
49 gc.show_colorscale(cmap='gist_heat')
50
51 to show the image showing a 'heat' map. You can find more information in the
52 :meth:`~aplpy.FITSFigure.show_grayscale` and
53 :meth:`~aplpy.FITSFigure.show_colorscale` documentation. For
54 example, you can control the minimum and maximum pixel values to show and the
55 stretch function to use.
56
57 It is possible to use APLpy to show 3-color images. To do this, you need a
58 FITS file with the image - this is used for the information relating to the
59 coordinates - and a PNG file containing the 3-color image. Both files need to
60 have exactly the same dimensions and the pixels from the PNG file have to
61 match those from the FITS file. An example is provided in the tutorial files.
62 Try the following::
63
64 gc.show_rgb('graphics/2MASS_arcsinh_color.png')
65
66 It is very easy to modify the font properties of the various labels.
67 For example, in this case, we can change the font size of the tick
68 labels to be smaller than the default::
69
70 gc.tick_labels.set_font(size='small')
71
72 APLpy can be used to overlay contours onto a grayscale/colorscale/3-color
73 image. Try typing the following command::
74
75 gc.show_contour('fits/mips_24micron.fits', colors='white')
76
77 There are a number of arguments that can be passed to :meth:`~aplpy.FITSFigure.show_contour` to
78 control the appearance of the contours as well as the number of levels to
79 show. For more information, see the see the :meth:`~aplpy.FITSFigure.show_contour` documentation.
80
81 Display a coordinate grid using::
82
83 gc.add_grid()
84
85 and hide it again using::
86
87 gc.remove_grid()
88
89 Let's overplot positions from a source list. Here we will use loadtxt to read
90 in the coordinates from a file, but in general you can pass any pair of lists
91 or numpy arrays that are already defined::
92
93 import numpy
94 ra, dec = numpy.loadtxt('data/yso_wcs_only.txt', unpack=True)
95 gc.show_markers(ra, dec, edgecolor='green', facecolor='none',
96 marker='o', s=10, alpha=0.5)
97
98 For more information, see the :meth:`~aplpy.FITSFigure.show_markers`
99 documentation.
100
101 It's often the case that you might want to change the look of a contour or
102 markers, but if you run :meth:`~aplpy.FITSFigure.show_contour` or :meth:`~aplpy.FITSFigure.show_markers` a second time, it
103 will overplot rather than replacing. To solve this problem APLpy has 'layers'
104 which can be manipulated in a basic way. Type::
105
106 gc.list_layers()
107
108 which will print out something like this::
109
110 There are 2 layers in this figure:
111
112 -> contour_set_1
113 -> marker_set_1
114
115 You can use :meth:`~aplpy.FITSFigure.remove_layer`, :meth:`~aplpy.FITSFigure.hide_layer`, and :meth:`~aplpy.FITSFigure.show_layer` to manipulate
116 the layers, and you can also specify the ``layer=name`` argument to
117 :meth:`~aplpy.FITSFigure.show_contour` or :meth:`~aplpy.FITSFigure.show_markers`. Using the latter forces APLpy to name
118 the layer you are creating with the name provided, and can also be used to
119 replace an existing layer. For example, let's change the color of the markers
120 from green to red::
121
122 gc.show_markers(ra, dec, layer='marker_set_1', edgecolor='red',
123 facecolor='none', marker='o', s=10, alpha=0.5)
124
125 Note the presence of the ``layer='marker_set_1'`` which means that the
126 current markers plot will be replaced. To view active layers, you can use the :meth:`~aplpy.FITSFigure.list_layers` documentation.
127
128 To wrap up this tutorial, we will save the plot to a file. Type the following::
129
130 gc.save('myfirstplot.png')
131
132 This will produce the following plot:
133
134 .. image:: myfirstplot.png
135
136 You can of course save it as a PS/EPS, PDF, or SVG file instead. The EPS
137 output is suitable for publication.
138
139 To summarize, the above plot was made using the following commands::
140
141 import aplpy
142 import numpy
143
144 gc = aplpy.FITSFigure('fits/2MASS_k.fits')
145 gc.show_rgb('graphics/2MASS_arcsinh_color.png')
146
147 gc.tick_labels.set_font(size='small')
148
149 gc.show_contour('fits/mips_24micron.fits', colors='white')
150
151 ra, dec = numpy.loadtxt('data/yso_wcs_only.txt', unpack=True)
152
153 gc.show_markers(ra, dec, layer='marker_set_1', edgecolor='red',
154 facecolor='none', marker='o', s=10, alpha=0.5)
155
156 gc.save('myfirstplot.png')
157
158 There are many more methods and options, from setting the tick spacing and
159 format to controlling the label fonts. For more information, see the :doc:`quick_reference` or the :ref:`api`.