Tapir: Observation planning software

A longer description, and links to examples of the code in use (including interfaces for plotting transit visibility, making airmass plots, and making finding charts) can be found at https://astro.swarthmore.edu/~jensen/tapir.html .

There are two main parts to the software: the form that accepts the input parameters (observing location, any constraints), and the code that takes this input, calculates the visibility of events, and generates the output. In addition, there are some supporting files, notably a few style sheets (.css files) and an HTML template file (.tmpl) that control the appearance of the output. In addition, there is separate code that generates the airmass plots and finding charts.

Prerequisites:

All of the code is in Perl (except for a little bit of Javascript in the input form), and requires that the following Perl packages be installed in order to run:

• DateTime - this may be installed by default in your Perl distribution, but even so you may need to update to the latest version. Perl has a very flexible mechanism for handling date and time arithmetic, including timezones, so most times are represented as DateTime objects internally in the code.

• DateTime::Set - tools for creating sets of DateTime objects (in our case, sunrises and sunsets over the desired time window).

• DateTime::Format::Epoch - needed for converting DateTime objects to JDs.

• Astro::PAL - the successor to the Starlink SLAlib routines.

• Astro::Coords

• HTML::Template

• HTML::Template::Expr

All of these packages may have prerequisites of their own. If you install them using the cpan application that is available with most Perl distributions, the prerequisites should be handled automatically.

Optional prerequisites:

• SVG::TT::Graph: Required for the code for making the airmass plots.

• Net::Google::Spreadsheets: If you use the script for fetching a Google docs spreadsheet, you'll need this. (Authentication for this has recently gotten very complicated - I'm working on a better solution here.)

• Tie::Handle::CSV: If you use the script for parsing the exoplanets.org CSV file, you'll need this.

• Date-Picker: If you want to have a nice pop-up calendar widget for selecting dates in the interface for specifying the date range to be considered, you can download and install the Date-Picker widget from http://www.frequency-decoder.com/2009/09/09/unobtrusive-date-picker-widget-v5

The actual download link is toward the bottom of the page: http://www.frequency-decoder.com/demo/date-picker-v5/date-picker-v5.zip

There is a call to this in the supplied default input form, assuming it is installed in a subdirectory called src below the directory where the form is installed. To use, just unpack the zip file into that src subdirectory, and make sure everything is readable by users of your webserver: chmod -R o+rx src/

For my own installation, I also edited the file src/date-picker-v5/js/lang/en.js to make Sunday be displayed as the first day of the week: firstDayOfWeek:6 It was set to O (Monday) by default.

To use a different localization, change the call in the header of the input form to load a different language file from that subdirectory.

If you run the code for creating finding charts, you'll need the tools convert and identify from ImageMagick to be installed and in your path.

Setup:

For the input form, there shouldn't be much setup needed - just put it in the same directory as the other files. If you change the name of the code that calculates the transits, you'll need to change it here, too, as the target of the form. If you want to change the appearance of the input form, or add observatories, you can edit this file. Note that it is not just an HTML file, but rather an mixture of Perl code and HTML; though most of the form is hard-coded and is easily edited here, the exact form is generated on the fly by execution of the Perl code. This allows, for example, filling in the user's default selections for observatory location, transit elevation, etc., by reading the stored cookies and using them to set the form values.

For the transit-calculating code, you'll find a section near the top of the file that gives instructions for customizing it for your setup. You need to change a few variables there to point to your target file and to give your contact info for error messages. You also may need to edit a few subroutines at the end of the file to specify where your finding charts (if any) are, and how to format links to web pages giving more information about your targets. (Note: the default output template includes links to finding charts on SkyMap.org, and to target info at Simbad and 2MASS - if that's enough for your purposes, you can set both of these functions to return undef. Most importantly, you'll need to look at the routine that parses a line of input from the datafile into separate fields that gives target information (coords, ephemeris, etc.). You'll need either to make sure that your input file conforms to that expected format, or to change the format there to match your file.

Regarding target format files, I've also supplied two auxiliary scripts that give examples of how to access target info from other locations on the web and convert them to the format expected by this script. One can access a target list that is stored in a Google Docs spreadsheet, using the column headings to identify the fields. The second parses the CSV file supplied by exoplanets.org into this target format. (To see an implementation of the script that uses the latter target list, go to https://astro.swarthmore.edu/transits.cgi .) If you wanted to avoid storing a local target list altogether, and only use an on-line spreadsheet, it wouldn't be too hard to combine the code that fetches and parses the Google spreadsheet with the code in the main routine - you'd just need to replace the file open / file read calls in the main routine with a call to the separate spreadsheet-reading code. (If anyone does this in a way that makes it easy to choose either mode, please send me a patch!)

