tess-ephem 0.6.3
Where are Solar System objects located in TESS FFI data?
License: MIT
Requires Python: <4.0,>=3.9
Keywords: NASA, TESS, Astronomy

tess-ephem
==========


**Where are Solar System objects located in TESS FFI data?**

|pypi| |pytest| |black| |flake8| |mypy|

.. |pypi| image:: https://img.shields.io/pypi/v/tess-ephem
                :target: https://pypi.python.org/pypi/tess-ephem
.. |pytest| image:: https://github.com/SSDataLab/tess-ephem/workflows/pytest/badge.svg
.. |black| image:: https://github.com/SSDataLab/tess-ephem/workflows/black/badge.svg
.. |flake8| image:: https://github.com/SSDataLab/tess-ephem/workflows/flake8/badge.svg
.. |mypy| image:: https://github.com/SSDataLab/tess-ephem/workflows/mypy/badge.svg

``tess-ephem`` is a user-friendly package which enables users to compute the positions of Solar System objects -- asteroids, comets, and planets --
in the data archive of NASA's TESS Space Telescope.

Installation
------------

.. code-block:: bash

    python -m pip install tess-ephem


Example use
-----------

tess-ephem allows you to search the entire archive of TESS FFI's for the presence
of a known minor planet, and obtain the result as a Pandas DataFrame. The output pixel coordinates (column and row) follow the TESS convention, with (1,1) being the middle of the pixel in the lower left corner of the FFI. For example:

.. code-block:: python

    >>> from tess_ephem import ephem
    >>> ephem("Sedna")
               sector  camera  ccd       column          row     tdb-ut  pixels_per_hour        ra      dec    vmag  hmag  sun_distance  obs_distance  phase_angle
    time                                                                                                                                                          
    2458438.5       5       1    4  1543.104021  1102.948351  69.182738         0.074363  57.11724  7.64961  20.803  1.49     84.947515     83.981039       0.1450
    2458439.5       5       1    4  1544.978969  1103.000701  69.182758         0.075353  57.10692  7.64724  20.802  1.49     84.946739     83.978850       0.1423
    2458440.5       5       1    4  1546.866007  1103.027415  69.182777         0.075362  57.09651  7.64500  20.801  1.49     84.945964     83.977315       0.1403
    2458441.5       5       1    4  1548.750885  1103.040242  69.182797         0.075132  57.08610  7.64284  20.801  1.49     84.945188     83.976314       0.1394
    2458442.5       5       1    4  1550.627199  1103.044020  69.182818         0.074800  57.07573  7.64074  20.801  1.49     84.944412     83.975782       0.1394
    ...           ...     ...  ...          ...          ...        ...              ...       ...      ...     ...   ...           ...           ...          ...
    2460254.5      71       2    4  1984.578578  1003.555888  69.182570         0.072528  60.21660  8.36089  20.750  1.49     83.592715     82.661747       0.2395
    2460255.5      71       2    4  1984.808484  1001.737047  69.182584         0.072889  60.20673  8.35803  20.749  1.49     83.591992     82.656583       0.2304
    2460256.5      71       2    4  1985.037223   999.911091  69.182599         0.073002  60.19682  8.35517  20.747  1.49     83.591270     82.651896       0.2214
    2460257.5      71       2    4  1985.258387   998.084718  69.182615         0.072664  60.18690  8.35235  20.745  1.49     83.590547     82.647726       0.2127
    2460258.5      71       2    4  1985.460633   996.280013  69.182631         0.071257  60.17708  8.34965  20.744  1.49     83.589824     82.644125       0.2044

    [75 rows x 14 columns]


The ``time`` is in the UT scale. To convert this to the TDB timescale, the column ``tdb-ut`` (offset in seconds) should be used.

You can also obtain the ephemeris for one or more specific times
by passing the ``time`` parameter:

