Metadata-Version: 2.1
Name: preface-spearnet
Version: 2.0.0b4
Summary: An Automated Pipeline for the Selection of Transmission Spectroscopy Candidates
Author-email: Chatdanai Sawangwong <chatdanai.saw@gmail.com>, Supachai Awiphan <supachai@narit.or.th>, Orarik Tasuya <orarik@narit.or.th>, Napaporn A-thano <napaporn@narit.or.th>
License: MIT
Project-URL: Homepage, https://github.com/chatdanai-s/PREFACE
Project-URL: BugTracker, https://github.com/chatdanai-s/PREFACE/issues
Keywords: astronomy,exoplanets,transmission-spectroscopy,observation-planning,target-selection,astrophysics,pipeline
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.1.0
Requires-Dist: pandas>=2.2.3
Requires-Dist: matplotlib>=3.9.2
Requires-Dist: astropy>=7.1.0
Requires-Dist: scipy>=1.13.1
Requires-Dist: python-dateutil>=2.9.0
Requires-Dist: joblib>=1.4.2
Requires-Dist: tqdm>=4.67.0
Requires-Dist: ephem>=4.2.1
Requires-Dist: timezonefinder>=8.2.4
Requires-Dist: pyarrow>=24.0.0

# PREFACE

**P**rioritization and **R**anking of **E**xoplanets **F**or **A**stronomical **C**haracterization and **E**xploration (**PREFACE**) is a Python package for selection of promising exoplanet transmission spectroscopy observations based on their expected scientific return and observational feasibility.

---

## Installation

Install the latest stable release from PyPI:
```bash
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.readthedocs.io](https://preface.readthedocs.io)**.

### Example

```python
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, 1, 1)
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.90,
    toggle_graph_outputs=True,
    event_weight_graph_threshold=0.75
)

MoonlightConfigs = MoonlightNoiseConfigurations(
    toggle_moonlight_noise=True,
    scattering_aod=0.2,
    absorption_aod=0.3,
    asymmetry_factor=0.6,
    moonlight_amplification_factor=10
)

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: chatdanai.saw@gmail.com

**Supachai Awiphan**\
email: supachai@narit.or.th

**Orarik Tasuya**\
email: orarik@narit.or.th

**Napaporn A-thano**\
email: napaporn@narit.or.th

<!-- ---

## Citation

If you use **PREFACE** in academic work, please cite the associated publications:

```bibtex
@software{NameYear_PREFACE,
  author    = {Authors},
  title     = {Title},
  year      = {Year},
  publisher = {Publisher}
}
```

```bibtex
@phdthesis{Morgan2020_SPEARNET,
  author       = {Morgan, Jake S.},
  title        = {SPEARNET: A Pilot Exoplanet Transmission Spectroscopy Survey},
  school       = {The University of Manchester},
  year         = {2020},
  type         = {PhD thesis},
  date         = {2020-11-18},
  month        = nov,
  url          = {https://research.manchester.ac.uk/en/studentTheses/spearnet-a-pilot-exoplanet-transmission-spectroscopy-survey}
}
```

---

## To-do List
- [ ] (Maybe) Implement automatic exoplanets.eu API querying
- [ ] (Maybe) Reduce multiprocessing overhead
- [ ] (Maybe) Month- and location-dependent aerosol scattering parameters via end-to-end AERONET data retrieval

 -->
