TAPIR1 - a web interface for planning astronomical observations

Baby tapir by Missud, on Flickr

To go straight to examples, see the full interface, airmass plots only, or annotated finding charts only. Or go to Github for the code.

Planning follow-up observations of periodic targets (e.g. eclipsing binaries, transiting planets) isn't difficult, but it can be tedious, especially when dealing with many targets, observing sites, and/or observational constraints. To help address this problem in our follow-up of planet transit candidates for KELT-North and KELT-South, I wrote a web interface that allows an observer to easily determine which events (e.g. transits) will be visible from a given location on a given date. In the hope that it might be useful to others, I'm releasing the code for other people to apply to their projects or collaborations.

The easiest way to see how this works is to look at an example. Here is a page that uses this code to report upcoming transits of the known transiting exoplanets.²

The big picture is that there is a master target list, which includes at minimum target names, coordinates, and (for periodic targets) ephemerides (period and time of zero phase), but possibly also comments on each target (e.g. notes on past observations) and relative priorities. Any time an observer wants to plan observations, he/she accesses a web script which reads the target list, determines which events are observable (or partially observable) from the specified location on the specified date(s), and returns a web page with target information, including the time and elevation of the start and end of the event, links to finding charts and airmass plots, and links to external sources of information like 2MASS and Simbad.

In the case of KELT, we use a Google spreadsheet to maintain the target list, which has the advantage that it can easily be updated by multiple team members in different locations by logging into a shared Google account. A script on the machine running the webserver accesses the spreadsheet hourly to update a local copy of the target list (in a flat text file), which is then read by the transit-planning script whenever a user invokes the web interface. The target list needn't be a spreadsheet - it could simply be a local text file in a specified format. Each time the local target list is updated, a script reads through it and creates finding charts for any new targets that have been added. Both the script to mirror a Google spreadsheet to a local text file, and the script to read the file and create annotated finding charts are included in the source code package. Alternatively, if you can't (or don't want to) store the target file or copies of the finding charts locally (i.e. if you can get someone to install the main code on a server, but not to run a cron job to update other files), it wouldn't be hard to change the code so that it downloads targets from a Google spreadsheet every time it runs, rather than reading a local file. This would decrease the responsiveness a little, but could be useful. Similarly, the finding charts could be generated on the fly as needed - this would just involve editing the HTML template file to alter the format of the links to the finding charts, so that rather than referencing static image files, they call the script to generate each chart and send it to the browser.

In addition, there is a script to create plots of airmass vs. time for each transit event. These are generated on the fly when requested by the user. To see examples, you can find links for the airmass plots and the annotated finding charts in the output of the transit-finding page linked above, or there is a standalone page for generating airmass plots, and a page for generating annotated finding charts.

The code was originally developed for calculating the visibility of periodic events, but it is possible to include non-periodic targets in the target list, too (e.g. out-of-transit observations for periodic targets, or just objects you want to observe any time they are up). To specify a target as non-periodic, there is a field in the input target list the designates each target for periodic observations, "any time" observations, or both (i.e. show visibility of the periodic events/eclipses/transits, but also include the target in the "any time" list). See the example input target spreadsheet in the source code distribution for examples of each kind of target. The targets in the "any time" category, if any, are displayed in a separate output table below the list of events from the periodic list. Rather than listing specific times of start/end of each event, these targets are ordered according to when they reach their highest elevation during the night.

The format of the output (e.g. what fields are displayed, how they are formatted, what other links are provided for each target) can be customized without editing the source code by editing an HTML template file, so to a large extent the output formatting can be separated from the coding. (For more on HTML::Template, see its code page on CPAN and this tutorial.)

All of the code is written in Perl, and has been tested primarily on Linux, and partially on Mac OSX. Both of these platforms come with Perl and the Apache webserver installed by default. To run the code, you'll need to install a number of other Perl packages, as detailed in the README.

For more details, see the README file for the code distribution, or grab the source code from github. (You can use the "Zip" button on that page to download a zipped file of the source.)

1. "TAPIR" could stand for TrAnsit PlannIng and Reconnaissance, but in truth I just thought the software needed a name, and I like tapirs. The stripes on the baby tapirs look sort of like light curves...

2. In this specific case, I realize that the functionality overlaps with that provided by the Exoplanet Transit Database, albeit with more flexibility for filtering the results; however, this is just an example, and the overall goal here is to allow you to provide a similar interface for your own target list.

Last modified: Thu Dec 13 11:24:52 EST 2012