# Spelunker — NIRISS FGS quicklook pipeline
-------------------------------------------------------------------------------------
**Authors:** Derod Deal (dealderod@ufl.edu), Néstor Espinoza (nespinoza@stsci.edu)
`spelunker` is a package that assists on studying JWST FGS/NIRISS guidestar data. Check out our [readthedocs](https://jwst-fgs-spelunker.readthedocs.io) for detailed documentation.
**If you make use of `spelunker`, please [cite our paper](https://joss.theoj.org/papers/10.21105/joss.06202) (Deal & Espinoza, 2024, JOSS, 9(97), 6202):**
@article{Deal2024,
doi = {10.21105/joss.06202},
url = {https://doi.org/10.21105/joss.06202},
year = {2024}, publisher = {The Open Journal},
volume = {9},
number = {97},
pages = {6202},
author = {Derod Deal and Néstor Espinoza},
title = {Spelunker: A quick-look Python pipeline for JWST NIRISS FGS Guide Star Data},
journal = {Journal of Open Source Software}
}
<a href="https://joss.theoj.org/papers/1547289b35b16a5d2955b20ed3945a2e"><img src="https://joss.theoj.org/papers/1547289b35b16a5d2955b20ed3945a2e/status.svg"></a>
## Statement of need
Every time JWST observes an object, it simultaneously observes a nearby star --- a so-called "guide star" --- with the NIRISS Fine Guidance Sensor (FGS) that is used to keep the telescope locked on the target of interest. While researchers typically focus on their science targets, the guide star data can be extremely interesting on its own right both to detect anomalies on science data, as well as to explore time-series data of guidestars themselves. `spelunker` provides an easy-to-access ("plug-and-play") library to access this guide star data. The library is able to generate time-series for several metrics of the FGS data in an automated fashion, including fluxes and PSF variations, along with derived products from those such as periodograms that can aid on their analysis given only a JWST program ID number.
## Installation
To install `spelunker`, use `pip install`.
```bash
pip install spelunker
```
## Using the library
Get started with `spelunker` with only two lines of code.
```python
import spelunker
spk = spelunker.load(pid=1534)
```
This will download guidestar data for Program ID 1534; the `spk` object itself can then be used to explore this guidestar data! For example, let's make a plot of the guidestar time-series for the first minutes of this PID:
```python
import matplotlib.pyplot as plt
# Convert times from MJD to minutes:
fig, ax = plt.subplots(figsize=(6,2), dpi=200)
plt.plot( ( spk.fg_time - spk.fg_time[0] ) * 24 * 60, spk.fg_flux, color='black', linewidth=0.2 )
plt.xlim(0,10)
plt.ylim(830000,950000)
plt.xlabel('Time from start (minutes)')
plt.ylabel('Counts')
```
<p align='center'>
<img src="plots/timeseries.png" width=100% height=80%>
</p>
(See below on more information that can be extracted, including fitting 2D gaussians to each FGS integration!).
We can even make a plot of the tracked guidestars within this Program ID. Within a selected Program ID, multiple guidestars could be used for each observation. Each star or object comes from the Guide Star Catalog (GSC) and is pre-selected depending on [telescope pointing and suitability of the star](https://jwst-docs.stsci.edu/jwst-observatory-characteristics/jwst-guide-stars). In the generated figure from `spk.guidestar_plot`, the guidestar positions (marked with an X) in the given Program ID are plotted from the *START* to the end of the program. A line (`gs track`) is traced between each guidestar to order each used target overtime.
```python
spk.guidestar_plot()
```
<p align='center'>
<img src="https://github.com/GalagaBits/JWST-FGS-Spelunker/blob/main/plots/guidestar_positions.png" width=80% height=80%>
</p>
Mnemonics from JWST technical events can be overplotted on any timeseries, such as high-gain antenna (HGA) movement or to identify if the FGS tracks a new guidestar [if the `jwstuser` package is also installed](https://github.com/spacetelescope/jwstuser/). Here, use `spk.mnemonics` to access engineering telemetry for `SA_ZHAGUPST` as a matplotlib `axes` object:
```python
import matplotlib.pyplot as plt
spk.mast_api_token = 'insert a token from auth.MAST here'
fig, ax = plt.subplots(figsize=(12,4),dpi=200)
ax = spk.mnemonics_local('GUIDESTAR') # plots when the JWST tracks onto a new guidestars as a vertical line
ax = spk.mnemonics('SA_ZHGAUPST', 60067.84, 60067.9) # plots the start and end of high gain antenna movement
ax.plot(spk.fg_time, spk.fg_flux)
plt.legend(loc=3)
plt.xlim(60067.84, 60067.9)
plt.show()
```
<img src="https://github.com/GalagaBits/JWST-FGS-Spelunker/blob/main/plots/mnemonics.png">
For more information on the tools under `spelunker` and how to get started, visit the [quickstart guide](https://github.com/GalagaBits/JWST-FGS-Spelunker/blob/main/notebooks/fgs-spelunker_quickstart.ipynb) or checkout our [readthedocs](https://jwst-fgs-spelunker.readthedocs.io). Get acquainted with `spelunker` with the following example notebooks:
- [Pixel centroid changes and mnemonics](https://github.com/GalagaBits/JWST-FGS-Spelunker/blob/main/notebooks/examples/pixel_centroid_mnemonics.ipynb)
- [TSOS Guidestar Demo](https://github.com/GalagaBits/JWST-FGS-Spelunker/blob/main/notebooks/fgs-spelunker-and-tsos.ipynb)
This software is currently under development on [GitHub](https://github.com). To report bugs or to send feature requests, send us an email or [open an issue](https://github.com/GalagaBits/JWST-FGS-Spelunker/issues) on GitHub.
## Licence and attribution
This project is under the MIT License, which can be viewed [here](https://github.com/GalagaBits/JWST-FGS-Spelunker/blob/main/LICENSE).
## Acknowledgments
DD and NE would like to thank the STScI's Space Astronomy Summer Program (SASP) as well as the National Astronomy Consortium (NAC) program which made it possible for them to work together on this fantastic project!
Raw data
{
"_id": null,
"home_page": "https://github.com/GalagaBits/JWST-FGS-Spelunker",
"name": "spelunker",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.12",
"maintainer_email": null,
"keywords": "guidestars",
"author": "Derod Deal",
"author_email": "dealderod@ufl.edu",
"download_url": "https://files.pythonhosted.org/packages/da/39/da266f2e510102ef75ae308b245e348ff24a61189abd8d10c33a1474bcaa/spelunker-1.1.18.tar.gz",
"platform": null,
"description": "# Spelunker \u2014 NIRISS FGS quicklook pipeline \n\n\n\n-------------------------------------------------------------------------------------\n\n**Authors:** Derod Deal (dealderod@ufl.edu), N\u00e9stor Espinoza (nespinoza@stsci.edu)\n\n`spelunker` is a package that assists on studying JWST FGS/NIRISS guidestar data. Check out our [readthedocs](https://jwst-fgs-spelunker.readthedocs.io) for detailed documentation. \n\n**If you make use of `spelunker`, please [cite our paper](https://joss.theoj.org/papers/10.21105/joss.06202) (Deal & Espinoza, 2024, JOSS, 9(97), 6202):**\n\n @article{Deal2024, \n doi = {10.21105/joss.06202}, \n url = {https://doi.org/10.21105/joss.06202}, \n year = {2024}, publisher = {The Open Journal}, \n volume = {9}, \n number = {97}, \n pages = {6202}, \n author = {Derod Deal and N\u00e9stor Espinoza}, \n title = {Spelunker: A quick-look Python pipeline for JWST NIRISS FGS Guide Star Data}, \n journal = {Journal of Open Source Software} \n }\n\n<a href=\"https://joss.theoj.org/papers/1547289b35b16a5d2955b20ed3945a2e\"><img src=\"https://joss.theoj.org/papers/1547289b35b16a5d2955b20ed3945a2e/status.svg\"></a>\n\n## Statement of need\n\nEvery time JWST observes an object, it simultaneously observes a nearby star --- a so-called \"guide star\" --- with the NIRISS Fine Guidance Sensor (FGS) that is used to keep the telescope locked on the target of interest. While researchers typically focus on their science targets, the guide star data can be extremely interesting on its own right both to detect anomalies on science data, as well as to explore time-series data of guidestars themselves. `spelunker` provides an easy-to-access (\"plug-and-play\") library to access this guide star data. The library is able to generate time-series for several metrics of the FGS data in an automated fashion, including fluxes and PSF variations, along with derived products from those such as periodograms that can aid on their analysis given only a JWST program ID number.\n\n## Installation\n\nTo install `spelunker`, use `pip install`.\n\n```bash\npip install spelunker\n```\n\n## Using the library\n\nGet started with `spelunker` with only two lines of code.\n\n```python\nimport spelunker\n\nspk = spelunker.load(pid=1534)\n```\nThis will download guidestar data for Program ID 1534; the `spk` object itself can then be used to explore this guidestar data! For example, let's make a plot of the guidestar time-series for the first minutes of this PID:\n\n```python\nimport matplotlib.pyplot as plt\n\n# Convert times from MJD to minutes:\nfig, ax = plt.subplots(figsize=(6,2), dpi=200)\n\nplt.plot( ( spk.fg_time - spk.fg_time[0] ) * 24 * 60, spk.fg_flux, color='black', linewidth=0.2 )\n\nplt.xlim(0,10)\nplt.ylim(830000,950000)\nplt.xlabel('Time from start (minutes)')\nplt.ylabel('Counts')\n\n```\n<p align='center'>\n <img src=\"plots/timeseries.png\" width=100% height=80%>\n</p>\n\n(See below on more information that can be extracted, including fitting 2D gaussians to each FGS integration!). \n\nWe can even make a plot of the tracked guidestars within this Program ID. Within a selected Program ID, multiple guidestars could be used for each observation. Each star or object comes from the Guide Star Catalog (GSC) and is pre-selected depending on [telescope pointing and suitability of the star](https://jwst-docs.stsci.edu/jwst-observatory-characteristics/jwst-guide-stars). In the generated figure from `spk.guidestar_plot`, the guidestar positions (marked with an X) in the given Program ID are plotted from the *START* to the end of the program. A line (`gs track`) is traced between each guidestar to order each used target overtime.\n\n```python\nspk.guidestar_plot()\n```\n<p align='center'>\n <img src=\"https://github.com/GalagaBits/JWST-FGS-Spelunker/blob/main/plots/guidestar_positions.png\" width=80% height=80%>\n</p>\n\n\n\nMnemonics from JWST technical events can be overplotted on any timeseries, such as high-gain antenna (HGA) movement or to identify if the FGS tracks a new guidestar [if the `jwstuser` package is also installed](https://github.com/spacetelescope/jwstuser/). Here, use `spk.mnemonics` to access engineering telemetry for `SA_ZHAGUPST` as a matplotlib `axes` object:\n\n```python\nimport matplotlib.pyplot as plt\n\nspk.mast_api_token = 'insert a token from auth.MAST here'\n\nfig, ax = plt.subplots(figsize=(12,4),dpi=200)\n\nax = spk.mnemonics_local('GUIDESTAR') # plots when the JWST tracks onto a new guidestars as a vertical line\nax = spk.mnemonics('SA_ZHGAUPST', 60067.84, 60067.9) # plots the start and end of high gain antenna movement\n\nax.plot(spk.fg_time, spk.fg_flux)\nplt.legend(loc=3)\nplt.xlim(60067.84, 60067.9)\nplt.show()\n```\n\n\n<img src=\"https://github.com/GalagaBits/JWST-FGS-Spelunker/blob/main/plots/mnemonics.png\">\n\nFor more information on the tools under `spelunker` and how to get started, visit the [quickstart guide](https://github.com/GalagaBits/JWST-FGS-Spelunker/blob/main/notebooks/fgs-spelunker_quickstart.ipynb) or checkout our [readthedocs](https://jwst-fgs-spelunker.readthedocs.io). Get acquainted with `spelunker` with the following example notebooks:\n\n- [Pixel centroid changes and mnemonics](https://github.com/GalagaBits/JWST-FGS-Spelunker/blob/main/notebooks/examples/pixel_centroid_mnemonics.ipynb)\n- [TSOS Guidestar Demo](https://github.com/GalagaBits/JWST-FGS-Spelunker/blob/main/notebooks/fgs-spelunker-and-tsos.ipynb)\n\nThis software is currently under development on [GitHub](https://github.com). To report bugs or to send feature requests, send us an email or [open an issue](https://github.com/GalagaBits/JWST-FGS-Spelunker/issues) on GitHub.\n\n## Licence and attribution\n\nThis project is under the MIT License, which can be viewed [here](https://github.com/GalagaBits/JWST-FGS-Spelunker/blob/main/LICENSE).\n\n## Acknowledgments\n\nDD and NE would like to thank the STScI's Space Astronomy Summer Program (SASP) as well as the National Astronomy Consortium (NAC) program which made it possible for them to work together on this fantastic project!\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "spelunker: a library to extract guidestar data and observe technical and stellar events",
"version": "1.1.18",
"project_urls": {
"Homepage": "https://github.com/GalagaBits/JWST-FGS-Spelunker"
},
"split_keywords": [
"guidestars"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a6a039e89cf5a936c756bcf18ab15d0d463215542200f320d08fac86ee97ad52",
"md5": "b675dcd60f671f4e20badbf13b9264bb",
"sha256": "75782d8ef8bea1629d22ea2fc698997389dfa01a9e913a458fa9029c84bf6c83"
},
"downloads": -1,
"filename": "spelunker-1.1.18-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b675dcd60f671f4e20badbf13b9264bb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.12",
"size": 24279,
"upload_time": "2024-05-24T17:18:50",
"upload_time_iso_8601": "2024-05-24T17:18:50.387995Z",
"url": "https://files.pythonhosted.org/packages/a6/a0/39e89cf5a936c756bcf18ab15d0d463215542200f320d08fac86ee97ad52/spelunker-1.1.18-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "da39da266f2e510102ef75ae308b245e348ff24a61189abd8d10c33a1474bcaa",
"md5": "23cbf65ec3979425fbe371f6f2ef5bd1",
"sha256": "a7dde9f3efafbf40ee80c452971c47b696530c141654ac2dfa088e196be10370"
},
"downloads": -1,
"filename": "spelunker-1.1.18.tar.gz",
"has_sig": false,
"md5_digest": "23cbf65ec3979425fbe371f6f2ef5bd1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.12",
"size": 23851,
"upload_time": "2024-05-24T17:18:51",
"upload_time_iso_8601": "2024-05-24T17:18:51.605670Z",
"url": "https://files.pythonhosted.org/packages/da/39/da266f2e510102ef75ae308b245e348ff24a61189abd8d10c33a1474bcaa/spelunker-1.1.18.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-24 17:18:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "GalagaBits",
"github_project": "JWST-FGS-Spelunker",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "spelunker"
}
JSON
