# SNEWS Publishing Tool
<img src="docs/custom_logo.png" alt="snews_logo" width="200"/>
[](https://snews-publishing-tools.readthedocs.io/en/latest/?badge=latest)
<br>See the docs at
| | |
| ------------ | ------ |
| **Docs:** | https://snews-publishing-tools.readthedocs.io/en/latest/ |
This packages provides users with a Python API and CLI to publish observation messages to SNEWS
> Note: Make sure your hop credentials are set up !!<br>
> Follow the instructions [**here**](https://github.com/scimma/hop-client) if needed<br>
> Request permissions to given topics [here](https://my.hop.scimma.org/hopauth/)
| |
|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Fire-Drills** |
| Also see [this page](https://snews-publishing-tools.readthedocs.io/en/latest/user/firedrills.html) | | |
| `snews_pt` allows for fire-drill mode, currently this is the default option. <br/>Later, it can be adjusted through `firedrill_mode=True/False` arguments in subcription and publication functions, and through `--firedrill/--no-firedrill` flags within the CLI tools. Make sure you have the correct [permissions](https://my.hop.scimma.org/hopauth/) to publish and subscribe to these firedrill channels. |
## How to Install
- #### From source <br>
First you need to clone this repo. In your terminal run the following:
```bash
git clone https://github.com/SNEWS2/SNEWS_Publishing_Tools.git
```
Once cloned, install the package using pip (make sure you're in the cloned dir)
```bash
pip install .
```
- #### From PyPi <br>
```bash
pip install -U snews-pt
```
## How to Publish
Before we get started, right now the publishing method will send your message to the test kafka server.
First you need to import your Publisher:
````Python
# Import the constructor for SNEWS Tiers and Publisher class
from snews_pt.snews_pub import SNEWSTiersPublisher
````
### Passing Message Parameters as Arguments.
To send a message you need initialize the ``Publisher``, construct your message by initializing ``SNEWSTiers`` and
passing your parameters of choice. The backend will parse your arguments, check their data types and determine which
tiers you can send a message to (see **Publishing Protocols**). If you pass multiple parameters (_see code bellow_) the
sender will send a message *all* the appropriate tiers.
```python
SNEWSTiersPublisher(detector_name='KamLAND', neutrino_time="2022-02-28T04:31:08.678999",
timing_series=["2022-02-28T04:31:08.694999", "2022-02-28T04:31:08.698999", "2022-02-28T04:31:08.7078945"],
p_val=0.000007,
machine_time="2022-02-28T04:31:09.778859",
).send_to_snews()
```
This instance has parameters for **CoincidenceTier** and **TimingTier**, thus it will send a message to both. The output
should look like this:
### Passing Message Parameters from JSON File.
You can also pass your input from a json file, and make modifications on the spot. Let's first create an `observation` object this time before sending it to snews;
```python
observation = SNEWSTiersPublisher.from_json('my_input_asjson.json',
detector_name='XENONnT',
comment="This is submitted from a json file")
```
Here, we read the content from the `'my_input_asjson.json'` file, and overwrite `detector_name` and also add a comment field (which will be accepted as a meta data). Notice we still haven't sent it to snews yet. You can display, and modify the _parsed messages_ after you create the object instance. Depending on the fields you provided `SNEWSTierPublisher` will decide where to submit your data (see above). You can see these tier(s) and the individual message contents. See, `observation.tiernames` to get names of the tiers that your input message belongs, and `observation.messages` to display their content, and modify if desired.
Once you are done, you can just send that `observation` object to snews.
```
observation.send_to_snews()
```
***See this [`examples notebook`](./examples.ipynb) for more tutorial scripts***
- ### [See Publishing Protocols here](docs/user/message_schema.md)
- ### [See Message Schemas here](docs/user/message_schema.md)
## How to Subscribe
In two lines, one can subscribe to the alert topic specified in the default configuration. <br>
This starts a stream, and waits for alert messages to be received.
```python
from snews_pt.snews_sub import Subscriber
Subscriber().subscribe()
```
Should there be an alert message, this will be both displayed on the screen and saved into your local machine. The location can be passed as an argument `subscribe(outputfolder='folder/path')`, if not given, the default is used based on the `"ALERT_OUTPUT"` folder in the environment file. The message is then saved under this directory with a time stamp as `folder/0_<date>_ALERTS.json` and if there are multiple messages in the same day e.g. for the same supernova you kept receiving alerts with every coincidence message, the counter infront will be incremented. An example alert message (partly missing) can be
found [here](https://github.com/SNEWS2/SNEWS_Publishing_Tools/blob/main/doc/subscribed_messages.json)
---
# [Command Line Interface (CLI)](docs/cli_docs.md)
There also exists tools for command line interactions. These are explained in detail [here](docs/cli_docs.md)
### Extension for follow-up plugins (only with CLI for now)
`snews_pt subscribe` also allows for other scripts to be plugged in and act on alerts. The *CLI* command `snews_pt subscribe` takes the custom made script via `--plugin` (`-p`) option.
```bash
user/home$: snews_pt subscribe -p ./auxiliary/custom_script.py
```
`snews_pt subscribe` saves the alert messages to a local JSON file with the date stamp of the received time. When a custom plugin is provided, as soon as an alert is received and JSON is created, the name of this unique-JSON file is passed to the script and executed.
Therefore, all custom-made scripts should contain the following two lines;
```python
# in "custom_made_script.py"
import sys, json
data = json.load(open(sys.argv[1]))
```
and do the follow-up work using the `data` dictionary as the alert message. See [this dummy example]https://github.com/SNEWS2/SNEWS_Publishing_Tools/blob/main/snews_pt/test/random_plugin.py) which
only brags about itself and displays you the content of the alert message.
Raw data
{
"_id": null,
"home_page": "https://github.com/SNEWS2/SNEWS_Publishing_Tools",
"name": "snews-pt",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "setup,distutils",
"author": "Sebastian Torres-Lara, Melih Kara",
"author_email": "sebastiantorreslara17@gmail.com, karamel.itu@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/6c/b2/19d97416018b6dcf76bb684d9347cbbda9017c06cc128b57de85e95eb1f9/snews_pt-1.3.3.tar.gz",
"platform": null,
"description": "# SNEWS Publishing Tool\n<img src=\"docs/custom_logo.png\" alt=\"snews_logo\" width=\"200\"/> \n\n[](https://snews-publishing-tools.readthedocs.io/en/latest/?badge=latest)\n\n<br>See the docs at\n\n| | |\n| ------------ | ------ |\n| **Docs:** | https://snews-publishing-tools.readthedocs.io/en/latest/ |\n\nThis packages provides users with a Python API and CLI to publish observation messages to SNEWS\n\n> Note: Make sure your hop credentials are set up !!<br>\n> Follow the instructions [**here**](https://github.com/scimma/hop-client) if needed<br>\n> Request permissions to given topics [here](https://my.hop.scimma.org/hopauth/)\n\n| |\n|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| \n| **Fire-Drills** |\n| Also see [this page](https://snews-publishing-tools.readthedocs.io/en/latest/user/firedrills.html) | | |\n| `snews_pt` allows for fire-drill mode, currently this is the default option. <br/>Later, it can be adjusted through `firedrill_mode=True/False` arguments in subcription and publication functions, and through `--firedrill/--no-firedrill` flags within the CLI tools. Make sure you have the correct [permissions](https://my.hop.scimma.org/hopauth/) to publish and subscribe to these firedrill channels. |\n\n## How to Install\n\n- #### From source <br>\n First you need to clone this repo. In your terminal run the following:\n\n ```bash \n git clone https://github.com/SNEWS2/SNEWS_Publishing_Tools.git\n ```\n Once cloned, install the package using pip (make sure you're in the cloned dir)\n ```bash\n pip install .\n ```\n\n- #### From PyPi <br>\n ```bash\n pip install -U snews-pt\n ```\n\n## How to Publish\n\nBefore we get started, right now the publishing method will send your message to the test kafka server.\n\nFirst you need to import your Publisher:\n\n````Python\n# Import the constructor for SNEWS Tiers and Publisher class\nfrom snews_pt.snews_pub import SNEWSTiersPublisher\n````\n### Passing Message Parameters as Arguments. \nTo send a message you need initialize the ``Publisher``, construct your message by initializing ``SNEWSTiers`` and\npassing your parameters of choice. The backend will parse your arguments, check their data types and determine which\ntiers you can send a message to (see **Publishing Protocols**). If you pass multiple parameters (_see code bellow_) the\nsender will send a message *all* the appropriate tiers.\n\n```python\nSNEWSTiersPublisher(detector_name='KamLAND', neutrino_time=\"2022-02-28T04:31:08.678999\",\n timing_series=[\"2022-02-28T04:31:08.694999\", \"2022-02-28T04:31:08.698999\", \"2022-02-28T04:31:08.7078945\"],\n p_val=0.000007,\n machine_time=\"2022-02-28T04:31:09.778859\", \n ).send_to_snews()\n```\n\nThis instance has parameters for **CoincidenceTier** and **TimingTier**, thus it will send a message to both. The output\nshould look like this:\n\n\n### Passing Message Parameters from JSON File.\n\nYou can also pass your input from a json file, and make modifications on the spot. Let's first create an `observation` object this time before sending it to snews;\n\n```python\nobservation = SNEWSTiersPublisher.from_json('my_input_asjson.json', \n detector_name='XENONnT', \n comment=\"This is submitted from a json file\")\n```\nHere, we read the content from the `'my_input_asjson.json'` file, and overwrite `detector_name` and also add a comment field (which will be accepted as a meta data). Notice we still haven't sent it to snews yet. You can display, and modify the _parsed messages_ after you create the object instance. Depending on the fields you provided `SNEWSTierPublisher` will decide where to submit your data (see above). You can see these tier(s) and the individual message contents. See, `observation.tiernames` to get names of the tiers that your input message belongs, and `observation.messages` to display their content, and modify if desired.\n\nOnce you are done, you can just send that `observation` object to snews.\n\n```\nobservation.send_to_snews()\n```\n\n\n***See this [`examples notebook`](./examples.ipynb) for more tutorial scripts***\n\n- ### [See Publishing Protocols here](docs/user/message_schema.md)\n- ### [See Message Schemas here](docs/user/message_schema.md)\n\n## How to Subscribe\n\nIn two lines, one can subscribe to the alert topic specified in the default configuration. <br>\nThis starts a stream, and waits for alert messages to be received.\n\n```python\nfrom snews_pt.snews_sub import Subscriber\n\nSubscriber().subscribe()\n```\n\nShould there be an alert message, this will be both displayed on the screen and saved into your local machine. The location can be passed as an argument `subscribe(outputfolder='folder/path')`, if not given, the default is used based on the `\"ALERT_OUTPUT\"` folder in the environment file. The message is then saved under this directory with a time stamp as `folder/0_<date>_ALERTS.json` and if there are multiple messages in the same day e.g. for the same supernova you kept receiving alerts with every coincidence message, the counter infront will be incremented. An example alert message (partly missing) can be\nfound [here](https://github.com/SNEWS2/SNEWS_Publishing_Tools/blob/main/doc/subscribed_messages.json)\n\n---\n\n# [Command Line Interface (CLI)](docs/cli_docs.md)\n\nThere also exists tools for command line interactions. These are explained in detail [here](docs/cli_docs.md)\n\n### Extension for follow-up plugins (only with CLI for now)\n`snews_pt subscribe` also allows for other scripts to be plugged in and act on alerts. The *CLI* command `snews_pt subscribe` takes the custom made script via `--plugin` (`-p`) option.\n\n```bash \nuser/home$: snews_pt subscribe -p ./auxiliary/custom_script.py\n```\n\n`snews_pt subscribe` saves the alert messages to a local JSON file with the date stamp of the received time. When a custom plugin is provided, as soon as an alert is received and JSON is created, the name of this unique-JSON file is passed to the script and executed.\n\nTherefore, all custom-made scripts should contain the following two lines;\n\n```python\n# in \"custom_made_script.py\"\nimport sys, json\ndata = json.load(open(sys.argv[1]))\n```\nand do the follow-up work using the `data` dictionary as the alert message. See [this dummy example]https://github.com/SNEWS2/SNEWS_Publishing_Tools/blob/main/snews_pt/test/random_plugin.py) which \nonly brags about itself and displays you the content of the alert message.\n",
"bugtrack_url": null,
"license": "BSD 3-Clause",
"summary": "An alert application for observing supernovas.",
"version": "1.3.3",
"project_urls": {
"Homepage": "https://github.com/SNEWS2/SNEWS_Publishing_Tools"
},
"split_keywords": [
"setup",
"distutils"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d107947b6e1c17d07163cbe635bbb935487e656dc8637fa6474ddbe5761825fc",
"md5": "e85eba94d6e4b2d15a3d13776e6b6350",
"sha256": "9ff0fe7ddafa3d9773bf9bb4cbb5a0566294f550f9bd3ca161d8c9bb00b03720"
},
"downloads": -1,
"filename": "snews_pt-1.3.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e85eba94d6e4b2d15a3d13776e6b6350",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 38055,
"upload_time": "2023-05-12T08:22:00",
"upload_time_iso_8601": "2023-05-12T08:22:00.231458Z",
"url": "https://files.pythonhosted.org/packages/d1/07/947b6e1c17d07163cbe635bbb935487e656dc8637fa6474ddbe5761825fc/snews_pt-1.3.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6cb219d97416018b6dcf76bb684d9347cbbda9017c06cc128b57de85e95eb1f9",
"md5": "3ce0782d45122e3f571fd9a27784a123",
"sha256": "c26c0206de91de10ab02cfedf5812661f2599fc521bfe1c5e472e86ae4748877"
},
"downloads": -1,
"filename": "snews_pt-1.3.3.tar.gz",
"has_sig": false,
"md5_digest": "3ce0782d45122e3f571fd9a27784a123",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 317479,
"upload_time": "2023-05-12T08:22:03",
"upload_time_iso_8601": "2023-05-12T08:22:03.327491Z",
"url": "https://files.pythonhosted.org/packages/6c/b2/19d97416018b6dcf76bb684d9347cbbda9017c06cc128b57de85e95eb1f9/snews_pt-1.3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-12 08:22:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SNEWS2",
"github_project": "SNEWS_Publishing_Tools",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "snews-pt"
}
JSON