.. code-block:: python

    >>> ephem("Sedna", time="2018-11-21 17:35:00")
                             sector  camera  ccd       column          row     tdb-ut  pixels_per_hour        ra      dec    vmag  hmag  sun_distance  obs_distance  phase_angle
    time                                                                                                                                                                        
    2018-11-21 17:35:00.000       5       1    4  1553.858404  1103.035027  69.182854         0.074053  57.05786  7.63721  20.802  1.49     84.943069     83.975873       0.1419

    >>> from astropy.time import Time
    >>> ephem("Sedna", time=Time([2458441.5,2460258.5], format='jd'))
               sector  camera  ccd       column          row     tdb-ut  pixels_per_hour        ra      dec    vmag  hmag  sun_distance  obs_distance  phase_angle
    time                                                                                                                                                          
    2458441.5       5       1    4  1548.750885  1103.040242  69.182797         0.075132  57.08610  7.64284  20.801  1.49     84.945188     83.976314       0.1394
    2460258.5      71       2    4  1985.460633   996.280013  69.182631         0.071257  60.17708  8.34965  20.744  1.49     83.589824     82.644125       0.2044


Orbital elements can be obtained by passing the ``orbital_elements=True`` parameter. The function returns the average orbital elements of the target during the queried time. Perihelion distance is in AU and orbital inclination is in degrees.

.. code-block:: python

    >>> df_ephem, orbital_elements = ephem("Sedna", time="2018-11-21 17:35:00", orbital_elements=True)
    >>> orbital_elements
    {'perihelion_distance': 76.13300496827914, 'eccentricity': 0.8413468330602263, 'orbital_inclination': 11.929585189509927}


You can alternatively obtain the ephemeris during a specific sector by passing 
the ``sector`` parameter:

.. code-block:: python

    >>> ephem("Sedna", sector=70)
               sector  camera  ccd       column          row     tdb-ut  pixels_per_hour        ra      dec    vmag  hmag  sun_distance  obs_distance  phase_angle
    time                                                                                                                                                          
    2460208.5      70       4    2  1965.994639  1827.049672  69.182409         0.025550  60.53693  8.49483  20.815  1.49     83.625984     83.171959       0.6161
    2460209.5      70       4    2  1966.304467  1826.442414  69.182402         0.029493  60.53386  8.49248  20.814  1.49     83.625260     83.156129       0.6112
    2460210.5      70       4    2  1966.639579  1825.743198  69.182395         0.032766  60.53030  8.48989  20.813  1.49     83.624537     83.140186       0.6058
    2460211.5      70       4    2  1966.995717  1824.975902  69.182389         0.035144  60.52638  8.48711  20.812  1.49     83.623813     83.124437       0.6001
    2460212.5      70       4    2  1967.363962  1824.160062  69.182382         0.037045  60.52220  8.48421  20.811  1.49     83.623090     83.108950       0.5940
    2460213.5      70       4    2  1967.743247  1823.299432  69.182377         0.038666  60.51778  8.48120  20.810  1.49     83.622366     83.093746       0.5878
    2460214.5      70       4    2  1968.127856  1822.402268  69.182372         0.040092  60.51316  8.47812  20.809  1.49     83.621642     83.078838       0.5813
    2460215.5      70       4    2  1968.516359  1821.470633  69.182367         0.041354  60.50835  8.47498  20.808  1.49     83.620919     83.064240       0.5747
    2460216.5      70       4    2  1968.909479  1820.507912  69.182363         0.042441  60.50337  8.47178  20.806  1.49     83.620195     83.049971       0.5680
    2460217.5      70       4    2  1969.301139  1819.520671  69.182359         0.043287  60.49825  8.46856  20.805  1.49     83.619472     83.036058       0.5611
    2460218.5      70       4    2  1969.690629  1818.514364  69.182355         0.043699  60.49302  8.46533  20.804  1.49     83.618748     83.022538       0.5541
    2460219.5      70       4    2  1970.070096  1817.504775  69.182353         0.043112  60.48776  8.46215  20.803  1.49     83.618025     83.009457       0.5471
    2460220.5      70       4    2  1970.413447  1816.527398  69.182350         0.040265  60.48264  8.45920  20.802  1.49     83.617302     82.996750       0.5403
    2460221.5      70       4    2  1970.685594  1815.593040  69.182349         0.039919  60.47768  8.45668  20.800  1.49     83.616578     82.983656       0.5337
    2460222.5      70       4    2  1970.945096  1814.590453  69.182347         0.043872  60.47232  8.45415  20.799  1.49     83.615855     82.969867       0.5266
    2460223.5      70       4    2  1971.226319  1813.505439  69.182347         0.046801  60.46652  8.45141  20.798  1.49     83.615131     82.956089       0.5192
    2460224.5      70       4    2  1971.528584  1812.361144  69.182347         0.048934  60.46041  8.44849  20.796  1.49     83.614408     82.942565       0.5115
    2460225.5      70       4    2  1971.840095  1811.172397  69.182347         0.050643  60.45406  8.44547  20.795  1.49     83.613685     82.929353       0.5035
    2460226.5      70       4    2  1972.160145  1809.944650  69.182348         0.052095  60.44750  8.44236  20.794  1.49     83.612961     82.916471       0.4954
    2460227.5      70       4    2  1972.484084  1808.682404  69.182350         0.053363  60.44075  8.43919  20.792  1.49     83.612238     82.903932       0.4871
    2460228.5      70       4    2  1972.811565  1807.392809  69.182352         0.054473  60.43385  8.43597  20.791  1.49     83.611515     82.891750       0.4787
    2460229.5      70       4    2  1973.139007  1806.076605  69.182354         0.055414  60.42680  8.43272  20.790  1.49     83.610791     82.879944       0.4701
    2460230.5      70       4    2  1973.467494  1804.738876  69.182358         0.056123  60.41963  8.42944  20.788  1.49     83.610068     82.868542       0.4615
    2460231.5      70       4    2  1973.791305  1803.387890  69.182361         0.056414  60.41238  8.42617  20.787  1.49     83.609345     82.857585       0.4528
    2460232.5      70       4    2  1974.102222  1802.037747  69.182365         0.055711  60.40512  8.42297  20.785  1.49     83.608622     82.847125       0.4442


