Debian Codegraph @

docs/tutorials/summer_triangle.rst

raw
1 .. _summer_triangle_tutorial:
2
3 .. todo::
4
5 Add section on moon phases, illumination fraction, etc.
6
7 Replace target construction with easier site name function.
8
9 Update with constraints when available?
10
11 Show users how to create/use Time objects in their own timezone.
12
13 *****************************
14 Observing the Summer Triangle
15 *****************************
16
17 .. note::
18
19 Your calculated rise/set and other times may differ slightly from those in
20 this tutorial, on the order of ~1 second. This is a normal variance in
21 precision due to several factors, including varying :ref:`IERS tables <iers>`
22 and machine architecture.
23
24 Contents
25 ========
26
27 * :ref:`summer_triangle-defining_objects`
28
29 * :ref:`summer_triangle-observable`
30
31 * :ref:`summer_triangle-optimal_observation`
32
33 * :ref:`summer_triangle-sky_charts`
34
35 .. _summer_triangle-defining_objects:
36
37 Defining Objects
38 ================
39
40 Say we want to look at the Summer Triangle (Altair, Deneb, and Vega) using the
41 Subaru Telescope.
42
43 First, we define our `~astroplan.Observer` object:
44
45 .. code-block:: python
46
47 >>> from astroplan import Observer
48
49 >>> subaru = Observer.at_site('subaru')
50
51 Then, we define our `~astroplan.FixedTarget`'s, since the Summer Triangle is
52 fixed with respect to the celestial sphere (if we ignore the relatively small
53 proper motion). We will use the `~astroplan.FixedTarget.from_name` class method,
54 which queries the CDS name resolver for your target's coordinates (giving you
55 the power of SIMBAD!):
56
57 .. code-block:: python
58
59 >>> from astropy.coordinates import SkyCoord
60 >>> from astroplan import FixedTarget
61
62 >>> altair = FixedTarget.from_name('Altair')
63 >>> vega = FixedTarget.from_name('Vega')
64
65
66 For objects that can't be resolved with `~astroplan.FixedTarget.from_name`, you
67 can enter coordinates manually:
68
69 .. code-block:: python
70
71 >>> coordinates = SkyCoord('20h41m25.9s', '+45d16m49.3s', frame='icrs')
72 >>> deneb = FixedTarget(name='Deneb', coord=coordinates)
73
74 We also have to define a `~astropy.time.Time` (in UTC) at which we wish to
75 observe. Here, we pick 2AM local time, which is noon UTC during the
76 summer::
77
78 >>> from astropy.time import Time
79
80 >>> time = Time('2015-06-16 12:00:00')
81
82 :ref:`Return to Top <summer_triangle_tutorial>`
83
84 .. _summer_triangle-observable:
85
86 Observable?
87 ===========
88
89 Next, it would be handy to know if our targets are visible from Subaru at the
90 time we settled on. In other words--are they above the horizon while the Sun
91 is down?
92
93 .. code-block:: python
94
95 >>> subaru.target_is_up(time, altair)
96 True
97
98 >>> subaru.target_is_up(time, vega)
99 True
100
101 >>> subaru.target_is_up(time, deneb)
102 True
103
104 ...They are!
105
106 What if we weren't sure if the Sun is down at this time:
107
108 .. code-block:: python
109
110 >>> subaru.is_night(time)
111 True
112
113 ...It is!
114
115 However, we may want to find a window of time for tonight during which all
116 three of our targets are above the horizon *and* the Sun is below the horizon
117 (let's worry about light pollution from the Moon later).
118
119 Let's define the window of time during which all targets are above the horizon.
120
121 Note that because of the precision limitations of rise/set calculations
122 (altitudes at these times won't equal precisely zero, but will be off by a few
123 arc seconds), we'll manually adjust rise/set times by a few minutes.
124
125 .. code-block:: python
126
127 >>> import numpy as np
128 >>> import astropy.units as u
129
130 >>> altair_rise = subaru.target_rise_time(time, altair) + 5*u.minute
131 >>> altair_set = subaru.target_set_time(time, altair) - 5*u.minute
132
133 >>> vega_rise = subaru.target_rise_time(time, vega) + 5*u.minute
134 >>> vega_set = subaru.target_set_time(time, vega) - 5*u.minute
135
136 >>> deneb_rise = subaru.target_rise_time(time, deneb) + 5*u.minute
137 >>> deneb_set = subaru.target_set_time(time, deneb) - 5*u.minute
138
139 >>> all_up_start = np.max([altair_rise, vega_rise, deneb_rise])
140 >>> all_up_end = np.min([altair_set, vega_set, deneb_set])
141
142 Now, let's find sunset and sunrise for tonight (and confirm that they are
143 indeed those for tonight):
144
145 .. code-block:: python
146
147 >>> sunset_tonight = subaru.sun_set_time(time, which='nearest')
148
149 >>> sunset_tonight.iso # doctest: +SKIP
150 '2015-06-16 04:59:11.267'
151
152 This is '2015-06-15 18:59:11.267' in the Hawaii time zone (that's where Subaru
153 is).
154
155 .. code-block:: python
156
157 >>> sunrise_tonight = subaru.sun_rise_time(time, which='nearest')
158
159 >>> sunrise_tonight.iso # doctest: +SKIP
160 '2015-06-16 15:47:35.822'
161
162 This is '2015-06-16 05:47:35.822' Hawaii time.
163
164 Sunset and sunrise check out, so now we define the limits of our observation
165 window:
166
167 .. code-block:: python
168
169 >>> start = np.max([sunset_tonight, all_up_start])
170 >>> start.iso # doctest: +SKIP
171 '2015-06-16 06:28:40.126'
172
173 >>> end = np.min([sunrise_tonight, all_up_end])
174 >>> end.iso # doctest: +SKIP
175 '2015-06-16 15:47:35.822'
176
177 So, our targets will be visible (as we've defined it above) from
178 '2015-06-15 20:28:40.126' to '2015-06-16 05:47:35.822' Hawaii time. Depending
179 on our observation goals, this window of time may be good enough for preliminary
180 planning, or we may want to optimize our observational conditions. If the
181 latter is the case, go on to the Optimal Observation Time section (immediately
182 below).
183
184 :ref:`Return to Top <summer_triangle_tutorial>`
185
186 .. _summer_triangle-optimal_observation:
187
188 Optimal Observation Time
189 ========================
190
191 There are a few things we can look at to find the best time to observe our
192 targets on a given night.
193
194 Airmass
195 -------
196
197 To get a general idea of our targets' airmass on the night of observation, we
198 can plot it over the course of the night (for more on plotting see :doc:`plots`):
199
200 .. code-block:: python
201
202 >>> from astroplan.plots import plot_airmass # doctest: +SKIP
203 >>> import matplotlib.pyplot as plt # doctest: +SKIP
204
205 >>> plot_airmass(altair, subaru, time) # doctest: +SKIP
206 >>> plot_airmass(vega, subaru, time) # doctest: +SKIP
207 >>> plot_airmass(deneb, subaru, time) # doctest: +SKIP
208
209 >>> plt.legend(loc=1, bbox_to_anchor=(1, 1)) # doctest: +SKIP
210 >>> plt.show() # doctest: +SKIP
211
212 .. plot::
213
214 import astropy.units as u
215 from astropy.coordinates import EarthLocation, SkyCoord
216 import matplotlib.pyplot as plt
217 from pytz import timezone
218
219 from astroplan import Observer, FixedTarget
220 from astroplan.plots import plot_airmass
221
222 longitude = '-155d28m48.900s'
223 latitude = '+19d49m42.600s'
224 elevation = 4163 * u.m
225 location = EarthLocation.from_geodetic(longitude, latitude, elevation)
226
227 subaru = Observer(name='Subaru Telescope',
228 location=location,
229 timezone=timezone('US/Hawaii'),
230 description="Subaru Telescope on Maunakea, Hawaii")
231
232 coordinates = SkyCoord('19h50m47.6s', '+08d52m12.0s', frame='icrs')
233 altair = FixedTarget(name='Altair', coord=coordinates)
234
235 coordinates = SkyCoord('18h36m56.5s', '+38d47m06.6s', frame='icrs')
236 vega = FixedTarget(name='Vega', coord=coordinates)
237
238 coordinates = SkyCoord('20h41m25.9s', '+45d16m49.3s', frame='icrs')
239 deneb = FixedTarget(name='Deneb', coord=coordinates)
240
241 from astropy.time import Time
242
243 time = Time('2015-06-16 12:00:00')
244
245 plot_airmass(altair, subaru, time)
246 plot_airmass(vega, subaru, time)
247 plot_airmass(deneb, subaru, time)
248
249 # Note that you don't need this code block to produce the plot.
250 # It reduces the plot size for the documentation.
251 ax = plt.gca()
252 box = ax.get_position()
253 ax.set_position([box.x0, box.y0, box.width * 0.8, box.height * 0.8])
254
255 plt.legend(loc=1, bbox_to_anchor=(1.35, 1))
256 plt.tight_layout()
257 plt.show()
258
259 We want a minimum airmass when observing, and it looks like sometime between
260 9:00 and 15:00 UTC (or 23:00 on the 15th to 5:00 on the 16th, US/Hawaii) would
261 be the best time to observe all three targets.
262
263 However, if we want to define a more specific time window based on airmass, we
264 can calculate this quantity directly. To get airmass measurements, we need to
265 use the ``AltAz`` frame:
266
267 .. code-block:: python
268
269 >>> subaru.altaz(time, altair).secz # doctest: +SKIP
270 <Quantity 1.0302347952130682>
271
272 >>> subaru.altaz(time, vega).secz # doctest: +SKIP
273 <Quantity 1.0690421636016616>
274
275 >>> subaru.altaz(time, deneb).secz # doctest: +SKIP
276 <Quantity 1.167753811648361>
277
278 Behind the scenes here, ``subaru.altaz(time, altair)`` is actually creating
279 an `~astropy.coordinates.AltAz` object in the ``AltAz`` frame, so if you
280 know how to work with `~astropy.coordinates` objects, you can do lots more
281 than just computing airmass.
282
283 Parallactic Angle
284 -----------------
285
286 To get a general idea of our targets' parallactic angle on the night of
287 observation, we can make another plot (again, see :doc:`plots` for more on
288 customizing plots and the like):
289
290 .. code-block:: python
291
292 >>> import matplotlib.pyplot as plt # doctest: +SKIP
293 >>> from astroplan.plots import plot_parallactic # doctest: +SKIP
294
295 >>> plot_parallactic(altair, subaru, time) # doctest: +SKIP
296 >>> plot_parallactic(vega, subaru, time) # doctest: +SKIP
297 >>> plot_parallactic(deneb, subaru, time) # doctest: +SKIP
298
299 >>> plt.legend(loc=2) # doctest: +SKIP
300 >>> plt.show() # doctest: +SKIP
301
302 .. plot::
303
304 import astropy.units as u
305 from astropy.coordinates import EarthLocation
306 from pytz import timezone
307 from astroplan import Observer
308
309 longitude = '-155d28m48.900s'
310 latitude = '+19d49m42.600s'
311 elevation = 4163 * u.m
312 location = EarthLocation.from_geodetic(longitude, latitude, elevation)
313
314 subaru = Observer(name='Subaru Telescope',
315 location=location,
316 timezone=timezone('US/Hawaii'),
317 description="Subaru Telescope on Maunakea, Hawaii")
318
319 from astropy.coordinates import SkyCoord
320 from astroplan import FixedTarget
321
322 coordinates = SkyCoord('19h50m47.6s', '+08d52m12.0s', frame='icrs')
323 altair = FixedTarget(name='Altair', coord=coordinates)
324
325 coordinates = SkyCoord('18h36m56.5s', '+38d47m06.6s', frame='icrs')
326 vega = FixedTarget(name='Vega', coord=coordinates)
327
328 coordinates = SkyCoord('20h41m25.9s', '+45d16m49.3s', frame='icrs')
329 deneb = FixedTarget(name='Deneb', coord=coordinates)
330
331 from astropy.time import Time
332
333 time = Time('2015-06-16 12:00:00')
334
335 from astroplan.plots import plot_parallactic
336 import matplotlib.pyplot as plt
337
338 plot_parallactic(altair, subaru, time)
339 plot_parallactic(vega, subaru, time)
340 plot_parallactic(deneb, subaru, time)
341
342 plt.legend(loc=2)
343 plt.tight_layout()
344 plt.show()
345
346 We can also calculate the parallactic angle directly:
347
348 .. code-block:: python
349
350 >>> subaru.parallactic_angle(time, altair) # doctest: +SKIP
351 <Angle -0.6404957821112053 rad>
352
353 >>> subaru.parallactic_angle(time, vega) # doctest: +SKIP
354 <Angle -0.46542183982024 rad>
355
356 >>> subaru.parallactic_angle(time, deneb) # doctest: +SKIP
357 <Angle 0.7297067855978494 rad>
358
359 The `~astropy.coordinates.Angle` objects resulting from the calls to
360 ``parallactic_angle()`` are subclasses of the `~astropy.units.Quantity`
361 class, so they can do everything a `~astropy.units.Quantity` can do -
362 basically they work like numbers with attached units, and keep track of
363 units so you don't have to.
364
365 For more on the many things you can do with these, take a look at the
366 `Astropy <https://astropy.org>`__ documentation or tutorials. For now the most useful thing is to
367 know is that ``angle.degree``, ``angle.hourangle``, and ``angle.radian``
368 give you back Python floats (or `numpy` arrays) for the angle in degrees,
369 hours, or radians.
370
371 The Moon
372 --------
373
374 If you need to take the Moon into account when observing, you may want to know
375 when it rises, sets, what phase it's in, etc. Let's first find out if the Moon
376 is out during the time we defined earlier:
377
378 .. code-block:: python
379
380 >>> subaru.moon_rise_time(time) # doctest: +SKIP
381 <Time object: scale='utc' format='jd' value=2457190.1696768994>
382
383 >>> subaru.moon_set_time(time) # doctest: +SKIP
384 <Time object: scale='utc' format='jd' value=2457189.684134357>
385
386 We could also look at the Moon's alt/az coordinates:
387
388 .. code-block:: python
389
390 >>> subaru.moon_altaz(time).alt # doctest: +SKIP
391 <Latitude -45.08860929634166 deg>
392
393 >>> subaru.moon_altaz(time).az # doctest: +SKIP
394 <Longitude 34.605498354422686 deg>
395
396 It looks like the Moon is well below the horizon at the time we picked before,
397 but we should check to see if it will be out during the window of time our
398 targets will be visible (again--as defined at the beginning of this tutorial):
399
400 .. code-block:: python
401
402 >>> visible_time = start + (end - start)*np.linspace(0, 1, 20)
403
404 >>> subaru.moon_altaz(visible_time).alt # doctest: +SKIP
405 <Latitude [-25.21127325,-30.68088873,-35.82145644,-40.53415037,
406 -44.68898859,-48.12296182,-50.64971858,-52.08946099,
407 -52.31849772,-51.31548444,-49.17038499,-46.04862654,
408 -42.13887599,-37.61479774,-32.61875342,-27.26048709,
409 -21.62215227,-15.76463668, -9.73313141, -2.19408792] deg>
410
411
412 Looks like the Moon will be below the horizon during the entire time.
413
414 :ref:`Return to Top <summer_triangle_tutorial>`
415
416 .. _summer_triangle-sky_charts:
417
418 Sky Charts
419 ==========
420
421 Now that we've determined the best times to observe our targets on the night in
422 question, let's take a look at the positions of our objects in the sky.
423
424 We can use `~astroplan.plots.plot_sky` as a sanity check on our target's
425 positions or even just to better visualize our observation run.
426
427 Let's take the ``start`` and ``end`` of the time window we determined
428 :ref:`earlier <summer_triangle-observable>` (using the most basic definition
429 of "visible" targets, above the horizon when the sun is down), and see where our
430 targets lay in the sky:
431
432 .. code-block:: python
433
434 >>> from astroplan.plots import plot_sky
435 >>> import matplotlib.pyplot as plt # doctest: +SKIP
436
437 >>> altair_style = {'color': 'r'}
438 >>> deneb_style = {'color': 'g'}
439
440 >>> plot_sky(altair, subaru, start, style_kwargs=altair_style) # doctest: +SKIP
441 >>> plot_sky(vega, subaru, start) # doctest: +SKIP
442 >>> plot_sky(deneb, subaru, start, style_kwargs=deneb_style) # doctest: +SKIP
443
444 >>> plt.legend(loc='center left', bbox_to_anchor=(1.25, 0.5)) # doctest: +SKIP
445 >>> plt.show() # doctest: +SKIP
446
447 >>> plot_sky(altair, subaru, end, style_kwargs=altair_style) # doctest: +SKIP
448 >>> plot_sky(vega, subaru, end) # doctest: +SKIP
449 >>> plot_sky(deneb, subaru, end, style_kwargs=deneb_style) # doctest: +SKIP
450
451 >>> plt.legend(loc='center left', bbox_to_anchor=(1.25, 0.5)) # doctest: +SKIP
452 >>> plt.show() # doctest: +SKIP
453
454 .. plot::
455
456
457 from astropy.coordinates import EarthLocation, SkyCoord
458 from astropy.time import Time
459 import astropy.units as u
460 import matplotlib.pyplot as plt
461 from pytz import timezone
462
463 from astroplan import Observer, FixedTarget
464 from astroplan.plots import plot_sky
465
466 longitude = '-155d28m48.900s'
467 latitude = '+19d49m42.600s'
468 elevation = 4163 * u.m
469 location = EarthLocation.from_geodetic(longitude, latitude, elevation)
470
471 subaru = Observer(name='Subaru Telescope',
472 location=location,
473 timezone=timezone('US/Hawaii'),
474 description="Subaru Telescope on Maunakea, Hawaii")
475
476 coordinates = SkyCoord('19h50m47.6s', '+08d52m12.0s', frame='icrs')
477 altair = FixedTarget(name='Altair', coord=coordinates)
478
479 coordinates = SkyCoord('18h36m56.5s', '+38d47m06.6s', frame='icrs')
480 vega = FixedTarget(name='Vega', coord=coordinates)
481
482 coordinates = SkyCoord('20h41m25.9s', '+45d16m49.3s', frame='icrs')
483 deneb = FixedTarget(name='Deneb', coord=coordinates)
484
485 start = Time('2015-06-16 06:28:40.126')
486 end = Time('2015-06-16 15:47:35.822')
487
488 altair_style = {'color': 'r'}
489 deneb_style = {'color': 'g'}
490
491 plot_sky(altair, subaru, start, style_kwargs=altair_style)
492 plot_sky(vega, subaru, start)
493 plot_sky(deneb, subaru, start, style_kwargs=deneb_style)
494
495 # Note that you don't need this code block to produce the plot.
496 # It reduces the plot size for the documentation.
497 ax = plt.gca()
498 box = ax.get_position()
499 ax.set_position([box.x0, box.y0, box.width * 0.75, box.height * 0.75])
500
501 plt.legend(loc='center left', bbox_to_anchor=(1.25, 0.5))
502 plt.tight_layout()
503 plt.show()
504
505 plot_sky(altair, subaru, end, style_kwargs=altair_style)
506 plot_sky(vega, subaru, end)
507 plot_sky(deneb, subaru, end, style_kwargs=deneb_style)
508
509 # Note that you don't need this code block to produce the plot.
510 # It reduces the plot size for the documentation.
511 ax = plt.gca()
512 box = ax.get_position()
513 ax.set_position([box.x0, box.y0, box.width * 0.75, box.height * 0.75])
514
515 plt.legend(loc='center left', bbox_to_anchor=(1.25, 0.5))
516 plt.tight_layout()
517 plt.show()
518
519 We can also show how our targets move over time during the night in question::
520
521 >>> time_window = start + (end - start) * np.linspace(0, 1, 10)
522
523 >>> plot_sky(altair, subaru, time_window, style_kwargs=altair_style) # doctest: +SKIP
524 >>> plot_sky(vega, subaru, time_window) # doctest: +SKIP
525 >>> plot_sky(deneb, subaru, time_window, style_kwargs=deneb_style) # doctest: +SKIP
526
527 >>> plt.legend(loc='center left', bbox_to_anchor=(1.25, 0.5)) # doctest: +SKIP
528 >>> plt.show() # doctest: +SKIP
529
530 .. plot::
531
532 import numpy as np
533 from astropy.coordinates import EarthLocation, SkyCoord
534 from astropy.time import Time
535 import astropy.units as u
536 import matplotlib.pyplot as plt
537 from pytz import timezone
538
539 from astroplan import Observer, FixedTarget
540 from astroplan.plots import plot_sky
541
542 longitude = '-155d28m48.900s'
543 latitude = '+19d49m42.600s'
544 elevation = 4163 * u.m
545 location = EarthLocation.from_geodetic(longitude, latitude, elevation)
546
547 subaru = Observer(name='Subaru Telescope',
548 location=location,
549 timezone=timezone('US/Hawaii'),
550 description="Subaru Telescope on Maunakea, Hawaii")
551
552 coordinates = SkyCoord('19h50m47.6s', '+08d52m12.0s', frame='icrs')
553 altair = FixedTarget(name='Altair', coord=coordinates)
554
555 coordinates = SkyCoord('18h36m56.5s', '+38d47m06.6s', frame='icrs')
556 vega = FixedTarget(name='Vega', coord=coordinates)
557
558 coordinates = SkyCoord('20h41m25.9s', '+45d16m49.3s', frame='icrs')
559 deneb = FixedTarget(name='Deneb', coord=coordinates)
560
561 start = Time('2015-06-16 06:28:40.126')
562 end = Time('2015-06-16 15:47:35.822')
563
564 time_window = start + (end - start) * np.linspace(0, 1, 10)
565
566 altair_style = {'color': 'r'}
567 deneb_style = {'color': 'g'}
568
569 plot_sky(altair, subaru, time_window, style_kwargs=altair_style)
570 plot_sky(vega, subaru, time_window)
571 plot_sky(deneb, subaru, time_window, style_kwargs=deneb_style)
572
573 plt.legend(loc='center left', bbox_to_anchor=(1.25, 0.5))
574
575 plt.tight_layout()
576
577 plt.show()