Add sensible calculation of closest transit

stellarphot/io/tess.py

@@ -1,4 +1,5 @@
 import re
+import warnings
 from dataclasses import dataclass
 from pathlib import Path
 from tempfile import NamedTemporaryFile
@@ -356,6 +357,41 @@ def from_tic_id(cls, tic_id):
             tess_mag_error=toi_table["TESS Mag err"],
         )
 
+    def transit_time_for_observation(self, obs_times):
+        """
+        Calculate the transit time for a set of observation times.
+
+        Parameters
+        ----------
+
+        obs_times : `astropy.time.Time`
+            The times of the observations.
+
+        Returns
+        -------
+
+        `astropy.time.Time`
+            The transit times for the observations.
+        """
+        first_obs = obs_times[0]
+        # Three possible cases here. Either the first time is close to, but before, a
+        # transit, or it is close to, but just after a transit, or it is nowhere close
+        # to a transit.
+        # Assume that the first time is just before a transit
+        cycle_number = int((first_obs - self.epoch) / self.period + 1)
+        that_transit = cycle_number * self.period + self.epoch
+
+        # Check -- is the first time closer to this transit or the one before it?
+        previous_transit = that_transit - self.period
+        if abs(first_obs - previous_transit) < abs(first_obs - that_transit):
+            that_transit = previous_transit
+
+        # Check -- are we way, way, way off from a transit?
+        if abs(first_obs - that_transit) > 3 * self.duration:
+            warnings.warn("Observation times are far from a transit.", stacklevel=2)
+
+        return that_transit
+
 
 def tess_photometry_setup(tic_id=None, TOI_object=None, overwrite=False):
     """

stellarphot/io/tests/test_tess.py

@@ -3,8 +3,10 @@
 import warnings
 from pathlib import Path
 
+import numpy as np
 import pytest
 from astropy.coordinates import SkyCoord
+from astropy.time import Time
 from requests import ConnectionError, ReadTimeout
 
 from stellarphot.io.tess import (
@@ -187,6 +189,25 @@ def test_from_tic_id(self, tess_tic_expected_values):
 
         assert toi_info.coord.separation(new_toi.coord).arcsecond < 0.01
 
+    @pytest.mark.parametrize("start_before_midpoint", [True, False])
+    def test_transit_time_for_observation(self, sample_toi, start_before_midpoint):
+        # For this test we are checking that the correct transit time is identified
+        # for a given observation time.
+        # For the sake of the test, we are going to use the 124th transit of the TOI
+        # as the reference transit.
+        reference_midpoint = sample_toi.epoch + 124 * sample_toi.period
+        if start_before_midpoint:
+            # Start the observation before the midpoint (and before the transit)
+            test_time_start = Time(reference_midpoint - 0.8 * sample_toi.duration)
+        else:
+            # Start the observation after the midpoint
+            test_time_start = Time(reference_midpoint + 0.1 * sample_toi.duration)
+        obs_times = test_time_start + np.linspace(0, 2) * sample_toi.duration
+
+        assert sample_toi.transit_time_for_observation(obs_times).jd == pytest.approx(
+            reference_midpoint.jd
+        )
+
 
 class TestTessPhotometrySetup:
     # This auto-used fixture changes the working directory to the temporary directory