# gocart
[](https://zenodo.org/badge/latestdoi/614846695)
<!-- INFO BADGES -->
[](https://pypi.org/project/gocart/)
[](https://pypi.org/project/gocart/)
[](https://anaconda.org/conda-forge/gocart)
[](https://pepy.tech/project/gocart)
[](https://github.com/thespacedoctor/gocart)
<!-- STATUS BADGES -->
[](https://soxs-eso-data.org/ci/blue/organizations/jenkins/gocart/activity?branch=main)
[](https://soxs-eso-data.org/ci/blue/organizations/jenkins/gocart/activity?branch=develop)
[](https://raw.githack.com/thespacedoctor/gocart/main/htmlcov/index.html)
[](https://gocart.readthedocs.io/en/main/)
[](https://github.com/thespacedoctor/gocart/issues?q=is%3Aissue+is%3Aopen+label%3A%22type%3A+bug%22+)
*gocart is a python package and command-line suite used to consume [GCN Kafka streams](https://gcn.nasa.gov).*
[](https://live.staticflickr.com/65535/52985431851_6a4ed02836_o.png)
Documentation for gocart is hosted by [Read the Docs](https://gocart.readthedocs.io/en/main/) ([development version](https://gocart.readthedocs.io/en/develop/) and [main version](https://gocart.readthedocs.io/en/main/)). The code lives on [github](https://github.com/thespacedoctor/gocart). Please report any issues you find [here](https://github.com/thespacedoctor/gocart/issues).
## Features
- Listen to GCN Kafka streams (currently LIGO-Virgo-KAGRA only) and write alerts and skymaps to the local filesystem.
- Ability to 'echo' the Kafka stream by re-listening to the last N days of alerts (provided the alerts are still hosted on the GCN Kafka cluster).
- Alert content, FITS Header data and some extra value-added event parameters are written to a single machine-readable YAML file.
- The healpix skymaps are optionally converted to ascii files (one row per healpix pixel) and/or rendered as aitoff plots.
- Create your own plugin scripts to run whenever an alert is parsed.
- works well in conjunction with [skyTag](https://github.com/thespacedoctor/skyTag).
## Installation
The easiest way to install gocart is to use `conda`:
``` bash
conda create -n gocart python=3.9 pip gocart -c conda-forge
conda activate gocart
```
To upgrade to the latest version of gocart use the command:
``` bash
conda upgrade gocart -c conda-forge
```
It is also possible to install via pip if required:
``` bash
pip install gocart
```
Or you can clone the [github repo](https://github.com/thespacedoctor/gocart) and install from a local version of the code:
``` bash
git clone git@github.com:thespacedoctor/gocart.git
cd gocart
python setup.py install
```
To check installation was successful run `gocart -v`. This should return the version number of the install.
## Initialising gocart
Before using gocart you need to use the `init` command to generate a user settings file. Running the following creates a [yaml](https://learnxinyminutes.com/docs/yaml/) settings file in your home folder under `~/.config/gocart/gocart.yaml`:
```bash
gocart init
```
The file is initially populated with gocart's default settings which can be adjusted to your preference.
If at any point the user settings file becomes corrupted or you just want to start afresh, simply trash the `gocart.yaml` file and rerun `gocart init`.
## GCN Kafka Credentials
When you first come to use gocart, you will need to add a GCN Kafka Client ID and Secret to the `gocart.yaml` settings file. To get these credentials you will need to signup for a [GCN Notices account here](https://gcn.nasa.gov/quickstart).
[](https://live.staticflickr.com/65535/52790651039_d88a05a4f5_b.jpg)
Once signed in, fill in a suitable name for your new client (any name will do, so gocart is as good a name as any). Fill in the captcha and click 'Create New Credentials'.
[](https://live.staticflickr.com/65535/52790654254_2b3611c714_o.png)
In the 'Customize Alerts' section, don't be concerned about what Notice Types to select as these are only used to generate template code in the next section. Not selecting any is fine. Click the 'Generate Code' button. You will now be presented with your newly created client credentials within the body of the code snippet:
[](https://live.staticflickr.com/65535/52790833500_7535fd6b34_o.png)
Open your gocart settings file at `~/.config/gocart/gocart.yaml` and copy and paste these credentials into the appropriate place.
[](https://live.staticflickr.com/65535/52790845580_b5a1145e13_o.png)
Don't worry about the `group_id` parameter, it's initially set to XXXX but gocart will replace this with a unique value when it's first run. It is this `group_id` that allows GCN Kafka to remember which alerts you have or have not heard before. Note the example client above has been deleted, so the credentials quoted here will not work.
You are now ready to start using gocart.
## SkyTag
gocart works very well in conjunction with [skyTag](https://github.com/thespacedoctor/skyTag), a tool to 'annotate' transient sources or galaxies with the percentage credibility region they reside within on a given HealPix sky map.
## How to cite gocart
If you use `gocart` in your work, please cite using the following BibTeX entry:
```bibtex
@software{Young_gocart,
author = {Young, David R.},
doi = {10.5281/zenodo.7970743},
license = {GPL-3.0-only},
title = {{gocart}},
url = {https://github.com/thespacedoctor/gocart}
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/thespacedoctor/gocart",
"name": "gocart",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "astronomy",
"author": "David Young",
"author_email": "d.r.young@qub.ac.uk",
"download_url": "https://files.pythonhosted.org/packages/7c/72/d02557698eed770fddeba362f26dc8251f2f6f350ad87c7d029e96de361b/gocart-0.4.8.tar.gz",
"platform": null,
"description": "# gocart\n\n[](https://zenodo.org/badge/latestdoi/614846695) \n\n<!-- INFO BADGES --> \n\n[](https://pypi.org/project/gocart/)\n[](https://pypi.org/project/gocart/)\n[](https://anaconda.org/conda-forge/gocart)\n[](https://pepy.tech/project/gocart)\n[](https://github.com/thespacedoctor/gocart)\n\n\n<!-- STATUS BADGES --> \n\n[](https://soxs-eso-data.org/ci/blue/organizations/jenkins/gocart/activity?branch=main)\n[](https://soxs-eso-data.org/ci/blue/organizations/jenkins/gocart/activity?branch=develop)\n[](https://raw.githack.com/thespacedoctor/gocart/main/htmlcov/index.html)\n[](https://gocart.readthedocs.io/en/main/)\n[](https://github.com/thespacedoctor/gocart/issues?q=is%3Aissue+is%3Aopen+label%3A%22type%3A+bug%22+) \n\n*gocart is a python package and command-line suite used to consume [GCN Kafka streams](https://gcn.nasa.gov).*\n\n[](https://live.staticflickr.com/65535/52985431851_6a4ed02836_o.png)\n\nDocumentation for gocart is hosted by [Read the Docs](https://gocart.readthedocs.io/en/main/) ([development version](https://gocart.readthedocs.io/en/develop/) and [main version](https://gocart.readthedocs.io/en/main/)). The code lives on [github](https://github.com/thespacedoctor/gocart). Please report any issues you find [here](https://github.com/thespacedoctor/gocart/issues).\n\n## Features\n\n- Listen to GCN Kafka streams (currently LIGO-Virgo-KAGRA only) and write alerts and skymaps to the local filesystem.\n- Ability to 'echo' the Kafka stream by re-listening to the last N days of alerts (provided the alerts are still hosted on the GCN Kafka cluster).\n- Alert content, FITS Header data and some extra value-added event parameters are written to a single machine-readable YAML file.\n- The healpix skymaps are optionally converted to ascii files (one row per healpix pixel) and/or rendered as aitoff plots.\n- Create your own plugin scripts to run whenever an alert is parsed.\n- works well in conjunction with [skyTag](https://github.com/thespacedoctor/skyTag).\n\n## Installation\n\nThe easiest way to install gocart is to use `conda`:\n\n``` bash\nconda create -n gocart python=3.9 pip gocart -c conda-forge\nconda activate gocart\n```\n\nTo upgrade to the latest version of gocart use the command:\n\n``` bash\nconda upgrade gocart -c conda-forge\n```\n\nIt is also possible to install via pip if required:\n\n``` bash\npip install gocart\n```\n\nOr you can clone the [github repo](https://github.com/thespacedoctor/gocart) and install from a local version of the code:\n\n``` bash\ngit clone git@github.com:thespacedoctor/gocart.git\ncd gocart\npython setup.py install\n```\n\nTo check installation was successful run `gocart -v`. This should return the version number of the install.\n\n## Initialising gocart\n\nBefore using gocart you need to use the `init` command to generate a user settings file. Running the following creates a [yaml](https://learnxinyminutes.com/docs/yaml/) settings file in your home folder under `~/.config/gocart/gocart.yaml`:\n\n```bash\ngocart init\n```\n\nThe file is initially populated with gocart's default settings which can be adjusted to your preference.\n\nIf at any point the user settings file becomes corrupted or you just want to start afresh, simply trash the `gocart.yaml` file and rerun `gocart init`.\n\n## GCN Kafka Credentials\n\nWhen you first come to use gocart, you will need to add a GCN Kafka Client ID and Secret to the `gocart.yaml` settings file. To get these credentials you will need to signup for a [GCN Notices account here](https://gcn.nasa.gov/quickstart).\n\n[](https://live.staticflickr.com/65535/52790651039_d88a05a4f5_b.jpg)\n\nOnce signed in, fill in a suitable name for your new client (any name will do, so gocart is as good a name as any). Fill in the captcha and click 'Create New Credentials'.\n\n[](https://live.staticflickr.com/65535/52790654254_2b3611c714_o.png)\n\nIn the 'Customize Alerts' section, don't be concerned about what Notice Types to select as these are only used to generate template code in the next section. Not selecting any is fine. Click the 'Generate Code' button. You will now be presented with your newly created client credentials within the body of the code snippet:\n\n[](https://live.staticflickr.com/65535/52790833500_7535fd6b34_o.png)\n\nOpen your gocart settings file at `~/.config/gocart/gocart.yaml` and copy and paste these credentials into the appropriate place.\n\n[](https://live.staticflickr.com/65535/52790845580_b5a1145e13_o.png)\n\nDon't worry about the `group_id` parameter, it's initially set to XXXX but gocart will replace this with a unique value when it's first run. It is this `group_id` that allows GCN Kafka to remember which alerts you have or have not heard before. Note the example client above has been deleted, so the credentials quoted here will not work.\n\nYou are now ready to start using gocart.\n\n## SkyTag\n\ngocart works very well in conjunction with [skyTag](https://github.com/thespacedoctor/skyTag), a tool to 'annotate' transient sources or galaxies with the percentage credibility region they reside within on a given HealPix sky map.\n\n## How to cite gocart\n\nIf you use `gocart` in your work, please cite using the following BibTeX entry: \n\n```bibtex\n@software{Young_gocart,\nauthor = {Young, David R.},\ndoi = {10.5281/zenodo.7970743},\nlicense = {GPL-3.0-only},\ntitle = {{gocart}},\nurl = {https://github.com/thespacedoctor/gocart}\n}\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Listen for, collect and convert multimessenger skymaps",
"version": "0.4.8",
"project_urls": {
"Download": "https://github.com/thespacedoctor/gocart/archive/v0.4.8.zip",
"Homepage": "https://github.com/thespacedoctor/gocart"
},
"split_keywords": [
"astronomy"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3c5c0c1280acb913fb61d5e64ac993ec88f621c1a621baae056ef1d58630ebfa",
"md5": "43d865957485544af6c4e46f346c1ad7",
"sha256": "fb5a37f12e5d4d1e65417867544dc96f7bdbd91fd5b41977e501e34959b853d2"
},
"downloads": -1,
"filename": "gocart-0.4.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "43d865957485544af6c4e46f346c1ad7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 50916,
"upload_time": "2023-09-04T11:21:39",
"upload_time_iso_8601": "2023-09-04T11:21:39.616550Z",
"url": "https://files.pythonhosted.org/packages/3c/5c/0c1280acb913fb61d5e64ac993ec88f621c1a621baae056ef1d58630ebfa/gocart-0.4.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7c72d02557698eed770fddeba362f26dc8251f2f6f350ad87c7d029e96de361b",
"md5": "b029f45c88a9851b07b20a0248c08cc6",
"sha256": "497ba8b85d3ca8094869644b712aa6265891505a3860adef33c3b48da425c736"
},
"downloads": -1,
"filename": "gocart-0.4.8.tar.gz",
"has_sig": false,
"md5_digest": "b029f45c88a9851b07b20a0248c08cc6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 48241,
"upload_time": "2023-09-04T11:21:36",
"upload_time_iso_8601": "2023-09-04T11:21:36.360036Z",
"url": "https://files.pythonhosted.org/packages/7c/72/d02557698eed770fddeba362f26dc8251f2f6f350ad87c7d029e96de361b/gocart-0.4.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-04 11:21:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "thespacedoctor",
"github_project": "gocart",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "gocart"
}
JSON