When passing the ``sector`` parameter, the ``time_step`` is by default 1 day. 
This can be changed as follows:

    >>> ephem("Sedna", sector=70, time_step=0.1)
               sector  camera  ccd       column          row     tdb-ut  pixels_per_hour         ra       dec       vmag  hmag  sun_distance  obs_distance  phase_angle
    time                                                                                                                                                               
    2460207.6      70       4    2  1965.698467  1827.543203  69.182416         0.026894  60.539373  8.496977  20.815973  1.49     83.626635     83.185495     0.620233
    2460207.7      70       4    2  1965.734658  1827.487317  69.182415         0.026487  60.539100  8.496720  20.816002  1.49     83.626563     83.184025     0.619771
    2460207.8      70       4    2  1965.769986  1827.432018  69.182415         0.026102  60.538829  8.496468  20.816045  1.49     83.626491     83.182549     0.619312
    2460207.9      70       4    2  1965.804410  1827.377187  69.182414         0.025764  60.538559  8.496221  20.816058  1.49     83.626418     83.181067     0.618856
    2460208.0      70       4    2  1965.837889  1827.322705  69.182413         0.025498  60.538290  8.495980  20.816000  1.49     83.626346     83.179575     0.618400
    ...           ...     ...  ...          ...          ...        ...              ...        ...       ...        ...   ...           ...           ...          ...
    2460233.0      70       4    2  1974.248380  1801.371667  69.182368         0.054524  60.401530  8.421430  20.785000  1.49     83.608260     82.842086     0.439900
    2460233.1      70       4    2  1974.275695  1801.240320  69.182368         0.054170  60.400820  8.421134  20.784886  1.49     83.608188     82.841090     0.439050
    2460233.2      70       4    2  1974.302128  1801.109815  69.182369         0.053786  60.400114  8.420844  20.784707  1.49     83.608115     82.840098     0.438204
    2460233.3      70       4    2  1974.327659  1800.980176  69.182369         0.053386  60.399412  8.420560  20.784486  1.49     83.608043     82.839105     0.437364
    2460233.4      70       4    2  1974.352268  1800.851430  69.182370         0.052985  60.398714  8.420282  20.784243  1.49     83.607971     82.838112     0.436529

    [259 rows x 14 columns]