Debian Codegraph @

docs/tutorials/periodic.rst

raw
1 .. include:: ../references.txt
2
3 .. doctest-skip-all
4
5 .. _periodic_tutorial:
6
7 ******************************************************
8 Observing Transiting Exoplanets and Eclipsing Binaries
9 ******************************************************
10
11 .. note::
12 The ``periodic`` module is new and under development. The API may change in
13 upcoming versions of astroplan, and pull requests are welcome!
14
15 .. warning::
16
17 There are currently two major caveats in the implementation of
18 `~astroplan.EclipsingSystem`. The secondary eclipse time approximation is
19 only accurate when the orbital eccentricity is small, and the eclipse
20 times are computed without any barycentric corrections. The current
21 implementation should only be used for approximate mid-eclipse times for
22 low eccentricity orbits, with event durations longer than the
23 barycentric correction error (<=16 minutes).
24
25 Contents
26 ========
27
28 * :ref:`periodic-transit_times`
29 * :ref:`periodic-transit_times_via_astroquery`
30 * :ref:`periodic-observable_transits`
31 * :ref:`periodic-phase_constraint`
32
33 .. _periodic-transit_times:
34
35 Transit/Primary and secondary eclipse times
36 ===========================================
37
38 We can define the properties of an eclipsing system, such as an eclipsing binary
39 or transiting exoplanet, using the `~astroplan.EclipsingSystem` object. Let's
40 make an instance for the transiting exoplanet HD 209458 b, which has a period
41 of 3.52474859 days, mid-transit time of JD=2452826.628514, and transit duration
42 of 0.1277:
43
44 .. code-block:: python
45
46 >>> from astropy.time import Time
47 >>> import astropy.units as u
48 >>> from astroplan import EclipsingSystem
49
50 >>> primary_eclipse_time = Time(2452826.628514, format='jd')
51 >>> orbital_period = 3.52474859 * u.day
52 >>> eclipse_duration = 0.1277 * u.day
53
54 >>> hd209458 = EclipsingSystem(primary_eclipse_time=primary_eclipse_time,
55 ... orbital_period=orbital_period, duration=eclipse_duration,
56 ... name='HD 209458 b')
57
58 Let's say we're observing on 2016 January 1, 00:00 UTC. We can compute the next
59 transit and secondary eclipse using the
60 `~astroplan.EclipsingSystem.next_primary_eclipse_time` and
61 `~astroplan.EclipsingSystem.next_secondary_eclipse_time` methods, respectively:
62
63 .. code-block:: python
64
65 >>> observing_time = Time('2016-01-01 00:00')
66 >>> hd209458.next_primary_eclipse_time(observing_time)
67 <Time object: scale='utc' format='iso' value=['2016-01-03 16:16:09.848']>
68
69 >>> hd209458.next_secondary_eclipse_time(observing_time)
70 <Time object: scale='utc' format='iso' value=['2016-01-01 21:58:20.708']>
71
72 You can compute the next ten mid-transit times with the ``n_eclipses`` keyword:
73
74 .. code-block:: python
75
76 >>> hd209458.next_primary_eclipse_time(observing_time, n_eclipses=5)
77 <Time object: scale='utc' format='iso' value=['2016-01-03 16:16:09.848' '2016-01-07 04:51:48.126'
78 '2016-01-10 17:27:26.404' '2016-01-14 06:03:04.682'
79 '2016-01-17 18:38:42.960']>
80
81 It's often useful to know the ingress and egress times of the next transits
82 when planning observations, which you can find with
83 `~astroplan.EclipsingSystem.next_primary_ingress_egress_time`:
84
85 .. code-block:: python
86
87 >>> hd209458.next_primary_ingress_egress_time(observing_time, n_eclipses=3)
88 <Time object: scale='utc' format='jd' value=[[ 2457391.11404175 2457391.24174175]
89 [ 2457394.63879034 2457394.76649034]
90 [ 2457398.16353893 2457398.29123893]]>
91
92 And remember - in the current implementation, all eclipse times are computed
93 without any barycentric corrections, and the secondary eclipse time
94 approximation is only accurate when the orbital eccentricity is small.
95
96 .. _periodic-transit_times_via_astroquery:
97
98 Transit times via astroquery
99 ============================
100
101 The development version of `astroquery`_ allows users to query for properties of
102 known exoplanets with three different services:
103 `~astroquery.ipac.nexsci.nasa_exoplanet_archive`, `~astroquery.exoplanet_orbit_database`,
104 and `~astroquery.open_exoplanet_catalogue`. In the example below, we will query
105 for the properties of the transiting exoplanet TRAPPIST-1 b with astroquery, and
106 calculate the times of the next three transits with
107 `~astroplan.EclipsingSystem`.
108
109 .. code-block:: python
110
111 >>> # NASA Exoplanet Archive for planet properties
112 >>> import astropy.units as u
113 >>> from astropy.time import Time
114 >>> from astroquery.ipac.nexsci.nasa_exoplanet_archive import NasaExoplanetArchive
115 >>> planet_properties = NasaExoplanetArchive.query_object('TRAPPIST-1 b', select='*', table='pscomppars')
116
117
118 >>> # get relevant planet properties
119 >>> epoch = Time(planet_properties['pl_tranmid'], format='jd')
120 >>> period = planet_properties['pl_orbper']
121 >>> transit_duration = planet_properties['pl_trandur']
122
123 >>> # Create an EclipsingSystem object for HD 209458
124 >>> from astroplan import EclipsingSystem
125 >>> trappist1b = EclipsingSystem(primary_eclipse_time=epoch, orbital_period=period,
126 ... duration=transit_duration)
127
128 >>> # Calculate next three mid-transit times which occur after ``obs_time``
129 >>> obs_time = Time('2017-01-01 12:00')
130 >>> trappist1b.next_primary_eclipse_time(obs_time, n_eclipses=3)
131 <Time object: scale='utc' format='iso' value=['2017-01-02 15:17:40.205' '2017-01-04 03:33:19.443'
132 '2017-01-05 15:48:58.681']>
133
134 .. _periodic-observable_transits:
135
136 When is the next observable transit?
137 ====================================
138
139 Let's continue with the example from above, and now let's calculate all
140 mid-transit times of HD 209458 b which are observable from Apache Point
141 Observatory, when the target is above 30 degrees altitude, and in the "A" half
142 of the night (roughly between sunset and midnight). First we need to create a
143 `~astroplan.FixedTarget` object for the star, which contains the sky coordinate,
144 and the `~astroplan.EclipsingSystem` object, which defines the transit time,
145 period and duration:
146
147 .. code-block:: python
148
149 >>> from astroplan import FixedTarget, Observer, EclipsingSystem
150 >>> apo = Observer.at_site('APO', timezone='US/Mountain')
151 >>> target = FixedTarget.from_name("HD 209458")
152
153 >>> primary_eclipse_time = Time(2452826.628514, format='jd')
154 >>> orbital_period = 3.52474859 * u.day
155 >>> eclipse_duration = 0.1277 * u.day
156
157 >>> hd209458 = EclipsingSystem(primary_eclipse_time=primary_eclipse_time,
158 ... orbital_period=orbital_period, duration=eclipse_duration,
159 ... name='HD 209458 b')
160
161 Then we compute a list of mid-transit times over the next year:
162
163 .. code-block:: python
164
165 >>> n_transits = 100 # This is the roughly number of transits per year
166 >>> obs_time = Time('2017-01-01 12:00')
167 >>> midtransit_times = hd209458.next_primary_eclipse_time(obs_time, n_eclipses=n_transits)
168
169 Finally, we can check if the target is observable at each transit time, given
170 our constraints on the altitude of the target (`~astroplan.AltitudeConstraint`)
171 and the time of observations (`~astroplan.LocalTimeConstraint` and
172 `~astroplan.AtNightConstraint`) with the function`~astroplan.is_event_observable`:
173
174 .. code-block:: python
175
176 >>> from astroplan import (PrimaryEclipseConstraint, is_event_observable
177 ... AtNightConstraint, AltitudeConstraint, LocalTimeConstraint)
178 >>> import datetime as dt
179 >>> import astropy.units as u
180 >>> min_local_time = dt.time(19, 0) # 19:00 local time at APO (7pm)
181 >>> max_local_time = dt.time(0, 0) # 00:00 local time at APO (midnight)
182 >>> constraints = [AtNightConstraint.twilight_civil(),
183 ... AltitudeConstraint(min=30*u.deg),
184 ... LocalTimeConstraint(min=min_local_time, max=max_local_time)]
185
186 >>> is_event_observable(constraints, apo, target, times=midtransit_times)
187 array([[ True, False, True, ..., True, False, True, False]], dtype=bool)
188
189 In the above example, we only checked that the star is observable at the
190 mid-transit time. If you were planning to do transit photometry of HD 209458 b,
191 you might want to be sure that the entire transit is observable. Let's look
192 for only completely observable transits:
193
194 .. code-block:: python
195
196 >>> ing_egr = hd209458.next_primary_ingress_egress_time(observing_time, n_eclipses=n_transits)
197 >>> is_event_observable(constraints, apo, target, times_ingress_egress=ing_egr)
198 array([[False, False, False, ..., True, False, False, False]], dtype=bool)
199
200 Note that several of the transits that were observable at their mid-transit time
201 are not observable at both the ingress and egress times, and therefore are
202 not observable in the computation above.
203
204 .. _periodic-phase_constraint:
205
206 Orbital Phase Constraint
207 ========================
208
209 It is often useful to plan observations as a function of orbital phase. You can
210 calculate the orbital phase of an eclipsing or non-eclipsing system with the
211 `~astroplan.PeriodicEvent` object, which you specify with an epoch and period.
212 Let's create a `~astroplan.PeriodicEvent` object for an imagined binary star:
213
214 .. code-block:: python
215
216 >>> from astroplan import PeriodicEvent
217 >>> import astropy.units as u
218 >>> from astropy.time import Time
219
220 >>> epoch = Time(2456001, format='jd') # reference time of periodic event
221 >>> period = 3.25 * u.day # period of periodic event
222 >>> duration = 2 * u.hour # duration of event
223
224 >>> binary_system = PeriodicEvent(epoch=epoch, period=period)
225
226 Now let's determine when we can observe the binary given some observing
227 constraints. We want to measure the binary's radial velocity at orbital phases
228 between 0.4 and 0.6, while observing between astronomical twilights, and while
229 the target is above 40 degrees altitude, for an observer in Greenwich, England
230 on the night of January 1, 2017. For this task we can use the
231 `~astroplan.PhaseConstraint` (learn more about the constraints module in
232 :doc:`constraints`):
233
234 .. code-block:: python
235
236 >>> from astropy.coordinates import SkyCoord
237 >>> from astroplan import FixedTarget, Observer, is_observable
238 >>> target = FixedTarget(SkyCoord(ra=42*u.deg, dec=42*u.deg), name='Target')
239 >>> greenwich = Observer.at_site("Greenwich")
240 >>> start_time = Time('2017-01-01 01:00')
241 >>> end_time = Time('2017-01-01 06:00')
242
243 >>> from astroplan import PhaseConstraint, AtNightConstraint, AltitudeConstraint
244 >>> constraints = [PhaseConstraint(binary_system, min=0.4, max=0.6),
245 ... AtNightConstraint.twilight_astronomical(),
246 ... AltitudeConstraint(min=40 * u.deg)]
247 >>> is_observable(constraints, greenwich, target, time_range=[start_time, end_time])
248 array([ True], dtype=bool)