User Guide

This is the user guide on the transitplanner code, mean to explain what each part of the code does to any individual who whishes to use it

Overview

This tool computes predicted transit times for known exoplanets, given their orbital parameters and an observing time window, using your location and telescope parameters which you input. It is intended for planning photometric observations, helping you identify which targets are observable from the given site and when their transits occur.

This guide explains each step of the workflow in more detail than the Quick Start, including input parameters, output interpretation, and recommended observing practices.

Input Parameters

TransitPlanner requires several pieces of information to be provided by the user in order compute observable targets. These are entered interactively in the CLI, but their meaning is explained here.

Longitude / Latitude

Geographic coordinates of the observatory in degrees. Positive longitude is east of Greenwich.

Telescope aperture

Diameter of the telescope in inches. Used to estimate achievable SNR.

Declination limits

Minimum and maximum declination the telescope can access.

Minimum SNR

The lowest acceptable signal-to-noise ratio for a transit to be considered observable.

Start date

Beginning of the observing window, in dd/mm/yy format.

Observation span

Number of days after the start date to search for transits.

Minimum altitude

Minimum altitude (in degrees) the target must reach during transit.

Running the CLI

TransitPlanner includes an interactive command-line interface. To launch it, run:

python -m transitplanner.cli

The program will check NASA and exoclock databases and then prompt you for observatory information such as longitude, latitude, telescope aperture, and observation constraints.

After this, the CLI will prompt you for observatory and instrument parameters. Each prompt includes validation to ensure values are within reasonable ranges.

How Targets Are Selected

TransitPlanner evaluates each known exoplanet using the following criteria:

  1. Transit occurs within the specified date range.

  2. Target is above the minimum altitude at some point during transit.

  3. Declination is within the user-defined limits.

  4. Estimated SNR exceeds the minimum threshold.

  5. Transit depth and duration are sufficient for detection with the given telescope aperture.

The result is a numbered list of all planets meeting these constraints.

Selecting a Target

Once the list of observable planets is displayed, select a target by entering its number, not its name.

For example: Enter planet number: 31

Interpreting the Output

After selecting a target, TransitPlanner provides several key quantities:

Observation Time

Total time the target remains above the minimum altitude during transit.

Predicted Duration

Expected duration of the transit in hours.

Predicted Depth

Estimated transit depth in magnitudes.

Estimated Error

Expected photometric uncertainty based on telescope aperture and target brightness.

A model light curve is also generated to illustrate the expected signal shape.

How TransitPlanner Builds the Observable Planet List

The CLI brings together several internal modules, each responsible for a different stage of the workflow. When the user enters their observing parameters, the following sequence occurs:

  1. Visibility calculation Module: core.visibility.find_observable_exoplanets This function computes which exoplanets have transits occurring within the user’s date range and are above the minimum altitude at the specified longitude and latitude. The output is a preliminary list of geometrically visible planets.

  2. Catalogue loading Modules: - io.nasa.load_nasa_data - io.exoclock.load_exoclock_data

    These functions load ephemeris and photometric data from NASA Exoplanet Archive and ExoClock. This includes period, T0, transit depth, magnitude, and duration.

  3. Data enrichment Module: observability.enrich.enrich_planets The visibility list is merged with catalogue data so each planet now has complete information needed for SNR and observability calculations.

  4. Signal-to-noise estimation Module: observability.snr.snr_formula For each planet, the expected SNR is computed using telescope aperture, transit depth, magnitude, and transit duration.

  5. Observability filtering Module: observability.filters.apply_filters Declination limits and SNR thresholds are applied. Each planet is labelled as Observable or Not Observable.

  6. Summary table generation Module: observability.summary.check_observability_table A full table of all planets (including filtered-out ones) is exported as CSV and Excel files.

  7. Light curve simulation Modules: - lightcurve.simulator.generate_lightcurve - lightcurve.plotting.plot_lightcurve

    After the user selects a planet from the observable list, a model transit light curve is generated and plotted. The CLI prints predicted duration, depth, and estimated photometric error.

Additional Notes

  • When selecting a planet, enter the number, not the name.

  • Dates must be entered in dd/mm/yy format.

  • Some transits may be excluded if ephemeris uncertainty is high.