A Telescope-Agnostic FRB Virtual Observatory Event (VOEvent) Service¶
FRB VOE is a telescope-agnostic server for publishing, broadcasting, and recording Virtual Observatory Events (VOEvents) for detections of Fast Radio Bursts (FRBs). The code base consists of a backend server that is managed by the maestro package, and a suite of command line interface (CLI) tools that allow a client to interact with the server.
Telescopes and observatories that are actively detecting or following up FRBs in the radio regime can establish a subscription-based FRB VOEvent service using frb-voe. The core functionality of the code base is the following tasks:
- Start and stop a Comet VOEvent broker.
- Publish VOEvents that follow an extension to the FRB VOEvent Standard originally prescribed in Petroff et al. 2017 and broadcast them using the Comet broker.
- Maintain a database of subscribers that can receive the VOEvent broadcast from the Comet broker.
- Submit, search for, and update existing FRB objects on the Transient Name Server (TNS).
Overview¶
There are currently two divergent branches: mcgill and master. The mcgill branch is a legacy code base designed to run on the chimefrb node on the calys network at McGill University. The master branch is the precursor to a forthcoming code package that will be made accessible to the public as a telescope-agnostic VOEvent publication server.
CHIME/FRB VOEvent McGill Server¶
Starting the CHIME/FRB VOEvent McGill Server¶
Login to the calys network, part of the Physics Department network at McGill University.
chimefrb to the chimefrb node on this network.
The FRB VOEvent server is configured as two systemd services, each with their own .service file. These are user specific but can only be modified by the System Administrator in the McGill Physics Department. Start the services one-by-one in the following order:
Confirm healthy start up by viewing the logs with either systemctl or journalctl. Examples:
Stopping the CHIME/FRB VOEvent McGill Server¶
In case you need to stop the server, for instance to prevent broadcasting VOEvents during a storm of false positives from the CHIME/FRB real-time pipeline, follow these instructions. First, login to the node as described in the previous section. Then stop the services one-by-one in the following order:
Confirm healthy shutdown by viewing the logs, as in the previous section.Updating the CHIME/FRB VOEvent Allow-list¶
Susbcriptions are acquired through the webform on the public webpage. They are added to the Google Cloud database automatically, but need to be fetched from there routinely so that the allow-list for the Comet broker is updated. Currently this requires a hard restart of the McGill server.
First, login to the node as described previously. Then activate the frb_voe environment:
python3 since the chimefrb node has been configured with multiple versions of python installed on it. You will be prompted to enter a date to collect subscriptions since. Select a date in the past, generally equal to the day after the last day that this process was performed. When in doubt, use October 1, 2021, since before this date the VOEvent Service was not public.
This will create three .csv files locally that you can look at. You only need to update the Google Group that represents the mailing list for email version of the VOEvents. This process is manual currently but could be automated in the future using Google's API for Groups. Nonetheless, read the contents of cloud_db_mailing_list.csv. Select any emails under Susbcriber Email that have not already been made members of the Google Group. Use the Google Group GUI to add these email addresses as members.
Finally, you need to stop and then start (effectively, restart) both services. Consult the directions in previous sections.
Plotting Published CHIME/FRB VOEvent Statistics¶
Use the IPython notebook in utilities/chimefrb_voevent_service_data_visualization.ipynb to create plots of published CHIME/FRB VOEvents from a select date range.
TNS Service¶
The TNS API has been moved to frb-master, and so the following is the relevant instruction for using the API in order to submit/search/change TNS submissions. It also contains the instruction for registeration on the TNS for the Collaboration TNS contact person, as well as legacy copy of the instructions for the now decrepid frb-voe metholodgy.
Using the TNS-API¶
The TNS (Transient Namin Server) is the official IAU-recognized distributor and maintainer of the naming scheme for FRBs, as previously announced in the FRB 2020 virtual conference. CHIME/FRB submits its discoveries to the TNS. As of February 2026, the API runs on FRB-master and naming submissions occur automatically for any Tsar-confirmed FRB (excluding repeater repeats). Names are submitted with a 1-year proprietary period, which can be modified.
The following commands can be used via the chime_frb_api to search an event for its TNS name and submit and event for naming. Changing proprietary period is also included, but should be handled by the TNS PoC.
After authenticating, the api can be used as follows:
from chime_frb_api.backends.frb_master import FRBMaster
master = FRBMaster()
# 1) Submit an event to TNS
submit_resp = master.tns.submit(event_number=65628049, period=5, sandbox=False)
# 2) Search for the TNS name by event number
search_resp = master.tns.search(event_number=65628049, sandbox=False)
# 3) Change proprietary period for an existing TNS object
change_resp = master.tns.change(
tns_name="FRB20191220F",
end_prop_period_date="2030-01-01",
sandbox=False,
)
event_number is the event ID, period is the proprietary period where the event is not public (in years), and sandbox: When sandbox=True, requests go to the TNS sandbox site. This is a safe testing environment and does not affect real TNS records. sandbox=False interacts with the real TNS database.
when changing proprietary period, an event will become public the day after end_prop_period_date="YYYY-MM-DD. This should be done when publishing an event (ATel, Paper submission, Catalog).
Example console.print output for search :
{
'success': True,
'search_failed': False,
'tns_name': 'FRB20260503D',
'status_code': '200',
'id_message': 'OK',
'tns_url': 'https://www.wis-tns.org/api',
'internal_name_used': 'chimefrb_1161934340',
'internal_name': 'chimefrb_1161934340',
'database_update': {
'status': 'not needed',
'reason': 'Candidate already has the right TNS name'
}
}
Registering on the TNS (for Collaboration VoE/TNS PoC)¶
All programmatic requests to the TNS require authentication. This in turn requires registration on the TNS web portal. To complete the registration process and obtain required authorization, follow these steps:
- Request a User Account here. If you had additional team members who will manage your TNS data, they should also create a User Account.
- Log in here.
- Edit your TNS Group members here.
- Add a TNS bot here. This is required in order to obtain the credentials that are needed for making programmatic requests to the TNS via the API that is embedded in
frb-voe. - Once your TNS bot has been created, it will appear in the table on this page. In the rightmost column you can click edit to view or change its properties. In particular, the Edit Bot page allows one to create a new API key for the bot at any time.
- From the Edit Bot page, one can obtain values for the environment variables that are required to use the TNS functionality of
frb-voe.TNS_API_KEYfrom the API alphanumeric key value.TNS_API_IDfrom the"tns_id"key in theUser-Agentspecification.TNS_API_BOT_NAMEfrom the"name"key in theUser-Agentspecification.
- set the following environment variables using the values that were provided to you or your organization when registering for usage of the TNS. The TNS API keys need to be updated in the frb-master TNS utilities.