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.
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.
-
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 theDate-Pickerwidget 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.
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 .
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.
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.
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 .
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.
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