The Astronomical Journal, 155:128 (9pp), 2018 March https://doi.org/10.

3847/1538-3881/aaa47e
© 2018. The American Astronomical Society.

astroplan: An Open Source Observation Planning Package in Python

Brett M. Morris1 , Erik Tollerud2 , Brigitta Sipőcz3, Christoph Deil4, Stephanie T. Douglas5 , Jazmin Berlanga Medina6,
Karl Vyhmeister7, Toby R. Smith1, Stuart Littlefair8 , Adrian M. Price-Whelan9 , Wilfred T. Gee10, and Eric Jeschke11
1
Astronomy Department, University of Washington, Seattle, WA 98195, USA; [email protected]
2
Space Telescope Science Institute, 3700 San Martin Drive, Baltimore, MD 21211, USA
3
Visitor, Institute of Astronomy, University of Cambridge, Madingley Road, CB30HA, UK
4
Max Planck Institute for Nuclear Physics, Saupfercheckweg 1, D-69117 Heidelberg, Germany
5
Harvard-Smithsonian Center for Astrophysics, 60 Garden Street, Cambridge, MA 02138, USA
6
Imagination Station, 600 North 4th Street, Lafayette, IN, USA
7
California Institute of Technology, 1200 East California Boulevard, Pasadena, CA 91125, USA
8
University of Sheffield, Western Bank, Sheffield S10 2TN, UK
9
Department of Astrophysical Sciences, Princeton University, 4 Ivy Lane, Princeton, NJ 08544, USA
10
Department of Physics and Astronomy, Macquarie University, NSW 2109, Australia
11
Subaru Telescope, National Astronomical Observatory of Japan, 650 North A’ohoku Place, Hilo, HI 96720, USA
Received 2017 October 18; revised 2017 December 23; accepted 2017 December 27; published 2018 February 23

Abstract
We present astroplan—an open source, open development, Astropy affiliated package for ground-based observation
planning and scheduling in Python. astroplan is designed to provide efficient access to common observational
quantities such as celestial rise, set, and meridian transit times and simple transformations from sky coordinates to
altitude-azimuth coordinates without requiring a detailed understanding of astropy’s implementation of coordinate
systems. astroplan provides convenience functions to generate common observational plots such as airmass and
parallactic angle as a function of time, along with basic sky (finder) charts. Users can determine whether or not a target is
observable given a variety of observing constraints, such as airmass limits, time ranges, Moon illumination/separation
ranges, and more. A selection of observation schedulers are included that divide observing time among a list of targets,
given observing constraints on those targets. Contributions to the source code from the community are welcome.
Key words: methods: numerical – methods: observational

1. Introduction astropy under-the-hood to handle the sky and time

coordinate transformations.
The Astropy Project is a community effort to develop a
The most similar existing Python software that can be used to
common core package for astronomy in Python and to foster an
plan observations is pyephem (Rhodes 2011). astroplan is
ecosystem of interoperable astronomy packages. The astropy
different from pyephem in a few fundamental ways. astro-
core package contains all of the machinery necessary for
plan provides support for computing the positions of the Sun,
computing whether or not a given object is observable from a
Moon, stars, and major planets. It uses astropy’s modern and
location on the Earth at specified times. It defines an object-
more accurate IAU2000/2006 methods and NASA’s DE430
oriented framework for specifying times and coordinates on the planetary ephemeris. astroplan is built around the astropy
sky and Earth. In this paper, we assume that the reader has some objects that specify times and coordinates. astroplan users can
familiarity with the tools available in astropy, see Astropy use the extensively documented and constantly improving
Collaboration et al. (2013) or the online documentation.12 astropy framework for specifying times and coordinates.
There are several practical algorithms useful for observation pyephem uses package-specific implementations of times and
planning that are not included in astropy. Some questions coordinates that are not cross-compatible with packages in the
that users may seek to answer using astropy would require Astropy Project ecosystem. pyephem supports the Sun, Moon,
substantial effort, such as: “is this star currently above 30° stars, major planets, asteroids and comets, and uses the older
altitude from the Apache Point Observatory?” or “what time is IAU1976/1980 precession/nutation methods, and VSOP87
astronomical twilight this evening on MaunaKea?” planetary ephemerides.
astroplan is an Astropy affiliated package for ground- Here, we briefly outline some key features of astroplan
based observation planning and scheduling, which provides version 0.4 and the design decisions that went into making
functionality for answering these questions. It is a pure-Python them. In Section 2, we outline the astroplan API, and in
package that provides an efficient application programming Section 3, we direct the reader to the online documentation and
interface (API) for quick access to common observational resources for teaching and learning astroplan.
calculations, while using the full accuracy and precision of