Though the main focus of the code is periodic events like transits or eclipses, it can also handle non-periodic events. For these "any time" targets, the code just calculates whether or not they are above some minimum elevation at some point during the night. To designate a target as non-periodic, give it a value of "2" in the "photometry requested" field. A value of "1" denotes a periodic target, and a value of "3" is both "1" and "2", i.e. a target for which the transit ephemeris should be used to report transits, but for which overall visibility should be calculated and reported as well, e.g. for out-of-transit monitoring.

The appearance of the output (the table of upcoming transits) is largely governed by a template file, target_table.tmpl, so this is the place to customize the output if you don't like the defaults. See the documentation for HTML::Template for more details, but briefly, this file specifies HTML code with special tags that are replaced by the values of Perl variables at run time. There are loops in the template file that are executed at run time over all visible targets, i.e. the code in the template is for one given row, but it is repeated as many times as necessary, with the values filled in for a particular target. There is an HTML::Template tutorial at https://www.perlmonks.org/?node_id=65642 .

Utility scripts and files included:

get_finding_charts.pl: this standalone script is used to produce the annotated finding charts linked from the output transit list. It can take as input the same format of target file that the main script uses, so you can generate finding charts all in one batch once you've assembled your target list. By default, it also skips over any targets in a file for which a finding chart already exists, so you can run it periodically on your target file (e.g. from a cron job) to have it create new finding charts as new targets are added. Make the file executable (chmod +x get_finding_charts.pl) and run it with the --help switch to see the usage details and options.

finding_charts.cgi and create_finding_chart.cgi: these provide a standalone web interface to the script mentioned in the previous entry, for creating finding charts. See https://astro.swarthmore.edu/finding_charts.cgi for an example. If you want to avoid generating and storing local copies of finding charts for your targets, you could replace the links in the default HTML template to links that call create_finding_chart.cgi with appropriate parameters, to generate them on-the-fly as needed (though this will be slower than having a chart already created and stored).

plot_airmass.cgi and airmass.cgi: The script plot_airmass.cgi produces the airmass plots linked from the web interface for the transit listings, but it can be used in standalone mode as well via the airmass.cgi script, which provides an input form to specify coordinates or an object name.

parse_google_spreadsheet.pl: This script can fetch a target list that is stored in a Google spreadsheet, and convert it to the format expected by the transit-plotting script. This provides a convenient way to have a target list that is editable by widely-dispersed collaborators, but also to have a locally-stored target list on the webserver that is quickly accessible by the scripts. You can run this script periodically from cron to keep the local target file up to date.

example_target_spreadsheet.csv: Example target spreadsheet in CSV (comma-separated value) format. This shows the layout of the target spreadsheet that is expected by default by the previous script. There's no reason you have to keep this format, but it can give you a quick start; if you import this doc into your Google account to create a Google docs (now Google Drive) spreadsheet, you'll have the columns easily set up and ready to go.

parse_exoplanets_csv.pl: Perl script to parse the CSV file of known transiting planets from exoplanets.org into the format expected by the transit-plotting code. URL for the CSV file is http://exoplanets.org/csv/exoplanets.csv

airmass.ico: small icon file displayed with the airmass plots.

Copying:

This code is free software, and it is released under the terms of the GNU General Public License. See the file COPYING.txt for more details.

Citing:

If you find this code useful for your work, please consider citing the Astronomy Source Code Library entry, https://ui.adsabs.harvard.edu/abs/2013ascl.soft06007J .

Acknowledgments:

Many thanks to the authors of various packages that made this work possible, especially Tim Jenness for Astro::Coords, Astro::Telescope, and Astro::PAL, and the various contributors to the DateTime and HTML::Template packages.

Thanks to Jason Wright and his team for the exoplanets.org database, and to STScI for providing access to the Digitized Sky Survey.

Feedback:

If you use this code and find it useful, or if you have any bug fixes or suggestions for improvement, I'd appreciate it if you would let me know. I developed it for my own and my collaborators' use, but it would make me happy to know that others are finding it useful, too. Please send me an e-mail at [email protected].

If you have any questions about getting this set up and working on your system, please let me know, and I'll do my best to help (though my response time may vary depending on the time of year, and will definitely be slower during September- mid-December and mid-January - May when I'm teaching).

Enjoy!

Eric Jensen