🐷 Susie Special Timing Object Usage#

🔵 Import the necessary python libraries and Susie objects.

import numpy as np
import pandas as pd
from susie.timing_data import TimingData

🔵 Other Timing Data Formats and Options#

The default option (shown in the example above) for timing data:

  • Is in JD TDB timing format and system

  • Includes mid-time uncertainties

  • Includes both transits AND occultations

However, there are a number of options you have for creating timing objects. A few include:

  • Timing formats and systems different from JD TDB. For example, you can specify that your data is in JD with UTC timing system. If you do not specify the timing system, the code will default to UTC and will automatically correct for barycentric light travel time.

    NOTE: If you choose to specify a different timing format and/or systems, or if you choose not to specify the timing system, REMEMBER the code will automatically convert your time to JD TDB timing format and system. If this happens, you will need to include some additional information including the position of your object in the sky (in RA and Dec) and the position of your observing location on Earth (in longitude and latitude). You ARE REQUIRED to input the coordinates of your object. You ARE NOT REQUIRED to specify your location on Earth, but this will generate a default position on Earth that corresponds to the North Pole.

  • No mid-time uncertainties. In this case, a placeholder list of 1s will be generated for functional purposes.

  • No list specifying transits and occultations. If you do not include a list specifying if the data included is a transit or occultation (this will be the tra_or_occ parameter), then the code defaults to transits and will generate a list of ‘tra’ that has a number of values equal to the number of values of your epochs array.

Below are examples of how these options would work.

🔷 Download the example timing data (includes transit and occultation data in Barycentric Julian Date) from the GitHub repository#

url = 'https://raw.githubusercontent.com/BoiseStatePlanetary/susie/main/example_data/wasp12b_tra_occ.csv'

# Read the CSV file directly from the URL
data = pd.read_csv(url)
tra_or_occs = np.array(data["tra_or_occ"])
epochs = np.array(data["epoch"].astype('int'))
mid_times = np.array(data["mid_time"])
mid_time_errs = np.array(data["mid_time_err"])

🔷 Using Timing Data that is NOT in JD TDB Format and/or System#

Using timing data that is not corrected for barcentric light travel time and is in a timing format and system other than JD TDB. For example, we will assume this data is in the JD timing format with the UTC time scale.

NOTE: If you do not include a timing system parameter when you create the TimingData object, it will default to UTC and correct for barycentric light travel time

🔹 Option 1: Including BOTH Object Coordinates and Observatory Coordinates#

For this example, we show creating the object:

  • WITHOUT specifying the timing system, which will default to UTC

  • WITH specifying the timing system as UTC

Note: These will both be the exact same because if the object is not given a timing system, it will default to UTC.

We also include positional data for both:

  • the object coordinates, which includes the right ascension and declination of WASP 12-b

  • the location of the observatory, which includes the latitude and longitude of the Boise State observatory.

Note: This data was not collected from the BSU observatory, we just use this as an example. Also note, this data is already corrected for barycentric light travel time, so the resulting data is not actually correct. This is JUST AN EXAMPLE. 

# Not including time scale. Will default to UTC
timing_obj2 = TimingData('jd', epochs, mid_times, mid_time_uncertainties=mid_time_errs, object_ra=97.64, object_dec=29.67, observatory_lat=43.60, observatory_lon=-116.21)
# OR including time scale as UTC
timing_obj2 = TimingData('jd', epochs, mid_times, mid_time_uncertainties=mid_time_errs, time_scale='utc', object_ra=97.64, object_dec=29.67, observatory_lat=43.60, observatory_lon=-116.21)

WARNING: Recieved time format jd and time scale None. Correcting all times to BJD timing system with TDB time scale. If no time scale is given, default is automatically assigned to UTC. If this is incorrect, please set the time format and time scale for TransitTime object.

WARNING: Using ICRS coordinates in degrees of RA and Dec (np.float64(97.64), np.float64(29.67)) for time correction. Using geodetic Earth coordinates in degrees of longitude and latitude (np.float64(-116.21), np.float64(43.6)) for time correction.

WARNING: Recieved time format jd and time scale utc. Correcting all times to BJD timing system with TDB time scale. If no time scale is given, default is automatically assigned to UTC. If this is incorrect, please set the time format and time scale for TransitTime object.

WARNING: Using ICRS coordinates in degrees of RA and Dec (np.float64(97.64), np.float64(29.67)) for time correction. Using geodetic Earth coordinates in degrees of longitude and latitude (np.float64(-116.21), np.float64(43.6)) for time correction.

Now the TimingData object contains the corrected mid-times and mid-time uncertainties. To see these corrected values, you can print the variables of the object by running the code below.

# Uncomment this ↓↓↓↓ to see the real data!

# for key, value in vars(timing_obj2).items():
#     print(f"{key}: {value}\n")

🔹 Option 2: Including ONLY Object Coordinates#

We can also opt to not include any observatory coordinates (due to not knowing where to data was taken, for example). If this is not passed in, the object will default to the gravitational center of the Earth at x=0, y=0, z=0.

We include positional data for the object coordinates, which includes the right ascension and declination of WASP 12-b.

Note: This data is already corrected for barycentric light travel time, so the resulting data is not actually correct. This is JUST AN EXAMPLE.

Don’t be scared of the warnings! These are just warnings, nothing is wrong.

# Including time scale as UTC. NOT passing in observatory coordinates
timing_obj3 = TimingData('jd', epochs, mid_times, mid_time_uncertainties=mid_time_errs, time_scale='utc', object_ra=97.64, object_dec=29.67)

WARNING: Recieved time format jd and time scale utc. Correcting all times to BJD timing system with TDB time scale. If no time scale is given, default is automatically assigned to UTC. If this is incorrect, please set the time format and time scale for TransitTime object.

WARNING: Unable to process observatory coordinates (None, None). Using gravitational center of Earth.

WARNING: Using ICRS coordinates in degrees of RA and Dec (np.float64(97.64), np.float64(29.67)) for time correction. Using geodetic Earth coordinates in degrees of longitude and latitude (np.float64(0.0), np.float64(90.0)) for time correction.

# Uncomment this ↓↓↓↓ to see the real data!

# for key, value in vars(timing_obj3).items():
#     print(f"{key}: {value}\n")

🔷 Using Timing Data that does NOT include uncertainties#

We do not have to include uncertainties for our mid-time data. If no uncertainties are given, the object will generate a default placeholder of 1’s with the same number of values that are in your epochs array.

# Create new transit times object with above data
timing_obj4 = TimingData('jd', epochs, mid_times, time_scale='tdb')

WARNING: Recieved value of None for mid time uncertainties. Auto-populating placeholder values of 0.001 for uncertainties.

# Uncomment this ↓↓↓↓ to see the real data!

# for key, value in vars(timing_obj4).items():
#     print(f"{key}: {value}\n")

🔷 Using Timing Data that does NOT include a transit or occultation array#

We also do not need to include a tra_or_occ array. For example, if you only have transit data, you most likely would not include a tra_or_occ array because all of your data are transits. If we do not provide an array for tra_or_occ, then the object will generate a default placeholder of ‘tra’ with the same number of values that are in your epochs array.

# Create new transit times object with above data
timing_obj5 = TimingData('jd', epochs, mid_times, mid_time_uncertainties=mid_time_errs, time_scale='tdb')

# Uncomment this ↓↓↓↓ to see the real data!

# for key, value in vars(timing_obj5).items():
#     print(f"{key}: {value}\n")

There are many different ways to create your TimingData object. Once you have created the TimingData object with as much information as you can provide, continue with the 🔵 Basic Usage workflow tutorial.