Debian Codegraph @

docs/tutorials/constraints.rst

raw
1 .. include:: ../references.txt
2
3 .. doctest-skip-all
4
5 .. _constraints:
6
7 ******************************
8 Defining Observing Constraints
9 ******************************
10
11 Contents
12 ========
13
14 * :ref:`constraints-built_in_constraints`
15 * :ref:`constraints-visualize_constraints`
16 * :ref:`constraints-user_defined_constraints`
17
18 .. _constraints-built_in_constraints:
19
20 Introduction to Built-In Constraints
21 ====================================
22
23 Frequently, we have a long list of targets that we want to observe, and we need
24 to know which ones are observable given a set of constraints imposed on our
25 observations by a wide range of limitations. For example, your telescope may
26 only point over a limited range of altitudes, your targets are only useful
27 in a range of airmasses, and they must be separated from the moon by some
28 large angle. The ``constraints`` module is here to help!
29
30 Say we're planning to observe from Subaru Observatory in Hawaii on August 1,
31 2015 from 06:00-12:00 UTC. First, let's set up an `~astroplan.Observer` object::
32
33 from astroplan import Observer, FixedTarget
34 from astropy.time import Time
35 subaru = Observer.at_site("Subaru")
36 time_range = Time(["2015-08-01 06:00", "2015-08-01 12:00"])
37
38 We're keeping a list of targets in a text file called ``targets.txt``, which
39 looks like this::
40
41 # name ra_degrees dec_degrees
42 Polaris 37.95456067 89.26410897
43 Vega 279.234734787 38.783688956
44 Albireo 292.68033548 27.959680072
45 Algol 47.042218553 40.955646675
46 Rigel 78.634467067 -8.201638365
47 Regulus 152.092962438 11.967208776
48
49 We'll read in this list of targets using `astropy.table`, and create a list
50 of `~astroplan.FixedTarget` objects out of them::
51
52 # Read in the table of targets
53 from astropy.table import Table
54 target_table = Table.read('targets.txt', format='ascii')
55
56 # Create astroplan.FixedTarget objects for each one in the table
57 from astropy.coordinates import SkyCoord
58 import astropy.units as u
59 targets = [FixedTarget(coord=SkyCoord(ra=ra*u.deg, dec=dec*u.deg), name=name)
60 for name, ra, dec in target_table]
61
62 We will build a bulleted list of our constraints first, then implement them in
63 code below.
64
65 * Our observations with Subaru can only occur between altitudes of ~10-80
66 degrees, which we can define using the
67 `~astroplan.constraints.AltitudeConstraint` class.
68
69 * We place an upper limit on the airmass of each target during observations
70 using the `~astroplan.constraints.AirmassConstraint` class.
71
72 * Since we're optical observers, we only want to observe targets at night, so
73 we'll also call the `~astroplan.constraints.AtNightConstraint` class. We're
74 not terribly worried about sky brightness for these bright stars, so we'll
75 define "night" times as those between civil twilights by using the class
76 method `~astroplan.AtNightConstraint.twilight_civil`:
77
78 .. code-block:: python
79
80 from astroplan import (AltitudeConstraint, AirmassConstraint,
81 AtNightConstraint)
82 constraints = [AltitudeConstraint(10*u.deg, 80*u.deg),
83 AirmassConstraint(5), AtNightConstraint.twilight_civil()]
84
85 This list of constraints can now be applied to our target list to determine:
86
87 * whether the targets are observable given the constraints at *any* times in the
88 time range, using `~astroplan.is_observable`,
89
90 * whether the targets are observable given the constraints at *all* times in the
91 time range, using `~astroplan.is_always_observable`
92
93 * during what months the targets are *ever* observable given the constraints,
94 using `~astroplan.months_observable`::
95
96 from astroplan import is_observable, is_always_observable, months_observable
97 # Are targets *ever* observable in the time range?
98 ever_observable = is_observable(constraints, subaru, targets, time_range=time_range)
99
100 # Are targets *always* observable in the time range?
101 always_observable = is_always_observable(constraints, subaru, targets, time_range=time_range)
102
103 # During what months are the targets ever observable?
104 best_months = months_observable(constraints, subaru, targets, time_range)
105
106 The `~astroplan.is_observable` and `~astroplan.is_always_observable` functions
107 will return boolean arrays which tell you whether or not each target is
108 observable given your constraints. Let's print these results in tabular form:
109
110 >>> from astropy.table import Table
111 >>> import numpy as np
112 >>> observability_table = Table()
113 >>> observability_table['targets'] = [target.name for target in targets]
114 >>> observability_table['ever_observable'] = ever_observable
115 >>> observability_table['always_observable'] = always_observable
116 >>> print(observability_table)
117 <Table length=6>
118 targets ever_observable always_observable
119 str7 bool bool
120 ------- --------------- -----------------
121 Polaris True True
122 Vega True True
123 Albireo True False
124 Algol True False
125 Rigel False False
126 Regulus False False
127
128 Now we can see which targets are observable! You can also use the
129 `~astroplan.observability_table` method to do the same calculations and
130 store the results in a table, all in one step::
131
132 >>> from astroplan import observability_table
133 >>> table = observability_table(constraints, subaru, targets, time_range=time_range)
134 >>> print(table)
135 target name ever observable always observable fraction of time observable
136 ----------- --------------- ----------------- ---------------------------
137 Polaris True True 1.0
138 Vega True True 1.0
139 Albireo True False 0.833333333333
140 Algol True False 0.166666666667
141 Rigel False False 0.0
142 Regulus False False 0.0
143
144 Let's sanity-check these results using `~astroplan.plots.plot_sky` to plot
145 the positions of the targets throughout the time range:
146
147 .. plot::
148
149 from astroplan.plots import plot_sky
150 from astroplan import Observer, FixedTarget
151
152 import matplotlib.pyplot as plt
153 from matplotlib import cm
154 from astropy.time import Time
155 from astropy.coordinates import SkyCoord
156 import astropy.units as u
157
158
159 # Get grid of times within the time_range limits
160 from astroplan import time_grid_from_range
161 time_range = Time(["2015-08-01 06:00", "2015-08-01 12:00"])
162 time_grid = time_grid_from_range(time_range)
163
164 subaru = Observer.at_site("Subaru")
165
166 target_table_string = """# name ra_degrees dec_degrees
167 Polaris 37.95456067 89.26410897
168 Vega 279.234734787 38.783688956
169 Albireo 292.68033548 27.959680072
170 Algol 47.042218553 40.955646675
171 Rigel 78.634467067 -8.201638365
172 Regulus 152.092962438 11.967208776"""
173 # Read in the table of targets
174 from astropy.io import ascii
175 target_table = ascii.read(target_table_string)
176 targets = [FixedTarget(coord=SkyCoord(ra=ra*u.deg, dec=dec*u.deg), name=name)
177 for name, ra, dec in target_table]
178
179 plt.figure(figsize=(6,6))
180 cmap = cm.Set1 # Cycle through this colormap
181
182 for i, target in enumerate(targets):
183 ax = plot_sky(target, subaru, time_grid,
184 style_kwargs=dict(color=cmap(float(i)/len(targets)),
185 label=target.name))
186
187 legend = ax.legend(loc='lower center')
188 legend.get_frame().set_facecolor('w')
189 plt.show()
190
191 We can see that Vega is in the sweet spot in altitude and azimuth for this
192 time range and is always observable. Albireo is not always observable given
193 these criteria because it rises above 80 degrees altitude. Polaris hardly moves
194 and is therefore always observable, and Algol starts out observable but sets
195 below the lower altitude limit, and then the airmass limit. Rigel and Regulus
196 never rise above those limits within the time range.
197
198 .. _constraints-visualize_constraints:
199
200 Visualizing Constraints
201 =======================
202
203 Suppose an observer is planning to observe low-mass stars in Praesepe in the
204 optical and infrared from the W.M. Keck Observatory. The observing constraints
205 require all observations to occur (i) between astronomical twilights; (ii)
206 while the Moon is separated from Praesepe by at least 45 degrees; and (iii)
207 while Praesepe is above the lower elevation limit of Keck I, about 33 degrees.
208 These observing constraints can be specified with the
209 `~astroplan.AtNightConstraint`, `~astroplan.MoonSeparationConstraint`, and
210 `~astroplan.AltitudeConstraint` objects, like this:
211
212 .. code-block::python
213
214 from astroplan import (FixedTarget, Observer, AltitudeConstraint,
215 AtNightConstraint, MoonSeparationConstraint)
216 from astropy.time import Time
217 from astroplan.utils import time_grid_from_range
218 import astropy.units as u
219 import numpy as np
220 import matplotlib.pyplot as plt
221
222 # Specify observer at Keck Observatory:
223 keck = Observer.at_site('Keck')
224
225 # Use Sesame name resolver to get coordinates for Praesepe:
226 target = FixedTarget.from_name("Praesepe")
227
228 # Define observing constraints:
229 constraints = [AtNightConstraint.twilight_astronomical(),
230 MoonSeparationConstraint(min=45 * u.deg),
231 AltitudeConstraint(min=33 * u.deg)]
232
233 We can evaluate the constraints at one hour intervals in a loop, to create an
234 observability grid like so:
235
236 .. code-block::python
237
238 # Define range of times to observe between
239 start_time = Time('2017-01-01 04:00:01')
240 end_time = Time('2017-01-01 11:00:01')
241 time_resolution = 1 * u.hour
242
243 # Create grid of times from ``start_time`` to ``end_time``
244 # with resolution ``time_resolution``
245 time_grid = time_grid_from_range([start_time, end_time],
246 time_resolution=time_resolution)
247
248 observability_grid = np.zeros((len(constraints), len(time_grid)))
249
250 for i, constraint in enumerate(constraints):
251 # Evaluate each constraint
252 observability_grid[i, :] = constraint(keck, target, times=time_grid)
253
254 This kind of grid can be useful for visualizing what's happening under-the-hood
255 when you use `~astroplan.is_observable` or `~astroplan.is_always_observable`.
256 Click the link below for the source code to produce the observability grid shown
257 below. Dark squares represent times when the observing constraint is not
258 satisfied.
259
260 .. plot::
261
262 from __future__ import (absolute_import, division, print_function,
263 unicode_literals)
264
265 from astroplan import (FixedTarget, Observer, AltitudeConstraint,
266 AtNightConstraint, MoonSeparationConstraint)
267 from astropy.time import Time
268 from astroplan.utils import time_grid_from_range
269 import astropy.units as u
270 import numpy as np
271 import matplotlib.pyplot as plt
272
273 # Specify observer at Keck Observatory:
274 keck = Observer.at_site('Keck')
275
276 # Use Sesame name resolver to get coordinates for Praesepe:
277 target = FixedTarget.from_name("Praesepe")
278
279 # Define observing constraints:
280 constraints = [AtNightConstraint.twilight_astronomical(),
281 MoonSeparationConstraint(min=45 * u.deg),
282 AltitudeConstraint(min=33 * u.deg)]
283
284 # Define range of times to observe between
285 start_time = Time('2017-01-01 04:00:01')
286 end_time = Time('2017-01-01 11:00:01')
287 time_resolution = 1 * u.hour
288
289 # Create grid of times from ``start_time`` to ``end_time``
290 # with resolution ``time_resolution``
291 time_grid = time_grid_from_range([start_time, end_time],
292 time_resolution=time_resolution)
293
294 observability_grid = np.zeros((len(constraints), len(time_grid)))
295
296 for i, constraint in enumerate(constraints):
297 # Evaluate each constraint
298 observability_grid[i, :] = constraint(keck, target, times=time_grid)
299
300 # Create plot showing observability of the target:
301
302 extent = [-0.5, -0.5+len(time_grid), -0.5, 2.5]
303
304 fig, ax = plt.subplots()
305 ax.imshow(observability_grid, extent=extent)
306
307 ax.set_yticks(range(0, 3))
308 ax.set_yticklabels([c.__class__.__name__ for c in constraints])
309
310 ax.set_xticks(range(len(time_grid)))
311 ax.set_xticklabels([t.datetime.strftime("%H:%M") for t in time_grid])
312
313 ax.set_xticks(np.arange(extent[0], extent[1]), minor=True)
314 ax.set_yticks(np.arange(extent[2], extent[3]), minor=True)
315
316 ax.grid(which='minor', color='w', linestyle='-', linewidth=2)
317 ax.tick_params(axis='x', which='minor', bottom='off')
318 plt.setp(ax.get_xticklabels(), rotation=30, ha='right')
319
320 ax.tick_params(axis='y', which='minor', left='off')
321 ax.set_xlabel('Time on {0} UTC'.format(time_grid[0].datetime.date()))
322 fig.subplots_adjust(left=0.35, right=0.9, top=0.9, bottom=0.1)
323 plt.show()
324
325
326 .. _constraints-user_defined_constraints:
327
328 User-Defined Constraints
329 ========================
330
331 There are many possible constraints that you could find useful which have
332 not been implemented (yet) in astroplan. This example will walk you through
333 creating your own constraint which will be compatible with the tools in the
334 ``constraints`` module.
335
336 We will begin by defining an observer at Subaru and reading the text file of
337 stellar coordinates defined in the example above::
338
339 from astroplan import Observer, FixedTarget
340 from astropy.time import Time
341 subaru = Observer.at_site("Subaru")
342 time_range = Time(["2015-08-01 06:00", "2015-08-01 12:00"])
343
344 # Read in the table of targets
345 from astropy.io import ascii
346 target_table = ascii.read('targets.txt')
347
348 # Create astroplan.FixedTarget objects for each one in the table
349 from astropy.coordinates import SkyCoord
350 import astropy.units as u
351 targets = [FixedTarget(coord=SkyCoord(ra=ra*u.deg, dec=dec*u.deg), name=name)
352 for name, ra, dec in target_table]
353
354 In the previous section, you may have noticed that constraints are assembled by
355 making a list of calls to the initializers for classes like
356 `~astroplan.AltitudeConstraint` and `~astroplan.AirmassConstraint`. Each of
357 those constraint classes is subclassed from the abstract
358 `~astroplan.Constraint` class, and the custom constraint that we're going to
359 write must be as well.
360
361 In this example, let's design our constraint to ensure that all targets must
362 be within some angular separation from Vega – we'll call it
363 ``VegaSeparationConstraint``. Two methods, ``__init__`` and
364 ``compute_constraint`` must be written for our constraint to work:
365
366 * The ``__init__`` method will accept the minimum and maximum acceptable separations
367 a target could have from Vega.
368
369 * We'll also define a method ``compute_constraints`` which takes three
370 arguments: a `~astropy.time.Time` or array of times to test,
371 an `~astroplan.Observer` object, and some targets (a `~astropy.coordinates.SkyCoord`
372 object representing a single target or a list of targets).
373 ``compute_constraints`` will return an array of booleans that describe whether
374 or not each target meets the constraints. The super class `~astroplan.Constraint` has a
375 ``__call__`` method which will run your custom class's ``compute_constraints`` method
376 when you check if a target is observable using `~astroplan.is_observable`
377 or `~astroplan.is_always_observable`. This ``__call__`` method also checks the
378 arguments, converting single `~astroplan.FixedTarget` or lists of `~astroplan.FixedTarget`
379 objects into an `~astropy.coordinates.SkyCoord` object. The ``__call__`` method ensures the
380 returned array of booleans is the correct shape, so ``compute_constraints`` should not
381 normally be called directly - use the ``__call__`` method instead.
382
383 * We also want to provide the option of having the constraint output
384 a non-boolean score. Where being closer to the minimum separation
385 returns a higher score than being closer to the maximum separation.
386
387 Here's our ``VegaSeparationConstraint`` implementation::
388
389 from astroplan import Constraint, is_observable, min_best_rescale
390 from astropy.coordinates import Angle
391 import astropy.units as u
392
393 class VegaSeparationConstraint(Constraint):
394 """
395 Constraint the separation from Vega
396 """
397 def __init__(self, min=None, max=None, boolean_constraint=True):
398 """
399 min : `~astropy.units.Quantity` or `None` (optional)
400 Minimum acceptable separation between Vega and target. `None`
401 indicates no limit.
402 max : `~astropy.units.Quantity` or `None` (optional)
403 Minimum acceptable separation between Vega and target. `None`
404 indicates no limit.
405 """
406 self.min = min if min is not None else 0*u.deg
407 self.max = max if max is not None else 180*u.deg
408 self.boolean_constraint = boolean_constraint
409
410 def compute_constraint(self, times, observer, targets):
411
412 vega = SkyCoord(ra=279.23473479*u.deg, dec=38.78368896*u.deg)
413
414 # Calculate separation between target and vega
415 # Targets are automatically converted to SkyCoord objects
416 # by __call__ before compute_constraint is called.
417 vega_separation = vega.separation(targets)
418
419 if self.boolean_constraint:
420 mask = ((self.min < vega_separation) & (vega_separation < self.max))
421 return mask
422
423 # if we want to return a non-boolean score
424 else:
425 # rescale the vega_separation values so that they become
426 # scores between zero and one
427 rescale = min_best_rescale(vega_separation, self.min,
428 self.max, less_than_min=0)
429 return rescale
430
431
432 Then as in the earlier example, we can call our constraint::
433
434 >>> constraints = [VegaSeparationConstraint(min=5*u.deg, max=30*u.deg)]
435 >>> observability = is_observable(constraints, subaru, targets,
436 ... time_range=time_range)
437 >>> print(observability)
438 [False False True False False False]
439
440 The resulting list of booleans indicates that the only target separated by
441 5 and 30 degrees from Vega is Albireo. Following this pattern, you can design
442 arbitrarily complex criteria for constraints.
443
444 By default, calling a constraint will try to broadcast the time and target arrays
445 against each other, and raise a `ValueError` if this is not possible. To see the
446 (target x time) array for the constraint, there is an optional ``grid_times_targets``
447 argument. Here we find the (target x time) array for the non-boolean score::
448
449 >>> constraint = VegaSeparationConstraint(min=5*u.deg, max=30*u.deg,
450 ... boolean_constraint=False)
451 >>> print(constraint(subaru, targets, time_range=time_range,
452 ... grid_times_targets=True))
453 [[ 0. 0. 0. 0. 0. 0. 0.
454 0. 0. 0. 0. 0. ]
455 [ 0. 0. 0. 0. 0. 0. 0.
456 0. 0. 0. 0. 0. ]
457 [ 0.57748686 0.57748686 0.57748686 0.57748686 0.57748686 0.57748686
458 0.57748686 0.57748686 0.57748686 0.57748686 0.57748686 0.57748686]
459 [ 0. 0. 0. 0. 0. 0. 0.
460 0. 0. 0. 0. 0. ]
461 [ 0. 0. 0. 0. 0. 0. 0.
462 0. 0. 0. 0. 0. ]
463 [ 0. 0. 0. 0. 0. 0. 0.
464 0. 0. 0. 0. 0. ]]
465
466 The score of .5775 for Albireo indicates that it is slightly closer to
467 the 5 degree minimum than to the 30 degree maximum.