# planobs
Toolset for planning and triggering observations with ZTF. GCN parsing is currently only implemented for IceCube alerts.
It checks if the object is observable with a maximum airmass on a given date, plots the airmass vs. time, computes two optimal (minimal airmass at night) observations of 300s in g- and r and generate the ZTF field plots for all fields having a reference. There is also the option to create a longer (multiday) observation plan.
[](https://github.com/simeonreusch/planobs/actions/workflows/continous_integration.yml)
[](https://coveralls.io/github/simeonreusch/planobs?branch=main)
[](https://badge.fury.io/py/planobs)
[](https://zenodo.org/badge/latestdoi/512753573)
# Requirements
[ztfquery](https://github.com/mickaelrigault/ztfquery) for checking if fields have a reference.
planobs requires Python 3.10.
# Installation
Using Pip: ```pip install planobs```.
Otherwise, you can clone the repository: ```git clone https://github.com/simeonreusch/planobs```, followed by ```poetry install``` This also gives you access to the Slackbot.
Note for ARM-based macs: The install of `fiona` might fail if you do not have [gdal](https://gdal.org/) installed. In that case, consider using a `conda` and running `conda install -c conda-forge gdal` before running `poetry install`.
# General usage
```python
from planobs.plan import PlanObservation
name = "testalert" # Name of the alert object
date = "2020-05-05" #This is optional, defaults to today
ra = 133.7
dec = 13.37
plan = PlanObservation(name=name, date=date, ra=ra, dec=dec)
plan.plot_target() # Plots the observing conditions
plan.request_ztf_fields() # Checks in which ZTF fields this
# object is observable and generates plots for them.
```
The observation plot and the ZTF field plots will be located in the current directory/[name]
Note: Checking if fields have references requires ztfquery, which needs IPAC credentials.
# Usage for IceCube alerts
```python
from planobs.plan import PlanObservation
name = "IC201007A" # Name of the alert object
date = "2020-10-08" #This is optional, defaults to today
# No RA and Dec values are given, because we set alertsource to icecube, which leads to automatic GCN parsing.
plan = PlanObservation(name=name, date=date, alertsource="icecube")
plan.plot_target() # Plots the observing conditions.
plan.request_ztf_fields() # Checks which ZTF fields cover the target (and have references).
print(plan.recommended_field) # This give you the field with the most overlap.
```
# Triggering ZTF
`planobs` can be used to schedule ToO observations with ZTF.
This is done through API calls to the `Kowalski` system, managed by the Kowalski Python API [penquins](https://github.com/dmitryduev/penquins).
To use this functionality, you must first configure the connection details. You need both an API token, and to know the address of the Kowalski host address. You can then set these as environment variables:
```bash
export KOWALSKI_HOST=something
export KOWALSKI_API_TOKEN=somethingelse
```
You can then import the Queue class for querying, submitting and deleting ToO triggers:
## Querying
```python
from planobs.api import Queue
q = Queue(user="yourname")
existing_too_requests = get_too_queues(names_only=True)
print(existing_too_requests)
```
## Submitting
```python
from planobs.api import Queue, get_too_queues
from planobs.models import TooTarget
trigger_name = "ToO_IC220513A_test"
# Instantiate the API connection
q = Queue(user="yourname")
# Add a trigger to the internal submission queue. Filter ID is 1 for r-, 2 for g- and 3 for i-band. Exposure time is given in seconds.
q.add_trigger_to_queue(
trigger_name=trigger_name,
validity_window_start_mjd=59719.309333333334,
targets=[
TooTarget(
field_id=427,
filter_id=1,
exposure_time=300,
)
],
)
q.submit_queue()
# Now we verify that our trigger has been successfully submitted
existing_too_requests = get_too_queues(names_only=True)
print(existing_too_requests)
assert trigger_name in existing_too_requests
```
## Deleting
```python
from planobs.api import Queue
q = Queue(user="yourname")
trigger_name = "ToO_IC220513A_test"
res = q.delete_trigger(trigger_name=trigger_name)
```
# Citing the code
If you use this code, please cite it! A DOI is provided by Zenodo, which can reference both the code repository and specific releases:
[](https://zenodo.org/badge/latestdoi/512753573)
# Contributors
* Simeon Reusch [@simeonreusch](https://github.com/simeonreusch)
* Robert Stein [@robertdstein](https://github.com/robertdstein)
Raw data
{
"_id": null,
"home_page": "https://github.com/simeonreusch/planobs",
"name": "planobs",
"maintainer": "Simeon Reusch",
"docs_url": null,
"requires_python": ">=3.10,<4",
"maintainer_email": "simeon.reusch@desy.de",
"keywords": "astroparticle physics,science,multimessenger astronomy,ZTF",
"author": "Simeon Reusch",
"author_email": "simeon.reusch@desy.de",
"download_url": "https://files.pythonhosted.org/packages/46/95/4ce8f8a316f03ca8303a8288ab12e926fa3184f9e2062ee94d0938a827ec/planobs-0.7.3.tar.gz",
"platform": null,
"description": "# planobs\nToolset for planning and triggering observations with ZTF. GCN parsing is currently only implemented for IceCube alerts.\n\nIt checks if the object is observable with a maximum airmass on a given date, plots the airmass vs. time, computes two optimal (minimal airmass at night) observations of 300s in g- and r and generate the ZTF field plots for all fields having a reference. There is also the option to create a longer (multiday) observation plan.\n\n[](https://github.com/simeonreusch/planobs/actions/workflows/continous_integration.yml)\n[](https://coveralls.io/github/simeonreusch/planobs?branch=main)\n[](https://badge.fury.io/py/planobs)\n[](https://zenodo.org/badge/latestdoi/512753573)\n\n# Requirements\n[ztfquery](https://github.com/mickaelrigault/ztfquery) for checking if fields have a reference.\n\nplanobs requires Python 3.10.\n\n# Installation\nUsing Pip: ```pip install planobs```.\n\nOtherwise, you can clone the repository: ```git clone https://github.com/simeonreusch/planobs```, followed by ```poetry install``` This also gives you access to the Slackbot. \n\nNote for ARM-based macs: The install of `fiona` might fail if you do not have [gdal](https://gdal.org/) installed. In that case, consider using a `conda` and running `conda install -c conda-forge gdal` before running `poetry install`.\n\n# General usage\n```python\nfrom planobs.plan import PlanObservation\n\nname = \"testalert\" # Name of the alert object\ndate = \"2020-05-05\" #This is optional, defaults to today\nra = 133.7\ndec = 13.37\n\nplan = PlanObservation(name=name, date=date, ra=ra, dec=dec)\nplan.plot_target() # Plots the observing conditions\nplan.request_ztf_fields() # Checks in which ZTF fields this \n# object is observable and generates plots for them.\n```\nThe observation plot and the ZTF field plots will be located in the current directory/[name]\n\n\nNote: Checking if fields have references requires ztfquery, which needs IPAC credentials.\n\n# Usage for IceCube alerts\n```python\nfrom planobs.plan import PlanObservation\n\nname = \"IC201007A\" # Name of the alert object\ndate = \"2020-10-08\" #This is optional, defaults to today\n\n# No RA and Dec values are given, because we set alertsource to icecube, which leads to automatic GCN parsing.\n\nplan = PlanObservation(name=name, date=date, alertsource=\"icecube\")\nplan.plot_target() # Plots the observing conditions.\nplan.request_ztf_fields() # Checks which ZTF fields cover the target (and have references).\nprint(plan.recommended_field) # This give you the field with the most overlap.\n```\n\n\n\n# Triggering ZTF\n\n`planobs` can be used to schedule ToO observations with ZTF. \nThis is done through API calls to the `Kowalski` system, managed by the Kowalski Python API [penquins](https://github.com/dmitryduev/penquins).\n\nTo use this functionality, you must first configure the connection details. You need both an API token, and to know the address of the Kowalski host address. You can then set these as environment variables:\n\n```bash\nexport KOWALSKI_HOST=something\nexport KOWALSKI_API_TOKEN=somethingelse\n```\n\nYou can then import the Queue class for querying, submitting and deleting ToO triggers:\n\n## Querying\n\n```python\nfrom planobs.api import Queue\n\nq = Queue(user=\"yourname\")\n\nexisting_too_requests = get_too_queues(names_only=True)\nprint(existing_too_requests)\n```\n\n## Submitting\n\n```python\nfrom planobs.api import Queue, get_too_queues\nfrom planobs.models import TooTarget\n\ntrigger_name = \"ToO_IC220513A_test\"\n\n# Instantiate the API connection\nq = Queue(user=\"yourname\")\n\n# Add a trigger to the internal submission queue. Filter ID is 1 for r-, 2 for g- and 3 for i-band. Exposure time is given in seconds.\nq.add_trigger_to_queue(\n trigger_name=trigger_name,\n validity_window_start_mjd=59719.309333333334,\n targets=[\n TooTarget(\n field_id=427,\n filter_id=1,\n exposure_time=300,\n )\n ],\n)\n\nq.submit_queue()\n\n# Now we verify that our trigger has been successfully submitted\nexisting_too_requests = get_too_queues(names_only=True)\nprint(existing_too_requests)\nassert trigger_name in existing_too_requests\n```\n\n## Deleting\n```python\nfrom planobs.api import Queue\n\nq = Queue(user=\"yourname\")\n\ntrigger_name = \"ToO_IC220513A_test\"\n\nres = q.delete_trigger(trigger_name=trigger_name)\n```\n\n# Citing the code\n\nIf you use this code, please cite it! A DOI is provided by Zenodo, which can reference both the code repository and specific releases:\n\n[](https://zenodo.org/badge/latestdoi/512753573)\n\n# Contributors\n\n* Simeon Reusch [@simeonreusch](https://github.com/simeonreusch)\n* Robert Stein [@robertdstein](https://github.com/robertdstein)",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Plan observations with the Zwicky Transient Facility",
"version": "0.7.3",
"project_urls": {
"Homepage": "https://github.com/simeonreusch/planobs",
"Repository": "https://github.com/simeonreusch/planobs"
},
"split_keywords": [
"astroparticle physics",
"science",
"multimessenger astronomy",
"ztf"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a126386a0023ad0e3ede8ac257421933edbd615c865cabba4c8433c5309255b3",
"md5": "f09a14f05b7da6285ddba76279418b8d",
"sha256": "32697e91269de6bd59d61e5a4fcb913d5fc3afd6f96d95f506098701dc5f2ef4"
},
"downloads": -1,
"filename": "planobs-0.7.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f09a14f05b7da6285ddba76279418b8d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4",
"size": 18506279,
"upload_time": "2023-09-01T11:11:34",
"upload_time_iso_8601": "2023-09-01T11:11:34.807786Z",
"url": "https://files.pythonhosted.org/packages/a1/26/386a0023ad0e3ede8ac257421933edbd615c865cabba4c8433c5309255b3/planobs-0.7.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "46954ce8f8a316f03ca8303a8288ab12e926fa3184f9e2062ee94d0938a827ec",
"md5": "4cd147785f502778619e7c64a7c5341d",
"sha256": "1d05d297ec1593536faf610557eba0db7c67196c1849d613b553d66f969eb111"
},
"downloads": -1,
"filename": "planobs-0.7.3.tar.gz",
"has_sig": false,
"md5_digest": "4cd147785f502778619e7c64a7c5341d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4",
"size": 17903111,
"upload_time": "2023-09-01T11:11:38",
"upload_time_iso_8601": "2023-09-01T11:11:38.599108Z",
"url": "https://files.pythonhosted.org/packages/46/95/4ce8f8a316f03ca8303a8288ab12e926fa3184f9e2062ee94d0938a827ec/planobs-0.7.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-01 11:11:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "simeonreusch",
"github_project": "planobs",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "planobs"
}
JSON
