PyGCN

Python Package Index status

Anonymous VOEvent client for receiving GCN/TAN notices in XML format

The Gamma-ray Coordinates Network/Transient Astronomy Network (GCN/TAN) is a system for distributing astronomical alerts, largely focused on operations of and detections from high-energy satellite missions.

GCN/TAN disseminates both Notices (prompt, machine-readable alerts) and Circulars (human-readable correspondence) through a handful of delivery methods and formats.

This package implements a simple client that listens for VOEvent XML format notices over the custom TCP/IP VOEvent Transport Protocol. By default, it connects to one of the anonymous GCN/TAN server, so no sign-up or configuration is necessary to begin receiving alerts.

Installation

To install PyGCN, simply run:

$ pip install --user pygcn

Usage

PyGCN provides an example script called pygcn-listen that will simply write all VOEvents that it receives to files in the current directory. To try it out, simply run:

$ pygcn-listen

and then type Control-C to quit.

Writing a custom GCN handler

You can also write your own handler that performs a custom action for every GCN that is received. A handler function takes two arguments: payload, the raw content of the GCN, and root, the root element of the XML document as parsed by lxml.etree. Here is a basic example:

#!/usr/bin/env python
import gcn

# Define your custom handler here.
def handler(payload, root):
    # Get the IVORN, or unique VOEvent ID, and print it.
    print(root.attrib['ivorn'])

    # Print all of the event attributes.
    for param in root.findall('./What/Param'):
        name = param.attrib['name']
        value = param.attrib['value']
        print('{} = {}'.format(name, value))

# Listen for VOEvents until killed with Control-C.
gcn.listen(handler=handler)

Filtering

You can also filter events by notice type using gcn.include_notice_types or gcn.exclude_notice_types. Here is an example:

#!/usr/bin/env python
import gcn

# Define your custom handler here.
@gcn.include_notice_types(
    gcn.notice_types.FERMI_GBM_FLT_POS,  # Fermi GBM localization (flight)
    gcn.notice_types.FERMI_GBM_GND_POS,  # Fermi GBM localization (ground)
    gcn.notice_types.FERMI_GBM_FIN_POS)  # Fermi GBM localization (final)
def handler(payload, root):
    # Look up right ascension, declination, and error radius fields.
    pos2d = root.find('.//{*}Position2D')
    ra = float(pos2d.find('.//{*}C1').text)
    dec = float(pos2d.find('.//{*}C2').text)
    radius = float(pos2d.find('.//{*}Error2Radius').text)

    # Print.
    print('ra = {:g}, dec={:g}, radius={:g}'.format(ra, dec, radius))

# Listen for VOEvents until killed with Control-C.
gcn.listen(handler=handler)

Metadata

Release files for pygcn 1.1.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pygcn 1.1.3
File	Size	Uploaded
pygcn-1.1.3.tar.gz	30.4 kB	Jul 20, 2022	Details

Built distribution (wheel)

Table of built distributions (wheels) for pygcn 1.1.3
File	Interpreter	ABI	Platform	Reset
pygcn-1.1.3-py3-none-any.whl 30.9 kB Jul 20, 2022	Python 3	none	any	Details

Total release size: 61.3 kB

Release files / pygcn-1.1.3.tar.gz

Download URL	pygcn-1.1.3.tar.gz
Size	30.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`cc74d365e9b53bd909ec7c4c0d36badf327c848f1481909669f099526fde66dc`
BLAKE2b-256 checksum How to use checksums	`27e957246fe197bb9478742d601398796224aefe509bc7f00f39c276dfb2be8f`
Upload date	Jul 20, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.1 CPython/3.9.13`

Release files / pygcn-1.1.3-py3-none-any.whl

Download URL	pygcn-1.1.3-py3-none-any.whl
Size	30.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`732f4c45242fd5e631a6d302a6174bf3b3c9be91a9f2adaa25f4ffdd21e6a172`
BLAKE2b-256 checksum How to use checksums	`8ad2f5b49358dd8b86b3476ba5ba8fdb77632a1a88d11ad799d56a2abbaaf82d`
Upload date	Jul 20, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.1 CPython/3.9.13`