Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mickolaua/aware-repo
"AWARE" is a Python application for receiving and processing the GCN/TAN alerts on high-energy transient events and observation planner.
https://github.com/mickolaua/aware-repo
astronomy-library kafka-consumer ligo-virgo observation optical python real-time telegram-bot
Last synced: 14 days ago
JSON representation
"AWARE" is a Python application for receiving and processing the GCN/TAN alerts on high-energy transient events and observation planner.
- Host: GitHub
- URL: https://github.com/mickolaua/aware-repo
- Owner: mickolaua
- License: gpl-2.0
- Created: 2022-09-02T13:42:25.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2024-05-28T14:38:14.000Z (7 months ago)
- Last Synced: 2024-05-29T06:12:07.975Z (7 months ago)
- Topics: astronomy-library, kafka-consumer, ligo-virgo, observation, optical, python, real-time, telegram-bot
- Language: Python
- Homepage:
- Size: 1.87 MB
- Stars: 1
- Watchers: 2
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# AWARE
**"AWARE"** is acronim for **"Alert Watcher and Astronomical Rapid Exploration"** is a
Python application for receiving and processing the Kafka Messages distributed via the
GCN https://gcn.nasa.gov broker for alerts on high-energy transient events such as
GRBs and gravitational wave events detected by LIGO/Virgo/KAGRA interferometers.
Besides that, **AWARE** provides optimal scheduling for the observations of these
astronomical phenomena with telescopes. The AWARE uses gcn_kafka
https://github.com/nasa-gcn/gcn-kafka-python and confluent_kafka
https://github.com/confluentinc/confluent-kafka-python under the hood, which provide convinient way for working with GCN/TAN Confluent Kafka broker. Once alert message were received by the AWARE, they almost immediately sent to the subscribers of the Telegram channel. After that, the AWARE is making observational plan for the specified list of observatories depending on the event type (more detailed in next paragraphs).
# Installation
Download an .whl file from tags and run pip:
`pip install AWARE-0.1.0-py3-none-any.whl --no-build-isolation`
Or build from source:
```
git clone https://github.com/mickolaua/aware-repo.git
cd aware repo
pip install .
```
# Receiving GCN alerts
The simplest way to receive messages is when a person has an access to the Telegram
channel controlled by the AWARE bot instance. One just needs to subscribe to the
channel via inventation link.
It is possible to deploy your own bot instance. First off, one needs to authorize to
the and get credentials (id and secret) to receive raw messages from
GCN. After that, set-up enviromental variables:
PowerShell:
``$Env:GCN_KAFKA_CLIENT_ID=""``
``$Env:GCN_KAFKA_CLIENT_SECRET=""``
Bourne shell (bash/sh/zsh):
``export GCN_KAFKA_CLIENT_ID=``
``export GCN_KAFKA_CLIENT_SECRET=``
Go ahead and install the aware package like specified in previous paragraph
**Installation**.
Next step is to get credentials for the Telegram bot creation. In the Telegram one has
to contact https://telegram.me/BotFather, choose bot name and get API token. The great tutorial with screenshots on how to do that could be find, for example, here
. Then,
write this API token to the enviromental variable:
PowerShell:
``$Env:AWARE_TG_API_TOKEN=""``
Bourne shell (bash/sh/zsh):
``export AWARE_TG_API_TOKEN=``
Now everything is completed to run the AWARE. Just type this command in any shell:
``python -m aware``
Note. It is desired to create a working folder in which the AWARE will be executed,
since there are a lot of observational plots and plans could be generated during the
its run.
Optionally, one can overwrite the default options like, list of event types to listen,
logging format, and other parameters. The default config file `aware.yaml` is located
in this repository. Access to the config file is provided via enviromental variable:
PowerShell:
``$Env:AWARE_CONFIG_FILE="path/to/config.yaml"``
Bourne Shell (bash, sh, zsh):
``export AWARE_CONFIG_FILE=path/to/config.yaml``
# Interaction with bot
A Telegram user can interact with bot using these commands:
`/run`
Run the communication with alert message consumer thread. This command must be executed
in order that all the channel subscribers could receive alert messages in real-time as
well as any related observational information.
`/stop`
Stop receiving messages.
`/status`
Check if bot is idle or broadcasting messages.
`/telescopes`
Get the list of telescopes for which observation planning is available.
`/topics`
Get the list of GCN event types to be received
`/help`
Display the help on bot commands.
Text commands:
1. Finding chart image:
just type something like: `TRANSIENT_NAME 133.33 35.33` to get DSS finding chart of
the target TRANSIENT_NAME at coordinates RA=133.33 DEC=35.33 (J2000).
Planning the observations
=========================
Depending on the event type (for example, SWIFT_XRT_POSITION or LVC_PRELIMENARY) and
localization uncertainty, observational information is different. For example, events
sent by Fermi, Swift, INTEGRAL, IceCube are localized within approximately circular
region in the sky. In this case, a typical localization area is up to a few degrees
(excluding Fermi GBM). For these events, the AWARE planner creates the airmass plot
for the center of the localization region if it is could be observable by a telescope.
For example, the what will send the bot on an XRT alert:
Fig. 1 -The alert message and visibility plot of the Swift Trigger #1162001 for AZT-33IK at Mondy observatory.
The corresponding JSON-file will include only one target per each telescope:
Fig. 2 - An example of XRT observational plan stored in the JSON-file.
## LVC observations
The message content is different from that for previously mentioned alert types. It
includes probabilities for event to be a binary neutron star merger, neutron star
black hole merger, binary black hole merger, or earthquake. An example of the message
sent by Telegram bot is shown here:
Fig. 3 - An example of the LVC event alert message and skymap plot.
Compared with above type of events, LVC events have up to 1000 deg $^2$ localization areas. To explore such large sky fields, two methods of observation planning are being
developed.
### Target observations
This method is best suited for narrow field-of-view telescopes, for example, 15x15
arcmin squared. Observational targets are GLADE+ galaxies that are contained inside
the 90% probability volume of the localization region. The example JSON-file with
GLADE+ target is shown bellow:
Fig. 4 - An example of JSON-file for LVC event.
Note. Only those targets that observable by the certain telescope in the nearest observational window are in the list.
### Mosaic observations (WiP)
The mosaic (e.g. tile, sky-field) observations is applicable for wide-field telescopes,
with FOV $\gtrsim 40$ arcmin. First off, algorithm re-grids the skymap in the tiles of
size 0.9xFOV (10% is accounted for any artefacts at the image edges). Then, the post probable tile is the chosen as the start point. The algorithm walks through most
probable to least probable tiles strictly N_ITER steps. After algorithm has finished,
the list of tile centers written to the JSON-file.