12
http://docs.astropy.org 2. API
2.1. Basic Operations
Original content from this work may be used under the terms
of the Creative Commons Attribution 3.0 licence. Any further We begin by defining the Observer object, which specifies
distribution of this work must maintain attribution to the author(s) and the title the location of an observer on the Earth. Most of the major
of the work, journal citation and DOI. observatories included in IRAF (National Optical Astronomy

1
The Astronomical Journal, 155:128 (9pp), 2018 March Morris et al.

An observer can be located anywhere on the Earth with use of

astropy’s EarthLocation object.

Example 2. Define a custom observer

In order to account for atmospheric refraction in different

environments, several atmospheric parameters can be described
on the Observer object, including the atmospheric pressure,
temperature, and relative humidity.
Targets with fixed celestial coordinates are described by
FixedTarget objects, which contain their coordinate
and name:

Example 3. Define a fixed celestial target

Figure 1. An airmass plot and a sky chart for observing Sirius and Rigel from
Apache Point Observatory, made with the astroplan.plots methods The from_name class method uses tools from astropy.
plot_airmass and plot_sky. The underlying altitude/azimuth calcul- coordinates to query Simbad, NED, and VizieR for target
ation powered by astropy.coordinates includes atmospheric refraction. coordinates by name through the Sesame Name Resolver
(Schaaff 2004). Non-fixed targets apart from the Sun and Moon
are not implemented in astroplan at the time of writing, and
community contributions for supporting minor bodies are
Observatories 1999) are accessible by name in astroplan
welcome.
via the at_site class method:
Rise and set times are the cornerstone computations of
observation planning. astroplan computes the rise and set
times of an object by transforming the sky coordinates of the
Example 1. Define a common observer object (e.g., ICRS, galactic, etc.) into a grid of altitude-azimuth
coordinates for that target as seen by an observer at a specific
location on the Earth, at 10-minute intervals over a 24-hr
period. The rise or set time is then computed by linear
interpolation between the two coordinates nearest to zero. The
meridian/anti-meridian transit time is computed similarly; it
takes a numerical derivative of the altitudes before searching
for the appropriate zero crossing. The user can also define a rise
or set horizon other than 0° altitude, which is useful for
observatories with non-zero altitude limits.
We chose to compute rise and set times with a grid-search to
maximize accuracy, rather than speed. In particular, we sought

2
The Astronomical Journal, 155:128 (9pp), 2018 March Morris et al.

to preserve the astropy altitude-azimuth coordinate trans- The constraints framework is modular and written to be
formation, which accounts for atmospheric refraction. extensible. Users can implement their own constraints for a
Convenience methods are included to compute the altitude- particular observatory or science case by following a tutorial in
azimuth coordinates of a target at a given time, and the times of the online documentation14 to produce constraint objects that
rise, set, meridian, and anti-meridian transit. are compatible with the astroplan scheduling framework.

Example 4. Find target altitude/azimuth and rise time 2.3. Transiting Exoplanets and Eclipsing Binaries (EBs)
The astroplan.periodic module contains a frame-
work for defining systems with periodic events, such as
exoplanets and binaries. There are specialized classes for
eclipsing systems, such as EBs and transiting exoplanets. The
module makes use of the generic terms “primary eclipse” and
“secondary eclipse,” where the primary eclipse is a “transit” in
the case of exoplanets. There are convenience functions for
computing the next primary or secondary eclipses of an
exoplanet or EB, or as well as computing ingress and egress
times of the next primary or secondary eclipse.

Times can be defined in a variety of scales using astropy

Time objects, including UTC, TAI, TCB, TCG, TDB, Example 5. Find upcoming exoplanet transit times
TT, UT1.
The sky coordinates of the major solar system bodies are
computed using the jplephem package, which provides an
API for querying JPL’s Satellite Planet Kernel files. The
methods for querying the positions of solar system bodies were
originally developed for astroplan, and have since been
moved into the astropy.coordinates package.
Common plots are accessible through the astroplan.
plots module—see Figure 1 for a few examples. There are
many more example plots and the source code that generates
them, which are available in the online documentation.13

