preface-spearnet 2.0.0b3

An Automated Pipeline for the Selection of Transmission Spectroscopy Candidates

PREFACE

Prioritization and Ranking of Exoplanets For Astronomical Characterization and Exploration (PREFACE) is a Python package for selection of promising exoplanet transmission spectroscopy observations based on their expected scientific return and observational feasibility.

---

To-do List

As this project is work in progress, here is the current to-do list:

• Fix a bug where the moonlight noise metric calculation sometimes return NaN
• Finish documentation
• (Maybe) Determine the default moonlight amplification factor that more properly and sensibly punishes full moon nights
• (Maybe) Reduce multiprocessing overhead
• (Maybe) Month- and location-dependent aerosol scattering parameters via end-to-end AERONET data retrieval

---

Installation

Install the latest stable release from PyPI:

pip install preface-spearnet

---

Usage

Using preface consists of four steps:

1. Configure the observing instrument with TelescopeConfigurations.
2. Define the observing window and output options with OutputConfigurations.
3. Optionally configure moonlight modelling and multiprocessing with MoonlightNoiseConfigurations and MultiprocessingConfigurations.
4. Execute the complete pipeline with run_preface().

Input validation is performed automatically before pipeline execution.

Full documentation (configuration reference, PREFACE workflow and output descriptions, and API) is available at preface-spearnet.readthedocs.io.

Example

import datetime as dt
from preface import run_preface
from preface.configs import (
    TelescopeConfigurations,
    OutputConfigurations,
    MoonlightNoiseConfigurations,
    MultiprocessingConfigurations,
)

ObsStart = dt.datetime(2025, 10, 1)
ObsEnd = dt.datetime(2026, 5, 31)
OutputFolder = r"C:\PREFACE_Output"

TelescopeConfigs = TelescopeConfigurations(
    instrument="TNT ULTRASPEC",
    filter_name="r",
    run_mode="Half_Well",
    toggle_sky_noise=True,
    toggle_defocus=False
)

OutputConfigs = OutputConfigurations(
    observation_start=ObsStart,
    observation_end=ObsEnd,
    output_folder=OutputFolder,
    metric_mode="Rank",
    viable_cumulative_cut=0.97
)

MoonlightConfigs = MoonlightNoiseConfigurations(
    toggle_moonlight_noise=True,
    scattering_aod=0.2,
    absorption_aod=0.3,
    asymmetry_factor=0.6,
    moonlight_amplification_factor=5,
    toggle_graph_outputs=True,
    event_weight_graph_threshold=0.75
)

MultiprocessingConfigs = MultiprocessingConfigurations(
    toggle_multiprocessing=True,
    cores_to_leave_out=2
)

run_preface(
    TelescopeConfigurations=TelescopeConfigs,
    OutputConfigurations=OutputConfigs,
    MoonlightNoiseConfigurations=MoonlightConfigs,
    MultiprocessingConfigurations=MultiprocessingConfigs
)

---

Authors

Jake Staberg Morgan (Original author)

Chatdanai Sawangwong (Current maintainer)
email: [e-mail]

Supachai Awiphan
email: [e-mail]

Orarik Tasuya
email: [e-mail]

Napaporn A-thano
email: [e-mail]