update docs

Author: christinahedges

docs/tutorials/calculating-barycentric-time-correction.ipynb

@@ -108,7 +108,7 @@
    "metadata": {},
    "source": [
     "SPOC data contains two time extensions:\n",
-    "1. `TIME`: the time of the observations in Barycentric Julian Date (i.e. at the solar system barycenter)\n",
+    "1. `TIME`: the time of the observations in the Barycentric Dynamical Time scale (TDB) as a Barycentric Julian Dates (i.e. time at the solar system barycenter)\n",
     "2. `TIMECORR`: the time correction applied to the original spacecraft time, to obtain `TIME`\n",
     "\n",
     "`lksearch` only works with spacecraft time. So we need to remove the SPOC applied time correction"
@@ -299,7 +299,9 @@
    "id": "38e86c6d-ecd5-4f02-94fa-eda02601148f",
    "metadata": {},
    "source": [
-    "Looks like our correction is working!"
+    "Looks like our correction is working!\n",
+    "\n",
+    "This has given us the number of seconds to apply to convert our time at the spacecraft into TDB."
    ]
   },
   {
@@ -390,20 +392,63 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 18,
+   "execution_count": null,
    "id": "83bee026-047d-422d-a895-2ac23f373c54",
    "metadata": {},
    "outputs": [],
    "source": [
     "time, time_corr = hdulist[1].data['TIME'], hdulist[1].data['TIMECORR']\n",
     "k = np.isfinite(time)\n",
-    "time, time_corr = time[k], time_corr[k]\n",
+    "time, time_corr = time[k], time_corr[k]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "817afae7",
+   "metadata": {},
+   "source": [
+    "Note that TESS gives times in Barycentric **TESS** Julian Date which is offset from BJD by"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "a46fa67d",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ts.time_offset"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c001636d",
+   "metadata": {},
+   "source": [
+    "We calculate the time at the spacecraft using"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "53dc2eed",
+   "metadata": {},
+   "outputs": [],
+   "source": [
     "t = Time(time - time_corr + ts.time_offset, format='jd')"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "13368a28",
+   "metadata": {},
+   "source": [
+    "Now we can calculate the barycentric time correction, i.e. the number of seconds to apply to the time at the spacecraft to obtain the time at the barycenter in TDB scale."
+   ]
+  },
   {
    "cell_type": "code",
-   "execution_count": 19,
+   "execution_count": null,
    "id": "7fc89a8b-303b-43b4-9abd-144ed3bb2e1e",
    "metadata": {},
    "outputs": [
@@ -423,6 +468,14 @@
     "ts.get_barycentric_time_correction(time=t, ra=ra, dec=dec)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "191a51e8",
+   "metadata": {},
+   "source": [
+    "We can plot this against the time in the TESScut FFI to see how much of a difference this made"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 20,

src/lkspacecraft/spacecraft.py

@@ -208,13 +208,13 @@ def get_barycentric_time_correction(
     ) -> npt.NDArray:
         """Returns the barycentric time correction in days for observations of a particular target specified by RA and Dec.
 
-        Note that `time` here must be time in spacecraft time, in UTC format.
+        Note that `time` here must be the time of the spacecraft clock.
         This means that for SPOC data this should be the time without the SPOC barycentric correction applied.
 
         Parameters:
         -----------
         time: astropy.time.Time
-            Time array at which to estimate position. Time must be in UTC.
+            Time array at which to estimate position. Time must be at the spacecraft.
         ra: float, np.ndarray
             The right ascention of the target in degrees
         dec: float, np.ndarray
@@ -403,7 +403,7 @@ def get_barycentric_time_correction(
     ) -> npt.NDArray:
         """Returns the barycentric time correction in days for observations of a particular target specified by RA and Dec.
 
-        Note that `time` here must be time in spacecraft time, in UTC format.
+        Note that `time` here must be time in spacecraft clock time.
         This means that for SPOC data this should be the time without the SPOC barycentric correction applied.
 
         Note this also corrects the timing error in the Kepler TIME column, see https://archive.stsci.edu/kepler/timing_error.html
@@ -419,6 +419,10 @@ def get_barycentric_time_correction(
         """
         time = self._process_time(time)
         tcorr = super().get_barycentric_time_correction(time, ra, dec)
+        # see data release notes in https://archive.stsci.edu/missions/kepler/docs/drn/release_notes19/DataRelease_19_20130204.pdf
+        # section 3.4
+        # For Kepler the TIME column was erroneously in UTC not TDB as reported. As such it did not account for leap seconds
+        # This corrects the error in the original products
         tcorr += 66.184
         k = time.jd > Time("2012-06-30 23:59:60", format="iso").jd
         tcorr[k] += 1