2.2. Observing Constraints

Planning astronomical observations often requires an
observer to determine whether or not a celestial object is
observable given a list of observing constraints. astroplan
contains a generic framework for defining observing con-
straints and computing the “observability” of a list of targets
given those constraints.
For example, suppose an observer is planning to observe There are also complementary methods in the constraints
low-mass stars in Praesepe in the optical and infrared from the module for use with the periodic system framework. Users
W.M.Keck Observatory. The constraints imposed by the can determine which eclipse events are observable from an
telescope and science case require all observations to occur: observatory with a list of constraints. We include a brief tutorial
(i) between astronomical twilights; (ii) while the Moon is for using the periodic module with queries from online
separated from Praesepe by at least 45°; and (iii) while exoplanet parameter databases in Appendix B.
Praesepe is above the lower elevation limit of Keck I, about
33°. These observing constraints can be specified with the
AtNightConstraint, MoonSeparationConstraint, 2.4. Scheduling Observations
and AltitudeConstraint objects. We demonstrate this The scheduling framework enables users to define observing
use case with astroplan in a long code example in blocks, which denote an observation of a target or group of
Appendix A. targets for an amount of time in a particular instrument
Other built-in constraints allow users to specify acceptable configuration. Each observing block can be assigned a numerical
ranges of: Moon illuminations, airmass, Sun separations (e.g., for priority, which by convention spans the range [0, 1] where zero
non-optical observations), and local times. The observing is low priority. Priorities can be assigned by an observer based
constraint classes take as inputs: targets, times, and an observer; on which potential observations are most important to them to
and the constraints return Boolean matrices indicating whether or get scheduled. A set of observing blocks gets assigned a rank,
not those targets are observable at each time.
14
13
https://astroplan.readthedocs.io/en/stable/tutorials/constraints.html#user-
https://astroplan.readthedocs.io/en/stable/tutorials/plots.html defined-constraints

3
The Astronomical Journal, 155:128 (9pp), 2018 March Morris et al.

