Debian Codegraph @

docs/fitsfigure/quick_reference.rst

raw
1 Quick reference Guide
2 ---------------------
3
4 .. toctree::
5 :maxdepth: 1
6
7
8 .. note:: Rather than showing the generic call signature for the methods on
9 this page, these are given in the form of example values. In
10 addition, not all of the optional keywords are mentioned here.
11 For more information on a specific command and all the options
12 available, use the ``help()`` function, e.g.
13 ``help(fig.show_grayscale)``. When multiple optional arguments are
14 given, this does not mean that all of them have to be specified, but
15 just shows all the options available.
16
17 Introduction
18 ^^^^^^^^^^^^
19
20 To import APLpy::
21
22 import aplpy
23
24 To create a figure of a FITS file::
25
26 fig = aplpy.FITSFigure('myimage.fits')
27
28 Here and in the remainder of this reference guide, we use the variable name
29 ``fig`` for the figure object, but any name can be used.
30
31 A grayscale or colorscale representation of the FITS image can be shown and
32 hidden using the following methods::
33
34 fig.show_grayscale()
35 fig.hide_grayscale()
36 fig.show_colorscale()
37 fig.hide_colorscale()
38
39 To show a three-color image, use the following method, specifying the
40 filename of the color image::
41
42 fig.show_rgb('m17.jpeg')
43
44 The figure can be interactively explored by zooming and panning. To
45 recenter on a specific region programmatically, use the following method,
46 specifying either a radius::
47
48 fig.recenter(33.23, 55.33, radius=0.3) # degrees
49
50 or a separate width and height::
51
52 fig.recenter(33.23, 55.33, width=0.3, height=0.2) # degrees
53
54 To overlay contours, use::
55
56 fig.show_contour('co_data.fits')
57
58 To save the current figure, use::
59
60 fig.save('myplot.eps')
61
62 Other formats such as PDF, PNG, etc. can be used.
63
64 Labels
65 ^^^^^^
66
67 Labels can be added either in world coordinates::
68
69 fig.add_label(34.455, 54.112, 'My favorite star')
70
71 or relative to the axes::
72
73 fig.add_label(0.1, 0.9, '(a)', relative=True)
74
75 Shapes
76 ^^^^^^
77
78 To overlay different shapes, the following methods are available::
79
80 fig.show_markers(x_world, y_world)
81 fig.show_circles(x_world, y_world, radius)
82 fig.show_ellipses(x_world, y_world, width, height)
83 fig.show_rectangles(x_world, y_world, width, height)
84 fig.show_arrows(x_world, y_world, dx, dy)
85
86 where ``x_world``, ``y_world``, ``radius``, ``width``, ``height``, ``dx``,
87 and ``dy`` should be 1D arrays specified in degrees.
88
89 It is also possible to plot lines and polygons using::
90
91 fig.show_lines(line_list)
92 fig.show_polygons(polygon_list)
93
94 For these methods, ``line_list`` and ``polygon_list`` should be lists of
95 2xN Numpy arrays describing the coordinates of the vertices in degrees.
96
97 DS9 Regions
98 ^^^^^^^^^^^
99
100 DS9 region files can be overlaid with::
101
102 fig.show_regions('myregions.reg')
103
104 Layers
105 ^^^^^^
106
107 Markers, shapes, regions and text labels are stored in layers. These layers can be listed using::
108
109 fig.list_layers()
110
111 Layers can be hidden and shown with the following methods::
112
113 fig.hide_layer('regions')
114 fig.show_layer('regions')
115
116 Any layer can be retrieved using::
117
118 layer = fig.get_layer('circles')
119
120 Finally, layers can be removed using::
121
122 fig.remove_layer('rectangles')
123
124 Coordinates
125 ^^^^^^^^^^^
126
127 Two methods are provided to help transform coordinates between world and pixel coordinates. These accept either scalars or arrays in degrees::
128
129 x_pix, y_pix = fig.world2pixel(45.3332, 22.1932)
130 x_world, y_world = fig.pixel2world(np.array([1., 2., 3]), np.array([1., 3., 5.]))
131
132 Frame
133 ^^^^^
134
135 To set the look of the frame around the figure, use::
136
137 fig.frame.set_linewidth(1) # points
138 fig.frame.set_color('black')
139
140 Colorbar
141 ^^^^^^^^
142
143 A grid can be added and removed using the following commands::
144
145 fig.add_colorbar()
146 fig.remove_colorbar()
147
148 Once :meth:`~aplpy.FITSFigure.add_colorbar` has been called, the ``fig.colorbar`` object is created and the following methods are then available:
149
150 * Show and hide the colorbar::
151
152 fig.colorbar.show()
153 fig.colorbar.hide()
154
155 * Set where to place the colorbar::
156
157 fig.colorbar.set_location('right')
158
159 This can be one of ``left``, ``right``, ``bottom`` or ``top``.
160
161 * Set the width of the colorbar::
162
163 fig.colorbar.set_width(0.1) # arbitrary units, default is 0.2
164
165 * Set the amount of padding between the colorbar and the parent axes::
166
167 fig.colorbar.set_pad(0.03) # arbitrary units, default is 0.05
168
169 * Set the font properties of the labels::
170
171 fig.colorbar.set_font(size='medium', weight='medium', \
172 stretch='normal', family='sans-serif', \
173 style='normal', variant='normal')
174
175 * Add a colorbar label::
176
177 f.colorbar.set_axis_label_text('Surface Brightness (Jy/beam)')
178
179 * Set some of the colorbar label properties::
180
181 f.colorbar.set_axis_label_font(size=12, weight='bold')
182
183 * Set the padding between the colorbar and the label in points::
184
185 f.colorbar.set_axis_label_pad(10)
186
187 * Change the rotation of the colorbar label, in degrees::
188
189 f.colorbar.set_axis_label_rotation(270)
190
191 Coordinate Grid
192 ^^^^^^^^^^^^^^^
193
194 A coordinate grid can be added and removed using the following commands::
195
196 fig.add_grid()
197 fig.remove_grid()
198
199 Once :meth:`~aplpy.FITSFigure.add_grid` has been called, the ``fig.grid`` object is created and the following methods are then available:
200
201 * Show and hide the grid::
202
203 fig.grid.show()
204 fig.grid.hide()
205
206 * Set the x and y spacing for the grid::
207
208 fig.grid.set_xspacing(0.2) # degrees
209 fig.grid.set_yspacing(0.2) # degrees
210
211 * Set the color of the grid lines::
212
213 fig.grid.set_color('white')
214
215 * Set the transparency level of the grid lines::
216
217 fig.grid.set_alpha(0.8)
218
219 * Set the line style and width for the grid lines::
220
221 fig.grid.set_linestyle('solid')
222 fig.grid.set_linewidth(1) # points
223
224 Scalebar
225 ^^^^^^^^
226
227 A scalebar can be added and removed using the following commands::
228
229 fig.add_scalebar()
230 fig.remove_scalebar()
231
232 Once :meth:`~aplpy.FITSFigure.add_scalebar` has been called, the ``fig.scalebar`` object is created and the following methods are then available:
233
234 * Show and hide the scalebar::
235
236 fig.scalebar.show(0.2) # length in degrees
237 fig.scalebar.hide()
238
239 * Change the length of the scalebar::
240
241 fig.scalebar.set_length(0.02) # degrees
242
243 * Specify the length of the scalebar in different units::
244
245 from astropy import units as u
246 fig.scalebar.set_length(72 * u.arcsecond)
247
248 * Change the label of the scalebar::
249
250 fig.scalebar.set_label('5 pc')
251
252 * Change the corner that the beam is shown in::
253
254 fig.scalebar.set_corner('top right')
255
256 This can be one of ``top right``, ``top left``, ``bottom right``,
257 ``bottom left``, ``left``, ``right``, ``bottom`` or ``top``.
258
259 * Set whether or not to show a frame around the beam::
260
261 fig.scalebar.set_frame(False)
262
263 * Set the transparency level of the scalebar and label::
264
265 fig.scalebar.set_alpha(0.7)
266
267 * Set the color of the scalebar and label::
268
269 fig.scalebar.set_color('white')
270
271 * Set the font properties of the label::
272
273 fig.scalebar.set_font(size='medium', weight='medium', \
274 stretch='normal', family='sans-serif', \
275 style='normal', variant='normal')
276
277 * Set the line style and width for the scalebar::
278
279 fig.scalebar.set_linestyle('solid')
280 fig.scalebar.set_linewidth(3) # points
281
282 * Set multiple properties at once::
283
284 fig.scalebar.set(linestyle='solid', color='red', ...)
285
286 Beam
287 ^^^^
288
289 A beam can be added and removed using the following commands::
290
291 fig.add_beam()
292 fig.remove_beam()
293
294 Once :meth:`~aplpy.FITSFigure.add_beam` has been called, the ``fig.beam`` object is created and the following methods are then available:
295
296 * Show and hide the beam::
297
298 fig.beam.show()
299 fig.beam.hide()
300
301 * Change the major and minor axes, and the position angle::
302
303 fig.beam.set_major(0.03) # degrees
304 fig.beam.set_minor(0.02) # degrees
305 fig.beam.set_angle(45.) # degrees
306
307 * Specify the major and minor axes, and the position angle, in explicit units::
308
309 from astropy import units as u
310 fig.beam.set_major(108 * u.arcsecond)
311 fig.beam.set_minor(349 * u.microradian)
312 fig.beam.set_angle(45 * u.degree)
313
314 * Change the corner that the beam is shown in::
315
316 fig.beam.set_corner('top left')
317
318 This can be one of ``top right``, ``top left``, ``bottom right``,
319 ``bottom left``, ``left``, ``right``, ``bottom`` or ``top``.
320
321 * Set whether or not to show a frame around the beam::
322
323 fig.beam.set_frame(False)
324
325 * Set the transparency level of the beam::
326
327 fig.beam.set_alpha(0.5)
328
329 * Set the color of the whole beam, or the edge and face color individually::
330
331 fig.beam.set_color('white')
332 fig.beam.set_edgecolor('white')
333 fig.beam.set_facecolor('green')
334
335 * Set the line style and width for the edge of the beam::
336
337 fig.beam.set_linestyle('dashed')
338 fig.beam.set_linewidth(2) # points
339
340 * Set the hatch style of the beam::
341
342 fig.beam.set_hatch('/')
343
344 * Set multiple properties at once::
345
346 fig.beam.set(facecolor='red', linestyle='dashed', ...)
347
348 Coordinate types
349 ^^^^^^^^^^^^^^^^
350
351 APLpy supports three types of coordinates: longitudes (in the range 0 to 360 with wrap-around), latitudes (in the range -90 to 90), and scalars (any arbitrary value). APLpy tries to guess the correct type of coordinate for each axis, but it is possible to override this::
352
353 fig.set_xaxis_coord_type('scalar')
354 fig.set_yaxis_coord_type('longitude')
355
356 Valid options are ``longitude``, ``latitude``, and ``scalar``.
357
358 Axis labels
359 ^^^^^^^^^^^
360
361 The methods to control the x- and y- axis labels are the following
362
363 * Show/hide both axis labels::
364
365 fig.axis_labels.show()
366 fig.axis_labels.hide()
367
368 * Show/hide the x-axis label::
369
370 fig.axis_labels.show_x()
371 fig.axis_labels.hide_x()
372
373 * Show/hide the y-axis label::
374
375 fig.axis_labels.show_y()
376 fig.axis_labels.hide_y()
377
378 * Set the text for the x- and y-axis labels::
379
380 fig.axis_labels.set_xtext('Right Ascension (J2000)')
381 fig.axis_labels.set_ytext('Declination (J2000)')
382
383 * Set the displacement of the x- and y-axis labels from the x- and y-axis respectively::
384
385 fig.axis_labels.set_xpad(...)
386 fig.axis_labels.set_ypad(...)
387
388 * Set where to place the x-axis label::
389
390 fig.axis_labels.set_xposition('bottom')
391
392 * Set where to place the y-axis label::
393
394 fig.axis_labels.set_yposition('right')
395
396 * Set the font properties of the labels::
397
398 fig.axis_labels.set_font(size='medium', weight='medium', \
399 stretch='normal', family='sans-serif', \
400 style='normal', variant='normal')
401
402 Tick labels
403 ^^^^^^^^^^^
404
405 The methods to control the numerical labels below each tick are the following
406
407 * Show/hide all tick labels::
408
409 fig.tick_labels.show()
410 fig.tick_labels.hide()
411
412 * Show/hide the x-axis labels::
413
414 fig.tick_labels.show_x()
415 fig.tick_labels.hide_x()
416
417 * Show/hide the y-axis labels::
418
419 fig.tick_labels.show_y()
420 fig.tick_labels.hide_y()
421
422 * Set the format for the x-axis labels (e.g hh:mm, hh:mm:ss.s, etc.)::
423
424 fig.tick_labels.set_xformat('hh:mm:ss.ss')
425
426 * Set the format for the y-axis labels (e.g dd:mm, dd:mm:ss.s, etc.)::
427
428 fig.tick_labels.set_yformat('dd:mm:ss.s')
429
430 * Set where to place the x-axis tick labels::
431
432 fig.tick_labels.set_xposition('top')
433
434 * Set where to place the y-axis tick labels::
435
436 fig.tick_labels.set_yposition('left')
437
438 * Set the style of the labels ('colons' or 'plain')::
439
440 fig.tick_labels.set_style('colons')
441
442 * Set the font properties of the labels::
443
444 fig.tick_labels.set_font(size='medium', weight='medium', \
445 stretch='normal', family='sans-serif', \
446 style='normal', variant='normal')
447
448 Ticks
449 ^^^^^
450
451 The methods to control properties relating to the tick marks are the following:
452
453 * Show/hide all ticks::
454
455 fig.ticks.show()
456 fig.ticks.hide()
457
458 * Show/hide the x-axis ticks::
459
460 fig.ticks.show_x()
461 fig.ticks.hide_x()
462
463 * Show/hide the y-axis ticks::
464
465 fig.ticks.show_y()
466 fig.ticks.hide_y()
467
468 * Change the tick spacing for the x- and y-axis::
469
470 fig.ticks.set_xspacing(0.04) # degrees
471 fig.ticks.set_yspacing(0.03) # degrees
472
473 * Change the length of the ticks::
474
475 fig.ticks.set_length(10) # points
476
477 * Change the color of the ticks::
478
479 fig.ticks.set_color('black')
480
481 * Set the line width for the ticks::
482
483 fig.ticks.set_linewidth(2) # points
484
485 * Set the number of minor ticks per major tick::
486
487 fig.ticks.set_minor_frequency(5)
488
489 Set this to ``1`` to get rid of minor ticks
490
491 Advanced
492 ^^^^^^^^
493
494 To control whether to refresh the display after each command, use the following method::
495
496 fig.set_auto_refresh(False)
497
498 To force a refresh, use::
499
500 fig.refresh()
501
502 To use the system LaTeX instead of the matplotlib LaTeX, use::
503
504 fig.set_system_latex(True)
505
506 The color for NaN values can be controlled using the following method::
507
508 fig.set_nan_color('black')
509
510 The order of figure elements (eg lines, shapes, imagemap) can be controlled using the zorder parameter using for example::
511
512 fig.show_ellipses(x_world, y_world, width, height, zorder=1)
513
514 Increasing integers from 0 will place elements towards the front. Setting zorder=0 places layer at the bottom.
515
516 Finally, to change the look of the plot using pre-set themes, use::
517
518 fig.set_theme('publication')