{"id":23304288,"url":"https://github.com/mickolaua/aware-repo","last_synced_at":"2025-10-10T19:07:56.787Z","repository":{"id":58465101,"uuid":"531941666","full_name":"mickolaua/aware-repo","owner":"mickolaua","description":"\"AWARE\" is a Python application for receiving and processing the GCN/TAN  alerts on high-energy transient events and observation planner.","archived":false,"fork":false,"pushed_at":"2024-05-28T14:38:14.000Z","size":1964,"stargazers_count":1,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-05-29T06:12:07.975Z","etag":null,"topics":["astronomy-library","kafka-consumer","ligo-virgo","observation","optical","python","real-time","telegram-bot"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mickolaua.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-02T13:42:25.000Z","updated_at":"2024-05-30T14:10:01.178Z","dependencies_parsed_at":"2024-03-13T18:27:29.407Z","dependency_job_id":"3392ee64-9677-455d-b176-d549569a7b08","html_url":"https://github.com/mickolaua/aware-repo","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/mickolaua/aware-repo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mickolaua%2Faware-repo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mickolaua%2Faware-repo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mickolaua%2Faware-repo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mickolaua%2Faware-repo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mickolaua","download_url":"https://codeload.github.com/mickolaua/aware-repo/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mickolaua%2Faware-repo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279005031,"owners_count":26083826,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["astronomy-library","kafka-consumer","ligo-virgo","observation","optical","python","real-time","telegram-bot"],"created_at":"2024-12-20T11:16:30.569Z","updated_at":"2025-10-10T19:07:56.771Z","avatar_url":"https://github.com/mickolaua.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AWARE\n\n**\"AWARE\"** is acronim for **\"Alert Watcher and Astronomical Rapid Exploration\"** is a \nPython application for receiving and processing the Kafka Messages distributed via the \nGCN https://gcn.nasa.gov broker for alerts on high-energy transient events such as \nGRBs and gravitational wave events detected by LIGO/Virgo/KAGRA interferometers. \nBesides that, **AWARE** provides optimal scheduling for the observations of these \nastronomical phenomena with telescopes. The AWARE uses gcn_kafka \nhttps://github.com/nasa-gcn/gcn-kafka-python and confluent_kafka \nhttps://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).\n\n# Installation\n\nDownload an .whl file from tags and run pip:\n\n`pip install AWARE-0.1.0-py3-none-any.whl --no-build-isolation`\n\nOr build from source:\n   ```\n   git clone https://github.com/mickolaua/aware-repo.git\n\n   cd aware repo\n\n   pip install .\n   ```\n\n# Receiving GCN alerts\n\nThe simplest way to receive messages is when a person has an access to the Telegram \nchannel controlled by the AWARE bot instance. One just needs to subscribe to the \nchannel via inventation link.\n\nIt is possible to deploy your own bot instance. First off, one needs to authorize to \nthe \u003cgcn.nasa.gov\u003e and get credentials (id and secret) to receive raw messages from \nGCN. After that, set-up enviromental variables:\n\nPowerShell:\n\n``$Env:GCN_KAFKA_CLIENT_ID=\"\u003cyour actual id\u003e\"``\n\n``$Env:GCN_KAFKA_CLIENT_SECRET=\"\u003cyour actual secret\u003e\"``\n\nBourne shell (bash/sh/zsh):\n\n``export GCN_KAFKA_CLIENT_ID=\u003cyour actual id\u003e``\n\n``export GCN_KAFKA_CLIENT_SECRET=\u003cyour actual secret\u003e``\n\nGo ahead and install the aware package like specified in previous paragraph \n**Installation**.\n\nNext step is to get credentials for the Telegram bot creation. In the Telegram one has \nto 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 \n\u003chttps://sendpulse.com/knowledge-base/chatbot/telegram/create-telegram-chatbot\u003e. Then, \nwrite this API token to the enviromental variable:\n\nPowerShell:\n\n``$Env:AWARE_TG_API_TOKEN=\"\u003cyour actual API token\u003e\"``\n\nBourne shell (bash/sh/zsh):\n\n``export AWARE_TG_API_TOKEN=\u003cyour actual API token\u003e``\n\nNow everything is completed to run the AWARE. Just type this command in any shell:\n\n``python -m aware``\n\nNote. It is desired to create a working folder in which the AWARE will be executed, \nsince there are a lot of observational plots and plans could be generated during the \nits run. \n\nOptionally, one can overwrite the default options like, list of event types to listen, \nlogging format, and other parameters. The default config file `aware.yaml` is located \nin this repository. Access to the config file is provided via enviromental variable:\n\nPowerShell:\n\n``$Env:AWARE_CONFIG_FILE=\"path/to/config.yaml\"``\n\nBourne Shell (bash, sh, zsh):\n\n``export AWARE_CONFIG_FILE=path/to/config.yaml``\n\n\n# Interaction with bot\n\nA Telegram user can interact with bot using these commands:\n\n`/run`\n\nRun the communication with alert message consumer thread. This command must be executed \nin order that all the channel subscribers could receive alert messages in real-time as \nwell as any related observational information.\n\n`/stop`\n\nStop receiving messages.\n\n`/status`\n\nCheck if bot is idle or broadcasting messages.\n\n`/telescopes`\n\nGet the list of telescopes for which observation planning is available.\n\n`/topics`\n\nGet the list of GCN event types to be received\n\n`/help`\n\nDisplay the help on bot commands.\n\nText commands:\n\n1. Finding chart image:\n\njust type something like: `TRANSIENT_NAME 133.33 35.33` to get DSS finding chart of \nthe target TRANSIENT_NAME at coordinates RA=133.33 DEC=35.33 (J2000).\n\n\nPlanning the observations\n=========================\nDepending on the event type (for example, SWIFT_XRT_POSITION or LVC_PRELIMENARY) and \nlocalization uncertainty, observational information is different. For example, events \nsent by Fermi, Swift, INTEGRAL, IceCube are localized within approximately circular \nregion in the sky. In this case, a typical localization area is up to a few degrees \n(excluding Fermi GBM). For these events, the AWARE planner creates the airmass plot \nfor the center of the localization region if it is could be observable by a telescope.\n\nFor example, the what will send the bot on an XRT alert:\n\n\u003cfigure align=\"center\"\u003e\n   \u003cimg src=\"airmass_plot_xrt_example.png\"\n         alt=\"XRT_airmass_plot_example\"\n         width=\"300\" \n         height=\"500\"\n         float=\"center\"\u003e\n   \u003cfigcaption\u003eFig. 1 -The alert message and visibility plot of the Swift Trigger #1162001 for AZT-33IK at Mondy observatory.\u003c/figcaption\u003e\n\u003c/figure\u003e\n\nThe corresponding JSON-file will include only one target per each telescope:\n\n\u003cfigure align=\"center\"\u003e\n   \u003cimg src=\"json_xrt_example.png\"\n         alt=\"XRT_json_example\"\n         width=\"300\" \n         height=\"500\"\n         float=\"center\"\u003e\n   \u003cfigcaption\u003eFig. 2 - An example of XRT observational plan stored in the JSON-file.\u003c/figcaption\u003e\n\u003c/figure\u003e\n\n## LVC observations\nThe message content is different from that for previously mentioned alert types. It \nincludes probabilities for event to be a binary neutron star merger, neutron star \nblack hole merger, binary black hole merger, or earthquake. An example of the message \nsent by Telegram bot is shown here:\n\n\u003cfigure align=\"center\"\u003e\n   \u003cimg src=\"lvc_skymap_example.png\"\n         alt=\"LVC skymap example\"\n         width=\"300\" \n         height=\"500\"\n         float=\"center\"\u003e\n   \u003cfigcaption\u003eFig. 3 - An example of the LVC event alert message and skymap plot.\u003c/figcaption\u003e\n\u003c/figure\u003e\n\nCompared 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 \ndeveloped. \n\n### Target observations\n\nThis method is best suited for narrow field-of-view telescopes, for example, 15x15 \narcmin squared. Observational targets are GLADE+ galaxies that are contained inside \nthe 90% probability volume of the localization region. The example JSON-file with \nGLADE+ target is shown bellow:\n\n\u003cfigure align=\"center\"\u003e\n   \u003cimg src=\"lvc_json_example.png\"\n         alt=\"LVC json example\"\n         width=\"250\" \n         height=\"500\"\n         float=\"center\"\u003e\n   \u003cfigcaption\u003eFig. 4 - An example of JSON-file for LVC event.\u003c/figcaption\u003e\n\u003c/figure\u003e\n\nNote. Only those targets that observable by the certain telescope in the nearest observational window are in the list. \n\n\n### Mosaic observations (WiP)\n\nThe mosaic (e.g. tile, sky-field) observations is applicable for wide-field telescopes, \nwith FOV $\\gtrsim 40$ arcmin. First off, algorithm re-grids the skymap in the tiles of \nsize 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 \nprobable to least probable tiles strictly N_ITER steps. After algorithm has finished, \nthe list of tile centers written to the JSON-file.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmickolaua%2Faware-repo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmickolaua%2Faware-repo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmickolaua%2Faware-repo/lists"}