which for example, might be the rank a proposal receives from a on contributing to the source code of either package are
telescope time allocation committee (TAC). available in the astropy documentation.16
Each observing block has a list of associated constraints. We
compute a score for each constraint on an observing block,
which can be a Boolean or float in the range [0, 1] where zero is 3. Documentation
unfavorable. For example, the score computed from an airmass
constraint will be highest when the airmass is low, while the 3.1. Online Documentation
score computed from an altitude constraint will be highest Detailed, tested, living documentation for astroplan is
when the altitude is high. Other constraints, like the available online via Read the Docs.17 This paper is intended as
AtNightConstraint, yield Boolean scores. a brief introduction to astroplan’s core functionality and
These scored observing blocks can be assigned to time slots the algorithms used throughout the package, so we refer the
by a scheduler, which chooses the order for which observing reader to the online documentation for the complete API
blocks get scheduled first, and the times to assign them. Each description and complete tutorials for each module with
scheduler creates an observing schedule based on one of examples.
several strategies for filling time slots with observing blocks.
As of astroplan version 0.4, there are two schedulers
implemented: the sequential and priority schedulers. 3.2. astroplan in the Classroom
The sequential scheduler begins by selecting the best-scored
observing block at the beginning of the observing time. It then astroplan is incorporated into the curriculum for under-
continues to choose the next best-scored block for the next graduate majors in astronomy at the University of Washington,
observation, until all available observing time is allocated, or in the “Introduction to Programming for Astronomical
all observing blocks have been allocated. Applications” course. The lesson plan on observing with
The priority scheduler takes a prioritized list of observing Python is built around the task of planning astronomical
blocks. The priority for each observing block could be assigned observations. Along the way, it guides students through using
by an observatory TAC, for example, or by an individual the time, coordinate, and quantity objects of astropy,
observer who needs to schedule their observations given their building up to their combined use in observation planning
scientific priorities. The scheduler will first allocate the highest with astroplan. Jupyter notebooks guiding students through
priority observing block to the best-scored time slot for that these lessons are freely available online.18
observing block, and then schedule the next priority block at its
best time, etc.
The two schedulers presently implemented are most useful
for planning an individual observer’s observations; a complete 4. Summary
example is available in Appendix C. We intend to continue to astroplan is a pure-Python, open source, Astropy
develop the scheduling module to support queue scheduling for affiliated package for observation planning and scheduling. It
observatories with many observing programs. A wide range of provides methods for computing common observational
strategies exist for planning observations, however, so the code quantities such as target rise, set, and transit times, and it
for the schedulers is adaptable for users to adopt to other specifies a framework for testing the “observability” of targets
strategies either via subclassing or creating new scheduler given observing constraints.
classes. The package welcomes contributions of this sort from
the community. B.M.M., J.B.M. and K.V. gratefully acknowledge support
from the Google Summer of Code program in 2015 and 2016.
2.5. Testing and Development B.M.M. acknowledges financial support from the Python
Software Foundation and from the University of Washington
astroplan has an extensive testing suite. In addition to eScience Institute, with funding from the Gordon and
simple unit tests, which check that sensible inputs yield Betty Moore Foundation and the Alfred P. Sloan Foundation.
sensible outputs, there are also many tests that compare the We thank Eric Agol and Suzanne Hawley for supporting
accuracy of astroplan outputs. The tests are executed B.M.M. to devote some PhD thesis time toward developing and
remotely whenever changes are made to the source code or maintaining astroplan. B.M.M. graciously acknowledges
documentation within the astroplan repository. The support from Jake VanderPlas, as well.
astroplan outputs are commonly compared against outputs This research has made use of NASA’s Astrophysics Data
from the independent python ephemeris package pyephem System. This research has made use of the SIMBAD database,
(Rhodes 2011). The difference in rise and set times with operated at CDS, Strasbourg, France (Wenger et al. 2000).
astroplan and pyephem is always <8 minutes (with Software:astroplan (Morris et al. 2017), ipython
atmospheric refraction), and the differences are probably (Perez & Granger 2007), numpy (Van Der Walt et al. 2011),
attributable to intrinsically different interpretations of these scipy (Jones et al. 2001), matplotlib (Hunter 2007),
times. astropy (Astropy Collaboration et al. 2013), pyephem
Contributions to the package from the community are (Rhodes 2011), jplephem.19
welcome. The source code is hosted on GitHub,15 where users
can contribute new features. astroplan follows the open 16
http://docs.astropy.org/en/stable/development/workflow/development_
development model refined by astropy, and many tutorials workflow.html
17
http://astroplan.readthedocs.io/
15 18
GitHub: https://github.com/astropy/astroplan, static Zenodo archive: https://github.com/UWashington-Astro300/astroplan-in-the-classroom
19
https://doi.org/10.5281/zenodo.1035883. https://github.com/brandon-rhodes/python-jplephem/releases/tag/v2.6

4
The Astronomical Journal, 155:128 (9pp), 2018 March Morris et al.

Appendix

We outline here some in-depth code examples that demonstrate a few intended use cases for astroplan.
We again encourage the reader to visit the online documentation described in Section 3 for many example inputs and outputs.

Appendix A
Observing Constraints
In Section 2.2, we outlined a list of example observing constraints, which we might like to evaluate at various times with
astroplan. We will observe Praesepe from Keck Observatory, and we are setting the following constraints: (i) observe between
astronomical twilights; (ii) observe while the Moon is separated from Praesepe by at least 45°; and (iii) observe while Praesepe is
above the lower elevation limit of Keck I, about 33°. These observing constraints can be specified with the AtNightConstraint,
MoonSeparationConstraint, and AltitudeConstraint objects. Other built-in constraints include: Moon illumination,
airmass limits, Sun separation limits (e.g., for non-optical observations), and local time constraints. The observing constraint classes
take the following parameters as input: targets, times, and an observer. The constraints return Boolean matrices indicating whether or
not those targets are observable at each time.
The following code will compute whether or not Praesepe is observable given the constraints listed above. The array
observablility will contain “True” for times when Praesepe is observable given the specified constraints, and “False”
otherwise. We visualize the observability grid in Figure 2.
A warning may be printed if astropy or astroplan need to update the International Earth Rotation and Reference Systems
Service (IERS) tables before computing a target’s altitude and azimuth. The altitude and azimuth of a target depends on the
orientation of the Earth, which varies on short timescales due to shifts in the Earth’s moment of inertia. In order to account for these
unpredictable variations in the Earth’s position with time, astropy (and therefore astroplan) use constantly updated tables from the
IERS, which specify the Earth’s orientation with observations of quasars.

5
The Astronomical Journal, 155:128 (9pp), 2018 March Morris et al.

