Debian Codegraph @

docs/tutorials/plots.rst

raw
1 .. include:: ../references.txt
2
3 .. _plots:
4
5 .. doctest-skip-all
6
7 ***********************
8 Plotting with Astroplan
9 ***********************
10
11 `astroplan` currently has convenience functions for making three different types
12 of plots: airmass vs time, parallactic angle vs time and sky charts. This
13 plotting functionality in `astroplan` requires `Matplotlib`_ (although non-
14 plotting functionality will work even without `Matplotlib`_ ). The use of
15 additional plotting packages (like `Seaborn
16 <http://stanford.edu/~mwaskom/software/seaborn/>`_) is not explicitly prevented,
17 but may or may not actually work.
18
19 All `astroplan` plots return a `~matplotlib.axes.Axes` object (which by
20 convention is assigned to the name ``ax`` in these tutorials). You can further
21 manipulate the returned ``ax`` object, including using it as input for more
22 `astroplan` plotting functions, or you can simply display/print the plot.
23
24 Contents
25 ========
26
27 * :ref:`plots_time_dependent`
28
29 * :ref:`plots_sky_charts`
30
31 * :ref:`finder_image`
32
33
34 .. _plots_time_dependent:
35
36 Time Dependent Plots
37 ====================
38
39 Although all `astroplan` plots are time-dependent in some way, we label those
40 that have a time-based axis as "time-dependent".
41
42 `astroplan` currently has a few different types of "time-dependent" plots,
43 for example `~astroplan.plots.plot_airmass`, `~astroplan.plots.plot_altitude`
44 and `~astroplan.plots.plot_parallactic`. These take, at minimum,
45 `~astroplan.Observer`, `~astroplan.FixedTarget` and `~astropy.time.Time` objects
46 as input.
47
48 .. _plots_airmass:
49
50 Airmass vs time plots are made the following way:
51
52 .. code-block:: python
53
54 >>> from astroplan.plots import plot_airmass
55
56 >>> plot_airmass(target, observer, time)
57
58 .. _plots_parallactic:
59
60 Parallactic angle vs time plots are made the following way:
61
62 .. code-block:: python
63
64 >>> from astroplan.plots import plot_airmass
65
66 >>> plot_parallactic(target, observer, time)
67
68 Below are general guidelines for working with time-dependent plots in
69 `astroplan`. Examples use airmass but apply to parallactic angle as well.
70
71 .. seealso::
72
73 `astropy.coordinates.AltAz.secz`
74
75 `astroplan.Observer.parallactic_angle`
76
77 Making a quick plot
78 -------------------
79
80 Any plot function in `astroplan` with a time-based axis will allow you to make
81 a quick plot over a 24-hour period.
82
83 After constructing `~astroplan.Observer` and `~astroplan.FixedTarget`
84 objects, construct a `~astropy.time.Time` object with a single instance in
85 time and issue the plotting command.
86
87 .. code-block:: python
88
89 >>> import matplotlib.pyplot as plt
90 >>> from astropy.time import Time
91 >>> from astroplan.plots import plot_airmass
92
93 >>> observe_time = Time('2000-06-15 23:30:00')
94
95 >>> plot_airmass(target, observer, observe_time)
96 >>> plt.show()
97
98 .. plot::
99
100 import matplotlib.pyplot as plt
101 import astropy.units as u
102 from astropy.coordinates import EarthLocation, SkyCoord
103 from pytz import timezone
104 from astropy.time import Time
105
106 from astroplan import Observer
107 from astroplan import FixedTarget
108 from astroplan.plots import plot_airmass
109
110 longitude = '-155d28m48.900s'
111 latitude = '+19d49m42.600s'
112 elevation = 4163 * u.m
113 location = EarthLocation.from_geodetic(longitude, latitude, elevation)
114
115 observer = Observer(name='Subaru Telescope',
116 location=location,
117 pressure=0.615 * u.bar,
118 relative_humidity=0.11,
119 temperature=0 * u.deg_C,
120 timezone=timezone('US/Hawaii'),
121 description="Subaru Telescope on Maunakea, Hawaii")
122
123 coordinates = SkyCoord('06h45m08.9173s', '-16d42m58.017s', frame='icrs')
124 target = FixedTarget(name='Sirius', coord=coordinates)
125
126 observe_time = Time('2000-06-15 23:30:00')
127
128 plot_airmass(target, observer, observe_time)
129 plt.tight_layout()
130 plt.show()
131
132 As you can see, the 24-hour plot is centered on the *time* input. You can also
133 use array `~astropy.time.Time` objects for these quick plots--they just
134 can't contain more than one instance in time.
135
136 For example, these are acceptable *time* inputs::
137
138 Time(['2000-06-15 23:30:00'])
139
140 [Time('2000-06-15 23:30:00')]
141
142 You can also add a second y-axis (on the right side) which shows the corresponding
143 altitude of the targets:
144
145 .. plot::
146
147 import matplotlib.pyplot as plt
148 import astropy.units as u
149 from astropy.coordinates import EarthLocation, SkyCoord
150 from pytz import timezone
151 from astropy.time import Time
152
153 from astroplan import Observer
154 from astroplan import FixedTarget
155 from astroplan.plots import plot_airmass
156
157 longitude = '-155d28m48.900s'
158 latitude = '+19d49m42.600s'
159 elevation = 4163 * u.m
160 location = EarthLocation.from_geodetic(longitude, latitude, elevation)
161
162 observer = Observer(name='Subaru Telescope',
163 location=location,
164 pressure=0.615 * u.bar,
165 relative_humidity=0.11,
166 temperature=0 * u.deg_C,
167 timezone=timezone('US/Hawaii'),
168 description="Subaru Telescope on Maunakea, Hawaii")
169
170 coordinates = SkyCoord('06h45m08.9173s', '-16d42m58.017s', frame='icrs')
171 target = FixedTarget(name='Sirius', coord=coordinates)
172
173 observe_time = Time('2000-06-15 23:30:00')
174
175 plot_airmass(target, observer, observe_time, altitude_yaxis=True)
176 plt.tight_layout()
177 plt.show()
178
179 You can make altitude the primary y-axis rather than airmass by using
180 `~astroplan.plots.plot_altitude`:
181
182 .. plot::
183
184 import matplotlib.pyplot as plt
185 import astropy.units as u
186 from astropy.coordinates import EarthLocation, SkyCoord
187 from pytz import timezone
188 from astropy.time import Time
189
190 from astroplan import Observer
191 from astroplan import FixedTarget
192 from astroplan.plots import plot_altitude
193
194 longitude = '-155d28m48.900s'
195 latitude = '+19d49m42.600s'
196 elevation = 4163 * u.m
197 location = EarthLocation.from_geodetic(longitude, latitude, elevation)
198
199 observer = Observer(name='Subaru Telescope',
200 location=location,
201 pressure=0.615 * u.bar,
202 relative_humidity=0.11,
203 temperature=0 * u.deg_C,
204 timezone=timezone('US/Hawaii'),
205 description="Subaru Telescope on Maunakea, Hawaii")
206
207 coordinates = SkyCoord('06h45m08.9173s', '-16d42m58.017s', frame='icrs')
208 target = FixedTarget(name='Sirius', coord=coordinates)
209
210 observe_time = Time('2000-06-15 23:30:00')
211
212 plot_altitude(target, observer, observe_time, airmass_yaxis=True)
213 plt.tight_layout()
214 plt.show()
215
216 .. _plots_time_window:
217
218 Specifying a time window
219 ------------------------
220
221 If you want to see airmass plotted over a window that is not 24 hours long or
222 you want to control the precision of the plot, you must specify every time for
223 which you want to see an airmass plotted. Therefore, an array
224 `~astropy.time.Time` object is necessary.
225
226 To quickly populate an `~astropy.time.Time` object with many instances of time,
227 use `Numpy`_ and `~astropy.units`. See example below.
228
229 Centering the window at some time
230 +++++++++++++++++++++++++++++++++
231
232 To center your window at some instance in time:
233
234 .. code-block:: python
235
236 >>> import numpy as np
237 >>> import matplotlib.pyplot as plt
238 >>> import astropy.units as u
239 >>> from astropy.time import Time
240 >>> from astroplan.plots import plot_airmass
241
242 >>> observe_time = Time('2000-06-15 23:30:00')
243 >>> observe_time = observe_time + np.linspace(-5, 5, 55)*u.hour
244
245 >>> plot_airmass(target, observer, observe_time)
246 >>> plt.show()
247
248 .. plot::
249
250 import matplotlib.pyplot as plt
251 import astropy.units as u
252 from astropy.coordinates import EarthLocation, SkyCoord
253 from pytz import timezone
254 from astropy.time import Time
255
256 from astroplan import Observer
257 from astroplan import FixedTarget
258 from astroplan.plots import plot_airmass
259
260 # Set up Observer, Target and observation time objects.
261 longitude = '-155d28m48.900s'
262 latitude = '+19d49m42.600s'
263 elevation = 4163 * u.m
264 location = EarthLocation.from_geodetic(longitude, latitude, elevation)
265
266 observer = Observer(name='Subaru Telescope',
267 location=location,
268 pressure=0.615 * u.bar,
269 relative_humidity=0.11,
270 temperature=0 * u.deg_C,
271 timezone=timezone('US/Hawaii'),
272 description="Subaru Telescope on Maunakea, Hawaii")
273
274 coordinates = SkyCoord('06h45m08.9173s', '-16d42m58.017s', frame='icrs')
275 target = FixedTarget(name='Sirius', coord=coordinates)
276
277 import numpy as np
278
279 observe_time = Time('2000-06-15 23:30:00')
280 observe_time = observe_time + np.linspace(-5, 5, 55)*u.hour
281
282 plot_airmass(target, observer, observe_time)
283 plt.tight_layout()
284 plt.show()
285
286 Specify start and end times
287 +++++++++++++++++++++++++++
288
289 If you know the start and end times of your observation run, you can use a
290 `~astropy.time.TimeDelta` object to create an array for time input::
291
292 >>> import numpy as np
293 >>> import matplotlib.pyplot as plt
294 >>> from astropy.time import Time
295 >>> from astroplan.plots import plot_airmass
296
297 >>> start_time = Time('2000-06-15 20:00:00')
298 >>> end_time = Time('2000-06-16 04:00:00')
299 >>> delta_t = end_time - start_time
300 >>> observe_time = start_time + delta_t*np.linspace(0, 1, 75)
301
302 >>> plot_airmass(target, observer, observe_time)
303 >>> plt.show()
304
305 .. plot::
306
307 import matplotlib.pyplot as plt
308 import astropy.units as u
309 from astropy.coordinates import EarthLocation, SkyCoord
310 from pytz import timezone
311 from astropy.time import Time
312
313 from astroplan import Observer
314 from astroplan import FixedTarget
315 from astroplan.plots import plot_airmass
316
317 # Set up Observer, Target and observation time objects.
318 longitude = '-155d28m48.900s'
319 latitude = '+19d49m42.600s'
320 elevation = 4163 * u.m
321 location = EarthLocation.from_geodetic(longitude, latitude, elevation)
322
323 observer = Observer(name='Subaru Telescope',
324 location=location,
325 pressure=0.615 * u.bar,
326 relative_humidity=0.11,
327 temperature=0 * u.deg_C,
328 timezone=timezone('US/Hawaii'),
329 description="Subaru Telescope on Maunakea, Hawaii")
330
331 coordinates = SkyCoord('06h45m08.9173s', '-16d42m58.017s', frame='icrs')
332 target = FixedTarget(name='Sirius', coord=coordinates)
333
334 start_time = Time('2000-06-15 20:00:00')
335 end_time = Time('2000-06-16 04:00:00')
336 delta_t = end_time - start_time
337 observe_time = start_time + delta_t*np.linspace(0, 1, 75)
338
339 plot_airmass(target, observer, observe_time)
340 plt.tight_layout()
341 plt.show()
342
343 Plotting a quantity for multiple targets
344 ----------------------------------------
345
346 If you want to plot airmass information for multiple targets, simply reissue
347 the `~astroplan.plots.plot_airmass` command, using a different
348 `~astroplan.FixedTarget` object as input this time. Repeat until you have as
349 many targets on the plot as you wish::
350
351 >>> import numpy as np
352 >>> import matplotlib.pyplot as plt
353 >>> from astropy.time import Time
354 >>> from astroplan.plots import plot_airmass
355
356 >>> observe_time = Time('2000-06-30 23:30:00') + np.linspace(-7.0, 5.5, 50)*u.hour
357
358 >>> plot_airmass(target, observer, observe_time)
359 >>> plot_airmass(other_target, observer, observe_time)
360 >>> plot_airmass(third_target, observer, observe_time)
361
362 >>> plt.legend(shadow=True, loc=2)
363 >>> plt.show()
364
365 .. plot::
366
367 import matplotlib.pyplot as plt
368 import astropy.units as u
369 from astropy.coordinates import EarthLocation, SkyCoord
370 from pytz import timezone
371 from astropy.time import Time
372
373 from astroplan import Observer
374 from astroplan import FixedTarget
375 from astroplan.plots import plot_airmass
376
377 longitude = '-155d28m48.900s'
378 latitude = '+19d49m42.600s'
379 elevation = 4163 * u.m
380 location = EarthLocation.from_geodetic(longitude, latitude, elevation)
381
382 observer = Observer(name='Subaru Telescope',
383 location=location,
384 pressure=0.615 * u.bar,
385 relative_humidity=0.11,
386 temperature=0 * u.deg_C,
387 timezone=timezone('US/Hawaii'),
388 description="Subaru Telescope on Maunakea, Hawaii")
389
390 coordinates = SkyCoord('06h45m08.9173s', '-16d42m58.017s', frame='icrs')
391 target = FixedTarget(name='Sirius', coord=coordinates)
392
393 coordinates = SkyCoord('02h31m49.09s', '+89d15m50.8s', frame='icrs')
394 other_target = FixedTarget(name='Polaris', coord=coordinates)
395
396 coordinates = SkyCoord('07h45m19.4s', '+28d01m35s', frame='icrs')
397 third_target = FixedTarget(name='Pollux', coord=coordinates)
398
399 observe_time = Time('2000-06-30 23:30:00') + np.linspace(-7.0, 5.5, 50)*u.hour
400
401 plot_airmass(target, observer, observe_time)
402 plot_airmass(other_target, observer, observe_time)
403 plot_airmass(third_target, observer, observe_time)
404
405 plt.legend(shadow=True, loc=2)
406 plt.tight_layout()
407 plt.show()
408
409 When you're ready to make a different plot, use ``ax.cla()`` to clear the
410 current `~matplotlib.axes.Axes` object.
411
412
413
414 .. _plots_style:
415
416 Changing style options
417 ----------------------
418
419 The default line for time-dependent plots is solid and the default label
420 (should you choose to display a legend) is the name contained in the
421 `~astroplan.Target` object. You can change the *linestyle*, *color*,
422 *label* and other plotting properties by setting the *style_kwargs* option.
423
424 .. code-block:: python
425
426 >>> import matplotlib.pyplot as plt
427 >>> from astroplan.plots import plot_airmass
428
429 >>> sirius_styles = {'linestyle': '--', 'color': 'r'}
430 >>> pollux_styles = {'color': 'g'}
431
432 >>> plot_airmass(target, observer, observe_time, style_kwargs=sirius_styles)
433 >>> plot_airmass(other_target, observer, observe_time, style_kwargs=pollux_styles)
434
435 >>> plt.legend(shadow=True, loc=2)
436 >>> plt.show()
437
438 .. plot::
439
440 import matplotlib.pyplot as plt
441 import astropy.units as u
442 from astropy.coordinates import EarthLocation, SkyCoord
443 from pytz import timezone
444 from astropy.time import Time
445
446 from astroplan import Observer
447 from astroplan import FixedTarget
448 from astroplan.plots import plot_airmass
449
450 longitude = '-155d28m48.900s'
451 latitude = '+19d49m42.600s'
452 elevation = 4163 * u.m
453 location = EarthLocation.from_geodetic(longitude, latitude, elevation)
454
455 observer = Observer(name='Subaru Telescope',
456 location=location,
457 pressure=0.615 * u.bar,
458 relative_humidity=0.11,
459 temperature=0 * u.deg_C,
460 timezone=timezone('US/Hawaii'),
461 description="Subaru Telescope on Maunakea, Hawaii")
462
463 coordinates = SkyCoord('06h45m08.9173s', '-16d42m58.017s', frame='icrs')
464 target = FixedTarget(name='Sirius', coord=coordinates)
465
466 coordinates = SkyCoord('07h45m19.4s', '+28d01m35s', frame='icrs')
467 other_target = FixedTarget(name='Pollux', coord=coordinates)
468
469 observe_time = Time('2000-06-30 23:30:00') + np.linspace(-10, 10, 50)*u.hour
470
471 sirius_styles = {'linestyle': '--', 'color': 'r'}
472 pollux_styles = {'color': 'g'}
473
474 plot_airmass(target, observer, observe_time, style_kwargs=sirius_styles)
475 plot_airmass(other_target, observer, observe_time, style_kwargs=pollux_styles)
476
477 plt.legend(shadow=True, loc=2)
478 plt.tight_layout()
479 plt.show()
480
481 See the `Matplotlib`_ documentation for information on plotting styles in line
482 plots.
483
484 Dark Theme Plots
485 ++++++++++++++++
486
487 By default, `astroplan` uses the `Astropy <https://astropy.org>`__ style sheet for `Matplotlib`_ to
488 generate plots with more pleasing settings than provided for by the matplotlib
489 defaults. When using `astroplan` at night, you may prefer to make plots with
490 dark backgrounds, rather than the default white background, to preserve your
491 night vision. To do so, you may use the `astroplan` dark style sheet to
492 produce dark-themed plots by using the *style_sheet* keyword argument in
493 any plotting function:
494
495 .. code-block:: python
496
497 >>> from astroplan.plots import dark_style_sheet, plot_airmass
498 >>> plot_airmass(target, observatory, time, style_sheet=dark_style_sheet)
499
500
501 .. plot::
502
503 from astropy.time import Time
504 from astropy.coordinates import SkyCoord
505 import astropy.units as u
506
507 from astroplan.plots import plot_airmass, dark_style_sheet
508 from astroplan import Observer, FixedTarget
509
510 import numpy as np
511 import matplotlib.pyplot as plt
512
513 vega = FixedTarget(coord=SkyCoord(ra=279.23473479*u.deg, dec=38.78368896*u.deg))
514 apo = Observer.at_site('APO')
515
516 plot_airmass(vega, apo, Time('2005-01-02 19:00') + np.linspace(-5, 5, 20)*u.hour,
517 style_sheet=dark_style_sheet)
518 plt.tight_layout()
519 plt.show()
520
521
522 Additional Options
523 ++++++++++++++++++
524
525 You can also shade the background according to the darkness of the sky (light
526 shading for 0 degree twilight, darker shading for -18 degree twilight) with
527 the ``brightness_shading`` keyword, and display additional y-axis ticks on the
528 right side of the axis with the altitudes in degrees using the
529 ``altitude_yaxis`` keyword:
530
531 .. code-block:: python
532
533 >>> import matplotlib.pyplot as plt
534 >>> from astropy.time import Time
535 >>> from astroplan import FixedTarget, Observer
536 >>> from astroplan.plots import plot_airmass
537
538 >>> time = Time('2018-01-02 19:00')
539 >>> target = FixedTarget.from_name('HD 189733')
540 >>> apo = Observer.at_site('APO')
541 >>> plot_airmass(target, apo, time, brightness_shading=True, altitude_yaxis=True)
542
543
544 .. plot::
545
546 from astroplan.plots import plot_airmass
547 import matplotlib.pyplot as plt
548 from astropy.time import Time
549 from astroplan import FixedTarget, Observer
550
551 time = Time('2018-01-02 19:00')
552 target = FixedTarget.from_name('HD 189733')
553 apo = Observer.at_site('APO')
554 plot_airmass(target, apo, time, brightness_shading=True, altitude_yaxis=True)
555 plt.tight_layout()
556 plt.show()
557
558
559
560 :ref:`Return to Top <plots>`
561
562
563 .. _plots_sky_charts:
564
565 Sky Charts
566 ==========
567
568 Many users planning an observation run will want to see the positions of targets
569 with respect to their local horizon, as well as the positions of familiar stars
570 or other objects to act as guides.
571
572 `~astroplan.plots.plot_sky` allows you to plot the positions of targets at a
573 single instance or over some window of time. You make this plot the
574 following way:
575
576 .. code-block:: python
577
578 >>> from astroplan.plots import plot_sky
579
580 >>> plot_sky(target, observer, time)
581
582 .. note::
583
584 `~astroplan.plots.plot_sky` currently produces polar plots in
585 altitude/azimuth coordinates only. Plots are centered on the observer's
586 zenith.
587
588 .. seealso::
589
590 `astroplan.Observer.altaz`
591
592 Making a plot for one instance in time
593 --------------------------------------
594
595 After constructing your `~astroplan.Observer` and `~astroplan.FixedTarget`
596 objects, construct a time input using an array of length 1.
597
598 That is, either an `~astropy.time.Time` object with an array containing one
599 time value (e.g., ``Time(['2000-1-1'])``) or an array containing one scalar
600 `~astropy.time.Time` object (e.g., ``[Time('2000-1-1')]``).
601
602 Let's say that you created `~astroplan.FixedTarget` objects for Polaris,
603 Altair, Vega and Deneb. To plot a map of the sky:
604
605 .. code-block:: python
606
607 >>> import matplotlib.pyplot as plt
608 >>> from astropy.time import Time
609 >>> from astroplan.plots import plot_sky
610
611 >>> observe_time = Time(['2000-03-15 15:30:00'])
612
613 >>> polaris_style = {color': 'k'}
614 >>> vega_style = {'color': 'g'}
615 >>> deneb_style = {'color': 'r'}
616
617 >>> plot_sky(polaris, observer, observe_time, style_kwargs=polaris_style)
618 >>> plot_sky(altair, observer, observe_time)
619 >>> plot_sky(vega, observer, observe_time, style_kwargs=vega_style)
620 >>> plot_sky(deneb, observer, observe_time, style_kwargs=deneb_style)
621
622 >>> plt.legend(loc='center left', bbox_to_anchor=(1.25, 0.5))
623 >>> plt.show()
624
625 .. note::
626
627 Since `~astroplan.plots.plot_sky` uses `~matplotlib.pyplot.scatter`
628 (which gives the same color to different plots made on the same set of
629 axes), you have to specify the color for each target via a style
630 dictionary if you don't want all targets to have the same color.
631
632 .. plot::
633
634 import matplotlib.pyplot as plt
635 import astropy.units as u
636 from astropy.coordinates import EarthLocation, SkyCoord
637 from pytz import timezone
638 from astropy.time import Time
639
640 from astroplan import Observer
641 from astroplan import FixedTarget
642 from astroplan.plots import plot_sky
643
644 # Set up Observer, Target and observation time objects.
645 longitude = '-155d28m48.900s'
646 latitude = '+19d49m42.600s'
647 elevation = 4163 * u.m
648 location = EarthLocation.from_geodetic(longitude, latitude, elevation)
649
650 observer = Observer(name='Subaru Telescope',
651 location=location,
652 pressure=0.615 * u.bar,
653 relative_humidity=0.11,
654 temperature=0 * u.deg_C,
655 timezone=timezone('US/Hawaii'),
656 description="Subaru Telescope on Maunakea, Hawaii")
657
658 coordinates = SkyCoord('02h31m49.09s', '+89d15m50.8s', frame='icrs')
659 polaris = FixedTarget(name='Polaris', coord=coordinates)
660 polaris_style = {'color': 'k'}
661
662 coordinates = SkyCoord('19h50m47.6s', '+08d52m12.0s', frame='icrs')
663 altair = FixedTarget(name='Altair', coord=coordinates)
664
665 coordinates = SkyCoord('18h36m56.5s', '+38d47m06.6s', frame='icrs')
666 vega = FixedTarget(name='Vega', coord=coordinates)
667 vega_style = {'color': 'g'}
668
669 coordinates = SkyCoord('20h41m25.9s', '+45d16m49.3s', frame='icrs')
670 deneb = FixedTarget(name='Deneb', coord=coordinates)
671 deneb_style = {'color': 'r'}
672
673 # Note that this is not a scalar.
674 observe_time = Time(['2000-03-15 15:30:00'])
675
676 plot_sky(polaris, observer, observe_time, style_kwargs=polaris_style)
677 plot_sky(altair, observer, observe_time)
678 plot_sky(vega, observer, observe_time, style_kwargs=vega_style)
679 plot_sky(deneb, observer, observe_time, style_kwargs=deneb_style)
680
681 # Note that you don't need this code block to produce the plot.
682 # It reduces the plot size for the documentation.
683 ax = plt.gca()
684 box = ax.get_position()
685 ax.set_position([box.x0, box.y0, box.width * 0.75, box.height * 0.75])
686
687 plt.legend(loc='center left', bbox_to_anchor=(1.25, 0.5))
688 plt.tight_layout()
689 plt.show()
690
691 Showing movement over time
692 --------------------------
693
694 If you want to see how your targets move over time, you need to explicitly
695 specify every instance in time.
696
697 Say I want to know how Altair moves in the sky over a 9-hour period:
698
699 .. code-block:: python
700
701 >>> import numpy as np
702 >>> import matplotlib.pyplot as plt
703 >>> import astropy.units as u
704 >>> from astroplan.plots import plot_sky
705
706 >>> observe_time = Time('2000-03-15 17:00:00')
707 >>> observe_time = observe_time + np.linspace(-4, 5, 10)*u.hour
708
709 >>> plot_sky(altair, observer, observe_time)
710
711 >>> plt.legend(loc='center left', bbox_to_anchor=(1.25, 0.5))
712 >>> plt.show()
713
714 .. plot::
715
716 import matplotlib.pyplot as plt
717 import astropy.units as u
718 from astropy.coordinates import EarthLocation, SkyCoord
719 from pytz import timezone
720 from astropy.time import Time
721
722 from astroplan import Observer
723 from astroplan import FixedTarget
724 from astroplan.plots import plot_sky
725
726 # Set up Observer, Target and observation time objects.
727 longitude = '-155d28m48.900s'
728 latitude = '+19d49m42.600s'
729 elevation = 4163 * u.m
730 location = EarthLocation.from_geodetic(longitude, latitude, elevation)
731
732 observer = Observer(name='Subaru Telescope',
733 location=location,
734 pressure=0.615 * u.bar,
735 relative_humidity=0.11,
736 temperature=0 * u.deg_C,
737 timezone=timezone('US/Hawaii'),
738 description="Subaru Telescope on Maunakea, Hawaii")
739
740 coordinates = SkyCoord('19h50m47.6s', '+08d52m12.0s', frame='icrs')
741 altair = FixedTarget(name='Altair', coord=coordinates)
742
743 import numpy as np
744
745 observe_time = Time('2000-03-15 17:00:00')
746 observe_time = observe_time + np.linspace(-4, 5, 10)*u.hour
747
748 plot_sky(altair, observer, observe_time)
749
750 # Note that you don't need this code block to produce the plot.
751 # It reduces the plot size for the documentation.
752 ax = plt.gca()
753 box = ax.get_position()
754 ax.set_position([box.x0, box.y0, box.width * 0.75, box.height * 0.75])
755
756 plt.legend(loc='center left', bbox_to_anchor=(1.25, 0.5))
757 plt.tight_layout()
758 plt.show()
759
760 For more examples on how to populate time objects, see `~astropy.time.Time`
761 documentation, or :ref:`plots_time_window`.
762
763 .. note::
764
765 Note that in the case of an object being under the horizon (or having
766 negative altitude) at any of the times in your *time* input,
767 `~astroplan.plots.plot_sky` will warn you. Your object(s) will not show
768 up on the plot for those particular times, but any positions above the
769 horizon will still be plotted as normal.
770
771 Customizing your sky plot
772 -------------------------
773
774 `astroplan` plots use `Matplotlib`_ defaults, so you can customize your plots in
775 much the same way you tweak any `Matplotlib`_ plot.
776
777
778 Setting style options
779 +++++++++++++++++++++
780
781 The default marker for `~astroplan.plots.plot_sky` is a circle and the
782 default label (should you choose to display a legend) is the name contained
783 in the `~astroplan.Target` object. You can change the *marker*, *color*,
784 *label* and other plotting properties by setting the *style_kwargs* option,
785 in the same way shown for the :ref:`time-dependent plots <plots_style>`.
786
787 One situation in which this is particularly useful is the plotting of guide
788 positions, such as a few familiar stars or any body used in calibrating your
789 telescope. You can also use this feature to set apart different types of targets
790 (e.g., high-priority, candidates for observing run, etc.).
791
792 See the `Matplotlib`_ documentation for information on plotting styles in
793 scatter plots.
794
795 Changing coordinate defaults
796 ++++++++++++++++++++++++++++
797
798 As seen in the above examples, the default position of North is at the top of
799 the plot, and South at the bottom, with azimuth increasing counter-clockwise
800 (CCW), putting East to the left, and West to the right.
801
802 You can't change the position of North or South (either in the actual plotting
803 of the data, or the labels), but you can "flip" East/West by changing the
804 direction in which azimuth increases via the *north_to_east_ccw* option:
805
806 .. code-block:: python
807
808 >>> import matplotlib.pyplot as plt
809 >>> from astroplan.plots import plot_sky
810
811 >>> guide_style = {'marker': '*'}
812
813 >>> plot_sky(polaris, observer, observe_time, snorth_to_east_ccw=False, style_kwargs=guide_style)
814 >>> plot_sky(altair, observer, observe_time, north_to_east_ccw=False)
815
816 >>> plt.legend(loc='center left', bbox_to_anchor=(1.25, 0.5))
817 >>> plt.show()
818
819 .. plot::
820
821 import matplotlib.pyplot as plt
822 import astropy.units as u
823 from astropy.coordinates import EarthLocation, SkyCoord
824 from pytz import timezone
825 from astropy.time import Time
826
827 from astroplan import Observer
828 from astroplan import FixedTarget
829 from astroplan.plots import plot_sky
830
831 # Set up Observer, Target and observation time objects.
832 longitude = '-155d28m48.900s'
833 latitude = '+19d49m42.600s'
834 elevation = 4163 * u.m
835 location = EarthLocation.from_geodetic(longitude, latitude, elevation)
836
837 observer = Observer(name='Subaru Telescope',
838 location=location,
839 pressure=0.615 * u.bar,
840 relative_humidity=0.11,
841 temperature=0 * u.deg_C,
842 timezone=timezone('US/Hawaii'),
843 description="Subaru Telescope on Maunakea, Hawaii")
844
845 coordinates = SkyCoord('02h31m49.09s', '+89d15m50.8s', frame='icrs')
846 polaris = FixedTarget(name='Polaris', coord=coordinates)
847
848 coordinates = SkyCoord('19h50m47.6s', '+08d52m12.0s', frame='icrs')
849 altair = FixedTarget(name='Altair', coord=coordinates)
850
851 import numpy as np
852
853 observe_time = Time('2000-03-15 17:00:00') + np.linspace(-4, 5, 10)*u.hour
854
855 guide_style = {'marker': '*'}
856
857 plot_sky(polaris, observer, observe_time, north_to_east_ccw=False,
858 style_kwargs=guide_style)
859 plot_sky(altair, observer, observe_time, north_to_east_ccw=False)
860
861 # Note that you don't need this code block to produce the plot.
862 # It reduces the plot size for the documentation.
863 ax = plt.gca()
864 box = ax.get_position()
865 ax.set_position([box.x0, box.y0, box.width * 0.75, box.height * 0.75])
866
867 plt.legend(loc='center left', bbox_to_anchor=(1.25, 0.5))
868 plt.tight_layout()
869 plt.show()
870
871 Some observatories may need to offset or rotate the azimuth labels due to their
872 particular telescope setup.
873
874 To do this, set *az_label_offset* equal to the number of degrees by which you
875 wish to rotate the labels. By default, *az_label_offset* is set to 0 degrees.
876 A positive offset is in the same direction as azimuth increase (see the
877 *north_to_east_ccw* option):
878
879 .. code-block:: python
880
881 >>> import matplotlib.pyplot as plt
882 >>> from astroplan.plots import plot_sky
883
884 >>> guide_style = {'marker': '*'}
885
886 >>> plot_sky(polaris, observer, observe_time, style_kwargs=guide_style, az_label_offset=180.0*u.deg)
887 >>> plot_sky(altair, observer, observe_time, az_label_offset=180.0*u.deg)
888
889 >>> plt.legend(loc='center left', bbox_to_anchor=(1.25, 0.5))
890 >>> plt.show()
891
892 .. plot::
893
894 import matplotlib.pyplot as plt
895 import astropy.units as u
896 from astropy.coordinates import EarthLocation, SkyCoord
897 from pytz import timezone
898 from astropy.time import Time
899
900 from astroplan import Observer
901 from astroplan import FixedTarget
902 from astroplan.plots import plot_sky
903
904 # Set up Observer, Target and observation time objects.
905 longitude = '-155d28m48.900s'
906 latitude = '+19d49m42.600s'
907 elevation = 4163 * u.m
908 location = EarthLocation.from_geodetic(longitude, latitude, elevation)
909
910 observer = Observer(name='Subaru Telescope',
911 location=location,
912 pressure=0.615 * u.bar,
913 relative_humidity=0.11,
914 temperature=0 * u.deg_C,
915 timezone=timezone('US/Hawaii'),
916 description="Subaru Telescope on Maunakea, Hawaii")
917
918 coordinates = SkyCoord('02h31m49.09s', '+89d15m50.8s', frame='icrs')
919 polaris = FixedTarget(name='Polaris', coord=coordinates)
920
921 coordinates = SkyCoord('19h50m47.6s', '+08d52m12.0s', frame='icrs')
922 altair = FixedTarget(name='Altair', coord=coordinates)
923
924 import numpy as np
925
926 observe_time = Time('2000-03-15 17:00:00') + np.linspace(-4, 5, 10)*u.hour
927
928 guide_style = {'marker': '*'}
929
930 plot_sky(polaris, observer, observe_time, style_kwargs=guide_style,
931 az_label_offset=180.0*u.deg)
932 plot_sky(altair, observer, observe_time, az_label_offset=180.0*u.deg)
933
934 # Note that you don't need this code block to produce the plot.
935 # It reduces the plot size for the documentation.
936 ax = plt.gca()
937 box = ax.get_position()
938 ax.set_position([box.x0, box.y0, box.width * 0.75, box.height * 0.75])
939
940 plt.legend(loc='center left', bbox_to_anchor=(1.25, 0.5))
941 plt.tight_layout()
942 plt.show()
943
944 .. note::
945
946 The *az_label_offset* option does not rotate the actual positions on the
947 plot, but simply the theta grid labels (which are drawn regardless of
948 gridline presence). Since labels are drawn with every call to
949 `~astroplan.plots.plot_sky`, we recommend you use the same
950 *az_label_offset* argument for every target on the same plot.
951
952 It is not advised that most users change this option, as it may **appear**
953 that your alt/az data does not coincide with the definition of altazimuth
954 (local horizon) coordinate system.
955
956 You can turn off the grid lines by setting the *grid* option to *False*:
957
958 .. code-block:: python
959
960 >>> import matplotlib.pyplot as plt
961 >>> from astroplan.plots import plot_sky
962
963 >>> guide_style = {'marker': '*'}
964
965 >>> plot_sky(polaris, observer, observe_time, style_kwargs=guide_style, grid=False)
966 >>> plot_sky(altair, observer, observe_time, grid=False)
967
968 >>> plt.legend(loc='center left', bbox_to_anchor=(1.25, 0.5))
969 >>> plt.show()
970
971 .. plot::
972
973 import matplotlib.pyplot as plt
974 import astropy.units as u
975 from astropy.coordinates import EarthLocation, SkyCoord
976 from pytz import timezone
977 from astropy.time import Time
978
979 from astroplan import Observer
980 from astroplan import FixedTarget
981 from astroplan.plots import plot_sky
982
983 # Set up Observer, Target and observation time objects.
984 longitude = '-155d28m48.900s'
985 latitude = '+19d49m42.600s'
986 elevation = 4163 * u.m
987 location = EarthLocation.from_geodetic(longitude, latitude, elevation)
988
989 observer = Observer(name='Subaru Telescope',
990 location=location,
991 pressure=0.615 * u.bar,
992 relative_humidity=0.11,
993 temperature=0 * u.deg_C,
994 timezone=timezone('US/Hawaii'),
995 description="Subaru Telescope on Maunakea, Hawaii")
996
997 coordinates = SkyCoord('02h31m49.09s', '+89d15m50.8s', frame='icrs')
998 polaris = FixedTarget(name='Polaris', coord=coordinates)
999
1000 coordinates = SkyCoord('19h50m47.6s', '+08d52m12.0s', frame='icrs')
1001 altair = FixedTarget(name='Altair', coord=coordinates)
1002
1003 import numpy as np
1004
1005 observe_time = Time('2000-03-15 17:00:00') + np.linspace(-4, 5, 10)*u.hour
1006
1007 guide_style = {'marker': '*'}
1008
1009 plot_sky(polaris, observer, observe_time, style_kwargs=guide_style,
1010 grid=False)
1011 plot_sky(altair, observer, observe_time, grid=False)
1012
1013 # Note that you don't need this code block to produce the plot.
1014 # It reduces the plot size for the documentation.
1015 ax = plt.gca()
1016 box = ax.get_position()
1017 ax.set_position([box.x0, box.y0, box.width * 0.75, box.height * 0.75])
1018
1019 plt.legend(loc='center left', bbox_to_anchor=(1.25, 0.5))
1020 plt.tight_layout()
1021 plt.show()
1022
1023 .. note::
1024
1025 Since grids are redrawn with every call to `~astroplan.plots.plot_sky`,
1026 you must set ``grid=False`` for every target in the same plot.
1027
1028 Other tweaks
1029 ++++++++++++
1030
1031 You can easily change other plot attributes by acting on the returned
1032 `matplotlib.axes.Axes` object or via `matplotlib.pyplot` calls (e.g.,
1033 ``plt.figure``, ``plt.rc``, etc.).
1034
1035 For instance, you can increase the size of your plot and its font:
1036
1037 .. code-block:: python
1038
1039 >>> # Set the figure size/font before you issue the plotting command.
1040 >>> plt.figure(figsize=(8,6))
1041 >>> plt.rc('font', size=14)
1042
1043 >>> plot_sky(polaris, observer, observe_time)
1044 >>> plot_sky(altair, observer, observe_time)
1045
1046 >>> plt.legend(loc='center left', bbox_to_anchor=(1.25, 0.5))
1047 >>> plt.show()
1048
1049 >>> # Change font size back to default once done plotting.
1050 >>> plt.rc('font', size=12)
1051
1052 :ref:`Return to Top <plots>`
1053
1054 Miscellaneous
1055 +++++++++++++
1056
1057 The easiest way to reuse the `~matplotlib.axes.Axes` object that is the base of
1058 your plots is to just let `astroplan`'s plotting functions take care of it in
1059 the background. You do, however, have the option of explicitly passing in a
1060 named axis, assuming that you have created the appropriate type for the
1061 particular plot you want.
1062
1063 We can explicitly give a name to the `~matplotlib.axes.Axes` object returned
1064 by `~astroplan.plots.plot_sky` when plotting Polaris and reuse it to plot
1065 Altair:
1066
1067 .. code-block:: python
1068
1069 >>> my_ax = plot_sky(polaris, observer, observe_time, style_kwargs=guide_style)
1070 >>> plot_sky(altair, observer, observe_time, my_ax)
1071
1072 We can also create a `~matplotlib.axes.Axes` object entirely outside of
1073 `~astroplan.plots.plot_sky`, then pass it in:
1074
1075 .. code-block:: python
1076
1077 >>> my_ax = plt.gcf().add_subplot(projection='polar')
1078 >>> plot_sky(polaris, observer, observe_time, my_ax)
1079
1080 Passing in named `matplotlib.axes.Axes` objects comes in handy when you want to
1081 make multiple plots:
1082
1083 .. code-block:: python
1084
1085 >>> from astroplan.plots import plot_sky
1086 >>> import matplotlib.pyplot as plt
1087
1088 >>> my_ax = plot_sky(polaris, observer, observe_time, style_kwargs=polaris_style)
1089 >>> plot_sky(altair, observer, observe_time, my_ax, style_kwargs=altair_style)
1090 >>> plt.legend(loc='center left', bbox_to_anchor=(1.3, 0.5))
1091
1092 >>> # Note that this plt.show (or another action, such as saving a figure) is critical in maintaining two separate plots.
1093 >>> plt.show()
1094
1095 >>> other_ax = plot_sky(vega, observer, observe_time, style_kwargs=vega_style)
1096 >>> plot_sky(deneb, observer, observe_time, other_ax, style_kwargs=deneb_style)
1097 >>> plt.legend(loc='center left', bbox_to_anchor=(1.25, 0.5))
1098 >>> plt.show()
1099
1100 .. plot::
1101
1102 import matplotlib.pyplot as plt
1103 import astropy.units as u
1104 from astropy.coordinates import EarthLocation, SkyCoord
1105 from pytz import timezone
1106 from astropy.time import Time
1107
1108 from astroplan import Observer
1109 from astroplan import FixedTarget
1110 from astroplan.plots import plot_sky
1111
1112 # Set up Observer, Target and observation time objects.
1113 longitude = '-155d28m48.900s'
1114 latitude = '+19d49m42.600s'
1115 elevation = 4163 * u.m
1116 location = EarthLocation.from_geodetic(longitude, latitude, elevation)
1117
1118 observer = Observer(name='Subaru Telescope',
1119 location=location,
1120 pressure=0.615 * u.bar,
1121 relative_humidity=0.11,
1122 temperature=0 * u.deg_C,
1123 timezone=timezone('US/Hawaii'),
1124 description="Subaru Telescope on Maunakea, Hawaii")
1125
1126 coordinates = SkyCoord('02h31m49.09s', '+89d15m50.8s', frame='icrs')
1127 polaris = FixedTarget(name='Polaris', coord=coordinates)
1128
1129 coordinates = SkyCoord('19h50m47.6s', '+08d52m12.0s', frame='icrs')
1130 altair = FixedTarget(name='Altair', coord=coordinates)
1131 altair_style = {'color': 'b'}
1132
1133 coordinates = SkyCoord('18h36m56.5s', '+38d47m06.6s', frame='icrs')
1134 vega = FixedTarget(name='Vega', coord=coordinates)
1135 vega_style = {'color': 'g'}
1136
1137 coordinates = SkyCoord('20h41m25.9s', '+45d16m49.3s', frame='icrs')
1138 deneb = FixedTarget(name='Deneb', coord=coordinates)
1139 deneb_style = {'color': 'r'}
1140
1141 observe_time = Time(['2000-03-15 15:30:00'])
1142
1143 my_ax = plot_sky(polaris, observer, observe_time)
1144 plot_sky(altair, observer, observe_time, my_ax, style_kwargs=altair_style)
1145
1146 # Note that you don't need this code block to produce the plot.
1147 # It reduces the plot size for the documentation.
1148 ax = plt.gca()
1149 box = ax.get_position()
1150 ax.set_position([box.x0, box.y0, box.width * 0.75, box.height * 0.75])
1151
1152 plt.legend(loc='center left', bbox_to_anchor=(1.3, 0.5))
1153
1154 # Note that this plt.show (or another action, such as saving a figure) is
1155 # critical in maintaining two separate plots.
1156 plt.tight_layout()
1157 plt.show()
1158
1159 other_ax = plot_sky(vega, observer, observe_time, style_kwargs=vega_style)
1160 plot_sky(deneb, observer, observe_time, other_ax, style_kwargs=deneb_style)
1161
1162 # Note that you don't need this code block to produce the plot.
1163 # It reduces the plot size for the documentation.
1164 ax = plt.gca()
1165 box = ax.get_position()
1166 ax.set_position([box.x0, box.y0, box.width * 0.75, box.height * 0.75])
1167
1168 plt.legend(loc='center left', bbox_to_anchor=(1.25, 0.5))
1169 plt.tight_layout()
1170 plt.show()
1171
1172 :ref:`Return to Top <plots>`
1173
1174 .. _finder_image:
1175
1176 Finder Chart/Image
1177 ==================
1178
1179 `astroplan` includes a function for generating quick finder images from
1180 Python, `~astroplan.plots.plot_finder_image`, by querying for images from
1181 sky surveys centered on a `~astroplan.FixedTarget`. This function depends on
1182 `astroquery`_ (in addition to `Matplotlib`_). In this example, we'll quickly
1183 make a finder image centered on The Crab Nebula (M1):
1184
1185 .. code-block:: python
1186
1187 >>> from astroplan.plots import plot_finder_image
1188 >>> from astroplan import FixedTarget
1189 >>> import matplotlib.pyplot as plt
1190
1191 >>> messier1 = FixedTarget.from_name("M1")
1192 >>> ax, hdu = plot_finder_image(messier1)
1193 >>> plt.show()
1194
1195 .. plot::
1196
1197 from astroplan import FixedTarget
1198 from astroplan.plots import plot_finder_image
1199 import matplotlib.pyplot as plt
1200
1201 messier1 = FixedTarget.from_name("M1")
1202 ax, hdu = plot_finder_image(messier1)
1203 plt.tight_layout()
1204 plt.show()
1205
1206
1207 :ref:`Return to Top <plots>`