| Name | lkspacecraft JSON |
| Version |
1.0.5
JSON |
| download |
| home_page | None |
| Summary | None |
| upload_time | 2025-01-13 16:13:29 |
| maintainer | None |
| docs_url | None |
| author | Christina Hedges |
| requires_python | <4.0,>=3.9 |
| license | None |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
.. image:: https://github.com/lightkurve/lkspacecraft/actions/workflows/pytest.yml/badge.svg
:target: https://github.com/lightkurve/lkspacecraft/actions/workflows/pytest.yml
:alt: Test status
.. image:: https://badge.fury.io/py/lkspacecraft.svg
:target: https://badge.fury.io/py/lkspacecraft
:alt: PyPI version
.. image:: https://img.shields.io/badge/documentation-live-blue.svg
:target: https://lightkurve.github.io/lkspacecraft/
:alt: Documentation
lkspacecraft
============
.. <!-- intro content start -->
This package provides a way to access the orbital parameters for the
Kepler and TESS spacecrafts. This will enable you to access
1. Spacecraft position at any given time with respect to the solar
system barycenter, the earth, or the moon
2. Spacecraft velocity at any given time with respect to the solar
system barycenter, the earth, or the moon
3. The baycentric time correction for any target RA/Dec at any time
4. The velocity aberration for any target RA/Dec at any time
.. image:: https://raw.githubusercontent.com/lightkurve/lkspacecraft/main/docs/images/tess_wrt_earth.png
:width: 400px
:alt: TESS position with respect to the earth.
Requirements
------------
This package relies heavily on
`spiceypy <https://github.com/AndrewAnnex/SpiceyPy>`__ which wraps
`SPICE <https://naif.jpl.nasa.gov/naif/toolkit.html>`__. It also relies
on `astropy <https://www.astropy.org/>`__.
Installation
------------
You can install this package with ``pip`` using
.. code-block:: console
pip install lkspacecraft --upgrade
You can also install this package by cloning the repo and then
installing via poetry
.. code-block:: console
git clone https://github.com/lightkurve/lkspacecraft.git
cd lkspacecraft
pip install --upgrade poetry
poetry install .
Usage
-----
``lkspacecraft`` provides ``Spacecraft`` object which will enable you to
access the orbital parameters of either the Kepler or TESS spacecraft.
``lkspacecraft`` will obtain the relevant SPICE kernels to calculate the
spacecraft position and velocity. To get the orbital elements you will
need to pick a time that is within the relevant window of those SPICE
kernels (i.e. when the mission was operational).
You can find the start and end times of the kernels using the following
.. code-block:: python
from lkspacecraft import KeplerSpacecraft
ks = KeplerSpacecraft()
ks.start_time, ks.end_time
All times in ``lkspacecraft`` use ``astropy.time.Time`` objects. Using the
``get_spacecraft_position`` or ``get_spacecraft_velocity`` functions
will provide you with the position or velocity in cartesian coordinates,
for example
.. code-block:: python
from lkspacecraft import KeplerSpacecraft
from astropy.time import Time
ks = KeplerSpacecraft()
t = Time("2009-04-06 06:22:56.000025")
ks.get_spacecraft_velocity(t)
will result in
::
array([[ 6.94188023, -26.24714425, -11.16828662]])
This will give the velocity with respect to the solar system barycenter
by default, but you can specify the earth or moon using
.. code-block:: python
from lkspacecraft import KeplerSpacecraft
from astropy.time import Time
ks = KeplerSpacecraft()
t = Time("2009-04-06 06:22:56.000025")
ks.get_spacecraft_velocity(time=t, observer="earth")
You are able to calculate the light arrival time of observations of a
source at a given RA/Dec using ``lkspacecraft``\ ’s
``get_barycentric_time_correction`` function. This will give you the
time delay in seconds from spacecraft time to time at the barycenter.
.. code-block:: python
from lkspacecraft import KeplerSpacecraft
from astropy.time import Time
ks = KeplerSpacecraft()
t = Time("2009-04-06 06:22:56.000025")
ks.get_barycentric_time_correction(time=t, ra=290.666, dec=44.5)
Finally you can calculate velocity aberration using
.. code-block:: python
from lkspacecraft import KeplerSpacecraft
from astropy.time import Time
ks = KeplerSpacecraft()
t = Time("2009-04-06 06:22:56.000025")
ks.get_velocity_aberrated_positions(time=t, ra=290.666, dec=44.5)
Units
~~~~~
In ``lkspacecraft``, just as in ``SPICE``, units are ``km`` and ``s``, unless
otherwise specified.
Kernels
-------
``lkspacecraft`` will obtain the SPICE kernels for Kepler and TESS for you
store them. Kernels can be found here:
The generic kernels can be obtained from NAIF generic kernels:
https://naif.jpl.nasa.gov/pub/naif/generic_kernels/
The Kepler kernels can be obtained from MAST:
https://archive.stsci.edu/missions/kepler/spice/
The K2 kernels can be obtained from MAST:
https://archive.stsci.edu/missions/k2/spice/ The
TESS kernels can be obtained from MAST:
https://archive.stsci.edu/missions/tess/engineering/
https://archive.stsci.edu/missions/tess/models/
When you first load `lkspacecraft` into Python all the kernels will be downloaded for you. This will take approximately 5 minutes, depending on your internet connection. Once this has been done, the kernels will be cached. If there are new TESS kernels available `lkspacecraft` will retrieve them for you and update the cache.
The total file volume for the kernels is ~1GB. These cached files are stored using `astropy`'s cache. If you want to clear the cache you can do either of the following;
.. code-block:: python
from lkspacecraft.utils import clear_download_cache
clear_download_cache()
.. code-block:: python
from astropy.utils.data import clear_download_cache
clear_download_cache(pkgname='lkspacecraft')
Extending ``lkspacecraft``
~~~~~~~~~~~~~~~~~~~~~~~~~~
If you wanted to extend ``lkspacecraft`` to include more spacecraft you would
need to include more kernels in the kernel directory and ensure they are
added to the meta kernel. You can then create a new class in the
``spacecraft.py`` module with the correct NAIF code.
Caveats
-------
Velocity Aberration vs. Differential Velocity Aberration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This package will provide you **velocity aberration**. However, each of
these spacecrafts repoint during observations to account for the bulk
offset of velocity aberration. If you are interested in where stars will
fall on pixels, you should consider calculating the **differential
velocity aberration**.
Spacecraft Time
~~~~~~~~~~~~~~~
This package assumes you will provide time as the time **at the
spacecraft**. For SPOC products, this is the time in the ``'TIME'``
column of any fits file, with the time corrections from ``TIME_CORR``
subtracted. i.e.
.. code-block:: python
t = np.asarray(hdulist[1].data['TIME'], dtype=float)
tcorr = np.asarray(hdulist[1].data['TIMECORR'], dtype=float)
# Spacecraft time:
t -= tcorr
If you are trying to accurately calculate time corrections, it is
important you use the spacecraft time in all functions.
.. <!-- intro content end -->
.. <!-- quickstart content start -->
The easiest way to install ``lkspacecraft`` and all of its dependencies is to use the ``pip`` command,
which is a standard part of all Python distributions. (upon release)
To install ``lkspacecraft``, run the following command in a terminal window:
.. code-block:: console
$ python -m pip install lkspacecraft --upgrade
The ``--upgrade`` flag is optional, but recommended if you already
have ``lkspacecraft`` installed and want to upgrade to the latest version.
You can use `lkspacecraft` to access position and velocity information of Kepler and TESS using input times
.. code-block:: python
from lkspacecraft import KeplerSpacecraft
ks = KeplerSpacecraft()
t = Time("2009-04-06 06:22:56.000025")
ks.get_velocity_aberrated_positions(time=t, ra=290.666, dec=44.5)
.. <!-- quickstart content end -->
.. <!-- Contributing content start -->
Contributing
============
``lkspacecraft`` is an open-source, community driven package.
We welcome users to contribute and develop new features for ``lkspacecraft``.
For further information, please see the `Lightkurve Community guidelines <https://docs.lightkurve.org/development/contributing.html>`_.
.. <!-- Contributing content end -->
.. <!-- Citing content start -->
Citing
======
If you find ``lkspacecraft`` useful in your research, please cite it and give us a GitHub star!
If you use Lightkurve for work or research presented in a publication, we request the following acknowledgment or citation:
`This research made use of Lightkurve, a Python package for Kepler and TESS data analysis (Lightkurve Collaboration, 2018).`
See full citation instuctions, including dependencies, in the `Lightkurve documentation <https://docs.lightkurve.org/about/citing.html>`_.
.. <!-- Citing content end -->
.. <!-- Contact content start -->
Contact
=======
``lkspacecraft`` is an open source community project created by the `TESS Science Support Center`_. The best way to contact us is to `open an issue`_ or to e-mail tesshelp@bigbang.gsfc.nasa.gov.
.. _`TESS Science Support Center`: https://heasarc.gsfc.nasa.gov/docs/tess/
.. _`open an issue`: https://github.com/lightkurve/lksearch/issues/new
Please include a self-contained example that fully demonstrates your problem or question.
.. <!-- Contact content end -->
License
=======
This project is licensed under the MIT License. See the LICENSE file for
details.
.. <!-- Changelog content start -->
Changelog:
==========
v1.0.5
- Added a function for calculating DVA
v1.0.4
- Made Python version >=3.9 compliant
v1.0.3
- Added ability to calculate velocity aberration on an array of RA/Decs.
- Added ability to calculate barycentric time correction on an array of RA/Decs.
v1.0.0
- First version
.. <!-- Changelog content end -->
Raw data
{
"_id": null,
"home_page": null,
"name": "lkspacecraft",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Christina Hedges",
"author_email": "christina.l.hedges@nasa.gov",
"download_url": "https://files.pythonhosted.org/packages/ef/cb/f836c67bb178151803442e6c046cf50e329f2e70d83ecfd945311aa49fd6/lkspacecraft-1.0.5.tar.gz",
"platform": null,
"description": ".. image:: https://github.com/lightkurve/lkspacecraft/actions/workflows/pytest.yml/badge.svg\n :target: https://github.com/lightkurve/lkspacecraft/actions/workflows/pytest.yml\n :alt: Test status\n\n.. image:: https://badge.fury.io/py/lkspacecraft.svg\n :target: https://badge.fury.io/py/lkspacecraft\n :alt: PyPI version\n\n.. image:: https://img.shields.io/badge/documentation-live-blue.svg\n :target: https://lightkurve.github.io/lkspacecraft/\n :alt: Documentation\n\n\nlkspacecraft\n============\n\n.. <!-- intro content start -->\n\nThis package provides a way to access the orbital parameters for the\nKepler and TESS spacecrafts. This will enable you to access\n\n1. Spacecraft position at any given time with respect to the solar\n system barycenter, the earth, or the moon\n2. Spacecraft velocity at any given time with respect to the solar\n system barycenter, the earth, or the moon\n3. The baycentric time correction for any target RA/Dec at any time\n4. The velocity aberration for any target RA/Dec at any time\n\n\n\n.. image:: https://raw.githubusercontent.com/lightkurve/lkspacecraft/main/docs/images/tess_wrt_earth.png\n :width: 400px\n :alt: TESS position with respect to the earth.\n\nRequirements\n------------\n\nThis package relies heavily on\n`spiceypy <https://github.com/AndrewAnnex/SpiceyPy>`__ which wraps\n`SPICE <https://naif.jpl.nasa.gov/naif/toolkit.html>`__. It also relies\non `astropy <https://www.astropy.org/>`__.\n\nInstallation\n------------\n\nYou can install this package with ``pip`` using\n\n.. code-block:: console\n\n pip install lkspacecraft --upgrade\n\nYou can also install this package by cloning the repo and then\ninstalling via poetry\n\n.. code-block:: console\n\n git clone https://github.com/lightkurve/lkspacecraft.git\n cd lkspacecraft\n pip install --upgrade poetry\n poetry install .\n\n\nUsage\n-----\n\n``lkspacecraft`` provides ``Spacecraft`` object which will enable you to\naccess the orbital parameters of either the Kepler or TESS spacecraft.\n``lkspacecraft`` will obtain the relevant SPICE kernels to calculate the\nspacecraft position and velocity. To get the orbital elements you will\nneed to pick a time that is within the relevant window of those SPICE\nkernels (i.e.\u00a0when the mission was operational).\n\nYou can find the start and end times of the kernels using the following\n\n.. code-block:: python\n\n from lkspacecraft import KeplerSpacecraft\n\n ks = KeplerSpacecraft()\n ks.start_time, ks.end_time\n\nAll times in ``lkspacecraft`` use ``astropy.time.Time`` objects. Using the\n``get_spacecraft_position`` or ``get_spacecraft_velocity`` functions\nwill provide you with the position or velocity in cartesian coordinates,\nfor example\n\n.. code-block:: python\n\n from lkspacecraft import KeplerSpacecraft\n from astropy.time import Time\n\n ks = KeplerSpacecraft()\n t = Time(\"2009-04-06 06:22:56.000025\")\n ks.get_spacecraft_velocity(t)\n\nwill result in\n\n::\n\n array([[ 6.94188023, -26.24714425, -11.16828662]])\n\nThis will give the velocity with respect to the solar system barycenter\nby default, but you can specify the earth or moon using\n\n.. code-block:: python\n\n from lkspacecraft import KeplerSpacecraft\n from astropy.time import Time\n\n ks = KeplerSpacecraft()\n t = Time(\"2009-04-06 06:22:56.000025\")\n ks.get_spacecraft_velocity(time=t, observer=\"earth\")\n\nYou are able to calculate the light arrival time of observations of a\nsource at a given RA/Dec using ``lkspacecraft``\\ \u2019s\n``get_barycentric_time_correction`` function. This will give you the\ntime delay in seconds from spacecraft time to time at the barycenter.\n\n.. code-block:: python\n\n from lkspacecraft import KeplerSpacecraft\n from astropy.time import Time\n\n ks = KeplerSpacecraft()\n t = Time(\"2009-04-06 06:22:56.000025\")\n ks.get_barycentric_time_correction(time=t, ra=290.666, dec=44.5)\n\nFinally you can calculate velocity aberration using\n\n.. code-block:: python\n\n from lkspacecraft import KeplerSpacecraft\n from astropy.time import Time\n\n ks = KeplerSpacecraft()\n t = Time(\"2009-04-06 06:22:56.000025\")\n ks.get_velocity_aberrated_positions(time=t, ra=290.666, dec=44.5)\n\nUnits\n~~~~~\n\nIn ``lkspacecraft``, just as in ``SPICE``, units are ``km`` and ``s``, unless\notherwise specified.\n\nKernels\n-------\n\n``lkspacecraft`` will obtain the SPICE kernels for Kepler and TESS for you\nstore them. Kernels can be found here:\n\nThe generic kernels can be obtained from NAIF generic kernels:\nhttps://naif.jpl.nasa.gov/pub/naif/generic_kernels/\nThe Kepler kernels can be obtained from MAST:\nhttps://archive.stsci.edu/missions/kepler/spice/ \nThe K2 kernels can be obtained from MAST: \nhttps://archive.stsci.edu/missions/k2/spice/ The\nTESS kernels can be obtained from MAST:\nhttps://archive.stsci.edu/missions/tess/engineering/\nhttps://archive.stsci.edu/missions/tess/models/\n\nWhen you first load `lkspacecraft` into Python all the kernels will be downloaded for you. This will take approximately 5 minutes, depending on your internet connection. Once this has been done, the kernels will be cached. If there are new TESS kernels available `lkspacecraft` will retrieve them for you and update the cache. \n\nThe total file volume for the kernels is ~1GB. These cached files are stored using `astropy`'s cache. If you want to clear the cache you can do either of the following;\n\n.. code-block:: python\n\n from lkspacecraft.utils import clear_download_cache\n clear_download_cache()\n \n.. code-block:: python\n\n from astropy.utils.data import clear_download_cache\n clear_download_cache(pkgname='lkspacecraft')\n\n\n\nExtending ``lkspacecraft``\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nIf you wanted to extend ``lkspacecraft`` to include more spacecraft you would\nneed to include more kernels in the kernel directory and ensure they are\nadded to the meta kernel. You can then create a new class in the\n``spacecraft.py`` module with the correct NAIF code.\n\nCaveats\n-------\n\nVelocity Aberration vs.\u00a0Differential Velocity Aberration\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThis package will provide you **velocity aberration**. However, each of\nthese spacecrafts repoint during observations to account for the bulk\noffset of velocity aberration. If you are interested in where stars will\nfall on pixels, you should consider calculating the **differential\nvelocity aberration**.\n\nSpacecraft Time\n~~~~~~~~~~~~~~~\n\nThis package assumes you will provide time as the time **at the\nspacecraft**. For SPOC products, this is the time in the ``'TIME'``\ncolumn of any fits file, with the time corrections from ``TIME_CORR``\nsubtracted. i.e.\n\n.. code-block:: python\n\n t = np.asarray(hdulist[1].data['TIME'], dtype=float)\n tcorr = np.asarray(hdulist[1].data['TIMECORR'], dtype=float)\n # Spacecraft time:\n t -= tcorr\n\nIf you are trying to accurately calculate time corrections, it is\nimportant you use the spacecraft time in all functions.\n\n\n.. <!-- intro content end -->\n\n.. <!-- quickstart content start -->\n\n\nThe easiest way to install ``lkspacecraft`` and all of its dependencies is to use the ``pip`` command,\nwhich is a standard part of all Python distributions. (upon release)\n\nTo install ``lkspacecraft``, run the following command in a terminal window:\n\n.. code-block:: console\n\n $ python -m pip install lkspacecraft --upgrade\n\nThe ``--upgrade`` flag is optional, but recommended if you already\nhave ``lkspacecraft`` installed and want to upgrade to the latest version.\n\nYou can use `lkspacecraft` to access position and velocity information of Kepler and TESS using input times\n\n.. code-block:: python\n\n from lkspacecraft import KeplerSpacecraft\n ks = KeplerSpacecraft()\n t = Time(\"2009-04-06 06:22:56.000025\")\n ks.get_velocity_aberrated_positions(time=t, ra=290.666, dec=44.5)\n\n.. <!-- quickstart content end -->\n\n.. <!-- Contributing content start -->\n\nContributing\n============\n\n``lkspacecraft`` is an open-source, community driven package. \nWe welcome users to contribute and develop new features for ``lkspacecraft``. \n\nFor further information, please see the `Lightkurve Community guidelines <https://docs.lightkurve.org/development/contributing.html>`_.\n\n.. <!-- Contributing content end -->\n\n.. <!-- Citing content start -->\n\nCiting\n======\n\nIf you find ``lkspacecraft`` useful in your research, please cite it and give us a GitHub star!\n\nIf you use Lightkurve for work or research presented in a publication, we request the following acknowledgment or citation:\n\n`This research made use of Lightkurve, a Python package for Kepler and TESS data analysis (Lightkurve Collaboration, 2018).`\n\nSee full citation instuctions, including dependencies, in the `Lightkurve documentation <https://docs.lightkurve.org/about/citing.html>`_. \n\n.. <!-- Citing content end -->\n\n.. <!-- Contact content start -->\n\nContact\n=======\n\n``lkspacecraft`` is an open source community project created by the `TESS Science Support Center`_. The best way to contact us is to `open an issue`_ or to e-mail tesshelp@bigbang.gsfc.nasa.gov.\n \n .. _`TESS Science Support Center`: https://heasarc.gsfc.nasa.gov/docs/tess/\n \n .. _`open an issue`: https://github.com/lightkurve/lksearch/issues/new\n\nPlease include a self-contained example that fully demonstrates your problem or question.\n\n\n.. <!-- Contact content end -->\n\nLicense\n=======\n\nThis project is licensed under the MIT License. See the LICENSE file for\ndetails.\n\n.. <!-- Changelog content start -->\n\nChangelog:\n==========\nv1.0.5\n - Added a function for calculating DVA\nv1.0.4\n - Made Python version >=3.9 compliant\nv1.0.3\n - Added ability to calculate velocity aberration on an array of RA/Decs.\n - Added ability to calculate barycentric time correction on an array of RA/Decs.\nv1.0.0\n - First version\n\n.. <!-- Changelog content end -->",
"bugtrack_url": null,
"license": null,
"summary": null,
"version": "1.0.5",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b60d2adb36f0e76cef3b6fdee378e23d40c8cd8f095d961a3d4af6936c011c0c",
"md5": "576c1d576459b308910ed7b6d0c8c165",
"sha256": "30710c32c64b081c22a3f0b3373d1cdaf9a3b6a8e24807891f5790b26c798b16"
},
"downloads": -1,
"filename": "lkspacecraft-1.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "576c1d576459b308910ed7b6d0c8c165",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 12179,
"upload_time": "2025-01-13T16:13:28",
"upload_time_iso_8601": "2025-01-13T16:13:28.027096Z",
"url": "https://files.pythonhosted.org/packages/b6/0d/2adb36f0e76cef3b6fdee378e23d40c8cd8f095d961a3d4af6936c011c0c/lkspacecraft-1.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "efcbf836c67bb178151803442e6c046cf50e329f2e70d83ecfd945311aa49fd6",
"md5": "a57c87ee7ef9b58a7543d7a40129f84c",
"sha256": "0f6bbdc85215b48b673699a5cf1cc6e1805e89bed9e157071457283a1d739d49"
},
"downloads": -1,
"filename": "lkspacecraft-1.0.5.tar.gz",
"has_sig": false,
"md5_digest": "a57c87ee7ef9b58a7543d7a40129f84c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 13833,
"upload_time": "2025-01-13T16:13:29",
"upload_time_iso_8601": "2025-01-13T16:13:29.076522Z",
"url": "https://files.pythonhosted.org/packages/ef/cb/f836c67bb178151803442e6c046cf50e329f2e70d83ecfd945311aa49fd6/lkspacecraft-1.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-13 16:13:29",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "lkspacecraft"
}