Figure 2. Diagram summarizing the “observability grid” of Praesepe given each observing constraint, at each hour within the time range. Dark squares represent times
when the observing constraint is not satisfied.

Appendix B
Eclipsing Binary and Transiting Exoplanet Ephemerides
Suppose you want to observe a newly discovered eclipsing binary or a well-known transiting exoplanet. You can compute the time
of the next primary eclipse or transit event with the EclipsingSystem object.

With the latest version of astroquery (Ginsburg et al. 2017), you can query the NASA Exoplanet Science Institute Exoplanet
Archive (Akeson et al. 2013) or the Exoplanet Orbit Database (Wright et al. 2011; Han et al. 2014) for exoplanet system parameters:

6
The Astronomical Journal, 155:128 (9pp), 2018 March Morris et al.

Appendix C
Scheduling Observations
In this example, suppose we want to create a schedule for observations at Apache Point Observatory in the first half of the night of 2016
July 7 UTC. We will schedule 16 exposures of Deneb and M13, each in three color filters: B, G, and R. We must observe these targets
when they meet the following constraints: (1) the airmass of the target is <3; (2) the time is between civil twilights; (3) the time is between
02:00–08:00 UTC, which corresponds to the first half of the night at Apache Point.
astroplan provides control over the many parameters that affect observation scheduling. In the example below, we take into
account the slew rate of the telescope, the time it takes to change filters, and a user-input priority for each observing block, see Figure 3.

7
The Astronomical Journal, 155:128 (9pp), 2018 March Morris et al.

Figure 3. Airmass plot showing the scheduled observing blocks. As we constrained the observations to occur before 8:00 UTC, but Deneb does not reach its highest
altitude until after 8:00 UTC, the scheduler assigned the Deneb observing blocks as late as possible before the 8:00 UTC, thus minimizing the airmass of Deneb during
the observations. As M13 is observable at its minimum airmass, the scheduler centered the three observing blocks on the times when M13 is at minimum airmass. The
black lines between observing blocks represent transitions, which account for instrument reconfiguration dead time—in this example, filter changes and telescope
slews add some dead time.

(Continued)

ORCID iDs References

Brett M. Morris https://orcid.org/0000-0003-2528-3409 Akeson, R. L., Chen, X., Ciardi, D., et al. 2013, PASP, 125, 989
Erik Tollerud https://orcid.org/0000-0002-9599-310X Astropy Collaboration, Robitaille, T. P., Tollerud, E. J., et al. 2013, A&A, 558, A33
Stephanie T. Douglas https://orcid.org/0000-0001- Ginsburg, A., Sipocz, B., Parikh, M., et al. 2017, astropy/astroquery: v0.3.6 with
fixed license, Zenodo, doi:10.5281/zenodo.826911
7371-2832
Han, E., Wang, S. X., Wright, J. T., et al. 2014, PASP, 126, 827
Stuart Littlefair https://orcid.org/0000-0001-7221-855X Hunter, J. D. 2007, CSE, 9, 90
Adrian M. Price-Whelan https://orcid.org/0000-0003- Jones, E., Oliphant, T., Peterson, P., et al. 2001, SciPy: Open Source Scientific
0872-7098 Tools for Python, http://www.scipy.org/

8
The Astronomical Journal, 155:128 (9pp), 2018 March Morris et al.

Morris, B. M., Vyhmeister, K., Sipocz, B., et al. 2017, astropy/astroplan: astroplan Schaaff, A. 2004, in ASP Conf. Ser. 314, Astronomical Data Analysis Software
v0.4, Zenodo, doi:10.5281/zenodo.1035883 and Systems (ADASS) XIII, ed. F. Ochsenbein, M. G. Allen, & D. Egret
National Optical Astronomy Observatories, 1999, IRAF: Image Reduction and (San Francisco, CA: ASP), 327
Analysis Facility, Astrophysics Source Code Library, ascl:9911.002 Van Der Walt, S., Colbert, S. C., & Varoquaux, G. 2011, arXiv:1102.
Perez, F., & Granger, B. E. 2007, CSE, 9, 21 1523
Rhodes, B. C. 2011, PyEphem: Astronomical Ephemeris for Python, Astrophysics Wenger, M., Ochsenbein, F., Egret, D., et al. 2000, A&AS, 143, 9
Source Code Library, ascl:1112.014 Wright, J. T., Fakhouri, O., Marcy, G. W., et al. 2011, PASP, 123, 412