User Guide#

Timing Data module#

class src.susie.timing_data.TimingData(time_format, epochs, mid_times, mid_time_uncertainties=None, tra_or_occ=None, time_scale=None, object_ra=None, object_dec=None, observatory_lon=None, observatory_lat=None)[source]#

Bases: object

Represents timing mid-point data over observations. Holds data to be accessed by Ephemeris.

This object processes, formats, and holds user data to be passed to the Ephemeris object. Users can input observational data as lists of transit and/or occultation mid-times and corresponding epochs and (if available) mid-time uncertainties.

Timing conversions are applied to ensure that all data is processed correctly and users are aware of timing formats and scales, which can give rise to false calculations in our metrics. If data is not specified to be in Barycentric Julian Date format with the TDB time scale, timing data will be corrected for barycentric light travel time using the Astropy Time utilities. If correction is needed, users will be required to provide additional information on the observed object.

If mid time uncertainties are not provided, we will generate placeholder values of 1.

Our implementations rely on Numpy functions. This object implements checks to ensure that data are stored in Numpy arrays and are of correct data types. The appropriate Type or Value Error is raised if there are any issues.

All timing data arrays will be sorted by ascending epoch. Epochs are shifted to start at zero by subtracting the minimum number from each value.

Parameters:

  • time_format (str) – An abbreviation of the data’s time system. Abbreviations for systems can be found on [Astropy’s Time documentation](https://docs.astropy.org/en/stable/time/#id3).

  • epochs (numpy.ndarray[int]) – List of orbit number reference points for timing observations

  • mid_times (numpy.ndarray[float]) – List of observed timing mid points corresponding with epochs, in timing units given by time_format.

  • mid_time_uncertainties (Optional(numpy.ndarray[float])) – List of uncertainties corresponding to timing mid points, in timing units given by time_format. If given None, will be replaced with array of 1’s with same shape as mid_times.

  • tra_or_occ (Optional(numpy.ndarray[str])) – List of either tra or occ which specifies if observational data was taken from a transit or an occultation.

  • time_scale (Optional(str)) – An abbreviation of the data’s time scale. Abbreviations for scales can be found on [Astropy’s Time documentation](https://docs.astropy.org/en/stable/time/#id6).

  • object_ra (Optional(float)) – The right ascension of observed object represented by data, in degrees

  • object_dec (Optional(float)) – The declination of observed object represented by data, in degrees

  • observatory_lon (Optional(float)) – The longitude of observatory data was collected from, in degrees

  • observatory_lat (Optional(float)) – The latitude of observatory data was collected from, in degrees

Raises:

  • TypeError: –

    • If epochs, mid_times, mid_time_uncertainties, and/or tra_or_occs are not Numpy arrays. - If epochs contain any non-int values. - If mid_times and/or mid_time_uncertainties contain any non-float values.

  • ValueError: –

    • If epochs, mid_times, mid_time_uncertainties, and/or tra_or_occs do not have the same amount of data (the arrays do not have the same shape). - If tra_or_occ contains any values that are not ‘tra’ or ‘occ’. - If mid_times or mid_time_uncertainties contain any NaN values. - If mid_time_uncertainties contain any negative or zero values.

Ephemeris module#

class src.susie.ephemeris.Ephemeris(timing_data)[source]#

Bases: object

Represents the fit model using transit or occultation mid-time data over epochs.

Parameters:

timing_data (TimingData obj) – A successfully instantiated TimingData object holding epochs, mid-times, and uncertainties.

Raises:

ValueError: – Raised if timing_data is not an instance of the TimingData object.

fit_model(model_type, **kwargs)[source]#

Fits the timing data to a specified model using an LMFIT Model.fit() method.

This function selects and fits one of three supported orbital models—linear, quadratic, or precession— to mid-time exoplanet data using non-linear least squares optimization.

Parameters:

model_type (str) – The type of model to fit. Must be one of: - ‘linear’: Constant-period orbital model. - ‘quadratic’: Linear model with a period change (e.g., tidal decay). - ‘precession’: Model including apsidal precession.

Keyword Arguments:

init_params (dict, optional) –

Dictionary of initial parameter guesses to seed the fit. Required keys depend on the model type:

For ‘linear’:

  • ’period’ (float): Estimated orbital period (in days).

  • ’conjunction_time’ (float): Reference time of mid-transit or occultation.

For ‘quadratic’:

  • All ‘linear’ parameters.

  • ’decay_rate’ (float): Change in period per epoch (in days/epoch).

For ‘precession’:

  • All ‘linear’ parameters.

  • ’eccentricity’ (float): Orbital eccentricity (unitless).

  • ’pericenter’ (float): Argument of pericenter (in radians).

  • ’precession_rate’ (float): Rate of pericenter precession per epoch (in radians/epoch).

Returns:

model_data – Dictionary of best-fit parameters from the model, including:

Common to all models:

  • ’model_type’: Name of the model used (‘linear’, ‘quadratic’, or ‘precession’).

  • ’model_data’: Array of predicted mid-times using best-fit parameters.

  • ’period’, ‘period_err’: Fitted orbital period and its uncertainty.

  • ’conjunction_time’, ‘conjunction_time_err’: Fitted time of conjunction and its uncertainty.

Additional for ‘quadratic’:

  • ’period_change_by_epoch’, ‘period_change_by_epoch_err’: Rate of period change per epoch and its uncertainty.

Additional for ‘precession’:

  • ’eccentricity’, ‘eccentricity_err’

  • ’pericenter’, ‘pericenter_err’

  • ’pericenter_change_by_epoch’, ‘pericenter_change_by_epoch_err’: Precession rate and its uncertainty.

Return type:

dict

get_model_uncertainties(model_data)[source]#

Calculates the mid-time uncertainties of specific model data when compared to the actual data.

Calculate the uncertainties between the model data and actual data over epochs using the equations…

For a linear model:

  • \(\sigma(\text{t pred, tra}) = \sqrt{(\sigma(T_0)^2 + \sigma(P)^2 * E^2)}\) for transit observations

  • \(\sigma(\text{t pred, tra}) = \sqrt{(\sigma(T_0)^2 + \sigma(P)^2 * (\frac{1}{2} + E)^2)}\) for occultation observations

For a quadratic model:

  • \(\sigma(\text{t pred, tra}) = \sqrt{(\sigma(T_0)^2 + (\sigma(P)^2 * E^2) + (\frac{1}{4} * \sigma(\frac{dP}{dE})^2 * E^4))}\) for transit observations

  • \(\sigma(\text{t pred, tra}) = \sqrt{(\sigma(T_0)^2 + (\sigma(P)^2 * (\frac{1}{2} + E^2)) + (\frac{1}{4} * \sigma(\frac{dP}{dE})^2 * E^4))}\) for occultation observations

where \(\sigma(T_0) =\) conjunction time error, \(E=\) epoch, \(\sigma(P)=\) period error, and \(\sigma(\frac{dP}{dE})=\) period change with respect to epoch error.

Parameters:

model_data (dict) – The model data dictionary recieved from the fit_model method.

Returns:

  • A list of mid-time uncertainties associated with the model passed in, calculated with the

  • equation above and the TimingData epochs.

Raises:

  • KeyError – If the model type in not in the model parameter dictionary.

  • KeyError – If the model parameter error values are not in the model parameter dictionary.

calc_bic(model_data)[source]#

Calculates the BIC value for a given model.

The BIC value is a modified \(\chi^2\) value that penalizes for additional parameters. Uses the equation \(BIC = \chi^2 + (k * log(N))\) where \(\chi^2=\sum{\frac{(\text{ observed midtimes - model midtimes})}{\text{(observed midtime uncertainties})^2}},\) k=number of fit parameters (2 for linear ephemerides, 3 for quadratic ephemerides, 5 for precession ephemerides), and N=total number of data points.

Parameters:

model_data (dict) – The model data dictionary recieved from the fit_model method.

Return type:

A float value representing the BIC value for this model.

calc_delta_bic(model1='linear', model2='quadratic')[source]#

Calculates the \(\Delta BIC\) value between linear and quadratic ephemerides using the given timing data.

model1 BIC value - model2 BIC value, default of linear - quadratic BIC values.

The BIC value is a modified \(\chi^2\) value that penalizes for additional parameters. The \(\Delta BIC\) value is the difference between the linear BIC value and the quadratic BIC value. Ephemerides that have smaller values of BIC are favored. Therefore, if the \(\Delta BIC\) value for your data is a large positive number (large linear BIC - small quadratic BIC), a quadratic model is favored and your data indicates possible orbital decay in your extrasolar system. If the \(\Delta BIC\) value for your data is a small number or negative (small linear BIC - large quadratic BIC), then a linear model is favored and your data may not indicate orbital decay.

This function will run all model instantiation and BIC calculations for you using the TimingData information you entered.

Parameters:

  • model1 (str) – This is the name of the first model.

  • model2 (str) – This is the name of second model, whose BIC value will be subtracted from the first.

Returns:

delta_bic – Represents the \(\Delta BIC\) value for this timing data.

Return type:

float

create_observer_obj(timezone, name, longitude=None, latitude=None, elevation=0.0)[source]#

Creates the Astroplan Observer object.

Parameters:

  • timezone (str) – The local timezone. If a string, it will be passed through pytz.timezone() to produce the timezone object.

  • name (str) – The name of the observer’s location. This can either be a registered Astropy site name (get the latest site names with EarthLocation.get_site_names()), which will return the latitude, longitude, and elevation of the site OR it can be a custom name to keep track of your Observer object.

  • latitude (float (Optional)) – The latitude of the observer’s location on Earth.

  • longitude (float (Optional)) – The longitude of the observer’s location on Earth.

  • elevation (float (Optional)) – The elevation of the observer’s location on Earth.

Return type:

The Astroplan Observer object.

Raises:

ValueError if neither coords nor name are given. –

create_target_obj(name, ra=None, dec=None)[source]#

Creates the Astroplan FixedTarget object.

Parameters:

  • coords (tuple(float, float) (Optional)) – The right ascension and declination of the object in the sky (most likely the planet’s host star).

  • name (str) – The name of the exoplanet host star. This can either be a registered object name, which will query a CDS name resolver (see the Astroplan Target Documentation for more information on this) OR it can be a custom name to keep track of your FixedTarget object.

  • ra (float (Optional)) – The right ascension of the object to observe in the sky (most likely a planet or star).

  • dec (float (Optional)) – The declination of the object to observe in the sky (most likely a planet or star).

Return type:

The Astroplan FixedTarget object.

Raises:

ValueError if neither coords nor name are given. –

get_observing_schedule(model_data, timezone, observer, target, n_transits, n_occultations, obs_start_time, exoplanet_name=None, eclipse_duration=None, csv_filename=None)[source]#

Returns a list of observable future transits for the target object

Parameters:

  • model_data (dict) – The model data dictionary recieved from the fit_model method.

  • timezone (str) – The local timezone. If a string, it will be passed through pytz.timezone() to produce the timezone object.

  • observer (Astroplan Observer obj) – An Astroplan Observer object holding information on the observer’s Earth location. Can be created through the create_observer_obj method, or can be manually created. See the Astroplan Observer Documentation for more information.

  • target (Astroplan FixedTarget obj) –

    An Astroplan FixedTarget object holding information on the object observed. Can be created through the create_target_obj method, or can be manually created. See the Astroplan Target Documentation for more information.

  • n_transits (int) – The number of transits to initially request. This will be filtered down by what is observable from the Earth location.

  • n_occultations (int) – The number of occultations to initially request. This will be filtered down by what is observable from the Earth location.

  • obs_start_time (str) – Time at which you would like to start looking for eclipse events. In the format YYYY-MM-DD. For example, if you would like to find eclipses happening after October 1st, 2024, the format would be “2024-10-01”.

  • exoplanet_name (str (Optional)) – The name of the exoplanet. Used to query the NASA Exoplanet Archive for transit duration. If no name is provided, the right ascension and declination from the FixedTarget object will be used. Can also provide the transit duration manually instead using the eclipse_duration parameter.

  • eclipse_duration (float (Optional)) – The full duration of the exoplanet transit from ingress to egress. If not given, will calculate using either provided system parameters or parameters pulled from the NASA Exoplanet Archive.

  • csv_filename (str (Optional)) – If given, will save the returned schedule dataframe as a CSV file.

plot_model(model_data, subtract_lin_params=False, show_occultations=False, save_plot=False, save_filepath=None)[source]#

Plots a scatterplot of epochs vs. model calculated mid-times.

Parameters:

  • model_data (dict) – The model data dictionary recieved from the fit_model method.

  • save_plot (bool) – If True, will save the plot as a figure.

  • save_filepath (Optional(str)) – The path used to save the plot if save_plot is True.

plot_timing_uncertainties(model_data, save_plot=False, save_filepath=None)[source]#

Plots a scatterplot of uncertainties on the fit model for each epoch.

Parameters:

  • model_data (dict) – The model data dictionary recieved from the fit_model method.

  • save_plot (bool) – If True, will save the plot as a figure.

  • save_filepath (Optional(str)) – The path used to save the plot if save_plot is True.

plot_oc_plot(model_type, save_plot=False, save_filepath=None, **kwargs)[source]#

Plots a scatter plot of observed minus calculated mid-times.

Subtracts the linear portion from the observed mid-times. The linear portion is calculated using the best-fit parameters from the given model_type.

Parameters:

  • model_type (str) – Either “quadratic” or “precession”. One of the ephemerides being compared to the linear model.

  • save_plot (bool) – If True, will save the plot as a figure.

  • save_filepath (Optional(str)) – The path used to save the plot if save_plot is True.

plot_running_delta_bic(model1, model2, save_plot=False, save_filepath=None)[source]#

Plots a scatterplot of epochs vs. \(\Delta BIC\) for each epoch.

Starting at the third epoch, will plot the value of \(\Delta BIC\) for all previous epochs, showing how the value of \(\Delta BIC\) progresses over time with more observations.

Parameters:

  • model1 (str) – Either “linear”, “quadratic”, or “precession”. One of the ephemerides being compared.

  • model2 (str) – Either “linear”, “quadratic”, or “precession”. One of the ephemerides being compared.

  • save_plot (bool) – If True, will save the plot as a figure.

  • save_filepath (Optional(str)) – The path used to save the plot if save_plot is True.

plot_delta_bic_omit_one(model1='linear', model2='quadratic', outlier_percentage=None, save_plot=False, save_filepath=None)[source]#
Parameters:

  • model1 (str)

  • model2 (str)

  • outlier_percentage (int)

  • save_plot (bool)

  • save_filepath (str)

plot_running_analytical_delta_bic_quadratic(save_plot=False, save_filepath=None)[source]#

delta_bic = 0.25(dPdE)^2 * sum(()^2) - ln(N) + 1

plot_running_analytical_delta_bic_precession(save_plot=False, save_filepath=None)[source]#

Plot the running analytical delta BIC

NOTES: Using synthetic precession data generated from Brian’s nb, Brian’s parameters:

‘period’: 1.091419633, ‘conjunction_time’: 2456305.45488, ‘eccentricity’: 0.0031, ‘pericenter’: 2.62, ‘pericenter_change_by_epoch’: 0.000984

precession model parameters:

‘period’: 1.0914194950612286, ‘conjunction_time’: 2456305.4547539037, ‘eccentricity’: 0.004492419251877544, ‘pericenter’: 3.748694994358649, ‘pericenter_change_by_epoch’: 0.0005248792790545403