Processing GCN Notices via Full-Format E-Mail [public]

This example script demonstrates how to process LIGO/Virgo alerts delivered via 'full-format' GCN/TAN e-mail messages, as an alternative to the VOEvent method described in our tutorial. To deploy, configure your computer's mail transfer agent (for example, using procmail) to filter and pipe messages to this script.

Attached to this Wiki page, there are three example messages that you can pipe in to this script like this:

./parse_gcn.py < 2-GCN_LVC_TEST_INITIAL.eml

Here are the example e-mails:

• 1-GCN_LVC_TEST_PRELIMINARY.eml: a 'preliminary' notice
• 2-GCN_LVC_TEST_INITIAL.eml: an 'initial' notice with a link to the rapid sky localization
• 3-GCN_LVC_TEST_UPDATE.eml: an 'update' notice with a link to the refined sky localization

Note that you will need to obtain a robot password from GraceDb in order to download sky maps. See the main tutorial for further information about how to work with sky maps or determine visibility of an event.

Example script: parse_gcn.py

#!/usr/bin/env python
# parse_gcn.py - Parse and process LIGO/Virgo GCN notices via full-format e-mail
# Leo Singer 
#
# Bare-bones script to process GCN/TAN notices resulting from LIGO/Virgo
# detection candidates. This script will handle GCN 'full-format' e-mails
# (see http://gcn.gsfc.nasa.gov/tech_describe.html#tc18 for description).
#
# Test this script by passing it at test e-mail message on stdin:
#
#     ./parse_gcn.py < 2-GCN_LVC_INITIAL_SKYMAP.eml
#
# To deploy, configure your system's mail transfer agent to filter and pipe
# messages to this script. Details depend on your system; see
# <https://www.freebsd.org/doc/handbook/mail-procmail.html> for procmail.
#
# Note that you need to get a GraceDb robot password to download sky maps
# from GraceDb. Add a line like this to your ~/.netrc file:
#    machine gracedb.ligo.org login albert.einstein@LIGO.ORG password JKJKJKJkjkjkjkj1223
# You can get the password from:
#    https://gracedb.ligo.org/gracedb/options/manage_password
#


#
# Imports
#
import email
import sys
import os

#
# Parse e-mail message from stdin.
#
message = email.message_from_file(sys.stdin)

#
# By a pleasant coincidence, Python can parse the colon-separated
# 'Key: Value' format of GCN notices just like an e-mail header.
#
gcn = email.message_from_string(message.get_payload())

#
# Filter based on notice type:
#
#  * keep initial and update events, both of which come with sky maps,
#  * and keep only compact binary coalescence (CBC) events.
#
if gcn['NOTICE_TYPE'] in ('TEST LVC Initial Skymap', 'TEST LVC Update Skymap') and gcn['GROUP_TYPE'] == '1 = CBC':
    # Assemble, echo, and execute curl command to download sky map.
    command = "curl --netrc -O '{0}'".format(gcn['SKYMAP_BASIC_URL'])
    print(command)
    os.system(command)
else:
    print('Ignoring alert, not for us')